uniku 0.3.2 → 0.4.0

package/README.md

@@ -35,6 +35,7 @@ console.log(first < second && second < third) // true
 | KSUID              |   ✅  |  ❌  |     ❌    |   ❌   |  ❌  |   ❌  |   ✅  |   ❌  |   ❌  |
 | ObjectID           |   ✅  |  ❌  |     ❌    |   ❌   |  ❌  |   ❌  |   ❌  |   ✅  |   ❌  |
 | TSID               |   ✅  |  ❌  |     ❌    |   ❌   |  ❌  |   ❌  |   ❌  |   ❌  |   ✅  |
+| XID                |   ✅  |  ❌  |     ❌    |   ❌   |  ❌  |   ❌  |   ❌  |   ❌  |   ❌  |
 | Tree-shakeable     |   ✅  |  ✅  |     ✅    |   ✅   |  ✅  |   ✅  |   ❌  |   ❌  |   ❌  |
 | ESM-only           |   ✅  | ✅¹  |     ❌    |   ✅   |  ❌  |   ✅  |   ❌  |   ❌  |   ❌  |
 | Edge/Workers       |   ✅  |  ✅  |     ✅    |   ✅   |  ⚠️  |   ✅  |  ⚠️  |  ⚠️  |  ⚠️  |
@@ -67,6 +68,7 @@ Uses `globalThis.crypto` (Web Crypto API) — no Node.js-specific APIs.
 | KSUID     | **1.5× faster** |
 | ObjectID  | **1.1× faster** |
 | TSID      | **1.7× faster** |
+| XID | See the current benchmark summary |
 | UUID v7   | **1.1× faster**  |
 | Nanoid    | **~comparable speed** |
 | Nanoid (10 chars) | npm is 1.1× faster |
@@ -88,6 +90,7 @@ Uses `globalThis.crypto` (Web Crypto API) — no Node.js-specific APIs.
 | Very high-volume distributed systems | **KSUID** | Time-ordered with 128-bit entropy |
 | MongoDB `_id` compatibility | **ObjectID** | Drop-in match for MongoDB's native document ID format |
 | Native 64-bit sortable integer ID | **TSID** | Fits a database `BIGINT` primary key, no UUID-sized overhead |
+| Go rs/xid compatibility | **XID** | Compact, time-ordered 12-byte identifier |
 
 ### Detailed Guide
 
@@ -222,6 +225,7 @@ deno install npm:uniku
 | `uniku/ksuid` | ~1.3 KB |
 | `uniku/objectid` | ~1.3 KB |
 | `uniku/tsid` | ~1.4 KB |
+| `uniku/xid` | ~1.7 KB |
 | `uniku/generators` | ~98 B |
 
 * The CUID2 entry point imports SHA3-512 from `@noble/hashes`; this table's entry-point size excludes that external dependency.
