record-locator
A Node.js module that encodes integers into a short, easy to read and pronounceable string.
What is a 'Record Locator'?
A record locator is an alphanumeric string that represents an integer.
A record locator can be used to provide a human-readable representation of a database primary key, providing users with a short, easy-to-read and pronounceable string. Record locators can be useful when you need to generate a document reference, confirmation number, reservation number or a booking reference to share with your users.
DKHR uses record locators to provide Taxfox customers with an easy way to reference PDF documents associated to them.
Examples
- The integer
8128
encodes to the record locator9Y2
- The integer
3141592
encodes to the record locator4ZVYR
- The integer
355688197484
encodes to the record locatorDEADBEEF
You can encode more than 33.5 million integers in a five-character record locator: the largest five-character record locator, ZZZZZ
, represents the integer 33554431
.
For more information, see Wikipedia's record locator article.
Installation
Use Node.js's default package manager (npm) to install the record-locator module into your project:
npm install --save record-locator
Usage
Encoding an integer into a record locator string:
var recordLocator = ;var documentId = 3141592;var documentReference = recordLocator; // console.log output: 4ZVYRconsole;
Decoding a record locator string back into an integer:
var recordLocator = ;var documentReference = '4ZVYR';var documentId = recordLocator; // console.log output: 3141592console;
Error Handling
The record-locator module will throw an exception error under the following circumstances:
encode()
ordecode()
is called with no argumentencode()
ordecode()
is called with an empty valueencode()
is called with a value that is not numberencode()
is called with a value that is not a positive integer
You can use a standard try/catch
block to handle these error scenarios:
var recordLocator = ;var invalidDocumentId = -12345;var documentReference; try documentReference = recordLocator; catch e // console.log output: [Error: Argument is not a positive integer] console;
For more information on error handling, see Joyent's reference: Error Handling in Node.js
Character Canonicalization
Certain characters, such as the letters "B" and "S", as well as the numbers 0 (zero) and 1 (one), are not used in record locators as there is the potential for confusion with other characters.
These specific characters are automatically replaced by encode()
and decode()
as follows:
Character | Replacement Letter |
---|---|
B | P |
S | F |
0 | O |
1 | I |
Related Libraries
The following third-party libraries provide alternative implementations that can also be used to encode and decode record locators:
- Jesse Vincent's Perl module: Number::RecordLocator
- Oliver Jakoubek's PHP library: php-recordlocator