@volter/twin-algolia 0.1.0

package/dist/src/algolia-filter.js

@@ -0,0 +1,125 @@
+function parseFacetToken(token) {
+    const idx = token.indexOf(':');
+    if (idx < 0)
+        return undefined;
+    const field = token.slice(0, idx).trim();
+    let value = token.slice(idx + 1).trim();
+    let negate = false;
+    if (value.startsWith('-')) {
+        negate = true;
+        value = value.slice(1);
+    }
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+    }
+    return { field, value, negate };
+}
+function facetValueMatches(recordValue, wanted) {
+    if (Array.isArray(recordValue))
+        return recordValue.some((v) => String(v) === wanted);
+    if (recordValue === undefined || recordValue === null)
+        return false;
+    return String(recordValue) === wanted;
+}
+/** Evaluate a single `facetFilters` clause (a bare "field:value" string, or an OR-array of them)
+ *  against a record. An absent/empty facetFilters matches everything. */
+export function matchesFacetFilters(record, facetFilters) {
+    if (!facetFilters || facetFilters.length === 0)
+        return true;
+    for (const clause of facetFilters) {
+        const items = Array.isArray(clause) ? clause : [clause];
+        // outer array element: AND with the rest; an array-of-strings ELEMENT is itself an OR group.
+        const orMatch = items.some((token) => {
+            const parsed = parseFacetToken(token);
+            if (!parsed)
+                return false;
+            const matched = facetValueMatches(record[parsed.field], parsed.value);
+            return parsed.negate ? !matched : matched;
+        });
+        if (!orMatch)
+            return false;
+    }
+    return true;
+}
+const COMPARE_RE = /^(\S+)\s*(>=|<=|!=|>|<|=)\s*(-?\d+(?:\.\d+)?)$/;
+function parseClause(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    let text = trimmed;
+    let negate = false;
+    if (text.startsWith('NOT ')) {
+        negate = true;
+        text = text.slice(4).trim();
+    }
+    const cmp = COMPARE_RE.exec(text);
+    if (cmp) {
+        const [, field, op, num] = cmp;
+        return { kind: 'compare', c: { field: field, op: (negate ? negateOp(op) : op), value: Number(num) } };
+    }
+    const facet = parseFacetToken(text);
+    if (facet)
+        return { kind: 'facet', c: { field: facet.field, value: facet.value, negate: negate !== facet.negate } };
+    return undefined;
+}
+function negateOp(op) {
+    const table = { '>': '<=', '>=': '<', '<': '>=', '<=': '>', '=': '!=', '!=': '=' };
+    return table[op];
+}
+function evalClause(record, clause) {
+    if (clause.kind === 'facet') {
+        const matched = facetValueMatches(record[clause.c.field], clause.c.value);
+        return clause.c.negate ? !matched : matched;
+    }
+    const raw = record[clause.c.field];
+    if (typeof raw !== 'number')
+        return false;
+    switch (clause.c.op) {
+        case '>':
+            return raw > clause.c.value;
+        case '>=':
+            return raw >= clause.c.value;
+        case '<':
+            return raw < clause.c.value;
+        case '<=':
+            return raw <= clause.c.value;
+        case '=':
+            return raw === clause.c.value;
+        case '!=':
+            return raw !== clause.c.value;
+    }
+}
+/** Evaluate an Algolia `filters` STRING against a stored record: AND binds tighter than OR,
+ *  evaluated as OR-of-AND-groups (no parenthesized precedence override — v1 honest cut). An
+ *  absent/empty/whitespace-only filter string matches everything. */
+export function matchesAlgoliaFilters(record, filters) {
+    if (!filters || filters.trim().length === 0)
+        return true;
+    const orGroups = filters.split(/\s+OR\s+/);
+    return orGroups.some((group) => group
+        .split(/\s+AND\s+/)
+        .map((raw) => parseClause(raw))
+        .every((clause) => (clause ? evalClause(record, clause) : true)));
+}
+/**
+ * REAL facet-count aggregation over an already-matched-and-filtered record set (conjunctive —
+ * counts reflect the final hit set, not a per-facet disjunctive relaxation — disjunctive facet
+ * counting is `facets.disjunctive_facets`, todo). Multi-value (array) facet attributes count
+ * each element once per record — a genuine tally, not a name check.
+ */
+export function computeFacetCounts(records, facetAttributes) {
+    const out = {};
+    for (const attr of facetAttributes) {
+        const counts = {};
+        for (const r of records) {
+            const v = r[attr];
+            const values = Array.isArray(v) ? v : v === undefined || v === null ? [] : [v];
+            for (const one of values) {
+                const key = String(one);
+                counts[key] = (counts[key] ?? 0) + 1;
+            }
+        }
+        out[attr] = counts;
+    }
+    return out;
+}

