@constructive-io/express-context 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @constructive-io/express-context
+
+Extractable Express middleware for Constructive tenant context — domain resolution, JWT auth, pgSettings, and withPgClient.
+
+## Usage
+
+```typescript
+import {
+  createContextMiddleware,
+  requestIdMiddleware
+} from '@constructive-io/express-context';
+
+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.post('/v1/chat', async (req, res) => {
+  const { withPgClient, pgSettings, userId, databaseId } = req.constructive;
+
+  const result = await withPgClient(async (client) => {
+    return client.query('SELECT current_user_id()');
+  });
+
+  res.json(result.rows);
+});
+```
+
+## What it provides
+
+- **Types** — `ApiStructure`, `RlsModule`, `AuthSettings`, `ConstructiveContext`, etc.
+- **pgSettings builder** — Constructs SET LOCAL key-value pairs from API + token
+- **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`
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/context.d.ts

@@ -0,0 +1,61 @@
+/**
+ * context — Builds `req.constructive` from resolved API + auth token
+ *
+ * This middleware runs AFTER the API resolver and auth middleware have
+ * populated `req.api` and `req.token`. It composes:
+ *
+ *   - pgSettings (role, claims, request_id, database_id)
+ *   - Tenant database pool (via pg-cache)
+ *   - withPgClient (transaction-scoped RLS helper)
+ *   - Convenience fields (userId, databaseId, requestId)
+ *   - useModule (lazy, on-demand per-database module resolution)
+ *
+ * The result is a single `req.constructive` object that any downstream
+ * route handler can use for tenant-scoped database operations.
+ */
+import type { Request, RequestHandler } from 'express';
+import type { PgpmOptions } from '@pgpmjs/types';
+import type { LoaderRegistry } from './loaders/registry';
+import type { ConstructiveContext } from './types';
+export interface ContextMiddlewareOptions {
+    /** Base PG options for pool creation (host, port, user, password) */
+    pg?: PgpmOptions['pg'];
+    /** Module loader registry for per-database cached lookups */
+    loaders?: LoaderRegistry;
+}
+/**
+ * Build the ConstructiveContext from the current request state.
+ *
+ * Requires `req.api` and `req.requestId` to be set by upstream middleware.
+ * `req.token` is optional (anonymous requests get null).
+ *
+ * Module loaders are NOT resolved eagerly. Instead, `ctx.useModule(name)`
+ * resolves them on demand — only the modules that middleware actually
+ * needs will fire SQL queries.
+ */
+export declare function buildContext(req: Request, opts?: ContextMiddlewareOptions): ConstructiveContext | null;
+/**
+ * Express middleware that builds `req.constructive` from the resolved
+ * API config and auth token.
+ *
+ * Mount AFTER the API resolver and auth middleware:
+ *
+ * ```typescript
+ * import { createContextMiddleware, createDefaultRegistry } from '@constructive-io/express-context';
+ *
+ * const loaders = createDefaultRegistry();
+ *
+ * app.use(apiMiddleware);       // sets req.api
+ * app.use(authMiddleware);      // sets req.token
+ * app.use(createContextMiddleware({ loaders }));
+ *
+ * // Downstream middleware/routes call useModule on demand:
+ * app.post('/v1/chat', async (req, res) => {
+ *   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
+ * });
+ * ```
+ */
+export declare function createContextMiddleware(opts?: ContextMiddlewareOptions): RequestHandler;

package/context.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * context — Builds `req.constructive` from resolved API + auth token
+ *
+ * This middleware runs AFTER the API resolver and auth middleware have
+ * populated `req.api` and `req.token`. It composes:
+ *
+ *   - pgSettings (role, claims, request_id, database_id)
+ *   - Tenant database pool (via pg-cache)
+ *   - withPgClient (transaction-scoped RLS helper)
+ *   - Convenience fields (userId, databaseId, requestId)
+ *   - useModule (lazy, on-demand per-database module resolution)
+ *
+ * The result is a single `req.constructive` object that any downstream
+ * route handler can use for tenant-scoped database operations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildContext = buildContext;
+exports.createContextMiddleware = createContextMiddleware;
+const pg_cache_1 = require("pg-cache");
+const pg_client_1 = require("./pg-client");
+const pg_settings_1 = require("./pg-settings");
+/**
+ * Create a `useModule` function bound to the given loader context.
+ *
+ * Calling `useModule('rlsModule')` lazily resolves the RLS loader,
+ * hitting the DB only on cache miss. The function is a no-op (returns
+ * undefined) when no registry is configured.
+ */
+function createUseModule(registry, loaderCtx) {
+    return (async (name) => {
+        if (!registry || !loaderCtx)
+            return undefined;
+        return registry.resolve(name, loaderCtx);
+    });
+}
+/**
+ * Build the ConstructiveContext from the current request state.
+ *
+ * Requires `req.api` and `req.requestId` to be set by upstream middleware.
+ * `req.token` is optional (anonymous requests get null).
+ *
+ * Module loaders are NOT resolved eagerly. Instead, `ctx.useModule(name)`
+ * resolves them on demand — only the modules that middleware actually
+ * needs will fire SQL queries.
+ */
+function buildContext(req, opts = {}) {
+    const api = req.api;
+    if (!api)
+        return null;
+    const token = req.token ?? null;
+    const requestId = req.requestId || '';
+    const pgSettings = (0, pg_settings_1.buildPgSettings)({
+        api,
+        token,
+        requestId,
+        clientIp: req.clientIp,
+    });
+    const tenantPool = (0, pg_cache_1.getPgPool)({
+        ...opts.pg,
+        database: api.dbname,
+    });
+    // Build loader context (if registry provided and databaseId known)
+    let loaderCtx = null;
+    if (opts.loaders && api.databaseId) {
+        const servicesPool = (0, pg_cache_1.getPgPool)(opts.pg);
+        loaderCtx = {
+            servicesPool,
+            tenantPool,
+            databaseId: api.databaseId,
+            apiId: api.apiId,
+            dbname: api.dbname,
+        };
+    }
+    return {
+        api,
+        token,
+        pgSettings,
+        databaseId: api.databaseId ?? null,
+        userId: token?.user_id ?? null,
+        requestId,
+        pool: tenantPool,
+        withPgClient: (fn) => (0, pg_client_1.withPgClient)(tenantPool, pgSettings, fn),
+        useModule: createUseModule(opts.loaders, loaderCtx),
+    };
+}
+/**
+ * Express middleware that builds `req.constructive` from the resolved
+ * API config and auth token.
+ *
+ * Mount AFTER the API resolver and auth middleware:
+ *
+ * ```typescript
+ * import { createContextMiddleware, createDefaultRegistry } from '@constructive-io/express-context';
+ *
+ * const loaders = createDefaultRegistry();
+ *
+ * app.use(apiMiddleware);       // sets req.api
+ * app.use(authMiddleware);      // sets req.token
+ * app.use(createContextMiddleware({ loaders }));
+ *
+ * // Downstream middleware/routes call useModule on demand:
+ * app.post('/v1/chat', async (req, res) => {
+ *   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
+ * });
+ * ```
+ */
+function createContextMiddleware(opts = {}) {
+    return (req, _res, next) => {
+        const ctx = buildContext(req, opts);
+        if (ctx) {
+            req.constructive = ctx;
+        }
+        next();
+    };
+}

package/esm/context.js

@@ -0,0 +1,115 @@
+/**
+ * context — Builds `req.constructive` from resolved API + auth token
+ *
+ * This middleware runs AFTER the API resolver and auth middleware have
+ * populated `req.api` and `req.token`. It composes:
+ *
+ *   - pgSettings (role, claims, request_id, database_id)
+ *   - Tenant database pool (via pg-cache)
+ *   - withPgClient (transaction-scoped RLS helper)
+ *   - Convenience fields (userId, databaseId, requestId)
+ *   - useModule (lazy, on-demand per-database module resolution)
+ *
+ * The result is a single `req.constructive` object that any downstream
+ * route handler can use for tenant-scoped database operations.
+ */
+import { getPgPool } from 'pg-cache';
+import { withPgClient as withPgClientFn } from './pg-client';
+import { buildPgSettings } from './pg-settings';
+/**
+ * Create a `useModule` function bound to the given loader context.
+ *
+ * Calling `useModule('rlsModule')` lazily resolves the RLS loader,
+ * hitting the DB only on cache miss. The function is a no-op (returns
+ * undefined) when no registry is configured.
+ */
+function createUseModule(registry, loaderCtx) {
+    return (async (name) => {
+        if (!registry || !loaderCtx)
+            return undefined;
+        return registry.resolve(name, loaderCtx);
+    });
+}
+/**
+ * Build the ConstructiveContext from the current request state.
+ *
+ * Requires `req.api` and `req.requestId` to be set by upstream middleware.
+ * `req.token` is optional (anonymous requests get null).
+ *
+ * Module loaders are NOT resolved eagerly. Instead, `ctx.useModule(name)`
+ * resolves them on demand — only the modules that middleware actually
+ * needs will fire SQL queries.
+ */
+export function buildContext(req, opts = {}) {
+    const api = req.api;
+    if (!api)
+        return null;
+    const token = req.token ?? null;
+    const requestId = req.requestId || '';
+    const pgSettings = buildPgSettings({
+        api,
+        token,
+        requestId,
+        clientIp: req.clientIp,
+    });
+    const tenantPool = getPgPool({
+        ...opts.pg,
+        database: api.dbname,
+    });
+    // Build loader context (if registry provided and databaseId known)
+    let loaderCtx = null;
+    if (opts.loaders && api.databaseId) {
+        const servicesPool = getPgPool(opts.pg);
+        loaderCtx = {
+            servicesPool,
+            tenantPool,
+            databaseId: api.databaseId,
+            apiId: api.apiId,
+            dbname: api.dbname,
+        };
+    }
+    return {
+        api,
+        token,
+        pgSettings,
+        databaseId: api.databaseId ?? null,
+        userId: token?.user_id ?? null,
+        requestId,
+        pool: tenantPool,
+        withPgClient: (fn) => withPgClientFn(tenantPool, pgSettings, fn),
+        useModule: createUseModule(opts.loaders, loaderCtx),
+    };
+}
+/**
+ * Express middleware that builds `req.constructive` from the resolved
+ * API config and auth token.
+ *
+ * Mount AFTER the API resolver and auth middleware:
+ *
+ * ```typescript
+ * import { createContextMiddleware, createDefaultRegistry } from '@constructive-io/express-context';
+ *
+ * const loaders = createDefaultRegistry();
+ *
+ * app.use(apiMiddleware);       // sets req.api
+ * app.use(authMiddleware);      // sets req.token
+ * app.use(createContextMiddleware({ loaders }));
+ *
+ * // Downstream middleware/routes call useModule on demand:
+ * app.post('/v1/chat', async (req, res) => {
+ *   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
+ * });
+ * ```
+ */
+export function createContextMiddleware(opts = {}) {
+    return (req, _res, next) => {
+        const ctx = buildContext(req, opts);
+        if (ctx) {
+            req.constructive = ctx;
+        }
+        next();
+    };
+}

package/esm/index.js

@@ -0,0 +1,45 @@
+/**
+ * @constructive-io/express-context
+ *
+ * Extractable Express middleware for Constructive tenant context.
+ *
+ * Provides:
+ *   - Shared types (ApiStructure, RlsModule, AuthSettings, etc.)
+ *   - pgSettings builder (role, JWT claims, request_id, database_id)
+ *   - withPgClient (tenant-scoped RLS transaction helper)
+ *   - requestId middleware (UUID correlation ID)
+ *   - Context middleware (composes all of the above into req.constructive)
+ *   - Module loaders (pluggable per-database cached lookups)
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createContextMiddleware,
+ *   requestIdMiddleware,
+ *   createDefaultRegistry,
+ * } from '@constructive-io/express-context';
+ *
+ * const loaders = createDefaultRegistry();
+ *
+ * app.use(requestIdMiddleware());
+ * app.use(apiMiddleware);        // sets req.api (your domain resolver)
+ * app.use(authMiddleware);       // sets req.token (your JWT verifier)
+ * app.use(createContextMiddleware({ loaders })); // builds req.constructive
+ *
+ * app.post('/v1/chat', async (req, res) => {
+ *   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
+ * });
+ * ```
+ */
+export { buildPgSettings } from './pg-settings';
+// withPgClient helper
+export { withPgClient } from './pg-client';
+// Request ID middleware
+export { requestIdMiddleware } from './request-id';
+export { buildContext, createContextMiddleware } from './context';
+export { authSettingsLoader, corsLoader, createDefaultRegistry, createLoaderRegistry, createModuleLoader, databaseSettingsLoader, pubkeyLoader, rlsLoader, webauthnLoader, } from './loaders';
+// Side-effect: Express type augmentation
+import './types';

