@objectstack/spec 0.6.0 → 0.7.1

package/dist/system/service-registry.zod.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopeInfoSchema = exports.ScopeConfigSchema = exports.ServiceFactoryRegistrationSchema = exports.ServiceRegistryConfigSchema = exports.ServiceMetadataSchema = exports.ServiceScopeType = void 0;
+const zod_1 = require("zod");
+/**
+ * Service Registry Protocol
+ *
+ * Zod schemas for service registry data structures.
+ * These schemas align with the IServiceRegistry contract interface.
+ *
+ * Following ObjectStack "Zod First" principle - all data structures
+ * must have Zod schemas for runtime validation and JSON Schema generation.
+ *
+ * Note: IServiceRegistry itself is a runtime interface (methods only),
+ * so it correctly remains a TypeScript interface. This file contains
+ * schemas for configuration and metadata related to service registry.
+ */
+// ============================================================================
+// Service Metadata Schemas
+// ============================================================================
+/**
+ * Service Scope Type Enum
+ * Different service scoping strategies
+ */
+exports.ServiceScopeType = zod_1.z.enum([
+    'singleton', // Single instance shared across the application
+    'transient', // New instance created each time
+    'scoped', // Instance per scope (request, session, transaction, etc.)
+]).describe('Service scope type');
+/**
+ * Service Metadata Schema
+ * Metadata about a registered service
+ *
+ * @example
+ * {
+ *   "name": "database",
+ *   "scope": "singleton",
+ *   "type": "IDataEngine",
+ *   "registeredAt": 1706659200000
+ * }
+ */
+exports.ServiceMetadataSchema = zod_1.z.object({
+    /**
+     * Service name (unique identifier)
+     */
+    name: zod_1.z.string().min(1).describe('Unique service name identifier'),
+    /**
+     * Service scope type
+     */
+    scope: exports.ServiceScopeType.optional().default('singleton')
+        .describe('Service scope type'),
+    /**
+     * Service type or interface name (optional)
+     */
+    type: zod_1.z.string().optional().describe('Service type or interface name'),
+    /**
+     * Registration timestamp (Unix milliseconds)
+     */
+    registeredAt: zod_1.z.number().int().optional()
+        .describe('Unix timestamp in milliseconds when service was registered'),
+    /**
+     * Additional metadata
+     */
+    metadata: zod_1.z.record(zod_1.z.any()).optional()
+        .describe('Additional service-specific metadata'),
+});
+// ============================================================================
+// Service Registry Configuration Schemas
+// ============================================================================
+/**
+ * Service Registry Configuration Schema
+ * Configuration for service registry behavior
+ *
+ * @example
+ * {
+ *   "strictMode": true,
+ *   "allowOverwrite": false,
+ *   "enableLogging": true,
+ *   "scopeTypes": ["singleton", "transient", "request", "session"]
+ * }
+ */
+exports.ServiceRegistryConfigSchema = zod_1.z.object({
+    /**
+     * Strict mode: throw errors on invalid operations
+     * @default true
+     */
+    strictMode: zod_1.z.boolean().optional().default(true)
+        .describe('Throw errors on invalid operations (duplicate registration, service not found, etc.)'),
+    /**
+     * Allow overwriting existing services
+     * @default false
+     */
+    allowOverwrite: zod_1.z.boolean().optional().default(false)
+        .describe('Allow overwriting existing service registrations'),
+    /**
+     * Enable logging for service operations
+     * @default false
+     */
+    enableLogging: zod_1.z.boolean().optional().default(false)
+        .describe('Enable logging for service registration and retrieval'),
+    /**
+     * Custom scope types (beyond singleton, transient, scoped)
+     * @default ['singleton', 'transient', 'scoped']
+     */
+    scopeTypes: zod_1.z.array(zod_1.z.string()).optional()
+        .describe('Supported scope types'),
+    /**
+     * Maximum number of services (prevent memory leaks)
+     */
+    maxServices: zod_1.z.number().int().min(1).optional()
+        .describe('Maximum number of services that can be registered'),
+});
+// ============================================================================
+// Service Factory Schemas
+// ============================================================================
+/**
+ * Service Factory Registration Schema
+ * Configuration for registering a service factory
+ *
+ * @example
+ * {
+ *   "name": "logger",
+ *   "scope": "singleton",
+ *   "factoryType": "sync"
+ * }
+ */
+exports.ServiceFactoryRegistrationSchema = zod_1.z.object({
+    /**
+     * Service name (unique identifier)
+     */
+    name: zod_1.z.string().min(1).describe('Unique service name identifier'),
+    /**
+     * Service scope type
+     */
+    scope: exports.ServiceScopeType.optional().default('singleton')
+        .describe('Service scope type'),
+    /**
+     * Factory type (sync or async)
+     */
+    factoryType: zod_1.z.enum(['sync', 'async']).optional().default('sync')
+        .describe('Whether factory is synchronous or asynchronous'),
+    /**
+     * Whether this is a singleton (cache factory result)
+     */
+    singleton: zod_1.z.boolean().optional().default(true)
+        .describe('Whether to cache the factory result (singleton pattern)'),
+});
+// ============================================================================
+// Scoped Service Schemas
+// ============================================================================
+/**
+ * Scope Configuration Schema
+ * Configuration for creating a new scope
+ *
+ * @example
+ * {
+ *   "scopeType": "request",
+ *   "scopeId": "req-12345",
+ *   "metadata": {
+ *     "userId": "user-123",
+ *     "requestId": "req-12345"
+ *   }
+ * }
+ */
+exports.ScopeConfigSchema = zod_1.z.object({
+    /**
+     * Type of scope (request, session, transaction, etc.)
+     */
+    scopeType: zod_1.z.string().describe('Type of scope'),
+    /**
+     * Scope identifier (optional, auto-generated if not provided)
+     */
+    scopeId: zod_1.z.string().optional().describe('Unique scope identifier'),
+    /**
+     * Scope metadata (context information)
+     */
+    metadata: zod_1.z.record(zod_1.z.any()).optional()
+        .describe('Scope-specific context metadata'),
+});
+/**
+ * Scope Info Schema
+ * Information about an active scope
+ *
+ * @example
+ * {
+ *   "scopeId": "req-12345",
+ *   "scopeType": "request",
+ *   "createdAt": 1706659200000,
+ *   "serviceCount": 5,
+ *   "metadata": {
+ *     "userId": "user-123"
+ *   }
+ * }
+ */
+exports.ScopeInfoSchema = zod_1.z.object({
+    /**
+     * Scope identifier
+     */
+    scopeId: zod_1.z.string().describe('Unique scope identifier'),
+    /**
+     * Type of scope
+     */
+    scopeType: zod_1.z.string().describe('Type of scope'),
+    /**
+     * Creation timestamp (Unix milliseconds)
+     */
+    createdAt: zod_1.z.number().int().describe('Unix timestamp in milliseconds when scope was created'),
+    /**
+     * Number of services in this scope
+     */
+    serviceCount: zod_1.z.number().int().min(0).optional()
+        .describe('Number of services registered in this scope'),
+    /**
+     * Scope metadata
+     */
+    metadata: zod_1.z.record(zod_1.z.any()).optional()
+        .describe('Scope-specific context metadata'),
+});

