@resistdesign/voltra 3.0.0-alpha.2 → 3.0.0-alpha.21

package/api/Indexing/structured/StructuredDdbBackend.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @packageDocumentation
+ *
+ * DynamoDB-backed structured indexing reader/writer implementations.
+ */
+import type { DynamoQueryClient } from "../ddb/Types";
+import type { DocId } from "../Types";
+import type { StructuredSearchDependencies } from "./SearchStructured";
+import type { StructuredQueryOptions, WhereValue } from "./Types";
+import { StructuredDdbWriter } from "./StructuredWriter";
+/**
+ * Deployment-specific DynamoDB table names required for structured indexing.
+ */
+export type StructuredTableNames = {
+    termIndex: string;
+    rangeIndex: string;
+    docFields: string;
+};
+/**
+ * Configuration for structured DynamoDB backends.
+ *
+ * Table names are required and should be injected per deployment.
+ */
+type StructuredDdbConfig = {
+    client: DynamoQueryClient;
+    tables: StructuredTableNames;
+};
+/**
+ * Read-only structured queries against DynamoDB term/range indexes.
+ */
+export declare class StructuredDdbReader implements StructuredSearchDependencies {
+    private readonly client;
+    private readonly termTableName;
+    private readonly rangeTableName;
+    /**
+     * @param config DynamoDB config for structured tables.
+     */
+    constructor(config: StructuredDdbConfig);
+    /**
+     * Term query implementation for structured search.
+     */
+    terms: {
+        /**
+         * @param field Field name to query.
+         * @param mode Term match mode.
+         * @param value Value to match.
+         * @param options Optional paging options.
+         * @returns Candidate page with optional cursor token.
+         */
+        query: (field: string, mode: "eq" | "contains", value: WhereValue, options?: StructuredQueryOptions) => Promise<{
+            candidateIds: DocId[];
+            lastEvaluatedKey?: string;
+        }>;
+    };
+    /**
+     * Range query implementation for structured search.
+     */
+    ranges: {
+        /**
+         * @param field Field name to query.
+         * @param lower Inclusive lower bound.
+         * @param upper Inclusive upper bound.
+         * @param options Optional paging options.
+         * @returns Candidate page with optional cursor token.
+         */
+        between: (field: string, lower: WhereValue, upper: WhereValue, options?: StructuredQueryOptions) => Promise<{
+            candidateIds: DocId[];
+            lastEvaluatedKey?: string;
+        }>;
+        /**
+         * @param field Field name to query.
+         * @param lower Inclusive lower bound.
+         * @param options Optional paging options.
+         * @returns Candidate page with optional cursor token.
+         */
+        gte: (field: string, lower: WhereValue, options?: StructuredQueryOptions) => Promise<{
+            candidateIds: DocId[];
+            lastEvaluatedKey?: string;
+        }>;
+        /**
+         * @param field Field name to query.
+         * @param upper Inclusive upper bound.
+         * @param options Optional paging options.
+         * @returns Candidate page with optional cursor token.
+         */
+        lte: (field: string, upper: WhereValue, options?: StructuredQueryOptions) => Promise<{
+            candidateIds: DocId[];
+            lastEvaluatedKey?: string;
+        }>;
+    };
+}
+/**
+ * Convenience wrapper that exposes both the reader and writer.
+ */
+export declare class StructuredDdbBackend {
+    /**
+     * Reader implementation for structured queries.
+     */
+    readonly reader: StructuredSearchDependencies;
+    /**
+     * Writer implementation for structured indexing.
+     */
+    readonly writer: StructuredDdbWriter;
+    /**
+     * @param config DynamoDB config for structured tables.
+     */
+    constructor(config: StructuredDdbConfig);
+}
+export {};

package/api/Indexing/structured/StructuredInMemoryBackend.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @packageDocumentation
+ *
+ * In-memory backend that wires {@link StructuredInMemoryIndex} to the structured
+ * search interfaces and write contract.
+ */
+import type { DocId } from "../Types";
+import type { StructuredSearchDependencies } from "./SearchStructured";
+import type { StructuredWriter } from "./Handlers";
+import type { StructuredDocFieldsRecord } from "./StructuredDdb";
+/**
+ * In-memory structured backend for tests and local usage.
+ */
+export declare class StructuredInMemoryBackend implements StructuredSearchDependencies, StructuredWriter {
+    private docFields;
+    private index;
+    private rebuildIndex;
+    private buildPage;
+    /**
+     * Term query implementation for structured search.
+     */
+    terms: StructuredSearchDependencies["terms"];
+    /**
+     * Range query implementation for structured search.
+     */
+    ranges: StructuredSearchDependencies["ranges"];
+    /**
+     * Write structured fields for a document.
+     * @param docId Document id to write.
+     * @param fields Structured fields to store.
+     * @returns Promise resolved once stored.
+     */
+    write(docId: DocId, fields: StructuredDocFieldsRecord): Promise<void>;
+}

