@karibsen/eponyme 0.1.1 → 0.3.0

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

@@ -16,7 +16,7 @@ export interface EponymeVersionAuthor {
 }
 export interface EponymeHistoryEntry {
     id: number;
-    action: EponymeAction | 'restore';
+    action: EponymeAction | 'restore' | 'import';
     status: EponymeStatus;
     createdAt: string;
     user: EponymeVersionAuthor | null;
@@ -33,11 +33,47 @@ export interface EponymeCollectionEntry<Data extends Record<string, unknown> = R
     status: EponymeStatus;
     publishedAt: string | null;
     updatedAt: string | null;
+    /** Only set for entries read from the trash. */
+    deletedAt?: string | null;
 }
 export interface EponymeSitemapEntry {
     loc: string;
     lastmod?: string;
 }
+/** One entry of an export file: the complete stored state, without the envelope. */
+export interface EponymeExportEntry {
+    name: string;
+    /** Set for collection entries, so a reader can group them without re-parsing the name. */
+    collection?: string;
+    draft: Record<string, unknown>;
+    published: Record<string, unknown>;
+    status: EponymeStatus;
+    publishedAt: string | null;
+}
+export interface EponymeExportFile {
+    eponyme: {
+        format: 1;
+        exportedAt: string;
+        /** Schema fingerprint per singleton and per collection, checked before an import writes anything. */
+        schemas: Record<string, string>;
+    };
+    entries: EponymeExportEntry[];
+}
+export interface EponymeImportResult {
+    dryRun: boolean;
+    created: number;
+    updated: number;
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+}
+/** The import was refused as a whole, before any write. */
+export interface EponymeImportRejection {
+    errors: string[];
+    /** Names whose configured schema differs from the one the file was exported with. */
+    schemaMismatch?: string[];
+}
 export type EponymeSortDirection = 'asc' | 'desc';
 export interface EponymeCollectionQuery {
     take?: number;
@@ -55,6 +91,11 @@ export type PrismaEponymeRow = {
     name: string;
     data: unknown;
     updatedAt?: Date | string;
+    deletedAt?: Date | string | null;
+};
+/** `null` keeps the live rows, `{ not: null }` the trashed ones. */
+export type PrismaDeletedAtFilter = null | {
+    not: null;
 };
 export type PrismaEponymeVersionRow = {
     id: number;
@@ -96,9 +137,11 @@ export type PrismaEponymeClient = {
             where: {
                 name: string;
                 updatedAt?: Date | string;
+                deletedAt?: PrismaDeletedAtFilter;
             };
             data: {
-                data: Record<string, unknown>;
+                data?: Record<string, unknown>;
+                deletedAt?: Date | null;
             };
         }): Promise<{
             count: number;
@@ -119,6 +162,7 @@ export type PrismaEponymeClient = {
                 name: {
                     startsWith: string;
                 };
+                deletedAt?: PrismaDeletedAtFilter;
             };
             orderBy: Array<{
                 updatedAt: 'desc';
@@ -165,17 +209,51 @@ export declare class EponymeService {
     private readonly client;
     private readonly schemas;
     private readonly collections;
-    constructor(config: EponymeConfig, client: PrismaEponymeClient);
+    /** Entries a read has already persisted the normalized shape for, so it only attempts it once. */
+    private readonly healedByRead;
+    /**
+     * Read-path cache of normalized rows, so a page that reads the same entry from a
+     * singleton, a listing and a layout pays one round trip instead of one per read.
+     * Writers never read from it, so the `updatedAt` they lock on always comes from the
+     * database and a stale key can never turn into a spurious conflict.
+     */
+    private readonly cache;
+    private readonly cacheMs;
+    constructor(config: EponymeConfig, client: PrismaEponymeClient, options?: {
+        cacheSeconds?: number;
+    });
+    private cached;
+    /**
+     * Drops what a write to `name` invalidates: the entry itself, and the listing of the
+     * collection that contains it, whose row set just changed.
+     */
+    private invalidate;
     getSchema(name: string): EponymeSchema | undefined;
     getCollection(name: string): EponymeCollectionDefinitionBase | undefined;
     private getCollectionEntry;
-    /** Reconcile every configured eponyme at application startup. */
+    /** Reconcile every configured eponyme at application startup. This is the one place that heals. */
     syncAll(): Promise<void>;
     private reconcile;
     private createState;
     private normalizeState;
-    /** Reads the stored state along with the `updatedAt` it was read at, used as the optimistic lock token. */
+    /**
+     * 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
+     * round trip on the critical path of a public page.
+     */
+    private loadSingletonRow;
+    /**
+     * Reads the stored state along with the `updatedAt` it was read at, used as the optimistic lock token.
+     *
+     * `heal` persists the normalized state when it differs from what is stored. It has to stay on for
+     * writers, because healing moves `updatedAt` and so decides the lock token they are about to compare.
+     *
+     * `cache` is only ever set for published content. Draft reads serve the preview panel, which has to
+     * show a save immediately, and they come from the dashboard rather than from a public page — so
+     * there is nothing to gain by caching them and a stale preview to lose.
+     */
     private loadRow;
+    private readRow;
     private loadState;
     /**
      * Writes a new state only if the row still carries the `updatedAt` we read.
@@ -183,6 +261,12 @@ export declare class EponymeService {
      * instead of silently discarding their changes.
      */
     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.
+     */
+    private liveCollectionRows;
     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. */
@@ -197,13 +281,40 @@ export declare class EponymeService {
      * one query per collection rather than one query per entry.
      */
     getSitemapEntries(previewPaths: Record<string, string>): Promise<EponymeSitemapEntry[]>;
+    /**
+     * Every singleton and every live collection entry, as a portable file.
+     * Collections are read with one query each rather than one per entry.
+     */
+    exportContent(): Promise<EponymeExportFile>;
+    /**
+     * Applies an export file on top of the current content: every entry it carries is
+     * 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.
+     */
+    importContent(file: unknown, options?: {
+        dryRun?: boolean;
+        actorId?: string;
+    }): Promise<EponymeImportResult | EponymeImportRejection>;
     createCollectionEntry(name: string, payload: unknown, actorId?: string): Promise<(EponymeResult & {
         slug: string;
         errors?: never;
     }) | {
         errors: ValidationErrors;
     } | undefined>;
+    /**
+     * A trashed entry keeps its row, so it keeps its slug: reusing one has to be
+     * refused with an error the editor can act on rather than the generic message.
+     */
+    private slugTakenError;
+    /** Moves an entry to the trash. Its history is kept, so it stays restorable. */
     deleteCollectionEntry(name: string): Promise<boolean>;
+    restoreCollectionEntry(name: string): Promise<boolean>;
+    /** Definitive: `onDelete: Cascade` takes the entry's whole history with it. */
+    purgeCollectionEntry(name: string): Promise<boolean>;
+    /** Trashed entries of a collection, most recently updated first. */
+    listCollectionTrash(name: string): Promise<EponymeCollectionPage | undefined>;
     patch(name: string, payload: unknown, action?: EponymeAction, actorId?: string): Promise<(EponymeResult & {
         errors?: never;
         conflict?: never;
@@ -214,4 +325,6 @@ export declare class EponymeService {
     history(name: string, limit?: number): Promise<EponymeHistoryEntry[] | undefined>;
     restore(name: string, versionId: number, actorId?: string): Promise<EponymeResult | EponymeConflict | undefined>;
 }
+/** Stable hash of a schema's shape, embedded in an export and checked on import. */
+export declare function schemaFingerprint(schema: EponymeSchema): string;
 export declare function isPrismaError(error: unknown, code: string): boolean;