sigilid 0.1.0

package/dist/prefix.cjs

@@ -0,0 +1,72 @@
+'use strict';
+
+// src/internal/alphabet.ts
+function generateFromAlphabet(alphabet, length, getBytes) {
+  const alphabetSize = alphabet.length;
+  let mask = 1;
+  while (mask < alphabetSize) mask = mask << 1 | 1;
+  const bufferMultiplier = Math.ceil(1.6 * mask * length / alphabetSize);
+  let result = "";
+  while (result.length < length) {
+    const bytes = getBytes(bufferMultiplier);
+    for (let i = 0; i < bytes.length && result.length < length; i++) {
+      const byte = bytes[i] & mask;
+      if (byte < alphabetSize) {
+        result += alphabet[byte];
+      }
+    }
+  }
+  return result;
+}
+
+// src/internal/assert.ts
+var MIN_LENGTH = 1;
+var MAX_LENGTH = 255;
+function assertLength(length) {
+  if (!Number.isInteger(length) || length < MIN_LENGTH || length > MAX_LENGTH) {
+    throw new RangeError(
+      `ID length must be an integer between ${MIN_LENGTH} and ${MAX_LENGTH}, got ${length}`
+    );
+  }
+}
+function assertPrefix(prefix) {
+  if (typeof prefix !== "string" || prefix.length === 0) {
+    throw new TypeError("Prefix must be a non-empty string");
+  }
+  if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(prefix)) {
+    throw new TypeError("Prefix must start with a letter and contain only letters and digits");
+  }
+}
+
+// src/internal/random.ts
+function randomBytes(count) {
+  const bytes = new Uint8Array(count);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+// src/index.ts
+var DEFAULT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+
+// src/prefix.ts
+var DEFAULT_LENGTH = 21;
+var SEPARATOR = "_";
+function generatePrefixedId(prefix, length = DEFAULT_LENGTH) {
+  assertPrefix(prefix);
+  assertLength(length);
+  const id = generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);
+  return `${prefix}${SEPARATOR}${id}`;
+}
+function createPrefixedGenerator(prefix, length = DEFAULT_LENGTH) {
+  assertPrefix(prefix);
+  assertLength(length);
+  return () => {
+    const id = generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);
+    return `${prefix}${SEPARATOR}${id}`;
+  };
+}
+
+exports.createPrefixedGenerator = createPrefixedGenerator;
+exports.generatePrefixedId = generatePrefixedId;
+//# sourceMappingURL=prefix.cjs.map
+//# sourceMappingURL=prefix.cjs.map

package/dist/prefix.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/alphabet.ts","../src/internal/assert.ts","../src/internal/random.ts","../src/index.ts","../src/prefix.ts"],"names":[],"mappings":";;;AAiCO,SAAS,oBAAA,CACd,QAAA,EACA,MAAA,EACA,QAAA,EACQ;AACR,EAAA,MAAM,eAAe,QAAA,CAAS,MAAA;AAG9B,EAAA,IAAI,IAAA,GAAO,CAAA;AACX,EAAA,OAAO,IAAA,GAAO,YAAA,EAAc,IAAA,GAAQ,IAAA,IAAQ,CAAA,GAAK,CAAA;AAGjD,EAAA,MAAM,mBAAmB,IAAA,CAAK,IAAA,CAAM,GAAA,GAAM,IAAA,GAAO,SAAU,YAAY,CAAA;AACvE,EAAA,IAAI,MAAA,GAAS,EAAA;AAEb,EAAA,OAAO,MAAA,CAAO,SAAS,MAAA,EAAQ;AAC7B,IAAA,MAAM,KAAA,GAAQ,SAAS,gBAAgB,CAAA;AACvC,IAAA,KAAA,IAAS,CAAA,GAAI,GAAG,CAAA,GAAI,KAAA,CAAM,UAAU,MAAA,CAAO,MAAA,GAAS,QAAQ,CAAA,EAAA,EAAK;AAC/D,MAAA,MAAM,IAAA,GAAQ,KAAA,CAAM,CAAC,CAAA,GAAe,IAAA;AACpC,MAAA,IAAI,OAAO,YAAA,EAAc;AACvB,QAAA,MAAA,IAAU,SAAS,IAAI,CAAA;AAAA,MACzB;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT;;;AC3DA,IAAM,UAAA,GAAa,CAAA;AACnB,IAAM,UAAA,GAAa,GAAA;AAEZ,SAAS,aAAa,MAAA,EAAsB;AACjD,EAAA,IAAI,CAAC,OAAO,SAAA,CAAU,MAAM,KAAK,MAAA,GAAS,UAAA,IAAc,SAAS,UAAA,EAAY;AAC3E,IAAA,MAAM,IAAI,UAAA;AAAA,MACR,CAAA,qCAAA,EAAwC,UAAU,CAAA,KAAA,EAAQ,UAAU,SAAS,MAAM,CAAA;AAAA,KACrF;AAAA,EACF;AACF;AAEO,SAAS,aAAa,MAAA,EAAsB;AACjD,EAAA,IAAI,OAAO,MAAA,KAAW,QAAA,IAAY,MAAA,CAAO,WAAW,CAAA,EAAG;AACrD,IAAA,MAAM,IAAI,UAAU,mCAAmC,CAAA;AAAA,EACzD;AACA,EAAA,IAAI,CAAC,wBAAA,CAAyB,IAAA,CAAK,MAAM,CAAA,EAAG;AAC1C,IAAA,MAAM,IAAI,UAAU,qEAAqE,CAAA;AAAA,EAC3F;AACF;;;AChBO,SAAS,YAAY,KAAA,EAA2B;AACrD,EAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,KAAK,CAAA;AAClC,EAAA,MAAA,CAAO,gBAAgB,KAAK,CAAA;AAC5B,EAAA,OAAO,KAAA;AACT;;;ACEO,IAAM,gBAAA,GAAmB,kEAAA;;;ACHhC,IAAM,cAAA,GAAiB,EAAA;AACvB,IAAM,SAAA,GAAY,GAAA;AAeX,SAAS,kBAAA,CAAmB,MAAA,EAAgB,MAAA,GAAiB,cAAA,EAAwB;AAC1F,EAAA,YAAA,CAAa,MAAM,CAAA;AACnB,EAAA,YAAA,CAAa,MAAM,CAAA;AACnB,EAAA,MAAM,EAAA,GAAK,oBAAA,CAAqB,gBAAA,EAAkB,MAAA,EAAQ,WAAW,CAAA;AACrE,EAAA,OAAO,CAAA,EAAG,MAAM,CAAA,EAAG,SAAS,GAAG,EAAE,CAAA,CAAA;AACnC;AAkBO,SAAS,uBAAA,CACd,MAAA,EACA,MAAA,GAAiB,cAAA,EACH;AAEd,EAAA,YAAA,CAAa,MAAM,CAAA;AACnB,EAAA,YAAA,CAAa,MAAM,CAAA;AACnB,EAAA,OAAO,MAAM;AACX,IAAA,MAAM,EAAA,GAAK,oBAAA,CAAqB,gBAAA,EAAkB,MAAA,EAAQ,WAAW,CAAA;AACrE,IAAA,OAAO,CAAA,EAAG,MAAM,CAAA,EAAG,SAAS,GAAG,EAAE,CAAA,CAAA;AAAA,EACnC,CAAA;AACF","file":"prefix.cjs","sourcesContent":["const MIN_ALPHABET_SIZE = 2;\nconst MAX_ALPHABET_SIZE = 256;\n\nexport function validateAlphabetString(alphabet: string): void {\n  if (typeof alphabet !== \"string\") {\n    throw new TypeError(\"Alphabet must be a string\");\n  }\n  if (alphabet.length < MIN_ALPHABET_SIZE) {\n    throw new RangeError(\n      `Alphabet must have at least ${MIN_ALPHABET_SIZE} characters, got ${alphabet.length}`,\n    );\n  }\n  if (alphabet.length > MAX_ALPHABET_SIZE) {\n    throw new RangeError(\n      `Alphabet must have at most ${MAX_ALPHABET_SIZE} characters, got ${alphabet.length}`,\n    );\n  }\n  const seen = new Set<string>();\n  for (const char of alphabet) {\n    if (seen.has(char)) {\n      throw new TypeError(`Alphabet contains duplicate character: \"${char}\"`);\n    }\n    seen.add(char);\n  }\n}\n\n/**\n * Generates an ID of `length` characters drawn from `alphabet` using\n * rejection sampling to avoid modulo bias.\n *\n * The caller is responsible for providing valid `alphabet` and `length` values.\n * Use `validateAlphabetString` and `assertLength` before calling this.\n */\nexport function generateFromAlphabet(\n  alphabet: string,\n  length: number,\n  getBytes: (count: number) => Uint8Array,\n): string {\n  const alphabetSize = alphabet.length;\n\n  // Find the smallest bitmask >= alphabetSize to reduce rejection rate.\n  let mask = 1;\n  while (mask < alphabetSize) mask = (mask << 1) | 1;\n\n  // Overshoot buffer size to reduce round-trips. Most cases complete in one pass.\n  const bufferMultiplier = Math.ceil((1.6 * mask * length) / alphabetSize);\n  let result = \"\";\n\n  while (result.length < length) {\n    const bytes = getBytes(bufferMultiplier);\n    for (let i = 0; i < bytes.length && result.length < length; i++) {\n      const byte = (bytes[i] as number) & mask;\n      if (byte < alphabetSize) {\n        result += alphabet[byte];\n      }\n    }\n  }\n\n  return result;\n}\n","const MIN_LENGTH = 1;\nconst MAX_LENGTH = 255;\n\nexport function assertLength(length: number): void {\n  if (!Number.isInteger(length) || length < MIN_LENGTH || length > MAX_LENGTH) {\n    throw new RangeError(\n      `ID length must be an integer between ${MIN_LENGTH} and ${MAX_LENGTH}, got ${length}`,\n    );\n  }\n}\n\nexport function assertPrefix(prefix: string): void {\n  if (typeof prefix !== \"string\" || prefix.length === 0) {\n    throw new TypeError(\"Prefix must be a non-empty string\");\n  }\n  if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(prefix)) {\n    throw new TypeError(\"Prefix must start with a letter and contain only letters and digits\");\n  }\n}\n","// Returns a Uint8Array of `count` cryptographically secure random bytes.\n// Works in Node 18+, all modern browsers, and edge runtimes that expose `crypto`.\nexport function randomBytes(count: number): Uint8Array {\n  const bytes = new Uint8Array(count);\n  crypto.getRandomValues(bytes);\n  return bytes;\n}\n","import { generateFromAlphabet } from \"./internal/alphabet.js\";\nimport { assertLength } from \"./internal/assert.js\";\nimport { randomBytes } from \"./internal/random.js\";\n\n/**\n * URL-safe alphabet used by default. 64 characters: A-Z, a-z, 0-9, _, -.\n * Chosen to be safe in URLs, filenames, and most log formats without encoding.\n */\nexport const DEFAULT_ALPHABET = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-\";\n\nconst DEFAULT_LENGTH = 21;\n\n/**\n * Generates a cryptographically secure random ID.\n *\n * @param length - Number of characters (1–255). Defaults to 21.\n * @returns A random URL-safe string of the requested length.\n *\n * @example\n * import { generateId } from \"sigilid\";\n * const id = generateId(); // \"K7gkJ_q3vR2nL8xH5eM0w\"\n */\nexport function generateId(length: number = DEFAULT_LENGTH): string {\n  assertLength(length);\n  return generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);\n}\n","import { DEFAULT_ALPHABET } from \"./index.js\";\nimport { generateFromAlphabet } from \"./internal/alphabet.js\";\nimport { assertLength, assertPrefix } from \"./internal/assert.js\";\nimport { randomBytes } from \"./internal/random.js\";\n\nconst DEFAULT_LENGTH = 21;\nconst SEPARATOR = \"_\";\n\n/**\n * Generates a prefixed, cryptographically secure ID.\n *\n * The format is `{prefix}_{id}`, e.g. `usr_K7gkJ_q3vR2nL8xH5eM0w`.\n *\n * @param prefix - Alphanumeric prefix starting with a letter, e.g. `\"usr\"`.\n * @param length - Length of the random portion (1–255). Defaults to 21.\n * @returns A string in the form `{prefix}_{id}`.\n *\n * @example\n * import { generatePrefixedId } from \"sigilid/prefix\";\n * const userId = generatePrefixedId(\"usr\"); // \"usr_K7gkJ_q3vR2nL8xH5eM0w\"\n */\nexport function generatePrefixedId(prefix: string, length: number = DEFAULT_LENGTH): string {\n  assertPrefix(prefix);\n  assertLength(length);\n  const id = generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);\n  return `${prefix}${SEPARATOR}${id}`;\n}\n\n/**\n * Returns a factory function that generates prefixed IDs with fixed settings.\n *\n * Useful when you generate IDs for a specific entity type throughout your\n * codebase and want to avoid repeating the prefix at every call site.\n *\n * @param prefix - Alphanumeric prefix starting with a letter.\n * @param length - Length of the random portion. Defaults to 21.\n * @returns A zero-argument function that returns a new prefixed ID each call.\n *\n * @example\n * import { createPrefixedGenerator } from \"sigilid/prefix\";\n * const userId = createPrefixedGenerator(\"usr\");\n * userId(); // \"usr_K7gkJ_q3vR2nL8xH5eM0w\"\n * userId(); // \"usr_Xp9mN2qL5vR8nK3eJ7cHw\"\n */\nexport function createPrefixedGenerator(\n  prefix: string,\n  length: number = DEFAULT_LENGTH,\n): () => string {\n  // Validate eagerly so callers get errors at factory creation, not later.\n  assertPrefix(prefix);\n  assertLength(length);\n  return () => {\n    const id = generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);\n    return `${prefix}${SEPARATOR}${id}`;\n  };\n}\n"]}

