@karibsen/eponyme 0.6.0 → 0.8.0

package/dist/runtime/server/services/eponyme-store.d.ts

@@ -1,5 +1,6 @@
 import type { EponymeCollectionDefinitionBase, EponymeConfig, EponymeSchema } from '../../types/index.js';
 import { type ValidationErrors } from '../../utils/validate-eponyme-data.js';
+import { type EponymeIndexRow } from '../../utils/eponyme-entry-index.js';
 export type EponymeAction = 'draft' | 'publish';
 export type EponymeVersion = 'draft' | 'published';
 /** Either the live draft/published content, or a numeric id from the version history. */
@@ -75,11 +76,31 @@ export interface EponymeImportRejection {
     schemaMismatch?: string[];
 }
 export type EponymeSortDirection = 'asc' | 'desc';
+/** Comparisons a filter may ask for. Only fields stored in a sortable text form accept one. */
+export interface EponymeFilterRange {
+    gte?: string;
+    lte?: string;
+    gt?: string;
+    lt?: string;
+}
+export interface EponymeFilterOperators extends EponymeFilterRange {
+    in?: string[];
+    /** Excluded values. Resolved by subtraction: the index only records what is there. */
+    not?: string[];
+    contains?: string;
+}
+/**
+ * One condition of a `where`. A list means "any of these", so the values of one key are
+ * ORed together while the keys themselves are ANDed.
+ */
+export type EponymeFilterCondition = string | string[] | EponymeFilterOperators;
 export interface EponymeCollectionQuery {
     take?: number;
     skip?: number;
     orderBy?: string;
     order?: EponymeSortDirection;
+    /** Keyed by field name. Only the keys `collectionFilterKeys` reports can be used. */
+    where?: Record<string, EponymeFilterCondition>;
 }
 export interface EponymeCollectionPage<Data extends Record<string, unknown> = Record<string, unknown>> {
     entries: EponymeCollectionEntry<Data>[];
@@ -87,12 +108,65 @@ export interface EponymeCollectionPage<Data extends Record<string, unknown> = Re
     total: number;
 }
 export declare const COLLECTION_METADATA_KEYS: readonly ["updatedAt", "publishedAt", "title", "slug"];
+/**
+ * A content row. Everything but the name is optional because a query narrows what it reads —
+ * a public listing selects `published` and never `draft` — and a narrowed row has to satisfy
+ * this type as it is, without an overload per shape.
+ */
 export type PrismaEponymeRow = {
     name: string;
-    data: unknown;
+    draft?: unknown;
+    published?: unknown;
+    status?: string;
+    publishedAt?: Date | string | null;
     updatedAt?: Date | string;
     deletedAt?: Date | string | null;
 };
+export type EponymeRowWrite = {
+    draft: Record<string, unknown>;
+    published: Record<string, unknown>;
+    status: EponymeStatus;
+    publishedAt: Date | null;
+};
+export type PrismaEponymeSelect = {
+    name?: true;
+    draft?: true;
+    published?: true;
+    status?: true;
+    publishedAt?: true;
+    updatedAt?: true;
+};
+export type PrismaEponymeQuery = {
+    where: {
+        /** `in` is what a filtered listing uses: the index resolves the names first. */
+        name: {
+            startsWith: string;
+        } | {
+            in: string[];
+        };
+        deletedAt?: PrismaDeletedAtFilter;
+        publishedAt?: {
+            not: null;
+        };
+    };
+    orderBy?: PrismaEponymeOrderBy[];
+    take?: number;
+    skip?: number;
+};
+/**
+ * `nulls` appears on `publishedAt` alone: Prisma refuses it on a column that cannot be null,
+ * and `updatedAt` never is. A test double cannot catch that — only the real client does.
+ */
+export type PrismaEponymeOrderBy = {
+    name: 'asc';
+} | {
+    updatedAt: EponymeSortDirection;
+} | {
+    publishedAt: {
+        sort: EponymeSortDirection;
+        nulls: 'last';
+    };
+};
 /** `null` keeps the live rows, `{ not: null }` the trashed ones. */
 export type PrismaDeletedAtFilter = null | {
     not: null;
@@ -110,27 +184,27 @@ export type PrismaEponymeVersionRow = {
         username: string;
     } | null;
 };
