@objectstack/runtime 1.0.2 → 1.0.5

package/dist/rest-server.js

@@ -1,518 +0,0 @@
-import { RouteManager } from './route-manager.js';
-/**
- * RestServer
- *
- * Provides automatic REST API endpoint generation for ObjectStack.
- * Generates standard RESTful CRUD endpoints, metadata endpoints, and batch operations
- * based on the configured protocol provider.
- *
- * Features:
- * - Automatic CRUD endpoint generation (GET, POST, PUT, PATCH, DELETE)
- * - Metadata API endpoints (/meta)
- * - Batch operation endpoints (/batch, /createMany, /updateMany, /deleteMany)
- * - Discovery endpoint
- * - Configurable path prefixes and patterns
- *
- * @example
- * const restServer = new RestServer(httpServer, protocolProvider, {
- *   api: {
- *     version: 'v1',
- *     basePath: '/api'
- *   },
- *   crud: {
- *     dataPrefix: '/data'
- *   }
- * });
- *
- * restServer.registerRoutes();
- */
-export class RestServer {
-    constructor(server, protocol, config = {}) {
-        this.server = server;
-        this.protocol = protocol;
-        this.config = this.normalizeConfig(config);
-        this.routeManager = new RouteManager(server);
-    }
-    /**
-     * Normalize configuration with defaults
-     */
-    normalizeConfig(config) {
-        const api = (config.api ?? {});
-        const crud = (config.crud ?? {});
-        const metadata = (config.metadata ?? {});
-        const batch = (config.batch ?? {});
-        const routes = (config.routes ?? {});
-        return {
-            api: {
-                version: api.version ?? 'v1',
-                basePath: api.basePath ?? '/api',
-                apiPath: api.apiPath,
-                enableCrud: api.enableCrud ?? true,
-                enableMetadata: api.enableMetadata ?? true,
-                enableBatch: api.enableBatch ?? true,
-                enableDiscovery: api.enableDiscovery ?? true,
-                documentation: api.documentation,
-                responseFormat: api.responseFormat,
-            },
-            crud: {
-                operations: crud.operations ?? {
-                    create: true,
-                    read: true,
-                    update: true,
-                    delete: true,
-                    list: true,
-                },
-                patterns: crud.patterns,
-                dataPrefix: crud.dataPrefix ?? '/data',
-                objectParamStyle: crud.objectParamStyle ?? 'path',
-            },
-            metadata: {
-                prefix: metadata.prefix ?? '/meta',
-                enableCache: metadata.enableCache ?? true,
-                cacheTtl: metadata.cacheTtl ?? 3600,
-                endpoints: metadata.endpoints ?? {
-                    types: true,
-                    items: true,
-                    item: true,
-                    schema: true,
-                },
-            },
-            batch: {
-                maxBatchSize: batch.maxBatchSize ?? 200,
-                enableBatchEndpoint: batch.enableBatchEndpoint ?? true,
-                operations: batch.operations ?? {
-                    createMany: true,
-                    updateMany: true,
-                    deleteMany: true,
-                    upsertMany: true,
-                },
-                defaultAtomic: batch.defaultAtomic ?? true,
-            },
-            routes: {
-                includeObjects: routes.includeObjects,
-                excludeObjects: routes.excludeObjects,
-                nameTransform: routes.nameTransform ?? 'none',
-                overrides: routes.overrides,
-            },
-        };
-    }
-    /**
-     * Get the full API base path
-     */
-    getApiBasePath() {
-        const { api } = this.config;
-        return api.apiPath ?? `${api.basePath}/${api.version}`;
-    }
-    /**
-     * Register all REST API routes
-     */
-    registerRoutes() {
-        const basePath = this.getApiBasePath();
-        // Discovery endpoint
-        if (this.config.api.enableDiscovery) {
-            this.registerDiscoveryEndpoints(basePath);
-        }
-        // Metadata endpoints
-        if (this.config.api.enableMetadata) {
-            this.registerMetadataEndpoints(basePath);
-        }
-        // CRUD endpoints
-        if (this.config.api.enableCrud) {
-            this.registerCrudEndpoints(basePath);
-        }
-        // Batch endpoints
-        if (this.config.api.enableBatch) {
-            this.registerBatchEndpoints(basePath);
-        }
-    }
-    /**
-     * Register discovery endpoints
-     */
-    registerDiscoveryEndpoints(basePath) {
-        this.routeManager.register({
-            method: 'GET',
-            path: basePath,
-            handler: async (req, res) => {
-                try {
-                    const discovery = await this.protocol.getDiscovery({});
-                    res.json(discovery);
-                }
-                catch (error) {
-                    res.status(500).json({ error: error.message });
-                }
-            },
-            metadata: {
-                summary: 'Get API discovery information',
-                tags: ['discovery'],
-            },
-        });
-    }
-    /**
-     * Register metadata endpoints
-     */
-    registerMetadataEndpoints(basePath) {
-        const { metadata } = this.config;
-        const metaPath = `${basePath}${metadata.prefix}`;
-        // GET /meta - List all metadata types
-        if (metadata.endpoints.types !== false) {
-            this.routeManager.register({
-                method: 'GET',
-                path: metaPath,
-                handler: async (req, res) => {
-                    try {
-                        const types = await this.protocol.getMetaTypes({});
-                        res.json(types);
-                    }
-                    catch (error) {
-                        res.status(500).json({ error: error.message });
-                    }
-                },
-                metadata: {
-                    summary: 'List all metadata types',
-                    tags: ['metadata'],
-                },
-            });
-        }
-        // GET /meta/:type - List items of a type
-        if (metadata.endpoints.items !== false) {
-            this.routeManager.register({
-                method: 'GET',
-                path: `${metaPath}/:type`,
-                handler: async (req, res) => {
-                    try {
-                        const items = await this.protocol.getMetaItems({ type: req.params.type });
-                        res.json(items);
-                    }
-                    catch (error) {
-                        res.status(404).json({ error: error.message });
-                    }
-                },
-                metadata: {
-                    summary: 'List metadata items of a type',
-                    tags: ['metadata'],
-                },
-            });
-        }
-        // GET /meta/:type/:name - Get specific item
-        if (metadata.endpoints.item !== false) {
-            this.routeManager.register({
-                method: 'GET',
-                path: `${metaPath}/:type/:name`,
-                handler: async (req, res) => {
-                    try {
-                        // Check if cached version is available
-                        if (metadata.enableCache && this.protocol.getMetaItemCached) {
-                            const cacheRequest = {
-                                ifNoneMatch: req.headers['if-none-match'],
-                                ifModifiedSince: req.headers['if-modified-since'],
-                            };
-                            const result = await this.protocol.getMetaItemCached({
-                                type: req.params.type,
-                                name: req.params.name,
-                                cacheRequest
-                            });
-                            if (result.notModified) {
-                                res.status(304).send();
-                                return;
-                            }
-                            // Set cache headers
-                            if (result.etag) {
-                                const etagValue = result.etag.weak
-                                    ? `W/"${result.etag.value}"`
-                                    : `"${result.etag.value}"`;
-                                res.header('ETag', etagValue);
-                            }
-                            if (result.lastModified) {
-                                res.header('Last-Modified', new Date(result.lastModified).toUTCString());
-                            }
-                            if (result.cacheControl) {
-                                const directives = result.cacheControl.directives.join(', ');
-                                const maxAge = result.cacheControl.maxAge
-                                    ? `, max-age=${result.cacheControl.maxAge}`
-                                    : '';
-                                res.header('Cache-Control', directives + maxAge);
-                            }
-                            res.json(result.data);
-                        }
-                        else {
-                            // Non-cached version
-                            const item = await this.protocol.getMetaItem({ type: req.params.type, name: req.params.name });
-                            res.json(item);
-                        }
-                    }
-                    catch (error) {
-                        res.status(404).json({ error: error.message });
-                    }
-                },
-                metadata: {
-                    summary: 'Get specific metadata item',
-                    tags: ['metadata'],
-                },
-            });
-        }
-        // PUT /meta/:type/:name - Save metadata item
-        // We always register this route, but return 501 if protocol doesn't support it
-        // This makes it discoverable even if not implemented
-        this.routeManager.register({
-            method: 'PUT',
-            path: `${metaPath}/:type/:name`,
-            handler: async (req, res) => {
-                try {
-                    if (!this.protocol.saveMetaItem) {
-                        res.status(501).json({ error: 'Save operation not supported by protocol implementation' });
-                        return;
-                    }
-                    const result = await this.protocol.saveMetaItem({
-                        type: req.params.type,
-                        name: req.params.name,
-                        item: req.body
-                    });
-                    res.json(result);
-                }
-                catch (error) {
-                    res.status(400).json({ error: error.message });
-                }
-            },
-            metadata: {
-                summary: 'Save specific metadata item',
-                tags: ['metadata'],
-            },
-        });
-    }
-    /**
-     * Register CRUD endpoints for data operations
-     */
-    registerCrudEndpoints(basePath) {
-        const { crud } = this.config;
-        const dataPath = `${basePath}${crud.dataPrefix}`;
-        const operations = crud.operations;
-        // GET /data/:object - List/query records
-        if (operations.list) {
-            this.routeManager.register({
-                method: 'GET',
-                path: `${dataPath}/:object`,
-                handler: async (req, res) => {
-                    try {
-                        const result = await this.protocol.findData({
-                            object: req.params.object,
-                            query: req.query
-                        });
-                        res.json(result);
-                    }
-                    catch (error) {
-                        res.status(400).json({ error: error.message });
-                    }
-                },
-                metadata: {
-                    summary: 'Query records',
-                    tags: ['data', 'crud'],
-                },
-            });
-        }
-        // GET /data/:object/:id - Get single record
-        if (operations.read) {
-            this.routeManager.register({
-                method: 'GET',
-                path: `${dataPath}/:object/:id`,
-                handler: async (req, res) => {
-                    try {
-                        const result = await this.protocol.getData({
-                            object: req.params.object,
-                            id: req.params.id
-                        });
-                        res.json(result);
-                    }
-                    catch (error) {
-                        res.status(404).json({ error: error.message });
-                    }
-                },
-                metadata: {
-                    summary: 'Get record by ID',
-                    tags: ['data', 'crud'],
-                },
-            });
-        }
-        // POST /data/:object - Create record
-        if (operations.create) {
-            this.routeManager.register({
-                method: 'POST',
-                path: `${dataPath}/:object`,
-                handler: async (req, res) => {
-                    try {
-                        const result = await this.protocol.createData({
-                            object: req.params.object,
-                            data: req.body
-                        });
-                        res.status(201).json(result);
-                    }
-                    catch (error) {
-                        res.status(400).json({ error: error.message });
-                    }
-                },
-                metadata: {
-                    summary: 'Create record',
-                    tags: ['data', 'crud'],
-                },
-            });
-        }
-        // PATCH /data/:object/:id - Update record
-        if (operations.update) {
-            this.routeManager.register({
-                method: 'PATCH',
-                path: `${dataPath}/:object/:id`,
-                handler: async (req, res) => {
-                    try {
-                        const result = await this.protocol.updateData({
-                            object: req.params.object,
-                            id: req.params.id,
-                            data: req.body
-                        });
-                        res.json(result);
-                    }
-                    catch (error) {
-                        res.status(400).json({ error: error.message });
-                    }
-                },
-                metadata: {
-                    summary: 'Update record',
-                    tags: ['data', 'crud'],
-                },
-            });
-        }
-        // DELETE /data/:object/:id - Delete record
-        if (operations.delete) {
-            this.routeManager.register({
-                method: 'DELETE',
-                path: `${dataPath}/:object/:id`,
-                handler: async (req, res) => {
-                    try {
-                        const result = await this.protocol.deleteData({
-                            object: req.params.object,
-                            id: req.params.id
-                        });
-                        res.json(result);
-                    }
-                    catch (error) {
-                        res.status(400).json({ error: error.message });
-                    }
-                },
-                metadata: {
-                    summary: 'Delete record',
-                    tags: ['data', 'crud'],
-                },
-            });
-        }
-    }
-    /**
-     * Register batch operation endpoints
-     */
-    registerBatchEndpoints(basePath) {
-        const { crud, batch } = this.config;
-        const dataPath = `${basePath}${crud.dataPrefix}`;
-        const operations = batch.operations;
-        // POST /data/:object/batch - Generic batch endpoint
-        if (batch.enableBatchEndpoint && this.protocol.batchData) {
-            this.routeManager.register({
-                method: 'POST',
-                path: `${dataPath}/:object/batch`,
-                handler: async (req, res) => {
-                    try {
-                        const result = await this.protocol.batchData({
-                            object: req.params.object,
-                            request: req.body
-                        });
-                        res.json(result);
-                    }
-                    catch (error) {
-                        res.status(400).json({ error: error.message });
-                    }
-                },
-                metadata: {
-                    summary: 'Batch operations',
-                    tags: ['data', 'batch'],
-                },
-            });
-        }
-        // POST /data/:object/createMany - Bulk create
-        if (operations.createMany && this.protocol.createManyData) {
-            this.routeManager.register({
-                method: 'POST',
-                path: `${dataPath}/:object/createMany`,
-                handler: async (req, res) => {
-                    try {
-                        const result = await this.protocol.createManyData({
-                            object: req.params.object,
-                            records: req.body || []
-                        });
-                        res.status(201).json(result);
-                    }
-                    catch (error) {
-                        res.status(400).json({ error: error.message });
-                    }
-                },
-                metadata: {
-                    summary: 'Create multiple records',
-                    tags: ['data', 'batch'],
-                },
-            });
-        }
-        // POST /data/:object/updateMany - Bulk update
-        if (operations.updateMany && this.protocol.updateManyData) {
-            this.routeManager.register({
-                method: 'POST',
-                path: `${dataPath}/:object/updateMany`,
-                handler: async (req, res) => {
-                    try {
-                        const result = await this.protocol.updateManyData({
-                            object: req.params.object,
-                            ...req.body
-                        });
-                        res.json(result);
-                    }
-                    catch (error) {
-                        res.status(400).json({ error: error.message });
-                    }
-                },
-                metadata: {
-                    summary: 'Update multiple records',
-                    tags: ['data', 'batch'],
-                },
-            });
-        }
-        // POST /data/:object/deleteMany - Bulk delete
-        if (operations.deleteMany && this.protocol.deleteManyData) {
-            this.routeManager.register({
-                method: 'POST',
-                path: `${dataPath}/:object/deleteMany`,
-                handler: async (req, res) => {
-                    try {
-                        const result = await this.protocol.deleteManyData({
-                            object: req.params.object,
-                            ...req.body
-                        });
-                        res.json(result);
-                    }
-                    catch (error) {
-                        res.status(400).json({ error: error.message });
-                    }
-                },
-                metadata: {
-                    summary: 'Delete multiple records',
-                    tags: ['data', 'batch'],
-                },
-            });
-        }
-    }
-    /**
-     * Get the route manager
-     */
-    getRouteManager() {
-        return this.routeManager;
-    }
-    /**
-     * Get all registered routes
-     */
-    getRoutes() {
-        return this.routeManager.getAll();
-    }
-}

