sigilid 1.1.0 → 1.2.0

package/README.md

@@ -24,10 +24,12 @@ const id = generateId(); // "K7gkJ_q3vR2nL8xH5eM0w"
 - **URL-safe by default** — 64-character alphabet: `A-Z a-z 0-9 _ -`
 - **Tree-shakeable** — subpath exports mean your bundle only includes what you import
 - **Zero runtime dependencies** — no third-party code in production output
-- **ESM-first with CJS compatibility** — works in modern Node, edge runtimes, and all major bundlers
+- **Optional Node native fast path** — `sigilid/native` for Node-only throughput tuning
+- **ESM-only** — works in modern Node, edge runtimes, and all major bundlers
 - **Strong TypeScript support** — strict types, branded ID types, precise inference
 - **Predictable behavior** — explicit errors on invalid input, no silent failures
-- **One package, six entrypoints** — `install sigilid`, then import only what you need
+- **One package, seven entrypoints** — `install sigilid`, then import only what you need
+- **Companion native addon package** — only needed when using `sigilid/native`
 
 ---
 
@@ -38,14 +40,14 @@ one never pulls in the others.
 
 | Import               | Size   |
 | -------------------- | ------ |
-| `sigilid`            | ~348 B |
-| `sigilid/non-secure` | ~222 B |
-| `sigilid/prefix`     | ~496 B |
-| `sigilid/typed`      | ~486 B |
-| `sigilid/validate`   | ~366 B |
-| `sigilid/alphabet`   | ~381 B |
+| `sigilid`            | ~297 B |
+| `sigilid/non-secure` | ~214 B |
+| `sigilid/prefix`     | ~385 B |
+| `sigilid/typed`      | ~398 B |
+| `sigilid/validate`   | ~360 B |
+| `sigilid/alphabet`   | ~380 B |
 
-Zero runtime dependencies. [Verified by size-limit on every PR.](link to workflow)
+Zero runtime dependencies. [Verified by size-limit on every PR.](.github/workflows/size-limit.yml)
 
 ---
 
@@ -65,6 +67,14 @@ yarn add sigilid
 
 Node 20+ required. Works in all modern runtimes that expose the Web Crypto API (`globalThis.crypto`).
 
+Optional native path:
+
+```bash
+npm install sigilid @sigilid/native-addon
+```
+
+Use `@sigilid/native-addon` only if you plan to import `sigilid/native`.
+
 ---
 
 ## Quick start
@@ -133,6 +143,30 @@ generateNonSecureId(8); // 8-character ID
 
 ---
 
