@stonyx/orm 0.3.2-alpha.2 → 0.3.2-alpha.20

package/dist/dynamodb/operation-builder.js

@@ -0,0 +1,109 @@
+/**
+ * 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 names = {};
+        const values = {};
+        const clauses = [];
+        for (const [attr, val] of Object.entries(conditions)) {
+            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 names = {};
+    const values = {};
+    const clauses = [];
+    for (const [attr, val] of Object.entries(keyConditions)) {
+        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/index.d.ts

@@ -8,6 +8,7 @@ import { createRecord, updateRecord } from './manage-record.js';
 import { count, avg, sum, min, max } from './aggregates.js';
 export { default } from './main.js';
 export { store, relationships } from './main.js';
+export type { PersistErrorDetail } from './main.js';
 export { Model, View, Serializer };
 export { attr, belongsTo, hasMany, createRecord, updateRecord };
 export { count, avg, sum, min, max };

package/dist/index.js

@@ -33,7 +33,7 @@ export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; //
 // store.findAll(model)   -- async, all records
 // store.query(model, conditions) -- async, always hits SQL
 //
-// Programmatic CRUD (memory + SQL persistence):
-// Orm.create(model, data)      -- async, createRecord + sqlDb.persist
-// Orm.update(model, id, data)  -- async, updateRecord + sqlDb.persist
-// Orm.remove(model, id)        -- async, sqlDb.persist + store.remove
+// Data-layer auto-persist (memory + SQL persistence):
+// createRecord(model, data)  -- sync, auto-persists to SQL (fire-and-forget)
+// updateRecord(record, data) -- sync, auto-persists to SQL (fire-and-forget)
+// store.remove(model, id)    -- sync, auto-persists delete to SQL (fire-and-forget)

package/dist/main.d.ts

@@ -1,5 +1,4 @@
 import Store from './store.js';
-import type { OrmRecord } from './types/orm-types.js';
 interface OrmOptions {
     dbType?: string;
 }
@@ -16,6 +15,12 @@ export interface OrmDB {
     save(): Promise<void>;
     init(): Promise<void>;
 }
+export interface PersistErrorDetail {
+    operation: 'create' | 'update' | 'delete';
+    modelName: string;
+    recordId: unknown;
+    error: Error;
+}
 export default class Orm {
     static initialized: boolean;
     static relationships: Map<string, Map<string, unknown>>;
@@ -30,6 +35,7 @@ export default class Orm {
     options: OrmOptions;
     sqlDb?: SqlDb;
     db?: OrmDB | SqlDb;
+    private _persistErrorHandler;
     constructor(options?: OrmOptions);
     init(): Promise<void>;
     startup(): Promise<void>;
@@ -41,20 +47,14 @@ export default class Orm {
     };
     isView(modelName: string): boolean;
     /**
-     * Programmatic create — writes to memory AND persists to SQL database.
-     * Use instead of createRecord() when records must be persisted to PostgreSQL/TimescaleDB.
-     */
-    static create(modelName: string, data?: Record<string, unknown>): Promise<OrmRecord>;
-    /**
-     * Programmatic update — updates in memory AND persists to SQL database.
-     * Captures old state for diff-based UPDATE queries.
+     * Register a callback to be invoked when a fire-and-forget SQL persist fails.
+     * Without a handler, persist errors are logged via log.error (backwards-compatible).
      */
-    static update(modelName: string, id: string | number, data: Record<string, unknown>): Promise<OrmRecord>;
+    onPersistError(handler: ((detail: PersistErrorDetail) => void) | null): void;
     /**
-     * Programmatic delete — removes from SQL database AND memory store.
-     * SQL delete runs first to ensure consistency on failure.
+     * Emit a persist error to the registered handler, or fall back to log.error.
      */
-    static remove(modelName: string, id: string | number): Promise<void>;
+    emitPersistError(detail: PersistErrorDetail): void;
     warn(message: string): void;
 }
 export declare const store: Store;

package/dist/main.js

@@ -24,7 +24,6 @@ import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
 import { setup } from '@stonyx/events';
-import { isOrmRecord } from './utils.js';
 const defaultOptions = {
     dbType: 'json'
 };