package/dist/src/algolia-search.d.ts

@@ -0,0 +1,42 @@
+export type CustomRankingRule = {
+    attribute: string;
+    direction: 'asc' | 'desc';
+};
+export type SearchRecord = Record<string, unknown> & {
+    objectID: string;
+};
+/** Deterministic ASCII/Unicode tokenizer: lowercase, split on runs of non letter/number
+ *  characters. This is the line `algolia.search.language_processing` (todo) will move: no
+ *  stemming/plural-folding/CJK segmentation/language normalization yet — just a real,
+ *  deterministic word-boundary split. */
+export declare function tokenize(text: string): string[];
+/** Real Damerau-Levenshtein edit distance (insertions/deletions/substitutions/adjacent
+ *  transpositions) — a genuine DP table, not an approximation. */
+export declare function damerauLevenshtein(a: string, b: string): number;
+/** All values a group of interchangeable synonym words maps to each other, lowercase. A word's
+ *  group includes itself. Basic bidirectional `type:"synonym"` groups only — one-way/altCorrection/
+ *  placeholder synonyms are `search.optional_words`-adjacent todos (synonyms.one_way etc). */
+export declare function buildSynonymGroups(synonymRecords: ReadonlyArray<{
+    type?: string;
+    synonyms?: readonly string[];
+}>): string[][];
+export type RankedHit<T extends SearchRecord = SearchRecord> = {
+    record: T;
+    typoTotal: number;
+    attributeIndex: number;
+    proximity: number;
+    exactCount: number;
+};
+/**
+ * Match + rank records against a query — the pack's signature strong-`done`. Returns every
+ * MATCHING record, best-first, per the faithful-subset tie-break chain: typo -> attribute
+ * (earlier configured attribute wins) -> proximity -> exact -> customRanking -> objectID
+ * (final deterministic tie-break). An empty/whitespace query matches every record (real
+ * Algolia's browse-all-via-empty-query convention) with every criterion tied, so ordering then
+ * falls straight to customRanking / objectID.
+ */
+export declare function rankRecords<T extends SearchRecord>(records: readonly T[], query: string, opts?: {
+    searchableAttributes?: readonly string[];
+    customRanking?: readonly CustomRankingRule[];
+    synonymGroups?: readonly string[][];
+}): RankedHit<T>[];

package/dist/src/algolia-search.js