package/api/Indexing/structured/StructuredInMemoryIndex.d.ts

@@ -0,0 +1,58 @@
+import type { DocId } from "../Types";
+import type { CandidatePage, StructuredQueryOptions, WhereValue } from "./Types";
+/**
+ * In-memory structured index that builds term/contains/range postings.
+ */
+export declare class StructuredInMemoryIndex {
+    private eqIndex;
+    private containsIndex;
+    private rangeIndex;
+    /**
+     * Add a document record to the index.
+     * @param docId Document id to index.
+     * @param record Structured field record for the document.
+     * @returns Nothing.
+     */
+    addDocument(docId: DocId, record: Record<string, WhereValue | WhereValue[]>): void;
+    /**
+     * Run an equality query for a field/value pair.
+     * @param field Field name to query.
+     * @param value Value to match.
+     * @param options Optional paging options.
+     * @returns Candidate page of matching document ids.
+     */
+    eq(field: string, value: WhereValue, options?: StructuredQueryOptions): CandidatePage;
+    /**
+     * Run a contains query for a field/value pair.
+     * @param field Field name to query.
+     * @param value Value to match.
+     * @param options Optional paging options.
+     * @returns Candidate page of matching document ids.
+     */
+    contains(field: string, value: WhereValue, options?: StructuredQueryOptions): CandidatePage;
+    /**
+     * Run a between range query for a field.
+     * @param field Field name to query.
+     * @param lower Inclusive lower bound.
+     * @param upper Inclusive upper bound.
+     * @param options Optional paging options.
+     * @returns Candidate page of matching document ids.
+     */
+    between(field: string, lower: WhereValue, upper: WhereValue, options?: StructuredQueryOptions): CandidatePage;
+    /**
+     * Run a greater-than-or-equal range query for a field.
+     * @param field Field name to query.
+     * @param lower Inclusive lower bound.
+     * @param options Optional paging options.
+     * @returns Candidate page of matching document ids.
+     */
+    gte(field: string, lower: WhereValue, options?: StructuredQueryOptions): CandidatePage;
+    /**
+     * Run a less-than-or-equal range query for a field.
+     * @param field Field name to query.
+     * @param upper Inclusive upper bound.
+     * @param options Optional paging options.
+     * @returns Candidate page of matching document ids.
+     */
+    lte(field: string, upper: WhereValue, options?: StructuredQueryOptions): CandidatePage;
+}

package/api/Indexing/structured/StructuredStringLike.d.ts

@@ -0,0 +1,25 @@
+import type { WhereValue } from "./Types";
+/**
+ * Prefix marker for structured string contains tokens.
+ */
+export declare const STRUCTURED_STRING_CONTAINS_TOKEN_PREFIX = "__str__:";
+/**
+ * Normalize a string for structured LIKE matching.
+ * - lowercase
+ * - trim
+ * - collapse internal whitespace
+ */
+export declare const normalizeStructuredLikeString: (value: string) => string;
+/**
+ * Build contains tokens for an indexed structured string field value.
+ */
+export declare const buildStructuredStringContainsTokens: (value: string) => string[];
+/**
+ * Build contains tokens for a SQL-like pattern. `%` and `_` are wildcard
+ * markers; when no wildcard exists, value behaves as `%value%`.
+ */
+export declare const buildStructuredLikePatternTokens: (value: string) => string[];
+/**
+ * True when this contains query value is a generated string token.
+ */
+export declare const isStructuredStringContainsToken: (value: WhereValue) => value is string;

package/api/Indexing/structured/StructuredWriter.d.ts

@@ -0,0 +1,61 @@
+import type { DocId } from "../Types";
+import type { StructuredDocFieldsRecord, StructuredRangeIndexItem, StructuredRangeIndexKey, StructuredTermIndexItem, StructuredTermIndexKey } from "./StructuredDdb";
+/**
+ * Dependencies required to persist structured index entries.
+ */
+export type StructuredWriterDependencies = {
+    /**
+     * Load previously stored fields for a document.
+     * @param docId Document id to load.
+     * @returns Stored fields or undefined when missing.
+     */
+    loadDocFields(docId: DocId): Promise<StructuredDocFieldsRecord | undefined>;
+    /**
+     * Store the latest fields for a document.
+     * @param docId Document id to store.
+     * @param fields Structured fields to persist.
+     * @returns Promise resolved once stored.
+     */
+    putDocFields(docId: DocId, fields: StructuredDocFieldsRecord): Promise<void>;
+    /**
+     * Store term index entries.
+     * @param entries Term entries to store.
+     * @returns Promise resolved once stored.
+     */
+    putTermEntries(entries: StructuredTermIndexItem[]): Promise<void>;
+    /**
+     * Delete term index entries.
+     * @param entries Term entry keys to delete.
+     * @returns Promise resolved once deleted.
+     */
+    deleteTermEntries(entries: StructuredTermIndexKey[]): Promise<void>;
+    /**
+     * Store range index entries.
+     * @param entries Range entries to store.
+     * @returns Promise resolved once stored.
+     */
+    putRangeEntries(entries: StructuredRangeIndexItem[]): Promise<void>;
+    /**
+     * Delete range index entries.
+     * @param entries Range entry keys to delete.
+     * @returns Promise resolved once deleted.
+     */
+    deleteRangeEntries(entries: StructuredRangeIndexKey[]): Promise<void>;
+};
+/**
+ * Writer that diffs structured fields and persists term/range entries.
+ */
+export declare class StructuredDdbWriter {
+    private readonly dependencies;
+    /**
+     * @param dependencies Writer dependencies for persistence.
+     */
+    constructor(dependencies: StructuredWriterDependencies);
+    /**
+     * Write structured fields for a document, diffing term/range entries.
+     * @param docId Document id to write.
+     * @param fields Structured fields to store.
+     * @returns Promise resolved once all writes complete.
+     */
+    write(docId: DocId, fields: StructuredDocFieldsRecord): Promise<void>;
+}

