@objectql/server 1.4.0 → 1.5.0

package/src/metadata.ts

@@ -20,7 +20,7 @@ function readBody(req: IncomingMessage): Promise<any> {
 
 /**
  * Creates a handler for metadata endpoints.
- * These endpoints expose information about registered objects.
+ * These endpoints expose information about registered objects and other metadata.
  */
 export function createMetadataHandler(app: IObjectQL) {
     return async (req: IncomingMessage, res: ServerResponse) => {
@@ -40,7 +40,22 @@ export function createMetadataHandler(app: IObjectQL) {
         }
 
         try {
-            // GET /api/metadata or /api/metadata/objects - List all objects
+            // Helper to send JSON
+            const sendJson = (data: any, status = 200) => {
+                res.setHeader('Content-Type', 'application/json');
+                res.statusCode = status;
+                res.end(JSON.stringify(data));
+            };
+
+            const sendError = (code: ErrorCode, message: string, status = 400) => {
+                sendJson({ error: { code, message } }, status);
+            };
+
+            // ---------------------------------------------------------
+            // 1. List Entries (GET /api/metadata/:type)
+            // ---------------------------------------------------------
+            
+            // Legacy/Alias: /api/metadata or /api/metadata/objects -> list objects
             if (method === 'GET' && (url === '/api/metadata' || url === '/api/metadata/objects')) {
                 const configs = app.getConfigs();
                 const objects = Object.values(configs).map(obj => ({
@@ -50,88 +65,108 @@ export function createMetadataHandler(app: IObjectQL) {
                     description: obj.description,
                     fields: obj.fields || {}
                 }));
+                return sendJson({ objects });
+            }
+
+            // Generic List: /api/metadata/:type
+            const listMatch = url.match(/^\/api\/metadata\/([^\/]+)$/);
+            if (method === 'GET' && listMatch) {
+                let [, type] = listMatch;
+                if (type === 'objects') type = 'object'; // Should not hit due to order, but safe to keep.
                 
-                res.setHeader('Content-Type', 'application/json');
-                res.statusCode = 200;
-                res.end(JSON.stringify({ objects }));
-                return;
+                const entries = app.metadata.list(type);
+                // Return simple list
+                return sendJson({ 
+                    [type]: entries
+                });
             }
 
-            // GET /api/metadata/objects/:name - Get object details
-            const objectMatch = url.match(/^\/api\/metadata\/objects\/([^\/\?]+)$/);
-            if (method === 'GET' && objectMatch) {
-                const objectName = objectMatch[1];
-                const metadata = app.getObject(objectName);
-                if (!metadata) {
-                    res.statusCode = 404;
-                    res.end(JSON.stringify({ 
-                        error: {
-                            code: ErrorCode.NOT_FOUND,
-                            message: `Object '${objectName}' not found`
-                        }
-                    }));
-                    return;
+            // ---------------------------------------------------------
+            // 2. Get Single Entry (GET /api/metadata/:type/:id)
+            // ---------------------------------------------------------
+            
+            const detailMatch = url.match(/^\/api\/metadata\/([^\/]+)\/([^\/\?]+)$/);
+            
+            if (method === 'GET' && detailMatch) {
+                let [, type, id] = detailMatch;
+
+                // Handle Object Special Logic (Field Formatting)
+                if (type === 'objects' || type === 'object') {
+                    const metadata = app.getObject(id);
+                    if (!metadata) {
+                        return sendError(ErrorCode.NOT_FOUND, `Object '${id}' not found`, 404);
+                    }
+                    
+                    // Convert fields object to array (Standard Object Response)
+                    const fields = metadata.fields 
+                        ? Object.entries(metadata.fields).map(([key, field]) => ({
+                            name: field.name || key,
+                            type: field.type,
+                            label: field.label,
+                            required: field.required,
+                            defaultValue: field.defaultValue,
+                            unique: field.unique,
+                            options: field.options,
+                            min: field.min,
+                            max: field.max,
+                            min_length: field.min_length,
+                            max_length: field.max_length,
+                            regex: field.regex
+                        }))
+                        : [];
+                    
+                    return sendJson({
+                        ...metadata,
+                        fields
+                    });
+                } else {
+                    // Generic Metadata (View, Form, etc.)
+                    const content = app.metadata.get(type, id);
+                    if (!content) {
+                         return sendError(ErrorCode.NOT_FOUND, `${type} '${id}' not found`, 404);
+                    }
+                    return sendJson(content);
+                }
+            }
+
+            // ---------------------------------------------------------
+            // 3. Update Entry (POST/PUT /api/metadata/:type/:id)
+            // ---------------------------------------------------------
+            if ((method === 'POST' || method === 'PUT') && detailMatch) {
+                let [, type, id] = detailMatch;
+                if (type === 'objects') type = 'object';
+
+                const body = await readBody(req);
+                try {
+                    await app.updateMetadata(type, id, body);
+                    return sendJson({ success: true });
+                } catch (e: any) {
+                    const isUserError = e.message.startsWith('Cannot update') || e.message.includes('not found');
+                    return sendError(
+                        isUserError ? ErrorCode.INVALID_REQUEST : ErrorCode.INTERNAL_ERROR,
+                        e.message,
+                        isUserError ? 400 : 500
+                    );
                 }
-                
-                // Convert fields object to array
-                const fields = metadata.fields 
-                    ? Object.entries(metadata.fields).map(([key, field]) => ({
-                        name: field.name || key,
-                        type: field.type,
-                        label: field.label,
-                        required: field.required,
-                        defaultValue: field.defaultValue,
-                        unique: field.unique,
-                        options: field.options,
-                        min: field.min,
-                        max: field.max,
-                        min_length: field.min_length,
-                        max_length: field.max_length,
-                        regex: field.regex
-                    }))
-                    : [];
-                
-                res.setHeader('Content-Type', 'application/json');
-                res.statusCode = 200;
-                res.end(JSON.stringify({
-                    ...metadata,
-                    fields
-                }));
-                return;
             }
 
-            // GET /api/metadata/objects/:name/fields/:field - Get field metadata
+            // ---------------------------------------------------------
+            // 4. Object Sub-resources (Fields, Actions)
+            // ---------------------------------------------------------
+            
+            // GET /api/metadata/objects/:name/fields/:field
+            // Legacy path support.
             const fieldMatch = url.match(/^\/api\/metadata\/objects\/([^\/]+)\/fields\/([^\/\?]+)$/);
             if (method === 'GET' && fieldMatch) {
                 const [, objectName, fieldName] = fieldMatch;
                 const metadata = app.getObject(objectName);
                 
-                if (!metadata) {
-                    res.statusCode = 404;
-                    res.end(JSON.stringify({ 
-                        error: {
-                            code: ErrorCode.NOT_FOUND,
-                            message: `Object '${objectName}' not found`
-                        }
-                    }));
-                    return;
-                }
+                if (!metadata) return sendError(ErrorCode.NOT_FOUND, `Object '${objectName}' not found`, 404);
 
                 const field = metadata.fields?.[fieldName];
-                if (!field) {
-                    res.statusCode = 404;
-                    res.end(JSON.stringify({ 
-                        error: {
-                            code: ErrorCode.NOT_FOUND,
-                            message: `Field '${fieldName}' not found in object '${objectName}'`
-                        }
-                    }));
-                    return;
-                }
+                if (!field) return sendError(ErrorCode.NOT_FOUND, `Field '${fieldName}' not found`, 404);
 
-                res.setHeader('Content-Type', 'application/json');
-                res.statusCode = 200;
-                res.end(JSON.stringify({
+                return sendJson({
                     name: field.name || fieldName,
                     type: field.type,
                     label: field.label,
@@ -144,36 +179,20 @@ export function createMetadataHandler(app: IObjectQL) {
                     min_length: field.min_length,
                     max_length: field.max_length,
                     regex: field.regex
-                }));
-                return;
+                });
             }
 
-            // GET /api/metadata/objects/:name/actions - List actions
+            // GET /api/metadata/objects/:name/actions
             const actionsMatch = url.match(/^\/api\/metadata\/objects\/([^\/]+)\/actions$/);
             if (method === 'GET' && actionsMatch) {
                 const [, objectName] = actionsMatch;
                 const metadata = app.getObject(objectName);
                 
-                if (!metadata) {
-                    res.statusCode = 404;
-                    res.end(JSON.stringify({ 
-                        error: {
-                            code: ErrorCode.NOT_FOUND,
-                            message: `Object '${objectName}' not found`
-                        }
-                    }));
-                    return;
-                }
+                if (!metadata) return sendError(ErrorCode.NOT_FOUND, `Object '${objectName}' not found`, 404);
 
                 const actions = metadata.actions || {};
                 const formattedActions = Object.entries(actions).map(([key, action]) => {
-                    const actionConfig = action as {
-                        type?: string;
-                        label?: string;
-                        params?: Record<string, unknown>;
-                        description?: string;
-                        fields?: Record<string, unknown>;
-                    };
+                    const actionConfig = action as any;
                     const hasFields = !!actionConfig.fields && Object.keys(actionConfig.fields).length > 0;
                     return {
                         name: key,
@@ -184,44 +203,12 @@ export function createMetadataHandler(app: IObjectQL) {
                     };
                 });
 
-                res.setHeader('Content-Type', 'application/json');
-                res.statusCode = 200;
-                res.end(JSON.stringify({ actions: formattedActions }));
-                return;
-            }
-
-            // POST/PUT /api/metadata/:type/:id - Update metadata
-            const updateMatch = url.match(/^\/api\/metadata\/([^\/]+)\/([^\/]+)$/);
-            if ((method === 'POST' || method === 'PUT') && updateMatch) {
-                const [, type, id] = updateMatch;
-                const body = await readBody(req);
-                
-                try {
-                    await app.updateMetadata(type, id, body);
-                    res.setHeader('Content-Type', 'application/json');
-                    res.statusCode = 200;
-                    res.end(JSON.stringify({ success: true }));
-                } catch (e: any) {
-                    const isUserError = e.message.startsWith('Cannot update') || e.message.includes('not found');
-                    res.statusCode = isUserError ? 400 : 500;
-                    res.end(JSON.stringify({ 
-                        error: {
-                            code: isUserError ? ErrorCode.INVALID_REQUEST : ErrorCode.INTERNAL_ERROR,
-                            message: e.message
-                        }
-                    }));
-                }
-                return;
+                return sendJson({ actions: formattedActions });
             }
 
             // Not found
-            res.statusCode = 404;
-            res.end(JSON.stringify({
-                error: {
-                    code: ErrorCode.NOT_FOUND,
-                    message: 'Not Found'
-                }
-            }));
+            sendError(ErrorCode.NOT_FOUND, 'Not Found', 404);
+            
         } catch (e: any) {
             console.error('[Metadata Handler] Error:', e);
             res.statusCode = 500;

package/src/openapi.ts

@@ -20,7 +20,41 @@ export function generateOpenAPI(app: IObjectQL): OpenAPISchema {
     const schemas: Record<string, any> = {};
 
     
-    // 1. Generate Schemas
+    // 1. JSON-RPC Endpoint
+    paths['/api/objectql'] = {
+        post: {
+            summary: 'JSON-RPC Entry Point',
+            description: 'Execute any ObjectQL operation via a JSON body.',
+            tags: ['System'],
+            requestBody: {
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                op: { type: 'string', enum: ['find', 'findOne', 'create', 'update', 'delete', 'count', 'action'] },
+                                object: { type: 'string' },
+                                args: { type: 'object' }
+                            },
+                            required: ['op', 'object']
+                        }
+                    }
+                }
+            },
+            responses: {
+                200: {
+                    description: 'Operation Result',
+                    content: {
+                        'application/json': {
+                            schema: { type: 'object' } // Dynamic result
+                        }
+                    }
+                }
+            }
+        }
+    };
+
+    // 2. Generate Schemas
     for (const obj of objects) {
         const schemaName = obj.name;
         const properties: Record<string, any> = {};
@@ -33,33 +67,23 @@ export function generateOpenAPI(app: IObjectQL): OpenAPISchema {
             type: 'object',
             properties
         };
-
-        // 2. Generate Paths (RPC Style representation for documentation purposes)
-        // Since we only have one endpoint, we might document operations as descriptions
-        // Or if we support REST style in the future, we would add /object paths here.
-        // For now, let's document the "Virtual" REST API that could exist via a gateway
-        // OR just document the schema.
-        // Let's assume the user might want to see standard CRUD paths even if implementation is RPC,
-        // so they can pass it to frontend generators?
-        // No, that would be misleading if the server doesn't support it.
-        
-        // Let's DOCUMENT the RPC operations as if they were paths, 
-        // OR clearer: One path /api/objectql with polymorphic body?
-        // Swagger UI handles oneOf poorly for top level operations sometimes.
     }
     
-    // Let's do a "Virtual" REST path generation for better visualization
-    // Assuming we WILL support REST mapping in this update.
+    // 3. REST API Paths
     for (const obj of objects) {
         const name = obj.name;
+        const basePath = `/api/data/${name}`; // Standard REST Path
         
-        // GET /name (List)
-        paths[`/${name}`] = {
+        // GET /api/data/:name (List)
+        paths[basePath] = {
             get: {
-                summary: `List ${name}s`,
+                summary: `List ${name}`,
                 tags: [name],
                 parameters: [
-                    { name: 'filter', in: 'query', schema: { type: 'string' }, description: 'JSON filter args' }
+                    { name: 'filter', in: 'query', schema: { type: 'string' }, description: 'JSON filter args' },
+                    { name: 'fields', in: 'query', schema: { type: 'string' }, description: 'Comma-separated fields to return' },
+                    { name: 'top', in: 'query', schema: { type: 'integer' }, description: 'Limit' },
+                    { name: 'skip', in: 'query', schema: { type: 'integer' }, description: 'Offset' }
                 ],
                 responses: {
                     200: {
@@ -98,26 +122,50 @@ export function generateOpenAPI(app: IObjectQL): OpenAPISchema {
             }
         };
 
-        // GET /name/{id}
-        paths[`/${name}/{id}`] = {
+        // /api/data/:name/:id
+        paths[`${basePath}/{id}`] = {
             get: {
                 summary: `Get ${name}`,
                 tags: [name],
                 parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
-                responses: { 200: { description: 'Item' } }
+                responses: {
+                    200: {
+                        description: 'Item',
+                        content: {
+                            'application/json': {
+                                schema: { $ref: `#/components/schemas/${name}` }
+                            }
+                        }
+                    }
+                }
             },
             patch: {
-                 summary: `Update ${name}`,
-                 tags: [name],
-                 parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
-                 requestBody: { content: { 'application/json': { schema: { type: 'object', properties: { data: { type: 'object' }} } } } },
-                 responses: { 200: { description: 'Updated' } }
+                summary: `Update ${name}`,
+                tags: [name],
+                parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+                requestBody: {
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                properties: {
+                                    data: { type: 'object' }
+                                }
+                            }
+                        }
+                    }
+                },
+                responses: {
+                    200: { description: 'Updated' }
+                }
             },
             delete: {
-                 summary: `Delete ${name}`,
-                 tags: [name],
-                 parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
-                 responses: { 200: { description: 'Deleted' } }
+                summary: `Delete ${name}`,
+                tags: [name],
+                parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+                responses: {
+                    200: { description: 'Deleted' }
+                }
             }
         };
     }

package/tsconfig.json

@@ -5,5 +5,9 @@
     "rootDir": "src",
     "composite": true
   },
-  "include": ["src/**/*"]
+  "include": ["src/**/*"],
+  "references": [
+    { "path": "../types" },
+    { "path": "../core" }
+  ]
 }