Skip to main content

@web-ts-toolkit/access-router

ACL-aware Express routers and in-memory data services for Mongoose-backed APIs.

Installation​

npm install @web-ts-toolkit/access-router express mongoose

Requires Node.js >=22, Express >=5 and Mongoose >=8. TypeScript applications also need typescript, @types/node and @types/express. The installed package README contains a self-contained quick start, configuration map and migration guide.

What It Exposes​

Main entrypoint:

  • default export acl — canonical shared-runtime API; named acl is identical
  • createAccessRuntime() for isolated runtime state
  • createOpenApiRouter(...) for /openapi.json and Swagger UI routes
  • combineRoutes(...) for mounting multiple routers together
  • guard(...) for route guards
  • permissionsPlugin — optional hydrated-document metadata alias, not field enforcement
  • RootRouter, ModelRouter, DataRouter
  • global/model option helpers; data option helpers are on the owning api.runtime

Low-level entrypoints:

  • @web-ts-toolkit/access-router/advanced (also re-exports the correlated-include wire types ParentRef, CorrelatedInclude, and Include without deep imports)
  • @web-ts-toolkit/access-router/processors

Quick Start​

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

// Public reference data: explicit route and field permissions, no database connection.
const fruitRouter = acl.createDataRouter('fruit', {
basePath: '/fruit',
data: [{ id: 'apple', name: 'Apple', public: true }],
idParam: 'id',
idField: 'id',
operationAccess: { list: true, read: true },
permissionSchema: {
id: true,
name: true,
public: true,
},
});

const app = express();
app.use(express.json());
app.use(fruitRouter.routes);
app.listen(3000);

GET /fruit returns { data, meta }; GET /fruit/apple returns the readable fruit. For model routes, pass a Mongoose model to createRouter(model, options) and connect MongoDB before listening. For actor-specific grants, configure globalPermissions from an authenticated server-side actor as shown in Configuration.

When To Use It​

Use access-router when you want:

  • model-backed CRUD routers with ACL-aware filtering and field selection
  • in-memory data routers with the same request/permission model
  • root batch routes for grouped operations
  • OpenAPI generation and Swagger UI without hand-maintaining route docs
  • reusable permission helpers, hooks, and request validation

If you only need low-level validation schemas, symbols, or enums, import from the advanced subpath instead.

Package Guide​

  • Routing: router factories, generated endpoints, and batch routing
  • Configuration: global, model, and data router options
  • Services: public service methods behind the generated routes
  • Hooks: ACL, filter, validation, decoration, and persistence hooks
  • Validation: built-in schemas and custom validator adapters
  • OpenAPI: generated spec routes, Swagger UI, and custom schema metadata
  • Advanced: lower-level types, enums, symbols, and validation helpers
  • Processors: document processing helpers