@objectstack/core 1.0.4 → 1.0.5

package/dist/api-registry.js

@@ -1,600 +0,0 @@
-import { ApiRegistryEntrySchema } from '@objectstack/spec/api';
-import { getEnv } from './utils/env.js';
-/**
- * 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 class ApiRegistry {
-    constructor(logger, conflictResolution = 'error', version = '1.0.0') {
-        this.apis = new Map();
-        this.endpoints = new Map();
-        this.routes = new Map();
-        // Performance optimization: Auxiliary indices for O(1) lookups
-        this.apisByType = new Map();
-        this.apisByTag = new Map();
-        this.apisByStatus = new Map();
-        this.logger = logger;
-        this.conflictResolution = conflictResolution;
-        this.version = version;
-        this.updatedAt = new Date().toISOString();
-    }
-    /**
-     * Register an API with its endpoints
-     *
-     * @param api - API registry entry
-     * @throws Error if API already registered or route conflicts detected
-     */
-    registerApi(api) {
-        // Check if API already exists
-        if (this.apis.has(api.id)) {
-            throw new Error(`[ApiRegistry] API '${api.id}' already registered`);
-        }
-        // Parse and validate the input using Zod schema
-        const fullApi = ApiRegistryEntrySchema.parse(api);
-        // Validate and register endpoints
-        for (const endpoint of fullApi.endpoints) {
-            this.validateEndpoint(endpoint, fullApi.id);
-        }
-        // Register the API
-        this.apis.set(fullApi.id, fullApi);
-        // Register endpoints
-        for (const endpoint of fullApi.endpoints) {
-            this.registerEndpoint(fullApi.id, endpoint);
-        }
-        // Update auxiliary indices for performance optimization
-        this.updateIndices(fullApi);
-        this.updatedAt = new Date().toISOString();
-        this.logger.info(`API registered: ${fullApi.id}`, {
-            api: fullApi.id,
-            type: fullApi.type,
-            endpointCount: fullApi.endpoints.length,
-        });
-    }
-    /**
-     * Unregister an API and all its endpoints
-     *
-     * @param apiId - API identifier
-     */
-    unregisterApi(apiId) {
-        const api = this.apis.get(apiId);
-        if (!api) {
-            throw new Error(`[ApiRegistry] API '${apiId}' not found`);
-        }
-        // Remove all endpoints
-        for (const endpoint of api.endpoints) {
-            this.unregisterEndpoint(apiId, endpoint.id);
-        }
-        // Remove from auxiliary indices
-        this.removeFromIndices(api);
-        // Remove the API
-        this.apis.delete(apiId);
-        this.updatedAt = new Date().toISOString();
-        this.logger.info(`API unregistered: ${apiId}`);
-    }
-    /**
-     * Register a single endpoint
-     *
-     * @param apiId - API identifier
-     * @param endpoint - Endpoint registration
-     * @throws Error if route conflict detected
-     */
-    registerEndpoint(apiId, endpoint) {
-        const endpointKey = `${apiId}:${endpoint.id}`;
-        // Check if endpoint already registered
-        if (this.endpoints.has(endpointKey)) {
-            throw new Error(`[ApiRegistry] Endpoint '${endpoint.id}' already registered for API '${apiId}'`);
-        }
-        // Register endpoint
-        this.endpoints.set(endpointKey, { api: apiId, endpoint });
-        // Register route if path is defined
-        if (endpoint.path) {
-            this.registerRoute(apiId, endpoint);
-        }
-    }
-    /**
-     * Unregister a single endpoint
-     *
-     * @param apiId - API identifier
-     * @param endpointId - Endpoint identifier
-     */
-    unregisterEndpoint(apiId, endpointId) {
-        const endpointKey = `${apiId}:${endpointId}`;
-        const entry = this.endpoints.get(endpointKey);
-        if (!entry) {
-            return; // Already unregistered
-        }
-        // Unregister route
-        if (entry.endpoint.path) {
-            const routeKey = this.getRouteKey(entry.endpoint);
-            this.routes.delete(routeKey);
-        }
-        // Unregister endpoint
-        this.endpoints.delete(endpointKey);
-    }
-    /**
-     * Register a route with conflict detection
-     *
-     * @param apiId - API identifier
-     * @param endpoint - Endpoint registration
-     * @throws Error if route conflict detected (based on strategy)
-     */
-    registerRoute(apiId, endpoint) {
-        const routeKey = this.getRouteKey(endpoint);
-        const priority = endpoint.priority ?? 100;
-        const existingRoute = this.routes.get(routeKey);
-        if (existingRoute) {
-            // Route conflict detected
-            this.handleRouteConflict(routeKey, apiId, endpoint, existingRoute, priority);
-            return;
-        }
-        // Register route
-        this.routes.set(routeKey, {
-            api: apiId,
-            endpointId: endpoint.id,
-            priority,
-        });
-    }
-    /**
-     * 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'
-     */
-    handleRouteConflict(routeKey, apiId, endpoint, existingRoute, newPriority) {
-        const strategy = this.conflictResolution;
-        switch (strategy) {
-            case 'error':
-                throw new Error(`[ApiRegistry] Route conflict detected: '${routeKey}' is already registered by API '${existingRoute.api}' endpoint '${existingRoute.endpointId}'`);
-            case 'priority':
-                if (newPriority > existingRoute.priority) {
-                    // New endpoint has higher priority, replace
-                    this.logger.warn(`Route conflict: replacing '${routeKey}' (priority ${existingRoute.priority} -> ${newPriority})`, {
-                        oldApi: existingRoute.api,
-                        oldEndpoint: existingRoute.endpointId,
-                        newApi: apiId,
-                        newEndpoint: endpoint.id,
-                    });
-                    this.routes.set(routeKey, {
-                        api: apiId,
-                        endpointId: endpoint.id,
-                        priority: newPriority,
-                    });
-                }
-                else {
-                    // Existing endpoint has higher priority, keep it
-                    this.logger.warn(`Route conflict: keeping existing '${routeKey}' (priority ${existingRoute.priority} >= ${newPriority})`, {
-                        existingApi: existingRoute.api,
-                        existingEndpoint: existingRoute.endpointId,
-                        newApi: apiId,
-                        newEndpoint: endpoint.id,
-                    });
-                }
-                break;
-            case 'first-wins':
-                // Keep existing route
-                this.logger.warn(`Route conflict: keeping first registered '${routeKey}'`, {
-                    existingApi: existingRoute.api,
-                    newApi: apiId,
-                });
-                break;
-            case 'last-wins':
-                // Replace with new route
-                this.logger.warn(`Route conflict: replacing with last registered '${routeKey}'`, {
-                    oldApi: existingRoute.api,
-                    newApi: apiId,
-                });
-                this.routes.set(routeKey, {
-                    api: apiId,
-                    endpointId: endpoint.id,
-                    priority: newPriority,
-                });
-                break;
-            default:
-                throw new Error(`[ApiRegistry] Unknown conflict resolution strategy: ${strategy}`);
-        }
-    }
-    /**
-     * 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")
-     */
-    getRouteKey(endpoint) {
-        const method = endpoint.method || 'ANY';
-        return `${method}:${endpoint.path}`;
-    }
-    /**
-     * Validate endpoint registration
-     *
-     * @param endpoint - Endpoint to validate
-     * @param apiId - API identifier (for error messages)
-     * @throws Error if endpoint is invalid
-     */
-    validateEndpoint(endpoint, apiId) {
-        if (!endpoint.id) {
-            throw new Error(`[ApiRegistry] Endpoint in API '${apiId}' missing 'id' field`);
-        }
-        if (!endpoint.path) {
-            throw new Error(`[ApiRegistry] Endpoint '${endpoint.id}' in API '${apiId}' missing 'path' field`);
-        }
-    }
-    /**
-     * Get an API by ID
-     *
-     * @param apiId - API identifier
-     * @returns API registry entry or undefined
-     */
-    getApi(apiId) {
-        return this.apis.get(apiId);
-    }
-    /**
-     * Get all registered APIs
-     *
-     * @returns Array of all APIs
-     */
-    getAllApis() {
-        return Array.from(this.apis.values());
-    }
-    /**
-     * 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) {
-        let resultIds;
-        // Use indices for performance-optimized filtering
-        // Start with the most restrictive filter to minimize subsequent filtering
-        // Filter by type (using index for O(1) lookup)
-        if (query.type) {
-            const typeIds = this.apisByType.get(query.type);
-            if (!typeIds || typeIds.size === 0) {
-                return { apis: [], total: 0, filters: query };
-            }
-            resultIds = new Set(typeIds);
-        }
-        // Filter by status (using index for O(1) lookup)
-        if (query.status) {
-            const statusIds = this.apisByStatus.get(query.status);
-            if (!statusIds || statusIds.size === 0) {
-                return { apis: [], total: 0, filters: query };
-            }
-            if (resultIds) {
-                // Intersect with previous results
-                resultIds = new Set([...resultIds].filter(id => statusIds.has(id)));
-            }
-            else {
-                resultIds = new Set(statusIds);
-            }
-            if (resultIds.size === 0) {
-                return { apis: [], total: 0, filters: query };
-            }
-        }
-        // Filter by tags (using index for O(M) lookup where M is number of tags)
-        if (query.tags && query.tags.length > 0) {
-            const tagMatches = new Set();
-            for (const tag of query.tags) {
-                const tagIds = this.apisByTag.get(tag);
-                if (tagIds) {
-                    tagIds.forEach(id => tagMatches.add(id));
-                }
-            }
-            if (tagMatches.size === 0) {
-                return { apis: [], total: 0, filters: query };
-            }
-            if (resultIds) {
-                // Intersect with previous results
-                resultIds = new Set([...resultIds].filter(id => tagMatches.has(id)));
-            }
-            else {
-                resultIds = tagMatches;
-            }
-            if (resultIds.size === 0) {
-                return { apis: [], total: 0, filters: query };
-            }
-        }
-        // Get the actual API objects
-        let results;
-        if (resultIds) {
-            results = Array.from(resultIds)
-                .map(id => this.apis.get(id))
-                .filter((api) => api !== undefined);
-        }
-        else {
-            results = Array.from(this.apis.values());
-        }
-        // Apply remaining filters that don't have indices (less common filters)
-        // Filter by plugin source
-        if (query.pluginSource) {
-            results = results.filter((api) => api.metadata?.pluginSource === query.pluginSource);
-        }
-        // Filter by version
-        if (query.version) {
-            results = results.filter((api) => api.version === query.version);
-        }
-        // Search in name/description
-        if (query.search) {
-            const searchLower = query.search.toLowerCase();
-            results = results.filter((api) => api.name.toLowerCase().includes(searchLower) ||
-                (api.description && api.description.toLowerCase().includes(searchLower)));
-        }
-        return {
-            apis: results,
-            total: results.length,
-            filters: query,
-        };
-    }
-    /**
-     * Get endpoint by API ID and endpoint ID
-     *
-     * @param apiId - API identifier
-     * @param endpointId - Endpoint identifier
-     * @returns Endpoint registration or undefined
-     */
-    getEndpoint(apiId, endpointId) {
-        const key = `${apiId}:${endpointId}`;
-        return this.endpoints.get(key)?.endpoint;
-    }
-    /**
-     * Find endpoint by route (method + path)
-     *
-     * @param method - HTTP method
-     * @param path - URL path
-     * @returns Endpoint registration or undefined
-     */
-    findEndpointByRoute(method, path) {
-        const routeKey = `${method}:${path}`;
-        const route = this.routes.get(routeKey);
-        if (!route) {
-            return undefined;
-        }
-        const api = this.apis.get(route.api);
-        const endpoint = this.getEndpoint(route.api, route.endpointId);
-        if (!api || !endpoint) {
-            return undefined;
-        }
-        return { api, endpoint };
-    }
-    /**
-     * Get complete registry snapshot
-     *
-     * @returns Current registry state
-     */
-    getRegistry() {
-        const apis = Array.from(this.apis.values());
-        // Group by type
-        const byType = {};
-        for (const api of apis) {
-            if (!byType[api.type]) {
-                byType[api.type] = [];
-            }
-            byType[api.type].push(api);
-        }
-        // Group by status
-        const byStatus = {};
-        for (const api of apis) {
-            const status = api.metadata?.status || 'active';
-            if (!byStatus[status]) {
-                byStatus[status] = [];
-            }
-            byStatus[status].push(api);
-        }
-        // Count total endpoints
-        const totalEndpoints = apis.reduce((sum, api) => sum + api.endpoints.length, 0);
-        return {
-            version: this.version,
-            conflictResolution: this.conflictResolution,
-            apis,
-            totalApis: apis.length,
-            totalEndpoints,
-            byType,
-            byStatus,
-            updatedAt: this.updatedAt,
-        };
-    }
-    /**
-     * 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 = {}) {
-        const isProduction = this.isProductionEnvironment();
-        if (isProduction && !options.force) {
-            throw new Error('[ApiRegistry] Cannot clear registry in production environment without force flag. ' +
-                'Use clear({ force: true }) if you really want to clear the registry.');
-        }
-        this.apis.clear();
-        this.endpoints.clear();
-        this.routes.clear();
-        // Clear auxiliary indices
-        this.apisByType.clear();
-        this.apisByTag.clear();
-        this.apisByStatus.clear();
-        this.updatedAt = new Date().toISOString();
-        if (isProduction) {
-            this.logger.warn('API registry forcefully cleared in production', { force: options.force });
-        }
-        else {
-            this.logger.info('API registry cleared');
-        }
-    }
-    /**
-     * Get registry statistics
-     *
-     * @returns Registry statistics
-     */
-    getStats() {
-        const apis = Array.from(this.apis.values());
-        const apisByType = {};
-        for (const api of apis) {
-            apisByType[api.type] = (apisByType[api.type] || 0) + 1;
-        }
-        const endpointsByApi = {};
-        for (const api of apis) {
-            endpointsByApi[api.id] = api.endpoints.length;
-        }
-        return {
-            totalApis: this.apis.size,
-            totalEndpoints: this.endpoints.size,
-            totalRoutes: this.routes.size,
-            apisByType,
-            endpointsByApi,
-        };
-    }
-    /**
-     * Update auxiliary indices when an API is registered
-     *
-     * @param api - API entry to index
-     * @private
-     * @internal
-     */
-    updateIndices(api) {
-        // Index by type
-        this.ensureIndexSet(this.apisByType, api.type).add(api.id);
-        // Index by status
-        const status = api.metadata?.status || 'active';
-        this.ensureIndexSet(this.apisByStatus, status).add(api.id);
-        // Index by tags
-        const tags = api.metadata?.tags || [];
-        for (const tag of tags) {
-            this.ensureIndexSet(this.apisByTag, tag).add(api.id);
-        }
-    }
-    /**
-     * Remove API from auxiliary indices when unregistered
-     *
-     * @param api - API entry to remove from indices
-     * @private
-     * @internal
-     */
-    removeFromIndices(api) {
-        // Remove from type index
-        this.removeFromIndexSet(this.apisByType, api.type, api.id);
-        // Remove from status index
-        const status = api.metadata?.status || 'active';
-        this.removeFromIndexSet(this.apisByStatus, status, api.id);
-        // Remove from tag indices
-        const tags = api.metadata?.tags || [];
-        for (const tag of tags) {
-            this.removeFromIndexSet(this.apisByTag, tag, api.id);
-        }
-    }
-    /**
-     * 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
-     */
-    ensureIndexSet(map, key) {
-        let set = map.get(key);
-        if (!set) {
-            set = new Set();
-            map.set(key, set);
-        }
-        return set;
-    }
-    /**
-     * 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
-     */
-    removeFromIndexSet(map, key, id) {
-        const set = map.get(key);
-        if (set) {
-            set.delete(id);
-            // Clean up empty sets to avoid memory leaks
-            if (set.size === 0) {
-                map.delete(key);
-            }
-        }
-    }
-    /**
-     * Check if running in production environment
-     *
-     * @returns true if NODE_ENV is 'production'
-     * @private
-     * @internal
-     */
-    isProductionEnvironment() {
-        return getEnv('NODE_ENV') === 'production';
-    }
-}

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

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=api-registry.test.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"api-registry.test.d.ts","sourceRoot":"","sources":["../src/api-registry.test.ts"],"names":[],"mappings":""}