@@ -375,6 +379,21 @@ const bytes = tsid.toBytes(id)
 const restored = tsid.fromBytes(bytes)
 ```
 
+### XID (time-ordered, rs/xid-compatible)
+
+```ts
+import { xid } from 'uniku/xid'
+
+const id = xid()
+// => "9m4e2mr0ui3e8a215n4g"
+
+const bytes = xid.toBytes(id)
+const restored = xid.fromBytes(bytes)
+const timestamp = xid.timestamp(id)
+```
+
+XID caches a random identity per runtime and uses a shared, always-incrementing counter. Supply `machineId`, `processId`, `secs`, and `counter` for deterministic output.
+
 ## Migrating to uniku
 
 ### From `uuid`
@@ -553,6 +572,19 @@ tsid.MAX  // 18446744073709551615n
 
 > Unlike every other generator listed here, `tsid()` returns `bigint` by default, and `toBytes`/`fromBytes`/`timestamp`/`isValid` all operate on that `bigint`. `toString`/`fromString` are the boundary conversions to/from the 13-character canonical Crockford Base32 string.
 
+### `xid` (from `uniku/xid`)
+
+```ts
+xid(options?: XidOptions): string
+xid(options: XidOptions | undefined, buf: Uint8Array, offset?: number): Uint8Array
+xid.toBytes(id: string): Uint8Array
+xid.fromBytes(bytes: Uint8Array): string
+xid.timestamp(id: string): number
+xid.isValid(id: unknown): id is string
+xid.NIL  // "00000000000000000000"
+xid.MAX  // "vvvvvvvvvvvvvvvvvvvg"
+```
+
 ## Documentation
 
 For advanced usage, examples, and contributing guidelines, see the [full documentation on GitHub](https://github.com/jkomyno/uniku).

package/build/generators.d.mts

@@ -7,7 +7,7 @@
 * `@uniku/cli`'s `--type` flag) should derive from this array rather than
 * hand-copying the union.
 */
-declare const ID_GENERATORS: readonly ["uuid", "ulid", "typeid", "nanoid", "cuid", "ksuid", "objectid", "tsid"];
+declare const ID_GENERATORS: readonly ["uuid", "ulid", "typeid", "nanoid", "cuid", "ksuid", "objectid", "tsid", "xid"];
 /**
 * The union of ID generators supported by uniku, derived from {@link ID_GENERATORS}.
 */

package/build/generators.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"generators.d.mts","names":[],"sources":["../src/generators.ts"],"mappings":";;AAWA;;;;AAA+F;AAK/F;;cALa,aAAA;;AAKqB;;KAAtB,WAAA,WAAsB,aAAA"}
+{"version":3,"file":"generators.d.mts","names":[],"sources":["../src/generators.ts"],"mappings":";;AAWA;;;;AAAuG;AAKvG;;cALa,aAAA;;AAKqB;;KAAtB,WAAA,WAAsB,aAAA"}

package/build/generators.mjs

@@ -1,2 +1,2 @@
-const e=[`uuid`,`ulid`,`typeid`,`nanoid`,`cuid`,`ksuid`,`objectid`,`tsid`];export{e as ID_GENERATORS};
+const e=[`uuid`,`ulid`,`typeid`,`nanoid`,`cuid`,`ksuid`,`objectid`,`tsid`,`xid`];export{e as ID_GENERATORS};
 //# sourceMappingURL=generators.mjs.map

package/build/generators.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"generators.mjs","names":[],"sources":["../src/generators.ts"],"sourcesContent":["/**\n * The canonical, ordered list of ID generators supported by uniku.\n *\n * This is the single source of truth for the set of supported ID generators.\n * Tools that need to enumerate or validate ID generators (for example,\n * `@uniku/cli`'s `--type` flag) should derive from this array rather than\n * hand-copying the union.\n */\n// Plain `as const` (not `as const satisfies readonly string[]`): the `satisfies`\n// wrapper defeats isolatedDeclarations' trivial declaration emit for this export.\n// All members are string literals, so the shape guard adds nothing here anyway.\nexport const ID_GENERATORS = ['uuid', 'ulid', 'typeid', 'nanoid', 'cuid', 'ksuid', 'objectid', 'tsid'] as const\n\n/**\n * The union of ID generators supported by uniku, derived from {@link ID_GENERATORS}.\n */\nexport type IdGenerator = (typeof ID_GENERATORS)[number]\n"],"mappings":"AAWA,MAAa,EAAgB,CAAC,OAAQ,OAAQ,SAAU,SAAU,OAAQ,QAAS,WAAY,MAAM"}
+{"version":3,"file":"generators.mjs","names":[],"sources":["../src/generators.ts"],"sourcesContent":["/**\n * The canonical, ordered list of ID generators supported by uniku.\n *\n * This is the single source of truth for the set of supported ID generators.\n * Tools that need to enumerate or validate ID generators (for example,\n * `@uniku/cli`'s `--type` flag) should derive from this array rather than\n * hand-copying the union.\n */\n// Plain `as const` (not `as const satisfies readonly string[]`): the `satisfies`\n// wrapper defeats isolatedDeclarations' trivial declaration emit for this export.\n// All members are string literals, so the shape guard adds nothing here anyway.\nexport const ID_GENERATORS = ['uuid', 'ulid', 'typeid', 'nanoid', 'cuid', 'ksuid', 'objectid', 'tsid', 'xid'] as const\n\n/**\n * The union of ID generators supported by uniku, derived from {@link ID_GENERATORS}.\n */\nexport type IdGenerator = (typeof ID_GENERATORS)[number]\n"],"mappings":"AAWA,MAAa,EAAgB,CAAC,OAAQ,OAAQ,SAAU,SAAU,OAAQ,QAAS,WAAY,OAAQ,KAAK"}

package/build/xid/xid.d.mts

@@ -0,0 +1,31 @@
+import { i as UniqueIdError, n as InvalidInputError, r as ParseError, t as BufferError } from "../errors-Dgoyi-ci.mjs";
+
+//#region src/xid/xid.d.ts
+type XidOptions = {
+  /** First three bytes used as the XID machine identity. */machineId?: Uint8Array; /** 16-bit process identity. */
+  processId?: number; /** Unix timestamp in seconds. Defaults to the current second. */
+  secs?: number; /** 24-bit counter. Explicit values do not consume shared state. */
+  counter?: number;
+};
+type Xid = {
+  (): string;
+  <TBuf extends Uint8Array = Uint8Array>(options: XidOptions | undefined, buf: TBuf, offset?: number): TBuf;
+  (options?: XidOptions, buf?: undefined, offset?: number): string;
+  toBytes(id: string): Uint8Array;
+  fromBytes(bytes: Uint8Array): string;
+  timestamp(id: string): number;
+  isValid(id: unknown): id is string;
+  NIL: string;
+  MAX: string;
+};
+/**
+* Generate a 20-character rs/xid-compatible identifier.
+*
+* XID embeds seconds, a lazily-random per-runtime identity, and a shared
+* always-incrementing counter. In Cloudflare Workers, time is frozen during a
+* request, so the counter preserves ordering for IDs made in that request.
+*/
+declare const xid: Xid;
+//#endregion
+export { BufferError, InvalidInputError, ParseError, UniqueIdError, Xid, XidOptions, xid };
+//# sourceMappingURL=xid.d.mts.map

package/build/xid/xid.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xid.d.mts","names":[],"sources":["../../src/xid/xid.ts"],"mappings":";;;KAaY,UAAA;4DAEV,SAAA,GAAY,UAAA,EAFd;EAIE,SAAA;EAEA,IAAA;EAEA,OAAA;AAAA;AAAA,KAGU,GAAA;EAAA;EAAA,cAEI,UAAA,GAAa,UAAA,EAAY,OAAA,EAAS,UAAA,cAAwB,GAAA,EAAK,IAAA,EAAM,MAAA,YAAkB,IAAA;EAAA,CACpG,OAAA,GAAU,UAAA,EAAY,GAAA,cAAiB,MAAA;EACxC,OAAA,CAAQ,EAAA,WAAa,UAAA;EACrB,SAAA,CAAU,KAAA,EAAO,UAAA;EACjB,SAAA,CAAU,EAAA;EACV,OAAA,CAAQ,EAAA,YAAc,EAAA;EACtB,GAAA;EACA,GAAA;AAAA;;;;;;;;cAmHW,GAAA,EAAK,GAAA"}

package/build/xid/xid.mjs

@@ -0,0 +1,2 @@
+import{n as e,t}from"../random-Chp-Nkzi.mjs";import{n,t as r}from"../validation-CTNpXm94.mjs";import{BufferError as i,InvalidInputError as a,ParseError as o,UniqueIdError as s}from"../errors.mjs";import{n as c}from"../bytes-xqWxFYsM.mjs";const l=`0123456789abcdefghijklmnopqrstuv`,u=new Uint8Array(65536);u.fill(255);for(let e=0;e<32;e+=1)u[l.charCodeAt(e)]=e;function d(e){if(e.length!==12)throw new i(`XID_BYTES_INVALID_LENGTH`,`XID bytes must be exactly 12 bytes, got ${e.length}`);return l[e[0]>>3]+l[(e[0]<<2|e[1]>>6)&31]+l[e[1]>>1&31]+l[(e[1]<<4|e[2]>>4)&31]+l[(e[2]<<1|e[3]>>7)&31]+l[e[3]>>2&31]+l[(e[3]<<3|e[4]>>5)&31]+l[e[4]&31]+l[e[5]>>3]+l[(e[5]<<2|e[6]>>6)&31]+l[e[6]>>1&31]+l[(e[6]<<4|e[7]>>4)&31]+l[(e[7]<<1|e[8]>>7)&31]+l[e[8]>>2&31]+l[(e[8]<<3|e[9]>>5)&31]+l[e[9]&31]+l[e[10]>>3]+l[(e[10]<<2|e[11]>>6)&31]+l[e[11]>>1&31]+l[e[11]<<4&31]}function f(e){if(e.length!==20)throw new o(`XID_INVALID_LENGTH`,`XID string must be 20 characters, got ${e.length}`);let t=new Uint8Array(20);for(let n=0;n<20;n+=1){let r=u[e.charCodeAt(n)];if(r===255)throw new o(`XID_INVALID_CHAR`,`Invalid XID character: ${e[n]}`);t[n]=r}if(t[19]!==0&&t[19]!==16)throw new o(`XID_NON_CANONICAL`,`XID trailing bits must be canonically encoded`);return new Uint8Array([t[0]<<3|t[1]>>2,t[1]<<6|t[2]<<1|t[3]>>4,t[3]<<4|t[4]>>1,t[4]<<7|t[5]<<2|t[6]>>3,t[6]<<5|t[7],t[8]<<3|t[9]>>2,t[9]<<6|t[10]<<1|t[11]>>4,t[11]<<4|t[12]>>1,t[12]<<7|t[13]<<2|t[14]>>3,t[14]<<5|t[15],t[16]<<3|t[17]>>2,t[17]<<6|t[18]<<1|t[19]>>4])}const p=4294967295,m=65535,h=16777215,g=/^[0-9a-v]{19}[0g]$/,_={machineId:void 0,processId:void 0,counter:void 0};function v(e){return t(e).slice()}function y(){_.machineId===void 0&&(_.machineId=v(3)),_.processId===void 0&&(_.processId=e()&m)}function b(){return _.counter===void 0&&(_.counter=e()&h),_.counter=_.counter+1&h,_.counter}function x(e,t,n,r,i,a){c(i,a,e),i.set(t.subarray(0,3),a+4),i[a+7]=n>>>8,i[a+8]=n&255,i[a+9]=r>>>16,i[a+10]=r>>>8&255,i[a+11]=r&255}function S(e){if(e.machineId!==void 0&&e.machineId.length<3)throw new a(`XID_MACHINE_ID_BYTES_TOO_SHORT`,`Machine ID bytes length must be >= 3 for XID`);if(e.processId!==void 0&&!r(e.processId,0,m))throw new a(`XID_PROCESS_ID_OUT_OF_RANGE`,`Process ID must be between 0 and ${m}`);if(e.secs!==void 0&&!r(e.secs,0,p))throw new a(`XID_TIMESTAMP_OUT_OF_RANGE`,`Timestamp must be between 0 and ${p}`);if(e.counter!==void 0&&!r(e.counter,0,h))throw new a(`XID_COUNTER_OUT_OF_RANGE`,`Counter must be between 0 and ${h}`)}function C(e,t,r=0){e!==void 0&&S(e);let a=e?.secs??Math.floor(Date.now()/1e3);(e?.machineId===void 0||e.processId===void 0)&&y();let o=e?.machineId??_.machineId,s=e?.processId??_.processId,c=e?.counter??b();if(t!==void 0){if(!n(t,r,12))throw new i(`XID_BUFFER_OUT_OF_BOUNDS`,`XID byte range ${r}:${r+11} is out of buffer bounds`);return x(a,o,s,c,t,r),t}let l=new Uint8Array(12);return x(a,o,s,c,l,0),d(l)}function w(e){return f(e)}function T(e){return d(e)}function E(e){let t=f(e);return((t[0]<<24|t[1]<<16|t[2]<<8|t[3])>>>0)*1e3}function D(e){return typeof e==`string`&&g.test(e)}const O=Object.assign(C,{toBytes:w,fromBytes:T,timestamp:E,isValid:D,NIL:`0`.repeat(20),MAX:d(new Uint8Array(12).fill(255))});export{i as BufferError,a as InvalidInputError,o as ParseError,s as UniqueIdError,O as xid};
+//# sourceMappingURL=xid.mjs.map

package/build/xid/xid.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"xid.mjs","names":["XID_BYTES"],"sources":["../../src/xid/base32hex.ts","../../src/xid/xid.ts"],"sourcesContent":["import { BufferError, ParseError } from '../errors'\n\nconst ENCODING = '0123456789abcdefghijklmnopqrstuv'\nconst XID_BYTES = 12\nconst XID_LENGTH = 20\n\nconst DECODING = new Uint8Array(65536)\nDECODING.fill(255)\nfor (let i = 0; i < ENCODING.length; i += 1) {\n  DECODING[ENCODING.charCodeAt(i)] = i\n}\n\n/** Encode the 12 canonical XID bytes as lowercase base32hex. */\nexport function encodeBase32Hex(bytes: Uint8Array): string {\n  if (bytes.length !== XID_BYTES) {\n    throw new BufferError(\n      'XID_BYTES_INVALID_LENGTH',\n      `XID bytes must be exactly ${XID_BYTES} bytes, got ${bytes.length}`,\n    )\n  }\n\n  return (\n    ENCODING[bytes[0] >> 3] +\n    ENCODING[((bytes[0] << 2) | (bytes[1] >> 6)) & 0x1f] +\n    ENCODING[(bytes[1] >> 1) & 0x1f] +\n    ENCODING[((bytes[1] << 4) | (bytes[2] >> 4)) & 0x1f] +\n    ENCODING[((bytes[2] << 1) | (bytes[3] >> 7)) & 0x1f] +\n    ENCODING[(bytes[3] >> 2) & 0x1f] +\n    ENCODING[((bytes[3] << 3) | (bytes[4] >> 5)) & 0x1f] +\n    ENCODING[bytes[4] & 0x1f] +\n    ENCODING[bytes[5] >> 3] +\n    ENCODING[((bytes[5] << 2) | (bytes[6] >> 6)) & 0x1f] +\n    ENCODING[(bytes[6] >> 1) & 0x1f] +\n    ENCODING[((bytes[6] << 4) | (bytes[7] >> 4)) & 0x1f] +\n    ENCODING[((bytes[7] << 1) | (bytes[8] >> 7)) & 0x1f] +\n    ENCODING[(bytes[8] >> 2) & 0x1f] +\n    ENCODING[((bytes[8] << 3) | (bytes[9] >> 5)) & 0x1f] +\n    ENCODING[bytes[9] & 0x1f] +\n    ENCODING[bytes[10] >> 3] +\n    ENCODING[((bytes[10] << 2) | (bytes[11] >> 6)) & 0x1f] +\n    ENCODING[(bytes[11] >> 1) & 0x1f] +\n    ENCODING[(bytes[11] << 4) & 0x1f]\n  )\n}\n\n/** Decode a canonical lowercase base32hex XID string to its 12 bytes. */\nexport function decodeBase32Hex(id: string): Uint8Array {\n  if (id.length !== XID_LENGTH) {\n    throw new ParseError('XID_INVALID_LENGTH', `XID string must be ${XID_LENGTH} characters, got ${id.length}`)\n  }\n\n  const values = new Uint8Array(XID_LENGTH)\n  for (let i = 0; i < XID_LENGTH; i += 1) {\n    const value = DECODING[id.charCodeAt(i)]\n    if (value === 255) {\n      throw new ParseError('XID_INVALID_CHAR', `Invalid XID character: ${id[i]}`)\n    }\n    values[i] = value\n  }\n\n  if (values[19] !== 0 && values[19] !== 16) {\n    throw new ParseError('XID_NON_CANONICAL', 'XID trailing bits must be canonically encoded')\n  }\n\n  return new Uint8Array([\n    (values[0] << 3) | (values[1] >> 2),\n    (values[1] << 6) | (values[2] << 1) | (values[3] >> 4),\n    (values[3] << 4) | (values[4] >> 1),\n    (values[4] << 7) | (values[5] << 2) | (values[6] >> 3),\n    (values[6] << 5) | values[7],\n    (values[8] << 3) | (values[9] >> 2),\n    (values[9] << 6) | (values[10] << 1) | (values[11] >> 4),\n    (values[11] << 4) | (values[12] >> 1),\n    (values[12] << 7) | (values[13] << 2) | (values[14] >> 3),\n    (values[14] << 5) | values[15],\n    (values[16] << 3) | (values[17] >> 2),\n    (values[17] << 6) | (values[18] << 1) | (values[19] >> 4),\n  ])\n}\n","import { writeTimestamp32 } from '../common/bytes'\nimport { randomBytes, randomUint32 } from '../common/random'\nimport { isIntegerInRange, isWritableRange } from '../common/validation'\nimport { BufferError, InvalidInputError } from '../errors'\nimport { decodeBase32Hex, encodeBase32Hex } from './base32hex'\n\nconst XID_BYTES = 12\nconst MACHINE_ID_BYTES = 3\nconst MAX_SECS = 0xffffffff\nconst MAX_PROCESS_ID = 0xffff\nconst MAX_COUNTER = 0xffffff\nconst XID_REGEX = /^[0-9a-v]{19}[0g]$/\n\nexport type XidOptions = {\n  /** First three bytes used as the XID machine identity. */\n  machineId?: Uint8Array\n  /** 16-bit process identity. */\n  processId?: number\n  /** Unix timestamp in seconds. Defaults to the current second. */\n  secs?: number\n  /** 24-bit counter. Explicit values do not consume shared state. */\n  counter?: number\n}\n\nexport type Xid = {\n  (): string\n  <TBuf extends Uint8Array = Uint8Array>(options: XidOptions | undefined, buf: TBuf, offset?: number): TBuf\n  (options?: XidOptions, buf?: undefined, offset?: number): string\n  toBytes(id: string): Uint8Array\n  fromBytes(bytes: Uint8Array): string\n  timestamp(id: string): number\n  isValid(id: unknown): id is string\n  NIL: string\n  MAX: string\n}\n\ntype XidState = {\n  machineId: Uint8Array | undefined\n  processId: number | undefined\n  counter: number | undefined\n}\n\nconst state: XidState = { machineId: undefined, processId: undefined, counter: undefined }\n\n/** Copy pooled bytes before another random draw can refill their backing pool. */\nfunction freshRandom(count: number): Uint8Array {\n  return randomBytes(count).slice()\n}\n\nfunction initializeIdentity(): void {\n  if (state.machineId === undefined) state.machineId = freshRandom(MACHINE_ID_BYTES)\n  if (state.processId === undefined) state.processId = randomUint32() & MAX_PROCESS_ID\n}\n\nfunction nextCounter(): number {\n  if (state.counter === undefined) state.counter = randomUint32() & MAX_COUNTER\n  state.counter = (state.counter + 1) & MAX_COUNTER\n  return state.counter\n}\n\nfunction writeXidBytesUnchecked(\n  secs: number,\n  machineId: Uint8Array,\n  processId: number,\n  counter: number,\n  buf: Uint8Array,\n  offset: number,\n): void {\n  writeTimestamp32(buf, offset, secs)\n  buf.set(machineId.subarray(0, MACHINE_ID_BYTES), offset + 4)\n  buf[offset + 7] = processId >>> 8\n  buf[offset + 8] = processId & 0xff\n  buf[offset + 9] = counter >>> 16\n  buf[offset + 10] = (counter >>> 8) & 0xff\n  buf[offset + 11] = counter & 0xff\n}\n\nfunction validateOptions(options: XidOptions): void {\n  if (options.machineId !== undefined && options.machineId.length < MACHINE_ID_BYTES) {\n    throw new InvalidInputError(\n      'XID_MACHINE_ID_BYTES_TOO_SHORT',\n      `Machine ID bytes length must be >= ${MACHINE_ID_BYTES} for XID`,\n    )\n  }\n  if (options.processId !== undefined && !isIntegerInRange(options.processId, 0, MAX_PROCESS_ID)) {\n    throw new InvalidInputError('XID_PROCESS_ID_OUT_OF_RANGE', `Process ID must be between 0 and ${MAX_PROCESS_ID}`)\n  }\n  if (options.secs !== undefined && !isIntegerInRange(options.secs, 0, MAX_SECS)) {\n    throw new InvalidInputError('XID_TIMESTAMP_OUT_OF_RANGE', `Timestamp must be between 0 and ${MAX_SECS}`)\n  }\n  if (options.counter !== undefined && !isIntegerInRange(options.counter, 0, MAX_COUNTER)) {\n    throw new InvalidInputError('XID_COUNTER_OUT_OF_RANGE', `Counter must be between 0 and ${MAX_COUNTER}`)\n  }\n}\n\nfunction xidFn(options?: XidOptions, buf?: undefined, offset?: number): string\nfunction xidFn<TBuf extends Uint8Array = Uint8Array>(options: XidOptions | undefined, buf: TBuf, offset?: number): TBuf\nfunction xidFn<TBuf extends Uint8Array = Uint8Array>(options?: XidOptions, buf?: TBuf, offset = 0): string | TBuf {\n  if (options !== undefined) validateOptions(options)\n\n  const secs = options?.secs ?? Math.floor(Date.now() / 1000)\n  if (options?.machineId === undefined || options.processId === undefined) {\n    initializeIdentity()\n  }\n  const machineId = options?.machineId ?? state.machineId!\n  const processId = options?.processId ?? state.processId!\n  const counter = options?.counter ?? nextCounter()\n\n  if (buf !== undefined) {\n    if (!isWritableRange(buf, offset, XID_BYTES)) {\n      throw new BufferError(\n        'XID_BUFFER_OUT_OF_BOUNDS',\n        `XID byte range ${offset}:${offset + 11} is out of buffer bounds`,\n      )\n    }\n    writeXidBytesUnchecked(secs, machineId, processId, counter, buf, offset)\n    return buf\n  }\n\n  const bytes = new Uint8Array(XID_BYTES)\n  writeXidBytesUnchecked(secs, machineId, processId, counter, bytes, 0)\n  return encodeBase32Hex(bytes)\n}\n\nfunction toBytes(id: string): Uint8Array {\n  return decodeBase32Hex(id)\n}\n\nfunction fromBytes(bytes: Uint8Array): string {\n  return encodeBase32Hex(bytes)\n}\n\nfunction timestamp(id: string): number {\n  const bytes = decodeBase32Hex(id)\n  return (((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0) * 1000\n}\n\nfunction isValid(id: unknown): id is string {\n  return typeof id === 'string' && XID_REGEX.test(id)\n}\n\n/**\n * Generate a 20-character rs/xid-compatible identifier.\n *\n * XID embeds seconds, a lazily-random per-runtime identity, and a shared\n * always-incrementing counter. In Cloudflare Workers, time is frozen during a\n * request, so the counter preserves ordering for IDs made in that request.\n */\nexport const xid: Xid = Object.assign(xidFn, {\n  toBytes,\n  fromBytes,\n  timestamp,\n  isValid,\n  NIL: '0'.repeat(20),\n  MAX: encodeBase32Hex(new Uint8Array(12).fill(0xff)),\n})\n\nexport { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'\n"],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "private": false,
   "name": "uniku",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Minimal, tree-shakeable unique ID generators for every JavaScript runtime",
   "author": {
     "name": "Alberto Schiabel",
@@ -28,6 +28,7 @@
     "nanoid",
     "ksuid",
     "objectid",
+    "xid",
     "mongodb",
     "tsid",
     "snowflake",
@@ -110,6 +111,11 @@
       "import": "./build/tsid/tsid.mjs",
       "default": "./build/tsid/tsid.mjs"
     },
+    "./xid": {
+      "types": "./build/xid/xid.d.mts",
+      "import": "./build/xid/xid.mjs",
+      "default": "./build/xid/xid.mjs"
+    },
     "./errors": {
       "types": "./build/errors.d.mts",
       "import": "./build/errors.mjs",
@@ -130,13 +136,15 @@
     "@owpz/ksuid": "^25.7.20",
     "@paralleldrive/cuid2": "^3.3.0",
     "@types/bun": "^1.3.14",
-    "effect": "4.0.0-beta.93",
     "bson": "^7.3.1",
+    "effect": "4.0.0-beta.93",
     "nanoid": "^5.1.16",
+    "nexid": "^2.1.0",
     "tsid-ts": "^0.0.9",
     "typeid-js": "1.2.0",
     "ulid": "3.0.2",
-    "uuid": "14.0.1"
+    "uuid": "14.0.1",
+    "xid-ts": "^1.3.0"
   },
   "scripts": {
     "clean": "rimraf build .turbo",

package/src/generators.ts

@@ -9,7 +9,7 @@
 // Plain `as const` (not `as const satisfies readonly string[]`): the `satisfies`
 // wrapper defeats isolatedDeclarations' trivial declaration emit for this export.
 // All members are string literals, so the shape guard adds nothing here anyway.
-export const ID_GENERATORS = ['uuid', 'ulid', 'typeid', 'nanoid', 'cuid', 'ksuid', 'objectid', 'tsid'] as const
+export const ID_GENERATORS = ['uuid', 'ulid', 'typeid', 'nanoid', 'cuid', 'ksuid', 'objectid', 'tsid', 'xid'] as const
 
 /**
  * The union of ID generators supported by uniku, derived from {@link ID_GENERATORS}.

package/src/xid/base32hex.ts

@@ -0,0 +1,79 @@
+import { BufferError, ParseError } from '../errors'
+
+const ENCODING = '0123456789abcdefghijklmnopqrstuv'
+const XID_BYTES = 12
+const XID_LENGTH = 20
+
+const DECODING = new Uint8Array(65536)
+DECODING.fill(255)
+for (let i = 0; i < ENCODING.length; i += 1) {
+  DECODING[ENCODING.charCodeAt(i)] = i
+}
+
+/** Encode the 12 canonical XID bytes as lowercase base32hex. */
+export function encodeBase32Hex(bytes: Uint8Array): string {
+  if (bytes.length !== XID_BYTES) {
+    throw new BufferError(
+      'XID_BYTES_INVALID_LENGTH',
+      `XID bytes must be exactly ${XID_BYTES} bytes, got ${bytes.length}`,
+    )
+  }
+
+  return (
+    ENCODING[bytes[0] >> 3] +
+    ENCODING[((bytes[0] << 2) | (bytes[1] >> 6)) & 0x1f] +
+    ENCODING[(bytes[1] >> 1) & 0x1f] +
+    ENCODING[((bytes[1] << 4) | (bytes[2] >> 4)) & 0x1f] +
+    ENCODING[((bytes[2] << 1) | (bytes[3] >> 7)) & 0x1f] +
+    ENCODING[(bytes[3] >> 2) & 0x1f] +
+    ENCODING[((bytes[3] << 3) | (bytes[4] >> 5)) & 0x1f] +
+    ENCODING[bytes[4] & 0x1f] +
+    ENCODING[bytes[5] >> 3] +
+    ENCODING[((bytes[5] << 2) | (bytes[6] >> 6)) & 0x1f] +
+    ENCODING[(bytes[6] >> 1) & 0x1f] +
+    ENCODING[((bytes[6] << 4) | (bytes[7] >> 4)) & 0x1f] +
+    ENCODING[((bytes[7] << 1) | (bytes[8] >> 7)) & 0x1f] +
+    ENCODING[(bytes[8] >> 2) & 0x1f] +
+    ENCODING[((bytes[8] << 3) | (bytes[9] >> 5)) & 0x1f] +
+    ENCODING[bytes[9] & 0x1f] +
+    ENCODING[bytes[10] >> 3] +
+    ENCODING[((bytes[10] << 2) | (bytes[11] >> 6)) & 0x1f] +
+    ENCODING[(bytes[11] >> 1) & 0x1f] +
+    ENCODING[(bytes[11] << 4) & 0x1f]
+  )
+}
+
+/** Decode a canonical lowercase base32hex XID string to its 12 bytes. */
+export function decodeBase32Hex(id: string): Uint8Array {
+  if (id.length !== XID_LENGTH) {
+    throw new ParseError('XID_INVALID_LENGTH', `XID string must be ${XID_LENGTH} characters, got ${id.length}`)
+  }
+
+  const values = new Uint8Array(XID_LENGTH)
+  for (let i = 0; i < XID_LENGTH; i += 1) {
+    const value = DECODING[id.charCodeAt(i)]
+    if (value === 255) {
+      throw new ParseError('XID_INVALID_CHAR', `Invalid XID character: ${id[i]}`)
+    }
+    values[i] = value
+  }
+
+  if (values[19] !== 0 && values[19] !== 16) {
+    throw new ParseError('XID_NON_CANONICAL', 'XID trailing bits must be canonically encoded')
+  }
+
+  return new Uint8Array([
+    (values[0] << 3) | (values[1] >> 2),
+    (values[1] << 6) | (values[2] << 1) | (values[3] >> 4),
+    (values[3] << 4) | (values[4] >> 1),
+    (values[4] << 7) | (values[5] << 2) | (values[6] >> 3),
+    (values[6] << 5) | values[7],
+    (values[8] << 3) | (values[9] >> 2),
+    (values[9] << 6) | (values[10] << 1) | (values[11] >> 4),
+    (values[11] << 4) | (values[12] >> 1),
+    (values[12] << 7) | (values[13] << 2) | (values[14] >> 3),
+    (values[14] << 5) | values[15],
+    (values[16] << 3) | (values[17] >> 2),
+    (values[17] << 6) | (values[18] << 1) | (values[19] >> 4),
+  ])
+}

package/src/xid/xid.ts

@@ -0,0 +1,158 @@
+import { writeTimestamp32 } from '../common/bytes'
+import { randomBytes, randomUint32 } from '../common/random'
+import { isIntegerInRange, isWritableRange } from '../common/validation'
+import { BufferError, InvalidInputError } from '../errors'
+import { decodeBase32Hex, encodeBase32Hex } from './base32hex'
+
+const XID_BYTES = 12
+const MACHINE_ID_BYTES = 3
+const MAX_SECS = 0xffffffff
+const MAX_PROCESS_ID = 0xffff
+const MAX_COUNTER = 0xffffff
+const XID_REGEX = /^[0-9a-v]{19}[0g]$/
+
+export type XidOptions = {
+  /** First three bytes used as the XID machine identity. */
+  machineId?: Uint8Array
+  /** 16-bit process identity. */
+  processId?: number
+  /** Unix timestamp in seconds. Defaults to the current second. */
+  secs?: number
+  /** 24-bit counter. Explicit values do not consume shared state. */
+  counter?: number
+}
+
+export type Xid = {
+  (): string
+  <TBuf extends Uint8Array = Uint8Array>(options: XidOptions | undefined, buf: TBuf, offset?: number): TBuf
+  (options?: XidOptions, buf?: undefined, offset?: number): string
+  toBytes(id: string): Uint8Array
+  fromBytes(bytes: Uint8Array): string
+  timestamp(id: string): number
+  isValid(id: unknown): id is string
+  NIL: string
+  MAX: string
+}
+
+type XidState = {
+  machineId: Uint8Array | undefined
+  processId: number | undefined
+  counter: number | undefined
+}
+
+const state: XidState = { machineId: undefined, processId: undefined, counter: undefined }
+
+/** Copy pooled bytes before another random draw can refill their backing pool. */
+function freshRandom(count: number): Uint8Array {
+  return randomBytes(count).slice()
+}
+
+function initializeIdentity(): void {
+  if (state.machineId === undefined) state.machineId = freshRandom(MACHINE_ID_BYTES)
+  if (state.processId === undefined) state.processId = randomUint32() & MAX_PROCESS_ID
+}
+
+function nextCounter(): number {
+  if (state.counter === undefined) state.counter = randomUint32() & MAX_COUNTER
+  state.counter = (state.counter + 1) & MAX_COUNTER
+  return state.counter
+}
+
+function writeXidBytesUnchecked(
+  secs: number,
+  machineId: Uint8Array,
+  processId: number,
+  counter: number,
+  buf: Uint8Array,
+  offset: number,
+): void {
+  writeTimestamp32(buf, offset, secs)
+  buf.set(machineId.subarray(0, MACHINE_ID_BYTES), offset + 4)
+  buf[offset + 7] = processId >>> 8
+  buf[offset + 8] = processId & 0xff
+  buf[offset + 9] = counter >>> 16
+  buf[offset + 10] = (counter >>> 8) & 0xff
+  buf[offset + 11] = counter & 0xff
+}
+
+function validateOptions(options: XidOptions): void {
+  if (options.machineId !== undefined && options.machineId.length < MACHINE_ID_BYTES) {
+    throw new InvalidInputError(
+      'XID_MACHINE_ID_BYTES_TOO_SHORT',
+      `Machine ID bytes length must be >= ${MACHINE_ID_BYTES} for XID`,
+    )
+  }
+  if (options.processId !== undefined && !isIntegerInRange(options.processId, 0, MAX_PROCESS_ID)) {
+    throw new InvalidInputError('XID_PROCESS_ID_OUT_OF_RANGE', `Process ID must be between 0 and ${MAX_PROCESS_ID}`)
+  }
+  if (options.secs !== undefined && !isIntegerInRange(options.secs, 0, MAX_SECS)) {
+    throw new InvalidInputError('XID_TIMESTAMP_OUT_OF_RANGE', `Timestamp must be between 0 and ${MAX_SECS}`)
+  }
+  if (options.counter !== undefined && !isIntegerInRange(options.counter, 0, MAX_COUNTER)) {
+    throw new InvalidInputError('XID_COUNTER_OUT_OF_RANGE', `Counter must be between 0 and ${MAX_COUNTER}`)
+  }
+}
+
+function xidFn(options?: XidOptions, buf?: undefined, offset?: number): string
+function xidFn<TBuf extends Uint8Array = Uint8Array>(options: XidOptions | undefined, buf: TBuf, offset?: number): TBuf
+function xidFn<TBuf extends Uint8Array = Uint8Array>(options?: XidOptions, buf?: TBuf, offset = 0): string | TBuf {
+  if (options !== undefined) validateOptions(options)
+
+  const secs = options?.secs ?? Math.floor(Date.now() / 1000)
+  if (options?.machineId === undefined || options.processId === undefined) {
+    initializeIdentity()
+  }
+  const machineId = options?.machineId ?? state.machineId!
+  const processId = options?.processId ?? state.processId!
+  const counter = options?.counter ?? nextCounter()
+
+  if (buf !== undefined) {
+    if (!isWritableRange(buf, offset, XID_BYTES)) {
+      throw new BufferError(
+        'XID_BUFFER_OUT_OF_BOUNDS',
+        `XID byte range ${offset}:${offset + 11} is out of buffer bounds`,
+      )
+    }
+    writeXidBytesUnchecked(secs, machineId, processId, counter, buf, offset)
+    return buf
+  }
+
+  const bytes = new Uint8Array(XID_BYTES)
+  writeXidBytesUnchecked(secs, machineId, processId, counter, bytes, 0)
+  return encodeBase32Hex(bytes)
+}
+
+function toBytes(id: string): Uint8Array {
+  return decodeBase32Hex(id)
+}
+
+function fromBytes(bytes: Uint8Array): string {
+  return encodeBase32Hex(bytes)
+}
+
+function timestamp(id: string): number {
+  const bytes = decodeBase32Hex(id)
+  return (((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0) * 1000
+}
+
+function isValid(id: unknown): id is string {
+  return typeof id === 'string' && XID_REGEX.test(id)
+}
+
+/**
+ * Generate a 20-character rs/xid-compatible identifier.
+ *
+ * XID embeds seconds, a lazily-random per-runtime identity, and a shared
+ * always-incrementing counter. In Cloudflare Workers, time is frozen during a
+ * request, so the counter preserves ordering for IDs made in that request.
+ */
+export const xid: Xid = Object.assign(xidFn, {
+  toBytes,
+  fromBytes,
+  timestamp,
+  isValid,
+  NIL: '0'.repeat(20),
+  MAX: encodeBase32Hex(new Uint8Array(12).fill(0xff)),
+})
+
+export { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'