package/dist/prefix.d.cts

@@ -0,0 +1,33 @@
+/**
+ * Generates a prefixed, cryptographically secure ID.
+ *
+ * The format is `{prefix}_{id}`, e.g. `usr_K7gkJ_q3vR2nL8xH5eM0w`.
+ *
+ * @param prefix - Alphanumeric prefix starting with a letter, e.g. `"usr"`.
+ * @param length - Length of the random portion (1–255). Defaults to 21.
+ * @returns A string in the form `{prefix}_{id}`.
+ *
+ * @example
+ * import { generatePrefixedId } from "sigilid/prefix";
+ * const userId = generatePrefixedId("usr"); // "usr_K7gkJ_q3vR2nL8xH5eM0w"
+ */
+declare function generatePrefixedId(prefix: string, length?: number): string;
+/**
+ * Returns a factory function that generates prefixed IDs with fixed settings.
+ *
+ * Useful when you generate IDs for a specific entity type throughout your
+ * codebase and want to avoid repeating the prefix at every call site.
+ *
+ * @param prefix - Alphanumeric prefix starting with a letter.
+ * @param length - Length of the random portion. Defaults to 21.
+ * @returns A zero-argument function that returns a new prefixed ID each call.
+ *
+ * @example
+ * import { createPrefixedGenerator } from "sigilid/prefix";
+ * const userId = createPrefixedGenerator("usr");
+ * userId(); // "usr_K7gkJ_q3vR2nL8xH5eM0w"
+ * userId(); // "usr_Xp9mN2qL5vR8nK3eJ7cHw"
+ */
+declare function createPrefixedGenerator(prefix: string, length?: number): () => string;
+
+export { createPrefixedGenerator, generatePrefixedId };

package/dist/prefix.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Generates a prefixed, cryptographically secure ID.
+ *
+ * The format is `{prefix}_{id}`, e.g. `usr_K7gkJ_q3vR2nL8xH5eM0w`.
+ *
+ * @param prefix - Alphanumeric prefix starting with a letter, e.g. `"usr"`.
+ * @param length - Length of the random portion (1–255). Defaults to 21.
+ * @returns A string in the form `{prefix}_{id}`.
+ *
+ * @example
+ * import { generatePrefixedId } from "sigilid/prefix";
+ * const userId = generatePrefixedId("usr"); // "usr_K7gkJ_q3vR2nL8xH5eM0w"
+ */
+declare function generatePrefixedId(prefix: string, length?: number): string;
+/**
+ * Returns a factory function that generates prefixed IDs with fixed settings.
+ *
+ * Useful when you generate IDs for a specific entity type throughout your
+ * codebase and want to avoid repeating the prefix at every call site.
+ *
+ * @param prefix - Alphanumeric prefix starting with a letter.
+ * @param length - Length of the random portion. Defaults to 21.
+ * @returns A zero-argument function that returns a new prefixed ID each call.
+ *
+ * @example
+ * import { createPrefixedGenerator } from "sigilid/prefix";
+ * const userId = createPrefixedGenerator("usr");
+ * userId(); // "usr_K7gkJ_q3vR2nL8xH5eM0w"
+ * userId(); // "usr_Xp9mN2qL5vR8nK3eJ7cHw"
+ */
+declare function createPrefixedGenerator(prefix: string, length?: number): () => string;
+
+export { createPrefixedGenerator, generatePrefixedId };

package/dist/prefix.js

