@byline/db-mysql 4.16.0 → 4.17.0

package/dist/database/schema/index.d.ts

@@ -274,6 +274,47 @@ export declare const documents: import("drizzle-orm/mysql-core").MySqlTableWithC
     };
     dialect: 'mysql';
 }>;
+export declare const singletonDocuments: import("drizzle-orm/mysql-core").MySqlTableWithColumns<{
+    name: "byline_singleton_documents";
+    schema: undefined;
+    columns: {
+        collection_id: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "collection_id";
+            tableName: "byline_singleton_documents";
+            dataType: "custom";
+            columnType: "MySqlCustomColumn";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        document_id: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: "document_id";
+            tableName: "byline_singleton_documents";
+            dataType: "custom";
+            columnType: "MySqlCustomColumn";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'mysql';
+}>;
 export declare const documentVersions: import("drizzle-orm/mysql-core").MySqlTableWithColumns<{
     name: "byline_document_versions";
     schema: undefined;

package/dist/database/schema/index.js

@@ -74,6 +74,20 @@ export const documents = mysqlTable('byline_documents', {
     }).onDelete('cascade'),
     index('idx_documents_collection').on(table.collection_id),
     index('idx_documents_collection_order').on(table.collection_id, table.order_key),
+    unique('uq_documents_collection_id_id').on(table.collection_id, table.id),
+]);
+// Singleton slot → document mapping. The composite foreign key proves that
+// the mapped document belongs to the registered collection while the primary
+// key enforces zero-or-one materialised document per singleton slot.
+export const singletonDocuments = mysqlTable('byline_singleton_documents', {
+    collection_id: uuidChar('collection_id').primaryKey(),
+    document_id: uuidChar('document_id').notNull().unique(),
+}, (table) => [
+    foreignKey({
+        name: 'fk_singleton_documents_document',
+        columns: [table.collection_id, table.document_id],
+        foreignColumns: [documents.collection_id, documents.id],
+    }).onDelete('cascade'),
 ]);
 // Document versions table
 export const documentVersions = mysqlTable('byline_document_versions', {

package/dist/database/schema/schema-pins.test.node.js

@@ -463,3 +463,25 @@ describe('schema pins — scheduled publication', () => {
         expect(expiry?.config.columns.map((column) => ('name' in column ? column.name : null))).toEqual(['execution_expires_at']);
     });
 });
+describe('schema pins — singleton documents', () => {
+    it('pins the supporting document ownership key', () => {
+        const cfg = getTableConfig(coreSchema.documents);
+        const ownershipKey = cfg.uniqueConstraints.find((constraint) => constraint.name === 'uq_documents_collection_id_id');
+        expect(ownershipKey?.columns.map((column) => column.name)).toEqual(['collection_id', 'id']);
+    });
+    it('pins slot and document uniqueness plus collection ownership', () => {
+        const cfg = getTableConfig(coreSchema.singletonDocuments);
+        const collectionId = cfg.columns.find((column) => column.name === 'collection_id');
+        const documentId = cfg.columns.find((column) => column.name === 'document_id');
+        const ownershipForeignKey = cfg.foreignKeys.find((foreignKey) => foreignKey.getName() === 'fk_singleton_documents_document');
+        const reference = ownershipForeignKey?.reference();
+        expect(collectionId?.primary).toBe(true);
+        expect(documentId?.isUnique).toBe(true);
+        expect(reference?.columns.map((column) => column.name)).toEqual([
+            'collection_id',
+            'document_id',
+        ]);
+        expect(reference?.foreignColumns.map((column) => column.name)).toEqual(['collection_id', 'id']);
+        expect(ownershipForeignKey?.onDelete).toBe('cascade');
+    });
+});

package/dist/index.js

@@ -15,6 +15,7 @@ import { createAuditQueries } from './modules/audit/audit-queries.js';
 import { createCounterCommands } from './modules/counters/counters-commands.js';
 import { createSchedulerStore } from './modules/scheduler/scheduler-store.js';
 import { classifyError } from './modules/storage/classify-error.js';
