@glion/util-uid 0.18.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Rethink Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @glion/util-uid
+
+Time-ordered, HL7v2-safe unique IDs.
+
+## What it does
+
+`@glion/util-uid` generates short, sortable, HL7v2-safe unique IDs. Use them for MSH-10 message control IDs, order numbers, or any field that needs a unique identifier.
+
+- **Fits MSH-10.** IDs are 20 characters — a standard ULID is 26 and does not fit.
+- **Sorts by time.** IDs start with a timestamp, so sorting IDs sorts by creation time.
+- **Safe characters only.** Digits and uppercase letters, minus I, L, O, and U: no HL7 delimiters, easy to read aloud, hard to mistype.
+
+## Install
+
+```bash
+npm install @glion/util-uid
+```
+
+## Use
+
+```ts
+import { uid } from "@glion/util-uid";
+
+const controlId = uid(); // e.g. for MSH-10
+// "01J9Z6M8QKT5W3XA9C0D" — 20 characters, sorts by generation time
+```
+
+Need a branded ID? Compose it: `"MKE" + uid({ size: 17 })`.
+
+## API
+
+### `uid(options?)`
+
+Generates a time-ordered unique identifier.
+
+| Parameter      | Type     | Default | Description                      |
+| -------------- | -------- | ------- | -------------------------------- |
+| `options.size` | `number` | `20`    | Total length of the generated ID |
+
+The time part needs 10 characters: keep `size >= 11`, or the ID degrades to a pure-random tail (unique, but not time-ordered). `size` must be a positive integer (`RangeError` otherwise). Per-millisecond uniqueness rests entirely on the random tail, so prefer the full default width when volumes are high.
+
+## Part of Glion
+
+`@glion/util-uid` is part of **[Glion]**, the application framework for HL7v2. See the [Glion README] for the full package catalog and architecture.
+
+[Glion]: https://github.com/rethinkhealth/glion#readme
+[Glion README]: https://github.com/rethinkhealth/glion#readme

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { uid } from "./uid";
+export type { UidOptions } from "./uid";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,YAAY,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC"}

package/dist/index.js