package/esm/loaders/auth-settings.js

@@ -0,0 +1,62 @@
+/**
+ * Auth Settings Loader (Tier 2 — tenant DB)
+ *
+ * Two-step discovery:
+ *   1. Query metaschema_modules_public.sessions_module to find the
+ *      schema name and table name for auth settings
+ *   2. Query the discovered <schema>.<table> in the tenant DB
+ *
+ * This is the pattern for any module whose config lives in the tenant
+ * database rather than the services database.
+ */
+import { createModuleLoader } from './create-loader';
+// ─── SQL ────────────────────────────────────────────────────────────────────
+const AUTH_SETTINGS_DISCOVERY_SQL = `
+  SELECT s.schema_name, sm.auth_settings_table AS table_name
+  FROM metaschema_modules_public.sessions_module sm
+  JOIN metaschema_public.schema s ON s.id = sm.schema_id
+  LIMIT 1
+`;
+const buildAuthSettingsQuery = (schemaName, tableName) => `
+  SELECT
+    cookie_secure,
+    cookie_samesite,
+    cookie_domain,
+    cookie_httponly,
+    cookie_max_age,
+    cookie_path,
+    remember_me_duration,
+    enable_captcha,
+    captcha_site_key
+  FROM "${schemaName}"."${tableName}"
+  LIMIT 1
+`;
+// ─── Loader ─────────────────────────────────────────────────────────────────
+export const authSettingsLoader = createModuleLoader({
+    name: 'authSettings',
+    ttlMs: 5 * 60_000,
+    async resolve(ctx) {
+        const { tenantPool } = ctx;
+        // Step 1: Discover schema + table from sessions_module
+        const discovery = await tenantPool.query(AUTH_SETTINGS_DISCOVERY_SQL);
+        const resolved = discovery.rows[0];
+        if (!resolved)
+            return undefined;
+        // Step 2: Query the actual auth settings table
+        const result = await tenantPool.query(buildAuthSettingsQuery(resolved.schema_name, resolved.table_name));
+        const row = result.rows[0];
+        if (!row)
+            return undefined;
+        return {
+            cookieSecure: row.cookie_secure,
+            cookieSamesite: row.cookie_samesite,
+            cookieDomain: row.cookie_domain,
+            cookieHttponly: row.cookie_httponly,
+            cookieMaxAge: row.cookie_max_age,
+            cookiePath: row.cookie_path,
+            rememberMeDuration: row.remember_me_duration,
+            enableCaptcha: row.enable_captcha,
+            captchaSiteKey: row.captcha_site_key,
+        };
+    },
+});

