@objectstack/objectql 7.9.0 → 8.0.1

package/dist/index.d.mts

@@ -5,6 +5,7 @@ import { MetadataRepository, MetaRef, MetadataItem, PutOptions, PutResult, Delet
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest, InstallPackageRequest, InstallPackageResponse } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
 import { IFeedService, IRealtimeService, ICryptoProvider } from '@objectstack/spec/contracts';
+import { Expression } from '@objectstack/spec';
 
 /**
  * Reserved namespaces that do not get FQN prefix applied.
@@ -525,7 +526,18 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 } | undefined;
                 shortcut?: string | undefined;
                 bulkEnabled?: boolean | undefined;
-                aiExposed?: boolean | undefined;
+                ai?: {
+                    exposed: boolean;
+                    description?: string | undefined;
+                    category?: "data" | "flow" | "analytics" | "action" | "integration" | "vector_search" | "utility" | undefined;
+                    paramHints?: Record<string, {
+                        description?: string | undefined;
+                        enum?: (string | number)[] | undefined;
+                        examples?: unknown[] | undefined;
+                    }> | undefined;
+                    outputSchema?: Record<string, unknown> | undefined;
+                    requiresConfirmation?: boolean | undefined;
+                } | undefined;
                 recordIdParam?: string | undefined;
                 recordIdField?: string | undefined;
                 bodyShape?: "flat" | {
@@ -627,6 +639,17 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                         } | undefined;
                     } | undefined;
                 }[] | undefined;
+                subforms?: {
+                    childObject: string;
+                    relationshipField?: string | undefined;
+                    columns?: any[] | undefined;
+                    amountField?: string | undefined;
+                    totalField?: string | undefined;
+                    title?: string | undefined;
+                    addLabel?: string | undefined;
+                    minRows?: number | undefined;
+                    maxRows?: number | undefined;
+                }[] | undefined;
                 defaultSort?: {
                     field: string;
                     order: "asc" | "desc";
@@ -665,7 +688,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             supportsVersioning: boolean;
             executionPinned: boolean;
             loadOrder: number;
-            domain: "system" | "data" | "ui" | "automation" | "ai" | "security";
+            domain: "system" | "data" | "ai" | "ui" | "automation" | "security";
             description?: string | undefined;
         }[];
     }>;
@@ -1779,15 +1802,16 @@ interface ObjectQLHostContext {
     logger: Logger;
     [key: string]: any;
 }
-/**
- * ObjectQL Engine
- *
- * Implements the IDataEngine interface for data persistence.
- * Acts as the reference implementation for:
- * - CoreServiceName.data (CRUD)
- * - CoreServiceName.metadata (Schema Registry)
- */
 declare class ObjectQL implements IDataEngine {
+    /**
+     * Ambient transaction store (ADR-0034). While a `transaction()` callback
+     * runs, the active transaction handle lives here so that EVERY data
+     * operation — including internal reads done during a write (reference
+     * checks, hooks, expand) — automatically binds to the same connection
+     * instead of asking the pool for another one and deadlocking on the
+     * single-connection SQLite pool.
+     */
+    private readonly txStore;
     private drivers;
     private defaultDriver;
     private logger;
@@ -1965,6 +1989,26 @@ declare class ObjectQL implements IDataEngine {
      * declarative `defaultValue: cel\`today()\``.
      */
     private applyFieldDefaults;
+    /**
+     * Generate values for empty `autonumber` fields on insert — ONLY for drivers
+     * that do not generate them natively (memory, mongodb). For SQL-backed objects
+     * the driver owns a persistent, atomic `_objectstack_sequences` table and
+     * advertises `supports.autonumber === true`; the engine then defers entirely
+     * and never pre-fills (so the persistent sequence is the single source of
+     * truth — see #1603). Required-validation exempts `autonumber` either way, so
+     * a `required` record number is never rejected for "missing" — the runtime
+     * owns the value, not the client.
+     *
+     * In the fallback path the next value is `max(existing) + 1`, seeded once per
+     * `object.field` from the store then incremented in memory (monotonic within
+     * the process, resilient to deletions). `autonumberFormat` is honored, e.g.
+     * `CASE-{0000}` → `CASE-0042`. NOTE: this in-memory seeding is single-instance.
+     */
+    private applyAutonumbers;
+    /** Seed the autonumber counter from the current max numeric value in store. */
+    private seedAutonumber;
+    /** Apply an autonumber format like `CASE-{0000}`; default to the bare number. */
+    private formatAutonumber;
     /**
      * Register contribution (Manifest)
      *
@@ -2131,6 +2175,27 @@ declare class ObjectQL implements IDataEngine {
     destroy(): Promise<void>;
     /** Maximum depth for recursive expand to prevent infinite loops */
     private static readonly MAX_EXPAND_DEPTH;
+    private static readonly MAX_CASCADE_DEPTH;
+    /** In-memory next-value cache per `object.field` for autonumber generation,
+     *  lazily seeded from the current max in the store. */
+    private readonly autonumberCounters;
+    /** Lazily-built index: child object name → roll-up summary descriptors on
+     *  parent objects that aggregate it. Invalidated when packages register. */
+    private summaryIndex;
+    /** Invalidate the cached roll-up summary index (call when metadata changes). */
+    private invalidateSummaryIndex;
+    /** Scan all registered objects for `summary` fields and index them by the
+     *  child object they aggregate, resolving the child→parent FK field. */
+    private buildSummaryIndex;
+    private getSummaryDescriptors;
+    /**
+     * Recompute roll-up `summary` fields on parent records after a child write.
+     * For each affected parent (the FK value on the changed/old child record), it
+     * aggregates the child collection and writes the result onto the parent's
+     * summary field. Runs in the caller's execution context so it joins the same
+     * transaction (e.g. the cross-object batch) when one is open.
+     */
+    private recomputeSummaries;
     /**
      * Post-process expand: resolve lookup/master_detail fields by batch-loading related records.
      *
@@ -2148,6 +2213,19 @@ declare class ObjectQL implements IDataEngine {
     findOne(objectName: string, query?: EngineQueryOptions): Promise<any>;
     insert(object: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
     update(object: string, data: any, options?: EngineUpdateOptions): Promise<any>;
+    /**
+     * Apply referential delete behavior for relations pointing AT this record,
+     * before it is removed. For every registered object with a `master_detail`
+     * or `lookup` field referencing `object`, honor the field's `deleteBehavior`:
+     *   - `cascade`  → delete the dependent rows (recursively, so grandchildren
+     *                  are handled by each child's own delete),
+     *   - `set_null` → clear the foreign key,
+     *   - `restrict` → refuse the delete when dependents exist.
+     * `master_detail` defaults to `cascade` (the parent owns the child
+     * lifecycle); `lookup` defaults to `set_null`. Only runs for single-id
+     * deletes — multi/predicate deletes skip cascade (logged).
+     */
+    private cascadeDeleteRelations;
     delete(object: string, options?: EngineDeleteOptions): Promise<any>;
     count(object: string, query?: EngineCountOptions): Promise<number>;
     aggregate(object: string, query: EngineAggregateOptions): Promise<any[]>;
@@ -2643,7 +2721,15 @@ interface EvaluateRulesOptions {
  */
 declare function needsPriorRecord(objectSchema: {
     validations?: unknown[];
+    fields?: Record<string, ConditionalFieldDef>;
 } | undefined | null): boolean;
+/** Field-level conditional rules (B2): a field is required / read-only when its
+ *  CEL predicate is TRUE over the record. */
+interface ConditionalFieldDef {
+    requiredWhen?: string | Expression;
+    conditionalRequired?: string | Expression;
+    readonlyWhen?: string | Expression;
+}
 /**
  * Evaluate an object's declared validation rules against an incoming write.
  *
@@ -2653,6 +2739,7 @@ declare function needsPriorRecord(objectSchema: {
  */
 declare function evaluateValidationRules(objectSchema: {
     validations?: unknown[];
+    fields?: Record<string, ConditionalFieldDef>;
 } | undefined | null, data: Record<string, unknown> | undefined | null, mode: Mode, opts?: EvaluateRulesOptions): void;
 /**
  * Introspection helper (ADR-0020 D3.3): given an object's schema, a state

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { MetadataRepository, MetaRef, MetadataItem, PutOptions, PutResult, Delet
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest, InstallPackageRequest, InstallPackageResponse } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
 import { IFeedService, IRealtimeService, ICryptoProvider } from '@objectstack/spec/contracts';
+import { Expression } from '@objectstack/spec';
 
 /**
  * Reserved namespaces that do not get FQN prefix applied.
@@ -525,7 +526,18 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 } | undefined;
                 shortcut?: string | undefined;
                 bulkEnabled?: boolean | undefined;
-                aiExposed?: boolean | undefined;
+                ai?: {
+                    exposed: boolean;
+                    description?: string | undefined;
+                    category?: "data" | "flow" | "analytics" | "action" | "integration" | "vector_search" | "utility" | undefined;
+                    paramHints?: Record<string, {
+                        description?: string | undefined;
+                        enum?: (string | number)[] | undefined;
+                        examples?: unknown[] | undefined;
+                    }> | undefined;
+                    outputSchema?: Record<string, unknown> | undefined;
+                    requiresConfirmation?: boolean | undefined;
+                } | undefined;
                 recordIdParam?: string | undefined;
                 recordIdField?: string | undefined;
                 bodyShape?: "flat" | {
@@ -627,6 +639,17 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                         } | undefined;
                     } | undefined;
                 }[] | undefined;
+                subforms?: {
+                    childObject: string;
+                    relationshipField?: string | undefined;
+                    columns?: any[] | undefined;
+                    amountField?: string | undefined;
+                    totalField?: string | undefined;
+                    title?: string | undefined;
+                    addLabel?: string | undefined;
+                    minRows?: number | undefined;
+                    maxRows?: number | undefined;
+                }[] | undefined;
                 defaultSort?: {
                     field: string;
                     order: "asc" | "desc";
@@ -665,7 +688,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             supportsVersioning: boolean;
             executionPinned: boolean;
             loadOrder: number;
-            domain: "system" | "data" | "ui" | "automation" | "ai" | "security";
+            domain: "system" | "data" | "ai" | "ui" | "automation" | "security";
             description?: string | undefined;
         }[];
     }>;
@@ -1779,15 +1802,16 @@ interface ObjectQLHostContext {
     logger: Logger;
     [key: string]: any;
 }
-/**
- * ObjectQL Engine
- *
- * Implements the IDataEngine interface for data persistence.
- * Acts as the reference implementation for:
- * - CoreServiceName.data (CRUD)
- * - CoreServiceName.metadata (Schema Registry)
- */
 declare class ObjectQL implements IDataEngine {
+    /**
+     * Ambient transaction store (ADR-0034). While a `transaction()` callback
+     * runs, the active transaction handle lives here so that EVERY data
+     * operation — including internal reads done during a write (reference
+     * checks, hooks, expand) — automatically binds to the same connection
+     * instead of asking the pool for another one and deadlocking on the
+     * single-connection SQLite pool.
+     */
+    private readonly txStore;
     private drivers;
     private defaultDriver;
     private logger;
@@ -1965,6 +1989,26 @@ declare class ObjectQL implements IDataEngine {
      * declarative `defaultValue: cel\`today()\``.
      */
     private applyFieldDefaults;
+    /**
+     * Generate values for empty `autonumber` fields on insert — ONLY for drivers
+     * that do not generate them natively (memory, mongodb). For SQL-backed objects
+     * the driver owns a persistent, atomic `_objectstack_sequences` table and
+     * advertises `supports.autonumber === true`; the engine then defers entirely
+     * and never pre-fills (so the persistent sequence is the single source of
+     * truth — see #1603). Required-validation exempts `autonumber` either way, so
+     * a `required` record number is never rejected for "missing" — the runtime
+     * owns the value, not the client.
+     *
+     * In the fallback path the next value is `max(existing) + 1`, seeded once per
+     * `object.field` from the store then incremented in memory (monotonic within
+     * the process, resilient to deletions). `autonumberFormat` is honored, e.g.
+     * `CASE-{0000}` → `CASE-0042`. NOTE: this in-memory seeding is single-instance.
+     */
+    private applyAutonumbers;
+    /** Seed the autonumber counter from the current max numeric value in store. */
+    private seedAutonumber;
+    /** Apply an autonumber format like `CASE-{0000}`; default to the bare number. */
+    private formatAutonumber;
     /**
      * Register contribution (Manifest)
      *
@@ -2131,6 +2175,27 @@ declare class ObjectQL implements IDataEngine {
     destroy(): Promise<void>;
     /** Maximum depth for recursive expand to prevent infinite loops */
     private static readonly MAX_EXPAND_DEPTH;
+    private static readonly MAX_CASCADE_DEPTH;
+    /** In-memory next-value cache per `object.field` for autonumber generation,
+     *  lazily seeded from the current max in the store. */
+    private readonly autonumberCounters;
+    /** Lazily-built index: child object name → roll-up summary descriptors on
+     *  parent objects that aggregate it. Invalidated when packages register. */
+    private summaryIndex;
+    /** Invalidate the cached roll-up summary index (call when metadata changes). */
+    private invalidateSummaryIndex;
+    /** Scan all registered objects for `summary` fields and index them by the
+     *  child object they aggregate, resolving the child→parent FK field. */
+    private buildSummaryIndex;
+    private getSummaryDescriptors;
+    /**
+     * Recompute roll-up `summary` fields on parent records after a child write.
+     * For each affected parent (the FK value on the changed/old child record), it
+     * aggregates the child collection and writes the result onto the parent's
+     * summary field. Runs in the caller's execution context so it joins the same
+     * transaction (e.g. the cross-object batch) when one is open.
+     */
+    private recomputeSummaries;
     /**
      * Post-process expand: resolve lookup/master_detail fields by batch-loading related records.
      *
@@ -2148,6 +2213,19 @@ declare class ObjectQL implements IDataEngine {
     findOne(objectName: string, query?: EngineQueryOptions): Promise<any>;
     insert(object: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
     update(object: string, data: any, options?: EngineUpdateOptions): Promise<any>;
+    /**
+     * Apply referential delete behavior for relations pointing AT this record,
+     * before it is removed. For every registered object with a `master_detail`
+     * or `lookup` field referencing `object`, honor the field's `deleteBehavior`:
+     *   - `cascade`  → delete the dependent rows (recursively, so grandchildren
+     *                  are handled by each child's own delete),
+     *   - `set_null` → clear the foreign key,
+     *   - `restrict` → refuse the delete when dependents exist.
+     * `master_detail` defaults to `cascade` (the parent owns the child
+     * lifecycle); `lookup` defaults to `set_null`. Only runs for single-id
+     * deletes — multi/predicate deletes skip cascade (logged).
+     */
+    private cascadeDeleteRelations;
     delete(object: string, options?: EngineDeleteOptions): Promise<any>;
     count(object: string, query?: EngineCountOptions): Promise<number>;
     aggregate(object: string, query: EngineAggregateOptions): Promise<any[]>;
@@ -2643,7 +2721,15 @@ interface EvaluateRulesOptions {
  */
 declare function needsPriorRecord(objectSchema: {
     validations?: unknown[];
+    fields?: Record<string, ConditionalFieldDef>;
 } | undefined | null): boolean;
+/** Field-level conditional rules (B2): a field is required / read-only when its
+ *  CEL predicate is TRUE over the record. */
+interface ConditionalFieldDef {
+    requiredWhen?: string | Expression;
+    conditionalRequired?: string | Expression;
+    readonlyWhen?: string | Expression;
+}
 /**
  * Evaluate an object's declared validation rules against an incoming write.
  *
@@ -2653,6 +2739,7 @@ declare function needsPriorRecord(objectSchema: {
  */
 declare function evaluateValidationRules(objectSchema: {
     validations?: unknown[];
+    fields?: Record<string, ConditionalFieldDef>;
 } | undefined | null, data: Record<string, unknown> | undefined | null, mode: Mode, opts?: EvaluateRulesOptions): void;
 /**
  * Introspection helper (ADR-0020 D3.3): given an object's schema, a state