@byline/db-mysql 4.8.0

package/dist/modules/storage/storage-commands.d.ts

@@ -0,0 +1,443 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { CollectionDefinition, ICollectionCommands, IDocumentCommands, TreeDeleteMutationResult, TreeMutationResult } from '@byline/core';
+import type { DBManager } from '../../lib/db-manager.js';
+/**
+ * CollectionCommands
+ *
+ * Mirrors `packages/db-postgres/src/modules/storage/storage-commands.ts`'s
+ * `CollectionCommands`. MySQL has no `RETURNING` clause, so every write
+ * constructs its return value in JS instead — collection ids are
+ * app-generated UUIDv7, so `create` already knows every value it needs
+ * without a round trip. `update` re-`SELECT`s because `patch` is partial
+ * and the caller expects the merged row back.
+ */
+export declare class CollectionCommands implements ICollectionCommands {
+    private dbManager;
+    constructor(dbManager: DBManager);
+    /**
+     * The executor for this call — the ambient transaction when a
+     * `withTransaction` boundary is open, otherwise the pool. Resolved per
+     * access so every `this.db.*` below transparently joins an enclosing
+     * transaction with no call-site change. See docs/03-architecture/03-transactions.md.
+     */
+    private get db();
+    create(path: string, config: CollectionDefinition, opts?: {
+        version?: number;
+        schemaHash?: string;
+    }): Promise<{
+        id: string;
+        path: string;
+        singular: string;
+        plural: string;
+        config: CollectionDefinition;
+        version: number;
+        schema_hash: string | null;
+        created_at: Date;
+        updated_at: Date;
+    }[]>;
+    update(id: string, patch: {
+        config?: CollectionDefinition;
+        version?: number;
+        schemaHash?: string;
+    }): Promise<{
+        created_at: Date;
+        updated_at: Date;
+        id: string;
+        path: string;
+        singular: string;
+        plural: string;
+        config: unknown;
+        version: number;
+        schema_hash: string | null;
+    }[]>;
+    delete(id: string): Promise<import("drizzle-orm/mysql2").MySqlRawQueryResult>;
+}
+/**
+ * DocumentCommands
+ *
+ * Ported from `packages/db-postgres/src/modules/storage/storage-commands.ts`'s
+ * `DocumentCommands`. Task 9A landed `createDocumentVersion` and its private
+ * helpers; Task 9B (this task) ports the rest of the write surface —
+ * `updateDocumentPath`, `setDocumentAvailableLocales`, `setDocumentStatus`,
+ * `archivePublishedVersions`, `softDeleteDocument`, `deleteDocumentLocale`,
+ * `setOrderKey`, `placeTreeNode`, `removeFromTree`, and
+ * `promoteChildrenAndRemoveFromTree` — completing `IDocumentCommands`. The
+ * pg source's `reAnchorDocument` / `reAnchorDocuments` / `backfillVersionLocales`
+ * are deliberately NOT ported here: `@byline/db-conformance`'s own suites
+ * (`document-paths.ts`, `locale-fallback.ts`) document them as "Postgres-only
+ * maintenance operations documented as off the core `IDbAdapter` contract" —
+ * not something a conforming adapter is required to implement, and neither is
+ * a member of `IDocumentCommands`.
+ */
+export declare class DocumentCommands implements IDocumentCommands {
+    private dbManager;
+    private defaultContentLocale;
+    constructor(dbManager: DBManager, defaultContentLocale: string);
+    /**
+     * The executor for this call — the ambient transaction when a
+     * `withTransaction` boundary is open, otherwise the pool. Resolved per
+     * access so every `this.db.*` below transparently joins an enclosing
+     * transaction with no call-site change. See docs/03-architecture/03-transactions.md.
+     */
+    private get db();
+    /**
+     * createDocumentVersion
+     *
+     * Creates a new document or a new version of an existing document. Ported
+     * from `packages/db-postgres/src/modules/storage/storage-commands.ts`'s
+     * `DocumentCommands.createDocumentVersion` — see spec §2's normative
+     * conversion table, applied at each site below:
+     *
+     *   - `.returning()` → construct-in-JS. Every id here is app-generated
+     *     UUIDv7 (minted before the insert), so the value is already known —
+     *     no re-`SELECT` is needed anywhere in this method.
+     *   - `onConflictDoUpdate` (path upsert) → NOT `.onDuplicateKeyUpdate()`
+     *     (found live: MySQL's `ON DUPLICATE KEY UPDATE` has no per-constraint
+     *     targeting the way pg's `onConflictDoUpdate({ target })` does, so it
+     *     would silently absorb a genuine cross-document path conflict instead
+     *     of erroring). `writeDocumentPath` below does the targeting itself —
+     *     see its docblock.
+     *   - `ON CONFLICT (document_version_id, field_path, locale) DO NOTHING`
+     *     (7 sites, the per-locale carry-forward) → MySQL has no per-row
+     *     `gen_random_uuid()` to call from an `INSERT … SELECT`, and ids must
+     *     be app-generated UUIDv7 — never `INSERT IGNORE`, which would swallow
+     *     unrelated errors, and never a DB-generated id. So each site becomes
+     *     a typed `SELECT` of the previous version's carry-forward rows,
+     *     followed by a JS-side UUIDv7-per-row bulk `INSERT … ON DUPLICATE KEY
+     *     UPDATE id = id` (drizzle's own documented no-op idiom for "do
+     *     nothing" on MySQL) — see `copyForwardStoreRows` below, which the 7
+     *     call sites share.
+     *   - `::uuid` casts → dropped (MySQL ids are plain `CHAR(36)`).
+     *
+     * @param params - Options for creating the document
+     * @returns The created document and the number of field values inserted
+     */
+    createDocumentVersion(params: {
+        documentId?: string;
+        collectionId: string;
+        collectionVersion: number;
+        collectionConfig: CollectionDefinition;
+        action: string;
+        documentData: any;
+        path?: string;
+        availableLocales?: string[];
+        locale?: string;
+        status?: string;
+        createdBy?: string;
+        previousVersionId?: string;
+        orderKey?: string;
+    }): Promise<{
+        document: {
+            id: string;
+            document_id: string;
+            collection_id: string;
+            collection_version: number;
+            doc: null;
+            event_type: string;
+            status: string;
+            is_deleted: boolean;
+            created_by: string | null;
+            change_summary: null;
+            created_at: Date;
+            updated_at: Date;
+        };
+        fieldCount: number;
+    }>;
+    /**
+     * writeDocumentPath
+     *
+     * Upsert the `byline_document_paths` row for a (document, locale) pair. The
+     * path row is document-grain and sticky across versions — it lives under the
+     * document's `source_locale` (its data anchor), not the mutable global
+     * default.
+     *
+     * Real dialect divergence from pg, found live (a test that should have
+     * raised a conflict silently "succeeded" instead): pg's `onConflictDoUpdate`
+     * takes an explicit `target` — the (`document_id`, `locale`) unique index —
+     * so a collision on the *other* unique index
+     * (`idx_document_paths_collection_locale_path`, a genuine path conflict
+     * from a different document) is deliberately left untargeted and bubbles up
+     * as `23505`. MySQL's `ON DUPLICATE KEY UPDATE` has no per-constraint
+     * targeting — it fires for a collision on *any* unique/primary key on the
+     * table, so a naive `.onDuplicateKeyUpdate()` would silently rewrite
+     * whichever existing row the *other* document's path collided with instead
+     * of raising `ER_DUP_ENTRY`. So this does the targeting itself: try the
+     * `INSERT` first; if it fails on the *own-document* unique index
+     * (`unique_document_paths_document_locale`, the ordinary "this document is
+     * resaving its already-anchored path" case — detected via `classifyError`,
+     * the same cause-chain-walking classifier the lifecycle layer uses, since
+     * mysql2/Drizzle wraps the duplicate-key error rather than throwing it
+     * bare), fall through to an explicit `UPDATE` instead. Any other
+     * duplicate-key error — in particular the collection-scoped
+     * path-uniqueness index — is rethrown unchanged, so it still surfaces as
+     * `ER_DUP_ENTRY` for the lifecycle layer's own `classifyError`-based
+     * `ERR_PATH_CONFLICT` mapping.
+     */
+    private writeDocumentPath;
+    /**
+     * writeDocumentAvailableLocales
+     *
+     * Replace a document's `byline_document_available_locales` rows wholesale —
+     * the editorial advertised-locale set. Document-grain and sticky across
+     * versions: `delete`-then-`insert`, deduplicated so a caller-supplied
+     * duplicate doesn't collide on the `(document_id, locale)` primary key. An
+     * empty array clears the set (advertise nothing).
+     */
+    private writeDocumentAvailableLocales;
+    /**
+     * writeVersionLocaleLedger
+     *
+     * Compute and insert a version's `byline_document_version_locales` rows: a
+     * locale is recorded when it covers every localized field path the version's
+     * `sourceLocale` has (path-coverage), and a version with no localized content
+     * records a single `'all'` sentinel. Reads the version's persisted store rows,
+     * so callers must have written them first. `::uuid` casts are dropped
+     * (MySQL ids are plain `CHAR(36)`); the WITH/UNION/HAVING NOT EXISTS logic is
+     * otherwise unchanged MySQL 8+ syntax — but the WITH clause's *position* is a
+     * real dialect difference, found live (a syntax error, not assumed): Postgres
+     * accepts `WITH … INSERT INTO … SELECT …`, whereas MySQL requires the WITH
+     * clause *after* `INSERT INTO <table>` and immediately before the `SELECT`
+     * it modifies (confirmed against a live MySQL 9.7.1 server) — so the two
+     * clauses are transposed relative to the pg original. See
+     * docs/07-internationalization/index.md.
+     */
+    private writeVersionLocaleLedger;
+    /**
+     * copyForwardStoreRows
+     *
+     * Carry forward one store table's rows for every locale except `'all'` and
+     * the version's active write locale, from `prevVersionId` to `newVersionId`.
+     * The MySQL counterpart of pg's `INSERT … SELECT gen_random_uuid(), … ON
+     * CONFLICT (document_version_id, field_path, locale) DO NOTHING`: MySQL has
+     * no per-row id generator usable from an `INSERT … SELECT`, and ids must be
+     * app-generated UUIDv7 (never DB-generated, never `INSERT IGNORE` — see the
+     * method doc on `createDocumentVersion`) — so this reads the candidate rows
+     * with a typed `SELECT`, mints a fresh UUIDv7 per row in JS, and bulk-inserts
+     * with `.onDuplicateKeyUpdate({ set: { id: sql\`id\` } })`, drizzle's own
+     * documented no-op idiom for "do nothing on conflict" on MySQL. One generic
+     * helper shared by all 7 call sites (pg keeps 7 near-identical raw-SQL
+     * blocks because it doesn't need this per-row JS step; MySQL does, so
+     * factoring it once here avoids seven copies of the same shape).
+     *
+     * `table` is threaded through as `AnyMySqlTable` and cast internally —
+     * the 7 store tables share the same `(id, document_version_id, …, locale,
+     * created_at, updated_at)` column shape (`baseStoreColumns` in the schema),
+     * but Drizzle's query builder generics don't unify cleanly across a union
+     * of distinct table types for `.from()` / `.insert()`, so the cast is
+     * confined to this one private helper rather than leaking into the 7 call
+     * sites, which stay fully typed.
+     */
+    private copyForwardStoreRows;
+    /**
+     * updateDocumentPath
+     *
+     * Standalone, non-versioned write of a document's URL path. Backs the admin
+     * path widget's direct-write Save path: it edits `byline_document_paths`
+     * in-place (document-grain, sticky) **without** minting a new document
+     * version or touching workflow status. The path's document-grain nature means
+     * the change is immediate and applies across every version of the document.
+     *
+     * Second caller into `writeDocumentPath` (the first is `createDocumentVersion`
+     * step 2a) — see that method's docblock for the insert-then-catch-and-
+     * conditionally-update targeting it does in place of pg's
+     * `onConflictDoUpdate({ target })`.
+     *
+     * Source-locale enforcement and `ERR_PATH_CONFLICT` mapping live in the
+     * lifecycle service that calls this; the command itself only performs the
+     * upsert (and surfaces the raw `ER_DUP_ENTRY` for the service to translate
+     * via `classifyError`).
+     */
+    updateDocumentPath(params: {
+        documentId: string;
+        collectionId: string;
+        locale: string;
+        path: string;
+    }): Promise<void>;
+    /**
+     * setDocumentAvailableLocales
+     *
+     * Standalone, non-versioned write of a document's editorial advertised-locale
+     * set. Backs the admin available-locales widget's direct-write Save path: it
+     * replaces `byline_document_available_locales` wholesale (document-grain)
+     * **without** minting a new document version or touching workflow status. The
+     * change is immediate and applies across every version of the document; the
+     * public advertised set remains the intersection with the resolved version's
+     * completeness ledger. See docs/07-internationalization/index.md.
+     */
+    setDocumentAvailableLocales(params: {
+        documentId: string;
+        collectionId: string;
+        availableLocales: string[];
+    }): Promise<void>;
+    /**
+     * copyAllVersionStoreRows
+     *
+     * Copy every store row — all seven value-store tables (optionally excluding
+     * one locale) plus the locale-agnostic `byline_store_meta` identity rows
+     * (always copied wholesale, unfiltered — a block's identity is shared
+     * across locales) — from one document version to another, verbatim. New
+     * `id`s are minted per row (MySQL has no per-row `gen_random_uuid()`
+     * usable from an `INSERT … SELECT`, and ids must be app-generated UUIDv7 —
+     * see `copyForwardStoreRows` above); `created_at`/`updated_at` are left off
+     * the inserted row so the column default (`CURRENT_TIMESTAMP(6)`) supplies
+     * a fresh timestamp, matching pg's explicit `NOW(), NOW()`.
+     *
+     * The target version is assumed fresh (no existing rows), so — unlike
+     * `copyForwardStoreRows`, which may collide with rows `createDocumentVersion`
+     * already wrote in the same transaction — this performs a plain `INSERT`
+     * with no conflict handling. A collision here would mean the caller reused
+     * a non-fresh version id, which should fail loudly rather than being
+     * silently absorbed. Used by `deleteDocumentLocale` to snapshot the current
+     * version into the new one with the target locale's rows dropped.
+     */
+    private copyAllVersionStoreRows;
+    /** One value-store table's share of `copyAllVersionStoreRows`. */
+    private copyVersionStoreRows;
+    /**
+     * deleteDocumentLocale
+     *
+     * Remove one content locale's data from a document by writing a **new
+     * immutable version** that carries forward every store row except the
+     * target locale's (the `'all'` rows and all other locales are kept). The
+     * prior version still holds the deleted locale, so the operation is
+     * recoverable via version restore, and a previously-published version keeps
+     * serving until the new version is published.
+     *
+     * The new version's status is supplied by the caller (the lifecycle service
+     * passes the workflow's default — a fresh draft, matching `copyToLocale`).
+     * The derived availability ledger is recomputed from the carried-forward
+     * rows, so the deleted locale drops out automatically. The default content
+     * locale (the document's anchor) must never be passed here — the lifecycle
+     * service enforces that.
+     *
+     * Defensively returns `null` when the document has no current version (the
+     * service validates existence first, so this is a guard).
+     */
+    deleteDocumentLocale(params: {
+        documentId: string;
+        locale: string;
+        status?: string;
+        createdBy?: string;
+    }): Promise<{
+        newVersionId: string;
+        previousVersionId: string;
+    } | null>;
+    /**
+     * setDocumentStatus
+     *
+     * Mutate the status field on an existing document version row.
+     * This is the one case where we UPDATE a version in-place — status is
+     * lifecycle metadata, not content.
+     */
+    setDocumentStatus(params: {
+        document_version_id: string;
+        status: string;
+    }): Promise<void>;
+    /**
+     * archivePublishedVersions
+     *
+     * Set ALL versions of a document that currently have `currentStatus`
+     * (defaults to 'published') to 'archived'. Optionally exclude a specific
+     * version so the caller can protect the version it is about to publish.
+     *
+     * Returns the number of rows updated. MySQL has no `RETURNING` and drizzle's
+     * mysql2 `update()` resolves to a `[ResultSetHeader, FieldPacket[]]` tuple
+     * rather than pg's driver result object — `affectedRows` lives on the first
+     * element (confirmed live against the test database), not `.rowCount`. See
+     * `affectedRowCount()` in `storage-utils.ts`, shared by every guarded write
+     * in this adapter (this method, `softDeleteDocument` below, and the admin
+     * repositories) for that cast.
+     */
+    archivePublishedVersions(params: {
+        document_id: string;
+        currentStatus?: string;
+        excludeVersionId?: string;
+    }): Promise<number>;
+    /**
+     * softDeleteDocument
+     *
+     * Mark ALL versions of a document as deleted by setting `is_deleted = true`.
+     * The `current_documents` view filters these out, so the document disappears
+     * from listings without physically removing data.
+     *
+     * Returns the number of version rows marked as deleted.
+     */
+    softDeleteDocument(params: {
+        document_id: string;
+    }): Promise<number>;
+    /**
+     * Write `order_key` on a single `byline_documents` row. Single-column
+     * metadata update — no new version row, no `documentVersions` touch.
+     * `updated_at` on the document row is bumped so list caches invalidate.
+     */
+    setOrderKey(params: {
+        document_id: string;
+        order_key: string;
+    }): Promise<void>;
+    /**
+     * Serialize structural changes per collection and verify the collection
+     * exists. `FOR UPDATE` — no `FOR UPDATE OF` qualifier needed since this
+     * query selects from a single table (confirmed against a live MySQL 9.7.1
+     * server; MySQL 8.0.1+ supports `FOR UPDATE OF tbl_name` for the
+     * multi-table case used below in `lockDocumentCollection`).
+     */
+    private lockTreeCollection;
+    /**
+     * Resolve a document's collection while locking only the collection row.
+     * `FOR UPDATE OF c` — confirmed live against a MySQL 9.7.1 server (MySQL
+     * 8.0.1+ supports the per-table lock qualifier; `::uuid` casts dropped).
+     */
+    private lockDocumentCollection;
+    /** Read one ordered sibling group on the already collection-locked transaction. */
+    private treeGroup;
+    /** Read a node's placement from the already collection-locked transaction. */
+    private treePlacement;
+    /** Read a raw node-and-descendants set while the collection tree lock is held. */
+    private treeSubtreeIds;
+    /**
+     * placeTreeNode — see {@link IDocumentCommands.placeTreeNode}.
+     *
+     * Single transaction: same-collection guard → cycle guard → resolve the
+     * target sibling group's neighbour keys → mint a fractional key → upsert the
+     * edge row. Unversioned; touches only `byline_document_relationships`.
+     *
+     * The edge upsert uses a plain `.onDuplicateKeyUpdate()` — unlike
+     * `writeDocumentPath`, `byline_document_relationships` carries exactly one
+     * unique constraint (`uq_document_relationships_child`, on
+     * `child_document_id`), so MySQL's lack of per-constraint targeting is not
+     * an issue here: any duplicate-key collision on this table can only be that
+     * one index, so there is no ambiguity to guard against.
+     */
+    placeTreeNode(params: {
+        collectionId: string;
+        documentId: string;
+        parentDocumentId: string | null;
+        beforeDocumentId?: string | null;
+        afterDocumentId?: string | null;
+        ifUnplaced?: boolean;
+    }): Promise<TreeMutationResult>;
+    /**
+     * removeFromTree — see {@link IDocumentCommands.removeFromTree}.
+     * Single-row delete; no-op when the node is already unplaced.
+     */
+    removeFromTree(params: {
+        collectionId: string;
+        documentId: string;
+        includeSubtree?: boolean;
+    }): Promise<TreeMutationResult>;
+    /** Promote direct children to roots and remove the parent edge under one lock. */
+    promoteChildrenAndRemoveFromTree(params: {
+        collectionId: string;
+        documentId: string;
+    }): Promise<TreeDeleteMutationResult>;
+}
+export declare function createCommandBuilders(dbManager: DBManager, defaultContentLocale: string): {
+    collections: CollectionCommands;
+    documents: DocumentCommands;
+};