@objectstack/core 0.8.2 → 0.9.1

package/dist/api-registry-plugin.test.js

@@ -0,0 +1,332 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ObjectKernel } from './kernel';
+import { createApiRegistryPlugin } from './api-registry-plugin';
+import { ApiRegistry } from './api-registry';
+describe('API Registry Plugin', () => {
+    let kernel;
+    beforeEach(() => {
+        kernel = new ObjectKernel();
+    });
+    describe('Plugin Registration', () => {
+        it('should register API Registry as a service', async () => {
+            kernel.use(createApiRegistryPlugin());
+            await kernel.bootstrap();
+            const registry = kernel.getService('api-registry');
+            expect(registry).toBeDefined();
+            expect(registry).toBeInstanceOf(ApiRegistry);
+            await kernel.shutdown();
+        });
+        it('should register with custom conflict resolution', async () => {
+            kernel.use(createApiRegistryPlugin({
+                conflictResolution: 'priority',
+                version: '2.0.0',
+            }));
+            await kernel.bootstrap();
+            const registry = kernel.getService('api-registry');
+            const snapshot = registry.getRegistry();
+            expect(snapshot.conflictResolution).toBe('priority');
+            expect(snapshot.version).toBe('2.0.0');
+            await kernel.shutdown();
+        });
+    });
+    describe('Integration with Plugins', () => {
+        it('should allow plugins to register APIs', async () => {
+            kernel.use(createApiRegistryPlugin());
+            const testPlugin = {
+                name: 'test-plugin',
+                init: async (ctx) => {
+                    const registry = ctx.getService('api-registry');
+                    const api = {
+                        id: 'test_api',
+                        name: 'Test API',
+                        type: 'rest',
+                        version: 'v1',
+                        basePath: '/api/test',
+                        endpoints: [
+                            {
+                                id: 'get_test',
+                                method: 'GET',
+                                path: '/api/test/hello',
+                                summary: 'Test endpoint',
+                                responses: [
+                                    {
+                                        statusCode: 200,
+                                        description: 'Success',
+                                    },
+                                ],
+                            },
+                        ],
+                    };
+                    registry.registerApi(api);
+                },
+            };
+            kernel.use(testPlugin);
+            await kernel.bootstrap();
+            const registry = kernel.getService('api-registry');
+            const api = registry.getApi('test_api');
+            expect(api).toBeDefined();
+            expect(api?.name).toBe('Test API');
+            expect(api?.endpoints.length).toBe(1);
+            await kernel.shutdown();
+        });
+        it('should allow multiple plugins to register APIs', async () => {
+            kernel.use(createApiRegistryPlugin());
+            const plugin1 = {
+                name: 'plugin-1',
+                init: async (ctx) => {
+                    const registry = ctx.getService('api-registry');
+                    registry.registerApi({
+                        id: 'api1',
+                        name: 'API 1',
+                        type: 'rest',
+                        version: 'v1',
+                        basePath: '/api/plugin1',
+                        endpoints: [
+                            {
+                                id: 'endpoint1',
+                                method: 'GET',
+                                path: '/api/plugin1/data',
+                                responses: [],
+                            },
+                        ],
+                    });
+                },
+            };
+            const plugin2 = {
+                name: 'plugin-2',
+                init: async (ctx) => {
+                    const registry = ctx.getService('api-registry');
+                    registry.registerApi({
+                        id: 'api2',
+                        name: 'API 2',
+                        type: 'graphql',
+                        version: 'v1',
+                        basePath: '/graphql',
+                        endpoints: [
+                            {
+                                id: 'query',
+                                path: '/graphql',
+                                responses: [],
+                            },
+                        ],
+                    });
+                },
+            };
+            kernel.use(plugin1);
+            kernel.use(plugin2);
+            await kernel.bootstrap();
+            const registry = kernel.getService('api-registry');
+            const stats = registry.getStats();
+            expect(stats.totalApis).toBe(2);
+            expect(stats.apisByType.rest).toBe(1);
+            expect(stats.apisByType.graphql).toBe(1);
+            await kernel.shutdown();
+        });
+        it('should support API discovery across plugins', async () => {
+            kernel.use(createApiRegistryPlugin());
+            const dataPlugin = {
+                name: 'data-plugin',
+                init: async (ctx) => {
+                    const registry = ctx.getService('api-registry');
+                    registry.registerApi({
+                        id: 'customer_api',
+                        name: 'Customer API',
+                        type: 'rest',
+                        version: 'v1',
+                        basePath: '/api/v1/customers',
+                        endpoints: [],
+                        metadata: {
+                            status: 'active',
+                            tags: ['crm', 'data'],
+                        },
+                    });
+                    registry.registerApi({
+                        id: 'product_api',
+                        name: 'Product API',
+                        type: 'rest',
+                        version: 'v1',
+                        basePath: '/api/v1/products',
+                        endpoints: [],
+                        metadata: {
+                            status: 'active',
+                            tags: ['inventory', 'data'],
+                        },
+                    });
+                },
+            };
+            const analyticsPlugin = {
+                name: 'analytics-plugin',
+                init: async (ctx) => {
+                    const registry = ctx.getService('api-registry');
+                    registry.registerApi({
+                        id: 'analytics_api',
+                        name: 'Analytics API',
+                        type: 'rest',
+                        version: 'v1',
+                        basePath: '/api/v1/analytics',
+                        endpoints: [],
+                        metadata: {
+                            status: 'beta',
+                            tags: ['analytics', 'reporting'],
+                        },
+                    });
+                },
+            };
+            kernel.use(dataPlugin);
+            kernel.use(analyticsPlugin);
+            await kernel.bootstrap();
+            const registry = kernel.getService('api-registry');
+            // Find all data APIs
+            const dataApis = registry.findApis({ tags: ['data'] });
+            expect(dataApis.total).toBe(2);
+            // Find active APIs
+            const activeApis = registry.findApis({ status: 'active' });
+            expect(activeApis.total).toBe(2);
+            // Find CRM APIs
+            const crmApis = registry.findApis({ tags: ['crm'] });
+            expect(crmApis.total).toBe(1);
+            expect(crmApis.apis[0].id).toBe('customer_api');
+            await kernel.shutdown();
+        });
+        it('should handle route conflicts based on strategy', async () => {
+            kernel.use(createApiRegistryPlugin({
+                conflictResolution: 'priority',
+            }));
+            const corePlugin = {
+                name: 'core-plugin',
+                init: async (ctx) => {
+                    const registry = ctx.getService('api-registry');
+                    registry.registerApi({
+                        id: 'core_api',
+                        name: 'Core API',
+                        type: 'rest',
+                        version: 'v1',
+                        basePath: '/api',
+                        endpoints: [
+                            {
+                                id: 'core_endpoint',
+                                method: 'GET',
+                                path: '/api/data/:object',
+                                priority: 900, // High priority
+                                summary: 'Core data endpoint',
+                                responses: [],
+                            },
+                        ],
+                    });
+                },
+            };
+            const pluginOverride = {
+                name: 'plugin-override',
+                init: async (ctx) => {
+                    const registry = ctx.getService('api-registry');
+                    registry.registerApi({
+                        id: 'plugin_api',
+                        name: 'Plugin API',
+                        type: 'rest',
+                        version: 'v1',
+                        basePath: '/api',
+                        endpoints: [
+                            {
+                                id: 'plugin_endpoint',
+                                method: 'GET',
+                                path: '/api/data/:object',
+                                priority: 300, // Lower priority
+                                summary: 'Plugin data endpoint',
+                                responses: [],
+                            },
+                        ],
+                    });
+                },
+            };
+            kernel.use(corePlugin);
+            kernel.use(pluginOverride);
+            await kernel.bootstrap();
+            const registry = kernel.getService('api-registry');
+            const result = registry.findEndpointByRoute('GET', '/api/data/:object');
+            // Core API should win due to higher priority
+            expect(result?.api.id).toBe('core_api');
+            expect(result?.endpoint.id).toBe('core_endpoint');
+            await kernel.shutdown();
+        });
+        it('should support cleanup on plugin unload', async () => {
+            kernel.use(createApiRegistryPlugin());
+            const dynamicPlugin = {
+                name: 'dynamic-plugin',
+                init: async (ctx) => {
+                    const registry = ctx.getService('api-registry');
+                    registry.registerApi({
+                        id: 'dynamic_api',
+                        name: 'Dynamic API',
+                        type: 'rest',
+                        version: 'v1',
+                        basePath: '/api/dynamic',
+                        endpoints: [
+                            {
+                                id: 'test',
+                                method: 'GET',
+                                path: '/api/dynamic/test',
+                                responses: [],
+                            },
+                        ],
+                    });
+                },
+                destroy: async () => {
+                    // In a real scenario, this would use ctx to access registry
+                    // For now, we'll test the registry's unregister capability
+                },
+            };
+            kernel.use(dynamicPlugin);
+            await kernel.bootstrap();
+            const registry = kernel.getService('api-registry');
+            expect(registry.getApi('dynamic_api')).toBeDefined();
+            // Unregister the API
+            registry.unregisterApi('dynamic_api');
+            expect(registry.getApi('dynamic_api')).toBeUndefined();
+            await kernel.shutdown();
+        });
+    });
+    describe('API Registry Lifecycle', () => {
+        it('should be available during plugin start phase', async () => {
+            kernel.use(createApiRegistryPlugin());
+            let registryAvailable = false;
+            const testPlugin = {
+                name: 'test-plugin',
+                init: async () => {
+                    // Init phase
+                },
+                start: async (ctx) => {
+                    // Start phase - registry should be available
+                    const registry = ctx.getService('api-registry');
+                    registryAvailable = registry !== undefined;
+                },
+            };
+            kernel.use(testPlugin);
+            await kernel.bootstrap();
+            expect(registryAvailable).toBe(true);
+            await kernel.shutdown();
+        });
+        it('should provide consistent registry across all plugins', async () => {
+            kernel.use(createApiRegistryPlugin());
+            let registry1;
+            let registry2;
+            const plugin1 = {
+                name: 'plugin-1',
+                init: async (ctx) => {
+                    registry1 = ctx.getService('api-registry');
+                },
+            };
+            const plugin2 = {
+                name: 'plugin-2',
+                init: async (ctx) => {
+                    registry2 = ctx.getService('api-registry');
+                },
+            };
+            kernel.use(plugin1);
+            kernel.use(plugin2);
+            await kernel.bootstrap();
+            // Same registry instance should be shared
+            expect(registry1).toBe(registry2);
+            await kernel.shutdown();
+        });
+    });
+});