+### `sigilid/native` — optional Node-only fast path
+
+```ts
+import { generateDefault, generateId } from "sigilid/native";
+
+generateDefault(); // 21-character secure ID
+generateDefault(32); // 32-character secure ID
+
+// Alias that mirrors the root naming
+generateId(21);
+```
+
+- Node-only entrypoint.
+- Requires the companion addon package: `@sigilid/native-addon`.
+- Uses secure randomness and the same default alphabet as `sigilid`.
+- Throws a clear error if the addon is missing or the runtime is unsupported.
+- Addon install tries prebuilt binaries first, then falls back to local `node-gyp` build.
+- Publishing note: `sigilid` and `@sigilid/native-addon` are versioned/published separately.
+
+If you want the broadest compatibility (browser, edge, and Node) stick to the root
+`sigilid` import.
+
+---
+
 ### `sigilid/prefix` — prefixed IDs
 
 ```ts
@@ -333,6 +367,34 @@ similar. The subpath ecosystem is where `sigilid` earns its place.
 If you are targeting an environment without Web Crypto, use `sigilid/non-secure`
 with the understanding that `Math.random` is not cryptographically safe.
 
+`sigilid/native` is a separate Node-only path. It depends on the companion addon
+package and is not intended for browsers or edge runtimes.
+
+---
+
+## Benchmarking
+
+For local performance checks, run:
+
+```bash
+npm ci
+npm run build
+npm run bench
+```
+
+Native vs JS benchmark:
+
+```bash
+npm run build:native-addon
+npm run bench:native
+```
+
+Build prebuilt binaries for publishing the addon:
+
+```bash
+npm run prebuild:native-addon
+```
+
 ---
 
 ## Package exports
@@ -340,13 +402,14 @@ with the understanding that `Math.random` is not cryptographically safe.
 | Import               | Entry file           | Description                        |
 | -------------------- | -------------------- | ---------------------------------- |
 | `sigilid`            | `dist/index.js`      | Secure root generator              |
+| `sigilid/native`     | `dist/native.js`     | Optional Node-only native fast path |
 | `sigilid/non-secure` | `dist/non-secure.js` | Math.random-based generator        |
 | `sigilid/prefix`     | `dist/prefix.js`     | Prefixed ID helpers                |
 | `sigilid/typed`      | `dist/typed.js`      | Branded types and typed generators |
 | `sigilid/validate`   | `dist/validate.js`   | Validation helpers                 |
 | `sigilid/alphabet`   | `dist/alphabet.js`   | Custom alphabet factory            |
 
-All exports are available as ESM (`.js`) and CommonJS (`.cjs`) with TypeScript declarations (`.d.ts`).
+All exports are ESM (`.js`) with TypeScript declarations (`.d.ts`). Node.js 20+ required.
 
 ---
 
@@ -363,8 +426,8 @@ decisions and constraints contributors should keep in mind.
 ## Release and versioning
 
 `sigilid` uses [Semantic Versioning](https://semver.org/). Breaking API changes
-will bump the major version. Releases are managed with
-[Changesets](https://github.com/changesets/changesets).
+will bump the major version. Releases are cut from GitHub — bump the version in
+`package.json`, tag the release, and the publish workflow handles the rest.
 
 ---
 

package/dist/alphabet.js

@@ -1 +1 @@
-function i(t){if(typeof t!="string")throw new TypeError("alphabet must be a string");if(t.length<2)throw new RangeError("alphabet must have at least 2 characters");if(t.length>256)throw new RangeError("alphabet must have at most 256 characters");if(new Set(t).size!==t.length)throw new TypeError("alphabet has duplicate characters")}function g(t,r,m){let o=t.length,e=1;for(;e<o;)e=e<<1|1;let c=Math.ceil(1.6*e*r/o),n="";for(;n.length<r;){let s=m(c);for(let a=0;a<s.length&&n.length<r;a++){let u=s[a]&e;u<o&&(n+=t[u]);}}return n}function h(t){if(!Number.isInteger(t)||t<1||t>255)throw new RangeError(`length must be 1\u2013255, got ${t}`)}function l(t){let r=new Uint8Array(t);return globalThis.crypto.getRandomValues(r),r}var p=21;function v(t){i(t);}function E(t){return i(t),{generate(r=p){return h(r),g(t,r,l)}}}export{E as createAlphabet,v as validateAlphabet};
+function a(t){if(typeof t!="string")throw new TypeError("alphabet must be a string");if(t.length<2)throw new RangeError("alphabet must have at least 2 characters");if(t.length>256)throw new RangeError("alphabet must have at most 256 characters");if(new Set(t).size!==t.length)throw new TypeError("alphabet has duplicate characters")}function g(t,r,c){let o=t.length,e=1;for(;e<o;)e=e<<1|1;let l=Math.ceil(1.6*e*r/o),n="";for(;n.length<r;){let s=c(l);for(let i=0;i<s.length&&n.length<r;i++){let u=s[i]&e;u<o&&(n+=t[u]);}}return n}function h(t){if(!Number.isInteger(t)||t<1||t>255)throw new RangeError(`length must be 1\u2013255, got ${t}`)}function m(t){let r=new Uint8Array(t);return crypto.getRandomValues(r),r}var p=21;function v(t){a(t);}function E(t){return a(t),{generate(r=p){return h(r),g(t,r,m)}}}export{E as createAlphabet,v as validateAlphabet};

package/dist/constants-CFnCjbhy.d.ts

@@ -0,0 +1,7 @@
+/**
+ * URL-safe alphabet used by default. 64 characters: A-Z, a-z, 0-9, _, -.
+ * Chosen to be safe in URLs, filenames, and most log formats without encoding.
+ */
+declare const DEFAULT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+
+export { DEFAULT_ALPHABET as D };

package/dist/index.d.ts

@@ -1,8 +1,4 @@
-/**
- * URL-safe alphabet used by default. 64 characters: A-Z, a-z, 0-9, _, -.
- * Chosen to be safe in URLs, filenames, and most log formats without encoding.
- */
-declare const DEFAULT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+export { D as DEFAULT_ALPHABET } from './constants-CFnCjbhy.js';
 
 /**
  * Generates a cryptographically secure random ID.
@@ -16,4 +12,4 @@ declare const DEFAULT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrst
  */
 declare function generateId(length?: number): string;
 
-export { DEFAULT_ALPHABET, generateId };
+export { generateId };

package/dist/index.js

@@ -1 +1 @@
-function m(t,r,p){let o=t.length,e=1;for(;e<o;)e=e<<1|1;let g=Math.ceil(1.6*e*r/o),n="";for(;n.length<r;){let i=p(g);for(let a=0;a<i.length&&n.length<r;a++){let s=i[a]&e;s<o&&(n+=t[s]);}}return n}function u(t){if(!Number.isInteger(t)||t<1||t>255)throw new RangeError(`length must be 1\u2013255, got ${t}`)}var h="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";function c(t){let r=new Uint8Array(t);return globalThis.crypto.getRandomValues(r),r}var f=21;function x(t=f){return u(t),m(h,t,c)}export{h as DEFAULT_ALPHABET,x as generateId};
+function s(t){if(!Number.isInteger(t)||t<1||t>255)throw new RangeError(`length must be 1\u2013255, got ${t}`)}var e="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";var n=1024,i=new Uint8Array(n),m=e,r=n;function a(t){r+t>n&&(crypto.getRandomValues(i),r=0);let o="",f=r+t;for(;r<f;)o+=m[i[r++]&63];return o}function w(t=21){return s(t),a(t)}export{e as DEFAULT_ALPHABET,w as generateId};

package/dist/native.d.ts

@@ -0,0 +1,6 @@
+export { D as DEFAULT_ALPHABET } from './constants-CFnCjbhy.js';
+
+declare function generateDefault(length?: number): string;
+declare function generateId(length?: number): string;
+
+export { generateDefault, generateId };

package/dist/native.js

@@ -0,0 +1 @@
+import {createRequire}from'module';function n(e){if(!Number.isInteger(e)||e<1||e>255)throw new RangeError(`length must be 1\u2013255, got ${e}`)}var a="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";var d=createRequire(import.meta.url),u="@sigilid/native-addon";function f(){return typeof process<"u"&&typeof process.versions?.node=="string"}function o(e=u){if(!f())throw new Error("sigilid/native is only supported in Node.js.");try{let t=d(e);if(typeof t.generateDefault!="function")throw new TypeError(`${e} does not export generateDefault(length).`);return t}catch(t){let i=`sigilid/native failed to load ${e}. Install it with "npm install ${e}" and ensure native builds are available.`,r=new Error(i);throw t instanceof Error&&Object.defineProperty(r,"cause",{value:t,enumerable:false,configurable:true,writable:true}),r}}var l=o();function p(e=21){return n(e),l.generateDefault(e)}function h(e=21){return p(e)}export{a as DEFAULT_ALPHABET,p as generateDefault,h as generateId};

package/dist/non-secure.js

@@ -1 +1 @@
-function o(t){if(!Number.isInteger(t)||t<1||t>255)throw new RangeError(`length must be 1\u2013255, got ${t}`)}var r="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";var i=21;function c(t=i){o(t);let e="",s=r.length;for(let n=0;n<t;n++)e+=r[Math.floor(Math.random()*s)];return e}export{c as generateNonSecureId};
+function n(r){if(!Number.isInteger(r)||r<1||r>255)throw new RangeError(`length must be 1\u2013255, got ${r}`)}var o="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";var i=21;function f(r=i){n(r);let t="";for(let e=0;e<r;e++)t+=o[Math.random()*64|0];return t}export{f as generateNonSecureId};

package/dist/prefix.js

@@ -1 +1 @@
-function a(t,r,e){let i=t.length,n=1;for(;n<i;)n=n<<1|1;let b=Math.ceil(1.6*n*r/i),o="";for(;o.length<r;){let h=e(b);for(let s=0;s<h.length&&o.length<r;s++){let f=h[s]&n;f<i&&(o+=t[f]);}}return o}function u(t){if(!Number.isInteger(t)||t<1||t>255)throw new RangeError(`length must be 1\u2013255, got ${t}`)}function c(t){if(typeof t!="string"||t.length===0)throw new TypeError("prefix must be a non-empty string");if(!/^[a-zA-Z][a-zA-Z0-9]*$/.test(t))throw new TypeError("prefix must start with a letter and contain only alphanumeric characters")}var m="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";function g(t){let r=new Uint8Array(t);return globalThis.crypto.getRandomValues(r),r}var p=21,l="_";function P(t,r=p){c(t),u(r);let e=a(m,r,g);return `${t}${l}${e}`}function $(t,r=p){return c(t),u(r),()=>{let e=a(m,r,g);return `${t}${l}${e}`}}export{$ as createPrefixedGenerator,P as generatePrefixedId};
+function n(r){if(!Number.isInteger(r)||r<1||r>255)throw new RangeError(`length must be 1\u2013255, got ${r}`)}function o(r){if(typeof r!="string"||r.length===0)throw new TypeError("prefix must be a non-empty string");if(!/^[a-z][a-z\d]*$/i.test(r))throw new TypeError("prefix must start with a letter and contain only alphanumeric characters")}var a="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";var s=1024,u=new Uint8Array(s),c=a,e=s;function i(r){e+r>s&&(crypto.getRandomValues(u),e=0);let t="",f=e+r;for(;e<f;)t+=c[u[e++]&63];return t}function x(r,t=21){return o(r),n(t),`${r}_${i(t)}`}function E(r,t=21){return o(r),n(t),()=>`${r}_${i(t)}`}export{E as createPrefixedGenerator,x as generatePrefixedId};

package/dist/typed.js

@@ -1 +1 @@
-function c(t,r,n){let o=t.length,e=1;for(;e<o;)e=e<<1|1;let h=Math.ceil(1.6*e*r/o),s="";for(;s.length<r;){let i=n(h);for(let a=0;a<i.length&&s.length<r;a++){let u=i[a]&e;u<o&&(s+=t[u]);}}return s}function f(t){if(!Number.isInteger(t)||t<1||t>255)throw new RangeError(`length must be 1\u2013255, got ${t}`)}function m(t){if(typeof t!="string"||t.length===0)throw new TypeError("prefix must be a non-empty string");if(!/^[a-zA-Z][a-zA-Z0-9]*$/.test(t))throw new TypeError("prefix must start with a letter and contain only alphanumeric characters")}var g="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";function d(t){let r=new Uint8Array(t);return globalThis.crypto.getRandomValues(r),r}var p=21,l="_";function B(t){return t}function I(t,r=p){return t!==void 0&&m(t),f(r),()=>{let n=c(g,r,d);return t!==void 0?`${t}${l}${n}`:n}}export{B as castId,I as createTypedGenerator};
+function s(t){if(!Number.isInteger(t)||t<1||t>255)throw new RangeError(`length must be 1\u2013255, got ${t}`)}function a(t){if(typeof t!="string"||t.length===0)throw new TypeError("prefix must be a non-empty string");if(!/^[a-z][a-z\d]*$/i.test(t))throw new TypeError("prefix must start with a letter and contain only alphanumeric characters")}var i="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";var o=1024,d=new Uint8Array(o),u=i,e=o;function f(t){e+t>o&&(crypto.getRandomValues(d),e=0);let r="",n=e+t;for(;e<n;)r+=u[d[e++]&63];return r}function l(t){return t}function w(t,r=21){return t!==void 0&&a(t),s(r),()=>{let n=f(r);return t!==void 0?`${t}_${n}`:n}}export{l as castId,w as createTypedGenerator};

package/dist/validate.js

@@ -1 +1 @@
-var r="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";function a(t,e={}){if(typeof t!="string"||t.length===0)return  false;if(e.alphabet!==void 0&&e.alphabet.length===0)throw new TypeError("ValidationOptions.alphabet must not be empty");let n=t;if(e.prefix!==void 0){let i=`${e.prefix}_`;if(!t.startsWith(i))return  false;n=t.slice(i.length);}if(e.length!==void 0&&n.length!==e.length||n.length===0)return  false;if(e.alphabet!==void 0){let i=new Set(e.alphabet);for(let o of n)if(!i.has(o))return  false}return  true}function l(t,e={}){let n={alphabet:r,...e};return a(t,n)}function s(t,e={}){if(!l(t,e)){let n=t.length>8?`${t.slice(0,8)}\u2026`:t;throw new TypeError(`Invalid ID: "${n}"`)}}function g(t,e={}){return s(t,e),t}export{s as assertValidId,l as isValidId,g as parseId};
+var r="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";function a(t,e={}){if(typeof t!="string"||t.length===0)return  false;if(e.alphabet!==void 0&&e.alphabet.length===0)throw new TypeError("alphabet option must not be empty");let n=t;if(e.prefix!==void 0){let i=`${e.prefix}_`;if(!t.startsWith(i))return  false;n=t.slice(i.length);}if(e.length!==void 0&&n.length!==e.length||n.length===0)return  false;if(e.alphabet!==void 0){let i=new Set(e.alphabet);for(let o of n)if(!i.has(o))return  false}return  true}function l(t,e={}){let n={alphabet:r,...e};return a(t,n)}function s(t,e={}){if(!l(t,e)){let n=t.length>8?`${t.slice(0,8)}\u2026`:t;throw new TypeError(`Invalid ID: "${n}"`)}}function g(t,e={}){return s(t,e),t}export{s as assertValidId,l as isValidId,g as parseId};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigilid",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A tiny, tree-shakeable ID toolkit for TypeScript apps. Secure core with optional subpath exports for prefixed IDs, typed IDs, validation, and custom alphabets.",
   "license": "MIT",
   "author": "moritzmyrz",
@@ -38,6 +38,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./native": {
+      "types": "./dist/native.d.ts",
+      "node": "./dist/native.js"
+    },
     "./non-secure": {
       "types": "./dist/non-secure.d.ts",
       "import": "./dist/non-secure.js"
@@ -60,9 +64,17 @@
     },
     "./package.json": "./package.json"
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsup",
+    "build:native-addon": "npm --prefix packages/native-addon run build",
+    "prebuild:native-addon": "npm --prefix packages/native-addon run prebuild",
+    "release:check": "npm run lint && npm run typecheck && npm run test && npm run build",
+    "release:pack": "npm pack && npm pack ./packages/native-addon",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -73,41 +85,44 @@
     "clean": "rm -rf dist *.tsbuildinfo",
     "verify": "npm run lint && npm run typecheck && npm run test && npm run build",
     "playground": "tsx tools/playground.ts",
-    "bench": "tsx tools/benchmark.ts"
+    "bench": "tsx tools/benchmark.ts",
+    "bench:native": "tsx tools/benchmark-native.ts"
   },
   "size-limit": [
     {
       "path": "dist/index.js",
       "brotli": true,
-      "limit": "350 B"
+      "limit": "265 B"
     },
     {
       "path": "dist/non-secure.js",
       "brotli": true,
-      "limit": "250 B"
+      "limit": "245 B"
     },
     {
       "path": "dist/prefix.js",
       "brotli": true,
-      "limit": "500 B"
+      "limit": "385 B"
     },
     {
       "path": "dist/typed.js",
       "brotli": true,
-      "limit": "500 B"
+      "limit": "420 B"
     },
     {
       "path": "dist/validate.js",
       "brotli": true,
-      "limit": "400 B"
+      "limit": "395 B"
     },
     {
       "path": "dist/alphabet.js",
       "brotli": true,
-      "limit": "400 B"
+      "limit": "415 B"
     }
   ],
   "devDependencies": {
+    "@sigilid/native-addon": "file:packages/native-addon",
+    "@types/node": "^24.5.2",
     "@biomejs/biome": "^1.9.4",
     "@size-limit/preset-small-lib": "^12.0.1",
     "@vitest/coverage-v8": "^3.0.7",