# mongoid-js

> very fast mongoid compatible unique string ids

Latest version **1.3.0** (published 2019-02-19) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install mongoid-js
pnpm add mongoid-js
yarn add mongoid-js
bun add mongoid-js
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.0 |
| Published | 2019-02-19 |
| First published | 2014-11-13 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.0.0 |
| Dependencies | 0 |
| Unpacked size | 22.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Andras |
| Maintainers | andrasq |
| Keywords | Andras, quick, fast, mongoid, globally, unique, ids |

## Links

- npm: https://www.npmjs.com/package/mongoid-js
- Repository: https://github.com/andrasq/node-mongoid-js
- Homepage: https://github.com/andrasq/node-mongoid-js#readme
- Issues: https://github.com/andrasq/node-mongoid-js/issues
- npm.io page: https://npm.io/package/mongoid-js

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 1.3.0 (latest) — 2019-02-19
- 1.1.3 — 2017-09-14
- 1.1.2 — 2017-05-06
- 1.1.0 — 2016-10-27
- 1.0.6 — 2015-07-20
- 1.0.5 — 2014-12-21
- 1.0.4 — 2014-12-21
- 1.0.3 — 2014-12-21
- 1.0.2 — 2014-11-14
- 1.0.1 — 2014-11-13
- 1.0.0 — 2014-11-13

## README

