@venizia/ignis-connectors 0.2.0-0

package/dist/esm/relational/sqlite/repositories/executor.js

@@ -0,0 +1,157 @@
+import { throwNotSupported } from '@venizia/ignis-kernel';
+import { BaseHelper, getError } from '@venizia/ignis-helpers/core';
+import omit from 'lodash/omit';
+/**
+ * Translates already-built SQL fragments (`where`, `orderBy`, projections) to Drizzle Core calls.
+ * Filter-to-SQL compilation is dialect work and stays in the repository tier.
+ *
+ * The `rows as Array<R>` every write verb ends in is convention, not proof: Drizzle infers
+ * `returning()`'s row type from the table schema, not from the caller-chosen R.
+ */
+export class SqliteQueryExecutor {
+    constructor() {
+        // Not `LoggerFactory`: it reaches the helpers root barrel, which pulls `ioredis` and fails a
+        // browser bundle on `tls`.
+        this.logger = new BaseHelper({ scope: SqliteQueryExecutor.name }).getLogger();
+    }
+    async select(opts) {
+        const { connector, table, columns, where, orderBy, limit, offset, lock } = opts;
+        // SQLite locks the whole database file, never a row, so there is no `FOR UPDATE` to
+        // emit. A write transaction (`BEGIN IMMEDIATE`) already excludes every other writer.
+        if (lock) {
+            throwNotSupported({
+                scope: SqliteQueryExecutor.name,
+                feature: 'Row-level locking (SELECT ... FOR UPDATE)',
+                logger: this.logger,
+            });
+        }
+        const sqliteTable = this.asTable({ table });
+        let query = columns
+            ? connector
+                .select(columns)
+                .from(sqliteTable)
+                .$dynamic()
+            : connector.select().from(sqliteTable).$dynamic();
+        if (where) {
+            query = query.where(where);
+        }
+        if (orderBy && orderBy.length > 0) {
+            query = query.orderBy(...orderBy);
+        }
+        if (limit !== undefined) {
+            query = query.limit(limit);
+        }
+        if (offset !== undefined) {
+            query = query.offset(offset);
+        }
+        // `$dynamic()` infers its row type from the table schema, not from the caller-chosen R.
+        return query;
+    }
+    async count(opts) {
+        const { connector, table, where } = opts;
+        return connector.$count(this.asTable({ table }), where);
+    }
+    async findMany(opts) {
+        const queryInterface = this.getQueryInterface(opts);
+        // Drizzle's relational result does not overlap the
+        // caller-chosen R enough for a direct assertion.
+        return queryInterface.findMany(opts.query);
+    }
+    async findFirst(opts) {
+        const queryInterface = this.getQueryInterface(opts);
+        // Drizzle's `findFirst` config type structurally forbids `limit` - it always fetches one row.
+        // This is the only place that knows that, so the strip happens here whatever the caller passed.
+        const queryOptions = omit(opts.query, ['limit']);
+        const result = await queryInterface.findFirst(queryOptions);
+        // Same drizzle-relational-query-versus-caller-generic boundary as `findMany` above.
+        return (result ?? null);
+    }
+    async insert(opts) {
+        const { connector, table, values, returning, shouldReturn } = opts;
+        const query = connector.insert(this.asTable({ table })).values(values);
+        if (!shouldReturn) {
+            const result = await query;
+            return { count: this.readAffectedRowCount({ result }), rows: [] };
+        }
+        const rows = returning ? await query.returning(returning) : await query.returning();
+        return { count: rows.length, rows: rows };
+    }
+    async update(opts) {
+        const { connector, table, data, where, returning, shouldReturn } = opts;
+        const query = connector
+            .update(this.asTable({ table }))
+            .set(data)
+            .where(where);
+        if (!shouldReturn) {
+            const result = await query;
+            return { count: this.readAffectedRowCount({ result }), rows: [] };
+        }
+        const rows = returning ? await query.returning(returning) : await query.returning();
+        return { count: rows.length, rows: rows };
+    }
+    async remove(opts) {
+        const { connector, table, where, returning, shouldReturn } = opts;
+        const query = connector.delete(this.asTable({ table })).where(where);
+        if (!shouldReturn) {
+            const result = await query;
+            return { count: this.readAffectedRowCount({ result }), rows: [] };
+        }
+        const rows = returning ? await query.returning(returning) : await query.returning();
+        return { count: rows.length, rows: rows };
+    }
+    /**
+     * The neutral options carry the dialect-free `Table` bound; every Drizzle SQLite verb wants the
+     * concrete `SQLiteTable`. Knowing your own input belongs in the engine adapter, so the whole
+     * boundary is this one cast.
+     */
+    asTable(opts) {
+        return opts.table;
+    }
+    /**
+     * Gets the Drizzle relational-query interface, validating schema registration. The error wording
+     * names the entity and lists the available keys, and a test asserts it word for word.
+     */
+    getQueryInterface(opts) {
+        const { connector, entityName } = opts;
+        const scope = opts.scope ?? this.constructor.name;
+        if (!connector.query) {
+            throw getError({
+                message: `[${scope}] Connector query interface not available | Ensure datasource is properly configured with schema`,
+            });
+        }
+        const queryInterface = connector.query[entityName];
+        if (!queryInterface) {
+            const availableKeys = Object.keys(connector.query);
+            throw getError({
+                message: `[${scope}] Schema key mismatch | Entity name '${entityName}' not found in connector.query | Available keys: [${availableKeys.join(', ')}] | Ensure the model's TABLE_NAME matches the schema registration key`,
+            });
+        }
+        return queryInterface;
+    }
+    /**
+     * Rows affected by a write with no RETURNING. Reads libsql's `ResultSet.rowsAffected`
+     * off the raw result - engine knowledge the shared repository tier must not hold.
+     * Drivers reporting `changes` instead are synchronous, and `TSqliteConnector` is
+     * pinned to `'async'`, so none can arrive here.
+     */
+    readAffectedRowCount(opts) {
+        const { result } = opts;
+        // A driver whose Drizzle run-result resolves to nothing carries no count to read.
+        if (result === null || result === undefined) {
+            return 0;
+        }
+        if (typeof result !== 'object') {
+            throw getError({
+                message: `[readAffectedRowCount] Unrecognized driver result | expected a libsql ResultSet | got: ${typeof result}`,
+            });
+        }
+        const { rowsAffected } = result;
+        if (typeof rowsAffected !== 'number') {
+            throw getError({
+                message: `[readAffectedRowCount] Unrecognized driver result | expected 'rowsAffected' (libsql) | got keys: ${Object.keys(result).join(', ')}`,
+            });
+        }
+        return rowsAffected;
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/esm/relational/sqlite/repositories/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../src/relational/sqlite/repositories/executor.ts"],"names":[],"mappings":"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"}

package/dist/esm/relational/sqlite/repositories/index.d.ts

@@ -0,0 +1,5 @@
+export * from './common/index.js';
+export * from './core/index.js';
+export * from './dialect/index.js';
+export * from './executor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/relational/sqlite/repositories/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/relational/sqlite/repositories/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAG1B,cAAc,YAAY,CAAC"}

package/dist/esm/relational/sqlite/repositories/index.js

@@ -0,0 +1,7 @@
+export * from './common/index.js';
+export * from './core/index.js';
+export * from './dialect/index.js';
+// `getQueryExecutor()` is a required member of `IRelationalDataSource`, so an application with a
+// hand-rolled datasource needs this class from the public barrel, not a deep internal path.
+export * from './executor.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/relational/sqlite/repositories/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/relational/sqlite/repositories/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,iGAAiG;AACjG,4FAA4F;AAC5F,cAAc,YAAY,CAAC"}

package/dist/esm/search/core/common/errors.d.ts

@@ -0,0 +1,53 @@
+import type { TRegisterErrors } from '@venizia/ignis-helpers/core';
+/** Codes a client branches on for a search-tier failure that is the caller's fault. Raised by every engine (Typesense, Meilisearch, and the neutral tier) so the same condition reads the same whichever backs the datasource. */
+/** Codes are LITERAL strings, deliberately not `SearchErrorCodes.*`: `MessageCode.build()` returns `string`, which erases the literal type `TRegisterErrors` is built on and silently kills autocomplete. The values are identical to what those constants produce - they are a public contract and must not shift. */
+export declare const SearchErrors: {
+    readonly NOT_FOUND: {
+        readonly message: {
+            readonly text: "Document not found";
+            readonly code: "core.search_engine.not_found";
+        };
+        readonly statusCode: 404;
+        readonly category: "business";
+    };
+    readonly ALREADY_EXISTS: {
+        readonly message: {
+            readonly text: "Document already exists";
+            readonly code: "core.search_engine.already_exists";
+        };
+        readonly statusCode: 409;
+        readonly category: "business";
+    };
+    /** A `where` key the collection definition does not declare - the search-tier answer to relational's `Column NOT FOUND`. */
+    readonly UNKNOWN_FIELD: {
+        readonly message: {
+            readonly text: "Unknown field in filter";
+            readonly code: "core.search_engine.unknown_field";
+        };
+        readonly statusCode: 400;
+        readonly category: "business";
+    };
+    /** A page this engine cannot deliver in one call - more hits than the multi-search budget covers, or a GROUPED query, whose groups cannot be split across windows without inventing an ordering the engine never produced. */
+    readonly PAGE_TOO_LARGE: {
+        readonly message: {
+            readonly text: "Requested page is too large";
+            readonly code: "core.search_engine.page_too_large";
+        };
+        readonly statusCode: 400;
+        readonly category: "business";
+    };
+    /** An operator this engine cannot express. Catalogued because WHICH engine backs the collection is what decides it - the same `where` is valid against one and not the other, so a caller must be able to branch rather than parse prose. */
+    readonly UNSUPPORTED_OPERATOR: {
+        readonly message: {
+            readonly text: "Operator not supported by this search engine";
+            readonly code: "core.search_engine.unsupported_operator";
+        };
+        readonly statusCode: 400;
+        readonly category: "business";
+    };
+};
+declare module '@venizia/ignis-helpers' {
+    interface IErrorKeyRegistry extends TRegisterErrors<typeof SearchErrors> {
+    }
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/search/core/common/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../../src/search/core/common/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAIrF,kOAAkO;AAClO,uTAAuT;AACvT,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;IAWvB,4HAA4H;;;;;;;;;IAM5H,8NAA8N;;;;;;;;;IAM9N,6OAA6O;;;;;;;;;CAS1L,CAAC;AAUtD,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,iBAAkB,SAAQ,eAAe,CAAC,OAAO,YAAY,CAAC;KAAG;CAC5E"}

package/dist/esm/search/core/common/errors.js

@@ -0,0 +1,38 @@
+import { ErrorScopes } from '@venizia/ignis-helpers/core';
+import { HTTP } from '@venizia/ignis-helpers/common';
+/** Codes a client branches on for a search-tier failure that is the caller's fault. Raised by every engine (Typesense, Meilisearch, and the neutral tier) so the same condition reads the same whichever backs the datasource. */
+/** Codes are LITERAL strings, deliberately not `SearchErrorCodes.*`: `MessageCode.build()` returns `string`, which erases the literal type `TRegisterErrors` is built on and silently kills autocomplete. The values are identical to what those constants produce - they are a public contract and must not shift. */
+export const SearchErrors = {
+    NOT_FOUND: {
+        message: { text: 'Document not found', code: 'core.search_engine.not_found' },
+        statusCode: HTTP.ResultCodes.RS_4.NotFound,
+        category: ErrorScopes.BUSINESS,
+    },
+    ALREADY_EXISTS: {
+        message: { text: 'Document already exists', code: 'core.search_engine.already_exists' },
+        statusCode: HTTP.ResultCodes.RS_4.Conflict,
+        category: ErrorScopes.BUSINESS,
+    },
+    /** A `where` key the collection definition does not declare - the search-tier answer to relational's `Column NOT FOUND`. */
+    UNKNOWN_FIELD: {
+        message: { text: 'Unknown field in filter', code: 'core.search_engine.unknown_field' },
+        statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+        category: ErrorScopes.BUSINESS,
+    },
+    /** A page this engine cannot deliver in one call - more hits than the multi-search budget covers, or a GROUPED query, whose groups cannot be split across windows without inventing an ordering the engine never produced. */
+    PAGE_TOO_LARGE: {
+        message: { text: 'Requested page is too large', code: 'core.search_engine.page_too_large' },
+        statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+        category: ErrorScopes.BUSINESS,
+    },
+    /** An operator this engine cannot express. Catalogued because WHICH engine backs the collection is what decides it - the same `where` is valid against one and not the other, so a caller must be able to branch rather than parse prose. */
+    UNSUPPORTED_OPERATOR: {
+        message: {
+            text: 'Operator not supported by this search engine',
+            code: 'core.search_engine.unsupported_operator',
+        },
+        statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+        category: ErrorScopes.BUSINESS,
+    },
+};
+//# sourceMappingURL=errors.js.map

package/dist/esm/search/core/common/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../../src/search/core/common/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,+BAA+B,CAAC;AAErD,kOAAkO;AAClO,uTAAuT;AACvT,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,SAAS,EAAE;QACT,OAAO,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,8BAA8B,EAAE;QAC7E,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ;QAC1C,QAAQ,EAAE,WAAW,CAAC,QAAQ;KAC/B;IACD,cAAc,EAAE;QACd,OAAO,EAAE,EAAE,IAAI,EAAE,yBAAyB,EAAE,IAAI,EAAE,mCAAmC,EAAE;QACvF,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ;QAC1C,QAAQ,EAAE,WAAW,CAAC,QAAQ;KAC/B;IACD,4HAA4H;IAC5H,aAAa,EAAE;QACb,OAAO,EAAE,EAAE,IAAI,EAAE,yBAAyB,EAAE,IAAI,EAAE,kCAAkC,EAAE;QACtF,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU;QAC5C,QAAQ,EAAE,WAAW,CAAC,QAAQ;KAC/B;IACD,8NAA8N;IAC9N,cAAc,EAAE;QACd,OAAO,EAAE,EAAE,IAAI,EAAE,6BAA6B,EAAE,IAAI,EAAE,mCAAmC,EAAE;QAC3F,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU;QAC5C,QAAQ,EAAE,WAAW,CAAC,QAAQ;KAC/B;IACD,6OAA6O;IAC7O,oBAAoB,EAAE;QACpB,OAAO,EAAE;YACP,IAAI,EAAE,8CAA8C;YACpD,IAAI,EAAE,yCAAyC;SAChD;QACD,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU;QAC5C,QAAQ,EAAE,WAAW,CAAC,QAAQ;KAC/B;CACkD,CAAC"}

package/dist/esm/search/core/common/index.d.ts

@@ -0,0 +1,2 @@
+export * from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/search/core/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/search/core/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC"}

package/dist/esm/search/core/common/index.js

@@ -0,0 +1,2 @@
+export * from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/search/core/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/search/core/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC"}

package/dist/esm/search/core/connector.d.ts

@@ -0,0 +1,238 @@
+import type { ISynonym } from '../../search/core/models/index.js';
+import type { ValueOrPromise } from '@venizia/ignis-helpers/common';
+import { BaseHelper } from '@venizia/ignis-helpers/core';
+export interface IImportResult<TResponse = unknown> {
+    count: {
+        success: number;
+        fail: number;
+    };
+    responses: TResponse[];
+}
+export interface IAliasInfo {
+    name: string;
+    collection: string;
+}
+export interface ISearchConnectorCallbacks {
+    onInitialized?: (opts: {
+        name: string;
+    }) => void;
+    onError?: (opts: {
+        name: string;
+        error: unknown;
+    }) => void;
+}
+/** Search-response envelope, read without a boundary cast. `score` scales are unrelated across engines - never compare or threshold one against another; `isFoundExact` is false when `found` is approximate. */
+export interface ISearchResult<DocumentType extends object = object, HighlightType = unknown, FacetCountType = unknown, GroupedHitType = unknown> {
+    found: number;
+    isFoundExact: boolean;
+    outOf?: number;
+    searchTimeMs?: number;
+    hits?: Array<{
+        document: DocumentType;
+        highlight?: HighlightType;
+        highlights?: HighlightType[];
+        score?: number;
+    }>;
+    facetCounts?: FacetCountType[];
+    groupedHits?: GroupedHitType[];
+}
+export interface ISearchCollectionScoped<CreateSchema = unknown, Schema = unknown, FieldSchema = unknown> {
+    create(opts: {
+        schema: CreateSchema;
+    }): Promise<Schema | void>;
+    ensure(opts: {
+        schema: CreateSchema;
+    }): Promise<Schema>;
+    get(opts: {
+        name: string;
+    }): Promise<Schema>;
+    list(): Promise<Schema[]>;
+    exists(opts: {
+        name: string;
+    }): Promise<boolean>;
+    patchSchema(opts: {
+        name: string;
+        fields: FieldSchema[];
+    }): Promise<void>;
+    delete(opts: {
+        name: string;
+    }): Promise<boolean>;
+}
+/** A named pointer to one physical collection. Engines without aliases omit this group entirely. */
+export interface ISearchAliasScoped {
+    upsert(opts: {
+        name: string;
+        collection: string;
+    }): Promise<void>;
+    get(opts: {
+        name: string;
+    }): Promise<IAliasInfo | null>;
+}
+/** Atomic exchange of two collections' documents and settings - the alias-less path to a zero-downtime reindex. */
+export interface ISearchSwapScoped {
+    indexes(opts: {
+        pairs: Array<[string, string]>;
+    }): Promise<void>;
+}
+export interface ISearchSynonymSetScoped {
+    upsert(opts: {
+        name: string;
+        items: ISynonym[];
+    }): Promise<void>;
+    get(opts: {
+        name: string;
+    }): Promise<ISynonym[] | null>;
+    list(): Promise<string[]>;
+    delete(opts: {
+        name: string;
+    }): Promise<boolean>;
+    link(opts: {
+        collection: string;
+        synonymSets: string[];
+    }): Promise<void>;
+}
+/** A flat per-collection synonym dictionary - no named, linkable set resource. */
+export interface ISearchSynonymScoped {
+    set(opts: {
+        collection: string;
+        items: ISynonym[];
+    }): Promise<void>;
+    get(opts: {
+        collection: string;
+    }): Promise<ISynonym[]>;
+    reset(opts: {
+        collection: string;
+    }): Promise<void>;
+}
+export interface ISearchDocumentScoped {
+    get<T extends object>(opts: {
+        collection: string;
+        id: string;
+    }): Promise<T>;
+    /** Exact count of documents matching `filterBy`. Engines whose search endpoint caps or estimates its total must answer from a document-listing endpoint instead. */
+    count(opts: {
+        collection: string;
+        filterBy?: string;
+    }): Promise<number>;
+    create<T extends object>(opts: {
+        collection: string;
+        document: T;
+    }): Promise<T>;
+    upsert<T extends object>(opts: {
+        collection: string;
+        document: T;
+    }): Promise<T>;
+    update<T extends object>(opts: {
+        collection: string;
+        id: string;
+        document: Partial<T>;
+    }): Promise<T>;
+    updateBy<T extends object>(opts: {
+        collection: string;
+        document: Partial<T>;
+        filterBy: string;
+    }): Promise<{
+        updatedCount: number;
+    }>;
+    delete(opts: {
+        collection: string;
+        id: string;
+    }): Promise<boolean>;
+    deleteBy(opts: {
+        collection: string;
+        filterBy: string;
+    }): Promise<number>;
+    deleteAll(opts: {
+        collection: string;
+    }): Promise<boolean>;
+    import<T extends object>(opts: {
+        collection: string;
+        documents: T[];
+        batchSize?: number;
+    }): Promise<IImportResult<unknown>>;
+    export(opts: {
+        collection: string;
+        filterBy?: string;
+        includeFields?: string[];
+    }): Promise<string>;
+}
+/** The verb contract every search engine implements - an interface so tests can fake it clientless. `collection`/`document` are the true intersection; `alias`/`synonymSet`/`synonyms`/`swap` are optional since no engine has all four, so agnostic callers must write `connector.alias?.…`. */
+export interface ISearchConnector {
+    getHealth(): Promise<{
+        ok: boolean;
+    }>;
+    ping(): Promise<boolean>;
+    collection: ISearchCollectionScoped;
+    document: ISearchDocumentScoped;
+    alias?: ISearchAliasScoped;
+    synonymSet?: ISearchSynonymSetScoped;
+    synonyms?: ISearchSynonymScoped;
+    swap?: ISearchSwapScoped;
+    search<TDocument extends object = object>(opts: {
+        collection: string;
+        params: unknown;
+    }): Promise<ISearchResult<TDocument>>;
+    multiSearch(opts: {
+        searches: unknown[];
+        union?: boolean;
+        commonParams?: unknown;
+        options?: unknown;
+    }): Promise<unknown>;
+}
+export declare abstract class BaseSearchConnector extends BaseHelper implements ISearchConnector {
+    constructor(opts: {
+        scope: string;
+        identifier: string;
+    });
+    ping(): Promise<boolean>;
+    protected assertNonEmpty(opts: {
+        value?: string | null;
+        name: string;
+        method: string;
+    }): void;
+    protected runEngineCall<T>(opts: {
+        method: string;
+        run: () => ValueOrPromise<T>;
+        tolerate?: {
+            when: (error: unknown) => boolean;
+            handle: (error: unknown) => ValueOrPromise<T>;
+        };
+    }): Promise<T>;
+    /** Which errors mean "not found" is engine-specific classification; the sanitized throw and the benign fallback are not. */
+    protected abstract isNotFoundError(opts: {
+        error: unknown;
+    }): boolean;
+    /** Tolerated-404 branch shared by getCollection/patchCollectionSchema/getDocument/updateDocument: throws the sanitized not-found error. */
+    protected notFoundTolerance(opts: {
+        method: string;
+        subject: string;
+    }): {
+        when: (error: unknown) => boolean;
+        handle: (error: unknown) => never;
+    };
+    /** Tolerated-404 branch shared by deleteCollection/getAlias/getSynonymSet/deleteSynonymSet/deleteDocument: logs and returns a benign sentinel instead of throwing. */
+    protected notFoundFallback<T>(opts: {
+        method: string;
+        message: string;
+        args?: unknown[];
+        fallback: T;
+    }): {
+        when: (error: unknown) => boolean;
+        handle: (error: unknown) => T;
+    };
+    abstract getHealth(): Promise<{
+        ok: boolean;
+    }>;
+    abstract collection: ISearchCollectionScoped;
+    abstract document: ISearchDocumentScoped;
+    abstract search<TDocument extends object = object>(opts: {
+        collection: string;
+        params: unknown;
+    }): Promise<ISearchResult<TDocument>>;
+    abstract multiSearch(opts: {
+        searches: unknown[];
+        union?: boolean;
+        commonParams?: unknown;
+    }): Promise<unknown>;
+}
+//# sourceMappingURL=connector.d.ts.map

package/dist/esm/search/core/connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../../../src/search/core/connector.ts"],"names":[],"mappings":"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"}

package/dist/esm/search/core/connector.js

@@ -0,0 +1,59 @@
+import { BaseHelper, getError, isApplicationError } from '@venizia/ignis-helpers/core';
+import { SearchConnectorInternal } from './internal/index.js';
+export class BaseSearchConnector extends BaseHelper {
+    constructor(opts) {
+        super(opts);
+    }
+    async ping() {
+        const health = await this.getHealth();
+        return health.ok;
+    }
+    assertNonEmpty(opts) {
+        const { value, name, method } = opts;
+        if (!value || value.trim().length === 0) {
+            throw getError({ message: `[${method}] Missing or empty value | name: ${name}` });
+        }
+    }
+    // Runs the engine verb; tolerated errors route to the caller's branch, everything else becomes a sanitized 503.
+    async runEngineCall(opts) {
+        const { method, run, tolerate } = opts;
+        try {
+            const rs = await run();
+            return rs;
+        }
+        catch (error) {
+            if (tolerate?.when(error)) {
+                const rs = await tolerate.handle(error);
+                return rs;
+            }
+            // A framework ApplicationError is already sanitized and carries its own statusCode/messageCode; only raw engine failures may be wrapped as a generic 503.
+            if (isApplicationError(error)) {
+                throw error;
+            }
+            SearchConnectorInternal.wrapDependencyError({ method, error, logger: this.logger });
+        }
+    }
+    /** Tolerated-404 branch shared by getCollection/patchCollectionSchema/getDocument/updateDocument: throws the sanitized not-found error. */
+    notFoundTolerance(opts) {
+        const { method, subject } = opts;
+        return {
+            when: error => this.isNotFoundError({ error }),
+            handle: () => {
+                this.logger.for(method).debug('%s not found', subject);
+                SearchConnectorInternal.throwNotFoundError({ method, subject });
+            },
+        };
+    }
+    /** Tolerated-404 branch shared by deleteCollection/getAlias/getSynonymSet/deleteSynonymSet/deleteDocument: logs and returns a benign sentinel instead of throwing. */
+    notFoundFallback(opts) {
+        const { method, message, args, fallback } = opts;
+        return {
+            when: error => this.isNotFoundError({ error }),
+            handle: () => {
+                this.logger.for(method).debug(message, ...(args ?? []));
+                return fallback;
+            },
+        };
+    }
+}
+//# sourceMappingURL=connector.js.map

package/dist/esm/search/core/connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.js","sourceRoot":"","sources":["../../../../src/search/core/connector.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACvF,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AA8IrD,MAAM,OAAgB,mBAAoB,SAAQ,UAAU;IAC1D,YAAY,IAA2C;QACrD,KAAK,CAAC,IAAI,CAAC,CAAC;IACd,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACtC,OAAO,MAAM,CAAC,EAAE,CAAC;IACnB,CAAC;IAES,cAAc,CAAC,IAA6D;QACpF,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QACrC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxC,MAAM,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,MAAM,oCAAoC,IAAI,EAAE,EAAE,CAAC,CAAC;QACpF,CAAC;IACH,CAAC;IAED,gHAAgH;IACtG,KAAK,CAAC,aAAa,CAAI,IAIhC;QACC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;QAEvC,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,MAAM,GAAG,EAAE,CAAC;YACvB,OAAO,EAAE,CAAC;QACZ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1B,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACxC,OAAO,EAAE,CAAC;YACZ,CAAC;YAED,0JAA0J;YAC1J,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9B,MAAM,KAAK,CAAC;YACd,CAAC;YAED,uBAAuB,CAAC,mBAAmB,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IAKD,2IAA2I;IACjI,iBAAiB,CAAC,IAAyC;QAInE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;QAEjC,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC;YAC9C,MAAM,EAAE,GAAG,EAAE;gBACX,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;gBACvD,uBAAuB,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YAClE,CAAC;SACF,CAAC;IACJ,CAAC;IAED,sKAAsK;IAC5J,gBAAgB,CAAI,IAK7B;QACC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;QAEjD,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC;YAC9C,MAAM,EAAE,GAAG,EAAE;gBACX,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;gBACxD,OAAO,QAAQ,CAAC;YAClB,CAAC;SACF,CAAC;IACJ,CAAC;CAkBF"}

package/dist/esm/search/core/controllers/abstract.d.ts

@@ -0,0 +1,27 @@
+import type { TEntityDataObject, TRouteContext } from '@venizia/ignis-kernel';
+import { BaseRestController } from '@venizia/ignis-kernel';
+import type { AbstractEntity } from '@venizia/ignis-kernel';
+import type { TAnyObjectSchema } from '@venizia/ignis-kernel';
+import type { AnyType } from '@venizia/ignis-helpers/common';
+import type { Env, Schema } from 'hono';
+import type { ReadableSearchRepository } from '../repositories/core/readable.js';
+/** Base tier of a generated search controller: the repository handle plus the search / multi-search verbs; SearchControllerFactory returns a thin subclass that only builds route configs and wires them. */
+export declare abstract class AbstractSearchController<TEntity extends AbstractEntity<TAnyObjectSchema> = AbstractEntity<TAnyObjectSchema>, RouteEnv extends Env = Env, RouteSchema extends Schema = {}, BasePath extends string = '/', ConfigurableOptions extends object = {}, TDataObject extends object = TEntityDataObject<TEntity>> extends BaseRestController<RouteEnv, RouteSchema, BasePath, ConfigurableOptions> {
+    repository: ReadableSearchRepository<TDataObject>;
+    constructor(opts: {
+        scope: string;
+        path: string;
+        isStrict?: boolean;
+        repository: ReadableSearchRepository<TDataObject>;
+        definitions: AnyType;
+    });
+    /** POST /search - single-collection keyword/semantic/hybrid/raw search. */
+    search(opts: {
+        context: TRouteContext<RouteEnv>;
+    }): Promise<import("@venizia/ignis-kernel").TJsonResponse<unknown, 200>>;
+    /** POST /multi-search - cross-collection search, forwarded verbatim to the engine. */
+    multiSearch(opts: {
+        context: TRouteContext<RouteEnv>;
+    }): Promise<import("@venizia/ignis-kernel").TJsonResponse<unknown, 200>>;
+}
+//# sourceMappingURL=abstract.d.ts.map