@geonosis/search 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,218 @@
+import { Executor } from '@geonosis/db';
+
+/** A document's own values, as primitives (D-050): what a projection reads. */
+type DocumentFields = Readonly<Record<string, string>>;
+/**
+ * What a caller hands the index — and there is no searchable projection in it.
+ *
+ * A contract field every implementer must remember to fill is a field one of them will not: two
+ * write paths in the source repo each derived the same searchable values by hand, and the one that
+ * forgot blanked a column on every document it wrote. The projection is declared once, where the
+ * index is built, so no call site is asked for it.
+ */
+type IndexedDocument<Kind extends string = string, Fields extends DocumentFields = DocumentFields> = {
+    fields: Fields;
+    id: string;
+    kind: Kind;
+};
+/** Where a document is addressed without being described: what `retire` needs and nothing more. */
+type DocumentAddress<Kind extends string = string> = {
+    id: string;
+    kind: Kind;
+};
+/** How one kind of document becomes searchable text. Declared once, per kind. */
+type SearchProjection<Fields extends DocumentFields = DocumentFields> = {
+    /** Searched, never returned: the body of the thing. */
+    body: (fields: Fields) => string;
+    /** Searched AND returned: what a hit shows. */
+    title: (fields: Fields) => string;
+};
+/** One projection per kind, or it does not compile — a new kind cannot ship unindexed. */
+type SearchProjections<Kind extends string, Fields extends DocumentFields = DocumentFields> = {
+    [K in Kind]: SearchProjection<Fields>;
+};
+/**
+ * What this index answers, by name AND by value.
+ *
+ * Publishing filter names without their value vocabularies is how a caller filters for a value
+ * nothing emits, gets an empty answer, and reports it as a count (#135).
+ */
+type SearchVocabulary<Kind extends string = string> = {
+    filters: Readonly<Record<string, readonly string[]>>;
+    orderings: readonly string[];
+    /** Present so a reader of the vocabulary alone can see what may be indexed. */
+    kinds?: readonly Kind[];
+};
+/** Opaque, and minted only by the index that will read it back. */
+type SearchCursor = string;
+type SearchOptions = {
+    /** Keyset, never an offset (D-013): the key of the row the last page ended on. */
+    after?: SearchCursor;
+    filters?: Readonly<Record<string, string>>;
+    limit?: number;
+    order?: string;
+};
+type SearchHit = {
+    id: string;
+    /** Epoch milliseconds (D-050). */
+    indexedAt: number;
+    kind: string;
+    title: string;
+};
+type SearchPage = {
+    hits: readonly SearchHit[];
+    /** Absent when this page is the last one — never an empty string. */
+    next?: SearchCursor;
+};
+type SearchIndex<Kind extends string = string> = {
+    index: (document: IndexedDocument<Kind>) => Promise<void>;
+    query: (terms: string, options?: SearchOptions) => Promise<SearchPage>;
+    retire: (document: DocumentAddress<Kind>) => Promise<void>;
+    vocabulary: SearchVocabulary<Kind>;
+};
+/** A question this index will not answer, as opposed to one it answers with nothing. */
+declare class SearchRefusal extends Error {
+    constructor(message: string);
+}
+declare const DEFAULT_LIMIT = 50;
+type ReadFilter = {
+    name: string;
+    value: string;
+};
+type ReadQuery = {
+    after?: SearchCursorKey;
+    filters: readonly ReadFilter[];
+    limit: number;
+    order: string;
+    terms: string;
+};
+/**
+ * The query as this index will run it, or a refusal naming what it could not answer.
+ *
+ * The ordering falls back to the first the vocabulary declares, so a vocabulary that declares its
+ * orderings in preference order needs no second place to say which is the default.
+ */
+declare const readSearchQuery: <Kind extends string>(vocabulary: SearchVocabulary<Kind>, terms: string, options?: SearchOptions) => ReadQuery;
+/**
+ * The key of the row a page ended on, plus the question it was asked.
+ *
+ * A relevance rank only means anything under the terms that produced it, so the terms and the
+ * ordering travel inside the cursor: a page fetched with the same cursor under a different question
+ * is a silently wrong page, which is the shape of the answer nobody checks.
+ */
+type SearchCursorKey = {
+    /** Epoch milliseconds of the indexed row, so `recent` pages by the same mechanism. */
+    at: number;
+    id: string;
+    kind: string;
+    order: string;
+    rank: number;
+    terms: string;
+};
+declare const encodeCursor: (key: SearchCursorKey) => SearchCursor;
+declare const readCursor: (cursor: SearchCursor, asked: {
+    order: string;
+    terms: string;
+}) => SearchCursorKey;
+
+type SearchConformanceCase = {
+    name: string;
+    run: () => Promise<void>;
+};
+/**
+ * One document this index can take, and two words: one that must find it, one that must not.
+ *
+ * `notFindableBy` is the whole exam for a derived projection. It is a value the document CARRIES
+ * and no projection READS — an index that stored the record it was handed rather than the text its
+ * projection derived is found by it, and nothing else can tell the two apart from outside.
+ */
+type SearchExample<Kind extends string = string> = {
+    document: IndexedDocument<Kind>;
+    findableBy: string;
+    notFindableBy: string;
+};
+type SearchSubject<Kind extends string = string> = {
+    /** At least two, addressed differently: one document proves no wall. */
+    examples: readonly SearchExample<Kind>[];
+    inTenant: <Result>(tenantId: string, run: (index: SearchIndex<Kind>) => Promise<Result>) => Promise<Result>;
+    /** The index reached OUTSIDE every tenant session: what the policies alone let through. */
+    outsideAnySession?: <Result>(run: (index: SearchIndex<Kind>) => Promise<Result>) => Promise<Result>;
+    /** Empty the index. Whatever role can do that — the exam's own rows are its business. */
+    reset: () => Promise<void>;
+};
+/**
+ * #135. An index that answers a question it never declared answers it with nothing, and nothing is
+ * read as a count. The control case is here on purpose: an index that refused everything would pass
+ * the three refusals below without answering anybody.
+ */
+declare const vocabularyConformance: <Kind extends string>(subject: SearchSubject<Kind>) => SearchConformanceCase[];
+/** What the write path derived, asked from outside: the only place a handed-in projection shows. */
+declare const derivedProjectionConformance: <Kind extends string>(subject: SearchSubject<Kind>) => SearchConformanceCase[];
+/**
+ * The tenant wall under this index's OWN queries.
+ *
+ * Every read here is the ordinary one. A read the exam qualifies by tenant proves its own where
+ * clause; only an unqualified one asks what the policy lets through.
+ */
+declare const tenantIsolationConformance: <Kind extends string>(subject: SearchSubject<Kind>) => SearchConformanceCase[];
+/**
+ * The whole exam a consumer runs against THEIR provider — and the bar this package's own provider
+ * is held to.
+ *
+ * What it does NOT measure: retrieval semantics. Which words match, how a rank is computed, whether
+ * a prefix or a stem or a synonym counts — those live in the DDL and in the dialect, and they
+ * differ by design between one index and the next. This exam asks whether a document is findable by
+ * what its projection derived and invisible to what it did not, whether a question outside the
+ * declared vocabulary is refused rather than answered emptily, and whether the tenant wall holds
+ * under the index's own queries. An index that passes may still rank badly.
+ */
+declare const searchConformance: <Kind extends string>(subject: SearchSubject<Kind>) => SearchConformanceCase[];
+
+/**
+ * The session variables the wall is built on. Neither has a default: these are the CONSUMER's
+ * vocabulary, and a default here would be one repo's names compiled into everybody's policies —
+ * in the one file no lint rule reads (#168).
+ */
+type SearchIndexSettings = {
+    /** What maintenance sets to reach every tenant. */
+    opsSetting: string;
+    /** What the ops setting holds while that lever is pulled. */
+    opsValue?: string;
+    /** What a transaction sets to name the tenant it is open for. */
+    tenantSetting: string;
+};
+type SearchMigration = {
+    name: string;
+    statements: string[];
+};
+declare const SEARCH_INDEX_TABLE = "search_index";
+/** The tokens the shipped `.sql` files carry where a session variable belongs. */
+declare const MIGRATION_PLACEHOLDERS: {
+    opsSetting: string;
+    tenantSetting: string;
+};
+declare const DEFAULT_OPS_VALUE = "on";
+/**
+ * The migrations a consumer applies, in order, with their session variables filled in — for a
+ * migrator that templates nothing. The same DDL ships as `.sql` files in this package for one that
+ * does.
+ */
+declare const searchIndexMigrations: (settings: SearchIndexSettings) => SearchMigration[];
+
+type PgFtsOptions<Kind extends string> = {
+    /** Already inside whatever session the consumer opened: this provider opens nothing. */
+    executor: Executor;
+    /** Injected, never ambient (D-050): the composition root passes `Date.now`. */
+    nowMs: () => number;
+    projections: SearchProjections<Kind>;
+};
+/**
+ * Postgres full text search over an injected executor.
+ *
+ * Nothing here names a tenant. The row's tenant is the column's default, read from the session, and
+ * the read carries no predicate at all — the policies in this package's own migrations are what
+ * answers that question, so a query that forgot its session sees nothing rather than everything.
+ */
+declare const pgFtsSearchIndex: <Kind extends string>({ executor, nowMs, projections, }: PgFtsOptions<Kind>) => SearchIndex<Kind>;
+
+export { DEFAULT_LIMIT, DEFAULT_OPS_VALUE, type DocumentAddress, type DocumentFields, type IndexedDocument, MIGRATION_PLACEHOLDERS, type PgFtsOptions, type ReadFilter, type ReadQuery, SEARCH_INDEX_TABLE, type SearchConformanceCase, type SearchCursor, type SearchCursorKey, type SearchExample, type SearchHit, type SearchIndex, type SearchIndexSettings, type SearchMigration, type SearchOptions, type SearchPage, type SearchProjection, type SearchProjections, SearchRefusal, type SearchSubject, type SearchVocabulary, derivedProjectionConformance, encodeCursor, pgFtsSearchIndex, readCursor, readSearchQuery, searchConformance, searchIndexMigrations, tenantIsolationConformance, vocabularyConformance };

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+import { Executor } from '@geonosis/db';
+
+/** A document's own values, as primitives (D-050): what a projection reads. */
+type DocumentFields = Readonly<Record<string, string>>;
+/**
+ * What a caller hands the index — and there is no searchable projection in it.
+ *
+ * A contract field every implementer must remember to fill is a field one of them will not: two
+ * write paths in the source repo each derived the same searchable values by hand, and the one that
+ * forgot blanked a column on every document it wrote. The projection is declared once, where the
+ * index is built, so no call site is asked for it.
+ */
+type IndexedDocument<Kind extends string = string, Fields extends DocumentFields = DocumentFields> = {
+    fields: Fields;
+    id: string;
+    kind: Kind;
+};
+/** Where a document is addressed without being described: what `retire` needs and nothing more. */
+type DocumentAddress<Kind extends string = string> = {
+    id: string;
+    kind: Kind;
+};
+/** How one kind of document becomes searchable text. Declared once, per kind. */
+type SearchProjection<Fields extends DocumentFields = DocumentFields> = {
+    /** Searched, never returned: the body of the thing. */
+    body: (fields: Fields) => string;
+    /** Searched AND returned: what a hit shows. */
+    title: (fields: Fields) => string;
+};
+/** One projection per kind, or it does not compile — a new kind cannot ship unindexed. */
+type SearchProjections<Kind extends string, Fields extends DocumentFields = DocumentFields> = {
+    [K in Kind]: SearchProjection<Fields>;
+};
+/**
+ * What this index answers, by name AND by value.
+ *
+ * Publishing filter names without their value vocabularies is how a caller filters for a value
+ * nothing emits, gets an empty answer, and reports it as a count (#135).
+ */
+type SearchVocabulary<Kind extends string = string> = {
+    filters: Readonly<Record<string, readonly string[]>>;
+    orderings: readonly string[];
+    /** Present so a reader of the vocabulary alone can see what may be indexed. */
+    kinds?: readonly Kind[];
+};
+/** Opaque, and minted only by the index that will read it back. */
+type SearchCursor = string;
+type SearchOptions = {
+    /** Keyset, never an offset (D-013): the key of the row the last page ended on. */
+    after?: SearchCursor;
+    filters?: Readonly<Record<string, string>>;
+    limit?: number;
+    order?: string;
+};
+type SearchHit = {
+    id: string;
+    /** Epoch milliseconds (D-050). */
+    indexedAt: number;
+    kind: string;
+    title: string;
+};
+type SearchPage = {
+    hits: readonly SearchHit[];
+    /** Absent when this page is the last one — never an empty string. */
+    next?: SearchCursor;
+};
+type SearchIndex<Kind extends string = string> = {
+    index: (document: IndexedDocument<Kind>) => Promise<void>;
+    query: (terms: string, options?: SearchOptions) => Promise<SearchPage>;
+    retire: (document: DocumentAddress<Kind>) => Promise<void>;
+    vocabulary: SearchVocabulary<Kind>;
+};
+/** A question this index will not answer, as opposed to one it answers with nothing. */
+declare class SearchRefusal extends Error {
+    constructor(message: string);
+}
+declare const DEFAULT_LIMIT = 50;
+type ReadFilter = {
+    name: string;
+    value: string;
+};
+type ReadQuery = {
+    after?: SearchCursorKey;
+    filters: readonly ReadFilter[];
+    limit: number;
+    order: string;
+    terms: string;
+};
+/**
+ * The query as this index will run it, or a refusal naming what it could not answer.
+ *
+ * The ordering falls back to the first the vocabulary declares, so a vocabulary that declares its
+ * orderings in preference order needs no second place to say which is the default.
+ */
+declare const readSearchQuery: <Kind extends string>(vocabulary: SearchVocabulary<Kind>, terms: string, options?: SearchOptions) => ReadQuery;
+/**
+ * The key of the row a page ended on, plus the question it was asked.
+ *
+ * A relevance rank only means anything under the terms that produced it, so the terms and the
+ * ordering travel inside the cursor: a page fetched with the same cursor under a different question
+ * is a silently wrong page, which is the shape of the answer nobody checks.
+ */
+type SearchCursorKey = {
+    /** Epoch milliseconds of the indexed row, so `recent` pages by the same mechanism. */
+    at: number;
+    id: string;
+    kind: string;
+    order: string;
+    rank: number;
+    terms: string;
+};
+declare const encodeCursor: (key: SearchCursorKey) => SearchCursor;
+declare const readCursor: (cursor: SearchCursor, asked: {
+    order: string;
+    terms: string;
+}) => SearchCursorKey;
+
+type SearchConformanceCase = {
+    name: string;
+    run: () => Promise<void>;
+};
+/**
+ * One document this index can take, and two words: one that must find it, one that must not.
+ *
+ * `notFindableBy` is the whole exam for a derived projection. It is a value the document CARRIES
+ * and no projection READS — an index that stored the record it was handed rather than the text its
+ * projection derived is found by it, and nothing else can tell the two apart from outside.
+ */
+type SearchExample<Kind extends string = string> = {
+    document: IndexedDocument<Kind>;
+    findableBy: string;
+    notFindableBy: string;
+};
+type SearchSubject<Kind extends string = string> = {
+    /** At least two, addressed differently: one document proves no wall. */
+    examples: readonly SearchExample<Kind>[];
+    inTenant: <Result>(tenantId: string, run: (index: SearchIndex<Kind>) => Promise<Result>) => Promise<Result>;
+    /** The index reached OUTSIDE every tenant session: what the policies alone let through. */
+    outsideAnySession?: <Result>(run: (index: SearchIndex<Kind>) => Promise<Result>) => Promise<Result>;
+    /** Empty the index. Whatever role can do that — the exam's own rows are its business. */
+    reset: () => Promise<void>;
+};
+/**
+ * #135. An index that answers a question it never declared answers it with nothing, and nothing is
+ * read as a count. The control case is here on purpose: an index that refused everything would pass
+ * the three refusals below without answering anybody.
+ */
+declare const vocabularyConformance: <Kind extends string>(subject: SearchSubject<Kind>) => SearchConformanceCase[];
+/** What the write path derived, asked from outside: the only place a handed-in projection shows. */
+declare const derivedProjectionConformance: <Kind extends string>(subject: SearchSubject<Kind>) => SearchConformanceCase[];
+/**
+ * The tenant wall under this index's OWN queries.
+ *
+ * Every read here is the ordinary one. A read the exam qualifies by tenant proves its own where
+ * clause; only an unqualified one asks what the policy lets through.
+ */
+declare const tenantIsolationConformance: <Kind extends string>(subject: SearchSubject<Kind>) => SearchConformanceCase[];
+/**
+ * The whole exam a consumer runs against THEIR provider — and the bar this package's own provider
+ * is held to.
+ *
+ * What it does NOT measure: retrieval semantics. Which words match, how a rank is computed, whether
+ * a prefix or a stem or a synonym counts — those live in the DDL and in the dialect, and they
+ * differ by design between one index and the next. This exam asks whether a document is findable by
+ * what its projection derived and invisible to what it did not, whether a question outside the
+ * declared vocabulary is refused rather than answered emptily, and whether the tenant wall holds
+ * under the index's own queries. An index that passes may still rank badly.
+ */
+declare const searchConformance: <Kind extends string>(subject: SearchSubject<Kind>) => SearchConformanceCase[];
+
+/**
+ * The session variables the wall is built on. Neither has a default: these are the CONSUMER's
+ * vocabulary, and a default here would be one repo's names compiled into everybody's policies —
+ * in the one file no lint rule reads (#168).
+ */
+type SearchIndexSettings = {
+    /** What maintenance sets to reach every tenant. */
+    opsSetting: string;
+    /** What the ops setting holds while that lever is pulled. */
+    opsValue?: string;
+    /** What a transaction sets to name the tenant it is open for. */
+    tenantSetting: string;
+};
+type SearchMigration = {
+    name: string;
+    statements: string[];
+};
+declare const SEARCH_INDEX_TABLE = "search_index";
+/** The tokens the shipped `.sql` files carry where a session variable belongs. */
+declare const MIGRATION_PLACEHOLDERS: {
+    opsSetting: string;
+    tenantSetting: string;
+};
+declare const DEFAULT_OPS_VALUE = "on";
+/**
+ * The migrations a consumer applies, in order, with their session variables filled in — for a
+ * migrator that templates nothing. The same DDL ships as `.sql` files in this package for one that
+ * does.
+ */
+declare const searchIndexMigrations: (settings: SearchIndexSettings) => SearchMigration[];
+
+type PgFtsOptions<Kind extends string> = {
+    /** Already inside whatever session the consumer opened: this provider opens nothing. */
+    executor: Executor;
+    /** Injected, never ambient (D-050): the composition root passes `Date.now`. */
+    nowMs: () => number;
+    projections: SearchProjections<Kind>;
+};
+/**
+ * Postgres full text search over an injected executor.
+ *
+ * Nothing here names a tenant. The row's tenant is the column's default, read from the session, and
+ * the read carries no predicate at all — the policies in this package's own migrations are what
+ * answers that question, so a query that forgot its session sees nothing rather than everything.
+ */
+declare const pgFtsSearchIndex: <Kind extends string>({ executor, nowMs, projections, }: PgFtsOptions<Kind>) => SearchIndex<Kind>;
+
+export { DEFAULT_LIMIT, DEFAULT_OPS_VALUE, type DocumentAddress, type DocumentFields, type IndexedDocument, MIGRATION_PLACEHOLDERS, type PgFtsOptions, type ReadFilter, type ReadQuery, SEARCH_INDEX_TABLE, type SearchConformanceCase, type SearchCursor, type SearchCursorKey, type SearchExample, type SearchHit, type SearchIndex, type SearchIndexSettings, type SearchMigration, type SearchOptions, type SearchPage, type SearchProjection, type SearchProjections, SearchRefusal, type SearchSubject, type SearchVocabulary, derivedProjectionConformance, encodeCursor, pgFtsSearchIndex, readCursor, readSearchQuery, searchConformance, searchIndexMigrations, tenantIsolationConformance, vocabularyConformance };