@stonyx/orm 0.3.2-beta.15 → 0.3.2-beta.151

package/dist/dynamodb/operation-builder.js

@@ -0,0 +1,116 @@
+/**
+ * DynamoDB operation parameter builders.
+ *
+ * Each function returns a plain-object "params" bag that can be passed
+ * directly to the corresponding DocumentClient command
+ * (PutCommand, GetCommand, UpdateCommand, DeleteCommand, ScanCommand, QueryCommand).
+ *
+ * All functions are pure — no SDK imports here; the caller wraps params
+ * in the appropriate Command class.
+ */
+/**
+ * PutItem — optionally with a condition expression.
+ *
+ * Pass conditionExpression = 'attribute_not_exists(id)' to enforce uniqueness.
+ */
+export function buildPutItem(tableName, item, conditionExpression) {
+    const params = { TableName: tableName, Item: item };
+    if (conditionExpression)
+        params.ConditionExpression = conditionExpression;
+    return params;
+}
+/**
+ * GetItem by primary key.
+ */
+export function buildGetItem(tableName, key) {
+    return { TableName: tableName, Key: key };
+}
+/**
+ * UpdateItem with a SET expression built from the `updates` object.
+ * Only the supplied attributes are updated (diff-based call site).
+ */
+export function buildUpdateItem(tableName, key, updates) {
+    const names = {};
+    const values = {};
+    const setClauses = [];
+    for (const [attr, val] of Object.entries(updates)) {
+        const nameAlias = `#${attr}`;
+        const valAlias = `:${attr}`;
+        names[nameAlias] = attr;
+        values[valAlias] = val;
+        setClauses.push(`${nameAlias} = ${valAlias}`);
+    }
+    return {
+        TableName: tableName,
+        Key: key,
+        UpdateExpression: `SET ${setClauses.join(', ')}`,
+        ExpressionAttributeNames: names,
+        ExpressionAttributeValues: values,
+        ReturnValues: 'NONE',
+    };
+}
+/**
+ * DeleteItem by primary key.
+ */
+export function buildDeleteItem(tableName, key) {
+    return { TableName: tableName, Key: key };
+}
+/**
+ * ScanCommand params.
+ * If conditions are supplied they are rendered as a FilterExpression using AND.
+ */
+export function buildScan(tableName, conditions, exclusiveStartKey) {
+    const params = { TableName: tableName };
+    if (exclusiveStartKey)
+        params.ExclusiveStartKey = exclusiveStartKey;
+    if (conditions && Object.keys(conditions).length > 0) {
+        const validEntries = Object.entries(conditions).filter(([, val]) => val !== undefined && val !== null);
+        if (validEntries.length > 0) {
+            const names = {};
+            const values = {};
+            const clauses = [];
+            for (const [attr, val] of validEntries) {
+                const nameAlias = `#${attr}`;
+                const valAlias = `:${attr}`;
+                names[nameAlias] = attr;
+                values[valAlias] = val;
+                clauses.push(`${nameAlias} = ${valAlias}`);
+            }
+            params.FilterExpression = clauses.join(' AND ');
+            params.ExpressionAttributeNames = names;
+            params.ExpressionAttributeValues = values;
+        }
+    }
+    return params;
+}
+/**
+ * QueryCommand params for a GSI.
+ * keyConditions must be in the form { attrName: value } and will be rendered
+ * as equality expressions joined by AND.
+ */
+export function buildQuery(tableName, indexName, keyConditions, exclusiveStartKey) {
+    const validEntries = Object.entries(keyConditions).filter(([, val]) => val !== undefined && val !== null);
+    if (validEntries.length === 0) {
+        throw new Error('buildQuery: all keyCondition values are undefined/null');
+    }
+    const names = {};
+    const values = {};
+    const clauses = [];
+    for (const [attr, val] of validEntries) {
+        const nameAlias = `#${attr}`;
+        const valAlias = `:${attr}`;
+        names[nameAlias] = attr;
+        values[valAlias] = val;
+        clauses.push(`${nameAlias} = ${valAlias}`);
+    }
+    const params = {
+        TableName: tableName,
+        IndexName: indexName,
+        KeyConditionExpression: clauses.join(' AND '),
+        ExpressionAttributeNames: names,
+        ExpressionAttributeValues: values,
+    };
+    if (exclusiveStartKey)
+        params.ExclusiveStartKey = exclusiveStartKey;
+    return params;
+}

