@objectstack/spec 2.0.6 → 2.0.7

package/dist/{index-BjxWBAB_.d.ts → index-CmY8tgpL.d.ts}

@@ -1,5 +1,5 @@
 import { Q as QueryAST, a as FieldSchema } from './field.zod-DuaF0Lcl.js';
-import { D as DataEngineQueryOptions, a as DataEngineInsertOptions, b as DataEngineUpdateOptions, c as DataEngineDeleteOptions, d as DataEngineCountOptions, e as DataEngineAggregateOptions, f as DataEngineRequest, g as DriverOptions, O as ObjectSchema } from './driver.zod-E3C6n0W-.js';
+import { D as DataEngineQueryOptions, a as DataEngineInsertOptions, b as DataEngineUpdateOptions, c as DataEngineDeleteOptions, d as DataEngineCountOptions, e as DataEngineAggregateOptions, f as DataEngineRequest, g as DriverOptions, h as DriverCapabilities, O as ObjectSchema } from './driver.zod-B3Q0oLlF.js';
 import { z } from 'zod';
 
 /**
@@ -125,6 +125,126 @@ interface DriverInterface {
     execute?(command: any, params?: any, options?: DriverOptions): Promise<any>;
 }
 
+/**
+ * IDataDriver - Comprehensive Database Driver Interface
+ *
+ * Pure TypeScript interface for all storage adapters (Postgres, Mongo, Excel, Salesforce).
+ * Mirrors the capabilities described in `data/driver.zod.ts` (DriverInterfaceSchema) but
+ * expressed as a TypeScript interface for type-safe implementation contracts.
+ *
+ * This is the contract that all ObjectStack database drivers MUST implement.
+ * Use `DriverCapabilitiesSchema` / `DriverConfigSchema` from `data/driver.zod.ts` for
+ * runtime capability detection and configuration validation.
+ *
+ * @see DriverCapabilitiesSchema for runtime capability flags
+ * @see DriverConfigSchema for driver configuration validation
+ */
+interface IDataDriver {
+    /** Driver unique name (e.g., 'postgresql', 'mongodb', 'rest_api') */
+    readonly name: string;
+    /** Driver version */
+    readonly version: string;
+    /** Capabilities descriptor */
+    readonly supports: DriverCapabilities;
+    /** Initialize connection pool or authenticate */
+    connect(): Promise<void>;
+    /** Close connections and cleanup resources */
+    disconnect(): Promise<void>;
+    /** Check connection health */
+    checkHealth(): Promise<boolean>;
+    /** Get connection pool statistics (optional) */
+    getPoolStats?(): {
+        total: number;
+        idle: number;
+        active: number;
+        waiting: number;
+    } | undefined;
+    /**
+     * Execute a raw command/query native to the driver.
+     *
+     * @param command - Raw command (SQL string, shell command, or API payload)
+     * @param parameters - Bound parameters for safe execution
+     * @param options - Driver options (transaction context, timeout)
+     * @returns Raw result from the driver
+     */
+    execute(command: unknown, parameters?: unknown[], options?: DriverOptions): Promise<unknown>;
+    /**
+     * Find multiple records matching the structured query.
+     * MUST return `id` as string. MUST NOT return implementation details like `_id`.
+     */
+    find(object: string, query: QueryAST, options?: DriverOptions): Promise<Record<string, unknown>[]>;
+    /**
+     * Stream records matching the structured query.
+     * Optimized for large datasets to avoid memory overflow.
+     * Returns an AsyncIterable or ReadableStream.
+     */
+    findStream(object: string, query: QueryAST, options?: DriverOptions): unknown;
+    /**
+     * Find a single record by query.
+     * MUST return `id` as string. MUST NOT return implementation details like `_id`.
+     */
+    findOne(object: string, query: QueryAST, options?: DriverOptions): Promise<Record<string, unknown> | null>;
+    /**
+     * Create a new record.
+     * MUST return `id` as string. MUST NOT return implementation details like `_id`.
+     */
+    create(object: string, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>>;
+    /**
+     * Update an existing record by ID.
+     * MUST return `id` as string. MUST NOT return implementation details like `_id`.
+     */
+    update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>>;
+    /**
+     * Upsert (Update or Insert) a record.
+     */
+    upsert(object: string, data: Record<string, unknown>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, unknown>>;
+    /**
+     * Delete a record by ID.
+     * @returns True if deleted, false if not found.
+     */
+    delete(object: string, id: string | number, options?: DriverOptions): Promise<boolean>;
+    /**
+     * Count records matching a query.
+     */
+    count(object: string, query?: QueryAST, options?: DriverOptions): Promise<number>;
+    /** Create multiple records in a single batch */
+    bulkCreate(object: string, dataArray: Record<string, unknown>[], options?: DriverOptions): Promise<Record<string, unknown>[]>;
+    /** Update multiple records in a single batch */
+    bulkUpdate(object: string, updates: Array<{
+        id: string | number;
+        data: Record<string, unknown>;
+    }>, options?: DriverOptions): Promise<Record<string, unknown>[]>;
+    /** Delete multiple records in a single batch */
+    bulkDelete(object: string, ids: Array<string | number>, options?: DriverOptions): Promise<void>;
+    /** Update multiple records matching a query (optional) */
+    updateMany?(object: string, query: QueryAST, data: Record<string, unknown>, options?: DriverOptions): Promise<number>;
+    /** Delete multiple records matching a query (optional) */
+    deleteMany?(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
+    /**
+     * Begin a new database transaction.
+     * @returns A transaction handle to pass via `options.transaction`.
+     */
+    beginTransaction(options?: {
+        isolationLevel?: string;
+    }): Promise<unknown>;
+    /** Commit the transaction */
+    commit(transaction: unknown): Promise<void>;
+    /** Rollback the transaction */
+    rollback(transaction: unknown): Promise<void>;
+    /**
+     * Synchronize the database schema with the Object definition.
+     * Idempotent: creates tables if missing, adds columns, updates indexes.
+     */
+    syncSchema(object: string, schema: unknown, options?: DriverOptions): Promise<void>;
+    /** Drop the underlying table or collection (destructive) */
+    dropTable(object: string, options?: DriverOptions): Promise<void>;
+    /**
+     * Analyze query performance.
+     * Returns execution plan without executing the query (optional).
+     */
+    explain?(object: string, query: QueryAST, options?: DriverOptions): Promise<unknown>;
+}
+
 /**
  * IHttpServer - Standard HTTP Server Interface
  *
@@ -1114,10 +1234,12 @@ interface IStorageService {
 /**
  * IMetadataService - Metadata Service Contract
  *
- * Defines the interface for managing object/field definitions in ObjectStack.
+ * Defines the async interface for managing object/field definitions in ObjectStack.
  * Concrete implementations (SchemaRegistry, Database-backed, etc.)
  * should implement this interface.
  *
+ * All methods are async to support database-backed persistence via datasource.
+ *
  * Follows Dependency Inversion Principle - plugins depend on this interface,
  * not on concrete metadata storage implementations.
  *
@@ -1125,46 +1247,60 @@ interface IStorageService {
  */
 interface IMetadataService {
     /**
-     * Register a metadata item by type
+     * Register/save a metadata item by type
      * @param type - Metadata type (e.g. 'object', 'view', 'flow')
-     * @param definition - The metadata definition to register
+     * @param name - Item name/identifier (snake_case)
+     * @param data - The metadata definition to register
      */
-    register(type: string, definition: unknown): void;
+    register(type: string, name: string, data: unknown): Promise<void>;
     /**
      * Get a metadata item by type and name
      * @param type - Metadata type
      * @param name - Item name/identifier
      * @returns The metadata definition, or undefined if not found
      */
-    get(type: string, name: string): unknown | undefined;
+    get(type: string, name: string): Promise<unknown | undefined>;
     /**
      * List all metadata items of a given type
      * @param type - Metadata type
      * @returns Array of metadata definitions
      */
-    list(type: string): unknown[];
+    list(type: string): Promise<unknown[]>;
+    /**
+     * Unregister/remove a metadata item by type and name
+     * @param type - Metadata type
+     * @param name - Item name/identifier
+     */
+    unregister(type: string, name: string): Promise<void>;
     /**
-     * Unregister a metadata item by type and name
+     * Check if a metadata item exists
      * @param type - Metadata type
      * @param name - Item name/identifier
+     * @returns True if the item exists
+     */
+    exists(type: string, name: string): Promise<boolean>;
+    /**
+     * List all names of metadata items of a given type
+     * @param type - Metadata type
+     * @returns Array of item names
      */
-    unregister(type: string, name: string): void;
+    listNames(type: string): Promise<string[]>;
     /**
      * Convenience: get an object definition by name
      * @param name - Object name (snake_case)
      * @returns The object definition, or undefined if not found
      */
-    getObject(name: string): unknown | undefined;
+    getObject(name: string): Promise<unknown | undefined>;
     /**
      * Convenience: list all object definitions
      * @returns Array of object definitions
      */
-    listObjects(): unknown[];
+    listObjects(): Promise<unknown[]>;
     /**
      * Unregister all metadata items from a specific package
      * @param packageName - The package name whose items should be removed
      */
-    unregisterPackage?(packageName: string): void;
+    unregisterPackage?(packageName: string): Promise<void>;
 }
 
 /**
@@ -1910,6 +2046,7 @@ type index_IAuthService = IAuthService;
 type index_IAutomationService = IAutomationService;
 type index_IBasicServiceRegistry = IBasicServiceRegistry;
 type index_ICacheService = ICacheService;
+type index_IDataDriver = IDataDriver;
 type index_IDataEngine = IDataEngine;
 type index_IGraphQLService = IGraphQLService;
 type index_IHttpRequest = IHttpRequest;
@@ -1959,7 +2096,7 @@ type index_WorkflowStatus = WorkflowStatus;
 type index_WorkflowTransition = WorkflowTransition;
 type index_WorkflowTransitionResult = WorkflowTransitionResult;
 declare namespace index {
-  export type { index_AIMessage as AIMessage, index_AIRequestOptions as AIRequestOptions, index_AIResult as AIResult, index_AnalyticsQuery as AnalyticsQuery, index_AnalyticsResult as AnalyticsResult, index_AuthResult as AuthResult, index_AuthSession as AuthSession, index_AuthUser as AuthUser, index_AutomationContext as AutomationContext, index_AutomationResult as AutomationResult, index_CacheStats as CacheStats, index_CubeMeta as CubeMeta, index_DriverInterface as DriverInterface, index_GraphQLRequest as GraphQLRequest, index_GraphQLResponse as GraphQLResponse, index_HealthStatus as HealthStatus, index_IAIService as IAIService, index_IAdvancedServiceRegistry as IAdvancedServiceRegistry, index_IAnalyticsService as IAnalyticsService, index_IAuthService as IAuthService, index_IAutomationService as IAutomationService, index_IBasicServiceRegistry as IBasicServiceRegistry, index_ICacheService as ICacheService, index_IDataEngine as IDataEngine, index_IGraphQLService as IGraphQLService, index_IHttpRequest as IHttpRequest, index_IHttpResponse as IHttpResponse, index_IHttpServer as IHttpServer, index_II18nService as II18nService, index_IJobService as IJobService, index_IMetadataService as IMetadataService, index_INotificationService as INotificationService, index_IPluginLifecycleEvents as IPluginLifecycleEvents, index_IPluginValidator as IPluginValidator, index_IQueueService as IQueueService, index_IRealtimeService as IRealtimeService, index_ISchemaDriver as ISchemaDriver, index_ISearchService as ISearchService, index_IServiceRegistry as IServiceRegistry, index_IStartupOrchestrator as IStartupOrchestrator, index_IStorageService as IStorageService, index_ITypedEventEmitter as ITypedEventEmitter, index_IUIService as IUIService, index_IWorkflowService as IWorkflowService, index_JobExecution as JobExecution, index_JobHandler as JobHandler, index_JobSchedule as JobSchedule, index_Logger as Logger, index_Middleware as Middleware, index_NotificationChannel as NotificationChannel, index_NotificationMessage as NotificationMessage, index_NotificationResult as NotificationResult, index_Plugin as Plugin, index_PluginStartupResult as PluginStartupResult, index_QueueHandler as QueueHandler, index_QueueMessage as QueueMessage, index_QueuePublishOptions as QueuePublishOptions, index_RealtimeEventHandler as RealtimeEventHandler, index_RealtimeEventPayload as RealtimeEventPayload, index_RealtimeSubscriptionOptions as RealtimeSubscriptionOptions, index_RouteHandler as RouteHandler, index_SearchHit as SearchHit, index_SearchOptions as SearchOptions, index_SearchResult as SearchResult, index_StartupOptions as StartupOptions, index_StorageFileInfo as StorageFileInfo, index_StorageUploadOptions as StorageUploadOptions, index_ValidationResult as ValidationResult, index_WorkflowStatus as WorkflowStatus, index_WorkflowTransition as WorkflowTransition, index_WorkflowTransitionResult as WorkflowTransitionResult };
+  export type { index_AIMessage as AIMessage, index_AIRequestOptions as AIRequestOptions, index_AIResult as AIResult, index_AnalyticsQuery as AnalyticsQuery, index_AnalyticsResult as AnalyticsResult, index_AuthResult as AuthResult, index_AuthSession as AuthSession, index_AuthUser as AuthUser, index_AutomationContext as AutomationContext, index_AutomationResult as AutomationResult, index_CacheStats as CacheStats, index_CubeMeta as CubeMeta, index_DriverInterface as DriverInterface, index_GraphQLRequest as GraphQLRequest, index_GraphQLResponse as GraphQLResponse, index_HealthStatus as HealthStatus, index_IAIService as IAIService, index_IAdvancedServiceRegistry as IAdvancedServiceRegistry, index_IAnalyticsService as IAnalyticsService, index_IAuthService as IAuthService, index_IAutomationService as IAutomationService, index_IBasicServiceRegistry as IBasicServiceRegistry, index_ICacheService as ICacheService, index_IDataDriver as IDataDriver, index_IDataEngine as IDataEngine, index_IGraphQLService as IGraphQLService, index_IHttpRequest as IHttpRequest, index_IHttpResponse as IHttpResponse, index_IHttpServer as IHttpServer, index_II18nService as II18nService, index_IJobService as IJobService, index_IMetadataService as IMetadataService, index_INotificationService as INotificationService, index_IPluginLifecycleEvents as IPluginLifecycleEvents, index_IPluginValidator as IPluginValidator, index_IQueueService as IQueueService, index_IRealtimeService as IRealtimeService, index_ISchemaDriver as ISchemaDriver, index_ISearchService as ISearchService, index_IServiceRegistry as IServiceRegistry, index_IStartupOrchestrator as IStartupOrchestrator, index_IStorageService as IStorageService, index_ITypedEventEmitter as ITypedEventEmitter, index_IUIService as IUIService, index_IWorkflowService as IWorkflowService, index_JobExecution as JobExecution, index_JobHandler as JobHandler, index_JobSchedule as JobSchedule, index_Logger as Logger, index_Middleware as Middleware, index_NotificationChannel as NotificationChannel, index_NotificationMessage as NotificationMessage, index_NotificationResult as NotificationResult, index_Plugin as Plugin, index_PluginStartupResult as PluginStartupResult, index_QueueHandler as QueueHandler, index_QueueMessage as QueueMessage, index_QueuePublishOptions as QueuePublishOptions, index_RealtimeEventHandler as RealtimeEventHandler, index_RealtimeEventPayload as RealtimeEventPayload, index_RealtimeSubscriptionOptions as RealtimeSubscriptionOptions, index_RouteHandler as RouteHandler, index_SearchHit as SearchHit, index_SearchOptions as SearchOptions, index_SearchResult as SearchResult, index_StartupOptions as StartupOptions, index_StorageFileInfo as StorageFileInfo, index_StorageUploadOptions as StorageUploadOptions, index_ValidationResult as ValidationResult, index_WorkflowStatus as WorkflowStatus, index_WorkflowTransition as WorkflowTransition, index_WorkflowTransitionResult as WorkflowTransitionResult };
 }
 
-export { type IAnalyticsService as $, type IStorageService as A, type IMetadataService as B, type CacheStats as C, type DriverInterface as D, type AuthUser as E, type AuthSession as F, type AuthResult as G, type HealthStatus as H, type IDataEngine as I, type IAuthService as J, type AutomationContext as K, type Logger as L, type Middleware as M, type NotificationChannel as N, type AutomationResult as O, type Plugin as P, type QueuePublishOptions as Q, type RouteHandler as R, type StartupOptions as S, type IAutomationService as T, type GraphQLRequest as U, type ValidationResult as V, type GraphQLResponse as W, type IGraphQLService as X, type AnalyticsQuery as Y, type AnalyticsResult as Z, type CubeMeta as _, type IHttpRequest as a, type RealtimeEventPayload as a0, type RealtimeEventHandler as a1, type RealtimeSubscriptionOptions as a2, type IRealtimeService as a3, type JobSchedule as a4, type JobHandler as a5, type JobExecution as a6, type IJobService as a7, type AIMessage as a8, type AIRequestOptions as a9, type AIResult as aa, type IAIService as ab, type II18nService as ac, type IUIService as ad, type WorkflowTransition as ae, type WorkflowTransitionResult as af, type WorkflowStatus as ag, type IWorkflowService as ah, type IHttpResponse as b, type IHttpServer as c, type IServiceRegistry as d, type IBasicServiceRegistry as e, type IAdvancedServiceRegistry as f, type IPluginValidator as g, type PluginStartupResult as h, index as i, type IStartupOrchestrator as j, type IPluginLifecycleEvents as k, type ITypedEventEmitter as l, type ISchemaDriver as m, type ICacheService as n, type SearchOptions as o, type SearchHit as p, type SearchResult as q, type ISearchService as r, type QueueMessage as s, type QueueHandler as t, type IQueueService as u, type NotificationMessage as v, type NotificationResult as w, type INotificationService as x, type StorageUploadOptions as y, type StorageFileInfo as z };
+export { type CubeMeta as $, type StorageFileInfo as A, type IStorageService as B, type CacheStats as C, type DriverInterface as D, type IMetadataService as E, type AuthUser as F, type AuthSession as G, type HealthStatus as H, type IDataEngine as I, type AuthResult as J, type IAuthService as K, type Logger as L, type Middleware as M, type NotificationChannel as N, type AutomationContext as O, type Plugin as P, type QueuePublishOptions as Q, type RouteHandler as R, type StartupOptions as S, type AutomationResult as T, type IAutomationService as U, type ValidationResult as V, type GraphQLRequest as W, type GraphQLResponse as X, type IGraphQLService as Y, type AnalyticsQuery as Z, type AnalyticsResult as _, type IDataDriver as a, type IAnalyticsService as a0, type RealtimeEventPayload as a1, type RealtimeEventHandler as a2, type RealtimeSubscriptionOptions as a3, type IRealtimeService as a4, type JobSchedule as a5, type JobHandler as a6, type JobExecution as a7, type IJobService as a8, type AIMessage as a9, type AIRequestOptions as aa, type AIResult as ab, type IAIService as ac, type II18nService as ad, type IUIService as ae, type WorkflowTransition as af, type WorkflowTransitionResult as ag, type WorkflowStatus as ah, type IWorkflowService as ai, type IHttpRequest as b, type IHttpResponse as c, type IHttpServer as d, type IServiceRegistry as e, type IBasicServiceRegistry as f, type IAdvancedServiceRegistry as g, type IPluginValidator as h, index as i, type PluginStartupResult as j, type IStartupOrchestrator as k, type IPluginLifecycleEvents as l, type ITypedEventEmitter as m, type ISchemaDriver as n, type ICacheService as o, type SearchOptions as p, type SearchHit as q, type SearchResult as r, type ISearchService as s, type QueueMessage as t, type QueueHandler as u, type IQueueService as v, type NotificationMessage as w, type NotificationResult as x, type INotificationService as y, type StorageUploadOptions as z };