@objectql/server 1.7.1 → 1.7.3

package/src/server.ts

@@ -58,17 +58,27 @@ export class ObjectQLServer {
             switch (req.op) {
                 case 'find':
                     result = await repo.find(req.args);
-                    break;
+                    // For find operations, return items array with pagination metadata
+                    return this.buildListResponse(result, req.args, repo);
                 case 'findOne':
                     // Support both string ID and query object
                     result = await repo.findOne(req.args);
-                    break;
+                    if (result) {
+                        return { ...result, '@type': req.object };
+                    }
+                    return result;
                 case 'create':
                     result = await repo.create(req.args);
-                    break;
+                    if (result) {
+                        return { ...result, '@type': req.object };
+                    }
+                    return result;
                 case 'update':
                     result = await repo.update(req.args.id, req.args.data);
-                    break;
+                    if (result) {
+                        return { ...result, '@type': req.object };
+                    }
+                    return result;
                 case 'delete':
                     result = await repo.delete(req.args.id);
                     if (!result) {
@@ -77,12 +87,15 @@ export class ObjectQLServer {
                             `Record with id '${req.args.id}' not found for delete`
                         );
                     }
-                    // Return standardized delete response on success
-                    result = { id: req.args.id, deleted: true };
-                    break;
+                    // Return standardized delete response with object type
+                    return { 
+                        id: req.args.id,
+                        deleted: true,
+                        '@type': req.object
+                    };
                 case 'count':
                     result = await repo.count(req.args);
-                    break;
+                    return { count: result, '@type': req.object };
                 case 'action':
                     // Map generic args to ActionContext
                     result = await app.executeAction(req.object, req.args.action, {
@@ -90,7 +103,10 @@ export class ObjectQLServer {
                          id: req.args.id,
                          input: req.args.input || req.args.params // Support both for convenience
                     });
-                    break;
+                    if (result && typeof result === 'object') {
+                        return { ...result, '@type': req.object };
+                    }
+                    return result;
                 default:
                     return this.errorResponse(
                         ErrorCode.INVALID_REQUEST,
@@ -98,13 +114,44 @@ export class ObjectQLServer {
                     );
             }
 
-            return { data: result };
-
         } catch (e: any) {
             return this.handleError(e);
         }
     }
 
+    /**
+     * Build a standardized list response with pagination metadata
+     */
+    private async buildListResponse(items: any[], args: any, repo: any): Promise<ObjectQLResponse> {
+        const response: ObjectQLResponse = {
+            items
+        };
+
+        // Calculate pagination metadata if limit/skip are present
+        if (args && (args.limit || args.skip)) {
+            const skip = args.skip || 0;
+            const limit = args.limit || items.length;
+            
+            // Get total count - use the same arguments as the query to ensure consistency
+            const total = await repo.count(args || {});
+            
+            const size = limit;
+            const page = limit > 0 ? Math.floor(skip / limit) + 1 : 1;
+            const pages = limit > 0 ? Math.ceil(total / limit) : 1;
+            const has_next = skip + items.length < total;
+
+            response.meta = {
+                total,
+                page,
+                size,
+                pages,
+                has_next
+            };
+        }
+
+        return response;
+    }
+
     /**
      * Handle errors and convert them to appropriate error responses
      */

package/src/types.ts

@@ -60,19 +60,35 @@ export interface ErrorDetails {
     [key: string]: unknown;
 }
 
+/**
+ * Pagination metadata
+ */
+export interface PaginationMeta {
+    total: number;        // Total number of records
+    page?: number;        // Current page number (1-indexed, e.g. page 1 corresponds to skip=0)
+    size?: number;        // Number of items per page
+    pages?: number;       // Total number of pages
+    has_next?: boolean;   // Whether there is a next page
+}
+
 /**
  * ObjectQL API response
  */
 export interface ObjectQLResponse {
-    data?: any;
+    // For list operations (find)
+    items?: any[];
+    
+    // Pagination metadata (for list operations)
+    meta?: PaginationMeta;
+    
+    // Error information
     error?: {
         code: ErrorCode | string;
         message: string;
-        details?: ErrorDetails;
-    };
-    meta?: {
-        total?: number;
-        page?: number;
-        per_page?: number;
+        details?: ErrorDetails | any; // Allow flexible details structure
     };
+    
+    // For single item operations, the response is the object itself with '@type' field
+    // This allows any additional fields from the actual data object
+    [key: string]: any;
 }

package/test/integration-example.ts

@@ -0,0 +1,247 @@
+/**
+ * Integration Example: Demonstrates the new standardized API response format
+ * 
+ * This file is for documentation purposes and shows how the API responses
+ * look with the new standardized format.
+ */
+
+import { ObjectQL } from '@objectql/core';
+import { createRESTHandler } from '../src/adapters/rest';
+import { Driver } from '@objectql/types';
+
+// Example: Setting up ObjectQL with a simple in-memory driver
+class InMemoryDriver implements Driver {
+    private data: Record<string, any[]> = {};
+
+    async init() {}
+    
+    async find(objectName: string, query: any) {
+        let items = this.data[objectName] || [];
+        
+        // Apply skip and limit for pagination
+        if (query) {
+            if (query.skip) {
+                items = items.slice(query.skip);
+            }
+            if (query.limit) {
+                items = items.slice(0, query.limit);
+            }
+        }
+        
+        return items;
+    }
+    
+    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) {
+        if (!this.data[objectName]) {
+            this.data[objectName] = [];
+        }
+        const newItem = { ...data, id: String(Date.now()) };
+        this.data[objectName].push(newItem);
+        return newItem;
+    }
+    
+    async update(objectName: string, id: string | number, data: any) {
+        const items = this.data[objectName] || [];
+        const index = items.findIndex(item => item.id === String(id));
+        if (index >= 0) {
+            this.data[objectName][index] = { ...items[index], ...data };
+            return this.data[objectName][index];
+        }
+        return null;
+    }
+    
+    async delete(objectName: string, id: string | number) {
+        const items = this.data[objectName] || [];
+        const index = items.findIndex(item => item.id === String(id));
+        if (index >= 0) {
+            this.data[objectName].splice(index, 1);
+            return 1;
+        }
+        return 0;
+    }
+    
+    async count(objectName: string) {
+        return (this.data[objectName] || []).length;
+    }
+    
+    // Seed some sample data
+    seed(objectName: string, items: any[]) {
+        this.data[objectName] = items;
+    }
+}
+
+// Initialize ObjectQL
+const driver = new InMemoryDriver();
+const app = new ObjectQL({
+    datasources: {
+        default: driver
+    }
+});
+
+// Register a simple object schema
+app.metadata.register('object', {
+    type: 'object',
+    id: 'contract',
+    content: {
+        name: 'contract',
+        label: 'Contract',
+        fields: {
+            name: { type: 'text', label: 'Contract Name' },
+            amount: { type: 'number', label: 'Amount' },
+            status: { type: 'text', label: 'Status' }
+        }
+    }
+});
+
+// Seed sample data
+driver.seed('contract', [
+    { id: '1', name: 'Contract A', amount: 5000, status: 'active' },
+    { id: '2', name: 'Contract B', amount: 3000, status: 'pending' },
+    { id: '3', name: 'Contract C', amount: 7500, status: 'active' },
+    { id: '4', name: 'Contract D', amount: 2000, status: 'completed' },
+    { id: '5', name: 'Contract E', amount: 9000, status: 'active' },
+]);
+
+/**
+ * Example 1: List all contracts (no pagination)
+ * 
+ * Request:  GET /api/data/contract
+ * 
+ * Response:
+ * {
+ *   "items": [
+ *     { "id": "1", "name": "Contract A", "amount": 5000, "status": "active" },
+ *     { "id": "2", "name": "Contract B", "amount": 3000, "status": "pending" },
+ *     { "id": "3", "name": "Contract C", "amount": 7500, "status": "active" },
+ *     { "id": "4", "name": "Contract D", "amount": 2000, "status": "completed" },
+ *     { "id": "5", "name": "Contract E", "amount": 9000, "status": "active" }
+ *   ]
+ * }
+ */
+
+/**
+ * Example 2: List contracts with pagination (first page)
+ * 
+ * Request:  GET /api/data/contract?limit=2&skip=0
+ * 
+ * Response:
+ * {
+ *   "items": [
+ *     { "id": "1", "name": "Contract A", "amount": 5000, "status": "active" },
+ *     { "id": "2", "name": "Contract B", "amount": 3000, "status": "pending" }
+ *   ],
+ *   "meta": {
+ *     "total": 5,
+ *     "page": 1,
+ *     "size": 2,
+ *     "pages": 3,
+ *     "has_next": true
+ *   }
+ * }
+ */
+
+/**
+ * Example 3: List contracts with pagination (second page)
+ * 
+ * Request:  GET /api/data/contract?limit=2&skip=2
+ * 
+ * Response:
+ * {
+ *   "items": [
+ *     { "id": "3", "name": "Contract C", "amount": 7500, "status": "active" },
+ *     { "id": "4", "name": "Contract D", "amount": 2000, "status": "completed" }
+ *   ],
+ *   "meta": {
+ *     "total": 5,
+ *     "page": 2,
+ *     "size": 2,
+ *     "pages": 3,
+ *     "has_next": true
+ *   }
+ * }
+ */
+
+/**
+ * Example 4: Get a single contract
+ * 
+ * Request:  GET /api/data/contract/1
+ * 
+ * Response:
+ * {
+ *   "data": {
+ *     "id": "1",
+ *     "name": "Contract A",
+ *     "amount": 5000,
+ *     "status": "active"
+ *   }
+ * }
+ */
+
+/**
+ * Example 5: Create a new contract
+ * 
+ * Request:  POST /api/data/contract
+ * Body:     { "name": "Contract F", "amount": 4500, "status": "pending" }
+ * 
+ * Response:
+ * {
+ *   "data": {
+ *     "id": "6",
+ *     "name": "Contract F",
+ *     "amount": 4500,
+ *     "status": "pending"
+ *   }
+ * }
+ */
+
+/**
+ * Example 6: Update a contract
+ * 
+ * Request:  PUT /api/data/contract/1
+ * Body:     { "status": "completed" }
+ * 
+ * Response:
+ * {
+ *   "data": {
+ *     "id": "1",
+ *     "name": "Contract A",
+ *     "amount": 5000,
+ *     "status": "completed"
+ *   }
+ * }
+ */
+
+/**
+ * Example 7: Delete a contract
+ * 
+ * Request:  DELETE /api/data/contract/1
+ * 
+ * Response:
+ * {
+ *   "data": {
+ *     "id": "1",
+ *     "deleted": true
+ *   }
+ * }
+ */
+
+/**
+ * Example 8: Error response (not found)
+ * 
+ * Request:  GET /api/data/contract/999
+ * 
+ * Response:
+ * {
+ *   "error": {
+ *     "code": "NOT_FOUND",
+ *     "message": "Record not found"
+ *   }
+ * }
+ */
+
+export { app, driver };

