binary-uuid

library2.0.3jsnpmunverified

Converts UUID v1 strings to BINARY(16) buffers with time-ordering scrambling optimized for MySQL indexing. Version 2.0.3 is current, stable, and rarely updated. Key differentiator: reorders UUID v1 bytes so that the timestamp component (which changes fastest) is placed in the middle of the binary representation, improving B-tree index performance. Supports both ESM imports and CommonJS require. Includes helpers to convert between string UUID and Buffer representations.

database

npm install binary-uuid

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BINARY-UUID

binary-uuid

databasejavascriptv2.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import createBinaryUUID from 'binary-uuid'

✗ const createBinaryUUID = require('binary-uuid') (returns module object, not function)

Default export is a function. In CJS, use require('binary-uuid').default.

fromBinaryUUID

✓ import { fromBinaryUUID } from 'binary-uuid'

✗ import fromBinaryUUID from 'binary-uuid' (named export, not default)

Named export for converting Buffer back to UUID string.

toBinaryUUID

✓ import { toBinaryUUID } from 'binary-uuid'

✗ import toBinaryUUID from 'binary-uuid'

Named export for converting a UUID string to Buffer.

createBinaryUUID

✓ const { createBinaryUUID } = require('binary-uuid')

✗ const createBinaryUUID = require('binary-uuid')

In CJS, createBinaryUUID is a named export from the module.

Demonstrates generating a binary UUID, round-tripping buffer to string, and converting an existing UUID string to buffer.

import createBinaryUUID, { toBinaryUUID, fromBinaryUUID } from 'binary-uuid'; // Generate a binary UUID (uses uuid v1 internally) const { uuid, buffer } = createBinaryUUID(); console.log(uuid); // e.g. '8a529060-04b1-11e9-9b52-31bbfe39da0e' console.log(buffer); // <Buffer 11 e9 04 b1 ...> // Convert Buffer back to string const uuidStr = fromBinaryUUID(buffer); console.log(uuidStr === uuid); // true // Convert existing UUID v1 string to buffer const buf = toBinaryUUID('550e8400-e29b-11d4-a716-446655440000'); console.log(buf); // <Buffer 11 d4 e2 9b 55 0e 84 00 ...>

Debug

Known issues

breakingRequires uuid package as peer dependency; must install uuid separately for v1 generation.

fix

Run 'npm install uuid' alongside binary-uuid.

affects: >=2.0.0

deprecatedDefault export is a function, not an object. CJS users must use .default.

fix

Use const createBinaryUUID = require('binary-uuid').default;

affects: >=2.0.0

gotchaOnly works correctly with UUID v1; using v4 will not scramble bytes properly and may degrade index performance.

fix

Always use UUID v1 with this package for binary storage.

affects: all

gotchaThe toBinaryUUID function expects a standard UUID v1 string; passing hyphenless or raw hex will produce incorrect buffers.

fix

Ensure input matches 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' format.

affects: all

Errors

Common errors & fixes

TypeError: createBinaryUUID is not a function

Using CJS require without accessing .default

fix

const createBinaryUUID = require('binary-uuid').default;

Cannot find module 'uuid'

uuid peer dependency not installed

fix

npm install uuid

fromBinaryUUID is not a function

Importing default instead of named export

fix

import { fromBinaryUUID } from 'binary-uuid';

Upgrade

Version history

2.0.3latest on npm

Audit

Dependencies

uuidoptionalPeer dependency for generating UUID v1 strings; must be installed separately

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/odo-network/binary-uuid ↗

packagebinary-uuid ↗

homepagehttps://github.com/odo-network/binary-uuid#readme ↗