package/dist/route-manager.d.ts

@@ -1,153 +0,0 @@
-import { RouteHandler, IHttpServer } from '@objectstack/core';
-import { System, Shared } from '@objectstack/spec';
-type RouteHandlerMetadata = System.RouteHandlerMetadata;
-type HttpMethod = Shared.HttpMethod;
-/**
- * Route Entry
- * Internal representation of registered routes
- */
-export interface RouteEntry {
-    method: HttpMethod;
-    path: string;
-    handler: RouteHandler;
-    metadata?: RouteHandlerMetadata['metadata'];
-    security?: RouteHandlerMetadata['security'];
-}
-/**
- * RouteManager
- *
- * Manages route registration and organization for HTTP servers.
- * Provides:
- * - Route registration with metadata
- * - Route lookup and querying
- * - Bulk route registration
- * - Route grouping by prefix
- *
- * @example
- * const manager = new RouteManager(server);
- *
- * // Register individual route
- * manager.register({
- *   method: 'GET',
- *   path: '/api/users/:id',
- *   handler: getUserHandler,
- *   metadata: {
- *     summary: 'Get user by ID',
- *     tags: ['users']
- *   }
- * });
- *
- * // Register route group
- * manager.group('/api/users', (group) => {
- *   group.get('/', listUsersHandler);
- *   group.post('/', createUserHandler);
- *   group.get('/:id', getUserHandler);
- * });
- */
-export declare class RouteManager {
-    private server;
-    private routes;
-    constructor(server: IHttpServer);
-    /**
-     * Register a route
-     * @param entry - Route entry with method, path, handler, and metadata
-     */
-    register(entry: Omit<RouteEntry, 'handler'> & {
-        handler: RouteHandler | string;
-    }): void;
-    /**
-     * Register multiple routes
-     * @param entries - Array of route entries
-     */
-    registerMany(entries: Array<Omit<RouteEntry, 'handler'> & {
-        handler: RouteHandler | string;
-    }>): void;
-    /**
-     * Unregister a route
-     * @param method - HTTP method
-     * @param path - Route path
-     */
-    unregister(method: HttpMethod, path: string): void;
-    /**
-     * Get route by method and path
-     * @param method - HTTP method
-     * @param path - Route path
-     */
-    get(method: HttpMethod, path: string): RouteEntry | undefined;
-    /**
-     * Get all routes
-     */
-    getAll(): RouteEntry[];
-    /**
-     * Get routes by method
-     * @param method - HTTP method
-     */
-    getByMethod(method: HttpMethod): RouteEntry[];
-    /**
-     * Get routes by path prefix
-     * @param prefix - Path prefix
-     */
-    getByPrefix(prefix: string): RouteEntry[];
-    /**
-     * Get routes by tag
-     * @param tag - Tag name
-     */
-    getByTag(tag: string): RouteEntry[];
-    /**
-     * Create a route group with common prefix
-     * @param prefix - Common path prefix
-     * @param configure - Function to configure routes in the group
-     */
-    group(prefix: string, configure: (group: RouteGroupBuilder) => void): void;
-    /**
-     * Get route count
-     */
-    count(): number;
-    /**
-     * Clear all routes
-     */
-    clear(): void;
-    /**
-     * Get route key for storage
-     */
-    private getRouteKey;
-    /**
-     * Register route with underlying server
-     */
-    private registerWithServer;
-}
-/**
- * RouteGroupBuilder
- *
- * Builder for creating route groups with common prefix
- */
-export declare class RouteGroupBuilder {
-    private manager;
-    private prefix;
-    constructor(manager: RouteManager, prefix: string);
-    /**
-     * Register GET route in group
-     */
-    get(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
-    /**
-     * Register POST route in group
-     */
-    post(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
-    /**
-     * Register PUT route in group
-     */
-    put(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
-    /**
-     * Register PATCH route in group
-     */
-    patch(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
-    /**
-     * Register DELETE route in group
-     */
-    delete(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
-    /**
-     * Resolve full path with prefix
-     */
-    private resolvePath;
-}
-export {};