@objectstack/objectql 8.0.0 → 9.0.0

package/dist/index.d.mts

@@ -1,10 +1,10 @@
-import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions, DateGranularityValue, Hook } from '@objectstack/spec/data';
+import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions, DateGranularityValue, Hook, SeedLoaderRequest, SeedLoaderResult, ObjectDependencyGraph, Seed, SeedLoaderConfigInput } from '@objectstack/spec/data';
 import { ObjectStackManifest, InstalledPackage, MetadataValidationResult, MetadataLock, MetadataProvenance, ExecutionContext } from '@objectstack/spec/kernel';
 import * as _objectstack_metadata_core from '@objectstack/metadata-core';
 import { MetadataRepository, MetaRef, MetadataItem, PutOptions, PutResult, DeleteOptions, DeleteResult, MetadataWriteIntent, ListFilter, MetadataItemHeader, HistoryOptions, MetadataEvent, WatchFilter } from '@objectstack/metadata-core';
 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 { IDataEngine, DriverInterface, Logger as Logger$1, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
+import { IFeedService, IRealtimeService, ICryptoProvider, ISeedLoaderService, IDataEngine as IDataEngine$1, IMetadataService } from '@objectstack/spec/contracts';
 import { Expression } from '@objectstack/spec';
 
 /**
@@ -1250,12 +1250,40 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         organizationId?: string;
         actor?: string;
         message?: string;
+        /**
+         * INTERNAL — `publishPackageDrafts` publishes many drafts and batch-applies
+         * every seed body in ONE loader pass afterwards (cross-seed references need
+         * multi-pass over the whole set), so it suppresses the per-item apply here.
+         */
+        _skipSeedApply?: boolean;
     }): Promise<{
         success: boolean;
         version: string;
         seq: number;
         message?: string;
+        /**
+         * Present when a `seed` draft was published: the result of materializing
+         * its rows. Publishing the metadata ALWAYS succeeds independently — a
+         * seed-load problem is surfaced here, never thrown, so callers (and UIs)
+         * must check `seedApplied.success` instead of assuming data went live.
+         */
+        seedApplied?: {
+            success: boolean;
+            inserted: number;
+            updated: number;
+            error?: string;
+            errors?: unknown[];
+        };
     }>;
+    /**
+     * Materialize published `seed` bodies into data rows via the SeedLoaderService
+     * (externalId-keyed upsert, multi-pass for cross-seed references). Passing ALL
+     * of a publish's seed bodies in ONE call lets a child seed reference a parent
+     * seed's rows regardless of publish order. Best-effort: any failure is
+     * returned, never thrown — publishing metadata must not be blocked by a data
+     * problem, but the caller surfaces `seedApplied` so the failure is LOUD.
+     */
+    private applySeedBodies;
     /**
      * List pending DRAFT metadata (ADR-0033) for the org, optionally narrowed
      * by `packageId` and/or `type`. The list reads of `getMetaItems` only see
@@ -1304,6 +1332,14 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             error: string;
             code?: string;
         }>;
+        /** Aggregate result of materializing every published `seed` (absent when no seeds). */
+        seedApplied?: {
+            success: boolean;
+            inserted: number;
+            updated: number;
+            error?: string;
+            errors?: unknown[];
+        };
     }>;
     /**
      * Discard every pending DRAFT bound to a package — the NON-destructive
@@ -1799,7 +1835,7 @@ type EngineMiddleware = (ctx: OperationContext, next: () => Promise<void>) => Pr
  */
 interface ObjectQLHostContext {
     ql: ObjectQL;
-    logger: Logger;
+    logger: Logger$1;
     [key: string]: any;
 }
 declare class ObjectQL implements IDataEngine {
@@ -3107,4 +3143,56 @@ declare function convertIntrospectedSchemaToObjects(introspectedSchema: Introspe
     skipSystemColumns?: boolean;
 }): ServiceObject[];
 