@@ -0,0 +1,69 @@
+// src/internal/alphabet.ts
+function generateFromAlphabet(alphabet, length, getBytes) {
+  const alphabetSize = alphabet.length;
+  let mask = 1;
+  while (mask < alphabetSize) mask = mask << 1 | 1;
+  const bufferMultiplier = Math.ceil(1.6 * mask * length / alphabetSize);
+  let result = "";
+  while (result.length < length) {
+    const bytes = getBytes(bufferMultiplier);
+    for (let i = 0; i < bytes.length && result.length < length; i++) {
+      const byte = bytes[i] & mask;
+      if (byte < alphabetSize) {
+        result += alphabet[byte];
+      }
+    }
+  }
+  return result;
+}
+
+// src/internal/assert.ts
+var MIN_LENGTH = 1;
+var MAX_LENGTH = 255;
+function assertLength(length) {
+  if (!Number.isInteger(length) || length < MIN_LENGTH || length > MAX_LENGTH) {
+    throw new RangeError(
+      `ID length must be an integer between ${MIN_LENGTH} and ${MAX_LENGTH}, got ${length}`
+    );
+  }
+}
+function assertPrefix(prefix) {
+  if (typeof prefix !== "string" || prefix.length === 0) {
+    throw new TypeError("Prefix must be a non-empty string");
+  }
+  if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(prefix)) {
+    throw new TypeError("Prefix must start with a letter and contain only letters and digits");
+  }
+}
+
+// src/internal/random.ts
+function randomBytes(count) {
+  const bytes = new Uint8Array(count);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+// src/index.ts
+var DEFAULT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+
+// src/prefix.ts
+var DEFAULT_LENGTH = 21;
+var SEPARATOR = "_";
+function generatePrefixedId(prefix, length = DEFAULT_LENGTH) {
+  assertPrefix(prefix);
+  assertLength(length);
+  const id = generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);
+  return `${prefix}${SEPARATOR}${id}`;
+}
+function createPrefixedGenerator(prefix, length = DEFAULT_LENGTH) {
+  assertPrefix(prefix);
+  assertLength(length);
+  return () => {
+    const id = generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);
+    return `${prefix}${SEPARATOR}${id}`;
+  };
+}
+
+export { createPrefixedGenerator, generatePrefixedId };
+//# sourceMappingURL=prefix.js.map
+//# sourceMappingURL=prefix.js.map

package/dist/prefix.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/alphabet.ts","../src/internal/assert.ts","../src/internal/random.ts","../src/index.ts","../src/prefix.ts"],"names":[],"mappings":";AAiCO,SAAS,oBAAA,CACd,QAAA,EACA,MAAA,EACA,QAAA,EACQ;AACR,EAAA,MAAM,eAAe,QAAA,CAAS,MAAA;AAG9B,EAAA,IAAI,IAAA,GAAO,CAAA;AACX,EAAA,OAAO,IAAA,GAAO,YAAA,EAAc,IAAA,GAAQ,IAAA,IAAQ,CAAA,GAAK,CAAA;AAGjD,EAAA,MAAM,mBAAmB,IAAA,CAAK,IAAA,CAAM,GAAA,GAAM,IAAA,GAAO,SAAU,YAAY,CAAA;AACvE,EAAA,IAAI,MAAA,GAAS,EAAA;AAEb,EAAA,OAAO,MAAA,CAAO,SAAS,MAAA,EAAQ;AAC7B,IAAA,MAAM,KAAA,GAAQ,SAAS,gBAAgB,CAAA;AACvC,IAAA,KAAA,IAAS,CAAA,GAAI,GAAG,CAAA,GAAI,KAAA,CAAM,UAAU,MAAA,CAAO,MAAA,GAAS,QAAQ,CAAA,EAAA,EAAK;AAC/D,MAAA,MAAM,IAAA,GAAQ,KAAA,CAAM,CAAC,CAAA,GAAe,IAAA;AACpC,MAAA,IAAI,OAAO,YAAA,EAAc;AACvB,QAAA,MAAA,IAAU,SAAS,IAAI,CAAA;AAAA,MACzB;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT;;;AC3DA,IAAM,UAAA,GAAa,CAAA;AACnB,IAAM,UAAA,GAAa,GAAA;AAEZ,SAAS,aAAa,MAAA,EAAsB;AACjD,EAAA,IAAI,CAAC,OAAO,SAAA,CAAU,MAAM,KAAK,MAAA,GAAS,UAAA,IAAc,SAAS,UAAA,EAAY;AAC3E,IAAA,MAAM,IAAI,UAAA;AAAA,MACR,CAAA,qCAAA,EAAwC,UAAU,CAAA,KAAA,EAAQ,UAAU,SAAS,MAAM,CAAA;AAAA,KACrF;AAAA,EACF;AACF;AAEO,SAAS,aAAa,MAAA,EAAsB;AACjD,EAAA,IAAI,OAAO,MAAA,KAAW,QAAA,IAAY,MAAA,CAAO,WAAW,CAAA,EAAG;AACrD,IAAA,MAAM,IAAI,UAAU,mCAAmC,CAAA;AAAA,EACzD;AACA,EAAA,IAAI,CAAC,wBAAA,CAAyB,IAAA,CAAK,MAAM,CAAA,EAAG;AAC1C,IAAA,MAAM,IAAI,UAAU,qEAAqE,CAAA;AAAA,EAC3F;AACF;;;AChBO,SAAS,YAAY,KAAA,EAA2B;AACrD,EAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,KAAK,CAAA;AAClC,EAAA,MAAA,CAAO,gBAAgB,KAAK,CAAA;AAC5B,EAAA,OAAO,KAAA;AACT;;;ACEO,IAAM,gBAAA,GAAmB,kEAAA;;;ACHhC,IAAM,cAAA,GAAiB,EAAA;AACvB,IAAM,SAAA,GAAY,GAAA;AAeX,SAAS,kBAAA,CAAmB,MAAA,EAAgB,MAAA,GAAiB,cAAA,EAAwB;AAC1F,EAAA,YAAA,CAAa,MAAM,CAAA;AACnB,EAAA,YAAA,CAAa,MAAM,CAAA;AACnB,EAAA,MAAM,EAAA,GAAK,oBAAA,CAAqB,gBAAA,EAAkB,MAAA,EAAQ,WAAW,CAAA;AACrE,EAAA,OAAO,CAAA,EAAG,MAAM,CAAA,EAAG,SAAS,GAAG,EAAE,CAAA,CAAA;AACnC;AAkBO,SAAS,uBAAA,CACd,MAAA,EACA,MAAA,GAAiB,cAAA,EACH;AAEd,EAAA,YAAA,CAAa,MAAM,CAAA;AACnB,EAAA,YAAA,CAAa,MAAM,CAAA;AACnB,EAAA,OAAO,MAAM;AACX,IAAA,MAAM,EAAA,GAAK,oBAAA,CAAqB,gBAAA,EAAkB,MAAA,EAAQ,WAAW,CAAA;AACrE,IAAA,OAAO,CAAA,EAAG,MAAM,CAAA,EAAG,SAAS,GAAG,EAAE,CAAA,CAAA;AAAA,EACnC,CAAA;AACF","file":"prefix.js","sourcesContent":["const MIN_ALPHABET_SIZE = 2;\nconst MAX_ALPHABET_SIZE = 256;\n\nexport function validateAlphabetString(alphabet: string): void {\n  if (typeof alphabet !== \"string\") {\n    throw new TypeError(\"Alphabet must be a string\");\n  }\n  if (alphabet.length < MIN_ALPHABET_SIZE) {\n    throw new RangeError(\n      `Alphabet must have at least ${MIN_ALPHABET_SIZE} characters, got ${alphabet.length}`,\n    );\n  }\n  if (alphabet.length > MAX_ALPHABET_SIZE) {\n    throw new RangeError(\n      `Alphabet must have at most ${MAX_ALPHABET_SIZE} characters, got ${alphabet.length}`,\n    );\n  }\n  const seen = new Set<string>();\n  for (const char of alphabet) {\n    if (seen.has(char)) {\n      throw new TypeError(`Alphabet contains duplicate character: \"${char}\"`);\n    }\n    seen.add(char);\n  }\n}\n\n/**\n * Generates an ID of `length` characters drawn from `alphabet` using\n * rejection sampling to avoid modulo bias.\n *\n * The caller is responsible for providing valid `alphabet` and `length` values.\n * Use `validateAlphabetString` and `assertLength` before calling this.\n */\nexport function generateFromAlphabet(\n  alphabet: string,\n  length: number,\n  getBytes: (count: number) => Uint8Array,\n): string {\n  const alphabetSize = alphabet.length;\n\n  // Find the smallest bitmask >= alphabetSize to reduce rejection rate.\n  let mask = 1;\n  while (mask < alphabetSize) mask = (mask << 1) | 1;\n\n  // Overshoot buffer size to reduce round-trips. Most cases complete in one pass.\n  const bufferMultiplier = Math.ceil((1.6 * mask * length) / alphabetSize);\n  let result = \"\";\n\n  while (result.length < length) {\n    const bytes = getBytes(bufferMultiplier);\n    for (let i = 0; i < bytes.length && result.length < length; i++) {\n      const byte = (bytes[i] as number) & mask;\n      if (byte < alphabetSize) {\n        result += alphabet[byte];\n      }\n    }\n  }\n\n  return result;\n}\n","const MIN_LENGTH = 1;\nconst MAX_LENGTH = 255;\n\nexport function assertLength(length: number): void {\n  if (!Number.isInteger(length) || length < MIN_LENGTH || length > MAX_LENGTH) {\n    throw new RangeError(\n      `ID length must be an integer between ${MIN_LENGTH} and ${MAX_LENGTH}, got ${length}`,\n    );\n  }\n}\n\nexport function assertPrefix(prefix: string): void {\n  if (typeof prefix !== \"string\" || prefix.length === 0) {\n    throw new TypeError(\"Prefix must be a non-empty string\");\n  }\n  if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(prefix)) {\n    throw new TypeError(\"Prefix must start with a letter and contain only letters and digits\");\n  }\n}\n","// Returns a Uint8Array of `count` cryptographically secure random bytes.\n// Works in Node 18+, all modern browsers, and edge runtimes that expose `crypto`.\nexport function randomBytes(count: number): Uint8Array {\n  const bytes = new Uint8Array(count);\n  crypto.getRandomValues(bytes);\n  return bytes;\n}\n","import { generateFromAlphabet } from \"./internal/alphabet.js\";\nimport { assertLength } from \"./internal/assert.js\";\nimport { randomBytes } from \"./internal/random.js\";\n\n/**\n * URL-safe alphabet used by default. 64 characters: A-Z, a-z, 0-9, _, -.\n * Chosen to be safe in URLs, filenames, and most log formats without encoding.\n */\nexport const DEFAULT_ALPHABET = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-\";\n\nconst DEFAULT_LENGTH = 21;\n\n/**\n * Generates a cryptographically secure random ID.\n *\n * @param length - Number of characters (1–255). Defaults to 21.\n * @returns A random URL-safe string of the requested length.\n *\n * @example\n * import { generateId } from \"sigilid\";\n * const id = generateId(); // \"K7gkJ_q3vR2nL8xH5eM0w\"\n */\nexport function generateId(length: number = DEFAULT_LENGTH): string {\n  assertLength(length);\n  return generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);\n}\n","import { DEFAULT_ALPHABET } from \"./index.js\";\nimport { generateFromAlphabet } from \"./internal/alphabet.js\";\nimport { assertLength, assertPrefix } from \"./internal/assert.js\";\nimport { randomBytes } from \"./internal/random.js\";\n\nconst DEFAULT_LENGTH = 21;\nconst SEPARATOR = \"_\";\n\n/**\n * Generates a prefixed, cryptographically secure ID.\n *\n * The format is `{prefix}_{id}`, e.g. `usr_K7gkJ_q3vR2nL8xH5eM0w`.\n *\n * @param prefix - Alphanumeric prefix starting with a letter, e.g. `\"usr\"`.\n * @param length - Length of the random portion (1–255). Defaults to 21.\n * @returns A string in the form `{prefix}_{id}`.\n *\n * @example\n * import { generatePrefixedId } from \"sigilid/prefix\";\n * const userId = generatePrefixedId(\"usr\"); // \"usr_K7gkJ_q3vR2nL8xH5eM0w\"\n */\nexport function generatePrefixedId(prefix: string, length: number = DEFAULT_LENGTH): string {\n  assertPrefix(prefix);\n  assertLength(length);\n  const id = generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);\n  return `${prefix}${SEPARATOR}${id}`;\n}\n\n/**\n * Returns a factory function that generates prefixed IDs with fixed settings.\n *\n * Useful when you generate IDs for a specific entity type throughout your\n * codebase and want to avoid repeating the prefix at every call site.\n *\n * @param prefix - Alphanumeric prefix starting with a letter.\n * @param length - Length of the random portion. Defaults to 21.\n * @returns A zero-argument function that returns a new prefixed ID each call.\n *\n * @example\n * import { createPrefixedGenerator } from \"sigilid/prefix\";\n * const userId = createPrefixedGenerator(\"usr\");\n * userId(); // \"usr_K7gkJ_q3vR2nL8xH5eM0w\"\n * userId(); // \"usr_Xp9mN2qL5vR8nK3eJ7cHw\"\n */\nexport function createPrefixedGenerator(\n  prefix: string,\n  length: number = DEFAULT_LENGTH,\n): () => string {\n  // Validate eagerly so callers get errors at factory creation, not later.\n  assertPrefix(prefix);\n  assertLength(length);\n  return () => {\n    const id = generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);\n    return `${prefix}${SEPARATOR}${id}`;\n  };\n}\n"]}