package/dist/api-registry.d.ts

@@ -0,0 +1,259 @@
+import type { ApiRegistry as ApiRegistryType, ApiRegistryEntry, ApiRegistryEntryInput, ApiEndpointRegistration, ConflictResolutionStrategy, ApiDiscoveryQuery, ApiDiscoveryResponse } from '@objectstack/spec/api';
+import type { Logger } from '@objectstack/spec/contracts';
+/**
+ * API Registry Service
+ *
+ * Central registry for managing API endpoints across different protocols.
+ * Provides endpoint registration, discovery, and conflict resolution.
+ *
+ * **Features:**
+ * - Multi-protocol support (REST, GraphQL, OData, WebSocket, etc.)
+ * - Route conflict detection with configurable resolution strategies
+ * - RBAC permission integration
+ * - Dynamic schema linking with ObjectQL references
+ * - Plugin API registration
+ *
+ * **Architecture Alignment:**
+ * - Kubernetes: Service Discovery & API Server
+ * - AWS API Gateway: Unified API Management
+ * - Kong Gateway: Plugin-based API Management
+ *
+ * @example
+ * ```typescript
+ * const registry = new ApiRegistry(logger, 'priority');
+ *
+ * // Register an API
+ * registry.registerApi({
+ *   id: 'customer_api',
+ *   name: 'Customer API',
+ *   type: 'rest',
+ *   version: 'v1',
+ *   basePath: '/api/v1/customers',
+ *   endpoints: [...]
+ * });
+ *
+ * // Discover APIs
+ * const apis = registry.findApis({ type: 'rest', status: 'active' });
+ *
+ * // Get registry snapshot
+ * const snapshot = registry.getRegistry();
+ * ```
+ */
+export declare class ApiRegistry {
+    private apis;
+    private endpoints;
+    private routes;
+    private apisByType;
+    private apisByTag;
+    private apisByStatus;
+    private conflictResolution;
+    private logger;
+    private version;
+    private updatedAt;
+    constructor(logger: Logger, conflictResolution?: ConflictResolutionStrategy, version?: string);
+    /**
+     * Register an API with its endpoints
+     *
+     * @param api - API registry entry
+     * @throws Error if API already registered or route conflicts detected
+     */
+    registerApi(api: ApiRegistryEntryInput): void;
+    /**
+     * Unregister an API and all its endpoints
+     *
+     * @param apiId - API identifier
+     */
+    unregisterApi(apiId: string): void;
+    /**
+     * Register a single endpoint
+     *
+     * @param apiId - API identifier
+     * @param endpoint - Endpoint registration
+     * @throws Error if route conflict detected
+     */
+    private registerEndpoint;
+    /**
+     * Unregister a single endpoint
+     *
+     * @param apiId - API identifier
+     * @param endpointId - Endpoint identifier
+     */
+    private unregisterEndpoint;
+    /**
+     * Register a route with conflict detection
+     *
+     * @param apiId - API identifier
+     * @param endpoint - Endpoint registration
+     * @throws Error if route conflict detected (based on strategy)
+     */
+    private registerRoute;
+    /**
+     * Handle route conflict based on resolution strategy
+     *
+     * @param routeKey - Route key
+     * @param apiId - New API identifier
+     * @param endpoint - New endpoint
+     * @param existingRoute - Existing route registration
+     * @param newPriority - New endpoint priority
+     * @throws Error if strategy is 'error'
+     */
+    private handleRouteConflict;
+    /**
+     * Generate a unique route key for conflict detection
+     *
+     * NOTE: This implementation uses exact string matching for route conflict detection.
+     * It works well for static paths but has limitations with parameterized routes.
+     * For example, `/api/users/:id` and `/api/users/:userId` will NOT be detected as conflicts
+     * even though they are semantically identical parameterized patterns. Similarly,
+     * `/api/:resource/list` and `/api/:entity/list` would also not be detected as conflicting.
+     *
+     * For more advanced conflict detection (e.g., path-to-regexp pattern matching),
+     * consider integrating with your routing library's conflict detection mechanism.
+     *
+     * @param endpoint - Endpoint registration
+     * @returns Route key (e.g., "GET:/api/v1/customers/:id")
+     */
+    private getRouteKey;
+    /**
+     * Validate endpoint registration
+     *
+     * @param endpoint - Endpoint to validate
+     * @param apiId - API identifier (for error messages)
+     * @throws Error if endpoint is invalid
+     */
+    private validateEndpoint;
+    /**
+     * Get an API by ID
+     *
+     * @param apiId - API identifier
+     * @returns API registry entry or undefined
+     */
+    getApi(apiId: string): ApiRegistryEntry | undefined;
+    /**
+     * Get all registered APIs
+     *
+     * @returns Array of all APIs
+     */
+    getAllApis(): ApiRegistryEntry[];
+    /**
+     * Find APIs matching query criteria
+     *
+     * Performance optimized with auxiliary indices for O(1) lookups on type, tags, and status.
+     *
+     * @param query - Discovery query parameters
+     * @returns Matching APIs
+     */
+    findApis(query: ApiDiscoveryQuery): ApiDiscoveryResponse;
+    /**
+     * Get endpoint by API ID and endpoint ID
+     *
+     * @param apiId - API identifier
+     * @param endpointId - Endpoint identifier
+     * @returns Endpoint registration or undefined
+     */
+    getEndpoint(apiId: string, endpointId: string): ApiEndpointRegistration | undefined;
+    /**
+     * Find endpoint by route (method + path)
+     *
+     * @param method - HTTP method
+     * @param path - URL path
+     * @returns Endpoint registration or undefined
+     */
+    findEndpointByRoute(method: string, path: string): {
+        api: ApiRegistryEntry;
+        endpoint: ApiEndpointRegistration;
+    } | undefined;
+    /**
+     * Get complete registry snapshot
+     *
+     * @returns Current registry state
+     */
+    getRegistry(): ApiRegistryType;
+    /**
+     * Clear all registered APIs
+     *
+     * **⚠️ SAFETY WARNING:**
+     * This method clears all registered APIs and should be used with caution.
+     *
+     * **Usage Restrictions:**
+     * - In production environments (NODE_ENV=production), a `force: true` parameter is required
+     * - Primarily intended for testing and development hot-reload scenarios
+     *
+     * @param options - Clear options
+     * @param options.force - Force clear in production environment (default: false)
+     * @throws Error if called in production without force flag
+     *
+     * @example Safe usage in tests
+     * ```typescript
+     * beforeEach(() => {
+     *   registry.clear(); // OK in test environment
+     * });
+     * ```
+     *
+     * @example Usage in production (requires explicit force)
+     * ```typescript
+     * // In production, explicit force is required
+     * registry.clear({ force: true });
+     * ```
+     */
+    clear(options?: {
+        force?: boolean;
+    }): void;
+    /**
+     * Get registry statistics
+     *
+     * @returns Registry statistics
+     */
+    getStats(): {
+        totalApis: number;
+        totalEndpoints: number;
+        totalRoutes: number;
+        apisByType: Record<string, number>;
+        endpointsByApi: Record<string, number>;
+    };
+    /**
+     * Update auxiliary indices when an API is registered
+     *
+     * @param api - API entry to index
+     * @private
+     * @internal
+     */
+    private updateIndices;
+    /**
+     * Remove API from auxiliary indices when unregistered
+     *
+     * @param api - API entry to remove from indices
+     * @private
+     * @internal
+     */
+    private removeFromIndices;
+    /**
+     * Helper to ensure an index set exists and return it
+     *
+     * @param map - Index map
+     * @param key - Index key
+     * @returns The Set for this key (created if needed)
+     * @private
+     * @internal
+     */
+    private ensureIndexSet;
+    /**
+     * Helper to remove an ID from an index set and clean up empty sets
+     *
+     * @param map - Index map
+     * @param key - Index key
+     * @param id - API ID to remove
+     * @private
+     * @internal
+     */
+    private removeFromIndexSet;
+    /**
+     * Check if running in production environment
+     *
+     * @returns true if NODE_ENV is 'production'
+     * @private
+     * @internal
+     */
+    private isProductionEnvironment;
+}
+//# sourceMappingURL=api-registry.d.ts.map