package/esm/loaders/cors.js

@@ -0,0 +1,55 @@
+/**
+ * CORS Origins Loader
+ *
+ * Resolves allowed CORS origins for a database+API combination.
+ * Checks per-API settings first, falls back to database-level default,
+ * then to the legacy api_modules approach.
+ */
+import { createModuleLoader } from './create-loader';
+// ─── SQL ────────────────────────────────────────────────────────────────────
+const CORS_SETTINGS_SQL = `
+  SELECT allowed_origins
+  FROM services_public.cors_settings
+  WHERE database_id = $1 AND api_id = $2
+  LIMIT 1
+`;
+const CORS_SETTINGS_DB_DEFAULT_SQL = `
+  SELECT allowed_origins
+  FROM services_public.cors_settings
+  WHERE database_id = $1 AND api_id IS NULL
+  LIMIT 1
+`;
+const CORS_MODULE_SQL = `
+  SELECT data
+  FROM services_public.api_modules
+  WHERE api_id = $1 AND name = 'cors'
+  LIMIT 1
+`;
+// ─── Loader ─────────────────────────────────────────────────────────────────
+export const corsLoader = createModuleLoader({
+    name: 'corsOrigins',
+    ttlMs: 5 * 60_000,
+    async resolve(ctx) {
+        const { servicesPool, databaseId, apiId } = ctx;
+        // Try per-API cors_settings first
+        try {
+            if (apiId) {
+                const perApi = await servicesPool.query(CORS_SETTINGS_SQL, [databaseId, apiId]);
+                if (perApi.rows[0])
+                    return perApi.rows[0].allowed_origins;
+            }
+            const dbDefault = await servicesPool.query(CORS_SETTINGS_DB_DEFAULT_SQL, [databaseId]);
+            if (dbDefault.rows[0])
+                return dbDefault.rows[0].allowed_origins;
+        }
+        catch {
+            // Table may not exist yet
+        }
+        // Fall back to legacy api_modules
+        if (apiId) {
+            const result = await servicesPool.query(CORS_MODULE_SQL, [apiId]);
+            return result.rows[0]?.data?.urls;
+        }
+        return undefined;
+    },
+});

