@quereus/store 4.5.0 → 4.7.0

package/dist/src/common/store-module-catalog.d.ts

@@ -0,0 +1,269 @@
+/**
+ * The catalog store: how a table / view / materialized view's DDL text is turned
+ * into a persisted entry, written, compared, reloaded and removed, plus the two
+ * pieces of durable open/close bookkeeping that live beside it (the clean-shutdown
+ * marker and the stale-materialized-view set).
+ *
+ * Second layer of the store-module chain:
+ *   StoreModuleBase -> StoreModuleCatalog -> StoreModuleSchemaSync -> StoreModuleIndex
+ *   -> StoreModuleAlterColumn -> StoreModuleAlter -> StoreModuleRename -> StoreModule
+ */
+import type { CatalogObjectKind, Database, MaintainedTableSchema, TableSchema, ViewSchema } from '@quereus/quereus';
+import { StoreModuleBase } from './store-module-base.js';
+export declare abstract class StoreModuleCatalog extends StoreModuleBase {
+    /**
+     * Build the catalog entry for a table: its CREATE TABLE DDL, one
+     * `CREATE [UNIQUE] INDEX` statement per persistable secondary index, and one
+     * `alter index … set tags (…)` statement per exposed implicit index carrying
+     * user tags, newline-joined into a single multi-statement bundle keyed by
+     * `{schema}.{table}`.
+     *
+     * Bundling the indexes into the table's own entry means every existing
+     * re-persist path — `saveTableDDL` (each `alterTable` arm, `renameTable`) and
+     * the `table_modified` listener (`persistCatalogIfChanged`) — carries the
+     * indexes along for free, and `removeTableDDL` drops them with the table. The
+     * bundle is consumed on reopen by `rehydrateCatalog` → `importCatalog`, whose
+     * `parser.parseAll` splits it AST-by-AST (never on `\n`) and imports each
+     * statement in document order, so the table registers before its indexes.
+     *
+     * Both the table DDL and the index DDL are emitted without a `db` arg, keeping
+     * the persistence-safe fully-qualified form. Hidden implicit covering indexes
+     * (the auto-built BTree backing a declared UNIQUE constraint) are excluded —
+     * they are a backing detail that round-trips via the table's UNIQUE constraint,
+     * not as a standalone CREATE INDEX. For store tables `buildTableSchemaFromAST`
+     * synthesizes none of those, so in practice every index is included; the guard
+     * is defensive. A `CREATE UNIQUE INDEX`'s derived UNIQUE constraint is already
+     * excluded from the table DDL by the generator, so it round-trips solely via
+     * its own `CREATE UNIQUE INDEX` line — no doubling.
+     *
+     * An *exposed* implicit index (a non-derived UNIQUE constraint tagged
+     * `quereus.expose_implicit_index = true`, never materialized in store mode)
+     * must NOT get a synthetic `CREATE INDEX` line — re-import would materialize a
+     * real `IndexSchema` and change the store-mode shape. Its user tags
+     * (`UniqueConstraintSchema.exposedIndexTags`) instead ride a trailing
+     * `alter index … set tags` line, which `importDDL` re-applies silently after
+     * the CREATE TABLE in the same entry has registered the constraint. Empty tag
+     * records emit no line, and `exposedImplicitIndexes` returns `[]` for
+     * memory-mode tables (name materialized) and orders descriptors by the
+     * `uniqueConstraints` array, so the bundle stays byte-deterministic — which
+     * the compare-write in `persistCatalogIfChanged` relies on.
+     */
+    private buildCatalogEntry;
+    /**
+     * Encode a bundle of persisted schema text (DDL) for the catalog store.
+     * The guard is {@link assertPersistableDdlText} — see it for why the FULL text
+     * is checked, not just the object's name.
+     */
+    private encodeCatalogDDL;
+    /**
+     * The catalog entry a plain table would be persisted as: its `{schema}.{table}` key
+     * (which {@link buildCatalogKey} refuses for an unencodable identifier) plus the DDL
+     * bundle {@link buildCatalogEntry} produces. Counterpart of {@link viewCatalogEntry} /
+     * {@link maintainedViewCatalogEntry}, and shared the same way — by both write paths
+     * ({@link saveTableDDL}, {@link persistTableCatalogEntryIfChanged}) and by the
+     * pre-flight veto ({@link assertCatalogObjectPersistable}) — so they cannot drift.
+     */
+    private tableCatalogEntry;
+    /**
+     * Save table DDL (bundled with its secondary index DDL) to the catalog store.
+     * Unconditional put — every caller has just produced the authoritative bundle
+     * (create-index / drop-index / an `alterTable` arm / `renameTable`). For the
+     * event-driven `table_added` path, which may be re-delivered over an entry that
+     * is already current, use {@link persistTableCatalogEntryIfChanged}.
+     */
+    saveTableDDL(tableSchema: TableSchema): Promise<void>;
+    /**
+     * Compare-write a TABLE's catalog entry: write when the entry is absent or its
+     * bundle differs, skip when identical.
+     *
+     * Two callers, both needing exactly this shape:
+     * - the `table_added` arm of `StoreModuleSchemaSync.dispatchSchemaChange` — the
+     *   authoritative write for a freshly registered store table, including one nobody
+     *   ever reads or writes;
+     * - `StoreTableBase.initializeStore`'s first-storage-access backstop, which the
+     *   `table_added` write normally renders a no-op.
+     *
+     * Distinct from both neighbours on purpose:
+     * - not {@link persistCatalogIfChanged}, whose absent → skip self-filter is exactly
+     *   the case this path exists to cover (a brand-new table has no entry yet);
+     * - not bare {@link saveTableDDL}, which always puts — `table_added` is also
+     *   delivered during rehydration for a store-hosted materialized-view backing, where
+     *   the entry is already current and a blind put would dirty otherwise-identical
+     *   catalog bytes.
+     *
+     * Shares {@link tableCatalogEntry} with the write and veto paths so all three agree
+     * on what a table's entry is.
+     */
+    persistTableCatalogEntryIfChanged(tableSchema: TableSchema): Promise<void>;
+    /**
+     * Remove DDL from the catalog store when a table is dropped.
+     */
+    removeTableDDL(schemaName: string, tableName: string): Promise<void>;
+    /**
+     * Persist a plain view's catalog entry (DDL via `generateViewDDL`), keyed by its
+     * reserved view prefix. Compare-write (skip identical) — see
+     * {@link persistObjectCatalogEntryIfChanged}.
+     */
+    saveViewDDL(view: ViewSchema): Promise<void>;
+    /** Remove a plain view's catalog entry (on DROP VIEW). */
+    removeViewDDL(schemaName: string, viewName: string): Promise<void>;
+    /**
+     * Persist a materialized view's catalog entry (DDL via `generateMaintainedTableDDL`
+     * over the maintained table — the unified record), keyed by its reserved MV
+     * prefix. Compare-write (skip identical) — see
+     * {@link persistObjectCatalogEntryIfChanged}.
+     */
+    saveMaterializedViewDDL(mv: MaintainedTableSchema): Promise<void>;
+    /** Remove a materialized view's catalog entry (on DROP MATERIALIZED VIEW). */
+    removeMaterializedViewDDL(schemaName: string, mvName: string): Promise<void>;
+    /**
+     * Pre-flight veto (see `VirtualTableModule.assertCatalogObjectPersistable`): refuse a
+     * view / materialized view / table whose catalog entry this module could not durably
+     * write.
+     *
+     * It runs exactly the derivation the write path runs — {@link viewCatalogEntry} /
+     * {@link maintainedViewCatalogEntry} / {@link tableCatalogEntry} build the key
+     * (rejecting an unencodable identifier) and {@link assertPersistableDdlText} checks the
+     * generated DDL text — so the veto and the write cannot disagree about what is
+     * persistable. It is the only synchronous path a rejection can travel: the actual save
+     * is chained onto `persistQueue` behind a `SchemaChangeNotifier` listener, and both
+     * layers swallow.
+     *
+     * The `'table'` kind arrives only from the RENAME pre-flight scan, which offers EVERY
+     * table in every schema whose record the propagation would rewrite — most of them not
+     * ours. {@link ownsTableCatalogEntry} is the synchronous self-filter that keeps a
+     * memory-backed dependent from being refused on our behalf.
+     *
+     * Gated on `subscribedDb === db`: this module persists a view/MV only while subscribed
+     * to that `Database`'s change notifier. Since `StoreModule.onRegister` subscribes at
+     * `Database.registerModule` — before any statement can run — the gate no longer
+     * shields an unsubscribed module from vetoing; it now only declines to answer on
+     * behalf of a *different* `Database` than the one this module serves (the
+     * one-instance-one-database posture `ensureSchemaSubscription` documents). That case
+     * writes nothing, so vetoing there would reject a definition that loses nothing.
+     */
+    assertCatalogObjectPersistable(db: Database, kind: CatalogObjectKind, object: ViewSchema | TableSchema): void;
+    /**
+     * The entry {@link assertCatalogObjectPersistable} is being asked about, or `undefined`
+     * when this module would write none for it (a non-maintained table offered as
+     * `'materializedView'`, or a table we do not own).
+     */
+    private prospectiveCatalogEntry;
+    /**
+     * Whether this module would be the one to write `table`'s catalog entry — the
+     * synchronous stand-in for the write path's absent-entry self-filter (see
+     * {@link persistCatalogIfChanged}), which reads the catalog store and so is unavailable
+     * to a hook that is synchronous and IO-free by contract.
+     *
+     * Also the self-filter for the `table_added` catalog write in
+     * `StoreModuleSchemaSync.dispatchSchemaChange`, which is likewise handed every table the
+     * engine registers regardless of who owns it.
+     *
+     * Ownership is tested exactly as `StoreModule.resolveOwnedTable` tests it: a table this
+     * session already touched (it is in `tables`), or one whose `vtabModule` is this module
+     * — or a WRAPPER exposing this module as `underlying`, which is what a store table looks
+     * like under `@quereus/quereus-isolation` (its `vtabModule` is the `IsolationModule`).
+     * Not ours ⇒ no entry ⇒ no check, which is what keeps a memory-backed dependent table in
+     * a database that also has store tables from being refused.
+     *
+     * It now agrees exactly with the `table_added` write path, which applies this same
+     * filter and then compare-writes ({@link persistTableCatalogEntryIfChanged}) with no
+     * absent → skip. It stays STRICTER than the `table_modified` write path
+     * ({@link persistCatalogIfChanged}), which skips an absent entry; refusing there is the
+     * safe side, since that table's own catalog write would throw on the diverged text
+     * anyway, on the swallowing persist queue with nothing left to tell the user.
+     */
+    protected ownsTableCatalogEntry(table: TableSchema): boolean;
+    /**
+     * Compare-write a catalog entry: write only when the entry is absent or its DDL
+     * differs from `newDDL` (skip identical). Unlike {@link persistCatalogIfChanged}
+     * there is **no** absent→skip self-filter — the callers have already established
+     * that the object belongs in this db's catalog (a view/MV unconditionally, since
+     * one module instance serves one Database; a table via
+     * {@link persistTableCatalogEntryIfChanged}'s ownership filter). Skipping identical
+     * writes makes any event whose regenerated DDL is unchanged (e.g. a
+     * `materialized_view_refreshed`, or a `table_added` re-delivered for an
+     * already-persisted materialized-view backing during rehydration) a no-op, so a
+     * second consecutive reopen yields identical catalog bytes. (View/MV rehydration
+     * itself fires no view/MV events at all — `importCatalog` is silent.)
+     */
+    private persistObjectCatalogEntryIfChanged;
+    /**
+     * Read-compare-write the catalog DDL for a table that just fired `table_modified`.
+     *
+     * - **Absent** catalog entry → the table is not store-backed in this catalog (a
+     *   memory table in the same `db`, or a store table never persisted) → skip. This
+     *   self-filters foreign-module tables without relying on `vtabModule` identity
+     *   (which points at the isolation wrapper when wrapped).
+     * - **Present** but identical DDL → skip (no redundant write). This is what makes a
+     *   structural ALTER — whose own `alterTable` already wrote the final DDL, then fires
+     *   `table_modified` with that same final schema — a no-op here (no double-write).
+     * - **Present** and different DDL → re-persist (the tag swap; or a beneficial
+     *   propagated rewrite of a dependent store table).
+     */
+    protected persistCatalogIfChanged(key: Uint8Array, newObject: TableSchema): Promise<void>;
+    /**
+     * Load all DDL **values** from the catalog store (keys discarded).
+     * Used to restore persisted tables on startup and by tests asserting persisted DDL.
+     * Note: this returns table, view, AND materialized-view entries intermixed —
+     * `StoreModuleSchemaSync.rehydrateCatalog` uses {@link loadCatalogEntries} (keys retained) to
+     * classify them. Meta entries (e.g. the clean-shutdown marker) are not DDL
+     * and are filtered out.
+     */
+    loadAllDDL(): Promise<string[]>;
+    /**
+     * Load every catalog entry as `{ key, ddl }`. Unlike {@link loadAllDDL} (values
+     * only) this retains the key so `StoreModuleSchemaSync.rehydrateCatalog` can classify each entry
+     * (table / view / materialized view) by its reserved key prefix.
+     */
+    protected loadCatalogEntries(): Promise<Array<{
+        key: Uint8Array;
+        ddl: string;
+    }>>;
+    /**
+     * Consume the clean-shutdown marker, deleting it in the same breath (single-use).
+     *
+     * Returns `{ trusted, staleAtClose }`:
+     * - `trusted` — the marker was present AND its payload parsed as a string array.
+     *   Absence (a fresh store, a crash, or a prior rehydrate without an intervening
+     *   `StoreModule.closeAll`) yields `false`, so every adopt this session falls back to
+     *   refill.
+     * - `staleAtClose` — the qualified lowercased `schema.mv` names that were
+     *   stale-at-close (written by `StoreModule.closeAll`); those MVs refill even under trust.
+     *
+     * Conservative parse: any unparseable / wrong-shape payload (including a legacy
+     * bare `'1'`, which parses to a number, not an array) degrades to
+     * `{ trusted: false, staleAtClose: ∅ }` — refill everything — rather than
+     * trust-everything. The marker is deleted regardless of parse outcome.
+     */
+    protected consumeCleanShutdownMarker(): Promise<{
+        trusted: boolean;
+        staleAtClose: ReadonlySet<string>;
+    }>;
+    /**
+     * Write the durable stale-MV set (`\x00meta\x00stale_mvs`) with `sync: true`. Unlike
+     * the clean-shutdown marker this entry is persistent current-truth — overwritten as
+     * staleness changes, never deleted — so a crash leaves the last synced value intact.
+     * The `sync` mirrors the marker-consume delete's durability discipline (and carries
+     * the same documented backend caveat: a backend without a durability knob no-ops it).
+     */
+    protected writeDurableStaleMvSet(json: string): Promise<void>;
+    /**
+     * Read + conservative-parse the durable stale-MV set, mirroring
+     * {@link consumeCleanShutdownMarker}'s parse discipline (but READ-only — never
+     * deleted). Returns:
+     * - `{ present: false }` — no entry on disk (a pre-atomic store, or an upgrade where
+     *   the capability was gained but no stale-set has been written yet) → the caller
+     *   falls back to the clean-shutdown marker path.
+     * - `{ present: true, stale }` — the parsed set of qualified `schema.mv` names.
+     * - `{ present: true, stale: null }` — a present but unparseable / wrong-shape payload
+     *   → the caller refills everything (the always-safe posture).
+     */
+    protected readDurableStaleMvSet(): Promise<{
+        present: false;
+    } | {
+        present: true;
+        stale: ReadonlySet<string> | null;
+    }>;
+}
+//# sourceMappingURL=store-module-catalog.d.ts.map

