@constructive-io/express-context 0.2.0 → 0.2.1

package/README.md

@@ -1,26 +1,44 @@
 # @constructive-io/express-context
 
-Extractable Express middleware for Constructive tenant context — domain resolution, JWT auth, pgSettings, and withPgClient.
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/@constructive-io/express-context"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=packages%2Fexpress-context%2Fpackage.json"/></a>
+</p>
+
+Extractable Express middleware for Constructive tenant context — domain resolution, JWT auth, pgSettings, withPgClient, and modular per-database cached lookups.
 
 ## Usage
 
 ```typescript
 import {
   createContextMiddleware,
-  requestIdMiddleware
+  requestIdMiddleware,
+  createDefaultRegistry,
 } from '@constructive-io/express-context';
 
+const loaders = createDefaultRegistry();
+
 const app = express();
 
 app.use(requestIdMiddleware());
 app.use(apiMiddleware);            // sets req.api
 app.use(authMiddleware);           // sets req.token
-app.use(createContextMiddleware()); // builds req.constructive
+app.use(createContextMiddleware({ loaders })); // builds req.constructive
 
 app.post('/v1/chat', async (req, res) => {
-  const { withPgClient, pgSettings, userId, databaseId } = req.constructive;
+  const ctx = req.constructive;
+  const rls = await ctx.useModule('rlsModule');       // only fires if not cached
+  const auth = await ctx.useModule('authSettings');    // only fires if not cached
+  // webauthnSettings loader never fires if nobody asks for it
 
-  const result = await withPgClient(async (client) => {
+  const result = await ctx.withPgClient(async (client) => {
     return client.query('SELECT current_user_id()');
   });
 
@@ -35,6 +53,40 @@ app.post('/v1/chat', async (req, res) => {
 - **withPgClient** — Tenant-scoped RLS transaction helper (BEGIN → SET LOCAL → fn → COMMIT)
 - **requestId middleware** — UUID correlation ID (from X-Request-Id header or generated)
 - **Context middleware** — Composes all of the above into `req.constructive`
+- **Module loaders** — Pluggable per-database cached lookups with lazy on-demand resolution
+
+## Module Loaders
+
+Each loader encapsulates a SQL query + type transform + per-databaseId LRU cache for one piece of per-database configuration. Loaders are registered in a `LoaderRegistry` and resolved lazily via `useModule(name)`.
+
+### Built-in loaders
+
+| Loader | Source | Description |
+|--------|--------|-------------|
+| `rlsLoader` | `services_public.rls_settings` | RLS module (authenticate functions, schema refs) |
+| `corsLoader` | `services_public.cors_settings` | CORS allowed origins |
+| `databaseSettingsLoader` | `services_public.database_settings` | Feature flags (aggregates, search, uploads, etc.) |
+| `pubkeyLoader` | `services_public.pubkey_settings` | Public key challenge auth settings |
+| `webauthnLoader` | `services_public.webauthn_settings` | WebAuthn/passkey configuration |
+| `authSettingsLoader` | `metaschema_modules_public.sessions_module` | Cookie/captcha settings (two-step tenant DB discovery) |
+
+### Custom loaders
+
+```typescript
+import { createModuleLoader, createLoaderRegistry } from '@constructive-io/express-context';
+
+const myLoader = createModuleLoader({
+  name: 'myModule',
+  ttlMs: 60_000,
+  async resolve(ctx) {
+    const { rows } = await ctx.tenantPool.query(MY_SQL, [ctx.databaseId]);
+    return rows[0] ? transform(rows[0]) : undefined;
+  },
+});
+
+const registry = createLoaderRegistry();
+registry.register(myLoader);
+```
 
 ---
 

package/esm/loaders/create-loader.js

@@ -1,7 +1,7 @@
 /**
  * create-loader — Factory for building cached ModuleLoader instances.
  *
- * Wraps a raw resolve function with an LRU cache keyed by databaseId.
+ * Wraps a raw resolve function with an LRU cache keyed by databaseId:apiId.
  * Each loader gets its own independent cache with configurable TTL and
  * max entries.
  */
@@ -20,7 +20,7 @@ export function createModuleLoader(opts) {
     return {
         name: opts.name,
         async resolve(ctx) {
-            const key = ctx.databaseId;
+            const key = ctx.apiId ? `${ctx.databaseId}:${ctx.apiId}` : ctx.databaseId;
             if (cache.has(key)) {
                 log.debug(`Cache HIT databaseId=${key}`);
                 return cache.get(key);
@@ -38,8 +38,15 @@ export function createModuleLoader(opts) {
         },
         invalidate(databaseId) {
             if (databaseId) {
-                cache.delete(databaseId);
-                log.debug(`Invalidated databaseId=${databaseId}`);
+                // Clear the plain databaseId key and any composite databaseId:apiId keys
+                let cleared = 0;
+                for (const k of cache.keys()) {
+                    if (k === databaseId || k.startsWith(`${databaseId}:`)) {
+                        cache.delete(k);
+                        cleared++;
+                    }
+                }
+                log.debug(`Invalidated ${cleared} entries for databaseId=${databaseId}`);
             }
             else {
                 cache.clear();

package/loaders/create-loader.d.ts

@@ -1,7 +1,7 @@
 /**
  * create-loader — Factory for building cached ModuleLoader instances.
  *
- * Wraps a raw resolve function with an LRU cache keyed by databaseId.
+ * Wraps a raw resolve function with an LRU cache keyed by databaseId:apiId.
  * Each loader gets its own independent cache with configurable TTL and
  * max entries.
  */

package/loaders/create-loader.js

@@ -2,7 +2,7 @@
 /**
  * create-loader — Factory for building cached ModuleLoader instances.
  *
- * Wraps a raw resolve function with an LRU cache keyed by databaseId.
+ * Wraps a raw resolve function with an LRU cache keyed by databaseId:apiId.
  * Each loader gets its own independent cache with configurable TTL and
  * max entries.
  */
@@ -23,7 +23,7 @@ function createModuleLoader(opts) {
     return {
         name: opts.name,
         async resolve(ctx) {
-            const key = ctx.databaseId;
+            const key = ctx.apiId ? `${ctx.databaseId}:${ctx.apiId}` : ctx.databaseId;
             if (cache.has(key)) {
                 log.debug(`Cache HIT databaseId=${key}`);
                 return cache.get(key);
@@ -41,8 +41,15 @@ function createModuleLoader(opts) {
         },
         invalidate(databaseId) {
             if (databaseId) {
-                cache.delete(databaseId);
-                log.debug(`Invalidated databaseId=${databaseId}`);
+                // Clear the plain databaseId key and any composite databaseId:apiId keys
+                let cleared = 0;
+                for (const k of cache.keys()) {
+                    if (k === databaseId || k.startsWith(`${databaseId}:`)) {
+                        cache.delete(k);
+                        cleared++;
+                    }
+                }
+                log.debug(`Invalidated ${cleared} entries for databaseId=${databaseId}`);
             }
             else {
                 cache.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/express-context",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Extractable Express middleware for Constructive tenant context — domain resolution, JWT auth, pgSettings, and withPgClient",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -59,5 +59,5 @@
     "jwt",
     "pgSettings"
   ],
-  "gitHead": "c0d04574f7719d92e67becb58d60791ae978c5f5"
+  "gitHead": "ccc303b2a2d1d9701648efc124ea1d9f2714711f"
 }