sigilid 1.1.1 → 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
+- **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,10 +40,10 @@ one never pulls in the others.
 
 | Import               | Size   |
 | -------------------- | ------ |
-| `sigilid`            | ~234 B |
+| `sigilid`            | ~297 B |
 | `sigilid/non-secure` | ~214 B |
-| `sigilid/prefix`     | ~348 B |
-| `sigilid/typed`      | ~382 B |
+| `sigilid/prefix`     | ~385 B |
+| `sigilid/typed`      | ~398 B |
 | `sigilid/validate`   | ~360 B |
 | `sigilid/alphabet`   | ~380 B |
 
@@ -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,6 +402,7 @@ 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 |

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 e(r){if(!Number.isInteger(r)||r<1||r>255)throw new RangeError(`length must be 1\u2013255, got ${r}`)}var t="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";function n(r){return Array.from(crypto.getRandomValues(new Uint8Array(r)),o=>t[o&63]).join("")}function g(r=21){return e(r),n(r)}export{t as DEFAULT_ALPHABET,g 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/prefix.js

@@ -1 +1 @@
-function e(r){if(!Number.isInteger(r)||r<1||r>255)throw new RangeError(`length must be 1\u2013255, got ${r}`)}function n(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 i="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";function o(r){return Array.from(crypto.getRandomValues(new Uint8Array(r)),t=>i[t&63]).join("")}function p(r,t=21){return n(r),e(t),`${r}_${o(t)}`}function c(r,t=21){return n(r),e(t),()=>`${r}_${o(t)}`}export{c 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 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 s="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";function a(r){return Array.from(crypto.getRandomValues(new Uint8Array(r)),t=>s[t&63]).join("")}function p(r){return r}function m(r,t=21){return r!==void 0&&o(r),n(t),()=>{let e=a(t);return r!==void 0?`${r}_${e}`:e}}export{p as castId,m 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigilid",
-  "version": "1.1.1",
+  "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"
@@ -67,6 +71,10 @@
   ],
   "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",
@@ -77,7 +85,8 @@
     "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": [
     {
@@ -112,6 +121,8 @@
     }
   ],
   "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",