@tnid/filter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Edlinger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @tnid/filter
+
+Generate TNIDs that don't contain blocklisted substrings (e.g., profanity).
+
+## Why Filter TNIDs?
+
+The 17-character data portion of a TNID string uses an alphabet that includes letters capable of forming recognizable words. For some applications, it may be undesirable for IDs to accidentally contain offensive terms.
+
+## Installation
+
+```bash
+# npm
+npm install @tnid/filter @tnid/core
+
+# pnpm
+pnpm add @tnid/filter @tnid/core
+
+# bun
+bun add @tnid/filter @tnid/core
+
+# deno
+deno add npm:@tnid/filter npm:@tnid/core
+```
+
+For encryption-aware filtering, also install `@tnid/encryption`.
+
+## Quick Start
+
+```typescript
+import { Tnid, TnidType } from "@tnid/core";
+import { Blocklist, newV0Filtered, newV1Filtered } from "@tnid/filter";
+
+const UserId = Tnid("user");
+type UserId = TnidType<typeof UserId>;
+
+// Create a blocklist
+const blocklist = new Blocklist(["TACO", "FOO", "BAZZ"]);
+
+// Generate filtered IDs
+const v0: UserId = newV0Filtered(UserId, blocklist);
+const v1: UserId = newV1Filtered(UserId, blocklist);
+```
+
+### With Encryption
+
+If you use the encryption extension to convert V0 to V1, you probably want both forms to be clean:
+
+```typescript
+import { Tnid } from "@tnid/core";
+import { EncryptionKey } from "@tnid/encryption";
+import { Blocklist } from "@tnid/filter";
+import { newV0FilteredForEncryption } from "@tnid/filter/encryption";
+
+const UserId = Tnid("user");
+const blocklist = new Blocklist(["TACO", "FOO"]);
+const key = EncryptionKey.fromHex("0102030405060708090a0b0c0d0e0f10");
+
+// Both the V0 and its encrypted V1 will be clean
+const v0 = await newV0FilteredForEncryption(UserId, blocklist, key);
+```
+
+## API Reference
+
+### `Blocklist`
+
+A compiled blocklist for case-insensitive substring matching. Patterns must only contain characters from the TNID data alphabet (`-0-9A-Z_a-z`).
+
+```typescript
+const blocklist = new Blocklist(["TACO", "FOO", "BAZZ"]);
+
+blocklist.containsMatch("xyzTACOxyz"); // true
+blocklist.containsMatch("xyztacoxyz"); // true (case-insensitive)
+blocklist.containsMatch("xyzHELLOxyz"); // false
+```
+
+### `newV0Filtered(factory, blocklist)`
+
+Generate a time-ordered V0 TNID whose data string contains no blocklisted words.
+
+- **Throws**: `FilterError` if the iteration limit is exceeded
+
+### `newV1Filtered(factory, blocklist)`
+
+Generate a random V1 TNID whose data string contains no blocklisted words.
+
+- **Throws**: `FilterError` if the iteration limit is exceeded
+
+### `newV0FilteredForEncryption(factory, blocklist, key)` (from `@tnid/filter/encryption`)
+
+Generate a V0 TNID where both the V0 and its encrypted V1 form contain no blocklisted words.
+
+- **Returns**: `Promise<TnidValue<Name>>`
+- **Throws**: `FilterError` if the iteration limit is exceeded
+
+### `FilterError`
+
+Thrown when filtered generation exceeds the iteration limit, which typically means the blocklist is too restrictive.
+
+```typescript
+import { FilterError } from "@tnid/filter";
+
+try {
+  const id = newV0Filtered(UserId, blocklist);
+} catch (e) {
+  if (e instanceof FilterError) {
+    console.log(`Failed after ${e.iterations} iterations`);
+  }
+}
+```
+
+## How It Works
+
+For V1, all bits are random, so the function simply regenerates until clean.
+
+For V0, the strategy depends on where the match appears in the data string:
+
+- **Random portion** (characters 7-16): Regenerate the random bits
+- **Timestamp portion** (characters 0-6): Advance the timestamp enough to change the matched characters, avoiding a potentially large "bad window"
+
+A global last-known-safe timestamp avoids re-discovering the same bad windows across calls.
+
+## License
+
+MIT