@@ -0,0 +1,76 @@
+//#region src/invariant.ts
+/**
+* Assertion primitives for this package's own internal invariants — bugs in
+* OUR arithmetic, never domain outcomes (a NAK is an `AckException`; an
+* invariant failure must never masquerade as one).
+*/
+/** Thrown when an internal invariant is violated — always a bug; report it. */
+var InvariantError = class extends Error {
+	constructor(message) {
+		super(`@glion/util-uid internal invariant violated: ${message} — this is a bug, please report it`);
+		this.name = "InvariantError";
+	}
+};
+/** Assert `condition`; the `asserts` signature also narrows types for tsc. */
+function invariant(condition, message) {
+	if (!condition) throw new InvariantError(message);
+}
+//#endregion
+//#region src/uid.ts
+/**
+* Time-ordered unique IDs for HL7v2 identifier fields — the ULID idea
+* resized to a 20-character default that fits MSH-10, the tightest common
+* ST field (a standard 26-character ULID cannot fit).
+* Stateless: fresh randomness every call, the same semantics as the ULID
+* reference implementation's default `ulid()`.
+*
+* @module
+*/
+const MAX_LENGTH = 20;
+const TIME_LENGTH = 10;
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/**
+* Encode `value` as exactly `length` Crockford base32 characters,
+* zero-padded. Throws when `value` is not a non-negative integer below
+* `32 ** length` — exported for its tests, not part of the package surface.
+*/
+function encodeCrockford(value, length) {
+	invariant(Number.isInteger(value) && value >= 0, `${value} is not encodable — the encoder takes non-negative integers`);
+	invariant(value < 32 ** length, `${value} does not fit ${length} base32 characters`);
+	let out = "";
+	let rest = value;
+	for (let i = 0; i < length; i++) {
+		out = ALPHABET[rest % 32] + out;
+		rest = Math.floor(rest / 32);
+	}
+	return out;
+}
+/**
+* `length` Crockford characters of fresh randomness — exported for its
+* tests, not part of the package surface.
+*/
+function randomChars(length) {
+	const bytes = new Uint8Array(length);
+	crypto.getRandomValues(bytes);
+	let out = "";
+	for (const byte of bytes) out += ALPHABET[byte % 32];
+	return out;
+}
+/**
+* Generate a time-ordered unique ID: timestamp + randomness, `size`
+* characters total (default 20 — fits MSH-10's ST limit). IDs sort
+* lexicographically by millisecond; same-millisecond IDs are unique but
+* unordered. Keep `size >= 11`: the timestamp needs 10 characters, and
+* per-millisecond uniqueness rests on what remains. Need a branded ID?
+* Compose it: `"MKE" + uid({ size: 17 })`.
+*/
+function uid(options = {}) {
+	const { size = MAX_LENGTH } = options;
+	if (!(Number.isInteger(size) && size > 0)) throw new RangeError(`uid size must be a positive integer, got ${size}`);
+	if (size <= TIME_LENGTH) return randomChars(size);
+	return encodeCrockford(Date.now(), TIME_LENGTH) + randomChars(size - TIME_LENGTH);
+}
+//#endregion
+export { uid };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/invariant.ts","../src/uid.ts"],"sourcesContent":["/**\n * Assertion primitives for this package's own internal invariants — bugs in\n * OUR arithmetic, never domain outcomes (a NAK is an `AckException`; an\n * invariant failure must never masquerade as one).\n */\n\n/** Thrown when an internal invariant is violated — always a bug; report it. */\nexport class InvariantError extends Error {\n  constructor(message: string) {\n    super(\n      `@glion/util-uid internal invariant violated: ${message} — this is a bug, please report it`\n    );\n    this.name = \"InvariantError\";\n  }\n}\n\n/** Assert `condition`; the `asserts` signature also narrows types for tsc. */\nexport function invariant(\n  condition: unknown,\n  message: string\n): asserts condition {\n  if (!condition) {\n    throw new InvariantError(message);\n  }\n}\n","/**\n * Time-ordered unique IDs for HL7v2 identifier fields — the ULID idea\n * resized to a 20-character default that fits MSH-10, the tightest common\n * ST field (a standard 26-character ULID cannot fit).\n * Stateless: fresh randomness every call, the same semantics as the ULID\n * reference implementation's default `ulid()`.\n *\n * @module\n */\n\nimport { invariant } from \"./invariant\";\n\n// Default budget: 20 characters — MSH-10's ST limit, the tightest common\n// HL7v2 identifier field.\nconst MAX_LENGTH = 20;\n\n// Characters the millisecond timestamp occupies. One base32 character is\n// 5 bits, so 10 characters hold 50 — every timestamp until the year 10889,\n// the same horizon as a standard ULID.\nconst TIME_LENGTH = 10;\n\n// Crockford base32 (https://www.crockford.com/base32.html): 0-9 plus the\n// uppercase alphabet minus I, L, O (read back as 1 and 0 by humans) and U\n// (accidental profanity). Index N encodes value N, so equal-length encodings\n// sort lexicographically in numeric order — what makes the IDs time-sortable\n// as plain strings. No HL7 delimiters, nothing legacy engines trip over.\n// Exported for its tests, not part of the package surface.\nexport const ALPHABET = \"0123456789ABCDEFGHJKMNPQRSTVWXYZ\";\n\n/**\n * Encode `value` as exactly `length` Crockford base32 characters,\n * zero-padded. Throws when `value` is not a non-negative integer below\n * `32 ** length` — exported for its tests, not part of the package surface.\n */\nexport function encodeCrockford(value: number, length: number): string {\n  // A value that does not fit would be truncated into a valid-LOOKING ID\n  // that silently stops sorting (and can collide). Loud beats silent for\n  // our own arithmetic — same rationale as unframe's assertInvariant.\n  invariant(\n    Number.isInteger(value) && value >= 0,\n    `${value} is not encodable — the encoder takes non-negative integers`\n  );\n  invariant(\n    value < 32 ** length,\n    `${value} does not fit ${length} base32 characters`\n  );\n  let out = \"\";\n  let rest = value;\n  for (let i = 0; i < length; i++) {\n    // Plain base conversion, like toString(16) with a custom alphabet:\n    // `rest % 32` is the lowest base32 digit, prepending puts high digits\n    // first — so larger values sort later as strings.\n    out = ALPHABET[rest % 32] + out;\n    rest = Math.floor(rest / 32);\n  }\n  // The loop always runs `length` times; once `rest` hits 0 it emits \"0\"s.\n  // That left-padding is load-bearing: \"2\" < \"10\" numerically but not\n  // lexicographically — constant width keeps string order = numeric order.\n  return out;\n}\n\n/**\n * `length` Crockford characters of fresh randomness — exported for its\n * tests, not part of the package surface.\n */\nexport function randomChars(length: number): string {\n  // One random byte per character. A byte spans 256 values and 256 is a\n  // whole multiple of 32, so `byte % 32` is exactly uniform over the\n  // alphabet — 5 bits of randomness per character, no bias, and no bit\n  // arithmetic to combine draws.\n  const bytes = new Uint8Array(length);\n  crypto.getRandomValues(bytes);\n  let out = \"\";\n  for (const byte of bytes) {\n    out += ALPHABET[byte % 32];\n  }\n  return out;\n}\n\nexport interface UidOptions {\n  size?: number;\n}\n\n/**\n * Generate a time-ordered unique ID: timestamp + randomness, `size`\n * characters total (default 20 — fits MSH-10's ST limit). IDs sort\n * lexicographically by millisecond; same-millisecond IDs are unique but\n * unordered. Keep `size >= 11`: the timestamp needs 10 characters, and\n * per-millisecond uniqueness rests on what remains. Need a branded ID?\n * Compose it: `\"MKE\" + uid({ size: 17 })`.\n */\nexport function uid(options: UidOptions = {}): string {\n  const { size = MAX_LENGTH } = options;\n  // Boundary validation, not an internal invariant: a bad `size` is the\n  // caller's bug, so it gets a native RangeError, never InvariantError.\n  // Unchecked, NaN would silently emit a bare timestamp with ZERO\n  // randomness (Uint8Array(NaN) has length 0) — colliding IDs that look\n  // perfectly valid.\n  if (!(Number.isInteger(size) && size > 0)) {\n    throw new RangeError(`uid size must be a positive integer, got ${size}`);\n  }\n  if (size <= TIME_LENGTH) {\n    // Too narrow for a timestamp: unique, but not time-sortable.\n    return randomChars(size);\n  }\n\n  const timestamp = encodeCrockford(Date.now(), TIME_LENGTH);\n  const random = randomChars(size - TIME_LENGTH);\n  return timestamp + random;\n}\n"],"mappings":";;;;;;;AAOA,IAAa,iBAAb,cAAoC,MAAM;CACxC,YAAY,SAAiB;AAC3B,QACE,gDAAgD,QAAQ,oCACzD;AACD,OAAK,OAAO;;;;AAKhB,SAAgB,UACd,WACA,SACmB;AACnB,KAAI,CAAC,UACH,OAAM,IAAI,eAAe,QAAQ;;;;;;;;;;;;;ACRrC,MAAM,aAAa;AAKnB,MAAM,cAAc;AAQpB,MAAa,WAAW;;;;;;AAOxB,SAAgB,gBAAgB,OAAe,QAAwB;AAIrE,WACE,OAAO,UAAU,MAAM,IAAI,SAAS,GACpC,GAAG,MAAM,6DACV;AACD,WACE,QAAQ,MAAM,QACd,GAAG,MAAM,gBAAgB,OAAO,oBACjC;CACD,IAAI,MAAM;CACV,IAAI,OAAO;AACX,MAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAAK;AAI/B,QAAM,SAAS,OAAO,MAAM;AAC5B,SAAO,KAAK,MAAM,OAAO,GAAG;;AAK9B,QAAO;;;;;;AAOT,SAAgB,YAAY,QAAwB;CAKlD,MAAM,QAAQ,IAAI,WAAW,OAAO;AACpC,QAAO,gBAAgB,MAAM;CAC7B,IAAI,MAAM;AACV,MAAK,MAAM,QAAQ,MACjB,QAAO,SAAS,OAAO;AAEzB,QAAO;;;;;;;;;;AAeT,SAAgB,IAAI,UAAsB,EAAE,EAAU;CACpD,MAAM,EAAE,OAAO,eAAe;AAM9B,KAAI,EAAE,OAAO,UAAU,KAAK,IAAI,OAAO,GACrC,OAAM,IAAI,WAAW,4CAA4C,OAAO;AAE1E,KAAI,QAAQ,YAEV,QAAO,YAAY,KAAK;AAK1B,QAFkB,gBAAgB,KAAK,KAAK,EAAE,YAE9B,GADD,YAAY,OAAO,YACT"}

