@objectql/server 1.8.3 → 1.9.0

package/src/adapters/rest.ts

@@ -1,7 +1,8 @@
-import { IObjectQL } from '@objectql/types';
+import { IObjectQL, ApiRouteConfig, resolveApiRoutes } from '@objectql/types';
 import { ObjectQLServer } from '../server';
 import { ObjectQLRequest, ErrorCode } from '../types';
 import { IncomingMessage, ServerResponse } from 'http';
+import { escapeRegexPath } from '../utils';
 
 /**
  * Parse query string parameters
@@ -60,20 +61,33 @@ function sendJSON(res: ServerResponse, statusCode: number, data: any) {
     res.end(JSON.stringify(data));
 }
 
+/**
+ * Options for createRESTHandler
+ */
+export interface RESTHandlerOptions {
+    /** Custom API route configuration */
+    routes?: ApiRouteConfig;
+}
+
 /**
  * Creates a REST-style HTTP request handler for ObjectQL
  * 
- * Endpoints:
- * - GET    /api/data/:object               - List records
- * - GET    /api/data/:object/:id           - Get single record
- * - POST   /api/data/:object               - Create record (or create many if array)
- * - POST   /api/data/:object/bulk-update   - Update many records
- * - POST   /api/data/:object/bulk-delete   - Delete many records
- * - PUT    /api/data/:object/:id           - Update record
- * - DELETE /api/data/:object/:id           - Delete record
+ * Default Endpoints (configurable via routes option):
+ * - GET    {dataPath}/:object               - List records
+ * - GET    {dataPath}/:object/:id           - Get single record
+ * - POST   {dataPath}/:object               - Create record (or create many if array)
+ * - POST   {dataPath}/:object/bulk-update   - Update many records
+ * - POST   {dataPath}/:object/bulk-delete   - Delete many records
+ * - PUT    {dataPath}/:object/:id           - Update record
+ * - DELETE {dataPath}/:object/:id           - Delete record
+ * 
+ * @param app - ObjectQL application instance
+ * @param options - Optional configuration including custom routes
  */