package/dist/typed.cjs

@@ -0,0 +1,70 @@
+'use strict';
+
+// src/internal/alphabet.ts
+function generateFromAlphabet(alphabet, length, getBytes) {
+  const alphabetSize = alphabet.length;
+  let mask = 1;
+  while (mask < alphabetSize) mask = mask << 1 | 1;
+  const bufferMultiplier = Math.ceil(1.6 * mask * length / alphabetSize);
+  let result = "";
+  while (result.length < length) {
+    const bytes = getBytes(bufferMultiplier);
+    for (let i = 0; i < bytes.length && result.length < length; i++) {
+      const byte = bytes[i] & mask;
+      if (byte < alphabetSize) {
+        result += alphabet[byte];
+      }
+    }
+  }
+  return result;
+}
+
+// src/internal/assert.ts
+var MIN_LENGTH = 1;
+var MAX_LENGTH = 255;
+function assertLength(length) {
+  if (!Number.isInteger(length) || length < MIN_LENGTH || length > MAX_LENGTH) {
+    throw new RangeError(
+      `ID length must be an integer between ${MIN_LENGTH} and ${MAX_LENGTH}, got ${length}`
+    );
+  }
+}
+function assertPrefix(prefix) {
+  if (typeof prefix !== "string" || prefix.length === 0) {
+    throw new TypeError("Prefix must be a non-empty string");
+  }
+  if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(prefix)) {
+    throw new TypeError("Prefix must start with a letter and contain only letters and digits");
+  }
+}
+
+// src/internal/random.ts
+function randomBytes(count) {
+  const bytes = new Uint8Array(count);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+// src/index.ts
+var DEFAULT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+
+// src/typed.ts
+var DEFAULT_LENGTH = 21;
+var SEPARATOR = "_";
+function castId(value) {
+  return value;
+}
+function createTypedGenerator(prefix, length = DEFAULT_LENGTH) {
+  if (prefix !== void 0) assertPrefix(prefix);
+  assertLength(length);
+  return () => {
+    const raw = generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);
+    const value = prefix !== void 0 ? `${prefix}${SEPARATOR}${raw}` : raw;
+    return value;
+  };
+}
+
+exports.castId = castId;
+exports.createTypedGenerator = createTypedGenerator;
+//# sourceMappingURL=typed.cjs.map
+//# sourceMappingURL=typed.cjs.map

