@gid128/core

GID-128 is a fast, time-sortable identifier system built for production use across Node and browser runtimes.

It gives you:

• 16-byte canonical binary storage for database indexing.
• 22-character gid_s text for URLs, logs, and APIs.
• 22-character gid_x public-token text for hiding timestamp and sort order.
• Rust-native Node runtime for production speed.

Why teams use it:

• Faster generation than common ID libraries in measured JS benchmarks.
• Node benchmark results on Apple M4 / darwin arm64:

| Library | Ops/sec | GID speed | | --- | ---: | ---: | | gid128/generate | 19.1M | 1.000x | | uuid/v4 | 10.0M | 1.907x slower | | nanoid | 8.7M | 2.202x slower | | xid-js | 4.8M | 3.987x slower | | uuid/v7 | 1.2M | 16.223x slower | | cuid | 492K | 38.792x slower | | ksuid | 266K | 71.614x slower | | ulid | 78K | 244.121x slower | | cuid2 | 9.9K | 1934.866x slower |

• Benchmarks compare against UUID v4, UUID v7, ULID, NanoID, KSUID, XID, and CUID-style generators where available.
• The benchmark gate is release-blocking and records the measured winners in the repo.
• Canonical binary storage for clean database indexing.
• Public tokens that do not expose timestamp order.
• One spec across JS and Python, with the same test vectors.

Install:

npm install @gid128/core

import {
  gid,
  parse,
  publicEncode,
  publicDecode,
  publicEncodeWithKeyId,
  publicDecodeWithKeyring,
  encodeTime,
  withPrefix
} from "@gid128/core";

const id = gid();
const text = id.toString();
const bytes = id.toBytes();
const timestamp = id.timestampMs();

const key = crypto.getRandomValues(new Uint8Array(32));
const publicId = publicEncode(id, key);
const original = publicDecode(publicId, key);
const keyedPublicId = publicEncodeWithKeyId(id, { kid: "k1", key });
const alsoOriginal = publicDecodeWithKeyring(keyedPublicId, { k1: key });
const timePrefix = encodeTime(id.timestampMs());
const orderId = withPrefix("order", id);

parse(text).equals(original);
parse(text).equals(alsoOriginal);

publicId is the canonical 22-character gid_x. keyedPublicId is a key-rotation wrapper for public distribution, not canonical gid_x.

Browser usage is ESM/bundler-compatible and requires globalThis.crypto.getRandomValues.

customAlphabet, customRandom, and nonSecure create display-only IDs. They do not replace canonical 22-character GID-128 text.

Use gid_s for database storage and internal identity. Use gid_x when public URLs or API output should hide timestamp and sort order. Use bytes when you need compact binary storage or indexed joins.

Recommended keywords for npm:

• gid
• gid128
• sortable-id
• identifier
• uuid
• ulid
• nanoid
• ksuid
• timestamp
• public-token
• crypto
• node
• browser
• benchmark
• performance
• uuidv7
• ulid

Local validation:

npm run validate