@objectstack/spec 2.0.4 → 2.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/dist/contracts/index.d.mts +2 -2
  2. package/dist/contracts/index.d.ts +2 -2
  3. package/dist/contracts/index.js.map +1 -1
  4. package/dist/data/index.d.mts +2 -2
  5. package/dist/data/index.d.ts +2 -2
  6. package/dist/data/index.js +482 -453
  7. package/dist/data/index.js.map +1 -1
  8. package/dist/data/index.mjs +481 -453
  9. package/dist/data/index.mjs.map +1 -1
  10. package/dist/{driver.zod-DddW_4lJ.d.mts → driver.zod-DnOPgUGi.d.mts} +430 -1
  11. package/dist/{driver.zod-BJHWEbwG.d.ts → driver.zod-E3C6n0W-.d.ts} +430 -1
  12. package/dist/index-B-u2mVKn.d.mts +1965 -0
  13. package/dist/{index-yvEIvpa3.d.ts → index-BPhGHW32.d.ts} +4 -2
  14. package/dist/index-BjxWBAB_.d.ts +1965 -0
  15. package/dist/index-CDN6TRx9.d.mts +765 -0
  16. package/dist/index-CDN6TRx9.d.ts +765 -0
  17. package/dist/{index-Cp6xnrOM.d.mts → index-D-tf4nDV.d.mts} +4 -2
  18. package/dist/{index-DOuMlF5h.d.ts → index-DyawwLFZ.d.ts} +31 -2
  19. package/dist/{index-DPlvQwlz.d.mts → index-E1mP_eoE.d.mts} +31 -2
  20. package/dist/index.d.mts +38 -799
  21. package/dist/index.d.ts +38 -799
  22. package/dist/index.js +8585 -8556
  23. package/dist/index.js.map +1 -1
  24. package/dist/index.mjs +8585 -8556
  25. package/dist/index.mjs.map +1 -1
  26. package/dist/kernel/index.d.mts +1 -1
  27. package/dist/kernel/index.d.ts +1 -1
  28. package/dist/kernel/index.js +23 -0
  29. package/dist/kernel/index.js.map +1 -1
  30. package/dist/kernel/index.mjs +22 -0
  31. package/dist/kernel/index.mjs.map +1 -1
  32. package/dist/security/index.d.mts +2 -0
  33. package/dist/security/index.d.ts +2 -0
  34. package/dist/security/index.js +666 -0
  35. package/dist/security/index.js.map +1 -0
  36. package/dist/security/index.mjs +616 -0
  37. package/dist/security/index.mjs.map +1 -0
  38. package/json-schema/data/BaseEngineOptions.json +49 -0
  39. package/json-schema/data/DataEngineAggregateOptions.json +42 -0
  40. package/json-schema/data/DataEngineAggregateRequest.json +42 -0
  41. package/json-schema/data/DataEngineBatchRequest.json +294 -0
  42. package/json-schema/data/DataEngineCountOptions.json +42 -0
  43. package/json-schema/data/DataEngineCountRequest.json +42 -0
  44. package/json-schema/data/DataEngineDeleteOptions.json +42 -0
  45. package/json-schema/data/DataEngineDeleteRequest.json +42 -0
  46. package/json-schema/data/DataEngineFindOneRequest.json +42 -0
  47. package/json-schema/data/DataEngineFindRequest.json +42 -0
  48. package/json-schema/data/DataEngineInsertOptions.json +42 -0
  49. package/json-schema/data/DataEngineInsertRequest.json +42 -0
  50. package/json-schema/data/DataEngineQueryOptions.json +42 -0
  51. package/json-schema/data/DataEngineRequest.json +588 -0
  52. package/json-schema/data/DataEngineUpdateOptions.json +42 -0
  53. package/json-schema/data/DataEngineUpdateRequest.json +42 -0
  54. package/json-schema/kernel/ExecutionContext.json +43 -0
  55. package/package.json +6 -1
  56. package/dist/index-C8xlxqpA.d.ts +0 -767
  57. package/dist/index-wFiQRott.d.mts +0 -767