package/dist/typed.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/alphabet.ts","../src/internal/assert.ts","../src/internal/random.ts","../src/index.ts","../src/typed.ts"],"names":[],"mappings":";;;AAiCO,SAAS,oBAAA,CACd,QAAA,EACA,MAAA,EACA,QAAA,EACQ;AACR,EAAA,MAAM,eAAe,QAAA,CAAS,MAAA;AAG9B,EAAA,IAAI,IAAA,GAAO,CAAA;AACX,EAAA,OAAO,IAAA,GAAO,YAAA,EAAc,IAAA,GAAQ,IAAA,IAAQ,CAAA,GAAK,CAAA;AAGjD,EAAA,MAAM,mBAAmB,IAAA,CAAK,IAAA,CAAM,GAAA,GAAM,IAAA,GAAO,SAAU,YAAY,CAAA;AACvE,EAAA,IAAI,MAAA,GAAS,EAAA;AAEb,EAAA,OAAO,MAAA,CAAO,SAAS,MAAA,EAAQ;AAC7B,IAAA,MAAM,KAAA,GAAQ,SAAS,gBAAgB,CAAA;AACvC,IAAA,KAAA,IAAS,CAAA,GAAI,GAAG,CAAA,GAAI,KAAA,CAAM,UAAU,MAAA,CAAO,MAAA,GAAS,QAAQ,CAAA,EAAA,EAAK;AAC/D,MAAA,MAAM,IAAA,GAAQ,KAAA,CAAM,CAAC,CAAA,GAAe,IAAA;AACpC,MAAA,IAAI,OAAO,YAAA,EAAc;AACvB,QAAA,MAAA,IAAU,SAAS,IAAI,CAAA;AAAA,MACzB;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT;;;AC3DA,IAAM,UAAA,GAAa,CAAA;AACnB,IAAM,UAAA,GAAa,GAAA;AAEZ,SAAS,aAAa,MAAA,EAAsB;AACjD,EAAA,IAAI,CAAC,OAAO,SAAA,CAAU,MAAM,KAAK,MAAA,GAAS,UAAA,IAAc,SAAS,UAAA,EAAY;AAC3E,IAAA,MAAM,IAAI,UAAA;AAAA,MACR,CAAA,qCAAA,EAAwC,UAAU,CAAA,KAAA,EAAQ,UAAU,SAAS,MAAM,CAAA;AAAA,KACrF;AAAA,EACF;AACF;AAEO,SAAS,aAAa,MAAA,EAAsB;AACjD,EAAA,IAAI,OAAO,MAAA,KAAW,QAAA,IAAY,MAAA,CAAO,WAAW,CAAA,EAAG;AACrD,IAAA,MAAM,IAAI,UAAU,mCAAmC,CAAA;AAAA,EACzD;AACA,EAAA,IAAI,CAAC,wBAAA,CAAyB,IAAA,CAAK,MAAM,CAAA,EAAG;AAC1C,IAAA,MAAM,IAAI,UAAU,qEAAqE,CAAA;AAAA,EAC3F;AACF;;;AChBO,SAAS,YAAY,KAAA,EAA2B;AACrD,EAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,KAAK,CAAA;AAClC,EAAA,MAAA,CAAO,gBAAgB,KAAK,CAAA;AAC5B,EAAA,OAAO,KAAA;AACT;;;ACEO,IAAM,gBAAA,GAAmB,kEAAA;;;ACHhC,IAAM,cAAA,GAAiB,EAAA;AACvB,IAAM,SAAA,GAAY,GAAA;AA+BX,SAAS,OAAyB,KAAA,EAAwB;AAC/D,EAAA,OAAO,KAAA;AACT;AAmBO,SAAS,oBAAA,CACd,MAAA,EACA,MAAA,GAAiB,cAAA,EACF;AACf,EAAA,IAAI,MAAA,KAAW,MAAA,EAAW,YAAA,CAAa,MAAM,CAAA;AAC7C,EAAA,YAAA,CAAa,MAAM,CAAA;AAEnB,EAAA,OAAO,MAAe;AACpB,IAAA,MAAM,GAAA,GAAM,oBAAA,CAAqB,gBAAA,EAAkB,MAAA,EAAQ,WAAW,CAAA;AACtE,IAAA,MAAM,KAAA,GAAQ,WAAW,MAAA,GAAY,CAAA,EAAG,MAAM,CAAA,EAAG,SAAS,CAAA,EAAG,GAAG,CAAA,CAAA,GAAK,GAAA;AACrE,IAAA,OAAO,KAAA;AAAA,EACT,CAAA;AACF","file":"typed.cjs","sourcesContent":["const MIN_ALPHABET_SIZE = 2;\nconst MAX_ALPHABET_SIZE = 256;\n\nexport function validateAlphabetString(alphabet: string): void {\n  if (typeof alphabet !== \"string\") {\n    throw new TypeError(\"Alphabet must be a string\");\n  }\n  if (alphabet.length < MIN_ALPHABET_SIZE) {\n    throw new RangeError(\n      `Alphabet must have at least ${MIN_ALPHABET_SIZE} characters, got ${alphabet.length}`,\n    );\n  }\n  if (alphabet.length > MAX_ALPHABET_SIZE) {\n    throw new RangeError(\n      `Alphabet must have at most ${MAX_ALPHABET_SIZE} characters, got ${alphabet.length}`,\n    );\n  }\n  const seen = new Set<string>();\n  for (const char of alphabet) {\n    if (seen.has(char)) {\n      throw new TypeError(`Alphabet contains duplicate character: \"${char}\"`);\n    }\n    seen.add(char);\n  }\n}\n\n/**\n * Generates an ID of `length` characters drawn from `alphabet` using\n * rejection sampling to avoid modulo bias.\n *\n * The caller is responsible for providing valid `alphabet` and `length` values.\n * Use `validateAlphabetString` and `assertLength` before calling this.\n */\nexport function generateFromAlphabet(\n  alphabet: string,\n  length: number,\n  getBytes: (count: number) => Uint8Array,\n): string {\n  const alphabetSize = alphabet.length;\n\n  // Find the smallest bitmask >= alphabetSize to reduce rejection rate.\n  let mask = 1;\n  while (mask < alphabetSize) mask = (mask << 1) | 1;\n\n  // Overshoot buffer size to reduce round-trips. Most cases complete in one pass.\n  const bufferMultiplier = Math.ceil((1.6 * mask * length) / alphabetSize);\n  let result = \"\";\n\n  while (result.length < length) {\n    const bytes = getBytes(bufferMultiplier);\n    for (let i = 0; i < bytes.length && result.length < length; i++) {\n      const byte = (bytes[i] as number) & mask;\n      if (byte < alphabetSize) {\n        result += alphabet[byte];\n      }\n    }\n  }\n\n  return result;\n}\n","const MIN_LENGTH = 1;\nconst MAX_LENGTH = 255;\n\nexport function assertLength(length: number): void {\n  if (!Number.isInteger(length) || length < MIN_LENGTH || length > MAX_LENGTH) {\n    throw new RangeError(\n      `ID length must be an integer between ${MIN_LENGTH} and ${MAX_LENGTH}, got ${length}`,\n    );\n  }\n}\n\nexport function assertPrefix(prefix: string): void {\n  if (typeof prefix !== \"string\" || prefix.length === 0) {\n    throw new TypeError(\"Prefix must be a non-empty string\");\n  }\n  if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(prefix)) {\n    throw new TypeError(\"Prefix must start with a letter and contain only letters and digits\");\n  }\n}\n","// Returns a Uint8Array of `count` cryptographically secure random bytes.\n// Works in Node 18+, all modern browsers, and edge runtimes that expose `crypto`.\nexport function randomBytes(count: number): Uint8Array {\n  const bytes = new Uint8Array(count);\n  crypto.getRandomValues(bytes);\n  return bytes;\n}\n","import { generateFromAlphabet } from \"./internal/alphabet.js\";\nimport { assertLength } from \"./internal/assert.js\";\nimport { randomBytes } from \"./internal/random.js\";\n\n/**\n * URL-safe alphabet used by default. 64 characters: A-Z, a-z, 0-9, _, -.\n * Chosen to be safe in URLs, filenames, and most log formats without encoding.\n */\nexport const DEFAULT_ALPHABET = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-\";\n\nconst DEFAULT_LENGTH = 21;\n\n/**\n * Generates a cryptographically secure random ID.\n *\n * @param length - Number of characters (1–255). Defaults to 21.\n * @returns A random URL-safe string of the requested length.\n *\n * @example\n * import { generateId } from \"sigilid\";\n * const id = generateId(); // \"K7gkJ_q3vR2nL8xH5eM0w\"\n */\nexport function generateId(length: number = DEFAULT_LENGTH): string {\n  assertLength(length);\n  return generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);\n}\n","import { DEFAULT_ALPHABET } from \"./index.js\";\nimport { generateFromAlphabet } from \"./internal/alphabet.js\";\nimport { assertLength, assertPrefix } from \"./internal/assert.js\";\nimport { randomBytes } from \"./internal/random.js\";\n\nconst DEFAULT_LENGTH = 21;\nconst SEPARATOR = \"_\";\n\n/**\n * A nominal type brand. Attach this to a string type to create a distinct\n * branded string that is not assignable from plain `string`.\n *\n * @example\n * type UserId = Brand<string, \"UserId\">;\n */\nexport type Brand<T, B> = T & { readonly __brand: B };\n\n/**\n * A branded string type for an entity named `T`.\n * Equivalent to `Brand<string, T>`, but more ergonomic for ID types.\n *\n * @example\n * type UserId = IdOf<\"User\">;\n * type PostId = IdOf<\"Post\">;\n */\nexport type IdOf<T extends string> = Brand<string, T>;\n\n/**\n * Casts a plain string to a branded `IdOf<T>`.\n *\n * This is a type-only operation at runtime — no validation is performed.\n * Use `assertValidId` from `\"sigilid/validate\"` first if you need runtime safety.\n *\n * @example\n * import { castId } from \"sigilid/typed\";\n * const id = castId<\"User\">(\"usr_abc123\");\n */\nexport function castId<T extends string>(value: string): IdOf<T> {\n  return value as IdOf<T>;\n}\n\n/**\n * Returns a factory function that generates cryptographically secure branded IDs.\n *\n * The type parameter `T` sets the brand. If a prefix is provided, the format\n * is `{prefix}_{id}`, otherwise it is a plain random string.\n *\n * Validation happens at factory creation, not per-call.\n *\n * @param prefix - Optional alphanumeric prefix.\n * @param length - Length of the random portion (1–255). Defaults to 21.\n * @returns A zero-argument function returning `IdOf<T>`.\n *\n * @example\n * import { createTypedGenerator } from \"sigilid/typed\";\n * const userId = createTypedGenerator<\"User\">(\"usr\");\n * const id = userId(); // IdOf<\"User\"> = \"usr_K7gkJ_q3vR2nL8xH5eM0w\"\n */\nexport function createTypedGenerator<T extends string>(\n  prefix?: string,\n  length: number = DEFAULT_LENGTH,\n): () => IdOf<T> {\n  if (prefix !== undefined) assertPrefix(prefix);\n  assertLength(length);\n\n  return (): IdOf<T> => {\n    const raw = generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);\n    const value = prefix !== undefined ? `${prefix}${SEPARATOR}${raw}` : raw;\n    return value as IdOf<T>;\n  };\n}\n"]}

package/dist/typed.d.cts