package/esm/blocklist.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Blocklist for matching substrings in TNID data strings.
+ *
+ * Uses a single compiled RegExp with alternation for efficient matching.
+ */
+/**
+ * A compiled blocklist for efficient case-insensitive substring matching.
+ *
+ * Patterns may only contain characters from the TNID data string alphabet
+ * (`-0-9A-Z_a-z`). Patterns with other characters can never match and
+ * will be rejected.
+ *
+ * @example
+ * ```typescript
+ * const blocklist = new Blocklist(["TACO", "FOO", "BAZZ"]);
+ *
+ * blocklist.containsMatch("xyzTACOxyz"); // true
+ * blocklist.containsMatch("xyztacoxyz"); // true (case-insensitive)
+ * blocklist.containsMatch("xyzHELLOxyz"); // false
+ * ```
+ */
+export declare class Blocklist {
+    private pattern;
+    /**
+     * Creates a new blocklist from the given patterns.
+     *
+     * @throws {Error} If any pattern contains characters outside the TNID data alphabet.
+     */
+    constructor(patterns: string[]);
+    /** Returns `true` if the text contains any blocklisted word. */
+    containsMatch(text: string): boolean;
+    /**
+     * Finds the first blocklist match in the text.
+     * Returns the start index and length, or `null` if no match.
+     */
+    findFirstMatch(text: string): {
+        start: number;
+        length: number;
+    } | null;
+}
+//# sourceMappingURL=blocklist.d.ts.map

package/esm/blocklist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocklist.d.ts","sourceRoot":"","sources":["../src/blocklist.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAgB;IAE/B;;;;OAIG;gBACS,QAAQ,EAAE,MAAM,EAAE;IAgB9B,gEAAgE;IAChE,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAKpC;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAMvE"}

package/esm/blocklist.js

