shepherdwind / bson-objectid

Construct ObjectIDs without the mongodb driver or bson module

BSON ObjectID  

This mdoule allows you to create and parse ObjectIDs without a reference to the mongodb or bson modules.

The goal is to be 100% compatable with all bson's public API implementation (found here: https://github.com/mongodb/js-bson/blob/master/lib/bson/objectid.js).

Install

$ npm install bson-objectid

Usage

var ObjectID = require("bson-objectid");

console.log(ObjectID());
console.log(ObjectID("54495ad94c934721ede76d90"));
console.log(ObjectID(1414093117));//time
console.log(ObjectID([ 84, 73, 90, 217, 76, 147, 71, 33, 237, 231, 109, 144 ]));
console.log(ObjectID(new Buffer([ 84, 73, 90, 217, 76, 147, 71, 33, 237, 231, 109, 144 ])));

ObjectID()
ObjectID(time)
ObjectID(hexString)
ObjectID(idString)
ObjectID(array)
ObjectID(buffer)

Creates a new immutable ObjectID instance based on the current system time.

Possible arguments:
time Constructs the instance based on the specified time (in seconds).
hexString Constructs the instance from a 24 character hex string.
idString Constructs the instance from a 12 byte string.
array Constructs the instance from an Array of 24 bytes.
buffer Constructs the instance from a 24 byte Buffer instance.

#id

returns the 12 byte id string.

#str

#toHexString()

returns the ObjectID represented as a 24 character hex string.

#equals(other)

returns true if the ObjectIDs represent the same underlying value. Otherwise false.

#getTimestamp()

returns the generation Date (accurate up to the second) that this ObjectID was generated.

ObjectID.createFromTime(time)

Creates an ObjectID from a time (in seconds) Number, with the rest of the ObjectID zeroed out. Used for comparisons or sorting the ObjectID.

ObjectID.createFromHexString(hexString)

Creates an ObjectID from a 24 character hex string.

ObjectID.isValid(hexString)
ObjectID.isValid(ObjectID)

Checks if a value is a valid ObjectID or 24 character hex string.

THE NATIVE DOCUMENTATION ISN'T CLEAR ON THIS GUY!
See: http://mongodb.github.io/node-mongodb-native/api-bson-generated/objectid.html#objectid-isvalid

ObjectID.generate()
ObjectID.generate(time)

You can use this to generate a 24 character hex string without instantiating a ObjectID instance.

This diverges from bson's implementation which returns the 12 byte string.

returns a valid 24 character ObjectID hex string.

ObjectID.setMachineID(number)
ObjectID.setMachineID(string)

You can use this to set a custom machine-id. It should be a 6 character hex string or a 3 byte integer and will truncate all larger values.

ObjectID.getMachineID()

returns the machine-id as a 3 byte int.

Test

mocha

or

npm test

License

Apache v2.0

See LICENSE file.

Special callout to @feross for the is-buffer code used internally to avoid Buffer from being loaded in browserify environments.