Express

Express Extension

UQL provides a built-in Express middleware to automatically generate RESTful APIs for your entities with zero boilerplate. It is a thin adapter over the framework-agnostic HTTP transport core, which owns the route table, the request/response envelopes, and the hook system; this page covers only what is Express-specific.

Quick Start

import express from 'express';
import { querierMiddleware } from 'uql-orm/express';
import './uql.config.js'; // registers the default querier pool (setQuerierPool)
import { User, Post } from './shared/models/index.js';

const app = express();
app.use(express.json());

// This will automatically generate routes like /api/user and /api/post
app.use('/api', querierMiddleware({
  include: [User, Post]
}));

app.listen(3000);

This mounts the full wire protocol for each entity (list, get, count, create, upsert, bulk operations, delete, plus the QUERY transport). Unknown entities and routes fall through via next(), so the middleware composes with your custom routes (webhooks, payments, SSE) on the same app.

Hooks

The middleware accepts the core’s pre, preSave, preFilter, and post hooks. Under Express, ctx.context is the express.Request, so session and tenant state are directly at hand:

app.use('/api', querierMiddleware({
  include: [User, Post],

  // Intercept save operations (POST, PUT, PATCH)
  preSave(ctx) {
    // Automatically set the creatorId from the session
    ctx.body = { ...(ctx.body as object), creatorId: ctx.context.user.id };
  },

  // Intercept filter operations (GET, DELETE)
  async preFilter({ query, context }) {
    // Enforce Row-Level Security: users only see their own data.
    // Abort by throwing an Error with a numeric status, e.g.
    // throw Object.assign(new Error('unauthorized'), { status: 401 });
    await ensureAuthenticated(context);
    query.$where ??= {};
    Object.assign(query.$where, { creatorId: context.user.id });
  }
}));

Error handling

Errors go to next(err), so your own error middleware keeps working. The exported errorHandler renders the canonical { error: { message, code } } envelope, honoring a numeric status thrown by hooks:

import { errorHandler } from 'uql-orm/express';

app.use('/api', querierMiddleware({ include: [User] }));
app.use(errorHandler);