@lp-labs/transliteration-search 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+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

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# @lp-labs/transliteration-search
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Original caller-table transliteration and literal search with stable original UTF-16 mapping.
+Independent, zero runtime/peer dependencies, no bundled script tables.
+**There is no global script coverage or linguistic equivalence claim.**
+
+## Install
+
+```bash
+npm install @lp-labs/transliteration-search
+```
+
+Node >=18, ES2022 ESM/CommonJS and strict TypeScript declarations.
+CommonJS: `const { createTransliterator } = require('@lp-labs/transliteration-search')`.
+
+## Quickstart
+
+```js
+import { createTransliterator } from '@lp-labs/transliteration-search';
+
+const engine = createTransliterator([
+  { source: 'æ', target: 'ae' },
+  { source: 'ж', target: 'zh' },
+  { source: '\u0301', target: '' },
+]);
+const result = engine.transliterate('😀æ e\u0301');
+if (result.text !== '😀ae e') throw new Error('Transliteration failed');
+const range = result.originalRange(3, 4);
+if (range.start !== 2 || range.end !== 3) throw new Error('Expansion mapping failed');
+const hits = engine.find('😀ж', 'zh');
+if (hits[0].start !== 2 || hits[0].end !== 3) throw new Error('Search mapping failed');
+```
+
+## Full API and types
+
+The only runtime export is
+`createTransliterator(entries: readonly TransliterationEntry[], options?: TransliterationOptions): Transliterator`.
+Types below are all exported:
+
+```ts
+interface TransliterationEntry {
+  source: string;
+  target: string;
+}
+interface TransliterationOptions {
+  maxInput?: number;
+  maxOutput?: number;
+}
+interface SourceSpan {
+  originalStart: number;
+  originalEnd: number;
+  transformedStart: number;
+  transformedEnd: number;
+}
+interface OriginalRange {
+  start: number;
+  end: number;
+}
+interface TransliteratedText {
+  original: string;
+  text: string;
+  spans: SourceSpan[];
+  originalRange(start: number, end: number): OriginalRange;
+}
+interface TransliterationMatch extends OriginalRange {
+  transformedStart: number;
+  transformedEnd: number;
+}
+interface Transliterator {
+  transliterate(text: string): TransliteratedText;
+  find(text: string, query: string, maxMatches?: number): TransliterationMatch[];
+}
+```
+
+### Table customization and transformation
+
+Supply 0..1024 entries with unique, nonempty `source` (<=32 UTF-16 units) and `target`
+(0..64 UTF-16 units). Empty targets mean deletion. Tables are copied into a code-point trie.
+Entries are read by bounded array indexes, not through caller-overridden iterators.
+The **longest matching source** at each original code-point boundary wins, independent of
+table order; replacements are not recursively processed. Unmatched code points pass through.
+Empty tables perform identity transformation.
+
+`maxInput` is an integer 1..65,536, default 65,536 UTF-16 units.
+`maxOutput` is an integer 1..262,144, default 262,144 UTF-16 units.
+These options may lower limits but cannot remove the hard bounds. Output is checked incrementally.
+All source, target, input and query strings must have paired UTF-16 surrogates.
+
+There is no automatic case folding, normalization, mark stripping, whitespace rewriting,
+locale detection or recursive application. Supply exactly the mappings your application needs;
+canonically equivalent forms need explicit entries if you want equivalent search behavior.
+
+### Stable interval mapping
+
+All coordinates are half-open UTF-16 ranges. Each consumed source entry/code point records one
+span, including zero-width transformed spans for deletions. Expansion/contraction substrings
+map back to the **entire consumed original source**, not an invented per-letter position.
+
+`originalRange(start, end)` accepts transformed offsets that do not split surrogate pairs:
+
+- Nonempty ranges return the smallest original interval covering overlapping nonempty spans.
+  Deleted interior text is included in that interval; deletions at the edges are excluded.
+- A collapsed range uses right bias: the next nonempty span's original start, or the containing
+  expansion's original start when inside it. At transformed end it maps to original end,
+  including trailing deletions; fully deleted input maps to original end.
+- Exposed spans are detached copies. Mutating them or returned text properties does not alter
+  the closure's captured mapping.
+
+```js
+import { createTransliterator } from '@lp-labs/transliteration-search';
+
+const engine = createTransliterator([
+  { source: '-', target: '' },
+  { source: 'ß', target: 'ss' },
+]);
+const result = engine.transliterate('-a-b-');
+const full = result.originalRange(0, 2);
+if (full.start !== 1 || full.end !== 4) throw new Error('Deletion interval failed');
+if (result.originalRange(2, 2).start !== 5) throw new Error('Trailing deletion bias failed');
+if (engine.find('ß', 's').length !== 2) throw new Error('Expansion hits must remain distinct');
+```
+
+### Search
+
+`find` transforms both text and query with the same table/limits, then uses case-sensitive
+literal substring matching. It returns stable nonoverlapping **transformed** hits, mapped to
+original ranges. Two expansion hits can map to the same original range; they are not deduplicated.
+`maxMatches` is an integer 1..256, default 100; reaching it truncates results without error.
+An empty or fully deleted query is rejected. No fuzzy scoring or regular-expression query syntax.
+
+## Errors, work bounds and limits
+
+Wrong types, duplicate/empty sources, unpaired surrogates and empty transformed queries throw
+`TypeError`. Table/string/options/output bounds, invalid range ordering/offsets, split-surrogate
+offsets and invalid hit limits throw `RangeError`. No coercion or partial output is returned.
+
+Trie construction uses at most 32,768 source UTF-16 units. Transformation examines at most 32
+source units per input position and stores <=65,536 spans, with <=262,144 output units.
+Mapping scans spans in O(S). Search delegates substring scanning to JavaScript and performs
+at most 256 O(S) mappings. Both transformed text and query have independent output bounds.
+No assumptions about browser selection, grapheme alignment or global transliteration accuracy.
+
+## Development
+
+`npm ci --offline`, `npm run build`, `npm run typecheck`, `npm test`,
+`npm run format`, `npm run format:check`. Cached dev packages are needed for offline installs.
+TypeScript ^5.9.3 and Prettier ^3.6.2 are development-only dependencies.
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,33 @@
+export interface TransliterationEntry {
+    source: string;
+    target: string;
+}
+export interface TransliterationOptions {
+    maxInput?: number;
+    maxOutput?: number;
+}
+export interface SourceSpan {
+    originalStart: number;
+    originalEnd: number;
+    transformedStart: number;
+    transformedEnd: number;
+}
+export interface OriginalRange {
+    start: number;
+    end: number;
+}
+export interface TransliteratedText {
+    original: string;
+    text: string;
+    spans: SourceSpan[];
+    originalRange(start: number, end: number): OriginalRange;
+}
+export interface TransliterationMatch extends OriginalRange {
+    transformedStart: number;
+    transformedEnd: number;
+}
+export interface Transliterator {
+    transliterate(text: string): TransliteratedText;
+    find(text: string, query: string, maxMatches?: number): TransliterationMatch[];
+}
+export declare function createTransliterator(entries: readonly TransliterationEntry[], options?: TransliterationOptions): Transliterator;