package/test/node.test.ts

@@ -60,7 +60,7 @@ describe('Node Adapter', () => {
 
         expect(response.status).toBe(200);
         expect(response.body).toEqual({
-            data: [{ id: 1, name: 'Alice' }]
+            items: [{ id: 1, name: 'Alice' }]
         });
     });
 
@@ -78,7 +78,9 @@ describe('Node Adapter', () => {
 
         expect(response.status).toBe(200);
         expect(response.body).toEqual({
-            data: { id: 2, name: 'Bob' }
+            id: 2,
+            name: 'Bob',
+            '@type': 'user'
         });
     });
 

package/test/rest.test.ts

@@ -17,7 +17,19 @@ class MockDriver implements Driver {
     async init() {}
     
     async find(objectName: string, query: any) {
-        return this.data[objectName] || [];
+        let items = this.data[objectName] || [];
+        
+        // Apply skip and limit if provided
+        if (query) {
+            if (query.skip) {
+                items = items.slice(query.skip);
+            }
+            if (query.limit) {
+                items = items.slice(0, query.limit);
+            }
+        }
+        
+        return items;
     }
     
     async findOne(objectName: string, id: string | number, query?: any, options?: any) {
@@ -101,8 +113,8 @@ describe('REST API Adapter', () => {
             .set('Accept', 'application/json');
 
         expect(response.status).toBe(200);
-        expect(response.body.data).toHaveLength(2);
-        expect(response.body.data[0].name).toBe('Alice');
+        expect(response.body.items).toHaveLength(2);
+        expect(response.body.items[0].name).toBe('Alice');
     });
 
     it('should handle GET /api/data/:object/:id - Get single record', async () => {
@@ -111,7 +123,8 @@ describe('REST API Adapter', () => {
             .set('Accept', 'application/json');
 
         expect(response.status).toBe(200);
-        expect(response.body.data.name).toBe('Alice');
+        expect(response.body.name).toBe('Alice');
+        expect(response.body['@type']).toBe('user');
     });
 
     it('should handle POST /api/data/:object - Create record', async () => {
@@ -121,8 +134,9 @@ describe('REST API Adapter', () => {
             .set('Accept', 'application/json');
 
         expect(response.status).toBe(201);
-        expect(response.body.data.name).toBe('Charlie');
-        expect(response.body.data._id).toBeDefined();
+        expect(response.body.name).toBe('Charlie');
+        expect(response.body._id).toBeDefined();
+        expect(response.body['@type']).toBe('user');
     });
 
     it('should handle PUT /api/data/:object/:id - Update record', async () => {
@@ -140,7 +154,8 @@ describe('REST API Adapter', () => {
             .set('Accept', 'application/json');
 
         expect(response.status).toBe(200);
-        expect(response.body.data.deleted).toBe(true);
+        expect(response.body.deleted).toBe(true);
+        expect(response.body['@type']).toBe('user');
     });
 
     it('should return 404 for non-existent object', async () => {
@@ -161,4 +176,29 @@ describe('REST API Adapter', () => {
         expect(response.status).toBe(400);
         expect(response.body.error.code).toBe('INVALID_REQUEST');
     });
+
+    it('should include pagination metadata with limit and skip', async () => {
+        const response = await request(server)
+            .get('/api/data/user?limit=1&skip=0')
+            .set('Accept', 'application/json');
+
+        expect(response.status).toBe(200);
+        expect(response.body.items).toBeDefined();
+        expect(response.body.meta).toBeDefined();
+        expect(response.body.meta.total).toBe(2);
+        expect(response.body.meta.page).toBe(1);
+        expect(response.body.meta.size).toBe(1);
+        expect(response.body.meta.pages).toBe(2);
+        expect(response.body.meta.has_next).toBe(true);
+    });
+
+    it('should calculate pagination metadata correctly for second page', async () => {
+        const response = await request(server)
+            .get('/api/data/user?limit=1&skip=1')
+            .set('Accept', 'application/json');
+
+        expect(response.status).toBe(200);
+        expect(response.body.meta.page).toBe(2);
+        expect(response.body.meta.has_next).toBe(false);
+    });
 });