@web-ts-toolkit/access-router 0.32.0 → 0.33.0

package/llms.txt

@@ -5,49 +5,72 @@ ACL-aware Express routers and in-memory data services for Mongoose-backed APIs.
 ## Main Patterns
 
 ```ts
-import acl from '@web-ts-toolkit/access-router';
+import express from 'express';
+import mongoose from 'mongoose';
+import acl, { permissionsPlugin } from '@web-ts-toolkit/access-router';
 
-// configure global permissions
-acl.setGlobalOptions({ globalPermissions(req) { return []; } });
+acl.setGlobalOptions({
+  requestPermissionField: '_permissions',
+  globalPermissions(req) { return req.headers.user === 'admin' ? ['isAdmin'] : []; },
+});
+
+const userSchema = new mongoose.Schema({ name: String, role: String, public: Boolean });
+userSchema.plugin(permissionsPlugin, { modelName: 'User' });
+mongoose.model('User', userSchema);
 
-// model CRUD router from a Mongoose model name
 const userRouter = acl.createRouter('User', { basePath: '/users' });
 
-// in-memory data router
+// Also: pass a mongoose.Model instance to preserve a non-default connection.
+// acl.createRouter(UserModel, { basePath: '/users' });
+
 const fruitRouter = acl.createDataRouter('fruit', {
   basePath: '/fruit',
   idField: 'id',
   data: [{ id: 'apple', name: 'Apple' }],
 });
 
-// OpenAPI + Swagger UI
 const docsRouter = acl.createOpenApiRouter({ title: 'Example API', version: '1.0.0' });
 ```
 
 Validation adapters:
 
 ```ts
+import { z } from 'zod';
 import { fromZod, defineRequestSchema } from '@web-ts-toolkit/access-router';
-
 const validator = fromZod(z.object({ name: z.string() }));
 const schema = defineRequestSchema(validator);
 ```
 
+Isolated runtime (no global state shared with default `acl`):
+
+```ts
+import { createAccessRuntime } from '@web-ts-toolkit/access-router';
+import mongoose from 'mongoose';
+const runtime = createAccessRuntime();
+runtime.setGlobalOptions({ globalPermissions: () => [] });
+runtime.createRouter('User', { basePath: '/users' });
+const UserModel = mongoose.model('User', new mongoose.Schema({ name: String }));
+runtime.registerModelInstance('User', UserModel);
+```
+
 Subpath imports:
 
 ```ts
 import { copyAndDepopulate } from '@web-ts-toolkit/access-router/processors';
-import { AccessRuntime, defaultRuntime } from '@web-ts-toolkit/access-router/advanced';
+import { parseBody, Codes, MIDDLEWARE } from '@web-ts-toolkit/access-router/advanced';
 ```
 
 ## Gotchas
 
 - peer dependencies: `express >= 5` and `mongoose >= 8`
-- default export `acl` and named exports are both available; default is preferred for the runtime API
-- `createRouter('User', ...)` takes a Mongoose model name string, not the model instance
+- default export `acl` is preferred for the default-runtime API; named exports are also available
+- `acl.createOpenApiRouter(options)` uses the default runtime; the standalone `createOpenApiRouter(runtime, options)` export requires the runtime as the first argument
+- `createRouter('User', ...)` accepts a Mongoose model name OR a `mongoose.Model` instance — passing the instance registers the model with the runtime and preserves non-default `mongoose.createConnection()` instances
+- `/advanced` does NOT export `acl`, `defaultRuntime`, `createRouter`, or `createAccessRuntime` — those live on the root entry only
 - `createDataRouter(...)` holds data in-memory; use it for lightweight/non-persisted resources
+- `package.json` declares `sideEffects` array listing the bundled runtime entries that run the lazy `mongoose-schema-jsonschema` patch on first runtime construction — bundlers must retain those entries
 
 ## Pointers
 
-- README: installation, quickstart, main exports
+- README: installation, quickstart (Express + Mongoose end-to-end), main exports, runtime isolation, createRouter overloads
 - website/docs/packages/access-router/: full documentation (routing, configuration, hooks, validation, openapi)

package/package.json

@@ -2,8 +2,13 @@
   "name": "@web-ts-toolkit/access-router",
   "description": "ACL-aware Express routers and in-memory data services for Mongoose-backed APIs",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/access-router",
-  "version": "0.32.0",
-  "sideEffects": false,
+  "version": "0.33.0",
+  "sideEffects": [
+    "./**/index.js",
+    "./**/index.mjs",
+    "./**/advanced.js",
+    "./**/advanced.mjs"
+  ],
   "keywords": [
     "express",
     "mongoose",
@@ -37,11 +42,11 @@
     }
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-json-router": "0.32.0",
-    "@web-ts-toolkit/utils": "0.32.0",
+    "@web-ts-toolkit/express-json-router": "0.33.0",
+    "@web-ts-toolkit/utils": "0.33.0",
     "just-diff": "^6.0.2",
     "mongoose-schema-jsonschema": "^4.0.1",
     "sift": "^17.1.3",