package/dist/api-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-registry.d.ts","sourceRoot":"","sources":["../src/api-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,IAAI,eAAe,EAC9B,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAA4C;IACxD,OAAO,CAAC,SAAS,CAA8E;IAC/F,OAAO,CAAC,MAAM,CAAiF;IAG/F,OAAO,CAAC,UAAU,CAAuC;IACzD,OAAO,CAAC,SAAS,CAAuC;IACxD,OAAO,CAAC,YAAY,CAAuC;IAE3D,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;gBAGxB,MAAM,EAAE,MAAM,EACd,kBAAkB,GAAE,0BAAoC,EACxD,OAAO,GAAE,MAAgB;IAQ3B;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,qBAAqB,GAAG,IAAI;IAiC7C;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAqBlC;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAmBrB;;;;;;;;;OASG;IACH,OAAO,CAAC,mBAAmB;IA8E3B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,WAAW;IAKnB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAInD;;;;OAIG;IACH,UAAU,IAAI,gBAAgB,EAAE;IAIhC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,oBAAoB;IAsGxD;;;;;;OAMG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS;IAKnF;;;;;;OAMG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;QACjD,GAAG,EAAE,gBAAgB,CAAC;QACtB,QAAQ,EAAE,uBAAuB,CAAC;KACnC,GAAG,SAAS;IAkBb;;;;OAIG;IACH,WAAW,IAAI,eAAe;IAwC9B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,KAAK,CAAC,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI;IA4B9C;;;;OAIG;IACH,QAAQ,IAAI;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACxC;IAsBD;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAerB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAStB;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;CAGhC"}