buffer-id v1.2.4

buffer-id

Install

npm install buffer-id

Create unique and reusable identifiers as buffers or arrays.

Example ids created by this module:

• [0,0,0] (as buffer <00 00 00>)
• [0,1] (as buffer <00 01>)
• [0,0,0,0,255] (as buffer <00 00 00 00 ff>)

Use

Create store and pass some options to it. For example idStore with options:

• idLength = 3
• indexRange = 256

will be able to create ids of length 3 where first id will be 0,0,0 and last 255,255,255. That gives 16777216 possible ids.

// Require module
const BufferId = require("buffer-id");

// Create idStore
const idStore = new BufferId({
  idLength: 3,
  indexRange: 256,
});

// Create id as array
const id = idStore.create(); // [0,0,0]

// Create another id
const id2 = idStore.create(); // [0,0,1]

// Remove id from idStore and release it
idStore.remove(id2);

// Create new id [0,0,1], since we released it in previous step
const id3 = idStore.create(); // [0,0,1]

Options

idLength - length of id

indexRange - specifies maximum values of each part of id

Note that starting value is always 0, so range 256 will allow values form 0 to 255. If ids are intended to use as buffer there is no point setting indexRange greater than 256.

For example if idLength is set to 3:

• indexRange = 256 will produce ids from [0,0,0] (<00 00 00> as buffer) to [255,255,255] (<ff ff ff> as buffer) (that gives 16777216 ids)
• indexRange = 10 will produce ids from [0,0,0] (<00 00 00> as buffer) to [9,9,9] (<09 09 09> as buffer) (that gives 1000 ids)

idFormat - default format of ids (can be array or buffer)

Methods

create

Creates new id. New id is either buffer or array (depends on store settings).

remove

Params:

Removes id from store, so it can be reused.

Implementation

Tree is used as internal structure of idStore. Animation shows creating and removing id when idLength is 3 and indexRange is 3. Identifiers are from range 0,0,0 to 2,2,2.

Use case

This module can be used to create buffer ids which we can be sent to some service alongside with buffer message.

Lets say we have two microservices A and B, which can communicate using strings and buffers. Sending file from A to B could look like that:

1. A to B: "I am about to send file named cat.jpg",
2. B to A: "Ok, send it with id 0,0,0,

Then on the side of A:

// we have cat.jpg in variable named cat
const id = Buffer.from([0, 0, 0]); // creates <Buffer 00 00 00>
const msg = Buffer.concat([id, cat]); // Ads id just before cat

3. A to B: <Buffer 00 00 00 ff d2 03 04 ... e5 06 0f 08>
4. B gets the message. Knowing that first 3 bytes is id it extracts cat from message and saves it as cat.jpg.

Test

AVA is used for testing. To run tests just type command:

npm run test