package/dist/src/common/store-module-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-module-catalog.d.ts","sourceRoot":"","sources":["../../../src/common/store-module-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,qBAAqB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAsBpH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AA8CzD,8BAAsB,kBAAmB,SAAQ,eAAe;IAC/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;;;;OAMG;IACG,YAAY,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,iCAAiC,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhF;;OAEG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1E;;;;OAIG;IACG,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlD,0DAA0D;IACpD,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxE;;;;;OAKG;IACG,uBAAuB,CAAC,EAAE,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvE,8EAA8E;IACxE,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IAMH,8BAA8B,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI;IAM7G;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAc/B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,CAAC,qBAAqB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAO5D;;;;;;;;;;;;OAYG;YACW,kCAAkC;IAOhD;;;;;;;;;;;;OAYG;cACa,uBAAuB,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB/F;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAerC;;;;OAIG;cACa,kBAAkB,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,EAAE,UAAU,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAUtF;;;;;;;;;;;;;;;OAeG;cACa,0BAA0B,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;IA8B9G;;;;;;OAMG;cACa,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASnE;;;;;;;;;;OAUG;cACa,qBAAqB,IAAI,OAAO,CAC/C;QAAE,OAAO,EAAE,KAAK,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAAA;KAAE,CACzE;CAoBD"}