@objectql/server

Generic HTTP Server Adapter for ObjectQL. Allows running ObjectQL on Node.js, Express, Next.js, etc.

Installation

pnpm add @objectql/server

Usage

Node.js (Raw HTTP)

import { createNodeHandler } from '@objectql/server';
import { app } from './objectql'; // Your initialized ObjectQL instance
import { createServer } from 'http';

const handler = createNodeHandler(app);
const server = createServer(handler);
server.listen(3000);

Express

import express from 'express';
import { createNodeHandler } from '@objectql/server';
import { app } from './objectql';

const server = express();

// Optional: Mount express.json() if you want, but ObjectQL handles parsing too.
// server.use(express.json());

// Mount the handler
server.all('/api/objectql', createNodeHandler(app));

server.listen(3000);

Next.js (API Routes)

// pages/api/objectql.ts
import { createNodeHandler } from '@objectql/server';
import { app } from '../../lib/objectql';

export const config = {
  api: {
    bodyParser: false, // ObjectQL handles body parsing
  },
};

export default createNodeHandler(app);

API Response Format

ObjectQL uses a standardized response format for all operations:

List Operations (find)

List operations return data in an items array with optional pagination metadata:

{
  "items": [
    {
      "id": "1001",
      "name": "Contract A",
      "amount": 5000
    },
    {
      "id": "1002",
      "name": "Contract B",
      "amount": 3000
    }
  ],
  "meta": {
    "total": 105,       // Total number of records
    "page": 1,          // Current page number (1-indexed)
    "size": 20,         // Number of items per page
    "pages": 6,         // Total number of pages
    "has_next": true    // Whether there is a next page
  }
}

Note: The meta object is only included when pagination parameters (limit and/or skip) are used.

Single Item Operations (findOne, create, update, delete)

Single item operations return data in a data field with an @type identifier:

{
  "data": {
    "_id": "1001",
    "name": "Contract A",
    "amount": 5000,
    "@type": "contract"
  }
}

Note: The @type field indicates the object type, and _id is the unique identifier.

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Record not found",
    "details": {
      "field": "id",
      "reason": "No record found with the given ID"
    }
  }
}

REST API Endpoints

The server exposes the following REST endpoints:

• GET /api/data/:object - List records (supports ?limit=10&skip=0 for pagination)
• GET /api/data/:object/:id - Get single record
• POST /api/data/:object - Create record
• PUT /api/data/:object/:id - Update record
• DELETE /api/data/:object/:id - Delete record

Pagination Example

# Get first page (10 items)
GET /api/data/contracts?limit=10&skip=0

# Get second page (10 items)
GET /api/data/contracts?limit=10&skip=10

Metadata API Endpoints

• GET /api/metadata/object - List all objects
• GET /api/metadata/object/:name - Get object definition
• GET /api/metadata/object/:name/actions - List object actions

All metadata list endpoints return data in the standardized items format.