record-locator
DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/record-locator package

1.0.5 • Public • Published

record-locator Build Status

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 locator 9Y2
  • The integer 3141592 encodes to the record locator 4ZVYR
  • The integer 355688197484 encodes to the record locator DEADBEEF

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 = require('record-locator');
var documentId = 3141592;
var documentReference = recordLocator.encode(documentId);
 
// console.log output: 4ZVYR
console.log(documentReference);

Decoding a record locator string back into an integer:

var recordLocator = require('record-locator');
var documentReference = '4ZVYR';
var documentId = recordLocator.decode(documentReference);
 
// console.log output: 3141592
console.log(documentId);

Error Handling

The record-locator module will throw an exception error under the following circumstances:

  • encode() or decode() is called with no argument
  • encode() or decode() is called with an empty value
  • encode() is called with a value that is not number
  • encode() 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 = require('record-locator');
var invalidDocumentId = -12345;
var documentReference;
 
try {
    documentReference = recordLocator.encode(invalidDocumentId);
} catch (e) {
    // console.log output: [Error: Argument is not a positive integer]
    console.log(e);
}
 

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:

Package Sidebar

Install

npm i record-locator

Weekly Downloads

190

Version

1.0.5

License

MIT

Last publish

Collaborators

  • dkhr