-export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type EvaluateRulesOptions, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SECRET_MASK, SECRET_REF_PREFIX, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, collectSecretFields, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, evaluateValidationRules, isSecretRef, legalNextStates, makeSecretRef, needsPriorRecord, noopHookMetricsRecorder, parseFQN, parseSecretRef, toTitleCase, validateRecord, wrapDeclarativeHook };
+interface Logger {
+    info(message: string, meta?: Record<string, any>): void;
+    warn(message: string, meta?: Record<string, any>): void;
+    error(message: string, error?: Error, meta?: Record<string, any>): void;
+    debug(message: string, meta?: Record<string, any>): void;
+}
+/**
+ * SeedLoaderService — Runtime implementation of ISeedLoaderService
+ *
+ * Provides metadata-driven seed data loading with:
+ * - Automatic lookup/master_detail reference resolution via externalId
+ * - Topological dependency ordering (parents before children)
+ * - Multi-pass loading for circular references
+ * - Dry-run validation mode
+ * - Upsert support honoring SeedSchema mode
+ * - Actionable error reporting
+ */
+declare class SeedLoaderService implements ISeedLoaderService {
+    private engine;
+    private metadata;
+    private logger;
+    constructor(engine: IDataEngine$1, metadata: IMetadataService, logger: Logger);
+    load(request: SeedLoaderRequest): Promise<SeedLoaderResult>;
+    buildDependencyGraph(objectNames: string[]): Promise<ObjectDependencyGraph>;
+    validate(datasets: Seed[], config?: SeedLoaderConfigInput): Promise<SeedLoaderResult>;
+    private loadDataset;
+    private resolveFromDatabase;
+    private resolveDeferredUpdates;
+    /**
+     * Seed writes always run as a privileged system context. This bypasses
+     * RBAC checks (so seeds can target system tables like `sys_*`) and
+     * disables the SecurityPlugin's auto-injection of `organization_id` /
+     * `owner_id` — seeds either declare those fields explicitly per
+     * record, or are intentionally cross-tenant / global.
+     */
+    private static readonly SEED_OPTIONS;
+    private writeRecord;
+    /**
+     * Kahn's algorithm for topological sort with cycle detection.
+     */
+    private topologicalSort;
+    private findCycles;
+    private filterByEnv;
+    private orderDatasets;
+    private buildReferenceMap;
+    private loadExistingRecords;
+    private looksLikeInternalId;
+    private extractId;
+    private buildEmptyResult;
+    private buildResult;
+}
+
+export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type EvaluateRulesOptions, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SECRET_MASK, SECRET_REF_PREFIX, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, SeedLoaderService, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, collectSecretFields, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, evaluateValidationRules, isSecretRef, legalNextStates, makeSecretRef, needsPriorRecord, noopHookMetricsRecorder, parseFQN, parseSecretRef, toTitleCase, validateRecord, wrapDeclarativeHook };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions, DateGranularityValue, Hook } from '@objectstack/spec/data';
+import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions, DateGranularityValue, Hook, SeedLoaderRequest, SeedLoaderResult, ObjectDependencyGraph, Seed, SeedLoaderConfigInput } from '@objectstack/spec/data';
 import { ObjectStackManifest, InstalledPackage, MetadataValidationResult, MetadataLock, MetadataProvenance, ExecutionContext } from '@objectstack/spec/kernel';
 import * as _objectstack_metadata_core from '@objectstack/metadata-core';
 import { MetadataRepository, MetaRef, MetadataItem, PutOptions, PutResult, DeleteOptions, DeleteResult, MetadataWriteIntent, ListFilter, MetadataItemHeader, HistoryOptions, MetadataEvent, WatchFilter } from '@objectstack/metadata-core';
 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 { IDataEngine, DriverInterface, Logger as Logger$1, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
+import { IFeedService, IRealtimeService, ICryptoProvider, ISeedLoaderService, IDataEngine as IDataEngine$1, IMetadataService } from '@objectstack/spec/contracts';
 import { Expression } from '@objectstack/spec';
 
 /**
@@ -1250,12 +1250,40 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         organizationId?: string;
         actor?: string;
         message?: string;
+        /**
+         * INTERNAL — `publishPackageDrafts` publishes many drafts and batch-applies
+         * every seed body in ONE loader pass afterwards (cross-seed references need
+         * multi-pass over the whole set), so it suppresses the per-item apply here.
+         */
+        _skipSeedApply?: boolean;
     }): Promise<{
         success: boolean;
         version: string;
         seq: number;
         message?: string;
+        /**
+         * Present when a `seed` draft was published: the result of materializing
+         * its rows. Publishing the metadata ALWAYS succeeds independently — a
+         * seed-load problem is surfaced here, never thrown, so callers (and UIs)
+         * must check `seedApplied.success` instead of assuming data went live.
+         */
+        seedApplied?: {
+            success: boolean;
+            inserted: number;
+            updated: number;
+            error?: string;
+            errors?: unknown[];
+        };
     }>;
