@objectstack/runtime 0.6.1 → 0.7.1

package/dist/rest-server.d.ts

@@ -0,0 +1,74 @@
+import { IHttpServer } from '@objectstack/core';
+import { RouteManager } from './route-manager';
+import { RestServerConfig } from '@objectstack/spec/api';
+import { ObjectStackProtocol } from '@objectstack/spec/api';
+/**
+ * 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 declare class RestServer {
+    private server;
+    private protocol;
+    private config;
+    private routeManager;
+    constructor(server: IHttpServer, protocol: ObjectStackProtocol, config?: RestServerConfig);
+    /**
+     * Normalize configuration with defaults
+     */
+    private normalizeConfig;
+    /**
+     * Get the full API base path
+     */
+    private getApiBasePath;
+    /**
+     * Register all REST API routes
+     */
+    registerRoutes(): void;
+    /**
+     * Register discovery endpoints
+     */
+    private registerDiscoveryEndpoints;
+    /**
+     * Register metadata endpoints
+     */
+    private registerMetadataEndpoints;
+    /**
+     * Register CRUD endpoints for data operations
+     */
+    private registerCrudEndpoints;
+    /**
+     * Register batch operation endpoints
+     */
+    private registerBatchEndpoints;
+    /**
+     * Get the route manager
+     */
+    getRouteManager(): RouteManager;
+    /**
+     * Get all registered routes
+     */
+    getRoutes(): import("./route-manager").RouteEntry[];
+}

package/dist/rest-server.js

@@ -0,0 +1,490 @@
+import { RouteManager } from './route-manager';
+/**
+ * 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'],
+                },
+            });
+        }
+    }
+    /**
+     * 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();
+    }
+}