@objectql/api 1.0.0

package/src/index.ts

@@ -0,0 +1,294 @@
+import { Router, Request, Response, NextFunction } from 'express';
+import { IObjectQL, ObjectQLContext, UnifiedQuery } from '@objectql/core';
+import * as path from 'path';
+import swaggerUi from 'swagger-ui-express';
+import { generateOpenApiSpec } from './swagger/generator';
+
+export interface ObjectQLServerOptions {
+    objectql: IObjectQL;
+    getContext?: (req: Request, res: Response) => Promise<ObjectQLContext> | ObjectQLContext;
+    swagger?: {
+        enabled: boolean;
+        path?: string; // default: /docs
+    }
+}
+
+export function createObjectQLRouter(options: ObjectQLServerOptions): Router {
+    const router = Router();
+    const { objectql, getContext, swagger } = options;
+
+    if (swagger && swagger.enabled) {
+        const docPath = swagger.path || '/docs';
+        const spec = generateOpenApiSpec(objectql);
+        router.use(docPath, swaggerUi.serve, swaggerUi.setup(spec));
+        console.log(`Swagger UI available at ${docPath}`);
+    }
+
+    const getCtx = async (req: Request, res: Response): Promise<ObjectQLContext> => {
+        if (getContext) {
+            return await getContext(req, res);
+        }
+        return {
+            roles: [],
+            object: (name: string) => { throw new Error("Not implemented in default context stub"); },
+            transaction: async (cb: any) => cb({} as any),
+            sudo: () => ({} as any)
+        } as unknown as ObjectQLContext;
+    };
+
+    const getRepo = async (req: Request, res: Response, objectName: string) => {
+        const ctx = await getCtx(req, res);
+        return ctx.object(objectName);
+    };
+
+    // Helper: Parse UnifiedQuery from Request
+    const parseQuery = (req: Request): UnifiedQuery => {
+        const query: UnifiedQuery = {};
+        const q = req.query;
+
+        // 1. Fields
+        if (q.fields) {
+            if (typeof q.fields === 'string') {
+                query.fields = q.fields.split(',');
+            }
+        }
+
+        // 2. Filters
+        if (q.filters) {
+            try {
+                if (typeof q.filters === 'string') {
+                    query.filters = JSON.parse(q.filters);
+                }
+            } catch (e) {
+                throw new Error("Invalid filters JSON");
+            }
+        }
+
+        // 3. Sort
+        // Format: ?sort=item1:asc,item2:desc  OR  ?sort=[["item1","asc"]]
+        if (q.sort) {
+            if (typeof q.sort === 'string') {
+                // Check if JSON
+                if (q.sort.startsWith('[')) {
+                    try {
+                        query.sort = JSON.parse(q.sort);
+                    } catch {}
+                } else {
+                    // split by comma
+                    query.sort = q.sort.split(',').map(part => {
+                        const [field, order] = part.split(':');
+                        return [field, (order || 'asc').toLowerCase() === 'desc' ? 'desc' : 'asc'];
+                    });
+                }
+            }
+        }
+
+        // 4. Pagination
+        if (q.top || q.limit) {
+            query.limit = parseInt((q.top || q.limit) as string);
+        }
+        if (q.skip || q.offset) {
+            query.skip = parseInt((q.skip || q.offset) as string);
+        }
+
+        // 5. Expand
+        // ?expand=items,details  OR ?expand={"items":{"fields":["name"]}}
+        if (q.expand) {
+            if (typeof q.expand === 'string') {
+                if (q.expand.startsWith('{')) {
+                    try {
+                        query.expand = JSON.parse(q.expand);
+                    } catch {}
+                } else {
+                    query.expand = {};
+                    q.expand.split(',').forEach(field => {
+                        // Simple expand implies selecting all or default fields
+                        // UnifiedQuery expects sub-query
+                        query.expand![field] = {}; 
+                    });
+                }
+            }
+        }
+
+        return query;
+    };
+
+    // === Special Endpoints (Must come before /:objectName) ===
+
+    router.get('/_schema', async (req: Request, res: Response) => {
+        try {
+            const configs = objectql.getConfigs();
+            res.json(configs);
+        } catch (e: any) {
+             res.status(500).json({ error: e.message });
+        }
+    });
+
+    // NONE for now, as :objectName is the root.
+    // However, we might want /:objectName/count or /:objectName/aggregate.
+
+
+    // === Collection Routes ===
+
+    // count
+    router.get('/:objectName/count', async (req: Request, res: Response) => {
+        try {
+            const { objectName } = req.params;
+            const repo = await getRepo(req, res, objectName);
+            let filters = undefined;
+            if (req.query.filters) {
+                try {
+                    filters = JSON.parse(req.query.filters as string);
+                } catch {
+                    return res.status(400).json({ error: "Invalid filters JSON" });
+                }
+            }
+            const count = await repo.count(filters);
+            res.json({ count });
+        } catch (e: any) {
+             res.status(500).json({ error: e.message });
+        }
+    });
+
+    // aggregate
+    router.post('/:objectName/aggregate', async (req: Request, res: Response) => {
+        try {
+            const { objectName } = req.params;
+            const repo = await getRepo(req, res, objectName);
+            const pipeline = req.body;
+            if (!Array.isArray(pipeline)) {
+                return res.status(400).json({ error: "Pipeline must be an array" });
+            }
+            const result = await repo.aggregate(pipeline);
+            res.json(result);
+        } catch (e: any) {
+             res.status(500).json({ error: e.message });
+        }
+    });
+
+    // delete many
+    router.delete('/:objectName', async (req: Request, res: Response) => {
+        try {
+            const { objectName } = req.params;
+            if (!req.query.filters) {
+                return res.status(400).json({ error: "filters parameter is required for bulk delete" });
+            }
+            const repo = await getRepo(req, res, objectName);
+            let filters;
+             try {
+                filters = JSON.parse(req.query.filters as string);
+            } catch {
+                return res.status(400).json({ error: "Invalid filters JSON" });
+            }
+            const result = await repo.deleteMany(filters);
+            res.json(result);
+        } catch (e: any) {
+             res.status(500).json({ error: e.message });
+        }
+    });
+
+    // list
+    router.get('/:objectName', async (req: Request, res: Response) => {
+        try {
+            const { objectName } = req.params;
+            const repo = await getRepo(req, res, objectName);
+            const query = parseQuery(req);
+            const results = await repo.find(query);
+            res.json(results);
+        } catch (e: any) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // create (one or many)
+    router.post('/:objectName', async (req: Request, res: Response) => {
+        try {
+            const { objectName } = req.params;
+            const repo = await getRepo(req, res, objectName);
+            if (Array.isArray(req.body)) {
+                const results = await repo.createMany(req.body);
+                res.status(201).json(results);
+            } else {
+                const result = await repo.create(req.body);
+                res.status(201).json(result);
+            }
+        } catch (e: any) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    // === Item Routes ===
+
+    // run action
+    router.post('/:objectName/:id/:actionName', async (req: Request, res: Response) => {
+         try {
+            const { objectName, id, actionName } = req.params;
+            const repo = await getRepo(req, res, objectName);
+            // Params merging body and id? Usually action needs specific params.
+            // Let's pass body as params.
+            const params = {
+                id,
+                ...req.body
+            };
+            const result = await repo.call(actionName, params);
+            res.json(result);
+        } catch (e: any) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    router.get('/:objectName/:id', async (req: Request, res: Response) => {
+        try {
+            const { objectName, id } = req.params;
+            const repo = await getRepo(req, res, objectName);
+            
+            // Allow expand here too?
+            // findOne takes id or query.
+            // If expand is needed, we should construct a query with filters: {_id: id}
+            
+            if (req.query.expand || req.query.fields) {
+                const query = parseQuery(req);
+                // Force filter by ID
+                // Note: normalized ID vs string ID.
+                query.filters = [['_id', '=', id]]; // or 'id' depending on driver
+                const results = await repo.find(query);
+                if (!results.length) {
+                    return res.status(404).json({ error: "Not found" });
+                }
+                return res.json(results[0]);
+            }
+
+            const result = await repo.findOne(id);
+            if (!result) {
+                return res.status(404).json({ error: "Not found" });
+            }
+            res.json(result);
+        } catch (e: any) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    router.put('/:objectName/:id', async (req: Request, res: Response) => {
+        try {
+            const { objectName, id } = req.params;
+            const repo = await getRepo(req, res, objectName);
+            const result = await repo.update(id, req.body);
+            res.json(result);
+        } catch (e: any) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    router.delete('/:objectName/:id', async (req: Request, res: Response) => {
+        try {
+            const { objectName, id } = req.params;
+            const repo = await getRepo(req, res, objectName);
+            await repo.delete(id);
+            res.status(204).send();
+        } catch (e: any) {
+            res.status(500).json({ error: e.message });
+        }
+    });
+
+    return router;
+}

package/src/swagger/generator.ts

@@ -0,0 +1,171 @@
+import { IObjectQL, ObjectConfig, FieldConfig } from '@objectql/core';
+
+export function generateOpenApiSpec(objectql: IObjectQL) {
+  const configs = objectql.getConfigs();
+  
+  const paths: any = {};
+  const schemas: any = {};
+
+  Object.values(configs).forEach((config) => {
+    const objectName = config.name;
+    const schemaName = objectName;
+
+    // 1. Define Schema
+    schemas[schemaName] = {
+      type: 'object',
+      properties: mapFieldsToProperties(config.fields)
+    };
+
+    // 2. Define Paths
+    const basePath = `/api/${objectName}`;
+    
+    // GET /api/{obj} - List
+    paths[basePath] = {
+      get: {
+        summary: `List ${config.label || objectName}`,
+        tags: [config.label || objectName],
+        parameters: [
+          {
+            name: 'fields',
+            in: 'query',
+            description: 'Comma separated fields to return',
+            schema: { type: 'string' }
+          },
+          {
+            name: 'filters',
+            in: 'query',
+            description: 'JSON string of filters',
+            schema: { type: 'string' }
+          },
+        ],
+        responses: {
+          200: {
+            description: 'Success',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'array',
+                  items: { $ref: `#/components/schemas/${schemaName}` }
+                }
+              }
+            }
+          }
+        }
+      },
+      // POST /api/{obj} - Create
+      post: {
+        summary: `Create ${config.label || objectName}`,
+        tags: [config.label || objectName],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: { $ref: `#/components/schemas/${schemaName}` }
+            }
+          }
+        },
+        responses: {
+          201: {
+            description: 'Created',
+            content: {
+              'application/json': {
+                 schema: { $ref: `#/components/schemas/${schemaName}` }
+              }
+            }
+          }
+        }
+      }
+    };
+
+    // /{id} operations
+    const itemPath = `${basePath}/{id}`;
+    paths[itemPath] = {
+      // GET - Retrieve
+      get: {
+        summary: `Get ${config.label || objectName}`,
+        tags: [config.label || objectName],
+        parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+        responses: {
+          200: {
+            description: 'Success',
+            content: {
+                'application/json': {
+                   schema: { $ref: `#/components/schemas/${schemaName}` }
+                }
+            }
+          }
+        }
+      },
+      // PUT - Update
+      put: {
+        summary: `Update ${config.label || objectName}`,
+        tags: [config.label || objectName],
+        parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                  type: 'object',
+                  properties: mapFieldsToProperties(config.fields)
+              }
+            }
+          }
+        },
+        responses: {
+          200: { description: 'Updated' }
+        }
+      },
+      // DELETE
+      delete: {
+        summary: `Delete ${config.label || objectName}`,
+        tags: [config.label || objectName],
+        parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+        responses: {
+          200: { description: 'Deleted' }
+        }
+      }
+    };
+
+  });
+
+  return {
+    openapi: '3.0.0',
+    info: {
+      title: 'ObjectQL API',
+      version: '1.0.0',
+    },
+    paths,
+    components: {
+      schemas
+    }
+  };
+}
+
+function mapFieldsToProperties(fields: Record<string, FieldConfig>) {
+  const props: any = {};
+  Object.entries(fields).forEach(([key, field]) => {
+    props[key] = {
+      type: mapType(field.type),
+      description: field.label
+    };
+  });
+  // Add _id
+  props['_id'] = { type: 'string' };
+  return props;
+}
+
+function mapType(objectType: string) {
+  switch (objectType) {
+    case 'number':
+    case 'currency':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'date':
+    case 'datetime':
+      return 'string'; // format: date-time ideally
+    default:
+      return 'string';
+  }
+}