@@ -0,0 +1,50 @@
+/**
+ * A nominal type brand. Attach this to a string type to create a distinct
+ * branded string that is not assignable from plain `string`.
+ *
+ * @example
+ * type UserId = Brand<string, "UserId">;
+ */
+type Brand<T, B> = T & {
+    readonly __brand: B;
+};
+/**
+ * A branded string type for an entity named `T`.
+ * Equivalent to `Brand<string, T>`, but more ergonomic for ID types.
+ *
+ * @example
+ * type UserId = IdOf<"User">;
+ * type PostId = IdOf<"Post">;
+ */
+type IdOf<T extends string> = Brand<string, T>;
+/**
+ * Casts a plain string to a branded `IdOf<T>`.
+ *
+ * This is a type-only operation at runtime — no validation is performed.
+ * Use `assertValidId` from `"sigilid/validate"` first if you need runtime safety.
+ *
+ * @example
+ * import { castId } from "sigilid/typed";
+ * const id = castId<"User">("usr_abc123");
+ */
+declare function castId<T extends string>(value: string): IdOf<T>;
+/**
+ * Returns a factory function that generates cryptographically secure branded IDs.
+ *
+ * The type parameter `T` sets the brand. If a prefix is provided, the format
+ * is `{prefix}_{id}`, otherwise it is a plain random string.
+ *
+ * Validation happens at factory creation, not per-call.
+ *
+ * @param prefix - Optional alphanumeric prefix.
+ * @param length - Length of the random portion (1–255). Defaults to 21.
+ * @returns A zero-argument function returning `IdOf<T>`.
+ *
+ * @example
+ * import { createTypedGenerator } from "sigilid/typed";
+ * const userId = createTypedGenerator<"User">("usr");
+ * const id = userId(); // IdOf<"User"> = "usr_K7gkJ_q3vR2nL8xH5eM0w"
+ */
+declare function createTypedGenerator<T extends string>(prefix?: string, length?: number): () => IdOf<T>;
+
+export { type Brand, type IdOf, castId, createTypedGenerator };

package/dist/typed.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A nominal type brand. Attach this to a string type to create a distinct
+ * branded string that is not assignable from plain `string`.
+ *
+ * @example
+ * type UserId = Brand<string, "UserId">;
+ */
+type Brand<T, B> = T & {
+    readonly __brand: B;
+};
+/**
+ * A branded string type for an entity named `T`.
+ * Equivalent to `Brand<string, T>`, but more ergonomic for ID types.
+ *
+ * @example
+ * type UserId = IdOf<"User">;
+ * type PostId = IdOf<"Post">;
+ */
+type IdOf<T extends string> = Brand<string, T>;
+/**
+ * Casts a plain string to a branded `IdOf<T>`.
+ *
+ * This is a type-only operation at runtime — no validation is performed.
+ * Use `assertValidId` from `"sigilid/validate"` first if you need runtime safety.
+ *
+ * @example
+ * import { castId } from "sigilid/typed";
+ * const id = castId<"User">("usr_abc123");
+ */
+declare function castId<T extends string>(value: string): IdOf<T>;
+/**
+ * Returns a factory function that generates cryptographically secure branded IDs.
+ *
+ * The type parameter `T` sets the brand. If a prefix is provided, the format
+ * is `{prefix}_{id}`, otherwise it is a plain random string.
+ *
+ * Validation happens at factory creation, not per-call.
+ *
+ * @param prefix - Optional alphanumeric prefix.
+ * @param length - Length of the random portion (1–255). Defaults to 21.
+ * @returns A zero-argument function returning `IdOf<T>`.
+ *
+ * @example
+ * import { createTypedGenerator } from "sigilid/typed";
+ * const userId = createTypedGenerator<"User">("usr");
+ * const id = userId(); // IdOf<"User"> = "usr_K7gkJ_q3vR2nL8xH5eM0w"
+ */
+declare function createTypedGenerator<T extends string>(prefix?: string, length?: number): () => IdOf<T>;
+
+export { type Brand, type IdOf, castId, createTypedGenerator };

package/dist/typed.js

@@ -0,0 +1,67 @@
+// src/internal/alphabet.ts
+function generateFromAlphabet(alphabet, length, getBytes) {
+  const alphabetSize = alphabet.length;
+  let mask = 1;
+  while (mask < alphabetSize) mask = mask << 1 | 1;
+  const bufferMultiplier = Math.ceil(1.6 * mask * length / alphabetSize);
+  let result = "";
+  while (result.length < length) {
+    const bytes = getBytes(bufferMultiplier);
+    for (let i = 0; i < bytes.length && result.length < length; i++) {
+      const byte = bytes[i] & mask;
+      if (byte < alphabetSize) {
+        result += alphabet[byte];
+      }
+    }
+  }
+  return result;
+}
+
+// src/internal/assert.ts
+var MIN_LENGTH = 1;
+var MAX_LENGTH = 255;
+function assertLength(length) {
+  if (!Number.isInteger(length) || length < MIN_LENGTH || length > MAX_LENGTH) {
+    throw new RangeError(
+      `ID length must be an integer between ${MIN_LENGTH} and ${MAX_LENGTH}, got ${length}`
+    );
+  }
+}
+function assertPrefix(prefix) {
+  if (typeof prefix !== "string" || prefix.length === 0) {
+    throw new TypeError("Prefix must be a non-empty string");
+  }
+  if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(prefix)) {
+    throw new TypeError("Prefix must start with a letter and contain only letters and digits");
+  }
+}
+
+// src/internal/random.ts
+function randomBytes(count) {
+  const bytes = new Uint8Array(count);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+// src/index.ts
+var DEFAULT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+
+// src/typed.ts
+var DEFAULT_LENGTH = 21;
+var SEPARATOR = "_";
+function castId(value) {
+  return value;
+}
+function createTypedGenerator(prefix, length = DEFAULT_LENGTH) {
+  if (prefix !== void 0) assertPrefix(prefix);
+  assertLength(length);
+  return () => {
+    const raw = generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);
+    const value = prefix !== void 0 ? `${prefix}${SEPARATOR}${raw}` : raw;
+    return value;
+  };
+}
+
+export { castId, createTypedGenerator };
+//# sourceMappingURL=typed.js.map
+//# sourceMappingURL=typed.js.map