package/dist/dynamodb/type-map.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Maps ORM attribute types to DynamoDB scalar attribute types.
+ * DynamoDB DocumentClient auto-marshalls JS objects, so most values
+ * are sent as their native JS types.  This map is used by the
+ * schema-introspector and startup provisioner for table/GSI creation.
+ */
+export type DynamoScalarType = 'S' | 'N' | 'BOOL';
+/**
+ * DynamoDB attribute-type string for a given ORM attr type.
+ * - string            → S
+ * - number / float    → N  (stored as Number; DocumentClient handles it)
+ * - boolean           → BOOL
+ * - date              → S  (ISO-8601 string — enables range queries)
+ * - timestamp         → N  (milliseconds since epoch)
+ * - passthrough/trim/etc → S  (safe default)
+ *
+ * For key schema declarations only `S` and `N` are valid; BOOL
+ * is legal for attributes but never for a PK/SK.
+ */
+declare const typeMap: Record<string, DynamoScalarType>;
+/**
+ * Returns the DynamoDB attribute type for a given ORM type string.
+ * Defaults to 'S' for any unknown/custom type.
+ */
+export declare function getDynamoType(attrType: string): DynamoScalarType;
+/**
+ * Returns the DynamoDB key type ('S' | 'N') for use in KeySchema.
+ * BOOL cannot be a key attribute; anything that maps to BOOL falls back to 'S'.
+ */
+export declare function getDynamoKeyType(attrType: string): 'S' | 'N';
+export default typeMap;

package/dist/dynamodb/type-map.js

@@ -0,0 +1,48 @@
+/**
+ * Maps ORM attribute types to DynamoDB scalar attribute types.
+ * DynamoDB DocumentClient auto-marshalls JS objects, so most values
+ * are sent as their native JS types.  This map is used by the
+ * schema-introspector and startup provisioner for table/GSI creation.
+ */
+/**
+ * DynamoDB attribute-type string for a given ORM attr type.
+ * - string            → S
+ * - number / float    → N  (stored as Number; DocumentClient handles it)
+ * - boolean           → BOOL
+ * - date              → S  (ISO-8601 string — enables range queries)
+ * - timestamp         → N  (milliseconds since epoch)
+ * - passthrough/trim/etc → S  (safe default)
+ *
+ * For key schema declarations only `S` and `N` are valid; BOOL
+ * is legal for attributes but never for a PK/SK.
+ */
+const typeMap = {
+    string: 'S',
+    number: 'N',
+    float: 'N',
+    boolean: 'BOOL',
+    date: 'S',
+    timestamp: 'N',
+    passthrough: 'S',
+    trim: 'S',
+    uppercase: 'S',
+    ceil: 'N',
+    floor: 'N',
+    round: 'N',
+};
+/**
+ * Returns the DynamoDB attribute type for a given ORM type string.
+ * Defaults to 'S' for any unknown/custom type.
+ */
+export function getDynamoType(attrType) {
+    return typeMap[attrType] ?? 'S';
+}
+/**
+ * Returns the DynamoDB key type ('S' | 'N') for use in KeySchema.
+ * BOOL cannot be a key attribute; anything that maps to BOOL falls back to 'S'.
+ */
+export function getDynamoKeyType(attrType) {
+    const t = getDynamoType(attrType);
+    return t === 'N' ? 'N' : 'S';
+}
+export default typeMap;

package/dist/main.js