package/esm/loaders/create-loader.js

@@ -0,0 +1,53 @@
+/**
+ * create-loader — Factory for building cached ModuleLoader instances.
+ *
+ * Wraps a raw resolve function with an LRU cache keyed by databaseId.
+ * Each loader gets its own independent cache with configurable TTL and
+ * max entries.
+ */
+import { LRUCache } from 'lru-cache';
+import { Logger } from '@pgpmjs/logger';
+const DEFAULT_TTL_MS = 60_000;
+const DEFAULT_MAX = 100;
+export function createModuleLoader(opts) {
+    const log = new Logger(`loader:${opts.name}`);
+    const cache = new LRUCache({
+        max: opts.max ?? DEFAULT_MAX,
+        ttl: opts.ttlMs ?? DEFAULT_TTL_MS,
+        updateAgeOnGet: true,
+        allowStale: false,
+    });
+    return {
+        name: opts.name,
+        async resolve(ctx) {
+            const key = ctx.databaseId;
+            if (cache.has(key)) {
+                log.debug(`Cache HIT databaseId=${key}`);
+                return cache.get(key);
+            }
+            log.debug(`Cache MISS databaseId=${key}, resolving`);
+            try {
+                const value = await opts.resolve(ctx);
+                cache.set(key, value);
+                return value;
+            }
+            catch (e) {
+                log.warn(`Failed to resolve databaseId=${key}: ${e.message}`);
+                return undefined;
+            }
+        },
+        invalidate(databaseId) {
+            if (databaseId) {
+                cache.delete(databaseId);
+                log.debug(`Invalidated databaseId=${databaseId}`);
+            }
+            else {
+                cache.clear();
+                log.debug(`Invalidated all entries (was size=${cache.size})`);
+            }
+        },
+        get cacheSize() {
+            return cache.size;
+        },
+    };
+}