@@ -0,0 +1,68 @@
+/**
+ * Blocklist for matching substrings in TNID data strings.
+ *
+ * Uses a single compiled RegExp with alternation for efficient matching.
+ */
+/** TNID data string alphabet: `-0-9A-Z_a-z` */
+const VALID_PATTERN = /^[-0-9A-Za-z_]+$/;
+/**
+ * A compiled blocklist for efficient case-insensitive substring matching.
+ *
+ * Patterns may only contain characters from the TNID data string alphabet
+ * (`-0-9A-Z_a-z`). Patterns with other characters can never match and
+ * will be rejected.
+ *
+ * @example
+ * ```typescript
+ * const blocklist = new Blocklist(["TACO", "FOO", "BAZZ"]);
+ *
+ * blocklist.containsMatch("xyzTACOxyz"); // true
+ * blocklist.containsMatch("xyztacoxyz"); // true (case-insensitive)
+ * blocklist.containsMatch("xyzHELLOxyz"); // false
+ * ```
+ */
+export class Blocklist {
+    /**
+     * Creates a new blocklist from the given patterns.
+     *
+     * @throws {Error} If any pattern contains characters outside the TNID data alphabet.
+     */
+    constructor(patterns) {
+        Object.defineProperty(this, "pattern", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        const nonEmpty = patterns.filter((p) => p.length > 0);
+        for (const p of nonEmpty) {
+            if (!VALID_PATTERN.test(p)) {
+                throw new Error(`invalid blocklist pattern "${p}": only TNID data characters are allowed (-0-9A-Za-z_)`);
+            }
+        }
+        if (nonEmpty.length === 0) {
+            this.pattern = null;
+        }
+        else {
+            this.pattern = new RegExp(nonEmpty.join("|"), "i");
+        }
+    }
+    /** Returns `true` if the text contains any blocklisted word. */
+    containsMatch(text) {
+        if (this.pattern === null)
+            return false;
+        return this.pattern.test(text);
+    }
+    /**
+     * Finds the first blocklist match in the text.
+     * Returns the start index and length, or `null` if no match.
+     */
+    findFirstMatch(text) {
+        if (this.pattern === null)
+            return null;
+        const m = this.pattern.exec(text);
+        if (m === null)
+            return null;
+        return { start: m.index, length: m[0].length };
+    }
+}

package/esm/filter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Filtered TNID generation functions.
+ *
+ * Generate TNIDs guaranteed not to contain blocklisted substrings
+ * in their data string representation.
+ */
+import type { NamedTnid, TnidValue } from "@tnid/core";
+import type { Blocklist } from "./blocklist.js";
+/** Error thrown when filtered generation exceeds the iteration limit. */
+export declare class FilterError extends Error {
+    readonly iterations: number;
+    constructor(iterations: number);
+}
+/**
+ * Generate a V0 TNID whose data string contains no blocklisted words.
+ *
+ * Uses smart timestamp bumping when a match is in the timestamp portion,
+ * and random regeneration when a match touches the random portion.
+ *
+ * @throws {FilterError} If maximum iterations exceeded.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { Blocklist, newV0Filtered } from "@tnid/filter";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const id = newV0Filtered(UserId, blocklist);
+ * ```
+ */
+export declare function newV0Filtered<Name extends string>(factory: NamedTnid<Name>, blocklist: Blocklist): TnidValue<Name>;
+/**
+ * Generate a V1 TNID whose data string contains no blocklisted words.
+ *
+ * Since all V1 bits are random, simply regenerates until clean.
+ *
+ * @throws {FilterError} If maximum iterations exceeded.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { Blocklist, newV1Filtered } from "@tnid/filter";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const id = newV1Filtered(UserId, blocklist);
+ * ```
+ */
+export declare function newV1Filtered<Name extends string>(factory: NamedTnid<Name>, blocklist: Blocklist): TnidValue<Name>;
+//# sourceMappingURL=filter.d.ts.map

package/esm/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAchD,yEAAyE;AACzE,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM;CAO/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,IAAI,SAAS,MAAM,EAC/C,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,EACxB,SAAS,EAAE,SAAS,GACnB,SAAS,CAAC,IAAI,CAAC,CAkBjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,IAAI,SAAS,MAAM,EAC/C,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,EACxB,SAAS,EAAE,SAAS,GACnB,SAAS,CAAC,IAAI,CAAC,CAYjB"}

package/esm/filter.js

@@ -0,0 +1,84 @@
+/**
+ * Filtered TNID generation functions.
+ *
+ * Generate TNIDs guaranteed not to contain blocklisted substrings
+ * in their data string representation.
+ */
+import { dataString, getStartingTimestamp, handleV0Match, randomBigInt, recordSafeTimestamp, V0_RANDOM_BITS, V1_RANDOM_BITS, } from "./internals.js";
+const MAX_V0_ITERATIONS = 1_000;
+const MAX_V1_ITERATIONS = 100;
+/** Error thrown when filtered generation exceeds the iteration limit. */
+export class FilterError extends Error {
+    constructor(iterations) {
+        super(`failed to generate clean ID after ${iterations} iterations; blocklist may be too restrictive`);
+        Object.defineProperty(this, "iterations", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "FilterError";
+        this.iterations = iterations;
+    }
+}
+/**
+ * Generate a V0 TNID whose data string contains no blocklisted words.
+ *
+ * Uses smart timestamp bumping when a match is in the timestamp portion,
+ * and random regeneration when a match touches the random portion.
+ *
+ * @throws {FilterError} If maximum iterations exceeded.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { Blocklist, newV0Filtered } from "@tnid/filter";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const id = newV0Filtered(UserId, blocklist);
+ * ```
+ */
+export function newV0Filtered(factory, blocklist) {
+    let timestamp = getStartingTimestamp();
+    for (let i = 0; i < MAX_V0_ITERATIONS; i++) {
+        const random = randomBigInt(V0_RANDOM_BITS);
+        const id = factory.v0_from_parts(timestamp, random);
+        const data = dataString(id);
+        const match = blocklist.findFirstMatch(data);
+        if (match === null) {
+            recordSafeTimestamp(timestamp);
+            return id;
+        }
+        timestamp = handleV0Match(match, timestamp);
+    }
+    throw new FilterError(MAX_V0_ITERATIONS);
+}
+/**
+ * Generate a V1 TNID whose data string contains no blocklisted words.
+ *
+ * Since all V1 bits are random, simply regenerates until clean.
+ *
+ * @throws {FilterError} If maximum iterations exceeded.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { Blocklist, newV1Filtered } from "@tnid/filter";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const id = newV1Filtered(UserId, blocklist);
+ * ```
+ */
+export function newV1Filtered(factory, blocklist) {
+    for (let i = 0; i < MAX_V1_ITERATIONS; i++) {
+        const random = randomBigInt(V1_RANDOM_BITS);
+        const id = factory.v1_from_parts(random);
+        const data = dataString(id);
+        if (!blocklist.containsMatch(data)) {
+            return id;
+        }
+    }
+    throw new FilterError(MAX_V1_ITERATIONS);
+}

package/esm/filter_encryption.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @tnid/filter/encryption - Encryption-aware blocklist filtering
+ *
+ * Generate V0 TNIDs where both the V0 and its encrypted V1 form
+ * contain no blocklisted words.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { EncryptionKey } from "@tnid/encryption";
+ * import { Blocklist } from "@tnid/filter";
+ * import { newV0FilteredForEncryption } from "@tnid/filter/encryption";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const key = EncryptionKey.fromHex("0102030405060708090a0b0c0d0e0f10");
+ *
+ * const id = await newV0FilteredForEncryption(UserId, blocklist, key);
+ * ```
+ *
+ * @module
+ */
+import type { NamedTnid, TnidValue } from "@tnid/core";
+import { type EncryptionKey } from "@tnid/encryption";
+import type { Blocklist } from "./blocklist.js";
+import { FilterError } from "./filter.js";
+export { Blocklist } from "./blocklist.js";
+export { FilterError };
+/**
+ * Generate a V0 TNID where both the V0 and its encrypted V1 form
+ * contain no blocklisted words.
+ *
+ * Requires the V0/V1 Encryption extension.
+ *
+ * @throws {FilterError} If maximum iterations exceeded.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { EncryptionKey } from "@tnid/encryption";
+ * import { Blocklist } from "@tnid/filter";
+ * import { newV0FilteredForEncryption } from "@tnid/filter/encryption";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const key = EncryptionKey.fromHex("0102030405060708090a0b0c0d0e0f10");
+ *
+ * const id = await newV0FilteredForEncryption(UserId, blocklist, key);
+ * ```
+ */
+export declare function newV0FilteredForEncryption<Name extends string>(factory: NamedTnid<Name>, blocklist: Blocklist, key: EncryptionKey): Promise<TnidValue<Name>>;
+//# sourceMappingURL=filter_encryption.d.ts.map

package/esm/filter_encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter_encryption.d.ts","sourceRoot":"","sources":["../src/filter_encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAW1C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,CAAC;AAIvB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,SAAS,MAAM,EAClE,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,EACxB,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CA2B1B"}

package/esm/filter_encryption.js

@@ -0,0 +1,74 @@
+/**
+ * @tnid/filter/encryption - Encryption-aware blocklist filtering
+ *
+ * Generate V0 TNIDs where both the V0 and its encrypted V1 form
+ * contain no blocklisted words.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { EncryptionKey } from "@tnid/encryption";
+ * import { Blocklist } from "@tnid/filter";
+ * import { newV0FilteredForEncryption } from "@tnid/filter/encryption";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const key = EncryptionKey.fromHex("0102030405060708090a0b0c0d0e0f10");
+ *
+ * const id = await newV0FilteredForEncryption(UserId, blocklist, key);
+ * ```
+ *
+ * @module
+ */
+import { encryptV0ToV1 } from "@tnid/encryption";
+import { FilterError } from "./filter.js";
+import { dataString, getStartingTimestamp, handleV0Match, randomBigInt, recordSafeTimestamp, V0_RANDOM_BITS, } from "./internals.js";
+// Re-export Blocklist and FilterError for convenience
+export { Blocklist } from "./blocklist.js";
+export { FilterError };
+const MAX_ENCRYPTION_ITERATIONS = 1_000;
+/**
+ * Generate a V0 TNID where both the V0 and its encrypted V1 form
+ * contain no blocklisted words.
+ *
+ * Requires the V0/V1 Encryption extension.
+ *
+ * @throws {FilterError} If maximum iterations exceeded.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { EncryptionKey } from "@tnid/encryption";
+ * import { Blocklist } from "@tnid/filter";
+ * import { newV0FilteredForEncryption } from "@tnid/filter/encryption";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ * const key = EncryptionKey.fromHex("0102030405060708090a0b0c0d0e0f10");
+ *
+ * const id = await newV0FilteredForEncryption(UserId, blocklist, key);
+ * ```
+ */
+export async function newV0FilteredForEncryption(factory, blocklist, key) {
+    let timestamp = getStartingTimestamp();
+    for (let i = 0; i < MAX_ENCRYPTION_ITERATIONS; i++) {
+        const random = randomBigInt(V0_RANDOM_BITS);
+        const v0 = factory.v0_from_parts(timestamp, random);
+        const v0Data = dataString(v0);
+        // Check V0 first
+        const v0Match = blocklist.findFirstMatch(v0Data);
+        if (v0Match !== null) {
+            timestamp = handleV0Match(v0Match, timestamp);
+            continue;
+        }
+        // V0 is clean, now check encrypted V1
+        const v1 = await encryptV0ToV1(v0, key);
+        const v1Data = dataString(v1);
+        if (!blocklist.containsMatch(v1Data)) {
+            recordSafeTimestamp(timestamp);
+            return v0;
+        }
+        // V1 had a match - regenerate (loop continues with new random)
+    }
+    throw new FilterError(MAX_ENCRYPTION_ITERATIONS);
+}

package/esm/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @tnid/filter - Blocklist filtering for TNID generation
+ *
+ * Generate TNIDs guaranteed not to contain specified substrings
+ * (e.g., profanity) in their string representation.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { Blocklist, newV0Filtered, newV1Filtered } from "@tnid/filter";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ *
+ * const v0 = newV0Filtered(UserId, blocklist);
+ * const v1 = newV1Filtered(UserId, blocklist);
+ * ```
+ *
+ * For encryption-aware filtering, use the `@tnid/filter/encryption` entry point.
+ *
+ * @module
+ */
+export { Blocklist } from "./blocklist.js";
+export { FilterError, newV0Filtered, newV1Filtered } from "./filter.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/esm/index.js

@@ -0,0 +1,24 @@
+/**
+ * @tnid/filter - Blocklist filtering for TNID generation
+ *
+ * Generate TNIDs guaranteed not to contain specified substrings
+ * (e.g., profanity) in their string representation.
+ *
+ * @example
+ * ```typescript
+ * import { Tnid } from "@tnid/core";
+ * import { Blocklist, newV0Filtered, newV1Filtered } from "@tnid/filter";
+ *
+ * const UserId = Tnid("user");
+ * const blocklist = new Blocklist(["TACO", "FOO"]);
+ *
+ * const v0 = newV0Filtered(UserId, blocklist);
+ * const v1 = newV1Filtered(UserId, blocklist);
+ * ```
+ *
+ * For encryption-aware filtering, use the `@tnid/filter/encryption` entry point.
+ *
+ * @module
+ */
+export { Blocklist } from "./blocklist.js";
+export { FilterError, newV0Filtered, newV1Filtered } from "./filter.js";

package/esm/internals.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared internals for filter functions.
+ * @internal Not part of the public API.
+ */
+export declare const FIRST_CHAR_WITH_RANDOM = 7;
+export declare const V0_RANDOM_BITS = 57;
+export declare const V1_RANDOM_BITS = 100;
+/** Global last-known-safe timestamp to avoid re-discovering bad windows. */
+export declare let lastSafeTimestamp: bigint;
+export declare function recordSafeTimestamp(ts: bigint): void;
+export declare function getStartingTimestamp(): bigint;
+/** Generate a random bigint with the specified number of bits. */
+export declare function randomBigInt(bits: number): bigint;
+/** Extract the 17-char data string from a TNID string. */
+export declare function dataString(tnid: string): string;
+/**
+ * Check if a match touches the random portion of V0 data string.
+ * If true, regenerating random bits may resolve the match.
+ * If false, the match is entirely in the timestamp portion and requires bumping.
+ */
+export declare function matchTouchesRandomPortion(start: number, length: number): boolean;
+/**
+ * Minimum timestamp bump (in ms) needed to change the character at position `pos`.
+ * Each character encodes 6 bits. Lower positions = more significant = larger bump.
+ */
+export declare function timestampBumpForChar(pos: number): bigint;
+/**
+ * Handle a V0 blocklist match: bump timestamp if match is in timestamp portion.
+ * Returns the (possibly bumped) timestamp.
+ */
+export declare function handleV0Match(match: {
+    start: number;
+    length: number;
+}, timestamp: bigint): bigint;
+//# sourceMappingURL=internals.d.ts.map

package/esm/internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.d.ts","sourceRoot":"","sources":["../src/internals.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,4EAA4E;AAC5E,eAAO,IAAI,iBAAiB,QAAK,CAAC;AAElC,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAIpD;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAG7C;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEhF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACxC,SAAS,EAAE,MAAM,GAChB,MAAM,CAMR"}