package/api/Indexing/structured/Types.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @packageDocumentation
+ *
+ * Types for structured query expressions and paging options.
+ */
+import type { DocId } from "../Types";
+/**
+ * Supported value types for structured queries.
+ */
+export type WhereValue = string | number | boolean | null;
+/**
+ * Term clause for structured queries.
+ */
+export type StructuredTermWhere = {
+    /**
+     * Clause type discriminator.
+     */
+    type: "term";
+    /**
+     * Field name to query.
+     */
+    field: string;
+    /**
+     * Term match mode.
+     */
+    mode: "eq" | "contains";
+    /**
+     * Value to match.
+     */
+    value: WhereValue;
+};
+/**
+ * Range clause for structured queries.
+ */
+export type StructuredRangeWhere = {
+    /**
+     * Clause type discriminator for range between.
+     */
+    type: "between";
+    /**
+     * Field name to query.
+     */
+    field: string;
+    /**
+     * Inclusive lower bound value.
+     */
+    lower: WhereValue;
+    /**
+     * Inclusive upper bound value.
+     */
+    upper: WhereValue;
+} | {
+    /**
+     * Clause type discriminator for range gte.
+     */
+    type: "gte";
+    /**
+     * Field name to query.
+     */
+    field: string;
+    /**
+     * Inclusive lower bound value.
+     */
+    value: WhereValue;
+} | {
+    /**
+     * Clause type discriminator for range lte.
+     */
+    type: "lte";
+    /**
+     * Field name to query.
+     */
+    field: string;
+    /**
+     * Inclusive upper bound value.
+     */
+    value: WhereValue;
+};
+/**
+ * Conjunction clause for structured queries.
+ */
+export type WhereAnd = {
+    /**
+     * All child clauses must match.
+     */
+    and: Where[];
+};
+/**
+ * Disjunction clause for structured queries.
+ */
+export type WhereOr = {
+    /**
+     * Any child clause may match.
+     */
+    or: Where[];
+};
+/**
+ * Structured query expression.
+ */
+export type Where = WhereAnd | WhereOr | StructuredTermWhere | StructuredRangeWhere;
+/**
+ * Paging options for structured queries.
+ */
+export type StructuredQueryOptions = {
+    /**
+     * Optional maximum number of candidates to return.
+     */
+    limit?: number;
+    /**
+     * Optional cursor string for pagination.
+     */
+    cursor?: string;
+};
+/**
+ * Candidate ids and cursor for structured searches.
+ */
+export type CandidatePage = {
+    /**
+     * Candidate document ids for the page.
+     */
+    candidateIds: DocId[];
+    /**
+     * Cursor string for the next page, if more results exist.
+     */
+    cursor?: string;
+};

package/api/Indexing/structured/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./Cursor";
+export * from "./Handlers";
+export * from "./StructuredInMemoryIndex";
+export * from "./StructuredInMemoryBackend";
+export * from "./SearchStructured";
+export * from "./StructuredDdb";
+export * from "./StructuredDdbBackend";
+export * from "./StructuredWriter";
+export * from "./Types";

package/api/Indexing/tokenize.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Tokenization output with a normalized string and its tokens.
+ * */
+export type TokenizationResult = {
+    /**
+     * Normalized input string used to produce tokens.
+     */
+    normalized: string;
+    /**
+     * Token list derived from the normalized input.
+     */
+    tokens: string[];
+};
+/**
+ * Normalize text and split into word tokens for exact/fulltext indexing.
+ * @returns Normalized string and token list.
+ * */
+export declare function tokenize(
+/**
+ * Raw input text to normalize and tokenize.
+ */
+input: string): TokenizationResult;
+/**
+ * Normalize text and emit lossy trigrams with a prefix marker for recall-heavy search.
+ * @returns Normalized string and token list.
+ * */
+export declare function tokenizeLossyTrigrams(
+/**
+ * Raw input text to normalize and tokenize.
+ */
+input: string): TokenizationResult;