@@ -1,767 +0,0 @@
1
- import { Q as QueryAST, a as FieldSchema } from './field.zod-DuaF0Lcl.js';
2
- 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-BJHWEbwG.js';
3
- import { z } from 'zod';
4
-
5
- /**
6
- * Logger Contract
7
- *
8
- * Defines the interface for logging in ObjectStack.
9
- * Compatible with both browser console and structured logging systems.
10
- */
11
- interface Logger {
12
- /**
13
- * Log a debug message
14
- * @param message - The message to log
15
- * @param meta - Optional metadata to include
16
- */
17
- debug(message: string, meta?: Record<string, any>): void;
18
- /**
19
- * Log an informational message
20
- * @param message - The message to log
21
- * @param meta - Optional metadata to include
22
- */
23
- info(message: string, meta?: Record<string, any>): void;
24
- /**
25
- * Log a warning message
26
- * @param message - The message to log
27
- * @param meta - Optional metadata to include
28
- */
29
- warn(message: string, meta?: Record<string, any>): void;
30
- /**
31
- * Log an error message
32
- * @param message - The message to log
33
- * @param error - Optional error object
34
- * @param meta - Optional metadata to include
35
- */
36
- error(message: string, error?: Error, meta?: Record<string, any>): void;
37
- /**
38
- * Log a fatal error message
39
- * @param message - The message to log
40
- * @param error - Optional error object
41
- * @param meta - Optional metadata to include
42
- */
43
- fatal?(message: string, error?: Error, meta?: Record<string, any>): void;
44
- /**
45
- * Create a child logger with additional context
46
- * @param context - Context to add to all logs from this child
47
- */
48
- child?(context: Record<string, any>): Logger;
49
- /**
50
- * Set trace context for distributed tracing
51
- * @param traceId - Trace identifier
52
- * @param spanId - Span identifier
53
- */
54
- withTrace?(traceId: string, spanId?: string): Logger;
55
- /**
56
- * Compatibility method for console.log usage
57
- * @param message - The message to log
58
- * @param args - Additional arguments
59
- */
60
- log?(message: string, ...args: any[]): void;
61
- /**
62
- * Cleanup resources (close file streams, etc.)
63
- * Should be called when the logger is no longer needed
64
- */
65
- destroy?(): Promise<void>;
66
- }
67
-
68
- /**
69
- * IDataEngine - Standard Data Engine Interface
70
- *
71
- * Abstract interface for data persistence capabilities.
72
- * Following the Dependency Inversion Principle - plugins depend on this interface,
73
- * not on concrete database implementations.
74
- *
75
- * Aligned with 'src/data/data-engine.zod.ts' in @objectstack/spec.
76
- */
77
- interface IDataEngine {
78
- find(objectName: string, query?: DataEngineQueryOptions): Promise<any[]>;
79
- findOne(objectName: string, query?: DataEngineQueryOptions): Promise<any>;
80
- insert(objectName: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
81
- update(objectName: string, data: any, options?: DataEngineUpdateOptions): Promise<any>;
82
- delete(objectName: string, options?: DataEngineDeleteOptions): Promise<any>;
83
- count(objectName: string, query?: DataEngineCountOptions): Promise<number>;
84
- aggregate(objectName: string, query: DataEngineAggregateOptions): Promise<any[]>;
85
- /**
86
- * Vector Search (AI/RAG)
87
- */
88
- vectorFind?(objectName: string, vector: number[], options?: {
89
- filter?: any;
90
- limit?: number;
91
- select?: string[];
92
- threshold?: number;
93
- }): Promise<any[]>;
94
- /**
95
- * Batch Operations (Transactional)
96
- */
97
- batch?(requests: DataEngineRequest[], options?: {
98
- transaction?: boolean;
99
- }): Promise<any[]>;
100
- /**
101
- * Execute raw command (Escape hatch)
102
- */
103
- execute?(command: any, options?: Record<string, any>): Promise<any>;
104
- }
105
- interface DriverInterface {
106
- name: string;
107
- version: string;
108
- connect(): Promise<void>;
109
- disconnect(): Promise<void>;
110
- find(object: string, query: QueryAST, options?: DriverOptions): Promise<any[]>;
111
- findOne(object: string, query: QueryAST, options?: DriverOptions): Promise<any>;
112
- create(object: string, data: any, options?: DriverOptions): Promise<any>;
113
- update(object: string, id: any, data: any, options?: DriverOptions): Promise<any>;
114
- delete(object: string, id: any, options?: DriverOptions): Promise<any>;
115
- /**
116
- * Bulk & Batch Operations
117
- */
118
- bulkCreate?(object: string, data: any[], options?: DriverOptions): Promise<any>;
119
- updateMany?(object: string, query: QueryAST, data: any, options?: DriverOptions): Promise<any>;
120
- deleteMany?(object: string, query: QueryAST, options?: DriverOptions): Promise<any>;
121
- count?(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
122
- /**
123
- * Raw Execution
124
- */
125
- execute?(command: any, params?: any, options?: DriverOptions): Promise<any>;
126
- }
127
-
128
- /**
129
- * IHttpServer - Standard HTTP Server Interface
130
- *
131
- * Abstract interface for HTTP server capabilities.
132
- * This allows plugins to interact with HTTP servers without knowing
133
- * the underlying implementation (Express, Fastify, Hono, etc.).
134
- *
135
- * Follows Dependency Inversion Principle - plugins depend on this interface,
136
- * not on concrete HTTP framework implementations.
137
- */
138
- /**
139
- * Generic HTTP Request type
140
- * Abstraction over framework-specific request objects
141
- */
142
- interface IHttpRequest {
143
- /** Request path parameters */
144
- params: Record<string, string>;
145
- /** Request query parameters */
146
- query: Record<string, string | string[]>;
147
- /** Request body */
148
- body?: any;
149
- /** Request headers */
150
- headers: Record<string, string | string[]>;
151
- /** HTTP method */
152
- method: string;
153
- /** Request path */
154
- path: string;
155
- }
156
- /**
157
- * Generic HTTP Response type
158
- * Abstraction over framework-specific response objects
159
- */
160
- interface IHttpResponse {
161
- /**
162
- * Send a JSON response
163
- * @param data - Data to send
164
- */
165
- json(data: any): void | Promise<void>;
166
- /**
167
- * Send a text/html response
168
- * @param data - Data to send
169
- */
170
- send(data: string): void | Promise<void>;
171
- /**
172
- * Set HTTP status code
173
- * @param code - HTTP status code
174
- */
175
- status(code: number): IHttpResponse;
176
- /**
177
- * Set response header
178
- * @param name - Header name
179
- * @param value - Header value (string or array of strings for multi-value headers)
180
- */
181
- header(name: string, value: string | string[]): IHttpResponse;
182
- }
183
- /**
184
- * Route handler function
185
- */
186
- type RouteHandler = (req: IHttpRequest, res: IHttpResponse) => void | Promise<void>;
187
- /**
188
- * Middleware function
189
- */
190
- type Middleware = (req: IHttpRequest, res: IHttpResponse, next: () => void | Promise<void>) => void | Promise<void>;
191
- /**
192
- * IHttpServer - HTTP Server capability interface
193
- *
194
- * Defines the contract for HTTP server implementations.
195
- * Concrete implementations (Express, Fastify, Hono) should implement this interface.
196
- */
197
- interface IHttpServer {
198
- /**
199
- * Register a GET route handler
200
- * @param path - Route path (e.g., '/api/users/:id')
201
- * @param handler - Route handler function
202
- */
203
- get(path: string, handler: RouteHandler): void;
204
- /**
205
- * Register a POST route handler
206
- * @param path - Route path
207
- * @param handler - Route handler function
208
- */
209
- post(path: string, handler: RouteHandler): void;
210
- /**
211
- * Register a PUT route handler
212
- * @param path - Route path
213
- * @param handler - Route handler function
214
- */
215
- put(path: string, handler: RouteHandler): void;
216
- /**
217
- * Register a DELETE route handler
218
- * @param path - Route path
219
- * @param handler - Route handler function
220
- */
221
- delete(path: string, handler: RouteHandler): void;
222
- /**
223
- * Register a PATCH route handler
224
- * @param path - Route path
225
- * @param handler - Route handler function
226
- */
227
- patch(path: string, handler: RouteHandler): void;
228
- /**
229
- * Register middleware
230
- * @param path - Optional path to apply middleware to (if omitted, applies globally)
231
- * @param handler - Middleware function
232
- */
233
- use(path: string | Middleware, handler?: Middleware): void;
234
- /**
235
- * Start the HTTP server
236
- * @param port - Port number to listen on
237
- * @returns Promise that resolves when server is ready
238
- */
239
- listen(port: number): Promise<void>;
240
- /**
241
- * Stop the HTTP server
242
- * @returns Promise that resolves when server is stopped
243
- */
244
- close?(): Promise<void>;
245
- }
246
-
247
- /**
248
- * IServiceRegistry - Service Registry Interface
249
- *
250
- * Abstract interface for managing service registration and lookup.
251
- * This provides a single source of truth for all services in the system.
252
- *
253
- * Following the Dependency Inversion Principle - both kernel implementations
254
- * and plugins depend on this interface, not on concrete implementations.
255
- */
256
- interface IServiceRegistry {
257
- /**
258
- * Register a service with a unique name
259
- * @param name - Unique service identifier
260
- * @param service - The service instance to register
261
- * @throws Error if service name is already registered
262
- */
263
- register<T>(name: string, service: T): void;
264
- /**
265
- * Get a registered service by name (synchronous)
266
- * @param name - Service identifier
267
- * @returns The registered service
268
- * @throws Error if service is not found
269
- */
270
- get<T>(name: string): T;
271
- /**
272
- * Get a registered service by name (asynchronous)
273
- * Useful for lazy-loaded or async-initialized services
274
- * @param name - Service identifier
275
- * @param scopeId - Optional scope identifier for scoped services
276
- * @returns Promise resolving to the registered service
277
- * @throws Error if service is not found
278
- */
279
- getAsync<T>(name: string, scopeId?: string): Promise<T>;
280
- /**
281
- * Check if a service is registered
282
- * @param name - Service identifier
283
- * @returns True if service is registered, false otherwise
284
- */
285
- has(name: string): boolean;
286
- /**
287
- * Unregister a service
288
- * @param name - Service identifier
289
- * @returns True if service was unregistered, false if it wasn't registered
290
- */
291
- unregister(name: string): boolean;
292
- /**
293
- * Get all registered service names
294
- * @returns Array of service names
295
- */
296
- getServiceNames?(): string[];
297
- /**
298
- * Clear all registered services
299
- * Useful for cleanup in tests or during shutdown
300
- */
301
- clear?(): void;
302
- }
303
- /**
304
- * BasicServiceRegistry - Simple synchronous implementation
305
- * Used by ObjectKernel for basic service management
306
- */
307
- interface IBasicServiceRegistry extends IServiceRegistry {
308
- }
309
- /**
310
- * AdvancedServiceRegistry - Enhanced implementation with additional features
311
- * Used by ObjectKernel for advanced service management
312
- */
313
- interface IAdvancedServiceRegistry extends IServiceRegistry {
314
- /**
315
- * Register a factory function that creates services on-demand
316
- * @param name - Service identifier
317
- * @param factory - Factory function that creates the service
318
- * @param singleton - If true, factory is called once and result is cached
319
- */
320
- registerFactory?<T>(name: string, factory: () => T | Promise<T>, singleton?: boolean): void;
321
- /**
322
- * Register a scoped service (per-request, per-session, etc.)
323
- * @param name - Service identifier
324
- * @param factory - Factory function that creates the service
325
- * @param scopeType - Type of scope ('request', 'session', 'transaction', etc.)
326
- */
327
- registerScoped?<T>(name: string, factory: (scopeId: string) => T | Promise<T>, scopeType: string): void;
328
- /**
329
- * Create a new scope for scoped services
330
- * @param scopeType - Type of scope
331
- * @returns Scope identifier
332
- */
333
- createScope?(scopeType: string): string;
334
- /**
335
- * Dispose a scope and cleanup scoped services
336
- * @param scopeId - Scope identifier
337
- */
338
- disposeScope?(scopeId: string): Promise<void>;
339
- }
340
-
341
- /**
342
- * IPluginValidator - Plugin Validator Interface
343
- *
344
- * Abstract interface for validating plugins before registration and startup.
345
- * Extracted from PluginLoader to follow Single Responsibility Principle.
346
- */
347
- /**
348
- * Validation result for a plugin
349
- */
350
- interface ValidationResult {
351
- /**
352
- * Whether the plugin passed validation
353
- */
354
- valid: boolean;
355
- /**
356
- * Validation errors (if any)
357
- */
358
- errors?: Array<{
359
- field: string;
360
- message: string;
361
- code?: string;
362
- }>;
363
- /**
364
- * Validation warnings (non-fatal issues)
365
- */
366
- warnings?: Array<{
367
- field: string;
368
- message: string;
369
- code?: string;
370
- }>;
371
- }
372
- /**
373
- * Plugin metadata for validation
374
- */
375
- interface Plugin {
376
- /**
377
- * Unique plugin identifier
378
- */
379
- name: string;
380
- /**
381
- * Plugin version (semver)
382
- */
383
- version?: string;
384
- /**
385
- * Plugin dependencies
386
- */
387
- dependencies?: string[];
388
- /**
389
- * Plugin initialization function
390
- */
391
- init?: (context: any) => void | Promise<void>;
392
- /**
393
- * Plugin startup function
394
- */
395
- start?: (context: any) => void | Promise<void>;
396
- /**
397
- * Plugin destruction function
398
- */
399
- destroy?: (context: any) => void | Promise<void>;
400
- /**
401
- * Plugin signature for verification (optional)
402
- */
403
- signature?: string;
404
- /**
405
- * Additional plugin metadata
406
- */
407
- [key: string]: any;
408
- }
409
- /**
410
- * IPluginValidator - Plugin validation interface
411
- */
412
- interface IPluginValidator {
413
- /**
414
- * Validate a plugin object structure
415
- * @param plugin - Plugin to validate
416
- * @returns Validation result
417
- */
418
- validate(plugin: unknown): ValidationResult;
419
- /**
420
- * Validate plugin version format (semver)
421
- * @param version - Version string to validate
422
- * @returns True if version is valid, false otherwise
423
- */
424
- validateVersion(version: string): boolean;
425
- /**
426
- * Validate plugin cryptographic signature (optional)
427
- * Used for plugin security verification
428
- * @param plugin - Plugin to validate
429
- * @returns Promise resolving to true if signature is valid
430
- */
431
- validateSignature?(plugin: Plugin): Promise<boolean>;
432
- /**
433
- * Validate plugin dependencies are satisfied
434
- * @param plugin - Plugin to validate
435
- * @param registry - Map of already registered plugins
436
- * @throws Error if dependencies are not satisfied
437
- */
438
- validateDependencies(plugin: Plugin, registry: Map<string, Plugin>): void;
439
- /**
440
- * Validate plugin has required lifecycle methods
441
- * @param plugin - Plugin to validate
442
- * @returns True if plugin has valid lifecycle methods
443
- */
444
- validateLifecycle?(plugin: Plugin): boolean;
445
- }
446
-
447
- /**
448
- * IStartupOrchestrator - Startup Orchestrator Interface
449
- *
450
- * Abstract interface for orchestrating plugin startup with advanced features:
451
- * - Timeout handling
452
- * - Rollback on failure
453
- * - Health checks
454
- * - Startup metrics
455
- *
456
- * Extracted from PluginLoader to follow Single Responsibility Principle.
457
- */
458
- /**
459
- * Startup options for orchestration
460
- */
461
- interface StartupOptions {
462
- /**
463
- * Maximum time (ms) to wait for each plugin to start
464
- * @default 30000 (30 seconds)
465
- */
466
- timeout?: number;
467
- /**
468
- * Whether to rollback (destroy) already-started plugins on failure
469
- * @default true
470
- */
471
- rollbackOnFailure?: boolean;
472
- /**
473
- * Whether to run health checks after startup
474
- * @default false
475
- */
476
- healthCheck?: boolean;
477
- /**
478
- * Whether to run plugins in parallel (if dependencies allow)
479
- * @default false (sequential startup)
480
- */
481
- parallel?: boolean;
482
- /**
483
- * Custom context to pass to plugin lifecycle methods
484
- */
485
- context?: any;
486
- }
487
- /**
488
- * Plugin startup result
489
- */
490
- interface PluginStartupResult {
491
- /**
492
- * Plugin that was started
493
- */
494
- plugin: Plugin;
495
- /**
496
- * Whether startup was successful
497
- */
498
- success: boolean;
499
- /**
500
- * Time taken to start (milliseconds)
501
- */
502
- duration: number;
503
- /**
504
- * Error if startup failed
505
- */
506
- error?: Error;
507
- /**
508
- * Health status after startup (if healthCheck enabled)
509
- */
510
- health?: HealthStatus;
511
- }
512
- /**
513
- * Health status for a plugin
514
- */
515
- interface HealthStatus {
516
- /**
517
- * Whether the plugin is healthy
518
- */
519
- healthy: boolean;
520
- /**
521
- * Health check timestamp
522
- */
523
- timestamp: number;
524
- /**
525
- * Optional health details
526
- */
527
- details?: Record<string, any>;
528
- /**
529
- * Optional error message if unhealthy
530
- */
531
- message?: string;
532
- }
533
- /**
534
- * IStartupOrchestrator - Plugin startup orchestration interface
535
- */
536
- interface IStartupOrchestrator {
537
- /**
538
- * Orchestrate startup of multiple plugins
539
- * Handles timeout, rollback, and health checks
540
- * @param plugins - Array of plugins to start (in dependency order)
541
- * @param options - Startup options
542
- * @returns Promise resolving to startup results for each plugin
543
- */
544
- orchestrateStartup(plugins: Plugin[], options: StartupOptions): Promise<PluginStartupResult[]>;
545
- /**
546
- * Rollback (destroy) a set of plugins
547
- * Used when startup fails and rollback is enabled
548
- * @param startedPlugins - Plugins that were successfully started
549
- * @returns Promise that resolves when rollback is complete
550
- */
551
- rollback(startedPlugins: Plugin[]): Promise<void>;
552
- /**
553
- * Check health of a single plugin
554
- * @param plugin - Plugin to check
555
- * @returns Promise resolving to health status
556
- */
557
- checkHealth(plugin: Plugin): Promise<HealthStatus>;
558
- /**
559
- * Wait for a plugin to start with timeout
560
- * @param plugin - Plugin to start
561
- * @param context - Plugin context
562
- * @param timeoutMs - Maximum time to wait (milliseconds)
563
- * @returns Promise resolving when plugin starts or rejecting on timeout
564
- */
565
- startWithTimeout?(plugin: Plugin, context: any, timeoutMs: number): Promise<void>;
566
- }
567
-
568
- /**
569
- * IPluginLifecycleEvents - Typed Plugin Lifecycle Events
570
- *
571
- * Type-safe event definitions for plugin and kernel lifecycle.
572
- * Provides strong typing for event emitters and listeners.
573
- *
574
- * This replaces the generic Map<string, any[]> approach with typed events.
575
- */
576
- /**
577
- * Plugin lifecycle event types and their payloads
578
- */
579
- interface IPluginLifecycleEvents {
580
- /**
581
- * Emitted when kernel is ready (all plugins initialized)
582
- * Payload: []
583
- */
584
- 'kernel:ready': [];
585
- /**
586
- * Emitted when kernel is shutting down
587
- * Payload: []
588
- */
589
- 'kernel:shutdown': [];
590
- /**
591
- * Emitted before kernel initialization starts
592
- * Payload: []
593
- */
594
- 'kernel:before-init': [];
595
- /**
596
- * Emitted after kernel initialization completes
597
- * Payload: [duration: number (milliseconds)]
598
- */
599
- 'kernel:after-init': [duration: number];
600
- /**
601
- * Emitted when a plugin is registered
602
- * Payload: [pluginName: string]
603
- */
604
- 'plugin:registered': [pluginName: string];
605
- /**
606
- * Emitted before a plugin's init method is called
607
- * Payload: [pluginName: string]
608
- */
609
- 'plugin:before-init': [pluginName: string];
610
- /**
611
- * Emitted when a plugin has been initialized
612
- * Payload: [pluginName: string]
613
- */
614
- 'plugin:init': [pluginName: string];
615
- /**
616
- * Emitted after a plugin's init method completes
617
- * Payload: [pluginName: string, duration: number (milliseconds)]
618
- */
619
- 'plugin:after-init': [pluginName: string, duration: number];
620
- /**
621
- * Emitted before a plugin's start method is called
622
- * Payload: [pluginName: string]
623
- */
624
- 'plugin:before-start': [pluginName: string];
625
- /**
626
- * Emitted when a plugin has started successfully
627
- * Payload: [pluginName: string, duration: number (milliseconds)]
628
- */
629
- 'plugin:started': [pluginName: string, duration: number];
630
- /**
631
- * Emitted after a plugin's start method completes
632
- * Payload: [pluginName: string, duration: number (milliseconds)]
633
- */
634
- 'plugin:after-start': [pluginName: string, duration: number];
635
- /**
636
- * Emitted before a plugin's destroy method is called
637
- * Payload: [pluginName: string]
638
- */
639
- 'plugin:before-destroy': [pluginName: string];
640
- /**
641
- * Emitted when a plugin has been destroyed
642
- * Payload: [pluginName: string]
643
- */
644
- 'plugin:destroyed': [pluginName: string];
645
- /**
646
- * Emitted after a plugin's destroy method completes
647
- * Payload: [pluginName: string, duration: number (milliseconds)]
648
- */
649
- 'plugin:after-destroy': [pluginName: string, duration: number];
650
- /**
651
- * Emitted when a plugin encounters an error
652
- * Payload: [pluginName: string, error: Error, phase: 'init' | 'start' | 'destroy']
653
- */
654
- 'plugin:error': [pluginName: string, error: Error, phase: 'init' | 'start' | 'destroy'];
655
- /**
656
- * Emitted when a service is registered
657
- * Payload: [serviceName: string]
658
- */
659
- 'service:registered': [serviceName: string];
660
- /**
661
- * Emitted when a service is unregistered
662
- * Payload: [serviceName: string]
663
- */
664
- 'service:unregistered': [serviceName: string];
665
- /**
666
- * Emitted when a hook is registered
667
- * Payload: [hookName: string, handlerCount: number]
668
- */
669
- 'hook:registered': [hookName: string, handlerCount: number];
670
- /**
671
- * Emitted when a hook is triggered
672
- * Payload: [hookName: string, args: any[]]
673
- */
674
- 'hook:triggered': [hookName: string, args: any[]];
675
- }
676
- /**
677
- * Type-safe event emitter interface
678
- * Provides compile-time type checking for event names and payloads
679
- */
680
- interface ITypedEventEmitter<Events extends Record<string, any[]>> {
681
- /**
682
- * Register an event listener
683
- * @param event - Event name (type-checked)
684
- * @param handler - Event handler (type-checked against event payload)
685
- */
686
- on<K extends keyof Events>(event: K, handler: (...args: Events[K]) => void | Promise<void>): void;
687
- /**
688
- * Unregister an event listener
689
- * @param event - Event name (type-checked)
690
- * @param handler - Event handler to remove
691
- */
692
- off<K extends keyof Events>(event: K, handler: (...args: Events[K]) => void | Promise<void>): void;
693
- /**
694
- * Emit an event with type-checked payload
695
- * @param event - Event name (type-checked)
696
- * @param args - Event payload (type-checked)
697
- */
698
- emit<K extends keyof Events>(event: K, ...args: Events[K]): Promise<void>;
699
- /**
700
- * Register a one-time event listener
701
- * @param event - Event name (type-checked)
702
- * @param handler - Event handler (type-checked against event payload)
703
- */
704
- once?<K extends keyof Events>(event: K, handler: (...args: Events[K]) => void | Promise<void>): void;
705
- /**
706
- * Get the number of listeners for an event
707
- * @param event - Event name
708
- * @returns Number of registered listeners
709
- */
710
- listenerCount?<K extends keyof Events>(event: K): number;
711
- /**
712
- * Remove all listeners for an event (or all events if not specified)
713
- * @param event - Optional event name
714
- */
715
- removeAllListeners?<K extends keyof Events>(event?: K): void;
716
- }
717
-
718
- type DataField = z.infer<typeof FieldSchema>;
719
- type DataObject = z.infer<typeof ObjectSchema>;
720
- /**
721
- * Interface for Data Definition Language (DDL) operations.
722
- * Drivers should implement this to support automatic migrations.
723
- */
724
- interface ISchemaDriver {
725
- createCollection(objectName: string, schema?: DataObject): Promise<void>;
726
- dropCollection(objectName: string): Promise<void>;
727
- addColumn(objectName: string, fieldName: string, field: DataField): Promise<void>;
728
- modifyColumn(objectName: string, fieldName: string, field: DataField): Promise<void>;
729
- dropColumn(objectName: string, fieldName: string): Promise<void>;
730
- createIndex(objectName: string, indexName: string, fields: string[]): Promise<void>;
731
- dropIndex(objectName: string, indexName: string): Promise<void>;
732
- executeRaw(statement: string): Promise<any>;
733
- }
734
-
735
- /**
736
- * ObjectStack Contracts
737
- *
738
- * Core interface definitions following "Protocol First" principle.
739
- * All interfaces should be defined in @objectstack/spec to avoid circular dependencies.
740
- */
741
-
742
- type index_DriverInterface = DriverInterface;
743
- type index_HealthStatus = HealthStatus;
744
- type index_IAdvancedServiceRegistry = IAdvancedServiceRegistry;
745
- type index_IBasicServiceRegistry = IBasicServiceRegistry;
746
- type index_IDataEngine = IDataEngine;
747
- type index_IHttpRequest = IHttpRequest;
748
- type index_IHttpResponse = IHttpResponse;
749
- type index_IHttpServer = IHttpServer;
750
- type index_IPluginLifecycleEvents = IPluginLifecycleEvents;
751
- type index_IPluginValidator = IPluginValidator;
752
- type index_ISchemaDriver = ISchemaDriver;
753
- type index_IServiceRegistry = IServiceRegistry;
754
- type index_IStartupOrchestrator = IStartupOrchestrator;
755
- type index_ITypedEventEmitter<Events extends Record<string, any[]>> = ITypedEventEmitter<Events>;
756
- type index_Logger = Logger;
757
- type index_Middleware = Middleware;
758
- type index_Plugin = Plugin;
759
- type index_PluginStartupResult = PluginStartupResult;
760
- type index_RouteHandler = RouteHandler;
761
- type index_StartupOptions = StartupOptions;
762
- type index_ValidationResult = ValidationResult;
763
- declare namespace index {
764
- export type { index_DriverInterface as DriverInterface, index_HealthStatus as HealthStatus, index_IAdvancedServiceRegistry as IAdvancedServiceRegistry, index_IBasicServiceRegistry as IBasicServiceRegistry, index_IDataEngine as IDataEngine, index_IHttpRequest as IHttpRequest, index_IHttpResponse as IHttpResponse, index_IHttpServer as IHttpServer, index_IPluginLifecycleEvents as IPluginLifecycleEvents, index_IPluginValidator as IPluginValidator, index_ISchemaDriver as ISchemaDriver, index_IServiceRegistry as IServiceRegistry, index_IStartupOrchestrator as IStartupOrchestrator, index_ITypedEventEmitter as ITypedEventEmitter, index_Logger as Logger, index_Middleware as Middleware, index_Plugin as Plugin, index_PluginStartupResult as PluginStartupResult, index_RouteHandler as RouteHandler, index_StartupOptions as StartupOptions, index_ValidationResult as ValidationResult };
765
- }
766
-
767
- export { type DriverInterface as D, type HealthStatus as H, type IDataEngine as I, type Logger as L, type Middleware as M, type Plugin as P, type RouteHandler as R, type StartupOptions as S, type ValidationResult as V, type IHttpRequest as a, 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 };