@monixlite/any-id 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @monixlite/any-id
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One function for every kind of identifier you actually use in a backend. Zero dependencies, built on Node's `crypto`, nothing is written to disk.
+
+## Install
+
+```
+npm install @monixlite/any-id
+```
+
+Node.js 16.9 or newer, CommonJS.
+
+## Types
+
+| Type | Length | Sortable by creation time | Notes |
+| --- | --- | --- | --- |
+| `mony` | 21 | yes | Base62, monotonic, checksummed. Default. |
+| `uuidv7` | 36 (32 without hyphens) | yes | RFC 9562 layout, monotonic. |
+| `ulid` | 26 | yes | Crockford Base32, monotonic. |
+| `objectid` | 24 | yes, to the second | MongoDB compatible. |
+| `id` | any | no | Random string over any alphabet. |
+
+Anything that has a timestamp can be read back with `AnyID.parse` and `AnyID.timestamp`.
+
+## Usage
+
+```js
+const AnyID = require("@monixlite/any-id");
+
+
+const user = AnyID.mony("usr");
+const order = AnyID.uuidv7({
+    hyphens: false,
+});
+const code = AnyID.id(6, AnyID.alphabet.numeric);
+const token = AnyID.id({
+    length: 32,
+    alphabet: AnyID.alphabet.hex,
+});
+```
+
+Every type is also a named export, so destructuring works:
+
+```js
+const { mony, uuidv7, ulid, objectID, id } = require("@monixlite/any-id");
+```
+
+### Options
+
+```js
+{
+    length: number,
+    alphabet: string,
+    prefix: string,
+    hyphens: boolean,
+    time: number | Date,
+}
+```
+
+| Option | Applies to | Description |
+| --- | --- | --- |
+| `length` | `id` | Output length. Default `16`. |
+| `alphabet` | `id` | 2 to 256 unique characters. Default Base62. |
+| `prefix` | all | Adds `prefix_` in front. Letters and digits, parts joined by `_`. |
+| `hyphens` | `uuidv7` | `false` removes the dashes. |
+| `time` | `mony`, `uuidv7`, `ulid`, `objectid` | `Date` or milliseconds. Use it for backfills and tests. |
+
+Shortcuts for the second argument: a number is `length`, a string is `prefix`, a boolean is `hyphens`, a `Date` is `time`.
+
+Invalid input never throws and never returns garbage. It returns `null`: an unknown type, a broken prefix, an alphabet with duplicates, a time outside the supported range.
+
+### Alphabets
+
+`AnyID.alphabet` ships `base62`, `crockford`, `url`, `numeric` and `hex`.
+
+```js
+AnyID.id(21, AnyID.alphabet.url);
+```
+
+`id` uses a bitmask with rejection sampling over random bytes, so every character is equally likely.
+
+### Custom generators
+
+```js
+const code = AnyID.custom(AnyID.alphabet.numeric, 6);
+
+code();
+code(8);
+```
+
+## mony
+
+`mony` is the type I wanted for primary keys: short, URL-safe, sortable, and hard to mistype.
+
+```
+44 bits   millisecond timestamp
+75 bits   random
+          = 119 bits, 20 Base62 characters
+ 1 char   check character (Luhn mod 62)
+```
+
+* **21 characters**, `0-9A-Za-z`, fixed width. Shorter than ULID (26) and UUID (36).
+* **Sorts as a string.** Base62 here follows ASCII order and the width is fixed, so `a < b` on plain strings matches creation order. Good for B-tree indexes, `ORDER BY id` and range scans.
+* **Monotonic inside a process.** Within one millisecond the random part grows by a random step instead of `+1`, so IDs stay strictly increasing without being guessable from the previous one. If the clock steps back, the last timestamp is kept and the sequence continues.
+* **75 random bits per millisecond.** Two processes generating in the same millisecond collide with probability around `n² / 2^76`. Ordering between processes is by millisecond.
+* **Self-checking.** The last character catches every single-character typo and most swapped neighbours. `validate` rejects about 98% of random 21-character Base62 strings before they reach your database.
+* **Good until the year 2527.**
+* **Case-sensitive.** Do not lowercase it.
+
+There is no persistence layer. State is a timestamp and a number in memory, nothing else. After a restart the 75 random bits cover you.
+
+## Parsing
+
+```js
+const AnyID = require("@monixlite/any-id");
+
+
+const user = AnyID.mony("usr");
+const info = AnyID.parse(user);
+const date = AnyID.timestamp(user);
+```
+
+`info` looks like this:
+
+```js
+{
+    id: "usr_5xnUsIPYET7dnFDP3m1fT",
+    prefix: "usr",
+    type: "mony",
+    time: 1793765681654,
+    random: "14f33840e078bda5e3f",
+    timestamp: 2026-11-04T04:14:41.654Z,
+}
+```
+
+`objectid` additionally returns `counter`. `parse` returns `null` for strings it cannot identify, including plain `id` values, since a random string says nothing about itself. Use `validate` for those.
+
+## Validation
+
+```js
+AnyID.validate(value);
+AnyID.validate(value, "mony");
+AnyID.validate(value, "mony", {
+    prefix: "usr",
+});
+AnyID.validate(value, "id", {
+    length: 10,
+    alphabet: AnyID.alphabet.url,
+});
+```
+
+* For `mony`, `uuidv7`, `ulid` and `objectid` it checks the real structure: alphabet, length, version and variant bits, checksum, value range.
+* For `id` it checks the alphabet and the length you pass in.
+* `prefix` set to a string requires exactly that prefix. Set to `null` it requires no prefix. Left out, any valid prefix is accepted.
+
+## Notes
+
+* `time` bypasses the monotonic state. IDs made with an explicit time are valid and parseable, but are not guaranteed to be ordered among themselves inside one millisecond.
+* `objectid` follows the MongoDB layout: 4 bytes of seconds, 5 random bytes per process, a 3-byte counter.
+* Generating is synchronous and takes a few microseconds per ID.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,39 @@
 {
-  "name": "@monixlite/any-id",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+    "name": "@monixlite/any-id",
+    "version": "1.0.0",
+    "description": "Zero-dependency ID generator for Node.js: Mony, UUIDv7, ULID, ObjectID and Custom-Alphabet IDs",
+    "main": "src/index.js",
+    "exports": {
+        ".": "./src/index.js",
+        "./package.json": "./package.json"
+    },
+    "type": "commonjs",
+    "files": [
+        "src",
+        "README.md"
+    ],
+    "engines": {
+        "node": ">=16.9.0"
+    },
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "id",
+        "uuidv7",
+        "ulid",
+        "objectid",
+        "mony",
+        "unique-id",
+        "sortable",
+        "time-ordered",
+        "k-sortable",
+        "monotonic",
+        "generator",
+        "crypto",
+        "monixlite"
+    ],
+    "author": "MonixLITE",
+    "license": "MIT"
 }