package/test/index.test.ts

@@ -0,0 +1,150 @@
+import { createObjectQLRouter } from '../src';
+import { IObjectQL } from '@objectql/core';
+import express from 'express';
+import request from 'supertest';
+
+describe('createObjectQLRouter', () => {
+    let mockObjectQL: any;
+    let mockRepo: any;
+    let mockGetContext: jest.Mock;
+    let app: express.Express;
+
+    beforeEach(() => {
+        // Mock Repository methods
+        mockRepo = {
+            find: jest.fn().mockResolvedValue([{ id: 1, name: 'Test' }]),
+            findOne: jest.fn().mockResolvedValue({ id: 1, name: 'Test' }),
+            count: jest.fn().mockResolvedValue(10),
+            aggregate: jest.fn().mockResolvedValue([]),
+            create: jest.fn().mockResolvedValue({ id: 2, name: 'New' }),
+            createMany: jest.fn().mockResolvedValue([{ id: 2, name: 'New' }]),
+            update: jest.fn().mockResolvedValue({ id: 1, name: 'Updated' }),
+            delete: jest.fn().mockResolvedValue(undefined),
+            deleteMany: jest.fn().mockResolvedValue({ deletedCount: 5 }),
+            call: jest.fn().mockResolvedValue({ result: 'ok' })
+        };
+
+        mockObjectQL = {
+            init: jest.fn(),
+            getConfigs: jest.fn().mockReturnValue([{ name: 'user', fields: {} }])
+        };
+
+        // Mock getContext to return a context that returns our mockRepo
+        mockGetContext = jest.fn().mockResolvedValue({
+            object: jest.fn().mockReturnValue(mockRepo),
+            roles: [],
+            transaction: jest.fn(),
+            sudo: jest.fn()
+        });
+
+        app = express();
+        app.use(express.json()); // Important for POST/PUT tests
+    });
+
+    it('should create a router', () => {
+        const router = createObjectQLRouter({ objectql: mockObjectQL });
+        expect(router).toBeDefined();
+        expect(typeof router).toBe('function');
+    });
+
+    it('should mount swagger if enabled', async () => {
+        const router = createObjectQLRouter({ 
+            objectql: mockObjectQL,
+            swagger: { enabled: true }
+        });
+        
+        app.use(router);
+        expect(router).toBeDefined();
+    });
+
+    describe('REST API Endpoints', () => {
+        beforeEach(() => {
+            const router = createObjectQLRouter({ 
+                objectql: mockObjectQL,
+                getContext: mockGetContext
+            });
+            app.use('/api', router);
+        });
+
+        it('GET /_schema should return configs', async () => {
+            const res = await request(app).get('/api/_schema');
+            expect(res.status).toBe(200);
+            expect(res.body).toEqual([{ name: 'user', fields: {} }]);
+            expect(mockObjectQL.getConfigs).toHaveBeenCalled();
+        });
+
+        it('GET /:objectName/count should return count', async () => {
+            const res = await request(app)
+                .get('/api/users/count')
+                .query({ filters: JSON.stringify([['age', '>', 20]]) });
+            
+            expect(res.status).toBe(200);
+            expect(res.body).toEqual({ count: 10 });
+            expect(mockRepo.count).toHaveBeenCalledWith([['age', '>', 20]]);
+        });
+
+        it('GET /:objectName should list objects', async () => {
+            const res = await request(app)
+                .get('/api/users')
+                .query({ 
+                    limit: 10, 
+                    skip: 0, 
+                    sort: 'name:asc', 
+                    fields: 'id,name' 
+                });
+
+            expect(res.status).toBe(200);
+            expect(res.body).toHaveLength(1);
+            expect(mockRepo.find).toHaveBeenCalledWith(expect.objectContaining({
+                limit: 10,
+                skip: 0,
+                // sort parsing: 'name:asc' -> [['name', 'asc']]
+                sort: [['name', 'asc']],
+                fields: ['id', 'name']
+            }));
+        });
+
+        it('GET /:objectName/:id should get one object', async () => {
+            const res = await request(app).get('/api/users/1');
+            expect(res.status).toBe(200);
+            expect(res.body).toEqual({ id: 1, name: 'Test' });
+            expect(mockRepo.findOne).toHaveBeenCalledWith('1');
+        });
+
+        it('POST /:objectName should create object', async () => {
+            const res = await request(app)
+                .post('/api/users')
+                .send({ name: 'New' });
+            
+            expect(res.status).toBe(201);
+            expect(res.body).toEqual({ id: 2, name: 'New' });
+            expect(mockRepo.create).toHaveBeenCalledWith({ name: 'New' });
+        });
+
+        it('PUT /:objectName/:id should update object', async () => {
+            const res = await request(app)
+                .put('/api/users/1')
+                .send({ name: 'Updated' });
+            
+            expect(res.status).toBe(200);
+            expect(res.body).toEqual({ id: 1, name: 'Updated' });
+            expect(mockRepo.update).toHaveBeenCalledWith('1', { name: 'Updated' });
+        });
+
+        it('DELETE /:objectName/:id should delete object', async () => {
+            const res = await request(app).delete('/api/users/1');
+            expect(res.status).toBe(204);
+            expect(mockRepo.delete).toHaveBeenCalledWith('1');
+        });
+
+        it('POST /:objectName/:id/:actionName should execute action', async () => {
+            const res = await request(app)
+                .post('/api/users/1/activate')
+                .send({ reason: 'testing' });
+            
+            expect(res.status).toBe(200);
+            expect(res.body).toEqual({ result: 'ok' });
+            expect(mockRepo.call).toHaveBeenCalledWith('activate', { id: '1', reason: 'testing' });
+        });
+    });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}