package/dist/invariant.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Assertion primitives for this package's own internal invariants — bugs in
+ * OUR arithmetic, never domain outcomes (a NAK is an `AckException`; an
+ * invariant failure must never masquerade as one).
+ */
+/** Thrown when an internal invariant is violated — always a bug; report it. */
+export declare class InvariantError extends Error {
+    constructor(message: string);
+}
+/** Assert `condition`; the `asserts` signature also narrows types for tsc. */
+export declare function invariant(condition: unknown, message: string): asserts condition;
+//# sourceMappingURL=invariant.d.ts.map

package/dist/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,+EAA+E;AAC/E,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAM5B;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CACvB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,CAInB"}

package/dist/uid.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Time-ordered unique IDs for HL7v2 identifier fields — the ULID idea
+ * resized to a 20-character default that fits MSH-10, the tightest common
+ * ST field (a standard 26-character ULID cannot fit).
+ * Stateless: fresh randomness every call, the same semantics as the ULID
+ * reference implementation's default `ulid()`.
+ *
+ * @module
+ */
+export declare const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/**
+ * Encode `value` as exactly `length` Crockford base32 characters,
+ * zero-padded. Throws when `value` is not a non-negative integer below
+ * `32 ** length` — exported for its tests, not part of the package surface.
+ */
+export declare function encodeCrockford(value: number, length: number): string;
+/**
+ * `length` Crockford characters of fresh randomness — exported for its
+ * tests, not part of the package surface.
+ */
+export declare function randomChars(length: number): string;
+export interface UidOptions {
+    size?: number;
+}
+/**
+ * Generate a time-ordered unique ID: timestamp + randomness, `size`
+ * characters total (default 20 — fits MSH-10's ST limit). IDs sort
+ * lexicographically by millisecond; same-millisecond IDs are unique but
+ * unordered. Keep `size >= 11`: the timestamp needs 10 characters, and
+ * per-millisecond uniqueness rests on what remains. Need a branded ID?
+ * Compose it: `"MKE" + uid({ size: 17 })`.
+ */
+export declare function uid(options?: UidOptions): string;
+//# sourceMappingURL=uid.d.ts.map