-export type PrismaEponymeClient = {
+/**
+ * The model delegates, which a transaction exposes just like the client does.
+ * They are named on their own because Prisma hands an interactive transaction a client
+ * stripped of `$transaction`, so the callback cannot be typed as the full client.
+ */
+export type PrismaEponymeDelegates = {
     eponyme: {
         upsert(args: {
             where: {
                 name: string;
             };
-            create: {
+            create: EponymeRowWrite & {
                 name: string;
-                data: Record<string, unknown>;
-            };
-            update: {
-                data?: Record<string, unknown>;
             };
+            update: Partial<EponymeRowWrite>;
         }): Promise<PrismaEponymeRow>;
         update(args: {
             where: {
                 name: string;
             };
-            data: {
-                data: Record<string, unknown>;
-            };
+            data: EponymeRowWrite;
         }): Promise<PrismaEponymeRow>;
         /** Used as a compare-and-swap: the `updatedAt` guard makes concurrent writes fail instead of overwriting. */
         updateMany(args: {
@@ -139,17 +213,15 @@ export type PrismaEponymeClient = {
                 updatedAt?: Date | string;
                 deletedAt?: PrismaDeletedAtFilter;
             };
-            data: {
-                data?: Record<string, unknown>;
+            data: Partial<EponymeRowWrite> & {
                 deletedAt?: Date | null;
             };
         }): Promise<{
             count: number;
         }>;
         create(args: {
-            data: {
+            data: EponymeRowWrite & {
                 name: string;
-                data: Record<string, unknown>;
             };
         }): Promise<PrismaEponymeRow>;
         findUnique(args: {
@@ -157,19 +229,14 @@ export type PrismaEponymeClient = {
                 name: string;
             };
         }): Promise<PrismaEponymeRow | null>;
-        findMany(args: {
-            where: {
-                name: {
-                    startsWith: string;
-                };
-                deletedAt?: PrismaDeletedAtFilter;
-            };
-            orderBy: Array<{
-                updatedAt: 'desc';
-            } | {
-                name: 'asc';
-            }>;
+        /**
+         * One signature rather than an overload per `select`: every column of
+         * `PrismaEponymeRow` but `name` is optional, so a narrowed row satisfies it as it is.
+         */
+        findMany(args: PrismaEponymeQuery & {
+            select?: PrismaEponymeSelect;
         }): Promise<PrismaEponymeRow[]>;
+        count(args: PrismaEponymeQuery): Promise<number>;
         delete(args: {
             where: {
                 name: string;
@@ -204,6 +271,94 @@ export type PrismaEponymeClient = {
             };
         }): Promise<PrismaEponymeVersionRow | null>;
     };
+    eponymeEntryIndex: {
+        /** The rows of an entry are replaced as a whole, so a removed value cannot survive. */
+        deleteMany(args: {
+            where: {
+                entryName: string | {
+                    startsWith: string;
+                };
+            };
+        }): Promise<{
+            count: number;
+        }>;
+        createMany(args: {
+            data: EponymeIndexRow[];
+        }): Promise<{
+            count: number;
+        }>;
+        findMany(args: {
+            where: {
+                entryName: {
+                    startsWith: string;
+                };
+                version: 'draft' | 'published';
+                key: string;
+                value: PrismaStringFilter;
+            };
+            select: {
+                entryName: true;
+            };
+        }): Promise<Array<{
+            entryName: string;
+        }>>;
+    };
+    eponymeIndexState: {
+        findMany(): Promise<Array<{
+            name: string;
+            fingerprint: string;
+        }>>;
+        upsert(args: {
+            where: {
+                name: string;
+            };
+            create: {
+                name: string;
+                fingerprint: string;
+            };
+            update: {
+                fingerprint: string;
+            };
+        }): Promise<{
+            name: string;
+            fingerprint: string;
+        }>;
+        deleteMany(args: {
+            where: {
+                name: {
+                    in: string[];
+                };
+            };
+        }): Promise<{
+            count: number;
+        }>;
+    };
+};
+/**
+ * What one condition asks the index for. Text order is the point: a range only makes sense
+ * because every indexed value is stored in a form whose alphabetical order is its natural
+ * one — see `buildEponymeIndexRows`.
+ */
+export type PrismaStringFilter = string | {
+    in?: string[];
+    /** Substring match. A leading wildcard cannot use the index's ordering, so this scans. */
+    contains?: string;
+    gte?: string;
+    lte?: string;
+    gt?: string;
+    lt?: string;
+};
+export type PrismaEponymeClient = PrismaEponymeDelegates & {
+    /**
+     * Prisma's interactive transaction. Writes that only make sense together — an entry and
+     * its history version, an import and every version it writes — run inside one, so a
+     * failure between the two rolls back instead of leaving the history disagreeing with
+     * the content it describes.
+     */
+    $transaction<T>(fn: (tx: PrismaEponymeDelegates) => Promise<T>, options?: {
+        maxWait?: number;
+        timeout?: number;
+    }): Promise<T>;
 };
 export declare class EponymeService {
     private readonly client;
@@ -228,14 +383,81 @@ export declare class EponymeService {
      * collection that contains it, whose row set just changed.
      */
     private invalidate;
+    /**
+     * Replaces an entry's filterable values, in the same transaction as the write that
+     * changed them.
+     *
+     * Deleting before inserting rather than diffing: an entry carries a handful of rows, the
+     * two statements are cheap, and a diff is one more place for the index to drift from the
+     * content it describes — a failure mode that returns wrong listings without erroring.
+     */
+    private reindexEntry;
+    collectionFilterKeys(name: string): string[] | undefined;
+    /**
+     * One transaction per entry rather than one for the whole collection: a collection has no
+     * bound, and a single transaction over it would exceed Prisma's timeout on anything real.
+     * The unit that has to be atomic is the entry, and it is.
+     */
+    private reindexName;
+    private indexedNames;
+    /**
+     * The unconditional rebuild, for a first backfill or a manual repair. It refreshes the
+     * recorded fingerprints too, so a repair does not leave the next boot with work to redo.
+     */
+    reindexAll(): Promise<{
+        entries: number;
+    }>;
+    /**
+     * Rebuilds only what a configuration change invalidated, and nothing when nothing changed.
+     *
+     * This is what makes the index self-maintaining. Ordinary writes keep it current, but a
+     * newly filterable field leaves the entries already stored without any row for that key —
+     * and a filter on them then answers "none" rather than failing, which is the worst way for
+     * this to break.
+     *
+     * Unchanged configuration costs one read of a table with one row per collection.
+     */
+    syncIndexState(): Promise<{
+        reindexed: string[];
+    }>;
+    private indexFingerprint;
+    private writeIndexState;
+    /**
+     * Runs writes that have to land together, then drops what they invalidated.
+     *
+     * The callback reports the entries it touched rather than invalidating them itself:
+     * inside the transaction the write has not landed yet, and a read racing an
+     * uncommitted change would re-cache the old row and hold it for the whole TTL. The
+     * drop is deliberate on a rollback too — losing a cache entry costs one query, while
+     * keeping a wrong one costs the TTL.
+     */
+    private transaction;
     getSchema(name: string): EponymeSchema | undefined;
     getCollection(name: string): EponymeCollectionDefinitionBase | undefined;
     private getCollectionEntry;
     /** Reconcile every configured eponyme at application startup. This is the one place that heals. */
     syncAll(): Promise<void>;
+    /**
+     * Brings a stored document back in line with the schema: keys the schema no longer declares
+     * are dropped, and a key it declares but the document lacks takes its default.
+     *
+     * Recursive, because a field added inside a section, a tab or an array item is otherwise
+     * never filled in: the container it lives in already exists and is still valid, so a
+     * top-level pass keeps it untouched and the new field reads as missing forever. That was
+     * silent — `defaultValue` simply did nothing for anything but a root field.
+     */
     private reconcile;
+    /** Descends into the containers; a leaf is returned untouched for `reconcile` to judge. */
+    private reconcileField;
     private createState;
+    /**
+     * Reads a state out of an envelope. Live content is in columns now, so this serves the two
+     * places an envelope still exists: a history row, which deliberately keeps the old shape so
+     * that versions written before this change stay restorable, and an import, which rebuilds
+     * one from the portable file.
+     */
     private normalizeState;
+    private rowToState;
     /**
      * A singleton row is created on first read, but only when it is genuinely missing.
      * An `upsert` would send a write on every read instead, and each one costs a database
@@ -259,14 +481,33 @@ export declare class EponymeService {
      * Writes a new state only if the row still carries the `updatedAt` we read.
      * Returns false when a concurrent editor won the race, so the caller can report a conflict
      * instead of silently discarding their changes.
+     *
+     * Dropping the cached row is left to `transaction`, which does it once the write has
+     * actually committed rather than while it is still in flight.
      */
     private writeState;
     /**
-     * The live rows of a collection, shared by the public listing and the sitemap so both
-     * read them once. The trash and the export deliberately query around it: one wants the
-     * rows this filter excludes, the other must not see a cached view of the content.
+     * Every live row of a collection, payload included. The reindex needs both versions of the
+     * content, so this is the one read that still selects everything; a listing goes through
+     * `collectionRows` with a narrower select.
      */
     private liveCollectionRows;
+    /**
+     * The names a `where` keeps, resolved from the index table before a single row of content
+     * is read. This is the point of the index: a filtered listing loads and normalizes the
+     * entries it returns, not the whole collection.
+     *
+     * One query per key, intersected: the values of a key are ORed by the query itself, and
+     * the keys are ANDed by narrowing the set. An empty set short-circuits the whole listing.
+     */
+    private resolveFilter;
+    private indexNames;
+    private collectionEntryNames;
+    /**
+     * The rows a filter selected. Never cached: the shared `rows:` key holds the whole
+     * collection, and one key per filter combination would evict it for no reuse.
+     */
+    private filteredCollectionRows;
     get(name: string, version?: EponymeVersionSelector): Promise<Record<string, unknown> | undefined>;
     getResult(name: string, version?: EponymeVersionSelector): Promise<EponymeResult | undefined>;
     /** Content as it was in a given version, for previewing without restoring it. */
@@ -275,6 +516,17 @@ export declare class EponymeService {
     /** Metadata keys that can be sorted on, alongside every field of the collection. */
     collectionSortKeys(name: string): string[] | undefined;
     listCollection(name: string, version?: EponymeVersion, query?: EponymeCollectionQuery): Promise<EponymeCollectionPage | undefined>;
+    /**
+     * The unpaginated read, still cached: an unfiltered listing of one collection is what a
+     * page hits repeatedly, and the key carries the version so a draft view cannot answer a
+     * public one.
+     */
+    private collectionRows;
+    /**
+     * `findMany` already carries every payload, so the state is built here rather than re-read
+     * one entry at a time: a listing costs one query, not N+1.
+     */
+    private toCollectionEntries;
     /**
      * Builds the public URL list configured by `previewPaths`.
      * Collections are resolved directly from their stored rows so this performs
@@ -291,12 +543,19 @@ export declare class EponymeService {
      * upserted, everything else is left alone. Nothing is ever deleted.
      *
      * The schema check runs first and refuses the whole file, so an import can never
-     * land half of its entries into a configuration that no longer matches.
+     * land half of its entries into a configuration that no longer matches. The writes then
+     * run in one transaction, so a failure partway through leaves nothing behind either —
+     * an interrupted import can simply be replayed.
      */
     importContent(file: unknown, options?: {
         dryRun?: boolean;
         actorId?: string;
     }): Promise<EponymeImportResult | EponymeImportRejection>;
+    /**
+     * The body of an import, over whichever client it was handed: the live one for a dry
+     * run, a transaction for the real thing.
+     */
+    private applyImport;
     createCollectionEntry(name: string, payload: unknown, actorId?: string): Promise<(EponymeResult & {
         slug: string;
         errors?: never;