@@ -0,0 +1,174 @@
+/** Deterministic ASCII/Unicode tokenizer: lowercase, split on runs of non letter/number
+ *  characters. This is the line `algolia.search.language_processing` (todo) will move: no
+ *  stemming/plural-folding/CJK segmentation/language normalization yet — just a real,
+ *  deterministic word-boundary split. */
+export function tokenize(text) {
+    return text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+}
+/** Real Damerau-Levenshtein edit distance (insertions/deletions/substitutions/adjacent
+ *  transpositions) — a genuine DP table, not an approximation. */
+export function damerauLevenshtein(a, b) {
+    const al = a.length;
+    const bl = b.length;
+    if (al === 0)
+        return bl;
+    if (bl === 0)
+        return al;
+    const d = Array.from({ length: al + 1 }, () => new Array(bl + 1).fill(0));
+    for (let i = 0; i <= al; i++)
+        d[i][0] = i;
+    for (let j = 0; j <= bl; j++)
+        d[0][j] = j;
+    for (let i = 1; i <= al; i++) {
+        for (let j = 1; j <= bl; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            let v = Math.min(d[i - 1][j] + 1, //      deletion
+            d[i][j - 1] + 1, //      insertion
+            d[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                v = Math.min(v, d[i - 2][j - 2] + cost); // adjacent transposition
+            }
+            d[i][j] = v;
+        }
+    }
+    return d[al][bl];
+}
+const MAX_TYPOS = 2;
+/** All values a group of interchangeable synonym words maps to each other, lowercase. A word's
+ *  group includes itself. Basic bidirectional `type:"synonym"` groups only — one-way/altCorrection/
+ *  placeholder synonyms are `search.optional_words`-adjacent todos (synonyms.one_way etc). */
+export function buildSynonymGroups(synonymRecords) {
+    const groups = [];
+    for (const s of synonymRecords) {
+        if (s.type !== 'synonym' || !Array.isArray(s.synonyms) || s.synonyms.length < 2)
+            continue;
+        groups.push(s.synonyms.map((w) => w.toLowerCase()));
+    }
+    return groups;
+}
+function sameSynonymGroup(a, b, groups) {
+    for (const g of groups)
+        if (g.includes(a) && g.includes(b))
+            return true;
+    return false;
+}
+/** Distance between a query word and a candidate token: 0 for exact or same-synonym-group,
+ *  else the Damerau-Levenshtein edit distance capped at MAX_TYPOS, else `undefined` (no match
+ *  at all — the record does not satisfy this query word via this token). */
+function wordDistance(queryWord, token, synonymGroups) {
+    if (queryWord === token)
+        return 0;
+    if (sameSynonymGroup(queryWord, token, synonymGroups))
+        return 0;
+    const d = damerauLevenshtein(queryWord, token);
+    return d <= MAX_TYPOS ? d : undefined;
+}
+/** Flatten one attribute's stored value into a token list (string, array-of-strings/values, or
+ *  a scalar stringified) — non-string/array/number/boolean values (objects, null, undefined)
+ *  contribute no tokens. */
+function tokensForAttributeValue(value) {
+    if (typeof value === 'string')
+        return tokenize(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return tokenize(String(value));
+    if (Array.isArray(value))
+        return value.flatMap((v) => tokensForAttributeValue(v));
+    return [];
+}
+/** Try to match every query word within ONE attribute's token list; undefined if any query word
+ *  finds no token in this attribute within MAX_TYPOS. */
+function matchWithinAttribute(tokens, queryWords, synonymGroups, attributeIndex) {
+    if (tokens.length === 0)
+        return undefined;
+    const positions = [];
+    let typoTotal = 0;
+    let exactCount = 0;
+    for (const qw of queryWords) {
+        let best;
+        for (let i = 0; i < tokens.length; i++) {
+            const d = wordDistance(qw, tokens[i], synonymGroups);
+            if (d !== undefined && (!best || d < best.typos))
+                best = { idx: i, typos: d };
+        }
+        if (!best)
+            return undefined;
+        positions.push(best.idx);
+        typoTotal += best.typos;
+        if (best.typos === 0)
+            exactCount++;
+    }
+    const proximity = positions.length > 0 ? Math.max(...positions) - Math.min(...positions) : 0;
+    return { attributeIndex, typoTotal, exactCount, proximity };
+}
+/** Default searchable-attribute order when settings.searchableAttributes is unset: every
+ *  top-level field except objectID, in a deterministic sorted order. Real Algolia treats every
+ *  attribute as equally searchable when unconfigured (no attribute-priority distinction) — this
+ *  twin's sorted-key stand-in only matters for tie-breaking when the caller HAS configured an
+ *  explicit order (search.attributes_to_retrieve / settings.searchable_attributes_affects_search). */
+function defaultSearchableAttributes(records) {
+    const keys = new Set();
+    for (const r of records)
+        for (const k of Object.keys(r))
+            if (k !== 'objectID')
+                keys.add(k);
+    return [...keys].sort();
+}
+function customRankingCompare(a, b, rules) {
+    for (const rule of rules) {
+        const av = a[rule.attribute];
+        const bv = b[rule.attribute];
+        const an = typeof av === 'number' ? av : Number.NEGATIVE_INFINITY;
+        const bn = typeof bv === 'number' ? bv : Number.NEGATIVE_INFINITY;
+        if (an === bn)
+            continue;
+        return rule.direction === 'desc' ? bn - an : an - bn;
+    }
+    return 0;
+}
+/**
+ * Match + rank records against a query — the pack's signature strong-`done`. Returns every
+ * MATCHING record, best-first, per the faithful-subset tie-break chain: typo -> attribute
+ * (earlier configured attribute wins) -> proximity -> exact -> customRanking -> objectID
+ * (final deterministic tie-break). An empty/whitespace query matches every record (real
+ * Algolia's browse-all-via-empty-query convention) with every criterion tied, so ordering then
+ * falls straight to customRanking / objectID.
+ */
+export function rankRecords(records, query, opts = {}) {
+    const attrs = opts.searchableAttributes && opts.searchableAttributes.length > 0 ? opts.searchableAttributes : defaultSearchableAttributes(records);
+    const customRanking = opts.customRanking ?? [];
+    const synonymGroups = opts.synonymGroups ?? [];
+    const queryWords = tokenize(query);
+    const hits = [];
+    for (const record of records) {
+        if (queryWords.length === 0) {
+            hits.push({ record, typoTotal: 0, attributeIndex: 0, proximity: 0, exactCount: 0 });
+            continue;
+        }
+        let best;
+        for (let i = 0; i < attrs.length; i++) {
+            const tokens = tokensForAttributeValue(record[attrs[i]]);
+            const m = matchWithinAttribute(tokens, queryWords, synonymGroups, i);
+            if (!m)
+                continue;
+            if (!best || m.typoTotal < best.typoTotal || (m.typoTotal === best.typoTotal && m.attributeIndex < best.attributeIndex))
+                best = m;
+        }
+        if (best)
+            hits.push({ record, typoTotal: best.typoTotal, attributeIndex: best.attributeIndex, proximity: best.proximity, exactCount: best.exactCount });
+    }
+    hits.sort((a, b) => {
+        if (a.typoTotal !== b.typoTotal)
+            return a.typoTotal - b.typoTotal;
+        if (a.attributeIndex !== b.attributeIndex)
+            return a.attributeIndex - b.attributeIndex;
+        if (a.proximity !== b.proximity)
+            return a.proximity - b.proximity;
+        if (a.exactCount !== b.exactCount)
+            return b.exactCount - a.exactCount;
+        const custom = customRankingCompare(a.record, b.record, customRanking);
+        if (custom !== 0)
+            return custom;
+        return a.record.objectID < b.record.objectID ? -1 : a.record.objectID > b.record.objectID ? 1 : 0;
+    });
+    return hits;
+}

package/dist/src/algolia-server.d.ts

@@ -0,0 +1,14 @@
+/** Options every Algolia-twin HTTP surface needs, independent of who owns the socket. */
+export interface AlgoliaTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+export declare function createAlgoliaTwinFetch(options?: AlgoliaTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createAlgoliaTwinServer(options?: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/algolia-server.js

@@ -0,0 +1,35 @@
+// Algolia twin HTTP server — ONE process serving every host shape a real `algoliasearch` SDK (or
+// raw REST caller) might target, so an unmodified SDK works end-to-end against a single local
+// process. Unlike pinecone's control/data HOST split, Algolia's REST paths already carry the
+// index name (`/1/indexes/{indexName}/...`), so this server does zero host-based dispatch — the
+// literal HTTP `Host` header (or, for the SDK-integration test's proxy-rewrite pattern, an
+// `x-algolia-target-host` stash) is threaded through purely for `routeAlgoliaSurface`'s host-
+// tolerance proof (see algolia-twin.ts's header); routing itself is 100% path-driven.
+//
+// Writable by default; pass readOnly to reject writes (per-operation — see algolia-twin.ts).
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler`) with the host threading as its per-request
+// `extras`; the server is one line of Bun.serve around that same closure.
+import { serveHttp } from '@volter/world-core';
+import { handleAlgoliaTwinRequest } from "./algolia-twin.js";
+import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+export function createAlgoliaTwinFetch(options = {}) {
+    return createTwinFetchFromHandler(handleAlgoliaTwinRequest, {
+        ...options,
+        manifest: statefulTwinManifest({ vendor: 'algolia', twinOf: 'Algolia hosted search', stores: 'indexes and their records (CRUD + batch), searched by a real local engine' }),
+        // `Headers` iteration already lower-cases every name, so the adapter's header map matches the
+        // one this server used to build by hand.
+        extras: (request, url) => ({
+            host: request.headers.get('x-algolia-target-host') || request.headers.get('host') || url.host,
+        }),
+    });
+}
+export async function createAlgoliaTwinServer(options = {}) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createAlgoliaTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/dist/src/algolia-twin.d.ts

@@ -0,0 +1,45 @@
+export type AlgoliaRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string>;
+    /** Effective request host (real Host header, or the SDK-integration-test's target host). Fed
+     *  through routeAlgoliaSurface/recoverAppIdFromHost purely for host-tolerance proof. */
+    host?: string;
+    /** Explicit appId override — the twin's OWN verifies use this directly (spec §6's documented
+     *  fallback, mirrors pinecone's `index` field) instead of round-tripping through a host. */
+    appId?: string;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+};
+export type AlgoliaResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+export declare const ALGOLIA_RESOURCE_TYPES: readonly ["index", "record", "synonym"];
+export type AlgoliaResourceType = typeof ALGOLIA_RESOURCE_TYPES[number];
+export type AlgoliaSurface = 'api';
+/** Canonical WRITE-host form for an appId — real Algolia hosts literally embed the appId as a
+ *  losslessly-recoverable prefix (unlike pinecone's synthetic per-index hash host), so no hash
+ *  is needed; `root` is accepted for signature symmetry with pinecone's mintHost but does not
+ *  affect the output (documented, not a bug — there is nothing per-root to disambiguate: the
+ *  appId already IS the whole identity a host shape encodes). */
+export declare function mintHost(appId: string, _root?: string): string;
+/** Recover an appId from ANY of the three real host shapes (or a bare Host: port-suffixed
+ *  variant), tolerating whichever one a caller presents. Returns undefined for an unrecognized
+ *  shape. */
+export declare function recoverAppIdFromHost(host: string | undefined): string | undefined;
+/** Accepts EVERY real host shape (and no host at all) — always resolves to the single `'api'`
+ *  surface; actual dispatch is by PATH alone (see file header). */
+export declare function routeAlgoliaSurface(_req: {
+    host?: string;
+    path: string;
+}): AlgoliaSurface;
+export declare function handleAlgoliaTwinRequest(req: AlgoliaRequest): Promise<AlgoliaResponse>;
+export type AlgoliaTwinSnapshot = {
+    resourceTypes: readonly AlgoliaResourceType[];
+    implementedEndpoints: readonly string[];
+};
+export declare function algoliaTwinSnapshot(): AlgoliaTwinSnapshot;