package/dist/uid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uid.d.ts","sourceRoot":"","sources":["../src/uid.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAmBH,eAAO,MAAM,QAAQ,qCAAqC,CAAC;AAE3D;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAyBrE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAYlD;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,OAAO,GAAE,UAAe,GAAG,MAAM,CAkBpD"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@glion/util-uid",
+  "version": "0.18.0",
+  "description": "Time-ordered unique IDs for HL7v2 — the ULID idea resized to a 20-character default that fits MSH-10 and other ST identifier fields",
+  "keywords": [
+    "health",
+    "healthcare",
+    "hl7",
+    "hl7v2",
+    "nodejs",
+    "typescript",
+    "uid",
+    "ulid"
+  ],
+  "homepage": "https://glion.dev",
+  "license": "MIT",
+  "author": {
+    "name": "Melek Somai",
+    "email": "melek@rethinkhealth.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rethinkhealth/glion.git",
+    "directory": "packages/util-uid"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "publint": "0.3.18",
+    "tsdown": "0.21.10",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11",
+    "@glion/check-readme": "0.18.0",
+    "@glion/testing": "0.18.0",
+    "@glion/tsconfig": "0.18.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown && tsc --emitDeclarationOnly",
+    "check-types": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",
+    "check:readme": "glion-check-readme",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "publint": "publint --strict"
+  }
+}