@objectstack/driver-sql 9.10.0 → 10.0.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { SchemaMode, QueryAST, DriverOptions } from '@objectstack/spec/data';
+import { AutonumberToken, SchemaMode, QueryAST, DriverOptions } from '@objectstack/spec/data';
 import { IDataDriver } from '@objectstack/spec/contracts';
 import knex, { Knex } from 'knex';
 
@@ -101,6 +101,20 @@ declare class SqlDriver implements IDataDriver {
     protected numericFields: Record<string, string[]>;
     protected dateFields: Record<string, Set<string>>;
     protected datetimeFields: Record<string, Set<string>>;
+    /**
+     * Federation read path (ADR-0015). For external objects whose physical
+     * remote table differs from the object name, these map between the two so
+     * {@link getBuilder} targets the remote table while the coercion maps above
+     * stay keyed by OBJECT name (matching formatInput/formatOutput). Empty for
+     * managed objects, so the managed query path is unchanged.
+     */
+    protected physicalTableByObject: Record<string, string>;
+    protected physicalSchemaByObject: Record<string, string>;
+    protected objectByPhysicalTable: Record<string, string>;
+    /** External columnMap (ADR-0015): logical field -> physical remote column (for WHERE/ORDER BY/writes). */
+    protected fieldColumnByObject: Record<string, Record<string, string>>;
+    /** External columnMap inverse: physical remote column -> logical field (for read output remap). */
+    protected columnFieldByObject: Record<string, Record<string, string>>;
     protected tablesWithTimestamps: Set<string>;
     /**
      * Autonumber field configs per table, captured during initObjects.
@@ -119,12 +133,19 @@ declare class SqlDriver implements IDataDriver {
     protected autoNumberFields: Record<string, Array<{
         name: string;
         format: string;
-        prefix: string;
-        padWidth: number;
+        tokens: AutonumberToken[];
         tenantField: string | null;
     }>>;
     /** Whether the sequences table has been ensured this process. */
     protected sequencesTableReady: boolean;
+    /**
+     * Whether `_objectstack_sequences` is the current `key_hash`-keyed shape.
+     * Set on a fresh create or a successful in-place migration. If a legacy table
+     * could NOT be migrated, this stays false: fixed-prefix sequences (empty
+     * scope) keep working via the legacy `(object, tenant_id, field)` key, while a
+     * per-scope write raises an actionable error rather than corrupting counters.
+     */
+    protected sequencesHasKeyHash: boolean;
     /** In-flight ensure promise; deduplicates concurrent first calls. */
     protected sequencesTableEnsurePromise: Promise<void> | null;
     /**
@@ -214,8 +235,34 @@ declare class SqlDriver implements IDataDriver {
     /**
      * Ensure the sequence-counter table exists. Idempotent and cheap after
      * the first call (cached via `sequencesTableReady`).
+     *
+     * The row key is `key_hash` — a SHA-256 of `(object, tenant_id, field, scope)`
+     * where `scope` is the rendered autonumber prefix (date/field tokens before
+     * the `{0000}` slot), so a new day/group/parent starts a fresh counter. A
+     * single 64-char hashed primary key (rather than the four raw columns, which
+     * blow past MySQL's 3072-byte index limit under utf8mb4 and bound how long a
+     * `{field}` scope may be) keys every dialect uniformly and lets `scope` be a
+     * generous non-indexed column. Fixed-prefix formats use the empty scope and
+     * keep their single global counter (backward compatible).
      */
     protected ensureSequencesTable(): Promise<void>;
+    /** SHA-256 of the composite counter key — the table's single-column PK. */
+    protected sequenceKeyHash(object: string, tenantId: string, field: string, scope: string): string;
+    /** Create the current `key_hash`-keyed sequences table shape. */
+    protected createSequencesTable(table: string): Promise<void>;
+    /**
+     * Migrate a pre-existing `_objectstack_sequences` table to the current
+     * `key_hash`-keyed shape. Handles both the original 3-column table (no
+     * `scope`) and an interim 4-column `(object, tenant_id, field, scope)` table:
+     * every legacy row is read, its `key_hash` computed in app code (no portable
+     * SQL hash exists), and re-inserted into a freshly built table that then
+     * replaces the original. Idempotent — a no-op once `key_hash` is present.
+     *
+     * If the rebuild fails, `sequencesHasKeyHash` stays false: fixed-prefix
+     * sequences keep working via the legacy key and per-scope writes error
+     * actionably (see getNextSequenceValue), rather than corrupting data.
+     */
+    protected ensureSequencesKeyHashShape(): Promise<void>;
     /**
      * Bootstrap helper: scan the data table for the highest numeric suffix
      * matching `prefix` (optionally scoped to a tenant). Used the first time
@@ -237,12 +284,14 @@ declare class SqlDriver implements IDataDriver {
      * Gaps are tolerated by design — a rolled-back insert "burns" a number,
      * matching standard sequence semantics.
      */
-    protected getNextSequenceValue(object: string, tableName: string, field: string, prefix: string, tenantField: string | null, tenantId: string | null, parentTrx?: Knex.Transaction): Promise<number>;
+    protected getNextSequenceValue(object: string, tableName: string, field: string, prefix: string, tenantField: string | null, tenantId: string | null, parentTrx?: Knex.Transaction, scope?: string): Promise<number>;
     /**
-     * For each `auto_number` field on the object that the caller did not
-     * provide a value for, reserve the next sequence value scoped to the
-     * record's tenant (or globally if the object has no tenant field) and
-     * render `prefix + zero-padded(value)`.
+     * For each `auto_number` field the caller left empty, render the format and
+     * reserve the next counter value. The counter is scoped to the rendered
+     * prefix (date tokens like `{YYYYMMDD}` in the request's business timezone,
+     * plus `{field}` interpolation from the row), so it resets per period/group;
+     * the full rendered prefix bootstraps the counter from existing data, and the
+     * tenant scopes it for isolation.
      */
     protected fillAutoNumberFields(object: string, row: Record<string, any>, options?: DriverOptions): Promise<void>;
     update(object: string, id: string | number, data: Record<string, any>, options?: DriverOptions): Promise<any>;
@@ -299,6 +348,30 @@ declare class SqlDriver implements IDataDriver {
     /**
      * Batch-initialise tables from an array of object definitions.
      */
+    /**
+     * DDL-free metadata registration for a federated (external) object — the
+     * read-path counterpart to {@link initObjects} (ADR-0015 federation).
+     *
+     * `initObjects` is gated by `assertSchemaMutable` and therefore throws for
+     * any non-`managed` driver, which left external objects with NO read-coercion
+     * metadata and the query path resolving to a table named after the object
+     * instead of its remote table. This populates the same coercion maps (keyed
+     * by OBJECT name, matching formatInput/formatOutput/coerceFilterValue) and
+     * records the physical remote table (`external.remoteName`, optionally
+     * `external.remoteSchema`) so {@link getBuilder} targets it — WITHOUT running
+     * any DDL (createTable/alterTable/columnInfo). Keep the field-classification
+     * below in sync with initObjects() if the field-type -> storage mapping changes.
+     */
+    registerExternalObject(schema: {
+        name: string;
+        fields?: Record<string, any>;
+        tenancy?: any;
+        external?: {
+            remoteName?: string;
+            remoteSchema?: string;
+            columnMap?: Record<string, string>;
+        };
+    }): void;
     initObjects(objects: Array<{
         name: string;
         fields?: Record<string, any>;
@@ -404,6 +477,16 @@ declare class SqlDriver implements IDataDriver {
      * `initObjects`). Returns null when the builder is not table-scoped yet.
      */
     protected tableNameForBuilder(builder: any): string | null;
+    /**
+     * Coercion-map key for a builder. Coercion maps (date/datetime) are keyed by
+     * OBJECT name, but after the federation change {@link getBuilder} targets the
+     * physical remote table, so a builder reports the remote name. Map it back to
+     * the object name for external objects; identity for managed ones (no reverse
+     * entry). Note datetime coercion is a SQLite-only concern (see
+     * coerceFilterValue), and SQLite external tables are bare-named, so this is
+     * exact where it matters.
+     */
+    protected coercionKey(builder: any): string | null;
     /**
      * Collapse a `Field.date` value to a timezone-naive `YYYY-MM-DD`
      * calendar-day string (ADR-0053 Phase 1). A `Date` collapses to its UTC
@@ -463,6 +546,19 @@ declare class SqlDriver implements IDataDriver {
     private applyContainsLike;
     protected applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp?: 'and' | 'or', tableHint?: string | null): void;
     protected mapSortField(field: string): string;
+    /**
+     * Physical column for a logical field on an external object that declares an
+     * `external.columnMap` (ADR-0015). Returns `fallback` (the caller's existing
+     * per-site resolution) when the object has no columnMap, so managed objects
+     * and external objects without a columnMap are byte-for-byte unchanged.
+     */
+    protected remoteColumn(object: string | null | undefined, field: string, fallback: string): string;
+    /**
+     * Remap a write payload's logical field keys to physical remote columns for an
+     * external object with a columnMap. No-op otherwise. Applied AFTER formatInput
+     * (whose value coercion is keyed by logical field name).
+     */
+    protected applyWriteColumnMap(object: string, data: any): any;
     protected mapAggregateFunc(func: string): string;
     protected buildWindowFunction(spec: any): string;
     protected createColumn(table: Knex.CreateTableBuilder, name: string, field: any): void;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SchemaMode, QueryAST, DriverOptions } from '@objectstack/spec/data';
+import { AutonumberToken, SchemaMode, QueryAST, DriverOptions } from '@objectstack/spec/data';
 import { IDataDriver } from '@objectstack/spec/contracts';
 import knex, { Knex } from 'knex';
 
@@ -101,6 +101,20 @@ declare class SqlDriver implements IDataDriver {
     protected numericFields: Record<string, string[]>;
     protected dateFields: Record<string, Set<string>>;
     protected datetimeFields: Record<string, Set<string>>;
+    /**
+     * Federation read path (ADR-0015). For external objects whose physical
+     * remote table differs from the object name, these map between the two so
+     * {@link getBuilder} targets the remote table while the coercion maps above
+     * stay keyed by OBJECT name (matching formatInput/formatOutput). Empty for
+     * managed objects, so the managed query path is unchanged.
+     */
+    protected physicalTableByObject: Record<string, string>;
+    protected physicalSchemaByObject: Record<string, string>;
+    protected objectByPhysicalTable: Record<string, string>;
+    /** External columnMap (ADR-0015): logical field -> physical remote column (for WHERE/ORDER BY/writes). */
+    protected fieldColumnByObject: Record<string, Record<string, string>>;
+    /** External columnMap inverse: physical remote column -> logical field (for read output remap). */
+    protected columnFieldByObject: Record<string, Record<string, string>>;
     protected tablesWithTimestamps: Set<string>;
     /**
      * Autonumber field configs per table, captured during initObjects.
@@ -119,12 +133,19 @@ declare class SqlDriver implements IDataDriver {
     protected autoNumberFields: Record<string, Array<{
         name: string;
         format: string;
-        prefix: string;
-        padWidth: number;
+        tokens: AutonumberToken[];
         tenantField: string | null;
     }>>;
     /** Whether the sequences table has been ensured this process. */
     protected sequencesTableReady: boolean;
+    /**
+     * Whether `_objectstack_sequences` is the current `key_hash`-keyed shape.
+     * Set on a fresh create or a successful in-place migration. If a legacy table
+     * could NOT be migrated, this stays false: fixed-prefix sequences (empty
+     * scope) keep working via the legacy `(object, tenant_id, field)` key, while a
+     * per-scope write raises an actionable error rather than corrupting counters.
+     */
+    protected sequencesHasKeyHash: boolean;
     /** In-flight ensure promise; deduplicates concurrent first calls. */
     protected sequencesTableEnsurePromise: Promise<void> | null;
     /**
@@ -214,8 +235,34 @@ declare class SqlDriver implements IDataDriver {
     /**
      * Ensure the sequence-counter table exists. Idempotent and cheap after
      * the first call (cached via `sequencesTableReady`).
+     *
+     * The row key is `key_hash` — a SHA-256 of `(object, tenant_id, field, scope)`
+     * where `scope` is the rendered autonumber prefix (date/field tokens before
+     * the `{0000}` slot), so a new day/group/parent starts a fresh counter. A
+     * single 64-char hashed primary key (rather than the four raw columns, which
+     * blow past MySQL's 3072-byte index limit under utf8mb4 and bound how long a
+     * `{field}` scope may be) keys every dialect uniformly and lets `scope` be a
+     * generous non-indexed column. Fixed-prefix formats use the empty scope and
+     * keep their single global counter (backward compatible).
      */
     protected ensureSequencesTable(): Promise<void>;
+    /** SHA-256 of the composite counter key — the table's single-column PK. */
+    protected sequenceKeyHash(object: string, tenantId: string, field: string, scope: string): string;
+    /** Create the current `key_hash`-keyed sequences table shape. */
+    protected createSequencesTable(table: string): Promise<void>;
+    /**
+     * Migrate a pre-existing `_objectstack_sequences` table to the current
+     * `key_hash`-keyed shape. Handles both the original 3-column table (no
+     * `scope`) and an interim 4-column `(object, tenant_id, field, scope)` table:
+     * every legacy row is read, its `key_hash` computed in app code (no portable
+     * SQL hash exists), and re-inserted into a freshly built table that then
+     * replaces the original. Idempotent — a no-op once `key_hash` is present.
+     *
+     * If the rebuild fails, `sequencesHasKeyHash` stays false: fixed-prefix
+     * sequences keep working via the legacy key and per-scope writes error
+     * actionably (see getNextSequenceValue), rather than corrupting data.
+     */
+    protected ensureSequencesKeyHashShape(): Promise<void>;
     /**
      * Bootstrap helper: scan the data table for the highest numeric suffix
      * matching `prefix` (optionally scoped to a tenant). Used the first time
@@ -237,12 +284,14 @@ declare class SqlDriver implements IDataDriver {
      * Gaps are tolerated by design — a rolled-back insert "burns" a number,
      * matching standard sequence semantics.
      */
-    protected getNextSequenceValue(object: string, tableName: string, field: string, prefix: string, tenantField: string | null, tenantId: string | null, parentTrx?: Knex.Transaction): Promise<number>;
+    protected getNextSequenceValue(object: string, tableName: string, field: string, prefix: string, tenantField: string | null, tenantId: string | null, parentTrx?: Knex.Transaction, scope?: string): Promise<number>;
     /**
-     * For each `auto_number` field on the object that the caller did not
-     * provide a value for, reserve the next sequence value scoped to the
-     * record's tenant (or globally if the object has no tenant field) and
-     * render `prefix + zero-padded(value)`.
+     * For each `auto_number` field the caller left empty, render the format and
+     * reserve the next counter value. The counter is scoped to the rendered
+     * prefix (date tokens like `{YYYYMMDD}` in the request's business timezone,
+     * plus `{field}` interpolation from the row), so it resets per period/group;
+     * the full rendered prefix bootstraps the counter from existing data, and the
+     * tenant scopes it for isolation.
      */
     protected fillAutoNumberFields(object: string, row: Record<string, any>, options?: DriverOptions): Promise<void>;
     update(object: string, id: string | number, data: Record<string, any>, options?: DriverOptions): Promise<any>;
@@ -299,6 +348,30 @@ declare class SqlDriver implements IDataDriver {
     /**
      * Batch-initialise tables from an array of object definitions.
      */
+    /**
+     * DDL-free metadata registration for a federated (external) object — the
+     * read-path counterpart to {@link initObjects} (ADR-0015 federation).
+     *
+     * `initObjects` is gated by `assertSchemaMutable` and therefore throws for
+     * any non-`managed` driver, which left external objects with NO read-coercion
+     * metadata and the query path resolving to a table named after the object
+     * instead of its remote table. This populates the same coercion maps (keyed
+     * by OBJECT name, matching formatInput/formatOutput/coerceFilterValue) and
+     * records the physical remote table (`external.remoteName`, optionally
+     * `external.remoteSchema`) so {@link getBuilder} targets it — WITHOUT running
+     * any DDL (createTable/alterTable/columnInfo). Keep the field-classification
+     * below in sync with initObjects() if the field-type -> storage mapping changes.
+     */
+    registerExternalObject(schema: {
+        name: string;
+        fields?: Record<string, any>;
+        tenancy?: any;
+        external?: {
+            remoteName?: string;
+            remoteSchema?: string;
+            columnMap?: Record<string, string>;
+        };
+    }): void;
     initObjects(objects: Array<{
         name: string;
         fields?: Record<string, any>;
@@ -404,6 +477,16 @@ declare class SqlDriver implements IDataDriver {
      * `initObjects`). Returns null when the builder is not table-scoped yet.
      */
     protected tableNameForBuilder(builder: any): string | null;
+    /**
+     * Coercion-map key for a builder. Coercion maps (date/datetime) are keyed by
+     * OBJECT name, but after the federation change {@link getBuilder} targets the
+     * physical remote table, so a builder reports the remote name. Map it back to
+     * the object name for external objects; identity for managed ones (no reverse
+     * entry). Note datetime coercion is a SQLite-only concern (see
+     * coerceFilterValue), and SQLite external tables are bare-named, so this is
+     * exact where it matters.
+     */
+    protected coercionKey(builder: any): string | null;
     /**
      * Collapse a `Field.date` value to a timezone-naive `YYYY-MM-DD`
      * calendar-day string (ADR-0053 Phase 1). A `Date` collapses to its UTC
@@ -463,6 +546,19 @@ declare class SqlDriver implements IDataDriver {
     private applyContainsLike;
     protected applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp?: 'and' | 'or', tableHint?: string | null): void;
     protected mapSortField(field: string): string;
+    /**
+     * Physical column for a logical field on an external object that declares an
+     * `external.columnMap` (ADR-0015). Returns `fallback` (the caller's existing
+     * per-site resolution) when the object has no columnMap, so managed objects
+     * and external objects without a columnMap are byte-for-byte unchanged.
+     */
+    protected remoteColumn(object: string | null | undefined, field: string, fallback: string): string;
+    /**
+     * Remap a write payload's logical field keys to physical remote columns for an
+     * external object with a columnMap. No-op otherwise. Applied AFTER formatInput
+     * (whose value coercion is keyed by logical field name).
+     */
+    protected applyWriteColumnMap(object: string, data: any): any;
     protected mapAggregateFunc(func: string): string;
     protected buildWindowFunction(spec: any): string;
     protected createColumn(table: Knex.CreateTableBuilder, name: string, field: any): void;