+import { SingletonCommands, SingletonQueries } from './modules/storage/singletons.js';
 import { createCommandBuilders } from './modules/storage/storage-commands.js';
 import { createQueryBuilders } from './modules/storage/storage-queries.js';
 export const mysqlAdapter = ({ connectionString, collections, defaultContentLocale, connectionLimit = 20, idleTimeout = 2000, connectTimeout = 30000, maxIdle, }) => {
@@ -87,6 +88,8 @@ export const mysqlAdapter = ({ connectionString, collections, defaultContentLoca
     const auditCommands = createAuditCommands(dbManager);
     const auditQueries = createAuditQueries(db);
     const schedulerStore = createSchedulerStore(db);
+    const singletonCommands = new SingletonCommands(dbManager);
+    const singletonQueries = new SingletonQueries(dbManager);
     // Boot check: run lazily on the pool's first physical connection rather
     // than eagerly here, because `mysqlAdapter` is synchronous (mirroring
     // `pgAdapter`) and cannot await a round trip before returning. mysql2
@@ -133,6 +136,7 @@ export const mysqlAdapter = ({ connectionString, collections, defaultContentLoca
             // `auditCommands` fully implements `IAuditCommands` as of Task 11 —
             // see `./modules/audit/audit-commands.js`.
             audit: auditCommands,
+            singletons: singletonCommands,
         },
         queries: {
             // `queryBuilders.collections` fully implements `ICollectionQueries`
@@ -144,6 +148,7 @@ export const mysqlAdapter = ({ connectionString, collections, defaultContentLoca
             // `auditQueries` fully implements `IAuditQueries` as of Task 11 — see
             // `./modules/audit/audit-queries.js`.
             audit: auditQueries,
+            singletons: singletonQueries,
         },
         withTransaction: (fn) => txManager.withTransaction(fn),
         scheduler: schedulerStore,

package/dist/lib/db-manager.d.ts

@@ -25,6 +25,8 @@ export interface DBManager {
      * boundary is open in this async context, otherwise the pool.
      */
     get(): DBExecutor;
+    /** Whether the current async context owns an ambient transaction. */
+    isInTransaction(): boolean;
 }
 export declare class DBManagerImpl implements DBManager {
     private readonly dbPool;
@@ -32,6 +34,7 @@ export declare class DBManagerImpl implements DBManager {
         dbPool: DBExecutor;
     });
     get(): DBExecutor;
+    isInTransaction(): boolean;
 }
 export interface TXManager {
     /**

package/dist/lib/db-manager.js

@@ -26,6 +26,9 @@ export class DBManagerImpl {
     get() {
         return transactionALS.getStore() ?? this.dbPool;
     }
+    isInTransaction() {
+        return transactionALS.getStore() != null;
+    }
 }
 export class TXManagerImpl {
     db;

package/dist/modules/storage/classify-error.d.ts

@@ -8,8 +8,8 @@
 import { type DbErrorClassification } from '@byline/core';
 /**
  * Classify a MySQL driver error. Walks a short `cause` chain (Drizzle's
- * `DrizzleQueryError` → the underlying mysql2 error) looking for a
- * duplicate-key error and returns the carried index name. Mirrors
+ * `DrizzleQueryError` → the underlying mysql2 error) looking for duplicate-key
+ * and foreign-key errors and returns the carried constraint or index name. Mirrors
  * `packages/db-postgres/src/modules/storage/classify-error.ts`, whose
  * pg-anatomy docblock this docblock intentionally parallels.
  *

package/dist/modules/storage/classify-error.js

@@ -8,8 +8,8 @@
 import { DbErrorCodes } from '@byline/core';
 /**
  * Classify a MySQL driver error. Walks a short `cause` chain (Drizzle's
- * `DrizzleQueryError` → the underlying mysql2 error) looking for a
- * duplicate-key error and returns the carried index name. Mirrors
+ * `DrizzleQueryError` → the underlying mysql2 error) looking for duplicate-key
+ * and foreign-key errors and returns the carried constraint or index name. Mirrors
  * `packages/db-postgres/src/modules/storage/classify-error.ts`, whose
  * pg-anatomy docblock this docblock intentionally parallels.
  *
@@ -44,6 +44,12 @@ export function classifyError(err) {
                 : qualifiedName;
             return { code: DbErrorCodes.UNIQUE_VIOLATION, constraint };
         }
+        // InnoDB's table-level FK failures use 1451/1452 and carry a constraint
+        // name. Legacy 1216/1217 variants omit the name, so they remain UNKNOWN.
+        if (e.errno === 1451 || e.errno === 1452) {
+            const match = typeof e.message === 'string' ? e.message.match(/CONSTRAINT [`']([^`']+)[`']/) : null;
+            return { code: DbErrorCodes.FOREIGN_KEY_VIOLATION, constraint: match?.[1] };
+        }
         e = e.cause;
     }
     return { code: DbErrorCodes.UNKNOWN };

package/dist/modules/storage/classify-error.test.node.js

@@ -46,13 +46,21 @@ describe('classifyError (mysql)', () => {
         };
         expect(classifyError(err).code).toBe('DB_UNIQUE_VIOLATION');
     });
-    it('returns DB_UNKNOWN for a non-duplicate-key error', () => {
+    it('classifies a foreign-key error with the constraint name', () => {
         expect(classifyError({
             code: 'ER_NO_REFERENCED_ROW_2',
             errno: 1452,
             sqlState: '23000',
-            message: 'Cannot add or update a child row: a foreign key constraint fails',
-        })).toEqual({ code: 'DB_UNKNOWN' });
+            message: 'Cannot add or update a child row: a foreign key constraint fails (`db`.`table`, CONSTRAINT `fk_document_owner` FOREIGN KEY (`document_id`))',
+        })).toEqual({
+            code: 'DB_FOREIGN_KEY_VIOLATION',
+            constraint: 'fk_document_owner',
+        });
+    });
+    it('returns DB_UNKNOWN for an unrelated database error', () => {
+        expect(classifyError({ code: 'ER_DATA_TOO_LONG', errno: 1406 })).toEqual({
+            code: 'DB_UNKNOWN',
+        });
     });
     it('returns DB_UNKNOWN for a non-error value', () => {
         expect(classifyError(undefined)).toEqual({ code: 'DB_UNKNOWN' });
@@ -79,11 +87,15 @@ runClassifyErrorContract([
                 message: "Duplicate entry 'some-uuid' for key 'byline_document_paths.idx_document_paths_collection_locale_path'",
             },
         },
-        unrelatedError: {
-            code: 'ER_NO_REFERENCED_ROW_2',
-            errno: 1452,
-            sqlState: '23000',
-            message: 'Cannot add or update a child row: a foreign key constraint fails',
+        foreignKeyViolationError: {
+            name: 'DrizzleQueryError',
+            cause: {
+                code: 'ER_NO_REFERENCED_ROW_2',
+                errno: 1452,
+                sqlState: '23000',
+                message: 'Cannot add or update a child row: a foreign key constraint fails (`db`.`table`, CONSTRAINT `fk_document_owner` FOREIGN KEY (`document_id`))',
+            },
         },
+        unrelatedError: { code: 'ER_DATA_TOO_LONG', errno: 1406, sqlState: '22001' },
     },
 ]);

package/dist/modules/storage/singletons.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 ISingletonCommands, type ISingletonQueries } from '@byline/core';
+import type { DBManager } from '../../lib/db-manager.js';
+export declare class SingletonCommands implements ISingletonCommands {
+    private dbManager;
+    constructor(dbManager: DBManager);
+    /**
+     * Resolve the executor per access so an enclosing `withTransaction`
+     * boundary is honoured through the adapter's ambient transaction manager.
+     */
+    private get db();
+    lockSlot(collectionId: string): Promise<void>;
+    setMapping(collectionId: string, documentId: string): Promise<void>;
+    clearMapping(collectionId: string): Promise<void>;
+}
+export declare class SingletonQueries implements ISingletonQueries {
+    private dbManager;
+    constructor(dbManager: DBManager);
+    private get db();
+    getMappedDocumentId(collectionId: string): Promise<string | null>;
+}

package/dist/modules/storage/singletons.js

@@ -0,0 +1,70 @@
+/**
+ * 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 { ERR_DATABASE, ERR_NOT_FOUND, } from '@byline/core';
+import { eq, sql } from 'drizzle-orm';
+import { singletonDocuments } from '../../database/schema/index.js';
+export class SingletonCommands {
+    dbManager;
+    constructor(dbManager) {
+        this.dbManager = dbManager;
+    }
+    /**
+     * Resolve the executor per access so an enclosing `withTransaction`
+     * boundary is honoured through the adapter's ambient transaction manager.
+     */
+    get db() {
+        return this.dbManager.get();
+    }
+    async lockSlot(collectionId) {
+        if (!this.dbManager.isInTransaction()) {
+            throw ERR_DATABASE({
+                message: 'singleton slot locks require an active transaction',
+                details: { collectionId },
+            });
+        }
+        const locked = await this.db.execute(sql `
+      SELECT id FROM byline_collections
+      WHERE id = ${collectionId}
+      FOR UPDATE
+    `);
+        const rows = locked[0];
+        if (rows.length === 0) {
+            throw ERR_NOT_FOUND({
+                message: 'singleton slot registration not found',
+                details: { collectionId },
+            });
+        }
+    }
+    async setMapping(collectionId, documentId) {
+        await this.db
+            .insert(singletonDocuments)
+            .values({ collection_id: collectionId, document_id: documentId });
+    }
+    async clearMapping(collectionId) {
+        await this.db
+            .delete(singletonDocuments)
+            .where(eq(singletonDocuments.collection_id, collectionId));
+    }
+}
+export class SingletonQueries {
+    dbManager;
+    constructor(dbManager) {
+        this.dbManager = dbManager;
+    }
+    get db() {
+        return this.dbManager.get();
+    }
+    async getMappedDocumentId(collectionId) {
+        const rows = await this.db
+            .select({ documentId: singletonDocuments.document_id })
+            .from(singletonDocuments)
+            .where(eq(singletonDocuments.collection_id, collectionId))
+            .limit(1);
+        return rows[0]?.documentId ?? null;
+    }
+}

package/dist/modules/storage/storage-commands.js

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { DbErrorCodes, ERR_CONFLICT, ERR_NOT_FOUND, ERR_VALIDATION, flattenFieldSetData, generateKeyBetween, TREE_PLACEMENT_STALE_MARKER, } from '@byline/core';
+import { DbErrorCodes, ERR_CONFLICT, ERR_NOT_FOUND, ERR_VALIDATION, flattenFieldSetData, generateKeyBetween, isSingleton, TREE_PLACEMENT_STALE_MARKER, } from '@byline/core';
 import { and, desc, eq, inArray, ne, notInArray, sql } from 'drizzle-orm';
 import { v7 as uuidv7 } from 'uuid';
 import { booleanStore, collections, currentDocumentsView, datetimeStore, documentAvailableLocales, documentPaths, documentRelationships, documents, documentVersions, fileStore, jsonStore, metaStore, numericStore, relationStore, textStore, } from '../../database/schema/index.js';
@@ -49,8 +49,8 @@ export class CollectionCommands {
     async create(path, config, opts) {
         const id = uuidv7();
         const version = opts?.version ?? 1;
-        const singular = config.labels.singular || path;
-        const plural = config.labels.plural || `${path}s`;
+        const singular = isSingleton(config) ? config.label : config.labels.singular || path;
+        const plural = isSingleton(config) ? config.label : config.labels.plural || `${path}s`;
         // `created_at`/`updated_at` are written explicitly rather than left to
         // the column's `DEFAULT CURRENT_TIMESTAMP(6)` — an earlier version of
         // this method approximated them with a request-time `Date` instead

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

@@ -356,8 +356,9 @@ export declare class DocumentQueries implements IDocumentQueries {
     /**
      * getDocumentByVersion — fetches a specific version and reconstructs its fields.
      */
-    getDocumentByVersion({ document_version_id, locale, collection_id, filters, }: {
+    getDocumentByVersion({ document_version_id, document_id, locale, collection_id, filters, }: {
         document_version_id: string;
+        document_id?: string;
         locale?: string;
         collection_id?: string;
         filters?: DocumentFilter[];

package/dist/modules/storage/storage-queries.js

@@ -652,10 +652,12 @@ export class DocumentQueries {
     /**
      * getDocumentByVersion — fetches a specific version and reconstructs its fields.
      */
-    async getDocumentByVersion({ document_version_id, locale = 'all', collection_id, filters, }) {
+    async getDocumentByVersion({ document_version_id, document_id, locale = 'all', collection_id, filters, }) {
         const projectionLocale = locale === 'all' ? undefined : locale;
         const filterLocale = projectionLocale ?? this.defaultContentLocale;
         const conditions = [eq(documentVersions.id, document_version_id)];
+        if (document_id)
+            conditions.push(eq(documentVersions.document_id, document_id));
         if (collection_id)
             conditions.push(eq(documentVersions.collection_id, collection_id));
         if (filters?.length) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-mysql",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.16.0",
+  "version": "4.17.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -48,26 +48,25 @@
   ],
   "dependencies": {
     "drizzle-orm": "^0.45.2",
-    "mysql2": "^3.23.4",
+    "mysql2": "^3.24.2",
     "uuid": "^14.0.2",
-    "@byline/admin": "4.16.0",
-    "@byline/core": "4.16.0"
+    "@byline/admin": "4.17.0",
+    "@byline/core": "4.17.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.9",
-    "@types/node": "^26.2.0",
+    "@biomejs/biome": "2.5.10",
+    "@types/node": "^26.4.0",
     "chokidar": "^5.0.0",
     "chokidar-cli": "^3.0.0",
     "dotenv": "^17.4.2",
     "drizzle-kit": "^0.31.10",
     "npm-run-all": "^4.1.5",
     "tsc-alias": "^1.9.2",
-    "tsx": "^4.23.12",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
-    "@byline/client": "4.16.0",
+    "@byline/auth": "4.17.0",
     "@byline/db-conformance": "0.0.10",
-    "@byline/auth": "4.16.0"
+    "@byline/client": "4.17.0"
   },
   "publishConfig": {
     "access": "public",