package/dist/system/startup-orchestrator.zod.d.ts

@@ -0,0 +1,376 @@
+import { z } from 'zod';
+/**
+ * Startup Orchestrator Protocol
+ *
+ * Zod schemas for plugin startup orchestration data structures.
+ * These schemas align with the IStartupOrchestrator contract interface.
+ *
+ * Following ObjectStack "Zod First" principle - all data structures
+ * must have Zod schemas for runtime validation and JSON Schema generation.
+ */
+/**
+ * Startup Options Schema
+ * Configuration for plugin startup orchestration
+ *
+ * @example
+ * {
+ *   "timeout": 30000,
+ *   "rollbackOnFailure": true,
+ *   "healthCheck": false,
+ *   "parallel": false
+ * }
+ */
+export declare const StartupOptionsSchema: z.ZodObject<{
+    /**
+     * Maximum time (ms) to wait for each plugin to start
+     * @default 30000 (30 seconds)
+     */
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    /**
+     * Whether to rollback (destroy) already-started plugins on failure
+     * @default true
+     */
+    rollbackOnFailure: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    /**
+     * Whether to run health checks after startup
+     * @default false
+     */
+    healthCheck: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    /**
+     * Whether to run plugins in parallel (if dependencies allow)
+     * @default false (sequential startup)
+     */
+    parallel: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    /**
+     * Custom context to pass to plugin lifecycle methods
+     */
+    context: z.ZodOptional<z.ZodAny>;
+}, "strip", z.ZodTypeAny, {
+    timeout: number;
+    rollbackOnFailure: boolean;
+    healthCheck: boolean;
+    parallel: boolean;
+    context?: any;
+}, {
+    timeout?: number | undefined;
+    context?: any;
+    rollbackOnFailure?: boolean | undefined;
+    healthCheck?: boolean | undefined;
+    parallel?: boolean | undefined;
+}>;
+export type StartupOptions = z.infer<typeof StartupOptionsSchema>;
+export type StartupOptionsInput = z.input<typeof StartupOptionsSchema>;
+/**
+ * Health Status Schema
+ * Health status for a plugin
+ *
+ * @example
+ * {
+ *   "healthy": true,
+ *   "timestamp": 1706659200000,
+ *   "details": {
+ *     "databaseConnected": true,
+ *     "memoryUsage": 45.2
+ *   }
+ * }
+ */
+export declare const HealthStatusSchema: z.ZodObject<{
+    /**
+     * Whether the plugin is healthy
+     */
+    healthy: z.ZodBoolean;
+    /**
+     * Health check timestamp (Unix milliseconds)
+     */
+    timestamp: z.ZodNumber;
+    /**
+     * Optional health details (plugin-specific)
+     */
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    /**
+     * Optional error message if unhealthy
+     */
+    message: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    timestamp: number;
+    healthy: boolean;
+    message?: string | undefined;
+    details?: Record<string, any> | undefined;
+}, {
+    timestamp: number;
+    healthy: boolean;
+    message?: string | undefined;
+    details?: Record<string, any> | undefined;
+}>;
+export type HealthStatus = z.infer<typeof HealthStatusSchema>;
+/**
+ * Plugin Startup Result Schema
+ * Result of a single plugin startup operation
+ *
+ * @example
+ * {
+ *   "plugin": { "name": "crm-plugin", "version": "1.0.0" },
+ *   "success": true,
+ *   "duration": 1250,
+ *   "health": {
+ *     "healthy": true,
+ *     "timestamp": 1706659200000
+ *   }
+ * }
+ */
+export declare const PluginStartupResultSchema: z.ZodObject<{
+    /**
+     * Plugin that was started
+     */
+    plugin: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>;
+    /**
+     * Whether startup was successful
+     */
+    success: z.ZodBoolean;
+    /**
+     * Time taken to start (milliseconds)
+     */
+    duration: z.ZodNumber;
+    /**
+     * Error if startup failed
+     */
+    error: z.ZodOptional<z.ZodType<Error, z.ZodTypeDef, Error>>;
+    /**
+     * Health status after startup (if healthCheck enabled)
+     */
+    health: z.ZodOptional<z.ZodObject<{
+        /**
+         * Whether the plugin is healthy
+         */
+        healthy: z.ZodBoolean;
+        /**
+         * Health check timestamp (Unix milliseconds)
+         */
+        timestamp: z.ZodNumber;
+        /**
+         * Optional health details (plugin-specific)
+         */
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        /**
+         * Optional error message if unhealthy
+         */
+        message: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        timestamp: number;
+        healthy: boolean;
+        message?: string | undefined;
+        details?: Record<string, any> | undefined;
+    }, {
+        timestamp: number;
+        healthy: boolean;
+        message?: string | undefined;
+        details?: Record<string, any> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    success: boolean;
+    duration: number;
+    plugin: {
+        name: string;
+        version?: string | undefined;
+    } & {
+        [k: string]: unknown;
+    };
+    error?: Error | undefined;
+    health?: {
+        timestamp: number;
+        healthy: boolean;
+        message?: string | undefined;
+        details?: Record<string, any> | undefined;
+    } | undefined;
+}, {
+    success: boolean;
+    duration: number;
+    plugin: {
+        name: string;
+        version?: string | undefined;
+    } & {
+        [k: string]: unknown;
+    };
+    error?: Error | undefined;
+    health?: {
+        timestamp: number;
+        healthy: boolean;
+        message?: string | undefined;
+        details?: Record<string, any> | undefined;
+    } | undefined;
+}>;
+export type PluginStartupResult = z.infer<typeof PluginStartupResultSchema>;
+/**
+ * Startup Orchestration Result Schema
+ * Overall result of orchestrating startup for multiple plugins
+ *
+ * @example
+ * {
+ *   "results": [
+ *     { "plugin": { "name": "plugin1" }, "success": true, "duration": 1200 },
+ *     { "plugin": { "name": "plugin2" }, "success": true, "duration": 850 }
+ *   ],
+ *   "totalDuration": 2050,
+ *   "allSuccessful": true
+ * }
+ */
+export declare const StartupOrchestrationResultSchema: z.ZodObject<{
+    /**
+     * Individual plugin startup results
+     */
+    results: z.ZodArray<z.ZodObject<{
+        /**
+         * Plugin that was started
+         */
+        plugin: z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodOptional<z.ZodString>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            name: z.ZodString;
+            version: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            name: z.ZodString;
+            version: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough">>;
+        /**
+         * Whether startup was successful
+         */
+        success: z.ZodBoolean;
+        /**
+         * Time taken to start (milliseconds)
+         */
+        duration: z.ZodNumber;
+        /**
+         * Error if startup failed
+         */
+        error: z.ZodOptional<z.ZodType<Error, z.ZodTypeDef, Error>>;
+        /**
+         * Health status after startup (if healthCheck enabled)
+         */
+        health: z.ZodOptional<z.ZodObject<{
+            /**
+             * Whether the plugin is healthy
+             */
+            healthy: z.ZodBoolean;
+            /**
+             * Health check timestamp (Unix milliseconds)
+             */
+            timestamp: z.ZodNumber;
+            /**
+             * Optional health details (plugin-specific)
+             */
+            details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+            /**
+             * Optional error message if unhealthy
+             */
+            message: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            timestamp: number;
+            healthy: boolean;
+            message?: string | undefined;
+            details?: Record<string, any> | undefined;
+        }, {
+            timestamp: number;
+            healthy: boolean;
+            message?: string | undefined;
+            details?: Record<string, any> | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        success: boolean;
+        duration: number;
+        plugin: {
+            name: string;
+            version?: string | undefined;
+        } & {
+            [k: string]: unknown;
+        };
+        error?: Error | undefined;
+        health?: {
+            timestamp: number;
+            healthy: boolean;
+            message?: string | undefined;
+            details?: Record<string, any> | undefined;
+        } | undefined;
+    }, {
+        success: boolean;
+        duration: number;
+        plugin: {
+            name: string;
+            version?: string | undefined;
+        } & {
+            [k: string]: unknown;
+        };
+        error?: Error | undefined;
+        health?: {
+            timestamp: number;
+            healthy: boolean;
+            message?: string | undefined;
+            details?: Record<string, any> | undefined;
+        } | undefined;
+    }>, "many">;
+    /**
+     * Total time taken for all plugins (milliseconds)
+     */
+    totalDuration: z.ZodNumber;
+    /**
+     * Whether all plugins started successfully
+     */
+    allSuccessful: z.ZodBoolean;
+    /**
+     * Plugins that were rolled back (if rollbackOnFailure was enabled)
+     */
+    rolledBack: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    results: {
+        success: boolean;
+        duration: number;
+        plugin: {
+            name: string;
+            version?: string | undefined;
+        } & {
+            [k: string]: unknown;
+        };
+        error?: Error | undefined;
+        health?: {
+            timestamp: number;
+            healthy: boolean;
+            message?: string | undefined;
+            details?: Record<string, any> | undefined;
+        } | undefined;
+    }[];
+    totalDuration: number;
+    allSuccessful: boolean;
+    rolledBack?: string[] | undefined;
+}, {
+    results: {
+        success: boolean;
+        duration: number;
+        plugin: {
+            name: string;
+            version?: string | undefined;
+        } & {
+            [k: string]: unknown;
+        };
+        error?: Error | undefined;
+        health?: {
+            timestamp: number;
+            healthy: boolean;
+            message?: string | undefined;
+            details?: Record<string, any> | undefined;
+        } | undefined;
+    }[];
+    totalDuration: number;
+    allSuccessful: boolean;
+    rolledBack?: string[] | undefined;
+}>;
+export type StartupOrchestrationResult = z.infer<typeof StartupOrchestrationResultSchema>;
+//# sourceMappingURL=startup-orchestrator.zod.d.ts.map

package/dist/system/startup-orchestrator.zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-orchestrator.zod.d.ts","sourceRoot":"","sources":["../../src/system/startup-orchestrator.zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AAMH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;OAGG;;IAIH;;;OAGG;;IAIH;;;OAGG;;IAIH;;;OAGG;;IAIH;;OAEG;;;;;;;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMvE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB;IAC7B;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;;;;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAM9D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB;IACpC;;OAEG;;;;;;;;;;;IAMH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;QApEH;;WAEG;;QAGH;;WAEG;;QAGH;;WAEG;;QAGH;;WAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqDH,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAM5E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gCAAgC;IAC3C;;OAEG;;QApDH;;WAEG;;;;;;;;;;;QAMH;;WAEG;;QAGH;;WAEG;;QAGH;;WAEG;;QAGH;;WAEG;;YApEH;;eAEG;;YAGH;;eAEG;;YAGH;;eAEG;;YAGH;;eAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAiFH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC"}