-export function createRESTHandler(app: IObjectQL) {
+export function createRESTHandler(app: IObjectQL, options?: RESTHandlerOptions) {
     const server = new ObjectQLServer(app);
+    const routes = resolveApiRoutes(options?.routes);
+    const dataPath = routes.data;
 
     return async (req: IncomingMessage & { body?: any }, res: ServerResponse) => {
         try {
@@ -101,8 +115,9 @@ export function createRESTHandler(app: IObjectQL) {
             const url = req.url || '';
             const method = req.method || 'GET';
 
-            // Parse URL: /api/data/:object or /api/data/:object/:id or /api/data/:object/bulk-*
-            const match = url.match(/^\/api\/data\/([^\/\?]+)(?:\/([^\/\?]+))?(\?.*)?$/);
+            // Parse URL: {dataPath}/:object or {dataPath}/:object/:id or {dataPath}/:object/bulk-*
+            const escapedPath = escapeRegexPath(dataPath);
+            const match = url.match(new RegExp(`^${escapedPath}/([^/\\?]+)(?:/([^/\\?]+))?(\\?.*)?$`));
 
             if (!match) {
                 sendJSON(res, 404, {
@@ -129,7 +144,7 @@ export function createRESTHandler(app: IObjectQL) {
                             args: id
                         };
                     } else {
-                        // GET /api/data/:object - List records
+                        // GET {dataPath}/:object - List records
                         const args: any = {};
 
                         // Parse query parameters
@@ -167,7 +182,7 @@ export function createRESTHandler(app: IObjectQL) {
                     
                     // Check for bulk operations
                     if (id === 'bulk-update') {
-                        // POST /api/data/:object/bulk-update - Update many records
+                        // POST {dataPath}/:object/bulk-update - Update many records
                         qlRequest = {
                             op: 'updateMany',
                             object: objectName,
@@ -177,7 +192,7 @@ export function createRESTHandler(app: IObjectQL) {
                             }
                         };
                     } else if (id === 'bulk-delete') {
-                        // POST /api/data/:object/bulk-delete - Delete many records
+                        // POST {dataPath}/:object/bulk-delete - Delete many records
                         qlRequest = {
                             op: 'deleteMany',
                             object: objectName,
@@ -186,14 +201,14 @@ export function createRESTHandler(app: IObjectQL) {
                             }
                         };
                     } else if (Array.isArray(createBody)) {
-                        // POST /api/data/:object with array - Create many records
+                        // POST {dataPath}/:object with array - Create many records
                         qlRequest = {
                             op: 'createMany',
                             object: objectName,
                             args: createBody
                         };
                     } else {
-                        // POST /api/data/:object - Create single record
+                        // POST {dataPath}/:object - Create single record
                         qlRequest = {
                             op: 'create',
                             object: objectName,
@@ -204,7 +219,7 @@ export function createRESTHandler(app: IObjectQL) {
 
                 case 'PUT':
                 case 'PATCH':
-                    // PUT /api/data/:object/:id - Update record
+                    // PUT {dataPath}/:object/:id - Update record
                     if (!id) {
                         sendJSON(res, 400, {
                             error: {
@@ -227,7 +242,7 @@ export function createRESTHandler(app: IObjectQL) {
                     break;
 
                 case 'DELETE':
-                    // DELETE /api/data/:object/:id - Delete record
+                    // DELETE {dataPath}/:object/:id - Delete record
                     if (!id) {
                         sendJSON(res, 400, {
                             error: {

package/src/index.ts

@@ -1,8 +1,8 @@
 export * from './types';
+export * from './utils';
 export * from './openapi';
 export * from './server';
 export * from './metadata';
-export * from './studio';
 export * from './storage';
 export * from './file-handler';
 // We export createNodeHandler from root for convenience, 

package/src/metadata.ts

@@ -1,6 +1,7 @@
-import { IObjectQL } from '@objectql/types';
+import { IObjectQL, ApiRouteConfig, resolveApiRoutes } from '@objectql/types';
 import { IncomingMessage, ServerResponse } from 'http';
 import { ErrorCode } from './types';
+import { escapeRegexPath } from './utils';
 
 function readBody(req: IncomingMessage): Promise<any> {
     return new Promise((resolve, reject) => {
@@ -18,11 +19,24 @@ function readBody(req: IncomingMessage): Promise<any> {
     });
 }
 
+/**
+ * Options for createMetadataHandler
+ */
+export interface MetadataHandlerOptions {
+    /** Custom API route configuration */
+    routes?: ApiRouteConfig;
+}
+
 /**
  * Creates a handler for metadata endpoints.
  * These endpoints expose information about registered objects and other metadata.
+ * 
+ * @param app - ObjectQL application instance
+ * @param options - Optional configuration including custom routes
  */
-export function createMetadataHandler(app: IObjectQL) {
+export function createMetadataHandler(app: IObjectQL, options?: MetadataHandlerOptions) {
+    const routes = resolveApiRoutes(options?.routes);
+    const metadataPath = routes.metadata;
     return async (req: IncomingMessage, res: ServerResponse) => {
         // Parse the URL
         const url = req.url || '';
@@ -52,13 +66,14 @@ export function createMetadataHandler(app: IObjectQL) {
             };
 
             // ---------------------------------------------------------
-            // 1. List Entries (GET /api/metadata/:type)
+            // 1. List Entries (GET {metadataPath}/:type)
             // ---------------------------------------------------------
             
-            // Generic List: /api/metadata/:type
-            // Also handles legacy /api/metadata (defaults to objects)
-            const listMatch = url.match(/^\/api\/metadata\/([^\/]+)$/);
-            const isRootMetadata = url === '/api/metadata';
+            // Generic List: {metadataPath}/:type
+            // Also handles legacy {metadataPath} (defaults to objects)
+            const escapedPath = escapeRegexPath(metadataPath);
+            const listMatch = url.match(new RegExp(`^${escapedPath}/([^/]+)$`));
+            const isRootMetadata = url === metadataPath;
             
             if (method === 'GET' && (listMatch || isRootMetadata)) {
                 let type = isRootMetadata ? 'object' : listMatch![1];
@@ -85,10 +100,10 @@ export function createMetadataHandler(app: IObjectQL) {
             }
 
             // ---------------------------------------------------------
-            // 2. Get Single Entry (GET /api/metadata/:type/:id)
+            // 2. Get Single Entry (GET {metadataPath}/:type/:id)
             // ---------------------------------------------------------
             
-            const detailMatch = url.match(/^\/api\/metadata\/([^\/]+)\/([^\/\?]+)$/);
+            const detailMatch = url.match(new RegExp(`^${escapedPath}/([^/]+)/([^/\\?]+)$`));
             
             if (method === 'GET' && detailMatch) {
                 let [, type, id] = detailMatch;
@@ -127,7 +142,7 @@ export function createMetadataHandler(app: IObjectQL) {
             }
 
             // ---------------------------------------------------------
-            // 3. Update Entry (POST/PUT /api/metadata/:type/:id)
+            // 3. Update Entry (POST/PUT {metadataPath}/:type/:id)
             // ---------------------------------------------------------
             if ((method === 'POST' || method === 'PUT') && detailMatch) {
                 let [, type, id] = detailMatch;
@@ -152,9 +167,9 @@ export function createMetadataHandler(app: IObjectQL) {
             // 4. Object Sub-resources (Fields, Actions)
             // ---------------------------------------------------------
             
-            // GET /api/metadata/object/:name/fields/:field
+            // GET {metadataPath}/object/:name/fields/:field
             // Legacy path support.
-            const fieldMatch = url.match(/^\/api\/metadata\/(?:objects|object)\/([^\/]+)\/fields\/([^\/\?]+)$/);
+            const fieldMatch = url.match(new RegExp(`^${escapedPath}/(?:objects|object)/([^/]+)/fields/([^/\\?]+)$`));
             if (method === 'GET' && fieldMatch) {
                 const [, objectName, fieldName] = fieldMatch;
                 const metadata = app.getObject(objectName);
@@ -180,8 +195,8 @@ export function createMetadataHandler(app: IObjectQL) {
                 });
             }
 
-            // GET /api/metadata/object/:name/actions
-            const actionsMatch = url.match(/^\/api\/metadata\/(?:objects|object)\/([^\/]+)\/actions$/);
+            // GET {metadataPath}/object/:name/actions
+            const actionsMatch = url.match(new RegExp(`^${escapedPath}/(?:objects|object)/([^/]+)/actions$`));
             if (method === 'GET' && actionsMatch) {
                 const [, objectName] = actionsMatch;
                 const metadata = app.getObject(objectName);

package/src/openapi.ts

@@ -1,4 +1,4 @@
-import { IObjectQL, ObjectConfig, FieldType, FieldConfig } from '@objectql/types';
+import { IObjectQL, ObjectConfig, FieldConfig, ApiRouteConfig, resolveApiRoutes } from '@objectql/types';
 
 interface OpenAPISchema {
     openapi: string;
@@ -12,16 +12,17 @@ interface OpenAPISchema {
     };
 }
 
-export function generateOpenAPI(app: IObjectQL): OpenAPISchema {
+export function generateOpenAPI(app: IObjectQL, routeConfig?: ApiRouteConfig): OpenAPISchema {
     const registry = (app as any).metadata; // Direct access or via interface
     const objects = registry.list('object') as ObjectConfig[];
+    const routes = resolveApiRoutes(routeConfig);
 
     const paths: Record<string, any> = {};
     const schemas: Record<string, any> = {};
 
     
     // 1. JSON-RPC Endpoint
-    paths['/api/objectql'] = {
+    paths[routes.rpc] = {
         post: {
             summary: 'JSON-RPC Entry Point',
             description: 'Execute any ObjectQL operation via a JSON body.',
@@ -72,9 +73,9 @@ export function generateOpenAPI(app: IObjectQL): OpenAPISchema {
     // 3. REST API Paths
     for (const obj of objects) {
         const name = obj.name;
-        const basePath = `/api/data/${name}`; // Standard REST Path
+        const basePath = `${routes.data}/${name}`; // Standard REST Path
         
-        // GET /api/data/:name (List)
+        // GET {dataPath}/:name (List)
         paths[basePath] = {
             get: {
                 summary: `List ${name}`,

package/src/utils.ts

@@ -0,0 +1,21 @@
+/**
+ * Utility functions for server operations
+ */
+
+/**
+ * Escapes special regex characters in a path string for use in RegExp
+ * @param path - The path string to escape
+ * @returns Escaped path string safe for use in RegExp
+ */
+export function escapeRegexPath(path: string): string {
+    return path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Normalizes a path to ensure it starts with a forward slash
+ * @param path - The path string to normalize
+ * @returns Normalized path string starting with '/'
+ */
+export function normalizePath(path: string): string {
+    return path.startsWith('/') ? path : `/${path}`;
+}

package/test/custom-routes.test.ts

@@ -0,0 +1,297 @@
+/**
+ * Tests for Custom API Route Configuration
+ * 
+ * Validates that API routes can be configured at initialization time
+ * instead of being hardcoded.
+ */
+
+import request from 'supertest';
+import { createServer } from 'http';
+import { ObjectQL } from '@objectql/core';
+import { createNodeHandler, createRESTHandler, createMetadataHandler } from '../src';
+import { Driver } from '@objectql/types';
+
+// Simple Mock Driver for testing
+class MockDriver implements Driver {
+    private data: Record<string, any[]> = {
+        user: [
+            { _id: '1', name: 'Alice', email: 'alice@example.com' },
+            { _id: '2', name: 'Bob', email: 'bob@example.com' }
+        ]
+    };
+    private nextId = 3;
+
+    async init() {}
+    
+    async find(objectName: string, query: any) {
+        return this.data[objectName] || [];
+    }
+    
+    async findOne(objectName: string, id: string | number) {
+        const items = this.data[objectName] || [];
+        return items.find(item => item._id === String(id)) || null;
+    }
+    
+    async create(objectName: string, data: any) {
+        const newItem = { _id: String(this.nextId++), ...data };
+        if (!this.data[objectName]) {
+            this.data[objectName] = [];
+        }
+        this.data[objectName].push(newItem);
+        return newItem;
+    }
+    
+    async update(objectName: string, id: string, data: any) {
+        const items = this.data[objectName] || [];
+        const index = items.findIndex(item => item._id === id);
+        if (index >= 0) {
+            this.data[objectName][index] = { ...items[index], ...data };
+            return 1;
+        }
+        return 0;
+    }
+    
+    async delete(objectName: string, id: string) {
+        const items = this.data[objectName] || [];
+        const index = items.findIndex(item => item._id === id);
+        if (index >= 0) {
+            this.data[objectName].splice(index, 1);
+            return 1;
+        }
+        return 0;
+    }
+    
+    async count(objectName: string) {
+        return (this.data[objectName] || []).length;
+    }
+    
+    async createMany(objectName: string, data: any[]) {
+        const results = [];
+        for (const item of data) {
+            results.push(await this.create(objectName, item));
+        }
+        return results;
+    }
+    
+    async updateMany(objectName: string, filters: any, data: any) {
+        return 0;
+    }
+    
+    async deleteMany(objectName: string, filters: any) {
+        return 0;
+    }
+}
+
+describe('Custom API Routes', () => {
+    let app: ObjectQL;
+    
+    beforeEach(async () => {
+        app = new ObjectQL({
+            datasources: {
+                default: new MockDriver()
+            }
+        });
+        
+        app.registerObject({
+            name: 'user',
+            label: 'User',
+            fields: {
+                name: { type: 'text', label: 'Name' },
+                email: { type: 'email', label: 'Email' }
+            }
+        });
+        
+        await app.init();
+    });
+
+    describe('REST Handler with Custom Routes', () => {
+        it('should work with custom data path /v1/resources', async () => {
+            const customRoutes = {
+                data: '/v1/resources'
+            };
+            
+            const handler = createRESTHandler(app, { routes: customRoutes });
+            const server = createServer(handler);
+            
+            const res = await request(server)
+                .get('/v1/resources/user')
+                .expect(200);
+                
+            expect(res.body.items).toBeDefined();
+            expect(res.body.items.length).toBe(2);
+        });
+
+        it('should not respond to default path when custom path is set', async () => {
+            const customRoutes = {
+                data: '/v1/resources'
+            };
+            
+            const handler = createRESTHandler(app, { routes: customRoutes });
+            const server = createServer(handler);
+            
+            await request(server)
+                .get('/api/data/user')
+                .expect(404);
+        });
+
+        it('should support multiple custom paths', async () => {
+            const customRoutes = {
+                data: '/api/v2/data',
+                metadata: '/api/v2/metadata'
+            };
+            
+            const restHandler = createRESTHandler(app, { routes: customRoutes });
+            const restServer = createServer(restHandler);
+            
+            const metadataHandler = createMetadataHandler(app, { routes: customRoutes });
+            const metadataServer = createServer(metadataHandler);
+            
+            // Test REST API with custom path
+            const restRes = await request(restServer)
+                .get('/api/v2/data/user')
+                .expect(200);
+            expect(restRes.body.items).toBeDefined();
+            
+            // Test Metadata API with custom path
+            const metadataRes = await request(metadataServer)
+                .get('/api/v2/metadata/objects')
+                .expect(200);
+            expect(metadataRes.body.items).toBeDefined();
+        });
+    });
+
+    describe('Node Handler with Custom Routes', () => {
+        it('should work with custom RPC path /v1/rpc', async () => {
+            const customRoutes = {
+                rpc: '/v1/rpc',
+                data: '/v1/data'
+            };
+            
+            const handler = createNodeHandler(app, { routes: customRoutes });
+            const server = createServer(handler);
+            
+            // Test custom RPC endpoint
+            const res = await request(server)
+                .post('/v1/rpc')
+                .send({
+                    op: 'find',
+                    object: 'user',
+                    args: {}
+                })
+                .expect(200);
+                
+            // NodeHandler returns the full ObjectQLResponse
+            expect(res.body.items || res.body.data).toBeDefined();
+        });
+
+        it('should work with custom data path for REST operations', async () => {
+            const customRoutes = {
+                rpc: '/v1/rpc',
+                data: '/v1/data'
+            };
+            
+            const handler = createNodeHandler(app, { routes: customRoutes });
+            const server = createServer(handler);
+            
+            // Test custom REST endpoint
+            const res = await request(server)
+                .get('/v1/data/user')
+                .expect(200);
+                
+            expect(res.body.items).toBeDefined();
+        });
+
+        it('should work with custom files path', async () => {
+            const customRoutes = {
+                rpc: '/v1/rpc',
+                data: '/v1/data',
+                files: '/v1/storage'
+            };
+            
+            const handler = createNodeHandler(app, { routes: customRoutes });
+            const server = createServer(handler);
+            
+            // Test that file upload path is recognized (will fail without multipart body, but path is recognized)
+            const res = await request(server)
+                .post('/v1/storage/upload');
+                
+            // Should not be 404 (not found), but may be 400 (bad request) or 500 (server error)
+            expect(res.status).not.toBe(404);
+        });
+    });
+
+    describe('Metadata Handler with Custom Routes', () => {
+        it('should work with custom metadata path /v1/schema', async () => {
+            const customRoutes = {
+                metadata: '/v1/schema'
+            };
+            
+            const handler = createMetadataHandler(app, { routes: customRoutes });
+            const server = createServer(handler);
+            
+            const res = await request(server)
+                .get('/v1/schema/objects')
+                .expect(200);
+                
+            expect(res.body.items).toBeDefined();
+            expect(res.body.items.length).toBeGreaterThan(0);
+        });
+
+        it('should support object detail endpoint with custom path', async () => {
+            const customRoutes = {
+                metadata: '/v1/schema'
+            };
+            
+            const handler = createMetadataHandler(app, { routes: customRoutes });
+            const server = createServer(handler);
+            
+            const res = await request(server)
+                .get('/v1/schema/object/user')
+                .expect(200);
+                
+            expect(res.body.name).toBe('user');
+            expect(res.body.fields).toBeDefined();
+        });
+    });
+
+    describe('Default Routes (Backward Compatibility)', () => {
+        it('should use default routes when no custom routes provided', async () => {
+            const handler = createRESTHandler(app);
+            const server = createServer(handler);
+            
+            const res = await request(server)
+                .get('/api/data/user')
+                .expect(200);
+                
+            expect(res.body.items).toBeDefined();
+        });
+
+        it('should use default RPC route when no custom routes provided', async () => {
+            const handler = createNodeHandler(app);
+            const server = createServer(handler);
+            
+            const res = await request(server)
+                .post('/api/objectql')
+                .send({
+                    op: 'find',
+                    object: 'user',
+                    args: {}
+                })
+                .expect(200);
+                
+            // NodeHandler returns the full ObjectQLResponse
+            expect(res.body.items || res.body.data).toBeDefined();
+        });
+
+        it('should use default metadata route when no custom routes provided', async () => {
+            const handler = createMetadataHandler(app);
+            const server = createServer(handler);
+            
+            const res = await request(server)
+                .get('/api/metadata/objects')
+                .expect(200);
+                
+            expect(res.body.items).toBeDefined();
+        });
+    });
+});