@@ -42,6 +41,7 @@ export default class Orm {
     options;
     sqlDb;
     db;
+    _persistErrorHandler = null;
     constructor(options = {}) {
         if (Orm.instance)
             return Orm.instance;
@@ -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;
@@ -170,53 +180,29 @@ export default class Orm {
         return !!this.views[`${modelClassPrefix}View`];
     }
     /**
-     * Programmatic create — writes to memory AND persists to SQL database.
-     * Use instead of createRecord() when records must be persisted to PostgreSQL/TimescaleDB.
+     * Register a callback to be invoked when a fire-and-forget SQL persist fails.
+     * Without a handler, persist errors are logged via log.error (backwards-compatible).
      */
-    static async create(modelName, data = {}) {
-        if (!Orm.initialized)
-            throw new Error('ORM is not ready');
-        const { createRecord } = await import('./manage-record.js');
-        const record = createRecord(modelName, data, { serialize: false });
-        if (Orm.instance.sqlDb) {
-            const response = { data: { id: record.id } };
-            await Orm.instance.sqlDb.persist('create', modelName, {}, response);
-        }
-        return record;
+    onPersistError(handler) {
+        this._persistErrorHandler = handler;
     }
     /**
-     * Programmatic update — updates in memory AND persists to SQL database.
-     * Captures old state for diff-based UPDATE queries.
+     * Emit a persist error to the registered handler, or fall back to log.error.
      */
-    static async update(modelName, id, data) {
-        if (!Orm.initialized)
-            throw new Error('ORM is not ready');
-        const record = Orm.store.get(modelName, id);
-        if (!record || !isOrmRecord(record))
-            throw new Error(`Record ${modelName}:${id} not found`);
-        const oldState = JSON.parse(JSON.stringify(record.__data));
-        // Apply attribute updates directly, matching the REST handler pattern
-        for (const [key, value] of Object.entries(data)) {
-            if (key === 'id')
-                continue;
-            record[key] = value;
-        }
-        if (Orm.instance.sqlDb) {
-            await Orm.instance.sqlDb.persist('update', modelName, { record, oldState }, {});
+    emitPersistError(detail) {
+        const fallbackLog = () => log.error?.(`[ORM] Failed to persist ${detail.operation} for ${detail.modelName}:${String(detail.recordId)}: ${detail.error.message}`);
+        if (this._persistErrorHandler) {
+            try {
+                this._persistErrorHandler(detail);
+            }
+            catch (handlerError) {
+                fallbackLog();
+                log.error?.(`[ORM] onPersistError handler threw: ${handlerError instanceof Error ? handlerError.message : String(handlerError)}`);
+            }
         }
-        return record;
-    }
-    /**
-     * Programmatic delete — removes from SQL database AND memory store.
-     * SQL delete runs first to ensure consistency on failure.
-     */
-    static async remove(modelName, id) {
-        if (!Orm.initialized)
-            throw new Error('ORM is not ready');
-        if (Orm.instance.sqlDb) {
-            await Orm.instance.sqlDb.persist('delete', modelName, { recordId: id }, {});
+        else {
+            fallbackLog();
         }
-        Orm.store.remove(modelName, id);
     }
     // Queue warnings to avoid the same error from being logged in the same iteration
     warn(message) {

package/dist/manage-record.d.ts

@@ -4,6 +4,7 @@ interface CreateRecordOptions {
     serialize?: boolean;
     transform?: boolean;
     update?: boolean;
+    _skipAutoPersist?: boolean;
     [key: string]: unknown;
 }
 export declare function createRecord(modelName: string, rawData?: {

package/dist/manage-record.js

@@ -7,6 +7,7 @@ const defaultOptions = {
     serialize: true,
     transform: true
 };
+let pendingIdCounter = 0;
 export function createRecord(modelName, rawData = {}, userOptions = {}) {
     const orm = Orm.instance;
     const { initialized } = Orm;
@@ -51,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;
@@ -71,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);
             }
@@ -79,6 +101,29 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
         // Clear the pending queue
         pendingBelongsTo.length = 0;
     }
+    // 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.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;
 }
 export function updateRecord(record, rawData, userOptions = {}) {
@@ -90,7 +135,22 @@ export function updateRecord(record, rawData, userOptions = {}) {
         throw new Error(`Cannot update records for read-only view '${modelName}'`);
     }
     const options = { ...defaultOptions, ...userOptions, update: true };
+    // Capture old state before update for SQL diff
+    const oldState = record.__data ? JSON.parse(JSON.stringify(record.__data)) : {};
     record.serialize(rawData, options);
+    // Auto-persist to SQL — skip for DB loads (isDbRecord) and relationship resolution (_relationshipKey)
+    const orm = Orm.instance;
+    const shouldPersist = orm?.sqlDb && !options.isDbRecord && !userOptions._relationshipKey && !options._skipAutoPersist;
+    if (shouldPersist && modelName) {
+        orm.sqlDb.persist('update', modelName, { record, oldState }, {}).catch((err) => {
+            orm.emitPersistError({
+                operation: 'update',
+                modelName,
+                recordId: record.id,
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+        });
+    }
 }
 /**
  * gets the next available id based on last record entry.
@@ -101,9 +161,11 @@ export function updateRecord(record, rawData, userOptions = {}) {
 function assignRecordId(modelName, rawData) {
     if (rawData.id)
         return;
-    // In SQL mode with numeric IDs, defer to database auto-increment
+    // In SQL mode with numeric IDs, defer to database auto-increment.
+    // Use unique negative integers — they survive the number transform (parseInt preserves negatives)
+    // and avoid NaN store-key collisions that string pending IDs caused.
     if (Orm.instance?.sqlDb && !isStringIdModel(modelName)) {
-        rawData.id = `__pending_${Date.now()}_${Math.random()}`;
+        rawData.id = -(++pendingIdCounter);
         rawData.__pendingSqlId = true;
         return;
     }

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

@@ -16,6 +16,7 @@ interface PersistContext {
     record?: OrmRecord;
     recordId?: unknown;
     oldState?: Record<string, unknown>;
+    rawData?: Record<string, unknown>;
 }
 interface PersistResponse {
     data?: {

package/dist/mysql/mysql-db.js

@@ -321,8 +321,10 @@ export default class MysqlDB {
         if (!record)
             return;
         const insertData = this._recordToRow(record, schema);
-        // For auto-increment models, remove the pending ID
-        const isPendingId = record.__data.__pendingSqlId;
+        // For auto-increment models, remove the pending ID.
+        // Check context.rawData (not record.__data) because __pendingSqlId is not a model
+        // attribute and gets lost during serialization.
+        const isPendingId = context.rawData?.__pendingSqlId === true;
         if (isPendingId) {
             delete insertData.id;
         }

package/dist/orm-request.js

@@ -248,7 +248,7 @@ export default class OrmRequest extends Request {
                 }
             }
             const recordAttributes = id !== undefined ? { id, ...sanitizedAttributes } : sanitizedAttributes;
-            const created = createRecord(model, recordAttributes, { serialize: false });
+            const created = createRecord(model, recordAttributes, { serialize: false, _skipAutoPersist: true });
             const record = isOrmRecord(created) ? created : null;
             if (!record)
                 return 500;
@@ -283,7 +283,7 @@ export default class OrmRequest extends Request {
                     }
                 }
                 if (Object.keys(relUpdates).length > 0) {
-                    updateRecord(record, relUpdates);
+                    updateRecord(record, relUpdates, { _skipAutoPersist: true });
                 }
             }
             return { data: record.toJSON?.() };
@@ -348,9 +348,9 @@ export default class OrmRequest extends Request {
             }
             // Execute main handler
             const response = await handler(request, state);
-            // Persist to SQL database for write operations
+            // Persist to SQL database for create/update (delete is handled by store.remove auto-persist)
             const sqlDb = Orm.instance.sqlDb;
-            if (sqlDb && WRITE_OPERATIONS.has(operation)) {
+            if (sqlDb && (operation === 'create' || operation === 'update')) {
                 await sqlDb.persist(operation, this.model, context, response);
             }
             // Add response and relevant records to context

package/dist/postgres/connection.d.ts

@@ -6,6 +6,7 @@ interface PgConfig {
     password: string;
     database: string;
     connectionLimit: number;
+    [key: string]: unknown;
 }
 /**
  * Create or return the singleton pg Pool.

package/dist/postgres/connection.js

@@ -7,15 +7,17 @@ export async function getPool(pgConfig, extensions = ['vector']) {
     if (pool)
         return pool;
     const { default: pg } = await import('pg');
+    const { host, port, user, password, database, connectionLimit, migrationsDir, migrationsTable, ...poolOpts } = pgConfig;
     pool = new pg.Pool({
-        host: pgConfig.host,
-        port: pgConfig.port,
-        user: pgConfig.user,
-        password: pgConfig.password,
-        database: pgConfig.database,
-        max: pgConfig.connectionLimit,
+        host,
+        port,
+        user,
+        password,
+        database,
+        max: connectionLimit,
         idleTimeoutMillis: 30000,
         connectionTimeoutMillis: 10000,
+        ...poolOpts,
     });
     // Enable requested PostgreSQL extensions
     for (const ext of extensions) {

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

@@ -17,6 +17,7 @@ interface PersistContext {
     record?: OrmRecord;
     recordId?: unknown;
     oldState?: Record<string, unknown>;
+    rawData?: Record<string, unknown>;
 }
 interface PersistResponse {
     data?: {