@lacspace/id 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data 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 conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+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.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,67 @@
+<div align="center">
+
+# @lacspace/id
+
+**Unique IDs done right — UUID v4, time-sortable UUID v7, Nano-ID-style & short codes.**
+
+[![npm version](https://img.shields.io/npm/v/@lacspace/id?color=%2316a34a&label=npm)](https://www.npmjs.com/package/@lacspace/id)
+[![minzipped](https://img.shields.io/bundlephobia/minzip/@lacspace/id?label=minzip)](https://bundlephobia.com/package/@lacspace/id)
+[![types](https://img.shields.io/badge/types-included-blue)](https://www.npmjs.com/package/@lacspace/id)
+[![license](https://img.shields.io/npm/l/@lacspace/id?color=green)](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
+
+</div>
+
+> Every ID kind you actually need, in one tiny package — including **UUID v7**, the time-sortable UUID that makes a fantastic database primary key. Cryptographically random (Web Crypto), monotonic within a millisecond, zero-dependency.
+
+- 🆔 `uuidv4()` — classic random UUID
+- ⏱️ `uuidv7()` — **time-sortable** UUID (great index-friendly primary key)
+- 🔤 `nanoid()` / `shortId()` — URL-safe random strings
+- 🏷️ `id("user")` — prefixed ids like `user_9f8c…`
+
+## Install
+
+```bash
+npm install @lacspace/id      # or pnpm add / yarn add / bun add
+```
+
+## Use
+
+```ts
+import { uuidv4, uuidv7, nanoid, shortId, id } from "@lacspace/id";
+
+uuidv4();          // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+uuidv7();          // "0192e7a1-3c2f-7abc-8def-1234567890ab"  ← sorts by time
+nanoid();          // "V1StGXR8_Z5jdHi6B-myT"
+shortId();         // "Ab3xK9_p"
+id("user");        // "user_9f8c1a3e7b2d4f6a"
+```
+
+Why v7? Because random UUIDs (v4) scatter across a database index, hurting insert performance. **v7 is lexicographically sortable by creation time** — index-friendly *and* globally unique — and `uuidv7Time(id)` reads the timestamp back out.
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `uuidv4()` | random UUID |
+| `uuidv7(now?)` · `uuidv7Time(id)` | time-sortable UUID + timestamp extract |
+| `nanoid(size=21)` · `shortId(size=8)` | URL-safe random strings |
+| `id(prefix, size=16)` | prefixed id |
+| `isUuid(s)` · `uuidVersion(s)` | validation |
+
+## Licensing
+
+This package is **free** under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — MIT-equivalent freedoms. Use it in personal and commercial projects at no cost; just keep the notice.
+
+Not every Lacspace package is free. We also offer **Commercial**, **Client-specific** and **Private** packages under separate terms — see the **[Lacspace Licence Centre](https://lacspace.com/licenses)**.
+
+---
+
+<div align="center">
+
+**Part of the Lacspace ecosystem — zero-dependency, isomorphic TypeScript packages.**
+
+[All packages ↗](https://lacspace.com/packages) · [npm org ↗](https://www.npmjs.com/org/lacspace) · [Licence Centre ↗](https://lacspace.com/licenses) · [GitHub ↗](https://github.com/lacspace/npm-packages)
+
+</div>
+
+<div align="center"><sub>Built with care by <a href="https://lacspace.com">Lacspace</a> · Lacspace Free Licence · <a href="https://github.com/lacspace/npm-packages">source</a></sub></div>

package/dist/index.cjs

@@ -0,0 +1,89 @@
+'use strict';
+
+// src/index.ts
+function getRandom(bytes) {
+  const c = globalThis.crypto;
+  if (!c || typeof c.getRandomValues !== "function") {
+    throw new Error("Web Crypto getRandomValues is unavailable in this environment.");
+  }
+  c.getRandomValues(bytes);
+  return bytes;
+}
+var HEX = [];
+for (let i = 0; i < 256; i++) HEX.push((i + 256).toString(16).slice(1));
+function bytesToUuid(b) {
+  return HEX[b[0]] + HEX[b[1]] + HEX[b[2]] + HEX[b[3]] + "-" + HEX[b[4]] + HEX[b[5]] + "-" + HEX[b[6]] + HEX[b[7]] + "-" + HEX[b[8]] + HEX[b[9]] + "-" + HEX[b[10]] + HEX[b[11]] + HEX[b[12]] + HEX[b[13]] + HEX[b[14]] + HEX[b[15]];
+}
+function uuidv4() {
+  const b = getRandom(new Uint8Array(16));
+  b[6] = b[6] & 15 | 64;
+  b[8] = b[8] & 63 | 128;
+  return bytesToUuid(b);
+}
+var lastV7Time = 0;
+var v7Counter = 0;
+function uuidv7(now) {
+  const time = now ?? Date.now();
+  if (time === lastV7Time) v7Counter++;
+  else {
+    lastV7Time = time;
+    v7Counter = 0;
+  }
+  const b = getRandom(new Uint8Array(16));
+  b[0] = time / 2 ** 40 & 255;
+  b[1] = time / 2 ** 32 & 255;
+  b[2] = time / 2 ** 24 & 255;
+  b[3] = time / 2 ** 16 & 255;
+  b[4] = time / 2 ** 8 & 255;
+  b[5] = time & 255;
+  b[6] = 112 | v7Counter >> 8 & 15;
+  b[7] = v7Counter & 255;
+  b[8] = b[8] & 63 | 128;
+  return bytesToUuid(b);
+}
+function uuidv7Time(uuid) {
+  const hex = uuid.replace(/-/g, "").slice(0, 12);
+  return parseInt(hex, 16);
+}
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function isUuid(s) {
+  return UUID_RE.test(s);
+}
+function uuidVersion(s) {
+  return isUuid(s) ? parseInt(s[14], 16) : null;
+}
+var NANO_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
+var URL_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_";
+function randomFromAlphabet(size, alphabet) {
+  const mask = (2 << 31 - Math.clz32(alphabet.length - 1 | 1)) - 1;
+  const step = Math.ceil(1.6 * mask * size / alphabet.length);
+  let id2 = "";
+  while (id2.length < size) {
+    const bytes = getRandom(new Uint8Array(step));
+    for (let i = 0; i < step && id2.length < size; i++) {
+      const idx = bytes[i] & mask;
+      if (idx < alphabet.length) id2 += alphabet[idx];
+    }
+  }
+  return id2;
+}
+function nanoid(size = 21) {
+  return randomFromAlphabet(size, NANO_ALPHABET);
+}
+function shortId(size = 8) {
+  return randomFromAlphabet(size, URL_ALPHABET);
+}
+function id(prefix, size = 16) {
+  return `${prefix}_${nanoid(size)}`;
+}
+
+exports.id = id;
+exports.isUuid = isUuid;
+exports.nanoid = nanoid;
+exports.shortId = shortId;
+exports.uuidVersion = uuidVersion;
+exports.uuidv4 = uuidv4;
+exports.uuidv7 = uuidv7;
+exports.uuidv7Time = uuidv7Time;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["id"],"mappings":";;;AAQA,SAAS,UAAU,KAAA,EAA+B;AAChD,EAAA,MAAM,IAAK,UAAA,CAAmC,MAAA;AAC9C,EAAA,IAAI,CAAC,CAAA,IAAK,OAAO,CAAA,CAAE,oBAAoB,UAAA,EAAY;AACjD,IAAA,MAAM,IAAI,MAAM,gEAAgE,CAAA;AAAA,EAClF;AACA,EAAA,CAAA,CAAE,gBAAgB,KAAK,CAAA;AACvB,EAAA,OAAO,KAAA;AACT;AAEA,IAAM,MAAgB,EAAC;AACvB,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,GAAA,EAAK,KAAK,GAAA,CAAI,IAAA,CAAA,CAAM,CAAA,GAAI,GAAA,EAAO,QAAA,CAAS,EAAE,CAAA,CAAE,KAAA,CAAM,CAAC,CAAC,CAAA;AAExE,SAAS,YAAY,CAAA,EAAuB;AAC1C,EAAA,OACE,IAAI,CAAA,CAAE,CAAC,CAAE,CAAA,GAAK,IAAI,CAAA,CAAE,CAAC,CAAE,CAAA,GAAK,IAAI,CAAA,CAAE,CAAC,CAAE,CAAA,GAAK,GAAA,CAAI,EAAE,CAAC,CAAE,CAAA,GAAK,GAAA,GACxD,IAAI,CAAA,CAAE,CAAC,CAAE,CAAA,GAAK,GAAA,CAAI,EAAE,CAAC,CAAE,CAAA,GAAK,GAAA,GAC5B,IAAI,CAAA,CAAE,CAAC,CAAE,CAAA,GAAK,GAAA,CAAI,EAAE,CAAC,CAAE,CAAA,GAAK,GAAA,GAC5B,IAAI,CAAA,CAAE,CAAC,CAAE,CAAA,GAAK,IAAI,CAAA,CAAE,CAAC,CAAE,CAAA,GAAK,MAC5B,GAAA,CAAI,CAAA,CAAE,EAAE,CAAE,CAAA,GAAK,IAAI,CAAA,CAAE,EAAE,CAAE,CAAA,GAAK,IAAI,CAAA,CAAE,EAAE,CAAE,CAAA,GAAK,GAAA,CAAI,EAAE,EAAE,CAAE,CAAA,GAAK,GAAA,CAAI,EAAE,EAAE,CAAE,IAAK,GAAA,CAAI,CAAA,CAAE,EAAE,CAAE,CAAA;AAEzF;AAGO,SAAS,MAAA,GAAiB;AAC/B,EAAA,MAAM,CAAA,GAAI,SAAA,CAAU,IAAI,UAAA,CAAW,EAAE,CAAC,CAAA;AACtC,EAAA,CAAA,CAAE,CAAC,CAAA,GAAK,CAAA,CAAE,CAAC,IAAK,EAAA,GAAQ,EAAA;AACxB,EAAA,CAAA,CAAE,CAAC,CAAA,GAAK,CAAA,CAAE,CAAC,IAAK,EAAA,GAAQ,GAAA;AACxB,EAAA,OAAO,YAAY,CAAC,CAAA;AACtB;AAEA,IAAI,UAAA,GAAa,CAAA;AACjB,IAAI,SAAA,GAAY,CAAA;AAOT,SAAS,OAAO,GAAA,EAAsB;AAC3C,EAAA,MAAM,IAAA,GAAO,GAAA,IAAO,IAAA,CAAK,GAAA,EAAI;AAC7B,EAAA,IAAI,SAAS,UAAA,EAAY,SAAA,EAAA;AAAA,OACpB;AAAE,IAAA,UAAA,GAAa,IAAA;AAAM,IAAA,SAAA,GAAY,CAAA;AAAA,EAAG;AAEzC,EAAA,MAAM,CAAA,GAAI,SAAA,CAAU,IAAI,UAAA,CAAW,EAAE,CAAC,CAAA;AAEtC,EAAA,CAAA,CAAE,CAAC,CAAA,GAAK,IAAA,GAAO,CAAA,IAAK,EAAA,GAAM,GAAA;AAC1B,EAAA,CAAA,CAAE,CAAC,CAAA,GAAK,IAAA,GAAO,CAAA,IAAK,EAAA,GAAM,GAAA;AAC1B,EAAA,CAAA,CAAE,CAAC,CAAA,GAAK,IAAA,GAAO,CAAA,IAAK,EAAA,GAAM,GAAA;AAC1B,EAAA,CAAA,CAAE,CAAC,CAAA,GAAK,IAAA,GAAO,CAAA,IAAK,EAAA,GAAM,GAAA;AAC1B,EAAA,CAAA,CAAE,CAAC,CAAA,GAAK,IAAA,GAAO,CAAA,IAAK,CAAA,GAAK,GAAA;AACzB,EAAA,CAAA,CAAE,CAAC,IAAI,IAAA,GAAO,GAAA;AAEd,EAAA,CAAA,CAAE,CAAC,CAAA,GAAI,GAAA,GAAS,SAAA,IAAa,CAAA,GAAK,EAAA;AAClC,EAAA,CAAA,CAAE,CAAC,IAAI,SAAA,GAAY,GAAA;AACnB,EAAA,CAAA,CAAE,CAAC,CAAA,GAAK,CAAA,CAAE,CAAC,IAAK,EAAA,GAAQ,GAAA;AACxB,EAAA,OAAO,YAAY,CAAC,CAAA;AACtB;AAGO,SAAS,WAAW,IAAA,EAAsB;AAC/C,EAAA,MAAM,GAAA,GAAM,KAAK,OAAA,CAAQ,IAAA,EAAM,EAAE,CAAA,CAAE,KAAA,CAAM,GAAG,EAAE,CAAA;AAC9C,EAAA,OAAO,QAAA,CAAS,KAAK,EAAE,CAAA;AACzB;AAEA,IAAM,OAAA,GAAU,4EAAA;AAGT,SAAS,OAAO,CAAA,EAAoB;AACzC,EAAA,OAAO,OAAA,CAAQ,KAAK,CAAC,CAAA;AACvB;AAGO,SAAS,YAAY,CAAA,EAA0B;AACpD,EAAA,OAAO,MAAA,CAAO,CAAC,CAAA,GAAI,QAAA,CAAS,EAAE,EAAE,CAAA,EAAI,EAAE,CAAA,GAAI,IAAA;AAC5C;AAEA,IAAM,aAAA,GAAgB,kEAAA;AACtB,IAAM,YAAA,GAAe,kEAAA;AAErB,SAAS,kBAAA,CAAmB,MAAc,QAAA,EAA0B;AAClE,EAAA,MAAM,IAAA,GAAA,CAAQ,KAAM,EAAA,GAAK,IAAA,CAAK,MAAO,QAAA,CAAS,MAAA,GAAS,CAAA,GAAK,CAAC,CAAA,IAAM,CAAA;AACnE,EAAA,MAAM,OAAO,IAAA,CAAK,IAAA,CAAM,MAAM,IAAA,GAAO,IAAA,GAAQ,SAAS,MAAM,CAAA;AAC5D,EAAA,IAAIA,GAAAA,GAAK,EAAA;AACT,EAAA,OAAOA,GAAAA,CAAG,SAAS,IAAA,EAAM;AACvB,IAAA,MAAM,KAAA,GAAQ,SAAA,CAAU,IAAI,UAAA,CAAW,IAAI,CAAC,CAAA;AAC5C,IAAA,KAAA,IAAS,IAAI,CAAA,EAAG,CAAA,GAAI,QAAQA,GAAAA,CAAG,MAAA,GAAS,MAAM,CAAA,EAAA,EAAK;AACjD,MAAA,MAAM,GAAA,GAAM,KAAA,CAAM,CAAC,CAAA,GAAK,IAAA;AACxB,MAAA,IAAI,MAAM,QAAA,CAAS,MAAA,EAAQA,GAAAA,IAAM,SAAS,GAAG,CAAA;AAAA,IAC/C;AAAA,EACF;AACA,EAAA,OAAOA,GAAAA;AACT;AAGO,SAAS,MAAA,CAAO,OAAO,EAAA,EAAY;AACxC,EAAA,OAAO,kBAAA,CAAmB,MAAM,aAAa,CAAA;AAC/C;AAGO,SAAS,OAAA,CAAQ,OAAO,CAAA,EAAW;AACxC,EAAA,OAAO,kBAAA,CAAmB,MAAM,YAAY,CAAA;AAC9C;AAGO,SAAS,EAAA,CAAG,MAAA,EAAgB,IAAA,GAAO,EAAA,EAAY;AACpD,EAAA,OAAO,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,MAAA,CAAO,IAAI,CAAC,CAAA,CAAA;AAClC","file":"index.cjs","sourcesContent":["/**\n * @lacspace/id\n *\n * Unique IDs done right — UUID v4, **UUID v7** (time-sortable), Nano-ID-style\n * and short URL-safe codes. Cryptographically random (Web Crypto), monotonic\n * v7 within the same millisecond, zero-dependency and isomorphic.\n */\n\nfunction getRandom(bytes: Uint8Array): Uint8Array {\n  const c = (globalThis as { crypto?: Crypto }).crypto;\n  if (!c || typeof c.getRandomValues !== \"function\") {\n    throw new Error(\"Web Crypto getRandomValues is unavailable in this environment.\");\n  }\n  c.getRandomValues(bytes);\n  return bytes;\n}\n\nconst HEX: string[] = [];\nfor (let i = 0; i < 256; i++) HEX.push((i + 0x100).toString(16).slice(1));\n\nfunction bytesToUuid(b: Uint8Array): string {\n  return (\n    HEX[b[0]!]! + HEX[b[1]!]! + HEX[b[2]!]! + HEX[b[3]!]! + \"-\" +\n    HEX[b[4]!]! + HEX[b[5]!]! + \"-\" +\n    HEX[b[6]!]! + HEX[b[7]!]! + \"-\" +\n    HEX[b[8]!]! + HEX[b[9]!]! + \"-\" +\n    HEX[b[10]!]! + HEX[b[11]!]! + HEX[b[12]!]! + HEX[b[13]!]! + HEX[b[14]!]! + HEX[b[15]!]!\n  );\n}\n\n/** RFC 4122 UUID v4 (random). */\nexport function uuidv4(): string {\n  const b = getRandom(new Uint8Array(16));\n  b[6] = (b[6]! & 0x0f) | 0x40; // version 4\n  b[8] = (b[8]! & 0x3f) | 0x80; // variant\n  return bytesToUuid(b);\n}\n\nlet lastV7Time = 0;\nlet v7Counter = 0;\n\n/**\n * UUID v7 — a time-sortable UUID (48-bit Unix-ms timestamp + randomness).\n * Great as a primary key: lexicographically sortable by creation time, index-\n * friendly, still globally unique. Monotonic within the same millisecond.\n */\nexport function uuidv7(now?: number): string {\n  const time = now ?? Date.now();\n  if (time === lastV7Time) v7Counter++;\n  else { lastV7Time = time; v7Counter = 0; }\n\n  const b = getRandom(new Uint8Array(16));\n  // 48-bit timestamp (big-endian) in bytes 0..5\n  b[0] = (time / 2 ** 40) & 0xff;\n  b[1] = (time / 2 ** 32) & 0xff;\n  b[2] = (time / 2 ** 24) & 0xff;\n  b[3] = (time / 2 ** 16) & 0xff;\n  b[4] = (time / 2 ** 8) & 0xff;\n  b[5] = time & 0xff;\n  // rand_a (12 bits) holds a monotonic counter so same-ms ids stay sortable\n  b[6] = 0x70 | ((v7Counter >> 8) & 0x0f); // version 7 + counter high nibble\n  b[7] = v7Counter & 0xff;                  // counter low byte\n  b[8] = (b[8]! & 0x3f) | 0x80;             // variant\n  return bytesToUuid(b);\n}\n\n/** Extract the timestamp (ms) embedded in a UUID v7. */\nexport function uuidv7Time(uuid: string): number {\n  const hex = uuid.replace(/-/g, \"\").slice(0, 12);\n  return parseInt(hex, 16);\n}\n\nconst UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;\n\n/** Is this a well-formed UUID? */\nexport function isUuid(s: string): boolean {\n  return UUID_RE.test(s);\n}\n\n/** UUID version digit (1–8), or null if not a UUID. */\nexport function uuidVersion(s: string): number | null {\n  return isUuid(s) ? parseInt(s[14]!, 16) : null;\n}\n\nconst NANO_ALPHABET = \"useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict\";\nconst URL_ALPHABET = \"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_\";\n\nfunction randomFromAlphabet(size: number, alphabet: string): string {\n  const mask = (2 << (31 - Math.clz32((alphabet.length - 1) | 1))) - 1;\n  const step = Math.ceil((1.6 * mask * size) / alphabet.length);\n  let id = \"\";\n  while (id.length < size) {\n    const bytes = getRandom(new Uint8Array(step));\n    for (let i = 0; i < step && id.length < size; i++) {\n      const idx = bytes[i]! & mask;\n      if (idx < alphabet.length) id += alphabet[idx];\n    }\n  }\n  return id;\n}\n\n/** Nano-ID-style URL-safe id (default 21 chars). */\nexport function nanoid(size = 21): string {\n  return randomFromAlphabet(size, NANO_ALPHABET);\n}\n\n/** Short, URL-safe, human-shareable code (default 8 chars). */\nexport function shortId(size = 8): string {\n  return randomFromAlphabet(size, URL_ALPHABET);\n}\n\n/** A prefixed id, e.g. `id(\"user\")` → \"user_9f8c…\". Uses nanoid. */\nexport function id(prefix: string, size = 16): string {\n  return `${prefix}_${nanoid(size)}`;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,29 @@
+/**
+ * @lacspace/id
+ *
+ * Unique IDs done right — UUID v4, **UUID v7** (time-sortable), Nano-ID-style
+ * and short URL-safe codes. Cryptographically random (Web Crypto), monotonic
+ * v7 within the same millisecond, zero-dependency and isomorphic.
+ */
+/** RFC 4122 UUID v4 (random). */
+declare function uuidv4(): string;
+/**
+ * UUID v7 — a time-sortable UUID (48-bit Unix-ms timestamp + randomness).
+ * Great as a primary key: lexicographically sortable by creation time, index-
+ * friendly, still globally unique. Monotonic within the same millisecond.
+ */
+declare function uuidv7(now?: number): string;
+/** Extract the timestamp (ms) embedded in a UUID v7. */
+declare function uuidv7Time(uuid: string): number;
+/** Is this a well-formed UUID? */
+declare function isUuid(s: string): boolean;
+/** UUID version digit (1–8), or null if not a UUID. */
+declare function uuidVersion(s: string): number | null;
+/** Nano-ID-style URL-safe id (default 21 chars). */
+declare function nanoid(size?: number): string;
+/** Short, URL-safe, human-shareable code (default 8 chars). */
+declare function shortId(size?: number): string;
+/** A prefixed id, e.g. `id("user")` → "user_9f8c…". Uses nanoid. */
+declare function id(prefix: string, size?: number): string;
+
+export { id, isUuid, nanoid, shortId, uuidVersion, uuidv4, uuidv7, uuidv7Time };

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @lacspace/id
+ *
+ * Unique IDs done right — UUID v4, **UUID v7** (time-sortable), Nano-ID-style
+ * and short URL-safe codes. Cryptographically random (Web Crypto), monotonic
+ * v7 within the same millisecond, zero-dependency and isomorphic.
+ */
+/** RFC 4122 UUID v4 (random). */
+declare function uuidv4(): string;
+/**
+ * UUID v7 — a time-sortable UUID (48-bit Unix-ms timestamp + randomness).
+ * Great as a primary key: lexicographically sortable by creation time, index-
+ * friendly, still globally unique. Monotonic within the same millisecond.
+ */
+declare function uuidv7(now?: number): string;
+/** Extract the timestamp (ms) embedded in a UUID v7. */
+declare function uuidv7Time(uuid: string): number;
+/** Is this a well-formed UUID? */
+declare function isUuid(s: string): boolean;
+/** UUID version digit (1–8), or null if not a UUID. */
+declare function uuidVersion(s: string): number | null;
+/** Nano-ID-style URL-safe id (default 21 chars). */
+declare function nanoid(size?: number): string;
+/** Short, URL-safe, human-shareable code (default 8 chars). */
+declare function shortId(size?: number): string;
+/** A prefixed id, e.g. `id("user")` → "user_9f8c…". Uses nanoid. */
+declare function id(prefix: string, size?: number): string;
+
+export { id, isUuid, nanoid, shortId, uuidVersion, uuidv4, uuidv7, uuidv7Time };

package/dist/index.js

@@ -0,0 +1,80 @@
+// src/index.ts
+function getRandom(bytes) {
+  const c = globalThis.crypto;
+  if (!c || typeof c.getRandomValues !== "function") {
+    throw new Error("Web Crypto getRandomValues is unavailable in this environment.");
+  }
+  c.getRandomValues(bytes);
+  return bytes;
+}
+var HEX = [];
+for (let i = 0; i < 256; i++) HEX.push((i + 256).toString(16).slice(1));
+function bytesToUuid(b) {
+  return HEX[b[0]] + HEX[b[1]] + HEX[b[2]] + HEX[b[3]] + "-" + HEX[b[4]] + HEX[b[5]] + "-" + HEX[b[6]] + HEX[b[7]] + "-" + HEX[b[8]] + HEX[b[9]] + "-" + HEX[b[10]] + HEX[b[11]] + HEX[b[12]] + HEX[b[13]] + HEX[b[14]] + HEX[b[15]];
+}
+function uuidv4() {
+  const b = getRandom(new Uint8Array(16));
+  b[6] = b[6] & 15 | 64;
+  b[8] = b[8] & 63 | 128;
+  return bytesToUuid(b);
+}
+var lastV7Time = 0;
+var v7Counter = 0;
+function uuidv7(now) {
+  const time = now ?? Date.now();
+  if (time === lastV7Time) v7Counter++;
+  else {
+    lastV7Time = time;
+    v7Counter = 0;
+  }
+  const b = getRandom(new Uint8Array(16));
+  b[0] = time / 2 ** 40 & 255;
+  b[1] = time / 2 ** 32 & 255;
+  b[2] = time / 2 ** 24 & 255;
+  b[3] = time / 2 ** 16 & 255;
+  b[4] = time / 2 ** 8 & 255;
+  b[5] = time & 255;
+  b[6] = 112 | v7Counter >> 8 & 15;
+  b[7] = v7Counter & 255;
+  b[8] = b[8] & 63 | 128;
+  return bytesToUuid(b);
+}
+function uuidv7Time(uuid) {
+  const hex = uuid.replace(/-/g, "").slice(0, 12);
+  return parseInt(hex, 16);
+}
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function isUuid(s) {
+  return UUID_RE.test(s);
+}
+function uuidVersion(s) {
+  return isUuid(s) ? parseInt(s[14], 16) : null;
+}
+var NANO_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
+var URL_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_";
+function randomFromAlphabet(size, alphabet) {
+  const mask = (2 << 31 - Math.clz32(alphabet.length - 1 | 1)) - 1;
+  const step = Math.ceil(1.6 * mask * size / alphabet.length);
+  let id2 = "";
+  while (id2.length < size) {
+    const bytes = getRandom(new Uint8Array(step));
+    for (let i = 0; i < step && id2.length < size; i++) {
+      const idx = bytes[i] & mask;
+      if (idx < alphabet.length) id2 += alphabet[idx];
+    }
+  }
+  return id2;
+}
+function nanoid(size = 21) {
+  return randomFromAlphabet(size, NANO_ALPHABET);
+}
+function shortId(size = 8) {
+  return randomFromAlphabet(size, URL_ALPHABET);
+}
+function id(prefix, size = 16) {
+  return `${prefix}_${nanoid(size)}`;
+}
+
+export { id, isUuid, nanoid, shortId, uuidVersion, uuidv4, uuidv7, uuidv7Time };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["id"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @lacspace/id\n *\n * Unique IDs done right — UUID v4, **UUID v7** (time-sortable), Nano-ID-style\n * and short URL-safe codes. Cryptographically random (Web Crypto), monotonic\n * v7 within the same millisecond, zero-dependency and isomorphic.\n */\n\nfunction getRandom(bytes: Uint8Array): Uint8Array {\n  const c = (globalThis as { crypto?: Crypto }).crypto;\n  if (!c || typeof c.getRandomValues !== \"function\") {\n    throw new Error(\"Web Crypto getRandomValues is unavailable in this environment.\");\n  }\n  c.getRandomValues(bytes);\n  return bytes;\n}\n\nconst HEX: string[] = [];\nfor (let i = 0; i < 256; i++) HEX.push((i + 0x100).toString(16).slice(1));\n\nfunction bytesToUuid(b: Uint8Array): string {\n  return (\n    HEX[b[0]!]! + HEX[b[1]!]! + HEX[b[2]!]! + HEX[b[3]!]! + \"-\" +\n    HEX[b[4]!]! + HEX[b[5]!]! + \"-\" +\n    HEX[b[6]!]! + HEX[b[7]!]! + \"-\" +\n    HEX[b[8]!]! + HEX[b[9]!]! + \"-\" +\n    HEX[b[10]!]! + HEX[b[11]!]! + HEX[b[12]!]! + HEX[b[13]!]! + HEX[b[14]!]! + HEX[b[15]!]!\n  );\n}\n\n/** RFC 4122 UUID v4 (random). */\nexport function uuidv4(): string {\n  const b = getRandom(new Uint8Array(16));\n  b[6] = (b[6]! & 0x0f) | 0x40; // version 4\n  b[8] = (b[8]! & 0x3f) | 0x80; // variant\n  return bytesToUuid(b);\n}\n\nlet lastV7Time = 0;\nlet v7Counter = 0;\n\n/**\n * UUID v7 — a time-sortable UUID (48-bit Unix-ms timestamp + randomness).\n * Great as a primary key: lexicographically sortable by creation time, index-\n * friendly, still globally unique. Monotonic within the same millisecond.\n */\nexport function uuidv7(now?: number): string {\n  const time = now ?? Date.now();\n  if (time === lastV7Time) v7Counter++;\n  else { lastV7Time = time; v7Counter = 0; }\n\n  const b = getRandom(new Uint8Array(16));\n  // 48-bit timestamp (big-endian) in bytes 0..5\n  b[0] = (time / 2 ** 40) & 0xff;\n  b[1] = (time / 2 ** 32) & 0xff;\n  b[2] = (time / 2 ** 24) & 0xff;\n  b[3] = (time / 2 ** 16) & 0xff;\n  b[4] = (time / 2 ** 8) & 0xff;\n  b[5] = time & 0xff;\n  // rand_a (12 bits) holds a monotonic counter so same-ms ids stay sortable\n  b[6] = 0x70 | ((v7Counter >> 8) & 0x0f); // version 7 + counter high nibble\n  b[7] = v7Counter & 0xff;                  // counter low byte\n  b[8] = (b[8]! & 0x3f) | 0x80;             // variant\n  return bytesToUuid(b);\n}\n\n/** Extract the timestamp (ms) embedded in a UUID v7. */\nexport function uuidv7Time(uuid: string): number {\n  const hex = uuid.replace(/-/g, \"\").slice(0, 12);\n  return parseInt(hex, 16);\n}\n\nconst UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;\n\n/** Is this a well-formed UUID? */\nexport function isUuid(s: string): boolean {\n  return UUID_RE.test(s);\n}\n\n/** UUID version digit (1–8), or null if not a UUID. */\nexport function uuidVersion(s: string): number | null {\n  return isUuid(s) ? parseInt(s[14]!, 16) : null;\n}\n\nconst NANO_ALPHABET = \"useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict\";\nconst URL_ALPHABET = \"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_\";\n\nfunction randomFromAlphabet(size: number, alphabet: string): string {\n  const mask = (2 << (31 - Math.clz32((alphabet.length - 1) | 1))) - 1;\n  const step = Math.ceil((1.6 * mask * size) / alphabet.length);\n  let id = \"\";\n  while (id.length < size) {\n    const bytes = getRandom(new Uint8Array(step));\n    for (let i = 0; i < step && id.length < size; i++) {\n      const idx = bytes[i]! & mask;\n      if (idx < alphabet.length) id += alphabet[idx];\n    }\n  }\n  return id;\n}\n\n/** Nano-ID-style URL-safe id (default 21 chars). */\nexport function nanoid(size = 21): string {\n  return randomFromAlphabet(size, NANO_ALPHABET);\n}\n\n/** Short, URL-safe, human-shareable code (default 8 chars). */\nexport function shortId(size = 8): string {\n  return randomFromAlphabet(size, URL_ALPHABET);\n}\n\n/** A prefixed id, e.g. `id(\"user\")` → \"user_9f8c…\". Uses nanoid. */\nexport function id(prefix: string, size = 16): string {\n  return `${prefix}_${nanoid(size)}`;\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@lacspace/id",
+  "version": "1.0.0",
+  "description": "Unique IDs done right — UUID v4, time-sortable UUID v7, Nano-ID-style and short URL-safe codes. Cryptographically random (Web Crypto), zero-dependency, isomorphic.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "uuid",
+    "uuidv4",
+    "uuidv7",
+    "uuid-v7",
+    "nanoid",
+    "short-id",
+    "unique-id",
+    "id-generator",
+    "time-sortable",
+    "web-crypto",
+    "zero-dependency",
+    "isomorphic",
+    "typescript"
+  ],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://lacspace.com/packages",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacspace/npm-packages.git",
+    "directory": "id"
+  },
+  "bugs": {
+    "url": "https://github.com/lacspace/npm-packages/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}