@stonyx/orm 0.3.2-alpha.5 → 0.3.2-alpha.50

package/README.md

@@ -13,7 +13,7 @@ A lightweight ORM for Stonyx projects, featuring model definitions, serializers,
 - **Models**: Define attributes with type-safe proxies (`attr`) and relationships (`hasMany`, `belongsTo`).
 - **Serializers**: Map raw data into model-friendly structures, including nested properties.
 - **Transforms**: Apply custom transformations on data values automatically.
-- **DB Integration**: Optional file-based persistence with auto-save support, or MySQL for production workloads.
+- **DB Integration**: Optional file-based persistence with auto-save support, or MySQL/PostgreSQL/TimescaleDB/DynamoDB for production workloads.
 - **REST Server Integration**: Automatic route setup with customizable access control.
 - **Lifecycle Hooks**: Middleware-based before/after hooks for validation, authorization, side effects, and auditing.
 
@@ -65,13 +65,16 @@ const {
   MYSQL_DATABASE,
   MYSQL_CONNECTION_LIMIT,
   MYSQL_MIGRATIONS_DIR,
+  DYNAMODB_REGION,
+  DYNAMODB_ENDPOINT,
+  DYNAMODB_TABLE_PREFIX,
 } = process.env;
 
 export default {
   orm: {
     logColor: 'white',
     logMethod: 'db',
-    
+
     db: {
       autosave: DB_AUTO_SAVE ?? 'false',
       file: DB_FILE ?? 'db.json',
@@ -95,6 +98,12 @@ export default {
       connectionLimit: parseInt(MYSQL_CONNECTION_LIMIT ?? '10'),
       migrationsDir: MYSQL_MIGRATIONS_DIR ?? 'migrations',
       migrationsTable: '__migrations',
+      autoMigrate: AUTO_MIGRATE === 'true' ? true : AUTO_MIGRATE === 'false' ? false : undefined,
+    } : undefined,
+    dynamodb: DYNAMODB_REGION ? {
+      region: DYNAMODB_REGION,
+      endpoint: DYNAMODB_ENDPOINT,          // optional, for DynamoDB Local
+      tablePrefix: DYNAMODB_TABLE_PREFIX,   // optional table name prefix
     } : undefined,
     restServer: {
       enabled: ORM_USE_REST_SERVER ?? 'true',
@@ -243,6 +252,31 @@ Set the `MYSQL_HOST` environment variable to enable MySQL persistence. The ORM l
 | `stonyx db:migrate` | Apply pending migrations |
 | `stonyx db:migrate:rollback` | Rollback the most recent migration |
 | `stonyx db:migrate:status` | Show migration status |
+| `stonyx db:sync` | Sync DynamoDB table definitions to match current model schemas |
+
+### DynamoDB Mode
+
+Set the `DYNAMODB_REGION` environment variable to enable DynamoDB persistence. Tables are created with PAY_PER_REQUEST (on-demand) billing. Global Secondary Indexes (GSIs) are auto-provisioned at startup based on model `belongsTo` relationships — each FK column gets a GSI. `findAll()` with conditions routes to a GSI Query when the condition key matches a GSI partition key; non-indexed attribute conditions fall back to Scan + FilterExpression (expensive for large tables). ULID generation replaces auto-increment for numeric-ID models.
+
+```javascript
+dynamodb: {
+  region: 'us-east-1',
+  endpoint: 'http://localhost:8000', // optional, for DynamoDB Local
+  tablePrefix: 'myapp-',            // optional table name prefix
+}
+```
+
+Environment variables:
+
+* `DYNAMODB_REGION`: AWS region for DynamoDB (e.g., `'us-east-1'`).
+* `DYNAMODB_ENDPOINT`: Optional custom endpoint URL, useful for DynamoDB Local during development.
+* `DYNAMODB_TABLE_PREFIX`: Optional prefix prepended to all table names (e.g., `'myapp-'` yields `'myapp-animals'`).
+
+**Peer dependencies:** `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` must be installed when using the DynamoDB driver. The AWS SDK is dynamically imported and only loaded when the DynamoDB driver is selected.
+
+```bash
+npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
+```
 
 ### Running MySQL Tests
 
@@ -275,19 +309,277 @@ import setupRestServer from '@stonyx/orm/setup-rest-server';
 await setupRestServer('/', './access');
 ```
 
-Access classes define models and provide custom filtering/authorization logic:
+Access classes define models and provide custom filtering/authorization logic.
+
+> **The URL-matching in this example is a stopgap. Read
+> [Matching the url](#matching-the-url) before copying it.** The same three-line
+> example has failed **open** in four distinct ways during one review, each found
+> only after the previous was fixed, by four different people. The sample below
+> closes all four; that is not the same as being safe — it is safe against the
+> four variants that happen to have been found, and there is no reason to believe
+> the list is complete.
+>
+> **The real fix is
+> [#202](https://github.com/abofs/stonyx-orm/issues/202)** — `access()` should
+> receive the model, the operation and the record, so there is no URL to parse
+> and no variant to miss. Until it lands, prefer the array shape (`['read']`) or
+> `false` where you can: the **function** shape is the one that requires URL
+> matching. The same warning is repeated at the top of `src/orm-request.ts`,
+> which ships; the longer write-up in `docs/usage-patterns.md` does **not** ship,
+> so this README and that source header are the two copies a consumer sees.
 
 ```js
+import config from 'stonyx/config';
+
+// Build the mount prefix from the SAME value the ORM mounts under, and compare
+// lower-cased. Both are load-bearing — see "Matching the url".
+function collectionPrefix(name) {
+  const route = config.orm.restServer.route ?? '/';
+  const trimmed = String(route).replace(/^\/+|\/+$/g, '');
+
+  return `${trimmed === '' ? '' : `/${trimmed}`}/${name}`.toLowerCase();
+}
+
 export default class GlobalAccess {
   models = ['owner', 'animal'];
 
   access(request) {
-    if (request.url.endsWith('/owner/angela')) return false;
+    // `originalUrl`, not `url` — `url` is mount-relative, so a prefix match
+    // against it is ALWAYS false. Query string stripped, because `originalUrl`
+    // carries it. Lower-cased, because the router matched case-insensitively
+    // and a matcher stricter than the router can be walked past. Every one of
+    // those three omissions fails OPEN.
+    const path = String(request.originalUrl ?? '').split('?')[0].toLowerCase();
+    const owners = collectionPrefix('owners');
+
+    // false → 403 for the whole request
+    if (path.startsWith(`${owners}/archived`)) return false;
+
+    // A function is a per-record filter. Anchored on a `/` boundary so it
+    // cannot also match `/owners-archive`. Rejected records are 404 on record
+    // routes, 403 on POST.
+    if (path === owners || path.startsWith(`${owners}/`)) {
+      return record => record.id !== 'angela';
+    }
+
     return ['read', 'create', 'update', 'delete'];
   }
 }
 ```
 
+### Return values
+
+| `access()` returns | Effect |
+|---|---|
+| `false` (or any falsy value) | `403` for the whole request |
+| `true` | full access, no filter |
+| `['read', 'create', 'update', 'delete']` | the listed operations only; anything else is `403` |
+| `'read'` (a bare string) | **one** permission, equivalent to `['read']` |
+| a function | a per-record filter — see below |
+| anything else | `403` — unknown shapes fail **closed** |
+
+A `throw` inside `access()` is a **denial**, not a 500.
+
+### Filter functions
+
+A function return value is a **per-record predicate**, and it is enforced on
+every endpoint that is addressed to a record — not only on the collection:
+
+| Endpoint | A record the predicate rejects |
+|---|---|
+| `GET /:models` | omitted from the collection |
+| `GET /:models/:id` | `404` |
+| `GET /:models/:id/{relationship}` | `404` — the **addressed** record is filtered, not the related one |
+| `GET /:models/:id/relationships/{relationship}` | `404` — same |
+| `PATCH /:models/:id` | `404`, no attribute is applied |
+| `DELETE /:models/:id` | `404`, the record is not removed and no SQL `DELETE` is issued |
+| `POST /:models` | `403`, and nothing is left in the store |
+
+**Denied record-level requests return 404, not 403.** This is deliberate and it
+is the property most easily "improved" away. 403 would confirm that the record
+exists to a caller who is not allowed to know that, which turns the filter into
+an existence oracle: `404` means "no such record", `403` means "there is one and
+it is not yours". Every status on a record route must therefore be identical for
+"filtered out" and "does not exist" — including `DELETE`, which is why deleting
+a record that never existed also returns 404 rather than 204.
+
+`POST` is the one exception and returns **403**, because 404 on a mounted
+collection route is indistinguishable from "model not mounted" — a genuinely
+different failure a developer needs to diagnose.
+
+**A client-supplied `id` on `POST` is refused with `403` whenever a function
+filter is in force.** This is the part that keeps `POST` from being an
+enumeration oracle, and it is worth understanding rather than working around.
+The duplicate-id check has to run before the filter, and it sees records the
+filter hides, so the *status* of a `POST` otherwise leaks whether an id is
+taken:
+
+| `POST /animals` with a payload the caller may create | before | now |
+|---|---|---|
+| an id held by a record the filter **hides** | `403` | `403` |
+| an id that is **free** | `200` | `403` |
+| an id held by a record the caller **can see** | `409` | `403` |
+
+Three outcomes, one request per id, the whole id space. Filtering only the
+*collision* status narrows that to callers who cannot create a record they are
+allowed to see; it does not close it. It cannot be closed while a caller both
+chooses the id and learns whether the create succeeded — so under a filter the
+caller does not choose the id. The refusal happens before any store lookup, so
+neither the status nor the response time depends on whether the id exists.
+
+Let the server assign the id and read it back from the response. Callers with no
+function-style filter are unaffected: `409` on a duplicate id and `200` on a free
+one both behave exactly as before.
+
+### Matching the url
+
+**This section describes a pattern the framework should not be asking you to
+implement.** It has produced four separate fail-open defects, listed below,
+each found only after the previous was fixed, and there is no reason to believe
+the list is complete. [#202](https://github.com/abofs/stonyx-orm/issues/202)
+replaces it. Until then, all four rules apply and each one, omitted, fails
+**open**.
+
+**1. Match `request.originalUrl`, never `request.url`.**
+`RestServer.mountRoute` mounts each model as an Express **sub-app**, so by the
+time `access()` runs the mount path has been stripped from `request.url`:
+
+| request | `request.url` | `request.originalUrl` |
+|---|---|---|
+| `GET /owners` | `/` | `/owners` |
+| `GET /owners/angela` | `/angela` | `/owners/angela` |
+| `GET /owners/angela/pets` | `/angela/pets` | `/owners/angela/pets` |
+
+`request.url.startsWith('/owners')` is therefore **always false**: the branch
+never fires, `access()` falls through to whatever it returns last, and a filter
+that looks correct enforces nothing on any surface.
+
+**2. Strip the query string, and match the prefix rather than the exact url.**
+The predicate has to be returned for record routes too, so
+`url.endsWith('/owners')` leaves `/owners/angela` unguarded — and `originalUrl`
+carries the query string, so a bare `=== '/owners'` misses
+`/owners?filter[age]=30` and lets a filtered collection through unfiltered.
+Anchoring on the path portion covers both without also matching
+`/owners-archive`.
+
+**3. Compare lower-cased.** `RestServer` mounts with a bare `express()`, whose
+default is `caseSensitive: false`, while `originalUrl` preserves the caller's
+case. A case-sensitive matcher is stricter than the router that dispatched the
+request, so it can simply be stepped around:
+
+```
+GET    /owners/angela  -> 404          GET    /OwNeRs/angela -> 200, angela in full
+GET    /owners         -> filtered     GET    /OWNERS        -> unfiltered
+DELETE /animals/22     -> 404          DELETE /ANIMALS/22    -> 204, record destroyed
+```
+
+Lower-case the **path** only. Record ids are case-sensitive and must be compared
+at their real case. The router-side fix is tracked as
+[stonyx-rest-server#47](https://github.com/abofs/stonyx-rest-server/issues/47).
+
+**4. Build the prefix from the configured mount route.** With
+`ORM_REST_ROUTE=/api` the urls above become `/api/owners/...`, and a sample
+hard-coded to `/owners` matches nothing — environment-specifically, which is
+harder to notice than failing everywhere.
+
+Note what this must *not* be. An earlier version of this document suggested
+`` `${config.orm.restServer.route}owners` ``. For the default route that is
+`/owners` and looks correct; for `ORM_REST_ROUTE=/api` it evaluates to
+**`/apiowners`**, so a reader who followed the correction exactly still failed
+open and believed they had handled it. Join on `/` and collapse the duplicate,
+as `collectionPrefix()` above does.
+
+### Known limitations
+
+- **Authorization by URL matching is a consumer-side reconstruction of
+  information the framework already holds.** `access()` receives a transport
+  artifact and is asked to re-derive, correctly and defensively, which model,
+  which operation and which record the request addresses. The four rules above
+  are the four ways that reconstruction has been observed to fail open so far.
+  Tracked as [#202](https://github.com/abofs/stonyx-orm/issues/202).
+- **Related and included records are not filtered.** The predicate is evaluated
+  against the record the route is *addressed to*. `GET /animals/1/owner`,
+  `GET /animals/1/relationships/owner` and `?include=owner` all serialize the
+  related record without resolving that model's own access class, so a filter on
+  `/owners` does not hide an owner reached through `/animals`. Tracked as
+  [#196](https://github.com/abofs/stonyx-orm/issues/196), which covers
+  `include=`, related-resource routes and relationship-linkage routes.
+- **A before-hook that returns a value short-circuits the request.** On write
+  operations addressed to a record the filter is consulted first, so a hook
+  cannot answer for a record the caller may not see. On reads it is not, so a
+  `beforeHook('get', ...)` read-through cache can answer past the filter.
+- **`beforeHook('create', ...)` still runs for a `POST` that is denied.** For
+  `create` there is no record to test until the handler has built one, so the
+  denial is not knowable in time. Every *after*-hook is gated, and every
+  before-hook on `update` and `delete` is gated; before-`create` is the one
+  exception. A before-`create` hook must not assume the create will succeed.
+- **A caller can still learn that a collection *has* a per-record filter**, by
+  observing `403` rather than `409`/`200` for an id-bearing `POST`. That
+  discloses a configuration fact, not the existence of any record.
+- **Enforcement is post-fetch.** The record is loaded and then tested, which
+  leaves a small timing difference between a hidden record and one that never
+  existed. Tracked as [#197](https://github.com/abofs/stonyx-orm/issues/197).
+- **A `relationships` key that is not a declared relationship is still applied
+  to the record.** The key comes verbatim from the request body and is checked
+  against nothing except `id`, which is stripped. On a `POST` that makes an
+  undeclared key a mass-assigned attribute; on a `PATCH` it is passed to
+  `updateRecord`. `id` is stripped in both handlers because it defeats breaking
+  change 3 above; the general form is tracked as
+  [#204](https://github.com/abofs/stonyx-orm/issues/204).
+- **A partially numeric `id` in a `POST` body can overwrite a different record
+  on an unfiltered collection.** The duplicate check rejects `"9105h"` as a
+  string, correctly, but the model's id transform truncates it to `9105` and the
+  create lands there. Filtered collections are unaffected — breaking change 3
+  refuses any client-supplied id — so this reaches consumers with **no**
+  function-style filter. Tracked as
+  [#205](https://github.com/abofs/stonyx-orm/issues/205), alongside
+  [#203](https://github.com/abofs/stonyx-orm/issues/203), which is the other way
+  a create can land on an id nobody named.
+
+### Breaking changes in 0.4.0
+
+There is no changelog or release-notes channel yet
+([stonyx-workflows#17](https://github.com/abofs/stonyx-workflows/issues/17)), so
+they are recorded here.
+
+1. **`DELETE /{collection}/{id}` on a record that does not exist returns `404`
+   instead of `204`.** This affects **every** consumer issuing a DELETE against
+   any mounted collection, whether or not an access filter is configured, and
+   `models: '*'` mounts every model by default. It is not optional: if a denied
+   delete returned 404 while a missing one returned 204, the pair would be a
+   perfect existence oracle and the filter would be worthless.
+2. **After-hooks no longer fire for a write that failed** — denied, missing,
+   `400` or `409`. Previously `afterHook('delete', ...)` ran with a populated
+   `context.recordId` on a request that deleted nothing, so a consumer cascade
+   destroyed children behind a 404.
+3. **`POST` with a client-supplied `id` returns `403` when a function-style
+   `access` filter is in force**, whatever the payload and whether or not the id
+   exists, and *before* any store lookup — so neither the status nor the lookup
+   cost can depend on whether that id exists. Only affects function-style
+   `access` users. See [Filter functions](#filter-functions) for why, and let the
+   server assign the id instead. `409`-on-duplicate is unchanged for everyone
+   else.
+
+   "Whatever the payload" is a statement about the **`id` member of the resource
+   object**, and it holds only because that is the sole channel a caller id can
+   arrive on. It was not always: a caller id moved into
+   `relationships: {"id": {"data": {"id": 21}}}` reached `createRecord` past this
+   refusal and overwrote a hidden record in place. Both strips — `attributes.id`
+   and `relationships.id` — are part of this behaviour, not tidiness. A future
+   change that adds a third channel without stripping it re-opens the oracle;
+   see [#204](https://github.com/abofs/stonyx-orm/issues/204).
+4. **Function-style `access` is now enforced on all seven surfaces.** Records
+   previously reachable by id despite being filtered from the collection now
+   return 404. Only affects function-style `access` users, for whom the old
+   behaviour was the bypass.
+5. **A predicate that throws is treated as a denial** rather than propagating to
+   Express's default 500 handler. So is an `access()` that throws.
+6. **`access()` returning a bare string is one permission, not full access.**
+   `AccessMethod` declares `string` legal, and it previously fell through every
+   branch and granted all four operations — `return 'read'` allowed `DELETE`.
+   It is now equivalent to `['read']`. Any other unrecognised shape (an object,
+   a number) now returns `403` rather than granting full access.
+
 ### Include Parameter (Sideloading Relationships)
 
 The ORM supports JSON API-compliant relationship sideloading via the `include` query parameter. This reduces the need for multiple API requests by embedding related records in a single response.

package/config/environment.js

@@ -1,12 +1,99 @@
-// project configuration, override-able by listed environment variables
-const {
-  DEBUG,
-  NODE_ENV,
-} = process.env;
-
-const environment = NODE_ENV ?? 'development';
-
-export default {
-  environment,
-  debug: DEBUG ?? environment === 'development',
-}
+const {
+  ORM_ACCESS_PATH,
+  ORM_MODEL_PATH,
+  ORM_REST_ROUTE,
+  ORM_SERIALIZER_PATH,
+  ORM_TRANSFORM_PATH,
+  ORM_VIEW_PATH,
+  ORM_USE_REST_SERVER,
+  DB_AUTO_SAVE,
+  DB_FILE,
+  DB_MODE,
+  DB_DIRECTORY,
+  DB_SCHEMA_PATH,
+  DB_SAVE_INTERVAL,
+  MYSQL_HOST,
+  MYSQL_PORT,
+  MYSQL_USER,
+  MYSQL_PASSWORD,
+  MYSQL_DATABASE,
+  MYSQL_CONNECTION_LIMIT,
+  MYSQL_MIGRATIONS_DIR,
+  PG_HOST,
+  PG_PORT,
+  PG_USER,
+  PG_PASSWORD,
+  PG_DATABASE,
+  PG_CONNECTION_LIMIT,
+  PG_MIGRATIONS_DIR,
+  TIMESCALE_HOST,
+  TIMESCALE_PORT,
+  TIMESCALE_USER,
+  TIMESCALE_PASSWORD,
+  TIMESCALE_DATABASE,
+  TIMESCALE_CONNECTION_LIMIT,
+  TIMESCALE_MIGRATIONS_DIR,
+  DYNAMODB_REGION,
+  DYNAMODB_ENDPOINT,
+  DYNAMODB_TABLE_PREFIX,
+} = process.env;
+
+export default {
+  logColor: 'white',
+  logMethod: 'db',
+  
+  db: {
+    autosave: DB_AUTO_SAVE ?? 'false', // 'true' (cron interval), 'false' (disabled), 'onUpdate' (save after each write op)
+    file: DB_FILE ?? 'db.json',
+    mode: DB_MODE ?? 'file', // 'file' (single db.json) or 'directory' (one file per collection)
+    directory: DB_DIRECTORY ?? 'db', // directory name for collection files when mode is 'directory'
+    saveInterval: DB_SAVE_INTERVAL ?? 60 * 60, // 1 hour
+    schema: DB_SCHEMA_PATH ?? './config/db-schema.js'
+  },
+  paths: {
+    access: ORM_ACCESS_PATH ?? './access', // Optional for restServer access hooks
+    model: ORM_MODEL_PATH ?? './models',
+    serializer: ORM_SERIALIZER_PATH ?? './serializers',
+    transform: ORM_TRANSFORM_PATH ?? './transforms',
+    view: ORM_VIEW_PATH ?? './views'
+  },
+  mysql: MYSQL_HOST ? {
+    host: MYSQL_HOST ?? 'localhost',
+    port: parseInt(MYSQL_PORT ?? '3306'),
+    user: MYSQL_USER ?? 'root',
+    password: MYSQL_PASSWORD ?? '',
+    database: MYSQL_DATABASE ?? 'stonyx',
+    connectionLimit: parseInt(MYSQL_CONNECTION_LIMIT ?? '10'),
+    migrationsDir: MYSQL_MIGRATIONS_DIR ?? 'migrations',
+    migrationsTable: '__migrations',
+  } : undefined,
+  postgres: PG_HOST ? {
+    host: PG_HOST ?? 'localhost',
+    port: parseInt(PG_PORT ?? '5432'),
+    user: PG_USER ?? 'postgres',
+    password: PG_PASSWORD ?? '',
+    database: PG_DATABASE ?? 'stonyx',
+    connectionLimit: parseInt(PG_CONNECTION_LIMIT ?? '10'),
+    migrationsDir: PG_MIGRATIONS_DIR ?? 'migrations',
+    migrationsTable: '__migrations',
+  } : undefined,
+  timescale: TIMESCALE_HOST ? {
+    host: TIMESCALE_HOST ?? 'localhost',
+    port: parseInt(TIMESCALE_PORT ?? '5432'),
+    user: TIMESCALE_USER ?? 'postgres',
+    password: TIMESCALE_PASSWORD ?? '',
+    database: TIMESCALE_DATABASE ?? 'stonyx',
+    connectionLimit: parseInt(TIMESCALE_CONNECTION_LIMIT ?? '10'),
+    migrationsDir: TIMESCALE_MIGRATIONS_DIR ?? 'migrations',
+    migrationsTable: '__migrations',
+  } : undefined,
+  dynamodb: DYNAMODB_REGION ? {
+    region: DYNAMODB_REGION,
+    endpoint: DYNAMODB_ENDPOINT || undefined,
+    tablePrefix: DYNAMODB_TABLE_PREFIX || '',
+  } : undefined,
+  restServer: {
+    enabled: ORM_USE_REST_SERVER ?? 'true', // Whether to load restServer for automatic route setup or
+    route: ORM_REST_ROUTE ?? '/',
+  }
+}

package/dist/commands.js

@@ -20,6 +20,11 @@ const commands = {
         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);
@@ -31,12 +36,33 @@ const commands = {
             }
         }
     },
+    '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,
         run: async () => {
             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);
@@ -75,6 +101,10 @@ const commands = {
         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) {
                 console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');
@@ -113,6 +143,10 @@ const commands = {
         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) {
                 console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');

package/dist/dynamodb/connection.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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;
+}
+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 declare function createDocumentClient(dbConfig: DynamoDBConfig): Promise<DocumentClient>;
+/**
+ * Nullify the document client reference (DynamoDB connections are HTTP-based
+ * and stateless — no explicit pool close needed, but we clear the reference).
+ */
+export declare function destroyDocumentClient(_client: DocumentClient | null): null;

package/dist/dynamodb/connection.js

@@ -0,0 +1,28 @@
+/**
+ * DynamoDB connection factory.
+ *
+ * Dynamically imports @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb
+ * so these are optional peerDependencies (matching the pg/mysql2 pattern).
+ */
+/**
+ * Create a DynamoDBDocumentClient from the given config.
+ * Uses dynamic import so @aws-sdk/* are optional peer deps.
+ */
+export async function createDocumentClient(dbConfig) {
+    const { DynamoDBClient } = await import('@aws-sdk/client-dynamodb');
+    const { DynamoDBDocumentClient } = await import('@aws-sdk/lib-dynamodb');
+    const clientOptions = {};
+    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) {
+    return null;
+}