@@ -54,6 +54,10 @@ export default class Orm {
         Orm.instance = this;
     }
     async init() {
+        // Self-register so log.db works even when @stonyx/orm is in the
+        // consumer's `dependencies` (stonyx loader only merges devDependencies).
+        const { logColor = 'white', logMethod = 'db' } = config.orm;
+        log.defineType(logMethod, logColor);
         const { paths, restServer } = config.orm;
         const promises = ['Model', 'Serializer', 'Transform'].map(type => {
             const lowerCaseType = type.toLowerCase();
@@ -115,6 +119,12 @@ export default class Orm {
             this.db = this.sqlDb;
             promises.push(this.sqlDb.init());
         }
+        else if (config.orm.dynamodb) {
+            const { default: DynamoDBDB } = await import('./dynamodb/dynamodb-db.js');
+            this.sqlDb = new DynamoDBDB();
+            this.db = this.sqlDb;
+            promises.push(this.sqlDb.init());
+        }
         else if (this.options.dbType !== 'none') {
             const db = new DB();
             this.db = db;

package/dist/manage-record.js

@@ -52,13 +52,34 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
             relationship.push(record);
         pendingHasMany.splice(0);
     }
+    // FK-based inverse hasMany wiring — when a child record is created with a
+    // foreign-key field (e.g. `owner: 'owner-1'` on an animal), find any parent
+    // whose hasMany registry targets this model and push the child into the
+    // parent's shared array.  This covers edge cases where the child is created
+    // in a separate async frame without a belongsTo handler firing.
+    const hasManyReg = getHasManyRegistry();
+    if (hasManyReg) {
+        for (const [parentModelName, targetMap] of hasManyReg) {
+            const childArrayMap = targetMap.get(modelName);
+            if (!childArrayMap)
+                continue;
+            // Check if rawData contains a FK field matching the parent model name
+            const fkValue = rawData[parentModelName];
+            if (fkValue === undefined || fkValue === null)
+                continue;
+            const parentArray = childArrayMap.get(fkValue);
+            if (parentArray && !parentArray.includes(record)) {
+                parentArray.push(record);
+            }
+        }
+    }
     // Fulfill pending belongsTo relationships
     const pendingBelongsToQueue = getPendingBelongsToRegistry();
     const pendingBelongsToRaw = pendingBelongsToQueue.get(modelName)?.get(record.id);
     const pendingBelongsTo = Array.isArray(pendingBelongsToRaw) ? pendingBelongsToRaw : undefined;
     if (pendingBelongsTo) {
         const belongsToReg = getBelongsToRegistry();
-        const hasManyReg = getHasManyRegistry();
+        const pendingHasManyReg = getHasManyRegistry();
         for (const { sourceRecord, sourceModelName, relationshipKey, relationshipId } of pendingBelongsTo) {
             // Update the belongsTo relationship on the source record
             sourceRecord.__relationships[relationshipKey] = record;
@@ -72,7 +93,7 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
                 }
             }
             // Wire inverse hasMany if it exists
-            const inverseHasMany = hasManyReg.get(modelName)?.get(sourceModelName)?.get(record.id);
+            const inverseHasMany = pendingHasManyReg.get(modelName)?.get(sourceModelName)?.get(record.id);
             if (inverseHasMany && !inverseHasMany.includes(sourceRecord)) {
                 inverseHasMany.push(sourceRecord);
             }
@@ -83,14 +104,24 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
     // Auto-persist to SQL — skip for DB loads (isDbRecord) and relationship resolution (_relationshipKey)
     const shouldPersist = orm?.sqlDb && !options.isDbRecord && !userOptions._relationshipKey && !options._skipAutoPersist;
     if (shouldPersist) {
+        // Capture ID before persist — SQL adapters re-key pending IDs to real DB IDs,
+        // but relationship registries were keyed with this original ID
+        const registryId = record.id;
         const response = { data: { id: record.id } };
-        orm.sqlDb.persist('create', modelName, { rawData }, response).catch((err) => {
+        orm.sqlDb.persist('create', modelName, { rawData }, response)
+            .catch((err) => {
             orm.emitPersistError({
                 operation: 'create',
                 modelName,
                 recordId: record.id,
                 error: err instanceof Error ? err : new Error(String(err)),
             });
+        })
+            .finally(() => {
+            // Evict non-memory records after persist to prevent unbounded heap growth (stonyx#81)
+            if (store._memoryResolver && !store._memoryResolver(modelName)) {
+                store.evictRecord(modelName, record.id, registryId);
+            }
         });
     }
     return record;

package/dist/mysql/connection.d.ts

@@ -8,6 +8,7 @@ interface MysqlConfig {
     connectionLimit?: number;
     migrationsTable?: string;
     migrationsDir?: string;
+    autoMigrate?: boolean;
 }
 export declare function getPool(mysqlConfig: MysqlConfig): Promise<Pool>;
 export declare function closePool(): Promise<void>;

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

@@ -61,6 +61,14 @@ export default class MysqlDB {
     deps: MysqlDBDeps;
     pool: Pool | null;
     mysqlConfig: MysqlConfig;
+    /**
+     * Promise-chain mutex for write serialization (#156).
+     * All persist() calls chain through this single queue so concurrent
+     * fire-and-forget writes never produce parallel InnoDB transactions
+     * on FK-linked rows (which cause deadlocks).
+     * Reads are NOT affected — only persist() serializes.
+     */
+    private _writeQueue;
     constructor(deps?: Partial<MysqlDBDeps>);
     private requirePool;
     init(): Promise<void>;

package/dist/mysql/mysql-db.js

@@ -26,6 +26,14 @@ export default class MysqlDB {
     deps;
     pool;
     mysqlConfig;
+    /**
+     * Promise-chain mutex for write serialization (#156).
+     * All persist() calls chain through this single queue so concurrent
+     * fire-and-forget writes never produce parallel InnoDB transactions
+     * on FK-linked rows (which cause deadlocks).
+     * Reads are NOT affected — only persist() serializes.
+     */
+    _writeQueue = Promise.resolve();
     constructor(deps = {}) {
         if (MysqlDB.instance)
             return MysqlDB.instance;
@@ -57,7 +65,17 @@ export default class MysqlDB {
         const pending = files.filter(f => !applied.includes(f));
         if (pending.length > 0) {
             this.deps.log.db?.(`${pending.length} pending migration(s) found.`);
-            const shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+            let shouldApply;
+            if (this.mysqlConfig.autoMigrate === true) {
+                shouldApply = true;
+            }
+            else if (this.mysqlConfig.autoMigrate === false) {
+                shouldApply = false;
+                this.deps.log.warn?.(`autoMigrate is false — skipping ${pending.length} pending migration(s).`);
+            }
+            else {
+                shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+            }
             if (shouldApply) {
                 for (const filename of pending) {
                     const content = await this.deps.readFile(this.deps.path.join(migrationsPath, filename));
@@ -76,7 +94,17 @@ export default class MysqlDB {
             const schemas = this.deps.introspectModels();
             const modelCount = Object.keys(schemas).length;
             if (modelCount > 0) {
-                const shouldGenerate = await this.deps.confirm(`No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`);
+                let shouldGenerate;
+                if (this.mysqlConfig.autoMigrate === true) {
+                    shouldGenerate = true;
+                }
+                else if (this.mysqlConfig.autoMigrate === false) {
+                    shouldGenerate = false;
+                    this.deps.log.warn?.(`autoMigrate is false — skipping initial migration generation for ${modelCount} model(s).`);
+                }
+                else {
+                    shouldGenerate = await this.deps.confirm(`No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`);
+                }
                 if (shouldGenerate) {
                     const { generateMigration } = await import('./migration-generator.js');
                     const result = await generateMigration('initial_setup');
@@ -302,14 +330,20 @@ export default class MysqlDB {
         const Orm = (await import('@stonyx/orm')).default;
         if (Orm.instance?.isView?.(modelName))
             return;
-        switch (operation) {
-            case 'create':
-                return this._persistCreate(modelName, context, response);
-            case 'update':
-                return this._persistUpdate(modelName, context, response);
-            case 'delete':
-                return this._persistDelete(modelName, context);
-        }
+        const work = async () => {
+            switch (operation) {
+                case 'create':
+                    return this._persistCreate(modelName, context, response);
+                case 'update':
+                    return this._persistUpdate(modelName, context, response);
+                case 'delete':
+                    return this._persistDelete(modelName, context);
+            }
+        };
+        // Chain through the write queue — .then(work, work) ensures the queue
+        // advances even when a previous persist rejects (#156).
+        this._writeQueue = this._writeQueue.then(work, work);
+        return this._writeQueue;
     }
     async _persistCreate(modelName, context, response) {
         const schemas = this.deps.introspectModels();

package/dist/orm-request.d.ts

@@ -1,3 +1,63 @@
+/**
+ * REST request handling and access enforcement for @stonyx/orm.
+ *
+ * ---------------------------------------------------------------------------
+ * DO NOT RECONSTRUCT THE REQUEST PATH INSIDE `access()`.
+ * ---------------------------------------------------------------------------
+ * `auth()` below hands your `access(request)` a raw transport artifact and asks
+ * you to work out which collection it addresses. Every attempt to do that by
+ * parsing the request target has failed OPEN. Five distinct variants of the
+ * same three-line example have now been found, each after the previous was
+ * fixed, by five different people:
+ *
+ *   1. `request.url` is mount-relative under `RestServer.mountRoute`, so a
+ *      prefix match against it is ALWAYS false.
+ *   2. `request.originalUrl` carries the query string, so an anchored equality
+ *      check misses `/owners?filter[age]=30`.
+ *   3. The router is a bare `express()` (`caseSensitive: false`) while a
+ *      hand-written matcher is case-SENSITIVE, so `GET /OwNeRs/angela` walks
+ *      past it. Router-side: abofs/stonyx-rest-server#47.
+ *   4. Under a configured `ORM_REST_ROUTE` a hard-coded `/owners` matches
+ *      nothing -- environment-specifically, which is worse.
+ *   5. HTTP/1.1 permits an ABSOLUTE-FORM request-target. Express routes on
+ *      `parseurl(req).pathname`, but `originalUrl` is the raw target, so
+ *      `GET http://anything.example/owners/angela` reaches the handler with
+ *      `originalUrl === 'http://anything.example/owners/angela'`. A `/owners`
+ *      prefix match is false, `access()` falls through to whatever it returns
+ *      last, and the record comes back in full. It walks past a hard
+ *      `return false` deny the same way.
+ *
+ * The fix is not a sixth rule. It is to stop parsing:
+ *
+ *   `request.baseUrl` is the mount Express ACTUALLY MATCHED when it dispatched
+ *   the request. It carries no query string, it is not mount-relative, it is
+ *   unaffected by absolute-form, and it already includes the configured
+ *   `ORM_REST_ROUTE` prefix -- so there is nothing to derive and nothing to
+ *   join. Compare it lower-cased (the router matched case-insensitively) and
+ *   fail CLOSED when it is absent. Use `request.path` -- mount-relative and
+ *   query-free -- if you need to distinguish sub-paths.
+ *
+ * `?? ''` is not a defence. It converts an absent request target into an empty
+ * string, which matches no collection, which falls through to the permission
+ * array -- a total grant. An input you cannot identify must DENY.
+ *
+ * THAT IS STILL A STOPGAP. `baseUrl` closes all five variants, but it is a
+ * transport artifact being asked to stand in for a structural fact.
+ * THE REAL FIX IS abofs/stonyx-orm#202: `access()` should receive the model,
+ * the operation and the record. Prefer the array shape (`['read']`) or `false`
+ * until #202 lands; the function shape is what requires any matching at all.
+ *
+ * The enforcement gates in this file (GATE 0/1/2, the create rollback, the
+ * per-handler `isDenied` re-checks) are correct independently of that -- they
+ * enforce whatever predicate you return. The stopgap is the part where YOU have
+ * to work out which predicate to return.
+ *
+ * AND A PREDICATE IS NOT A GUARANTEE THAT A HIDDEN RECORD CANNOT BE MODIFIED.
+ * It is evaluated against the record the route is ADDRESSED TO, on that model
+ * only. A write to a DIFFERENT collection can still re-parent a hidden record
+ * and de-hide it -- abofs/stonyx-orm#207, which is blocked on #202 and #196.
+ * See `### Known limitations` in README.
+ */
 import { Request } from '@stonyx/rest-server';
 interface OrmRequest$ extends Request {
     protocol?: string;