palgres 0.0.0-stage → 0.2.0

package/types/palgres/src/search.d.ts

@@ -0,0 +1,107 @@
+import { type Search, type SearchMetric } from './model.js';
+import type { Roles } from './plan.js';
+export declare const SEARCH_SCHEMA = "palgres_search";
+/** A generation of a table's vectors, as palgres_search.generations says it. */
+export interface SearchGeneration {
+    gen: number;
+    model: string;
+    dimensions: number;
+    metric: SearchMetric;
+    from: string[];
+    status: 'filling' | 'active' | 'retired';
+}
+/** What a generation's vectors are made with: a declaration that says the same needs no other. */
+export declare const sameVectors: (a: Pick<Search, 'model' | 'dimensions' | 'metric' | 'from'>, b: Pick<Search, 'model' | 'dimensions' | 'metric' | 'from'>) => boolean;
+/**
+ * The table a generation's vectors are in: <schema>__<table>__g<gen>, its
+ * name cut and told apart by a hash where 63 bytes would not hold it.
+ * palgres_search.vectors() says the same in SQL.
+ */
+export declare function vectorTable(tableKey: string, gen: number): string;
+/** A generation's triggers on its table. */
+export declare const searchTriggers: (gen: number) => {
+    insert: string;
+    update: string;
+};
+/** The index the keyword leg reads: one per list of columns, so a new list's is built beside the old one's. */
+export declare function keywordIndex(t: {
+    schema: string;
+    name: string;
+}, from: readonly string[]): string;
+/**
+ * A row's text as it is embedded and as the keyword leg reads it: its `from`
+ * columns in their order, a space between them, NULL as nothing. One
+ * expression for the index, the query and the worker — an index is used only
+ * by the expression it was built on.
+ */
+export declare function sourceText(from: readonly string[], alias?: string): string;
+/** The keyword leg's document: 'simple' — no language's stemming, the words as they are written. */
+export declare const keywordDocument: (from: readonly string[], alias?: string) => string;
+/** How pgvector keeps and compares a generation's vectors: half precision past what a full one can be indexed at. */
+export declare function vectorKind(dimensions: number, metric: SearchMetric): {
+    type: 'vector' | 'halfvec';
+    opclass: string;
+    operator: string;
+};
+/** A table's key ("schema.table") as the relation it names. */
+export declare function relationOf(tableKey: string): string;
+/**
+ * What a generation makes, in one transaction: its row, its vectors' table
+ * (read by the app's roles through the parent's own policies, written by the
+ * service role), the function its triggers run and the triggers. `types`
+ * says where pgvector's types are (the extension's schema).
+ */
+export declare function generationSql(o: {
+    table: {
+        schema: string;
+        name: string;
+    };
+    gen: number;
+    search: Search;
+    status: 'filling' | 'active';
+    pk: {
+        name: string;
+        type: string;
+    };
+    roles: Roles;
+    types: string;
+}): string[];
+/** A generation's triggers on its table: every new row, and every row whose text changes. `replace`: over the ones there, with another staleness. */
+export declare function generationTriggers(o: {
+    table: {
+        schema: string;
+        name: string;
+    };
+    gen: number;
+    from: readonly string[];
+    staleness: Search['staleness'];
+}, replace: boolean): string[];
+/** Every row of a table into a generation's queue: one statement, and run again it adds nothing. */
+export declare function enqueueAllSql(table: {
+    schema: string;
+    name: string;
+}, gen: number, pk: string): string;
+/** What takes a generation away, whatever of it is there: its triggers, its vectors, its function, its queue, its row. */
+export declare function dropGenerationSql(table: {
+    schema: string;
+    name: string;
+}, gen: number): string[];
+/**
+ * What the search schema says of itself (its comment) once searchLedgerSql
+ * made it: this text, for these roles. A migrator that reads it there makes
+ * nothing again; any change to what searchLedgerSql makes changes the number.
+ */
+export declare const searchLedgerMark: (roles: Roles) => string;
+/**
+ * Palgres' search schema, made with its ledger in every database it migrates
+ * (migrate.ts' ensure): the generations, the queue, and promote() — how a
+ * filled generation takes over. Each statement leaves what is there as it
+ * is; the last says it is done (searchLedgerMark).
+ */
+export declare function searchLedgerSql(roles: Roles): string[];
+/** Told when a write to a table with search commits in this process: a worker here need not wait for its next look. */
+export declare const searchWrites: {
+    /** `wake` on every such commit; the return ends it. */
+    listen(wake: () => void): () => void;
+    committed(): void;
+};

package/types/palgres/src/testing/fake.d.ts

@@ -0,0 +1,22 @@
+import type { DBClient } from '../query/client.js';
+type Row = Record<string, unknown>;
+/** One raw SQL call, as it was made. */
+export interface RecordedQuery {
+    sql: string;
+    params: unknown[];
+}
+export interface FakeClient extends DBClient {
+    /** Rows written into a table since it was made: inserts and the inserts of put, claim and plans. */
+    inserted(table: string): Row[];
+    /** Rows as each update left them: update, updateMany, put on a row that was there, plans. */
+    updated(table: string): Row[];
+    /** The ids of the rows deleted from a table. */
+    deleted(table: string): string[];
+    /** The table's rows, from now on: the given ones, copied. */
+    seed(table: string, rows: Row[]): void;
+    /** Every raw SQL call, through any handle — the request's, $asService(), a savepoint's. */
+    readonly queries: readonly RecordedQuery[];
+}
+/** A DBClient in memory: see the top of this file. */
+export declare function createFakeClient(): FakeClient;
+export {};

package/types/palgres/src/testing/index.d.ts

@@ -0,0 +1,2 @@
+export { createFakeClient, type FakeClient, type RecordedQuery } from './fake.js';
+export { typedDatabase } from '../query/surface.js';

package/types/palgres/src/units.d.ts

@@ -0,0 +1,24 @@
+export interface SchemaUnit {
+    /** The Postgres schema it is in: the schema file that carries it. */
+    schema: string;
+    /** What it is and its name, as Introspected.objects keys it. */
+    key: string;
+    /** How Introspected.unmanaged begins its line for it: what a file carrying it no longer lists as left. */
+    listed: string;
+    kind: 'domain' | 'type' | 'sequence' | 'function' | 'view' | 'materialized view' | 'index' | 'trigger';
+    /** A name for it as a schema file's raw unit: letters, digits and _, unique in the schema. */
+    name: string;
+    /** Made before the schema's tables: a column's type or default may need it. */
+    before: boolean;
+    /** Makes it, and leaves one already there as it is. */
+    create: string;
+    drop: string;
+}
+type Query = <T>(text: string) => Promise<T[]>;
+/**
+ * The units of `schemas`, in an order they can be made in. `managed`: the
+ * relations the model carries ("schema.name"); `objects` receives each unit's
+ * text, the key it is compared by.
+ */
+export declare function readUnits(q: Query, inSchemas: string, managed: ReadonlySet<string>, objects: Map<string, string>): Promise<SchemaUnit[]>;
+export {};