package/dist/cjs/index.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTransliterator = createTransliterator;
+function bound(value, maximum) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum)
+        throw new RangeError(`Expected integer in 1..${maximum}.`);
+    return value;
+}
+function validText(value, maximum) {
+    if (typeof value !== 'string')
+        throw new TypeError('Expected text.');
+    if (value.length > maximum)
+        throw new RangeError('Text exceeds UTF-16 length bound.');
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(++i);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                throw new TypeError('Unpaired high surrogate.');
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            throw new TypeError('Unpaired low surrogate.');
+    }
+}
+function offset(value, text) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > text.length)
+        throw new RangeError('Offset outside transformed text.');
+    if (value > 0 &&
+        value < text.length &&
+        /[\uD800-\uDBFF]/.test(text[value - 1]) &&
+        /[\uDC00-\uDFFF]/.test(text[value]))
+        throw new RangeError('Offset splits a surrogate pair.');
+}
+function createTransliterator(entries, options = {}) {
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+        throw new TypeError('Expected options object.');
+    const maxInput = bound(options.maxInput === undefined ? 65_536 : options.maxInput, 65_536);
+    const maxOutput = bound(options.maxOutput === undefined ? 262_144 : options.maxOutput, 262_144);
+    if (!Array.isArray(entries))
+        throw new TypeError('Expected an array of entries.');
+    if (entries.length > 1024)
+        throw new RangeError('Expected up to 1024 entries.');
+    const root = { children: new Map() };
+    const count = entries.length;
+    for (let index = 0; index < count; index++) {
+        const entry = entries[index];
+        if (!entry || typeof entry !== 'object')
+            throw new TypeError('Expected table entry.');
+        validText(entry.source, 32);
+        validText(entry.target, 64);
+        if (!entry.source.length)
+            throw new TypeError('Source cannot be empty.');
+        let node = root;
+        for (const char of entry.source) {
+            let child = node.children.get(char);
+            if (!child) {
+                child = { children: new Map() };
+                node.children.set(char, child);
+            }
+            node = child;
+        }
+        if (node.target !== undefined)
+            throw new TypeError('Duplicate source.');
+        node.target = entry.target;
+    }
+    const transliterate = (original) => {
+        validText(original, maxInput);
+        const spans = [];
+        const parts = [];
+        let length = 0;
+        for (let start = 0; start < original.length;) {
+            const first = String.fromCodePoint(original.codePointAt(start));
+            let end = start + first.length;
+            let replacement = first;
+            let node = root;
+            for (let cursor = start; cursor < original.length;) {
+                const char = String.fromCodePoint(original.codePointAt(cursor));
+                const next = node.children.get(char);
+                if (!next)
+                    break;
+                node = next;
+                cursor += char.length;
+                if (node.target !== undefined) {
+                    replacement = node.target;
+                    end = cursor;
+                }
+            }
+            if (length + replacement.length > maxOutput)
+                throw new RangeError('Output exceeds maxOutput.');
+            spans.push({
+                originalStart: start,
+                originalEnd: end,
+                transformedStart: length,
+                transformedEnd: length + replacement.length,
+            });
+            parts.push(replacement);
+            length += replacement.length;
+            start = end;
+        }
+        const text = parts.join('');
+        return {
+            original,
+            text,
+            spans: spans.map((span) => ({ ...span })),
+            originalRange(start, end) {
+                offset(start, text);
+                offset(end, text);
+                if (start > end)
+                    throw new RangeError('Reversed transformed range.');
+                if (start === end) {
+                    const span = spans.find((part) => part.transformedEnd > start);
+                    const position = span?.originalStart ?? original.length;
+                    return { start: position, end: position };
+                }
+                const overlapping = spans.filter((part) => part.transformedEnd > start &&
+                    part.transformedStart < end &&
+                    part.transformedEnd > part.transformedStart);
+                return {
+                    start: overlapping[0].originalStart,
+                    end: overlapping[overlapping.length - 1].originalEnd,
+                };
+            },
+        };
+    };
+    return {
+        transliterate,
+        find(text, query, maxMatches = 100) {
+            bound(maxMatches, 256);
+            const source = transliterate(text);
+            const needle = transliterate(query).text;
+            if (!needle.length)
+                throw new TypeError('Query cannot transliterate to empty text.');
+            const matches = [];
+            let cursor = 0;
+            while (matches.length < maxMatches) {
+                const start = source.text.indexOf(needle, cursor);
+                if (start < 0)
+                    break;
+                const end = start + needle.length;
+                const range = source.originalRange(start, end);
+                matches.push({ ...range, transformedStart: start, transformedEnd: end });
+                cursor = end;
+            }
+            return matches;
+        },
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,33 @@
+export interface TransliterationEntry {
+    source: string;
+    target: string;
+}
+export interface TransliterationOptions {
+    maxInput?: number;
+    maxOutput?: number;
+}
+export interface SourceSpan {
+    originalStart: number;
+    originalEnd: number;
+    transformedStart: number;
+    transformedEnd: number;
+}
+export interface OriginalRange {
+    start: number;
+    end: number;
+}
+export interface TransliteratedText {
+    original: string;
+    text: string;
+    spans: SourceSpan[];
+    originalRange(start: number, end: number): OriginalRange;
+}
+export interface TransliterationMatch extends OriginalRange {
+    transformedStart: number;
+    transformedEnd: number;
+}
+export interface Transliterator {
+    transliterate(text: string): TransliteratedText;
+    find(text: string, query: string, maxMatches?: number): TransliterationMatch[];
+}
+export declare function createTransliterator(entries: readonly TransliterationEntry[], options?: TransliterationOptions): Transliterator;

package/dist/esm/index.js

@@ -0,0 +1,144 @@
+function bound(value, maximum) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum)
+        throw new RangeError(`Expected integer in 1..${maximum}.`);
+    return value;
+}
+function validText(value, maximum) {
+    if (typeof value !== 'string')
+        throw new TypeError('Expected text.');
+    if (value.length > maximum)
+        throw new RangeError('Text exceeds UTF-16 length bound.');
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(++i);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                throw new TypeError('Unpaired high surrogate.');
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            throw new TypeError('Unpaired low surrogate.');
+    }
+}
+function offset(value, text) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > text.length)
+        throw new RangeError('Offset outside transformed text.');
+    if (value > 0 &&
+        value < text.length &&
+        /[\uD800-\uDBFF]/.test(text[value - 1]) &&
+        /[\uDC00-\uDFFF]/.test(text[value]))
+        throw new RangeError('Offset splits a surrogate pair.');
+}
+export function createTransliterator(entries, options = {}) {
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+        throw new TypeError('Expected options object.');
+    const maxInput = bound(options.maxInput === undefined ? 65_536 : options.maxInput, 65_536);
+    const maxOutput = bound(options.maxOutput === undefined ? 262_144 : options.maxOutput, 262_144);
+    if (!Array.isArray(entries))
+        throw new TypeError('Expected an array of entries.');
+    if (entries.length > 1024)
+        throw new RangeError('Expected up to 1024 entries.');
+    const root = { children: new Map() };
+    const count = entries.length;
+    for (let index = 0; index < count; index++) {
+        const entry = entries[index];
+        if (!entry || typeof entry !== 'object')
+            throw new TypeError('Expected table entry.');
+        validText(entry.source, 32);
+        validText(entry.target, 64);
+        if (!entry.source.length)
+            throw new TypeError('Source cannot be empty.');
+        let node = root;
+        for (const char of entry.source) {
+            let child = node.children.get(char);
+            if (!child) {
+                child = { children: new Map() };
+                node.children.set(char, child);
+            }
+            node = child;
+        }
+        if (node.target !== undefined)
+            throw new TypeError('Duplicate source.');
+        node.target = entry.target;
+    }
+    const transliterate = (original) => {
+        validText(original, maxInput);
+        const spans = [];
+        const parts = [];
+        let length = 0;
+        for (let start = 0; start < original.length;) {
+            const first = String.fromCodePoint(original.codePointAt(start));
+            let end = start + first.length;
+            let replacement = first;
+            let node = root;
+            for (let cursor = start; cursor < original.length;) {
+                const char = String.fromCodePoint(original.codePointAt(cursor));
+                const next = node.children.get(char);
+                if (!next)
+                    break;
+                node = next;
+                cursor += char.length;
+                if (node.target !== undefined) {
+                    replacement = node.target;
+                    end = cursor;
+                }
+            }
+            if (length + replacement.length > maxOutput)
+                throw new RangeError('Output exceeds maxOutput.');
+            spans.push({
+                originalStart: start,
+                originalEnd: end,
+                transformedStart: length,
+                transformedEnd: length + replacement.length,
+            });
+            parts.push(replacement);
+            length += replacement.length;
+            start = end;
+        }
+        const text = parts.join('');
+        return {
+            original,
+            text,
+            spans: spans.map((span) => ({ ...span })),
+            originalRange(start, end) {
+                offset(start, text);
+                offset(end, text);
+                if (start > end)
+                    throw new RangeError('Reversed transformed range.');
+                if (start === end) {
+                    const span = spans.find((part) => part.transformedEnd > start);
+                    const position = span?.originalStart ?? original.length;
+                    return { start: position, end: position };
+                }
+                const overlapping = spans.filter((part) => part.transformedEnd > start &&
+                    part.transformedStart < end &&
+                    part.transformedEnd > part.transformedStart);
+                return {
+                    start: overlapping[0].originalStart,
+                    end: overlapping[overlapping.length - 1].originalEnd,
+                };
+            },
+        };
+    };
+    return {
+        transliterate,
+        find(text, query, maxMatches = 100) {
+            bound(maxMatches, 256);
+            const source = transliterate(text);
+            const needle = transliterate(query).text;
+            if (!needle.length)
+                throw new TypeError('Query cannot transliterate to empty text.');
+            const matches = [];
+            let cursor = 0;
+            while (matches.length < maxMatches) {
+                const start = source.text.indexOf(needle, cursor);
+                if (start < 0)
+                    break;
+                const end = start + needle.length;
+                const range = source.originalRange(start, end);
+                matches.push({ ...range, transformedStart: start, transformedEnd: end });
+                cursor = end;
+            }
+            return matches;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/transliteration-search",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Caller-table transliteration and bounded literal search with original UTF-16 interval mapping.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build && node scripts/check-types.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}