package/dist/typed.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/alphabet.ts","../src/internal/assert.ts","../src/internal/random.ts","../src/index.ts","../src/typed.ts"],"names":[],"mappings":";AAiCO,SAAS,oBAAA,CACd,QAAA,EACA,MAAA,EACA,QAAA,EACQ;AACR,EAAA,MAAM,eAAe,QAAA,CAAS,MAAA;AAG9B,EAAA,IAAI,IAAA,GAAO,CAAA;AACX,EAAA,OAAO,IAAA,GAAO,YAAA,EAAc,IAAA,GAAQ,IAAA,IAAQ,CAAA,GAAK,CAAA;AAGjD,EAAA,MAAM,mBAAmB,IAAA,CAAK,IAAA,CAAM,GAAA,GAAM,IAAA,GAAO,SAAU,YAAY,CAAA;AACvE,EAAA,IAAI,MAAA,GAAS,EAAA;AAEb,EAAA,OAAO,MAAA,CAAO,SAAS,MAAA,EAAQ;AAC7B,IAAA,MAAM,KAAA,GAAQ,SAAS,gBAAgB,CAAA;AACvC,IAAA,KAAA,IAAS,CAAA,GAAI,GAAG,CAAA,GAAI,KAAA,CAAM,UAAU,MAAA,CAAO,MAAA,GAAS,QAAQ,CAAA,EAAA,EAAK;AAC/D,MAAA,MAAM,IAAA,GAAQ,KAAA,CAAM,CAAC,CAAA,GAAe,IAAA;AACpC,MAAA,IAAI,OAAO,YAAA,EAAc;AACvB,QAAA,MAAA,IAAU,SAAS,IAAI,CAAA;AAAA,MACzB;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT;;;AC3DA,IAAM,UAAA,GAAa,CAAA;AACnB,IAAM,UAAA,GAAa,GAAA;AAEZ,SAAS,aAAa,MAAA,EAAsB;AACjD,EAAA,IAAI,CAAC,OAAO,SAAA,CAAU,MAAM,KAAK,MAAA,GAAS,UAAA,IAAc,SAAS,UAAA,EAAY;AAC3E,IAAA,MAAM,IAAI,UAAA;AAAA,MACR,CAAA,qCAAA,EAAwC,UAAU,CAAA,KAAA,EAAQ,UAAU,SAAS,MAAM,CAAA;AAAA,KACrF;AAAA,EACF;AACF;AAEO,SAAS,aAAa,MAAA,EAAsB;AACjD,EAAA,IAAI,OAAO,MAAA,KAAW,QAAA,IAAY,MAAA,CAAO,WAAW,CAAA,EAAG;AACrD,IAAA,MAAM,IAAI,UAAU,mCAAmC,CAAA;AAAA,EACzD;AACA,EAAA,IAAI,CAAC,wBAAA,CAAyB,IAAA,CAAK,MAAM,CAAA,EAAG;AAC1C,IAAA,MAAM,IAAI,UAAU,qEAAqE,CAAA;AAAA,EAC3F;AACF;;;AChBO,SAAS,YAAY,KAAA,EAA2B;AACrD,EAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,KAAK,CAAA;AAClC,EAAA,MAAA,CAAO,gBAAgB,KAAK,CAAA;AAC5B,EAAA,OAAO,KAAA;AACT;;;ACEO,IAAM,gBAAA,GAAmB,kEAAA;;;ACHhC,IAAM,cAAA,GAAiB,EAAA;AACvB,IAAM,SAAA,GAAY,GAAA;AA+BX,SAAS,OAAyB,KAAA,EAAwB;AAC/D,EAAA,OAAO,KAAA;AACT;AAmBO,SAAS,oBAAA,CACd,MAAA,EACA,MAAA,GAAiB,cAAA,EACF;AACf,EAAA,IAAI,MAAA,KAAW,MAAA,EAAW,YAAA,CAAa,MAAM,CAAA;AAC7C,EAAA,YAAA,CAAa,MAAM,CAAA;AAEnB,EAAA,OAAO,MAAe;AACpB,IAAA,MAAM,GAAA,GAAM,oBAAA,CAAqB,gBAAA,EAAkB,MAAA,EAAQ,WAAW,CAAA;AACtE,IAAA,MAAM,KAAA,GAAQ,WAAW,MAAA,GAAY,CAAA,EAAG,MAAM,CAAA,EAAG,SAAS,CAAA,EAAG,GAAG,CAAA,CAAA,GAAK,GAAA;AACrE,IAAA,OAAO,KAAA;AAAA,EACT,CAAA;AACF","file":"typed.js","sourcesContent":["const MIN_ALPHABET_SIZE = 2;\nconst MAX_ALPHABET_SIZE = 256;\n\nexport function validateAlphabetString(alphabet: string): void {\n  if (typeof alphabet !== \"string\") {\n    throw new TypeError(\"Alphabet must be a string\");\n  }\n  if (alphabet.length < MIN_ALPHABET_SIZE) {\n    throw new RangeError(\n      `Alphabet must have at least ${MIN_ALPHABET_SIZE} characters, got ${alphabet.length}`,\n    );\n  }\n  if (alphabet.length > MAX_ALPHABET_SIZE) {\n    throw new RangeError(\n      `Alphabet must have at most ${MAX_ALPHABET_SIZE} characters, got ${alphabet.length}`,\n    );\n  }\n  const seen = new Set<string>();\n  for (const char of alphabet) {\n    if (seen.has(char)) {\n      throw new TypeError(`Alphabet contains duplicate character: \"${char}\"`);\n    }\n    seen.add(char);\n  }\n}\n\n/**\n * Generates an ID of `length` characters drawn from `alphabet` using\n * rejection sampling to avoid modulo bias.\n *\n * The caller is responsible for providing valid `alphabet` and `length` values.\n * Use `validateAlphabetString` and `assertLength` before calling this.\n */\nexport function generateFromAlphabet(\n  alphabet: string,\n  length: number,\n  getBytes: (count: number) => Uint8Array,\n): string {\n  const alphabetSize = alphabet.length;\n\n  // Find the smallest bitmask >= alphabetSize to reduce rejection rate.\n  let mask = 1;\n  while (mask < alphabetSize) mask = (mask << 1) | 1;\n\n  // Overshoot buffer size to reduce round-trips. Most cases complete in one pass.\n  const bufferMultiplier = Math.ceil((1.6 * mask * length) / alphabetSize);\n  let result = \"\";\n\n  while (result.length < length) {\n    const bytes = getBytes(bufferMultiplier);\n    for (let i = 0; i < bytes.length && result.length < length; i++) {\n      const byte = (bytes[i] as number) & mask;\n      if (byte < alphabetSize) {\n        result += alphabet[byte];\n      }\n    }\n  }\n\n  return result;\n}\n","const MIN_LENGTH = 1;\nconst MAX_LENGTH = 255;\n\nexport function assertLength(length: number): void {\n  if (!Number.isInteger(length) || length < MIN_LENGTH || length > MAX_LENGTH) {\n    throw new RangeError(\n      `ID length must be an integer between ${MIN_LENGTH} and ${MAX_LENGTH}, got ${length}`,\n    );\n  }\n}\n\nexport function assertPrefix(prefix: string): void {\n  if (typeof prefix !== \"string\" || prefix.length === 0) {\n    throw new TypeError(\"Prefix must be a non-empty string\");\n  }\n  if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(prefix)) {\n    throw new TypeError(\"Prefix must start with a letter and contain only letters and digits\");\n  }\n}\n","// Returns a Uint8Array of `count` cryptographically secure random bytes.\n// Works in Node 18+, all modern browsers, and edge runtimes that expose `crypto`.\nexport function randomBytes(count: number): Uint8Array {\n  const bytes = new Uint8Array(count);\n  crypto.getRandomValues(bytes);\n  return bytes;\n}\n","import { generateFromAlphabet } from \"./internal/alphabet.js\";\nimport { assertLength } from \"./internal/assert.js\";\nimport { randomBytes } from \"./internal/random.js\";\n\n/**\n * URL-safe alphabet used by default. 64 characters: A-Z, a-z, 0-9, _, -.\n * Chosen to be safe in URLs, filenames, and most log formats without encoding.\n */\nexport const DEFAULT_ALPHABET = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-\";\n\nconst DEFAULT_LENGTH = 21;\n\n/**\n * Generates a cryptographically secure random ID.\n *\n * @param length - Number of characters (1–255). Defaults to 21.\n * @returns A random URL-safe string of the requested length.\n *\n * @example\n * import { generateId } from \"sigilid\";\n * const id = generateId(); // \"K7gkJ_q3vR2nL8xH5eM0w\"\n */\nexport function generateId(length: number = DEFAULT_LENGTH): string {\n  assertLength(length);\n  return generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);\n}\n","import { DEFAULT_ALPHABET } from \"./index.js\";\nimport { generateFromAlphabet } from \"./internal/alphabet.js\";\nimport { assertLength, assertPrefix } from \"./internal/assert.js\";\nimport { randomBytes } from \"./internal/random.js\";\n\nconst DEFAULT_LENGTH = 21;\nconst SEPARATOR = \"_\";\n\n/**\n * A nominal type brand. Attach this to a string type to create a distinct\n * branded string that is not assignable from plain `string`.\n *\n * @example\n * type UserId = Brand<string, \"UserId\">;\n */\nexport type Brand<T, B> = T & { readonly __brand: B };\n\n/**\n * A branded string type for an entity named `T`.\n * Equivalent to `Brand<string, T>`, but more ergonomic for ID types.\n *\n * @example\n * type UserId = IdOf<\"User\">;\n * type PostId = IdOf<\"Post\">;\n */\nexport type IdOf<T extends string> = Brand<string, T>;\n\n/**\n * Casts a plain string to a branded `IdOf<T>`.\n *\n * This is a type-only operation at runtime — no validation is performed.\n * Use `assertValidId` from `\"sigilid/validate\"` first if you need runtime safety.\n *\n * @example\n * import { castId } from \"sigilid/typed\";\n * const id = castId<\"User\">(\"usr_abc123\");\n */\nexport function castId<T extends string>(value: string): IdOf<T> {\n  return value as IdOf<T>;\n}\n\n/**\n * Returns a factory function that generates cryptographically secure branded IDs.\n *\n * The type parameter `T` sets the brand. If a prefix is provided, the format\n * is `{prefix}_{id}`, otherwise it is a plain random string.\n *\n * Validation happens at factory creation, not per-call.\n *\n * @param prefix - Optional alphanumeric prefix.\n * @param length - Length of the random portion (1–255). Defaults to 21.\n * @returns A zero-argument function returning `IdOf<T>`.\n *\n * @example\n * import { createTypedGenerator } from \"sigilid/typed\";\n * const userId = createTypedGenerator<\"User\">(\"usr\");\n * const id = userId(); // IdOf<\"User\"> = \"usr_K7gkJ_q3vR2nL8xH5eM0w\"\n */\nexport function createTypedGenerator<T extends string>(\n  prefix?: string,\n  length: number = DEFAULT_LENGTH,\n): () => IdOf<T> {\n  if (prefix !== undefined) assertPrefix(prefix);\n  assertLength(length);\n\n  return (): IdOf<T> => {\n    const raw = generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);\n    const value = prefix !== undefined ? `${prefix}${SEPARATOR}${raw}` : raw;\n    return value as IdOf<T>;\n  };\n}\n"]}

package/dist/validate.cjs

@@ -0,0 +1,45 @@
+'use strict';
+
+// src/index.ts
+var DEFAULT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+
+// src/internal/validation.ts
+function isValidIdValue(value, options = {}) {
+  if (typeof value !== "string" || value.length === 0) return false;
+  let idPart = value;
+  if (options.prefix !== void 0) {
+    const expected = `${options.prefix}_`;
+    if (!value.startsWith(expected)) return false;
+    idPart = value.slice(expected.length);
+  }
+  if (options.length !== void 0 && idPart.length !== options.length) return false;
+  if (idPart.length === 0) return false;
+  if (options.alphabet !== void 0) {
+    const charSet = new Set(options.alphabet);
+    for (const char of idPart) {
+      if (!charSet.has(char)) return false;
+    }
+  }
+  return true;
+}
+
+// src/validate.ts
+function isValidId(value, options = {}) {
+  const opts = { alphabet: DEFAULT_ALPHABET, ...options };
+  return isValidIdValue(value, opts);
+}
+function assertValidId(value, options = {}) {
+  if (!isValidId(value, options)) {
+    throw new TypeError(`Invalid ID: "${value}"`);
+  }
+}
+function parseId(value, options = {}) {
+  assertValidId(value, options);
+  return value;
+}
+
+exports.assertValidId = assertValidId;
+exports.isValidId = isValidId;
+exports.parseId = parseId;
+//# sourceMappingURL=validate.cjs.map
+//# sourceMappingURL=validate.cjs.map