+    /**
+     * Materialize published `seed` bodies into data rows via the SeedLoaderService
+     * (externalId-keyed upsert, multi-pass for cross-seed references). Passing ALL
+     * of a publish's seed bodies in ONE call lets a child seed reference a parent
+     * seed's rows regardless of publish order. Best-effort: any failure is
+     * returned, never thrown — publishing metadata must not be blocked by a data
+     * problem, but the caller surfaces `seedApplied` so the failure is LOUD.
+     */
+    private applySeedBodies;
     /**
      * List pending DRAFT metadata (ADR-0033) for the org, optionally narrowed
      * by `packageId` and/or `type`. The list reads of `getMetaItems` only see
@@ -1304,6 +1332,14 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             error: string;
             code?: string;
         }>;
+        /** Aggregate result of materializing every published `seed` (absent when no seeds). */
+        seedApplied?: {
+            success: boolean;
+            inserted: number;
+            updated: number;
+            error?: string;
+            errors?: unknown[];
+        };
     }>;
     /**
      * Discard every pending DRAFT bound to a package — the NON-destructive
@@ -1799,7 +1835,7 @@ type EngineMiddleware = (ctx: OperationContext, next: () => Promise<void>) => Pr
  */
 interface ObjectQLHostContext {
     ql: ObjectQL;
-    logger: Logger;
+    logger: Logger$1;
     [key: string]: any;
 }
 declare class ObjectQL implements IDataEngine {
@@ -3107,4 +3143,56 @@ declare function convertIntrospectedSchemaToObjects(introspectedSchema: Introspe
     skipSystemColumns?: boolean;
 }): ServiceObject[];
 
-export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type EvaluateRulesOptions, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SECRET_MASK, SECRET_REF_PREFIX, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, collectSecretFields, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, evaluateValidationRules, isSecretRef, legalNextStates, makeSecretRef, needsPriorRecord, noopHookMetricsRecorder, parseFQN, parseSecretRef, toTitleCase, validateRecord, wrapDeclarativeHook };
+interface Logger {
+    info(message: string, meta?: Record<string, any>): void;
+    warn(message: string, meta?: Record<string, any>): void;
+    error(message: string, error?: Error, meta?: Record<string, any>): void;
+    debug(message: string, meta?: Record<string, any>): void;
+}
+/**
+ * SeedLoaderService — Runtime implementation of ISeedLoaderService
+ *
+ * Provides metadata-driven seed data loading with:
+ * - Automatic lookup/master_detail reference resolution via externalId
+ * - Topological dependency ordering (parents before children)
+ * - Multi-pass loading for circular references
+ * - Dry-run validation mode
+ * - Upsert support honoring SeedSchema mode
+ * - Actionable error reporting
+ */
+declare class SeedLoaderService implements ISeedLoaderService {
+    private engine;
+    private metadata;
+    private logger;
+    constructor(engine: IDataEngine$1, metadata: IMetadataService, logger: Logger);
+    load(request: SeedLoaderRequest): Promise<SeedLoaderResult>;
+    buildDependencyGraph(objectNames: string[]): Promise<ObjectDependencyGraph>;
+    validate(datasets: Seed[], config?: SeedLoaderConfigInput): Promise<SeedLoaderResult>;
+    private loadDataset;
+    private resolveFromDatabase;
+    private resolveDeferredUpdates;
+    /**
+     * Seed writes always run as a privileged system context. This bypasses
+     * RBAC checks (so seeds can target system tables like `sys_*`) and
+     * disables the SecurityPlugin's auto-injection of `organization_id` /
+     * `owner_id` — seeds either declare those fields explicitly per
+     * record, or are intentionally cross-tenant / global.
+     */
+    private static readonly SEED_OPTIONS;
+    private writeRecord;
+    /**
+     * Kahn's algorithm for topological sort with cycle detection.
+     */
+    private topologicalSort;
+    private findCycles;
+    private filterByEnv;
+    private orderDatasets;
+    private buildReferenceMap;
+    private loadExistingRecords;
+    private looksLikeInternalId;
+    private extractId;
+    private buildEmptyResult;
+    private buildResult;
+}
+
+export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type EvaluateRulesOptions, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SECRET_MASK, SECRET_REF_PREFIX, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, SeedLoaderService, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, collectSecretFields, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, evaluateValidationRules, isSecretRef, legalNextStates, makeSecretRef, needsPriorRecord, noopHookMetricsRecorder, parseFQN, parseSecretRef, toTitleCase, validateRecord, wrapDeclarativeHook };