@stonyx/orm 0.3.2-alpha.7 → 0.3.2-alpha.70

package/dist/types/orm-types.d.ts

@@ -16,6 +16,7 @@ export interface OrmMysqlConfig {
     connectionLimit?: number;
     migrationsDir?: string;
     migrationsTable?: string;
+    autoMigrate?: boolean;
     [key: string]: unknown;
 }
 export interface OrmPostgresConfig {
@@ -27,6 +28,7 @@ export interface OrmPostgresConfig {
     connectionLimit?: number;
     migrationsDir?: string;
     migrationsTable?: string;
+    autoMigrate?: boolean;
     [key: string]: unknown;
 }
 export interface OrmPaths {
@@ -42,6 +44,12 @@ export interface OrmRestServerConfig {
     route: string;
     metaRoute: boolean;
 }
+export interface OrmDynamoDBConfig {
+    region?: string;
+    endpoint?: string;
+    tablePrefix?: string;
+    [key: string]: unknown;
+}
 export interface OrmSection {
     db: OrmDbConfig;
     paths: OrmPaths;
@@ -49,6 +57,9 @@ export interface OrmSection {
     mysql?: OrmMysqlConfig;
     postgres?: OrmPostgresConfig;
     timescale?: OrmPostgresConfig;
+    dynamodb?: OrmDynamoDBConfig;
+    logColor?: string;
+    logMethod?: string;
     [key: string]: unknown;
 }
 export interface OrmConfig {
@@ -151,3 +162,199 @@ export interface SnapshotEntry {
     source?: string;
     viewQuery?: string;
 }
+/**
+ * The shapes a consumer `access()` predicate may return.
+ *
+ * - `false` (or any falsy value) -- deny, 403.
+ * - `true` -- allow, with no per-record filter.
+ * - a permission string or array of them, drawn from the same four verbs as
+ *   {@link AccessContext.operation}. A BARE STRING IS ONE PERMISSION, not a
+ *   grant of all four.
+ * - a `(record) => boolean` predicate -- allow, and filter every record the
+ *   request touches through it.
+ *
+ * Anything else fails CLOSED. See `src/orm-request.ts` `auth()`.
+ */
+export type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
+/**
+ * The closed vocabulary `AccessContext.operation` is drawn from
+ * (abofs/stonyx-orm#202).
+ *
+ * A literal union rather than `string`, so the guarantee the prose makes is the
+ * one the compiler enforces: a consumer who writes `operation === 'GET'` or
+ * `operation === 'get'` -- the hook vocabulary, see below -- gets a compile
+ * error instead of a comparison that never matches. A predicate that stops
+ * matching falls through to the permission array, so the misreading is
+ * fail-open shaped.
+ *
+ * In-repo precedent: `PersistErrorDetail.operation` in `src/main.ts`.
+ */
+export type AccessOperation = 'read' | 'create' | 'update' | 'delete';
+/**
+ * The structural facts about the request being authorised, handed to a consumer
+ * `access()` predicate as its SECOND argument (abofs/stonyx-orm#202).
+ *
+ * These are the facts the framework already holds at authorisation time. Before
+ * #202 a consumer had to reconstruct both of them by string-matching a URL, and
+ * five independent fail-open variants of that reconstruction were found in one
+ * three-line documented example -- each one wrong in the direction that GRANTS
+ * access. Read these instead; there is nothing to parse and no variant to miss.
+ *
+ * `record` is deliberately NOT a member. `auth()` runs after route matching but
+ * before any handler executes (`@stonyx/rest-server` `src/request.ts:58-60`),
+ * so nothing has been fetched yet -- carrying a record here would force a
+ * pre-fetch on every request. It is also unnecessary: the `(record) => boolean`
+ * return shape of {@link AccessMethod} already IS the per-record hook, applied
+ * by the handlers. Auth-time and record-time are separate decision points.
+ */
+export interface AccessContext {
+    /**
+     * The model this route was mounted for, e.g. `'owner'` or `'phone-number'`.
+     *
+     * Model names are kebab-case, as declared under `config.orm.paths.model` and
+     * keyed in the store -- NOT the pluralised, mount-prefixed route name. It is
+     * read from the `OrmRequest` instance and is never derived from the request
+     * target, so a mount prefix, a case-varied path, a query string or an
+     * absolute-form request-target cannot change it.
+     */
+    model: string;
+    /**
+     * The operation being authorised. Exactly one of the four {@link
+     * AccessOperation} verbs, or `undefined`. These are exactly the values of
+     * `methodAccessMap` in `src/orm-request.ts`, which is also what the
+     * permission-array return shape is matched against -- so the two forms cannot
+     * disagree.
+     *
+     * NOT the hook vocabulary. `HookContext.operation` (`src/hooks.ts`) carries
+     * `'list' | 'get' | 'create' | 'update' | 'delete'` on an identically-named
+     * key of an identically-shaped context object, and the access vocabulary
+     * collapses `list` and `get` into `'read'`. For one `GET /animals/1` a hook
+     * sees `'get'` and `access()` sees `'read'`. "No second vocabulary" is a
+     * statement about the ACCESS path only.
+     *
+     * `undefined` when the dispatched method has no entry in that map. Express
+     * delivers `HEAD` to the `GET` handler, so this is reachable. It is left
+     * undefined rather than defaulted on purpose: a fabricated `'read'` would
+     * turn an unclassified request into an authorised one.
+     *
+     * The KEY is required even though the value may be undefined: `auth()` always
+     * sets it, and a context that simply omitted it would be indistinguishable
+     * from one that classified the request and found nothing.
+     */
+    operation: AccessOperation | undefined;
+    /**
+     * The record this route was addressed to, as the store key -- or `null` on a
+     * collection route, which is addressed to no record (abofs/stonyx-orm#236).
+     *
+     * IT IS ALREADY DECODED, AND THAT IS THE WHOLE POINT. Express decodes route
+     * PARAMETERS while leaving `request.path` raw, so a consumer comparing
+     * `request.path` against a literal compares an undecoded string against a
+     * decoded dispatch. `GET /owners/%61rchived` reached such a comparison as
+     * `/%61rchived`, walked past a `/archived` deny, and was dispatched as the
+     * record `archived` -- 200 with the record in full, and `DELETE` destroyed
+     * it, unauthenticated. 255 non-canonical spellings of an 8-character id
+     * decode to the same key, so a deny-list of spellings is the wrong shape.
+     *
+     * SO DO NOT NORMALISE THIS, AND DO NOT NORMALISE ANYTHING ELSE INSTEAD:
+     *
+     * - Do NOT decode it. Express decodes exactly ONCE, which is what a route
+     *   parameter means. `GET /owners/%2561rchived` is the legitimate id
+     *   `%61rchived`, not a second-order spelling of `archived`; a predicate that
+     *   decoded until stable would deny a record it was never asked about.
+     * - Do NOT case-fold it. A record id is a VALUE, not a literal route segment,
+     *   and express's `case sensitive routing` governs literal segments only.
+     *   With a distinct owner seeded at `ARCHIVED`, `.toLowerCase()` was measured
+     *   wrong in BOTH directions at once: `GET /owners/ARCHIVED` 403 (a false
+     *   deny, on the wrong record) and `GET /owners/%41RCHIVED` 200 (a false
+     *   allow, on that same record).
+     * - Do NOT derive it from `request.path` or the request target. Decoding the
+     *   whole path decodes THEN splits, while the router splits THEN decodes, so
+     *   `/owners/archived%2fx` -- a genuinely distinct record whose id is
+     *   `archived/x` -- was measured over-denied 403.
+     *
+     * IT IS `getId(request.params)`, BYTE FOR BYTE -- the same single coercion
+     * the store lookup uses, exactly as `operation` is the same `methodAccessMap`
+     * lookup the permission-array branch uses. The predicate and the dispatch
+     * therefore cannot disagree about which record a request addresses. Handing
+     * over the raw `request.params.id` instead would reintroduce that divergence
+     * on hex-shaped ids: `GET /animals/0x2391` looks up record `9105`.
+     *
+     * It inherits abofs/stonyx-orm#209 along with that coercion -- on a model
+     * declaring `id = attr('string')`, `'9107'` arrives here as the number
+     * `9107`. That is consistency WITH THE LOOKUP, which is the property this key
+     * exists to buy; it is not a defect to repair here.
+     *
+     * `null`, not `undefined`, on a collection route -- and the KEY IS ALWAYS
+     * PRESENT, the same rule `operation` states above. `auth()` always sets it,
+     * so a context arriving WITHOUT the key did not come from `auth()`: it was
+     * hand-assembled by a caller resolving the predicate through
+     * `Orm.instance.getAccess()`. That absence stays a distinguishable, deniable
+     * signal only because the framework never produces it.
+     *
+     * IT DISAGREES WITH THE HOOK VOCABULARY, AND NOT ONLY ON THE ABSENCE
+     * SPELLING. `HookContext.recordId` (`src/hooks.ts`) is an identically-named
+     * key on an identically-shaped context object, which is the exact
+     * configuration that makes `operation` fail-open shaped -- a hook sees
+     * `'get'` where `access()` sees `'read'`. An earlier revision of THIS
+     * docblock asserted the opposite ("here they AGREE... they differ in ONE way
+     * and it is the absence spelling"). That was measured false, in the fail-open
+     * direction, and it is corrected here rather than deleted.
+     *
+     * MEASURED over the live dispatch, before-hooks registered for all five
+     * operations on one model:
+     *
+     *     before:list    key ABSENT      ('recordId' in context === false)
+     *     before:get     key ABSENT      params={"id":"visible1"}
+     *     before:create  key ABSENT
+     *     before:update  key ABSENT      params={"id":"visible2"}
+     *     before:delete  recordId="visible3"
+     *     after:delete   recordId="visible3"
+     *
+     * `_withHooks` assigns `context.recordId` at exactly TWO sites in
+     * `src/orm-request.ts`, and BOTH sit inside an `operation === 'delete'`
+     * branch. So the two keys differ in COVERAGE, on four of five operations: on
+     * a hook context the key is absent for get, list, create and update, while
+     * this key is present on every route `auth()` classifies. The absence
+     * spelling is the smaller half of the difference, not the whole of it.
+     *
+     * AND THAT INVERTS THE ARGUMENT ABOVE WHEN IT IS READ ACROSS THE TWO. Here,
+     * a missing `recordId` means "did not come from `auth()`" and is deniable.
+     * On a hook context it means "this is a get / list / create / update" -- an
+     * ordinary request. A consumer who writes the hook-side half of the same
+     * rule --
+     *
+     *     beforeHook('update', 'owner', ctx => ctx.recordId === 'archived' ? 403 : undefined)
+     *
+     * -- gets a deny that NEVER FIRES: measured, `PATCH /owners/visible2` -> 200,
+     * with `ctx.recordId === undefined` while the addressed record sits in
+     * `ctx.params`. The hook side is abofs/stonyx-orm#242 and is deliberately not
+     * repaired here. A predicate must not read `undefined` here as "collection",
+     * and nothing in this contract makes it safe to read the two keys as one key.
+     *
+     * IT NAMES WHICH RECORD, NOT WHICH SURFACE. `GET /owners/gina`,
+     * `GET /owners/gina/pets` and `GET /owners/gina/relationships/pets` all
+     * carry `recordId: 'gina'`; the related-resource gap is abofs/stonyx-orm#196
+     * and is untouched by this key.
+     */
+    recordId: string | number | null;
+}
+/**
+ * A consumer `access()` predicate.
+ *
+ * The second argument is ADDITIVE: JavaScript ignores extra arguments, so every
+ * pre-#202 single-argument predicate keeps working untouched. Changing the
+ * FIRST argument instead would have been the breaking form, and a predicate
+ * that can no longer identify its collection falls through to a full CRUD
+ * grant -- so the "safer" breaking change would have converted every unmigrated
+ * predicate into a fail-open.
+ *
+ * `context` is nonetheless REQUIRED in the type, and that costs back-compat
+ * nothing. TypeScript already lets a fewer-parameter implementation satisfy a
+ * more-parameter signature, so an arity-1 predicate assigns to this type
+ * cleanly -- measured under `--strict`. What the `?` bought was the opposite of
+ * safety: it silently permitted `getAccess('animal')?.(request)` at the CALL
+ * site, i.e. exactly the omission {@link AccessContext} exists to prevent, and
+ * that call gets the model-wrong answer. Required, a caller that drops the
+ * context gets `TS2554: Expected 2 arguments, but got 1`.
+ */
+export type AccessFunction = (request: unknown, context: AccessContext) => AccessMethod;

package/dist/utils.d.ts

@@ -5,3 +5,47 @@ export declare function isDbError(error: unknown): error is {
 };
 export declare function isOrmRecord(value: unknown): value is OrmRecord;
 export declare function pluralize(word: string): string;
+/**
+ * The highest NUMERIC id held by a set of records, or `0` when there is none.
+ *
+ * ONE COPY, and the duplication it replaces is the reason it lives here. Three
+ * near-identical reduces existed at once: `assignRecordId` (server-assigned id
+ * selection), `StandaloneDB.create` (src/standalone-db.ts) and the #203 test
+ * helper. `docs/improvements.md`'s standing WET Code category prescribes
+ * exactly this remedy -- extract into the module that already acts as the
+ * shared utility -- and `assignRecordId` already imported `isOrmRecord` from
+ * here.
+ *
+ * NON-NUMBERS ARE SKIPPED RATHER THAN COERCED TO `0`, AND THAT IS STYLISTIC.
+ * `StandaloneDB`'s shape mapped them to `0`, which can never beat a seed of
+ * `0`. Measured over eleven input classes (`[]`, `1`, `NaN`, `'5'`, `'abc'`,
+ * `-3`, `0`, `null`, `undefined`, `Infinity`, and mixed arrays) the two shapes
+ * produce IDENTICAL output on every one. In particular `typeof NaN` is
+ * `'number'`, so NEITHER shape coerces `NaN` -- both reject it on `NaN > max`,
+ * which is `false`. An earlier revision of this code asserted that the skip was
+ * what made the `NaN` case work; it is not, the comparison is, and that claim
+ * has been removed rather than left standing.
+ *
+ * WHAT IS LOAD-BEARING is that this is not `Math.max(...ids)`. `Math.max`
+ * returns `NaN` if any operand is `NaN`, and a record CAN be held under the key
+ * `NaN` -- so the obvious fix assigns `NaN`, lands on that slot and overwrites
+ * it, which is abofs/stonyx-orm#203 in a new disguise. Pinned by
+ * test/unit/assign-record-id-test.ts AC2; before that file existed the whole
+ * suite scored 951/0 under exactly that fix.
+ */
+export declare function maxNumericId(records: {
+    id?: unknown;
+}[]): number;
+/**
+ * The message prefix `assignRecordId` throws with when no free id can be
+ * derived for a model, and the ONE string `createHandler` matches on to answer
+ * `409` instead of letting the rejection reach express's default handler.
+ *
+ * It lives here rather than in either file because both need it and neither
+ * should own a copy: a literal in two places is how the two id coercions in
+ * orm-request.ts drifted apart (see `coerceId`). The repo has no error codes
+ * and no custom error classes -- 24 bare `throw new Error` sites across `src/`
+ * -- so a shared prefix is the narrowest way to make ONE failure distinguishable
+ * without inventing an error taxonomy this codebase does not use.
+ */
+export declare const NO_FREE_ID_ERROR = "Cannot assign record ID: no free id available";

package/dist/utils.js

@@ -15,3 +15,50 @@ export function pluralize(word) {
     }
     return basePluralize(word);
 }
+/**
+ * The highest NUMERIC id held by a set of records, or `0` when there is none.
+ *
+ * ONE COPY, and the duplication it replaces is the reason it lives here. Three
+ * near-identical reduces existed at once: `assignRecordId` (server-assigned id
+ * selection), `StandaloneDB.create` (src/standalone-db.ts) and the #203 test
+ * helper. `docs/improvements.md`'s standing WET Code category prescribes
+ * exactly this remedy -- extract into the module that already acts as the
+ * shared utility -- and `assignRecordId` already imported `isOrmRecord` from
+ * here.
+ *
+ * NON-NUMBERS ARE SKIPPED RATHER THAN COERCED TO `0`, AND THAT IS STYLISTIC.
+ * `StandaloneDB`'s shape mapped them to `0`, which can never beat a seed of
+ * `0`. Measured over eleven input classes (`[]`, `1`, `NaN`, `'5'`, `'abc'`,
+ * `-3`, `0`, `null`, `undefined`, `Infinity`, and mixed arrays) the two shapes
+ * produce IDENTICAL output on every one. In particular `typeof NaN` is
+ * `'number'`, so NEITHER shape coerces `NaN` -- both reject it on `NaN > max`,
+ * which is `false`. An earlier revision of this code asserted that the skip was
+ * what made the `NaN` case work; it is not, the comparison is, and that claim
+ * has been removed rather than left standing.
+ *
+ * WHAT IS LOAD-BEARING is that this is not `Math.max(...ids)`. `Math.max`
+ * returns `NaN` if any operand is `NaN`, and a record CAN be held under the key
+ * `NaN` -- so the obvious fix assigns `NaN`, lands on that slot and overwrites
+ * it, which is abofs/stonyx-orm#203 in a new disguise. Pinned by
+ * test/unit/assign-record-id-test.ts AC2; before that file existed the whole
+ * suite scored 951/0 under exactly that fix.
+ */
+export function maxNumericId(records) {
+    return records.reduce((max, record) => {
+        const { id } = record;
+        return typeof id === 'number' && id > max ? id : max;
+    }, 0);
+}
+/**
+ * The message prefix `assignRecordId` throws with when no free id can be
+ * derived for a model, and the ONE string `createHandler` matches on to answer
+ * `409` instead of letting the rejection reach express's default handler.
+ *
+ * It lives here rather than in either file because both need it and neither
+ * should own a copy: a literal in two places is how the two id coercions in
+ * orm-request.ts drifted apart (see `coerceId`). The repo has no error codes
+ * and no custom error classes -- 24 bare `throw new Error` sites across `src/`
+ * -- so a shared prefix is the narrowest way to make ONE failure distinguishable
+ * without inventing an error taxonomy this codebase does not use.
+ */
+export const NO_FREE_ID_ERROR = 'Cannot assign record ID: no free id available';

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.7",
+  "version": "0.3.2-alpha.70",
   "description": "",
   "main": "dist/index.js",
   "type": "module",
@@ -61,16 +61,25 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "@stonyx/cron": "0.2.1-beta.59",
-    "@stonyx/events": "0.1.1-beta.47",
-    "stonyx": "0.2.3-beta.63"
+    "@stonyx/cron": "0.2.1-beta.85",
+    "@stonyx/events": "0.1.1-beta.52",
+    "@stonyx/utils": "0.2.3-beta.26",
+    "stonyx": "0.2.3-beta.77"
   },
   "peerDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.0.0",
+    "@aws-sdk/lib-dynamodb": "^3.0.0",
     "@stonyx/rest-server": ">=0.2.1-beta.14",
     "mysql2": "^3.0.0",
     "pg": "^8.0.0"
   },
   "peerDependenciesMeta": {
+    "@aws-sdk/client-dynamodb": {
+      "optional": true
+    },
+    "@aws-sdk/lib-dynamodb": {
+      "optional": true
+    },
     "mysql2": {
       "optional": true
     },
@@ -82,8 +91,7 @@
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.59",
-    "@stonyx/utils": "0.2.3-beta.23",
+    "@stonyx/rest-server": "0.2.1-beta.84",
     "@types/node": "^25.6.0",
     "mysql2": "^3.20.0",
     "pg": "^8.20.0",
@@ -95,6 +103,7 @@
   "scripts": {
     "build": "tsc",
     "build:test": "tsc -p tsconfig.test.json",
-    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'"
+    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'",
+    "test:dynamodb": "pnpm build && node --import tsx/esm --import ./test/integration/dynamodb/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/dynamodb/**/*-test.ts'"
   }
 }

package/src/commands.ts

@@ -28,6 +28,13 @@ const commands: Record<string, Command> = {
     description: 'Generate a MySQL migration from current model schemas',
     bootstrap: true,
     run: async (args) => {
+      const config = (await import('stonyx/config')).default;
+
+      if (config.orm.dynamodb) {
+        console.log('DynamoDB does not use file-based migrations. Use db:sync to provision tables.');
+        return;
+      }
+
       const description = args?.join(' ') || 'migration';
       const { generateMigration } = await import('./mysql/migration-generator.js');
       const result = await generateMigration(description);
@@ -39,6 +46,25 @@ const commands: Record<string, Command> = {
       }
     }
   },
+  'db:sync': {
+    description: 'Provision DynamoDB tables and GSIs from current model schemas',
+    bootstrap: true,
+    run: async () => {
+      const config = (await import('stonyx/config')).default;
+
+      if (!config.orm.dynamodb) {
+        console.error('DynamoDB is not configured. Set DYNAMODB_REGION (and optionally DYNAMODB_ENDPOINT) to enable DynamoDB mode.');
+        process.exit(1);
+      }
+
+      const { default: DynamoDBDB } = await import('./dynamodb/dynamodb-db.js');
+      const db = new DynamoDBDB();
+      await db.init();
+      await db.startup();
+      await db.shutdown();
+      console.log('DynamoDB tables synced successfully.');
+    }
+  },
   'db:migrate': {
     description: 'Apply pending MySQL migrations',
     bootstrap: true,
@@ -46,6 +72,11 @@ const commands: Record<string, Command> = {
       const config = (await import('stonyx/config')).default;
       const mysqlConfig = config.orm.mysql;
 
+      if (config.orm.dynamodb) {
+        console.log('DynamoDB does not use file-based migrations. Use db:sync to provision tables.');
+        return;
+      }
+
       if (!mysqlConfig) {
         console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');
         process.exit(1);
@@ -92,6 +123,12 @@ const commands: Record<string, Command> = {
     bootstrap: true,
     run: async () => {
       const config = (await import('stonyx/config')).default;
+
+      if (config.orm.dynamodb) {
+        console.log('DynamoDB does not support migration rollback. Manage table changes via the AWS console or db:sync.');
+        return;
+      }
+
       const mysqlConfig = config.orm.mysql;
 
       if (!mysqlConfig) {
@@ -138,6 +175,12 @@ const commands: Record<string, Command> = {
     bootstrap: true,
     run: async () => {
       const config = (await import('stonyx/config')).default;
+
+      if (config.orm.dynamodb) {
+        console.log('DynamoDB does not use file-based migrations. Use db:sync to provision tables.');
+        return;
+      }
+
       const mysqlConfig = config.orm.mysql;
 
       if (!mysqlConfig) {

package/src/dynamodb/connection.ts

@@ -0,0 +1,50 @@
+/**
+ * DynamoDB connection factory.
+ *
+ * Dynamically imports @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb
+ * so these are optional peerDependencies (matching the pg/mysql2 pattern).
+ */
+
+export interface DynamoDBConfig {
+  region?: string;
+  endpoint?: string;
+  tablePrefix?: string;
+  [key: string]: unknown;
+}
+
+// Type aliases — declared loose so we don't need to import the real SDK types
+// at compile time (they're optional peer deps).
+export type DocumentClient = {
+  send(command: unknown): Promise<unknown>;
+};
+
+export type DynamoDBClientConstructor = new (options: unknown) => { config: unknown };
+export type DocumentClientFromFn = { from(client: unknown): DocumentClient };
+
+/**
+ * Create a DynamoDBDocumentClient from the given config.
+ * Uses dynamic import so @aws-sdk/* are optional peer deps.
+ */
+export async function createDocumentClient(dbConfig: DynamoDBConfig): Promise<DocumentClient> {
+  const { DynamoDBClient } = await import('@aws-sdk/client-dynamodb' as string) as {
+    DynamoDBClient: DynamoDBClientConstructor;
+  };
+  const { DynamoDBDocumentClient } = await import('@aws-sdk/lib-dynamodb' as string) as {
+    DynamoDBDocumentClient: DocumentClientFromFn;
+  };
+
+  const clientOptions: Record<string, unknown> = {};
+  if (dbConfig.region) clientOptions.region = dbConfig.region;
+  if (dbConfig.endpoint) clientOptions.endpoint = dbConfig.endpoint;
+
+  const rawClient = new DynamoDBClient(clientOptions);
+  return DynamoDBDocumentClient.from(rawClient);
+}
+
+/**
+ * Nullify the document client reference (DynamoDB connections are HTTP-based
+ * and stateless — no explicit pool close needed, but we clear the reference).
+ */
+export function destroyDocumentClient(_client: DocumentClient | null): null {
+  return null;
+}