@stonyx/orm 0.3.2-alpha.1 → 0.3.2-alpha.100

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',
@@ -104,6 +113,12 @@ export default {
 };
 ```
 
+> **`route` and JSON:API `links`.** Generated endpoints are mounted under `route`, and every
+> `links.self` / `links.related` the ORM emits is an absolute URL that includes it. With
+> `ORM_REST_ROUTE='/api'` the animal collection is served at `/api/animals` and advertises
+> `http://host/api/animals`, so published links are followable as-is — do not prepend the
+> mount yourself.
+
 Then run the application via the Stonyx CLI, which auto-initializes all modules including the ORM:
 
 ```bash
@@ -243,6 +258,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
 
@@ -278,16 +318,127 @@ await setupRestServer('/', './access');
 Access classes define models and provide custom filtering/authorization logic:
 
 ```js
-export default class GlobalAccess {
-  models = ['owner', 'animal'];
+export default class OwnerAccess {
+  models = ['owner'];
+
+  access(request) {
+    // `access` runs after route matching, so `request.params` is populated and
+    // `id` has already been URL-decoded. Authorize on it, never on a URL.
+    const { id } = request.params;
+
+    // `id` is still raw client text. Normalise it the way the record lookup
+    // does, or your predicate and the lookup disagree — see "Numeric ids" below.
+    // No radix on parseInt: that is deliberate, and it must stay that way.
+    const recordId = id === undefined ? undefined : (isNaN(id) ? id : parseInt(id));
+
+    // Returning false explicitly denies access to this record
+    if (recordId === 'angela') return false;
+
+    // No `id` means the collection route. Returning a function plugs it in to
+    // the response object as a filter. NOTE: a function return authorizes the
+    // request outright — the operations list below is not consulted — so this
+    // branch permits POST /owners as well as reads.
+    if (recordId === undefined) return record => record.id !== 'angela';
+
+    // Returning a list of operations allows full access to everything else
+    return ['read', 'create', 'update', 'delete'];
+  }
+}
+```
+
+**Do not authorize on the request URL.** `request.url` is rewritten relative to
+the mount point, so inside the REST server it is `/angela`, not `/owners/angela`
+— a suffix comparison against it never matches and the request falls through to
+whatever the method returns next. `request.originalUrl` keeps the full path but
+is still the raw text the client sent, so it varies with query strings
+(`/owners?x=1`), trailing slashes (`/owners/angela/`), casing (`/OwNeRs/angela`)
+and percent-encoding (`/owners/%61ngela`). Each of those is a plain address-bar
+request. Which of them reach your handler at all depends on how the REST server
+configures Express route matching — that is a deployment detail you should not
+be building an authorization decision on top of. `request.params.id` is
+identical for every spelling that does reach you.
+
+**One access class per model when the rules are model-specific.** `access()`
+receives only the request, and the request does not carry the model name
+directly — `request.baseUrl` is the *mount text as the client spelled it*
+(`/OWNERS`), so it must be case-normalised before it is compared, and it is
+still the mount rather than the model. Deriving a model from it means every
+unrecognised spelling falls through to whatever your method returns next, so
+prefer one class per model. A class may still list several models in `models`
+when they share one rule.
+
+**Numeric ids: normalise before you compare.** `request.params.id` is raw text
+from the client. When it looks numeric the ORM coerces it — `isNaN(id) ? id :
+parseInt(id)` — *before* it resolves the record, so `7`, `007`, `7.0`, `7.9`,
+`7e0`, `0x7`, `+7`, `%207` (a leading space), `%09 7` (a tab) and `7%0A` (a
+trailing newline) all address record `7`, while a `===` against the raw text
+matches only the one spelling you wrote down. Every other spelling falls through
+to whatever your method returns next — which, in the shape above, is a full CRUD
+grant. All of them are plain address-bar requests.
+
+Two details are load-bearing. `parseInt` is called with **no radix**, so `0x7`
+is `7` and not `0`; writing `parseInt(id, 10)` in your predicate re-opens the
+hex spelling. And the coercion applies only when the id looks numeric, so a
+model with string ids (like `owner` above) is unaffected — which is exactly why
+this is easy to miss. Normalise the same way the lookup does:
+
+```javascript
+export default class AnimalAccess {
+  models = ['animal'];
 
   access(request) {
-    if (request.url.endsWith('/owner/angela')) return false;
+    const { id } = request.params;
+
+    // Agrees with the lookup for every spelling of 7 above. Compare the
+    // coerced value, which for a numeric-id model is a number, not a string.
+    const recordId = id === undefined ? undefined : (isNaN(id) ? id : parseInt(id));
+
+    if (recordId === 7) return false;
+
+    if (recordId === undefined) return record => record.id !== 7;
+
     return ['read', 'create', 'update', 'delete'];
   }
 }
 ```
 
+Both samples above are extracted from this file and executed verbatim against a
+live server on every CI run — see
+[`test/integration/readme-access/`](https://github.com/abofs/stonyx-orm/tree/dev/test/integration/readme-access).
+`DELETE /owners/angela` is asserted to be refused with the record intact, and
+every spelling named above is measured individually, the numeric ones over a raw
+socket. Nothing in this section is prose that was never run.
+
+### Upgrading: behaviour changes
+
+**Advertised `links.self` / `links.related` now carry the REST mount route.**
+Consumer-visible for any deployment where `orm.restServer.route` is not the
+default `'/'`.
+
+Measured on this repo's mounted-route harness at `ORM_REST_ROUTE='/api'`, resource
+`links.self` in the response to `GET /api/animals/1`:
+
+| | published `links.self` | fetching that URL |
+|---|---|---|
+| before | `http://host/animals/1` | **404** |
+| after | `http://host/api/animals/1` | **200** |
+
+The ORM previously built links from the request origin alone, so at any non-default
+mount every URL it advertised pointed at a route that did not exist
+(abofs/stonyx-orm#254). Links are now built from the path the routes are actually
+mounted at, and are followable verbatim.
+
+**⚠️ Breaking if you carry a prepending workaround.** The usual workaround for #254
+was for the client to prepend the mount to every link the ORM published. That now
+double-prefixes: prepending `/api` to the new `http://host/api/animals/1` yields
+`http://host/api/api/animals/1`, measured **404**. Remove the prepending. There is no
+configuration flag that restores the old link shape.
+
+**Unaffected.** Deployments on the default `ORM_REST_ROUTE='/'` see byte-identical
+output — the prefix is empty, and this is pinned by a byte-identity test against a
+golden fixture captured *before* the fix. Response structure, field names and the
+public API are unchanged; only the URL value inside `links` changes.
+
 ### 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

@@ -33,6 +33,9 @@ const {
   TIMESCALE_DATABASE,
   TIMESCALE_CONNECTION_LIMIT,
   TIMESCALE_MIGRATIONS_DIR,
+  DYNAMODB_REGION,
+  DYNAMODB_ENDPOINT,
+  DYNAMODB_TABLE_PREFIX,
 } = process.env;
 
 export default {
@@ -84,6 +87,11 @@ export default {
     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;
+}

package/dist/dynamodb/dynamodb-db.d.ts

@@ -0,0 +1,142 @@
+/**
+ * DynamoDB driver implementing the SqlDb PAL contract.
+ *
+ * Drop-in replacement for PostgresDB / MysqlDB — zero ORM core changes.
+ * Selected via config.orm.dynamodb.
+ */
+import { createDocumentClient, destroyDocumentClient } from './connection.js';
+import type { DocumentClient, DynamoDBConfig } from './connection.js';
+import { buildPutItem, buildGetItem, buildUpdateItem, buildDeleteItem, buildScan, buildQuery } from './operation-builder.js';
+import { introspectModels, getTopologicalOrder } from '../postgres/schema-introspector.js';
+import { getDynamoKeyType } from './type-map.js';
+import { store } from '@stonyx/orm';
+import { createRecord } from '../manage-record.js';
+import { getPluralName } from '../plural-registry.js';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import type { OrmRecord } from '../types/orm-types.js';
+/**
+ * Load the DynamoDB DocumentClient command constructors via dynamic import.
+ * Returns a frozen object so it can be cached in deps.
+ */
+export declare function loadDocClientCommands(): Promise<{
+    PutCommand: new (params: unknown) => unknown;
+    GetCommand: new (params: unknown) => unknown;
+    UpdateCommand: new (params: unknown) => unknown;
+    DeleteCommand: new (params: unknown) => unknown;
+    ScanCommand: new (params: unknown) => unknown;
+    QueryCommand: new (params: unknown) => unknown;
+}>;
+export declare function loadTableCommands(): Promise<{
+    DynamoDBClient: new (opts: unknown) => {
+        send(cmd: unknown): Promise<unknown>;
+    };
+    DescribeTableCommand: new (params: unknown) => unknown;
+    CreateTableCommand: new (params: unknown) => unknown;
+    UpdateTableCommand: new (params: unknown) => unknown;
+}>;
+interface PersistContext {
+    record?: OrmRecord;
+    recordId?: unknown;
+    oldState?: Record<string, unknown>;
+    rawData?: Record<string, unknown>;
+}
+interface PersistResponse {
+    data?: {
+        id?: unknown;
+    };
+}
+/** Minimal Orm module shape needed at runtime — avoids circular import at top-level. */
+interface OrmModule {
+    default: {
+        instance: {
+            getRecordClasses(name: string): {
+                modelClass: {
+                    memory?: boolean;
+                };
+            };
+            isView?(name: string): boolean;
+        };
+    };
+}
+export interface DynamoDBDeps {
+    createDocumentClient: typeof createDocumentClient;
+    destroyDocumentClient: typeof destroyDocumentClient;
+    loadDocClientCommands: typeof loadDocClientCommands;
+    loadTableCommands: typeof loadTableCommands;
+    buildPutItem: typeof buildPutItem;
+    buildGetItem: typeof buildGetItem;
+    buildUpdateItem: typeof buildUpdateItem;
+    buildDeleteItem: typeof buildDeleteItem;
+    buildScan: typeof buildScan;
+    buildQuery: typeof buildQuery;
+    introspectModels: typeof introspectModels;
+    getTopologicalOrder: typeof getTopologicalOrder;
+    getDynamoKeyType: typeof getDynamoKeyType;
+    createRecord: typeof createRecord;
+    store: typeof store;
+    getPluralName: typeof getPluralName;
+    config: typeof config;
+    log: typeof log;
+    /** Injected for testing — import('@stonyx/orm') replacement */
+    _importOrm?: () => Promise<OrmModule>;
+    [key: string]: unknown;
+}
+export default class DynamoDBDB {
+    static instance: DynamoDBDB | undefined;
+    deps: DynamoDBDeps;
+    client: DocumentClient | null;
+    dbConfig: DynamoDBConfig;
+    /** GSI registry built during init from model introspection. */
+    private _gsiRegistry;
+    constructor(deps?: Partial<DynamoDBDeps>);
+    private requireClient;
+    private _resolveTableName;
+    /** Resolve Orm singleton — falls back to real import in production. */
+    private _getOrm;
+    init(): Promise<void>;
+    /**
+     * For each model, DescribeTable — CreateTable if missing (with GSIs, PAY_PER_REQUEST).
+     * For existing tables, check for missing GSIs and UpdateTable + poll for ACTIVE.
+     */
+    startup(): Promise<void>;
+    shutdown(): Promise<void>;
+    /**
+     * DynamoDB does NOT use write serialization (#156).
+     *
+     * Unlike MySQL/PostgreSQL, DynamoDB has no server-side foreign key
+     * constraints and no multi-row transactions in standard single-item
+     * operations (PutItem, UpdateItem, DeleteItem). Each operation is
+     * atomic at the item level and cannot deadlock against other items.
+     * Concurrent fire-and-forget writes therefore cannot produce the
+     * cross-row lock contention that causes InnoDB/PG deadlocks.
+     */
+    persist(operation: string, modelName: string, context: PersistContext, response: PersistResponse): Promise<void>;
+    findRecord(modelName: string, id: unknown): Promise<OrmRecord | undefined>;
+    findAll(modelName: string, conditions?: Record<string, unknown>): Promise<OrmRecord[]>;
+    loadMemoryRecords(): Promise<void>;
+    private _persistCreate;
+    private _persistUpdate;
+    private _persistDelete;
+    private _paginatedScan;
+    private _paginatedQuery;
+    /**
+     * Build the GSI registry from model introspection.
+     * Registry: modelName → attrName → gsiName
+     *
+     * FK columns (belonging to belongsTo relationships) get a GSI automatically.
+     */
+    private _buildGsiRegistry;
+    /**
+     * Find a GSI that can serve the given conditions.
+     */
+    private _findGsiMatch;
+    private _buildAttributeDefinitions;
+    private _buildGsiDefinitions;
+    private _waitForTableActive;
+    private _itemToRawData;
+    private _recordToItem;
+    private _evictIfNotMemory;
+    loadAllRecords(): Promise<void>;
+}
+export {};