@objectstack/runtime 3.2.1 → 3.2.3

package/dist/index.d.cts

@@ -1,6 +1,8 @@
 import { ObjectKernel, IHttpServer, ObjectKernelConfig, Plugin, PluginContext, RouteHandler, Middleware } from '@objectstack/core';
 export * from '@objectstack/core';
 export { ObjectKernel } from '@objectstack/core';
+import { ISeedLoaderService, IDataEngine, IMetadataService } from '@objectstack/spec/contracts';
+import { SeedLoaderRequest, SeedLoaderResult, ObjectDependencyGraph, Dataset, SeedLoaderConfigInput } from '@objectstack/spec/data';
 import { MiddlewareConfig, MiddlewareType } from '@objectstack/spec/system';
 export { RestApiPluginConfig, RestServer, RouteEntry, RouteGroupBuilder, RouteManager, createRestApiPlugin } from '@objectstack/rest';
 
@@ -92,6 +94,50 @@ declare class AppPlugin implements Plugin {
     start: (ctx: PluginContext) => Promise<void>;
 }
 
+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 DatasetSchema mode
+ * - Actionable error reporting
+ */
+declare class SeedLoaderService implements ISeedLoaderService {
+    private engine;
+    private metadata;
+    private logger;
+    constructor(engine: IDataEngine, metadata: IMetadataService, logger: Logger);
+    load(request: SeedLoaderRequest): Promise<SeedLoaderResult>;
+    buildDependencyGraph(objectNames: string[]): Promise<ObjectDependencyGraph>;
+    validate(datasets: Dataset[], config?: SeedLoaderConfigInput): Promise<SeedLoaderResult>;
+    private loadDataset;
+    private resolveFromDatabase;
+    private resolveDeferredUpdates;
+    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;
+}
+
 interface DispatcherPluginConfig {
     /**
      * API path prefix for all endpoints.
@@ -486,7 +532,7 @@ declare class HttpDispatcher {
      * Handles Analytics requests
      * path: sub-path after /analytics/
      */
-    handleAnalytics(path: string, method: string, body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    handleAnalytics(path: string, method: string, body: any, _context: HttpProtocolContext): Promise<HttpDispatcherResult>;
     /**
      * Handles i18n requests
      * path: sub-path after /i18n/
@@ -680,4 +726,4 @@ declare class MiddlewareManager {
     createCompositeMiddleware(): Middleware;
 }
 
-export { AppPlugin, type DispatcherPluginConfig, DriverPlugin, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, MiddlewareManager, Runtime, type RuntimeConfig, createDispatcherPlugin };
+export { AppPlugin, type DispatcherPluginConfig, DriverPlugin, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, MiddlewareManager, Runtime, type RuntimeConfig, SeedLoaderService, createDispatcherPlugin };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { ObjectKernel, IHttpServer, ObjectKernelConfig, Plugin, PluginContext, RouteHandler, Middleware } from '@objectstack/core';
 export * from '@objectstack/core';
 export { ObjectKernel } from '@objectstack/core';
+import { ISeedLoaderService, IDataEngine, IMetadataService } from '@objectstack/spec/contracts';
+import { SeedLoaderRequest, SeedLoaderResult, ObjectDependencyGraph, Dataset, SeedLoaderConfigInput } from '@objectstack/spec/data';
 import { MiddlewareConfig, MiddlewareType } from '@objectstack/spec/system';
 export { RestApiPluginConfig, RestServer, RouteEntry, RouteGroupBuilder, RouteManager, createRestApiPlugin } from '@objectstack/rest';
 
@@ -92,6 +94,50 @@ declare class AppPlugin implements Plugin {
     start: (ctx: PluginContext) => Promise<void>;
 }
 
+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 DatasetSchema mode
+ * - Actionable error reporting
+ */
+declare class SeedLoaderService implements ISeedLoaderService {
+    private engine;
+    private metadata;
+    private logger;
+    constructor(engine: IDataEngine, metadata: IMetadataService, logger: Logger);
+    load(request: SeedLoaderRequest): Promise<SeedLoaderResult>;
+    buildDependencyGraph(objectNames: string[]): Promise<ObjectDependencyGraph>;
+    validate(datasets: Dataset[], config?: SeedLoaderConfigInput): Promise<SeedLoaderResult>;
+    private loadDataset;
+    private resolveFromDatabase;
+    private resolveDeferredUpdates;
+    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;
+}
+
 interface DispatcherPluginConfig {
     /**
      * API path prefix for all endpoints.
@@ -486,7 +532,7 @@ declare class HttpDispatcher {
      * Handles Analytics requests
      * path: sub-path after /analytics/
      */
-    handleAnalytics(path: string, method: string, body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    handleAnalytics(path: string, method: string, body: any, _context: HttpProtocolContext): Promise<HttpDispatcherResult>;
     /**
      * Handles i18n requests
      * path: sub-path after /i18n/
@@ -680,4 +726,4 @@ declare class MiddlewareManager {
     createCompositeMiddleware(): Middleware;
 }
 
-export { AppPlugin, type DispatcherPluginConfig, DriverPlugin, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, MiddlewareManager, Runtime, type RuntimeConfig, createDispatcherPlugin };
+export { AppPlugin, type DispatcherPluginConfig, DriverPlugin, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, MiddlewareManager, Runtime, type RuntimeConfig, SeedLoaderService, createDispatcherPlugin };