Utility Package
The utility package provides classes to manipulate integers and strings, independently of any AIDC problem domain. The package has been designed to maximize performance and minimize memory by reducing many of the typical AIDC requirements, such as serial number generation, to on-demand generation using the JavaScript Iterable and IterableIterator types.
To provide the most flexibility and to handle the most significant demands of the AIDC problem domain, the AIDC Toolkit uses the JavaScript bigint type, with many functions converting from the lower-range number type if provided. This gives applications significant flexibility at a small performance cost inherent in bigint operations.
Integers
Sequence
Many of AIDC processes can be reduced to a simple statement about sequences:
"Give me a million serial numbers for manufacturing."
"Generate a handful of GTINs for my new product line."
"Label the containers in the shipping area with SSCCs."
Each statement has a quantity and an output. Implicit in them, however, is the requirement that the generated output be unique, not only within itself, but also within any previous outputs generated. A sequence is simply a utility to generate a sequence of integers given a start value and a count.
Creating and using a sequence
Create a sequence with a start value and a count. The count is typically positive, which means that the sequence runs from the start value up. If negative, the sequence runs from the start value down.
// Sequence starts at 33,000 and will iterate 1,000 times. const sequence = new Sequence(33000, 1000);Use the sequence.
Use it in a
forloop.for (const value of sequence) { console.log(value); }Transform it using an
Iteratorhelper method.const sum = Iterator.from(sequence).reduce((accumulator, value) => accumulator + value, 0);Pass it to a function.
// Generate sequence of 10-character hexadecimal strings. const stringSequence = HEXADECIMAL_STRING_CREATOR.create(10, sequence);
Transformer
A transformer transforms values in a numeric domain to values in a range equal to the domain or to another range defined by a callback function.
There are two types of transformers defined in the AIDC Toolkit: the identity transformer and the encryption transformer. Regardless of the type, before any input value is transformed, it is validated against the domain provided when constructing the transformer; if the input value is less than zero or greater than or equal to the domain, an error is thrown.
The identity transformer simply maps any input value to the same output value.
The encryption transformer maps an input value to an output value resulting from repeated shuffle and xor operations defined by a tweak. In cryptography, a tweak is a value that alters an operation to change or "tweak" the output in a predictable and unique way that is hard to reverse engineer. Normally, a tweak works side by side with a password to generate a cryptographic key to ensure that no two systems can produce the same output from the same input and password; each system defines its own tweak and the password is kept by the user. Because the tweak is applied to every encryption operation, it is inherently less secure (e.g., a system administrator may know the tweak but that's not enough to compromise any user's encryption), but for the purposes of the AIDC Toolkit, it is secure enough.
Suppose that you're manufacturing a product that is valuable enough to be of interest to counterfeiters. To protect the product, you want to generate a unique serial number for each one you put on the market. If anyone submits a warranty claim, the serial number will tell you whether the product is legitimate.
You expect that you will manufacture at most 1,000,000 units of the product before releasing an upgrade, so your serial numbers are going to be numeric only and 6 digits long. If you generate the serial numbers in sequence, then generating 10 of them starting from unit 200,000 results in the following: 200000, 200001, 200002, 200003, 200004, 200005, 200006, 200007, 200008, 200009.
The sequence is predictable and a counterfeiter can easily guess at valid serial numbers, which will cause problems for distributors and retailers when they see duplicates in the supply chain, problems for your customers who believe they are buying a legitimate product, and problems for you when you can't easily distinguish legitimate from counterfeit.
The first thing you need to do is put some space between your serial numbers, to make guessing difficult. Let's say that in this case you make serial numbers 8 digits long, which means you have 100 times the capacity of serial numbers as of your expected manufacturing run. Next, you use the encryption transformer, with the the tweak set to some random value (which you have to save and reuse to ensure that you don't generate any duplicates). Generating 10 serial numbers starting from unit 200,000 results in the following: 14608575, 00118914, 14609085, 00250498, 07625339, 85755635, 41179259, 67532896, 02000912, 19087354.
The sequence is statistically random and a counterfeiter is highly unlikely to guess at valid serial numbers, which will make detection of illegitimate serial numbers significantly easier for all parties.
Sequence and Transformer
The Transformer class underlies most AIDC Toolkit operations involved in string creation. The forward() method takes either a single bigint value or an Iterable<bigint> of values. This provides maximum flexibility, but it comes at a cost. All inputs are validated prior to transformation, which can add to the system load when transforming a large number of values.
When dealing with Iterable objects, transformers will recognize Sequence objects and validate the start value and count at the beginning rather than each value individually as they are transformed. This reduces the number of validations from however many entries there are in an Iterable object to two. It also ensures that the client code deals with errors at the very beginning rather than in the middle of its processing.
Strings
String validation
Validation is a requirement for any application. The AIDC Toolkit provides a simple but extensible validation framework built on two interfaces: StringValidation and StringValidator. The two are related in that an interface extending StringValidation may be passed as a parameter to the validate() method of a class implementing StringValidator to restrict validation further. For example, the CharacterSetValidator implementation accepts a CharacterSetValidation object that can constrain the length and limit the way numeric values are expressed (e.g., exclude zero as the first character or exclude strings that are all numeric).
The StringValidation interface is a placeholder only; it's empty, which, in a structurally typed language like TypeScript, matches any object, so it's up to StringValidator implementations to decide what the implementation type should be.
Validation is straightforward: if a string passed to a validate() method is valid, the method returns; if not, a RangeError is thrown.
Predefined validators
The following validator types are predefined:
Type | Description |
|---|---|
Regular expression | Validates a string against a regular expression. |
Record | Validates a string by looking it up in a |
Character set | Validates a string by ensuring that each character is within a defined character set, with additional validation parameters optionally constraining the length and limiting the way numeric values are expressed. Predefined character set validators are:
|
String creation
String creation varies depending on the type of string being created, so there's no single interface that can be implemented. There is a pattern, however:
Creation is done via a
create()method. If the class can create more than one type of string, it can define additionalcreateNNN()methods as appropriate.The
create()(orcreateNNN()) method is overloaded, with a parameter accepting either a single value to create a single string or multiple values to create multiple strings.If the value to create a string is numeric (
numberorbigint):The method uses a transformer and supports sparse creation.
Because of this, passing in a sequence is strongly recommended when creating multiple strings.
Predefined creators
The following creator types are predefined:
Type | Description |
|---|---|
Character set | Creates strings by mapping numeric (
|
Output restriction
As with string validators, string creators can restrict their output to meet the needs of certain use cases. For example, when creating serial numbers, it may be necessary to generate values that either don't start with a zero (to prevent leading zeros from being dropped by other applications) or that aren't composed entirely of digits (to prevent strings from being interpreted as numbers).