mongoid-js
==========
[![Build status](https://travis-ci.org/andrasq/node-mongoid-js.svg?branch=master)](https://travis-ci.org/andrasq/node-mongoid-js?branch=master)
[![Coverage Status](https://coveralls.io/repos/github/andrasq/node-mongoid-js/badge.svg?branch=master)](https://coveralls.io/github/andrasq/node-mongoid-js?branch=master)

very very fast MongoID compatible unique id generator

Generates unique id strings.  The ids are constructed like MongoDB document ids,
built out of a timestamp, system id, process id and sequence number.  Similar
to `BSON.ObjectID()`, but at 12 million ids / sec, 35 x faster.

The ids are guaranteed unique on any one server, and can be configured
to be unique across a cluster of up to 16 million (2^24) servers.
Uniqueness is guaranteed by unique {server, process} id pairs.

The ids returned by an id factory are always in strictly ascending order;
an id string will compare as `<` less than any id string generated after it.

The uniqueness guarantee requires that process ids be no more than 16 bits
(`kernel.pid_max` must be configured to 65535 or less on linux).

The 24-char id string is constructed by concatenating the big-endian hex values of
- 32 bit count of seconds elapsed since 1970-01-01 00:00:00 GMT
- 24 bit caller provided system id, else a 24-bit random value
- 16 bits of the process id (high bits above 16 are ignored)
- 24 bit monotonically increasing sequence number


## Summary

    var mongoid = require('mongoid-js');
    var id = mongoid();                 // => "543f376340e2816497000001"
    var id2 = mongoid();                // => "543f376340e2816497000002"

    var MongoId = require('mongoid-js').MongoId;
    var idFactory = new MongoId(/*systemId:*/ 0x123);
    var id = idFactory.fetch();         // => "543f3789001230649f000001"


## Functions

### mongoid( )

generates ids that are unique to this server.  The ids are generated by a
`new MongoId` singleton initialized with a random machine id.  All subsequent calls
to `mongoid()` in this process will fetch ids from this singleton.

    // ids with a randomly chosen system id (here 0x40e281)
    var mongoid = require('mongoid-js');
    var id1 = mongoid();                // => "543f376340e2816497000001"
    var id2 = mongoid();                // => "543f376340e2816497000002"

### new MongoId( [systemId] )

Create an id factory that embeds the given system id in each generated unique id.
By a systematic assignment of system ids to servers, this approach can guarantee
globally unique ids (ie, globally for an installation).

The systemId must be an integer between 0 and 16777215 (0xFFFFFF), inclusive.
If no system id is specified, a random 24-bit integer is used.

    // ids with a unique system id (here 0xbaabaa)
    var MongoId = require('mongoid-js').MongoId;
    var systemId = 0xBaaBaa;
    var idFactory = new MongoId(systemId);
    idFactory.fetch();                  // => "59cd11d3baabaa05ce000001"

## Instance Methods

MongoId objects can act as id factories.  Each factory can also assign itself an id.
Id factories should all have unique system ids, else they may not generate unique ids.

    var MongoId = require('mongoid-js').MongoId;
    var systemId = 0x123456;
    var ids = new MongoId(systemId);

#### ids.fetch( )

generate and return the next id in the sequence.  Up to 16 million distinct
ids (16777216) can be fetched during the same wallclock second; trying to
fetch more blocks until the next second.  The second starts when the clock reads _*000_
milliseconds, not when the first id is fetched.  The second ends 1000
milliseconds after the start, when the clock next reads _*000_ milliseconds.

    var ids = new MongoId(0x001230);
    var id1 = ids.fetch();              // => "543f3789001230649f000001"
    var id2 = ids.fetch();              // => "543f3789001230649f000002"
    var id3 = ids.fetchShort();         // => "K2wrXF-HB5HU---2"
    var id4 = ids.fetch();              // => "543f3789001230649f000004"

#### ids.fetchShort( )

return the next id in the sequence, encoded to be more compact.  The id itself is the same as
returned by `fetch()`, but expressed as a shorter string.  Shortids can be converted to and
from ordinary hexids; see `shorten` and `unshorten` below.  Note that the `parse` and related
functions operate on hexids.

#### ids.parse( [idString] )

With no `idString`, parse the factory's (id object's) built-in id.  If the factory does not
yet have an id string, assign one.  Same as `MongoId.parse(id.toString())`, see below.  If
`idString` is provided, parse it just like `MongoId.parse`.

#### ids.getTimestamp( )

Get the timestamp of the id factory itself.  Assign a new id string to the factory if it
does not yet have one.  Same as `MongoId.getTimestamp(id.getTimestamp())`, see below.

#### ids.toString( )

Return the factory id string.  If the factory does not yet have an id string,
assign one.  The assigned id is reused the next time it a factory id is needed.

    var ids = new MongoId();
    var id1 = ids.fetch();              // => "59cd101bd5057e7ec1000001"
    ids.toString();                     // => "59cd101bd5057e7ec1000002"


## Class Methods

### MongoId.parse( idString )

Decompose the id string into its parts -- unix timestamp, machine id,
process id and sequence number.  Unix timestamps are seconds since the
start of the epoch (1970-01-01 GMT).  Note that `parse()` returns seconds,
while `getTimestamp()` returns milliseconds.

    var parts = MongoId.parse("543f376340e2816497000013");
    // => { timestamp: 1413429091,      // 0x543f3763
    //      machineid: 4252289,         // 0x40e281
    //      pid: 25751,                 // 0x6497
    //      sequence: 19 }              // 0x000013

### MongoId.getTimestamp( idString )

Return just the javascript timestamp part of the id.  Javascript timestamps
are milliseconds since the start of the epoch.  Each mongoid embeds a seconds
precision unix timestamp; getTimestamp() returns that multiplied by 1000.

    MongoId.getTimestamp("543f376340e2816497000013");
    // => 1413429091000

### MongoId.shorten( idString )

Convert the hexadecimal mongoid to a more compact string.  The conversion is lossless.
The converted strings sort into the same respective alpha order as in hexadecimal form, and
are safe to use in URLs.

### MongoId.unshorten( shortIdString )

Convert the shortened mongoid string back to its hexadecimal form.

    MongoId.shorten("543f376340e2816497000013");
    // => "K2wrNo2XVLHM---I"

    MongoId.unshorten("K2wrNo2XVLHM---I");
    // => "543f376340e2816497000013"

### MongoId.setShortCharset( charset )

Redefine the shortid character set.  `charset` is expected to be a string of 64 7-bit ASCII characters.
The default character set is `-`, `0-9`, `A-Z`, `_`, and `a-z`, in that order (ASCII order).
The character set `'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'` would
produce base64 shortids (which wouldn't sort into timestamp and sequence order, but would be
base64).  Note that this changes the shortid charset globally, for all MongoId instances.


## Change Log

- 1.3.0 - new method `fetchShort()`, optional hexid to id.parse(), 25% faster fetch()
- 1.2.0 - new static methods `shorten` and `unshorten`, block until next second if out of ids (do not throw)
- 1.1.3 - only include the low 16 bits of the process id to not overflow 24 chars,
  change unit tests to work on systems with longer than 16 bit process ids
- 1.1.2 - put under travis ci tests, add coverage,  move `qnit` dev dependency into .travis.yml
- 1.1.1 - fix test with qnit, fix unit test pid < 0x1000, add .travis.yml
- 1.1.0 - tentative `browserify` support: use a random pid if process.pid is not set, avoid object methods in constructor, 100% unit test coverage
- 1.0.7 - fix getTimestamp and quantize correctly, deprecate index.js, test with qnit, fix sequence wrapping
- 1.0.6 - doc edits
- 1.0.5 - stable, fast version

---
_Source: https://npm.io/package/mongoid-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._