package/src/index.js

@@ -0,0 +1,378 @@
+const crypto = require("crypto");
+
+
+const additions = {}; {
+    additions.alphabet = {
+        base62: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
+        crockford: "0123456789ABCDEFGHJKMNPQRSTVWXYZ",
+        url: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_",
+        numeric: "0123456789",
+        hex: "0123456789abcdef",
+    };
+
+    additions.prefix = (/^[A-Za-z0-9]+(?:_[A-Za-z0-9]+)*$/);
+
+    additions.codec = {
+        encode: (num, length) => {
+            let out = "";
+
+            for (var i = 0; i < length; i++) {
+                out = (additions.alphabet.base62[Number(num % 62n)] + out);
+                num = (num / 62n);
+            };
+
+            return out;
+        },
+
+        decode: (value) => {
+            return value.split("").reduce((acc, char) => ((acc * 62n) + BigInt(additions.alphabet.base62.indexOf(char))), 0n);
+        },
+
+        checksum: (value) => {
+            let sum = 0;
+
+            for (var i = (value.length - 1); i >= 0; i--) {
+                const addend = (additions.alphabet.base62.indexOf(value[i]) * ((((value.length - 1 - i) % 2) == 0) ? 2 : 1));
+
+                sum += (Math.floor((addend / 62)) + (addend % 62));
+            };
+
+            return additions.alphabet.base62[((62 - (sum % 62)) % 62)];
+        },
+    };
+
+    additions.next = (entity, input) => {
+        const cap = (1n << BigInt(entity.size.random));
+        const limit = (2 ** entity.size.time);
+        const time = ((input instanceof Date) ? input.getTime() : ((typeof (input) == "number") ? Math.floor(input) : ((input == null) ? null : NaN)));
+        const entropy = (BigInt(`0x${crypto.randomBytes(Math.ceil((entity.size.random / 8))).toString("hex")}`) & (cap - 1n)); {
+            if (time != null) {
+                if (!Number.isFinite(time) || time < 0 || time >= limit) return null;
+
+                return {
+                    time: time,
+                    random: entropy,
+                };
+            };
+        };
+
+
+        const now = Date.now(); {
+            if (now > entity.time) {
+                entity.time = now;
+                entity.random = entropy;
+            } else {
+                entity.random += ((entropy & 0xffffffffn) + 1n);
+
+                if (entity.random >= cap) {
+                    entity.time += 1;
+                    entity.random = entropy;
+                };
+            };
+        };
+
+
+        if (entity.time >= limit) return null;
+
+        return {
+            time: entity.time,
+            random: entity.random,
+        };
+    };
+};
+
+const entities = {}; {
+    entities["id"] = {
+        generate: (opts) => {
+            const list = Array.from(opts?.alphabet ?? additions.alphabet.base62);
+            const length = (opts?.length ?? 16); {
+                if (list.length < 2 || list.length > 256 || new Set(list).size != list.length || !Number.isInteger(length) || length <= 0) return null;
+            };
+
+
+            const mask = ((2 << (31 - Math.clz32(((list.length - 1) | 1)))) - 1);
+            const out = [];
+
+            while (out.length < length) {
+                for (const byte of crypto.randomBytes((length * 2))) {
+                    if ((byte & mask) < list.length && out.length < length) out.push(list[(byte & mask)]);
+                };
+            };
+
+
+            return out.join("");
+        },
+
+        check: (value, opts) => {
+            const set = new Set(Array.from(opts?.alphabet ?? additions.alphabet.base62));
+            const list = Array.from(value);
+
+            return (list.length > 0 && (opts?.length == null || list.length == opts.length) && list.every((char) => set.has(char)));
+        },
+    };
+
+    entities["uuidv7"] = {
+        time: 0,
+        random: 0n,
+        size: { time: 48, random: 74 },
+
+        generate: (opts) => {
+            const current = additions.next(entities.uuidv7, opts?.time); {
+                if (!current) return null;
+            };
+
+
+            const hex = ((BigInt(current.time) << 80n) | (0x7n << 76n) | (((current.random >> 62n) & 0xfffn) << 64n) | (0x2n << 62n) | (current.random & 0x3fffffffffffffffn)).toString(16).padStart(32, "0"); {
+                if (opts?.hyphens == false) return hex;
+            };
+
+
+            return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+        },
+
+        parse: (body) => {
+            if (!(/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i).test(body) && !(/^[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$/i).test(body)) return null;
+
+
+            const num = BigInt(`0x${body.replace(/-/g, "")}`);
+
+            return {
+                time: Number(num >> 80n),
+                random: ((((num >> 64n) & 0xfffn) << 62n) | (num & 0x3fffffffffffffffn)).toString(16).padStart(19, "0"),
+            };
+        },
+    };
+
+    entities["ulid"] = {
+        time: 0,
+        random: 0n,
+        size: { time: 48, random: 80 },
+
+        generate: (opts) => {
+            const current = additions.next(entities.ulid, opts?.time); {
+                if (!current) return null;
+            };
+
+
+            let num = ((BigInt(current.time) << 80n) | current.random);
+            let out = ""; {
+                for (var i = 0; i < 26; i++) {
+                    out = (additions.alphabet.crockford[Number(num & 0x1fn)] + out);
+                    num = (num >> 5n);
+                };
+            };
+
+
+            return out;
+        },
+
+        parse: (body) => {
+            if (!(/^[0-7][0-9A-HJKMNP-TV-Z]{25}$/i).test(body)) return null;
+
+
+            const num = body.toUpperCase().split("").reduce((acc, char) => ((acc << 5n) | BigInt(additions.alphabet.crockford.indexOf(char))), 0n);
+
+            return {
+                time: Number(num >> 80n),
+                random: (num & ((1n << 80n) - 1n)).toString(16).padStart(20, "0"),
+            };
+        },
+    };
+
+    entities["objectid"] = {
+        counter: crypto.randomInt(0, 0x1000000),
+        process: crypto.randomBytes(5),
+
+        generate: (opts) => {
+            const seconds = Math.floor((((opts?.time instanceof Date) ? opts.time.getTime() : (opts?.time ?? Date.now())) / 1000)); {
+                if (!Number.isFinite(seconds) || seconds < 0 || seconds > 0xffffffff) return null;
+            };
+
+
+            entities.objectid.counter = ((entities.objectid.counter + 1) & 0xffffff);
+
+
+            const buf = Buffer.allocUnsafe(12); {
+                buf.writeUInt32BE(seconds, 0);
+                entities.objectid.process.copy(buf, 4, 0, 5);
+                buf.writeUIntBE(entities.objectid.counter, 9, 3);
+            };
+
+
+            return buf.toString("hex");
+        },
+
+        parse: (body) => {
+            if (!(/^[0-9a-f]{24}$/i).test(body)) return null;
+
+
+            return {
+                time: (parseInt(body.slice(0, 8), 16) * 1000),
+                random: body.slice(8, 18).toLowerCase(),
+                counter: parseInt(body.slice(18, 24), 16),
+            };
+        },
+    };
+
+    entities["mony"] = {
+        time: 0,
+        random: 0n,
+        size: { time: 44, random: 75 },
+
+        generate: (opts) => {
+            const current = additions.next(entities.mony, opts?.time); {
+                if (!current) return null;
+            };
+
+
+            const payload = additions.codec.encode(((BigInt(current.time) << 75n) | current.random), 20);
+
+            return (payload + additions.codec.checksum(payload));
+        },
+
+        parse: (body) => {
+            if (!(/^[0-9A-Za-z]{21}$/).test(body) || additions.codec.checksum(body.slice(0, 20)) != body[20]) return null;
+
+
+            const num = additions.codec.decode(body.slice(0, 20)); {
+                if (num >= (1n << 119n)) return null;
+            };
+
+
+            return {
+                time: Number(num >> 75n),
+                random: (num & ((1n << 75n) - 1n)).toString(16).padStart(19, "0"),
+            };
+        },
+    };
+};
+
+
+const AnyID = (type = "mony", options = {}) => {
+    let name = type;
+    let config = options; {
+        if (typeof (type) == "object" && type !== null) {
+            name = (type?.type ?? "mony");
+            config = type;
+        };
+    };
+
+
+    const key = String(name).toLowerCase();
+    const entity = (Object.hasOwn(entities, key) ? entities[key] : null); {
+        if (!entity) return null;
+    };
+
+
+    const parsed = ((typeof (config) == "object" && config !== null && !(config instanceof Date)) ? {
+        ...config,
+    } : {}); {
+        if (typeof (config) == "number") parsed.length = config;
+        if (typeof (config) == "string") parsed.prefix = config;
+        if (typeof (config) == "boolean") parsed.hyphens = config;
+        if (config instanceof Date) parsed.time = config;
+    };
+
+
+    if (parsed?.prefix != null && !additions.prefix.test(parsed.prefix)) return null;
+
+
+    const result = entity.generate(parsed); {
+        if (result == null) return null;
+        if (parsed?.prefix != null) return `${parsed.prefix}_${result}`;
+    };
+
+
+    return result;
+}; {
+    for (const type of ["uuidv7", "ulid", "objectid", "mony"]) {
+        AnyID[type] = (options = {}) => {
+            return AnyID(type, options);
+        };
+    };
+
+    AnyID.objectID = AnyID.objectid;
+    AnyID.objectId = AnyID.objectid;
+
+
+    AnyID.custom = (chars = additions.alphabet.base62, length = 16) => {
+        return (len = length) => {
+            return AnyID("id", {
+                length: len,
+                alphabet: chars,
+            });
+        };
+    };
+
+    AnyID.id = (options = 16, chars = null) => {
+        if (chars) return AnyID("id", {
+            length: (typeof (options) == "number" ? options : (options?.length ?? 16)),
+            alphabet: chars,
+        });
+
+
+        return AnyID("id", options);
+    };
+
+
+    AnyID.parse = (id, options = {}) => {
+        if (typeof (id) != "string" || id.length == 0) return null;
+
+
+        for (const body of (id.includes("_") ? [id, id.slice((id.lastIndexOf("_") + 1))] : [id])) {
+            const prefix = ((body == id) ? null : id.slice(0, (id.length - body.length - 1))); {
+                if (prefix != null && !additions.prefix.test(prefix)) continue;
+                if (options?.prefix !== undefined && options.prefix != prefix) continue;
+            };
+
+
+            for (const type of ["uuidv7", "objectid", "ulid", "mony"]) {
+                const item = entities[type].parse(body); {
+                    if (!item) continue;
+                };
+
+
+                return {
+                    id: id,
+                    prefix: prefix,
+                    type: type,
+                    ...item,
+                    timestamp: (new Date(item.time)),
+                };
+            };
+        };
+
+
+        return null;
+    };
+
+    AnyID.timestamp = (id, options = {}) => {
+        return (AnyID.parse(id, options)?.timestamp ?? null);
+    };
+
+    AnyID.validate = (id, type = null, options = {}) => {
+        if (typeof (id) != "string") return false;
+
+
+        const key = (type ? String(type).toLowerCase() : null); {
+            if (key == "id") {
+                const prefix = (options?.prefix ? `${options.prefix}_` : "");
+
+                return (id.startsWith(prefix) && (entities.id.check(id.slice(prefix.length), options) || (!options?.prefix && entities.id.check(id.slice((id.lastIndexOf("_") + 1)), options))));
+            };
+        };
+
+
+        const parsed = AnyID.parse(id, options);
+
+        return (!!parsed && (key == null || parsed.type == key));
+    };
+
+
+    AnyID.alphabet = additions.alphabet;
+
+    AnyID.AnyID = AnyID;
+    AnyID.anyID = AnyID;
+};
+
+module.exports = AnyID;