package/dist/validate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/internal/validation.ts","../src/validate.ts"],"names":[],"mappings":";;;AAQO,IAAM,gBAAA,GAAmB,kEAAA;;;ACCzB,SAAS,cAAA,CAAe,KAAA,EAAe,OAAA,GAA6B,EAAC,EAAY;AACtF,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,CAAM,MAAA,KAAW,GAAG,OAAO,KAAA;AAE5D,EAAA,IAAI,MAAA,GAAS,KAAA;AAEb,EAAA,IAAI,OAAA,CAAQ,WAAW,MAAA,EAAW;AAChC,IAAA,MAAM,QAAA,GAAW,CAAA,EAAG,OAAA,CAAQ,MAAM,CAAA,CAAA,CAAA;AAClC,IAAA,IAAI,CAAC,KAAA,CAAM,UAAA,CAAW,QAAQ,GAAG,OAAO,KAAA;AACxC,IAAA,MAAA,GAAS,KAAA,CAAM,KAAA,CAAM,QAAA,CAAS,MAAM,CAAA;AAAA,EACtC;AAEA,EAAA,IAAI,QAAQ,MAAA,KAAW,MAAA,IAAa,OAAO,MAAA,KAAW,OAAA,CAAQ,QAAQ,OAAO,KAAA;AAC7E,EAAA,IAAI,MAAA,CAAO,MAAA,KAAW,CAAA,EAAG,OAAO,KAAA;AAEhC,EAAA,IAAI,OAAA,CAAQ,aAAa,MAAA,EAAW;AAClC,IAAA,MAAM,OAAA,GAAU,IAAI,GAAA,CAAI,OAAA,CAAQ,QAAQ,CAAA;AACxC,IAAA,KAAA,MAAW,QAAQ,MAAA,EAAQ;AACzB,MAAA,IAAI,CAAC,OAAA,CAAQ,GAAA,CAAI,IAAI,GAAG,OAAO,KAAA;AAAA,IACjC;AAAA,EACF;AAEA,EAAA,OAAO,IAAA;AACT;;;ACZO,SAAS,SAAA,CAAU,KAAA,EAAe,OAAA,GAA6B,EAAC,EAAY;AACjF,EAAA,MAAM,IAAA,GAAO,EAAE,QAAA,EAAU,gBAAA,EAAkB,GAAG,OAAA,EAAQ;AACtD,EAAA,OAAO,cAAA,CAAe,OAAO,IAAI,CAAA;AACnC;AAWO,SAAS,aAAA,CAAc,KAAA,EAAe,OAAA,GAA6B,EAAC,EAAS;AAClF,EAAA,IAAI,CAAC,SAAA,CAAU,KAAA,EAAO,OAAO,CAAA,EAAG;AAC9B,IAAA,MAAM,IAAI,SAAA,CAAU,CAAA,aAAA,EAAgB,KAAK,CAAA,CAAA,CAAG,CAAA;AAAA,EAC9C;AACF;AAYO,SAAS,OAAA,CAAQ,KAAA,EAAe,OAAA,GAA6B,EAAC,EAAW;AAC9E,EAAA,aAAA,CAAc,OAAO,OAAO,CAAA;AAC5B,EAAA,OAAO,KAAA;AACT","file":"validate.cjs","sourcesContent":["import { generateFromAlphabet } from \"./internal/alphabet.js\";\nimport { assertLength } from \"./internal/assert.js\";\nimport { randomBytes } from \"./internal/random.js\";\n\n/**\n * URL-safe alphabet used by default. 64 characters: A-Z, a-z, 0-9, _, -.\n * Chosen to be safe in URLs, filenames, and most log formats without encoding.\n */\nexport const DEFAULT_ALPHABET = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-\";\n\nconst DEFAULT_LENGTH = 21;\n\n/**\n * Generates a cryptographically secure random ID.\n *\n * @param length - Number of characters (1–255). Defaults to 21.\n * @returns A random URL-safe string of the requested length.\n *\n * @example\n * import { generateId } from \"sigilid\";\n * const id = generateId(); // \"K7gkJ_q3vR2nL8xH5eM0w\"\n */\nexport function generateId(length: number = DEFAULT_LENGTH): string {\n  assertLength(length);\n  return generateFromAlphabet(DEFAULT_ALPHABET, length, randomBytes);\n}\n","export interface ValidationOptions {\n  /** Expected exact length of the ID portion (excluding prefix and separator). */\n  length?: number;\n  /** Expected prefix. The separator `_` is assumed. */\n  prefix?: string;\n  /** Alphabet the ID characters must belong to. Defaults to DEFAULT_ALPHABET. */\n  alphabet?: string;\n}\n\nexport function isValidIdValue(value: string, options: ValidationOptions = {}): boolean {\n  if (typeof value !== \"string\" || value.length === 0) return false;\n\n  let idPart = value;\n\n  if (options.prefix !== undefined) {\n    const expected = `${options.prefix}_`;\n    if (!value.startsWith(expected)) return false;\n    idPart = value.slice(expected.length);\n  }\n\n  if (options.length !== undefined && idPart.length !== options.length) return false;\n  if (idPart.length === 0) return false;\n\n  if (options.alphabet !== undefined) {\n    const charSet = new Set(options.alphabet);\n    for (const char of idPart) {\n      if (!charSet.has(char)) return false;\n    }\n  }\n\n  return true;\n}\n","import { DEFAULT_ALPHABET } from \"./index.js\";\nimport type { ValidationOptions } from \"./internal/validation.js\";\nimport { isValidIdValue } from \"./internal/validation.js\";\n\nexport type { ValidationOptions };\n\n/**\n * Returns `true` if `value` is a valid ID, `false` otherwise.\n *\n * By default, validates that the value is a non-empty string of characters\n * from the default URL-safe alphabet. Options can constrain length, prefix,\n * and alphabet.\n *\n * @example\n * import { isValidId } from \"sigilid/validate\";\n * isValidId(\"K7gkJ_q3vR2nL8xH5eM0w\"); // true\n * isValidId(\"usr_K7gkJ_q3vR2nL8xH5eM0w\", { prefix: \"usr\" }); // true\n * isValidId(\"\", {}); // false\n */\nexport function isValidId(value: string, options: ValidationOptions = {}): boolean {\n  const opts = { alphabet: DEFAULT_ALPHABET, ...options };\n  return isValidIdValue(value, opts);\n}\n\n/**\n * Throws a `TypeError` if `value` is not a valid ID.\n *\n * Useful for asserting IDs at API boundaries.\n *\n * @example\n * import { assertValidId } from \"sigilid/validate\";\n * assertValidId(req.params.id); // throws if invalid\n */\nexport function assertValidId(value: string, options: ValidationOptions = {}): void {\n  if (!isValidId(value, options)) {\n    throw new TypeError(`Invalid ID: \"${value}\"`);\n  }\n}\n\n/**\n * Parses and returns the ID if valid, otherwise throws.\n *\n * A convenience wrapper over `assertValidId` for use in pipelines where\n * you want the validated value back from the same call.\n *\n * @example\n * import { parseId } from \"sigilid/validate\";\n * const id = parseId(rawInput); // throws if invalid, returns the same string if valid\n */\nexport function parseId(value: string, options: ValidationOptions = {}): string {\n  assertValidId(value, options);\n  return value;\n}\n"]}

package/dist/validate.d.cts

@@ -0,0 +1,46 @@
+interface ValidationOptions {
+    /** Expected exact length of the ID portion (excluding prefix and separator). */
+    length?: number;
+    /** Expected prefix. The separator `_` is assumed. */
+    prefix?: string;
+    /** Alphabet the ID characters must belong to. Defaults to DEFAULT_ALPHABET. */
+    alphabet?: string;
+}
+
+/**
+ * Returns `true` if `value` is a valid ID, `false` otherwise.
+ *
+ * By default, validates that the value is a non-empty string of characters
+ * from the default URL-safe alphabet. Options can constrain length, prefix,
+ * and alphabet.
+ *
+ * @example
+ * import { isValidId } from "sigilid/validate";
+ * isValidId("K7gkJ_q3vR2nL8xH5eM0w"); // true
+ * isValidId("usr_K7gkJ_q3vR2nL8xH5eM0w", { prefix: "usr" }); // true
+ * isValidId("", {}); // false
+ */
+declare function isValidId(value: string, options?: ValidationOptions): boolean;
+/**
+ * Throws a `TypeError` if `value` is not a valid ID.
+ *
+ * Useful for asserting IDs at API boundaries.
+ *
+ * @example
+ * import { assertValidId } from "sigilid/validate";
+ * assertValidId(req.params.id); // throws if invalid
+ */
+declare function assertValidId(value: string, options?: ValidationOptions): void;
+/**
+ * Parses and returns the ID if valid, otherwise throws.
+ *
+ * A convenience wrapper over `assertValidId` for use in pipelines where
+ * you want the validated value back from the same call.
+ *
+ * @example
+ * import { parseId } from "sigilid/validate";
+ * const id = parseId(rawInput); // throws if invalid, returns the same string if valid
+ */
+declare function parseId(value: string, options?: ValidationOptions): string;
+
+export { type ValidationOptions, assertValidId, isValidId, parseId };