primitive-admin 1.2.0-alpha.1 → 1.2.0-alpha.11

package/dist/src/lib/db3-export.d.ts

@@ -0,0 +1,231 @@
+/**
+ * `primitive db3 export` and `primitive db3 import` (#4889): a db3 written
+ * to a directory, and a directory loaded into a db3.
+ *
+ * An export is a directory holding `db3.json` (the manifest: the db3's id,
+ * title and tags, its type by name and revision, its declaration as
+ * `GET db3/:id/schema` answers it, the indexes registered through the index
+ * routes, the log number the rows are at), the rows under `snapshot/` and
+ * `chain.json` as `documents export` writes a record-log document's, and
+ * the blobs under `blobs/`. It carries no grant, custody, sync state or alias:
+ * those belong to the app the db3 lives in.
+ *
+ * An import does every check before any write: the manifest's type must be
+ * one the app has, with an equal declaration (or `--untyped`); a `--into`
+ * target must be of the manifest's type and declare its models alike; and
+ * blobs are imported under their ids, so the source db3 must be gone from the
+ * app first. Then it creates the db3 (or confirms `--into`), registers the
+ * indexes an untyped target needs before any row, loads the rows through the
+ * db3's bulk-load session and uploads the blobs.
+ *
+ * The planner (`planDb3Import`) and the comparison (`compareDeclarations`)
+ * are pure; the verbs in `../commands/db3.ts` read what they need and drive
+ * the steps.
+ */
+import type { ApiClient } from "./api-client.js";
+import { type IngestOutcome } from "./document-ingest.js";
+/** The manifest file an export writes and an import reads. */
+export declare const DB3_MANIFEST = "db3.json";
+/** One model's declaration: its fields' options and its compound unique constraints by name. */
+export interface Db3ModelDeclaration {
+    fields: Record<string, Record<string, unknown>>;
+    constraints?: Record<string, {
+        type: "unique";
+        fields: string[];
+    }>;
+}
+/** What a db3 declares, model by model. */
+export interface Db3Declaration {
+    models: Record<string, Db3ModelDeclaration>;
+}
+/** An index registered through `POST db3/:id/indexes`, as `GET db3/:id/indexes` lists it. */
+export interface Db3RegisteredIndex {
+    name: string;
+    model: string;
+    fields: string[];
+    unique: boolean;
+}
+/** `db3.json`. */
+export interface Db3ExportManifest {
+    kind: "db3-export";
+    version: 1;
+    id: string;
+    title: string | null;
+    tags: string[];
+    type: {
+        name: string;
+        revision: {
+            generation: number;
+            hash: string;
+        } | null;
+    } | null;
+    declaration: Db3Declaration;
+    indexes: Db3RegisteredIndex[];
+    lsn: number;
+    exportedAt: string;
+}
+/** A blob as `blobs/index.json` lists it. */
+export interface Db3ExportedBlob {
+    blobId: string;
+    filename: string;
+    contentType: string;
+    sha256: string;
+    numBytes: number;
+}
+/** One `POST db3/:id/indexes` body. */
+export type Db3IndexRegistration = {
+    model: string;
+    field: string;
+    unique?: true;
+} | {
+    model: string;
+    fields: string[];
+    name: string;
+    unique: true;
+};
+/**
+ * The declaration `GET db3/:id/schema` answers. The answer gives a declared
+ * model with no fields and a live undeclared model alike, `{ fields: {} }`,
+ * so such a model is kept only when `declaredModels` names it: the models a
+ * typed db3's type declares ({@link declaredModelNames}). A type that
+ * declares no models holds any model undeclared, and an untyped db3
+ * declares none.
+ */
+export declare function declarationOfSchemaAnswer(answer: any, options?: {
+    declaredModels?: Iterable<string>;
+}): Db3Declaration;
+/** The models a db3 type's schema TOML declares, by name. */
+export declare function declaredModelNames(schema: unknown): string[];
+/** The declaration a db3 type's schema TOML installs (`GET db3-types/:name`'s `schema`). */
+export declare function declarationOfTypeSchema(schema: unknown): Db3Declaration;
+/**
+ * The differences between the declaration an export holds and the one a
+ * type or a target installs, one line per model, field or constraint; none
+ * when they are equal. Order is ignored: of models, fields, constraints and
+ * a constraint's fields. A field compares by its kind and its `indexed` and
+ * `unique` flags. With `only: "installed"`, only the models `installed`
+ * declares are compared (an `--untyped` import into a target that already
+ * declares some of them).
+ */
+export declare function compareDeclarations(exported: Db3Declaration, installed: Db3Declaration, options?: {
+    only?: "installed";
+    installedName?: string;
+}): string[];
+/**
+ * The index registrations that install `declaration`'s indexes and uniques,
+ * and `indexes`, on an untyped db3: one per model and set of fields, unique
+ * when either source holds it unique (a registration over the same fields
+ * replaces the earlier one's uniqueness, so a later non-unique one would
+ * lift it), each compound name a valid identifier no other of the model's
+ * registrations takes.
+ */
+export declare function registrationsFor(declaration: Db3Declaration, indexes?: Db3RegisteredIndex[]): Db3IndexRegistration[];
+/** An index as `GET db3/:id/indexes` lists it. */
+export interface Db3ListedIndex {
+    name: string;
+    model: string;
+    fields: string[];
+    unique: boolean;
+}
+/**
+ * `register` against the indexes a target already has: a registration an
+ * index over the same fields already serves, as unique or more, is left out
+ * (so an existing unique index is never registered again without `unique`,
+ * which would lift it, and a constraint the target holds is not registered
+ * a second time under another name); a named registration whose name the
+ * target gives an index over other fields is a conflict.
+ */
+export declare function pendingRegistrations(register: Db3IndexRegistration[], existing: Db3ListedIndex[]): {
+    register: Db3IndexRegistration[];
+    kept: string[];
+    conflicts: string[];
+};
+/** What the import was asked. */
+export interface Db3ImportFlags {
+    into?: string;
+    title?: string;
+    type?: string;
+    untyped?: boolean;
+    noBlobs?: boolean;
+    /** Create the new db3 under the export's id (`--keep-id`, #4921). */
+    keepId?: boolean;
+}
+/** What the import read before deciding: the type, the target, whether the source is still in the app. */
+export interface Db3ImportFacts {
+    /** The type the import resolved (`--type`, else the manifest's), as `GET db3-types/:name` answered it; `null` when the app has none of that name. */
+    type?: {
+        name: string;
+        schema: unknown;
+        revision?: {
+            generation: number;
+            hash: string;
+        } | null;
+    } | null;
+    /** The `--into` target: its row, its declaration and the indexes it has. */
+    target?: {
+        row: any;
+        declaration: Db3Declaration;
+        indexes?: Db3ListedIndex[];
+    };
+    /** Blobs `blobs/index.json` lists. */
+    blobCount: number;
+    /** Whether `GET db3/<manifest.id>` found the source in the app; asked when blobs are imported or the id is kept. */
+    sourceExists?: boolean;
+}
+/** The import's decision: a refusal before any write, or its steps. */
+export type Db3ImportPlan = {
+    ok: false;
+    refusal: string;
+    lines?: string[];
+} | {
+    ok: true;
+    /** The type name the import resolved, or `null`. */
+    typeName: string | null;
+    /** `POST db3`'s body, or absent for `--into`; `id` is the export's under `--keep-id`. */
+    create?: {
+        title: string;
+        type?: string;
+        tags: string[];
+        id?: string;
+    };
+    into?: string;
+    /** Registered before the rows. */
+    register: Db3IndexRegistration[];
+    blobs: boolean;
+    /** Said beside the import, not judged (a hash that also covers hooks). */
+    notes: string[];
+};
+/** The type name an import resolves: `--type`, else the manifest's; none under `--untyped` without one. */
+export declare function resolvedTypeName(manifest: Db3ExportManifest, flags: Db3ImportFlags): string | null;
+/**
+ * Decide an import from what was read, before any write: a refusal naming
+ * what to do, or the steps.
+ */
+export declare function planDb3Import(manifest: Db3ExportManifest, flags: Db3ImportFlags, facts: Db3ImportFacts): Db3ImportPlan;
+/** Read `<dir>/db3.json`, or `null` when the directory has none. */
+export declare function readDb3Manifest(dir: string): Db3ExportManifest | null;
+/** The blobs `<dir>/blobs/index.json` lists; none without one. */
+export declare function readExportedBlobs(dir: string): Db3ExportedBlob[];
+/** What `db3 export` wrote. */
+export interface Db3ExportResult {
+    manifest: Db3ExportManifest;
+    dir: string;
+    rows: number;
+    blobs: number;
+}
+/**
+ * Write db3 `db3Id` to `dir`: the rows (a segment export, as `documents
+ * export` writes a record-log document's), `chain.json`, the blobs unless
+ * `blobs` is false, and `db3.json` last, so a directory with a manifest is a
+ * finished export.
+ */
+export declare function exportDb3(client: ApiClient, appId: string, db3Id: string, dir: string, options: {
+    blobs: boolean;
+    onProgress?: (line: string) => void;
+}): Promise<Db3ExportResult>;
+/**
+ * Load an export's rows into `db3Id` through its bulk-load session (merge,
+ * the epoch reserved at open), waited to a terminal state. Answers the
+ * session's outcome, or `null` when the export holds no rows.
+ */
+export declare function loadDb3Rows(client: ApiClient, appId: string, db3Id: string, dir: string, onProgress: (line: string) => void): Promise<IngestOutcome | null>;