Skip to main content

Routing

access-router gives you three router classes:

  • RootRouter for batch requests
  • ModelRouter for Mongoose models
  • DataRouter for in-memory collections

The main factory is acl.createRouter(...).

Router Factories​

import mongoose from 'mongoose';
import acl from '@web-ts-toolkit/access-router';

const modelRouter = acl.createRouter('User', { basePath: '/users' });
const dataRouter = acl.createDataRouter('fruit', { basePath: '/fruit', data: [] });
const rootRouter = acl.createRouter({ basePath: '/batch', operationAccess: true });

const typedRouter = acl.createRouter(
  mongoose.model('User', new mongoose.Schema({ name: String })),
  { basePath: '/users' },
);

createAccessRuntime() returns a fresh acl instance with isolated runtime state.

Mounting​

Each router exposes:

  • router for the internal JsonRouter instance
  • routes for the underlying Express router
  • fullBasePath for the normalized mounted path

Use combineRoutes(...) to mount several routers at once.

import express from 'express';
import acl, { combineRoutes } from '@web-ts-toolkit/access-router';

app.use(combineRoutes(fruitRouter, userRouter, rootRouter));
app.use(acl.combineRoutes(fruitRouter, userRouter, rootRouter));

combineRoutes(...) accepts ModelRouter, DataRouter, RootRouter, or a plain Express Router.

Model Router Routes​

Default route segments are __query and __mutation.

  • GET /base for simple list
  • POST /base/__query for advanced list
  • POST /base for create
  • POST /base/__mutation for advanced create
  • GET /base/new for a new-document template
  • GET /base/:id for read by id
  • POST /base/__query/__filter for advanced read by filter
  • POST /base/__query/:id for advanced read by id
  • PATCH /base/:id for update
  • PATCH /base/__mutation/:id for advanced update
  • PUT /base for upsert
  • PUT /base/__mutation for advanced upsert
  • DELETE /base/:id for delete
  • GET /base/count for count
  • POST /base/count for filtered count
  • GET /base/distinct/:field for distinct values
  • POST /base/distinct/:field for filtered distinct values

Sub-document routes are generated for every referenced subpath discovered on the model schema.

For each subdocument path sub, these routes are added:

  • GET /base/:id/sub
  • POST /base/:id/sub/__query
  • PATCH /base/:id/sub
  • GET /base/:id/sub/:subId
  • POST /base/:id/sub/:subId/__query
  • PATCH /base/:id/sub/:subId
  • POST /base/:id/sub
  • DELETE /base/:id/sub/:subId

That gives you generated list, advanced list, bulk update, read, advanced read, update, create, and delete operations for each discovered subdocument collection.

Data Router Routes​

Default route segment is __query.

  • GET /base
  • POST /base/__query
  • GET /base/:id
  • POST /base/__query/__filter
  • POST /base/__query/:id

Root Router​

RootRouter handles batch payloads that dispatch to model or data operations.

Use it when you want a single request to run multiple operations in order.

Each batch item uses:

  • target: model or data
  • name: the model or data router name
  • op: the operation name
  • order: optional execution bucket

Operation-specific fields are kept at the top level:

  • id for single-document operations
  • sub and subId for sub-document operations
  • field for distinct
  • filter for query-based lookups
  • data for writes
  • args for selection, populate, paging, and task inputs
  • options for behavior switches such as permissions and counts

The response wraps each operation as:

{
  index: number;
  target: 'model' | 'data';
  name: string;
  op: string;
  statusCode: number;
  message: string;
  result: unknown;
}

result keeps the underlying service response instead of flattening it into a second batch-only format.

OpenAPI Router​

access-router can also mount a separate documentation router:

app.use(acl.createOpenApiRouter());

By default this exposes:

  • GET /openapi.json
  • GET /docs

You can customize those paths with jsonPath and docsPath, or disable Swagger UI entirely with docsPath: false.

Mutability​

Build-time route-shape options are immutable after router construction.

Model router build-time options:

  • basePath
  • parentPath
  • idParam
  • queryRouteSegment
  • mutationRouteSegment

Data router build-time options:

  • basePath
  • parentPath
  • idParam
  • queryRouteSegment

Behavior options such as filters, hooks, permissions, and defaults can be changed later with set(...), setOption(...), or setOptions(...).