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

package/src/dynamodb/operation-builder.ts

@@ -0,0 +1,188 @@
+/**
+ * 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.
+ */
+
+export interface PutItemParams {
+  TableName: string;
+  Item: Record<string, unknown>;
+  ConditionExpression?: string;
+}
+
+export interface GetItemParams {
+  TableName: string;
+  Key: Record<string, unknown>;
+}
+
+export interface UpdateItemParams {
+  TableName: string;
+  Key: Record<string, unknown>;
+  UpdateExpression: string;
+  ExpressionAttributeNames: Record<string, string>;
+  ExpressionAttributeValues: Record<string, unknown>;
+  ReturnValues: string;
+}
+
+export interface DeleteItemParams {
+  TableName: string;
+  Key: Record<string, unknown>;
+}
+
+export interface ScanParams {
+  TableName: string;
+  FilterExpression?: string;
+  ExpressionAttributeNames?: Record<string, string>;
+  ExpressionAttributeValues?: Record<string, unknown>;
+  ExclusiveStartKey?: Record<string, unknown>;
+}
+
+export interface QueryParams {
+  TableName: string;
+  IndexName: string;
+  KeyConditionExpression: string;
+  ExpressionAttributeNames: Record<string, string>;
+  ExpressionAttributeValues: Record<string, unknown>;
+  ExclusiveStartKey?: Record<string, unknown>;
+}
+
+/**
+ * PutItem — optionally with a condition expression.
+ *
+ * Pass conditionExpression = 'attribute_not_exists(id)' to enforce uniqueness.
+ */
+export function buildPutItem(
+  tableName: string,
+  item: Record<string, unknown>,
+  conditionExpression?: string,
+): PutItemParams {
+  const params: PutItemParams = { TableName: tableName, Item: item };
+  if (conditionExpression) params.ConditionExpression = conditionExpression;
+  return params;
+}
+
+/**
+ * GetItem by primary key.
+ */
+export function buildGetItem(
+  tableName: string,
+  key: Record<string, unknown>,
+): GetItemParams {
+  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: string,
+  key: Record<string, unknown>,
+  updates: Record<string, unknown>,
+): UpdateItemParams {
+  const names: Record<string, string> = {};
+  const values: Record<string, unknown> = {};
+  const setClauses: string[] = [];
+
+  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: string,
+  key: Record<string, unknown>,
+): DeleteItemParams {
+  return { TableName: tableName, Key: key };
+}
+
+/**
+ * ScanCommand params.
+ * If conditions are supplied they are rendered as a FilterExpression using AND.
+ */
+export function buildScan(
+  tableName: string,
+  conditions?: Record<string, unknown>,
+  exclusiveStartKey?: Record<string, unknown>,
+): ScanParams {
+  const params: ScanParams = { TableName: tableName };
+
+  if (exclusiveStartKey) params.ExclusiveStartKey = exclusiveStartKey;
+
+  if (conditions && Object.keys(conditions).length > 0) {
+    const names: Record<string, string> = {};
+    const values: Record<string, unknown> = {};
+    const clauses: string[] = [];
+
+    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: string,
+  indexName: string,
+  keyConditions: Record<string, unknown>,
+  exclusiveStartKey?: Record<string, unknown>,
+): QueryParams {
+  const names: Record<string, string> = {};
+  const values: Record<string, unknown> = {};
+  const clauses: string[] = [];
+
+  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: QueryParams = {
+    TableName: tableName,
+    IndexName: indexName,
+    KeyConditionExpression: clauses.join(' AND '),
+    ExpressionAttributeNames: names,
+    ExpressionAttributeValues: values,
+  };
+
+  if (exclusiveStartKey) params.ExclusiveStartKey = exclusiveStartKey;
+
+  return params;
+}

package/src/dynamodb/type-map.ts

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+const typeMap: Record<string, DynamoScalarType> = {
+  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: string): DynamoScalarType {
+  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: string): 'S' | 'N' {
+  const t = getDynamoType(attrType);
+  return t === 'N' ? 'N' : 'S';
+}
+
+export default typeMap;

package/src/index.ts

@@ -26,6 +26,7 @@ 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 }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers
@@ -37,7 +38,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/src/main.ts

@@ -25,8 +25,6 @@ import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
 import { setup } from '@stonyx/events';
-import type { OrmRecord } from './types/orm-types.js';
-import { isOrmRecord } from './utils.js';
 
 interface OrmOptions {
   dbType?: string;
@@ -51,6 +49,13 @@ const defaultOptions: OrmOptions = {
   dbType: 'json'
 }
 
+export interface PersistErrorDetail {
+  operation: 'create' | 'update' | 'delete';
+  modelName: string;
+  recordId: unknown;
+  error: Error;
+}
+
 export default class Orm {
   static initialized: boolean = false;
   static relationships: Map<string, Map<string, unknown>> = new Map();
@@ -67,6 +72,8 @@ export default class Orm {
   sqlDb?: SqlDb;
   db?: OrmDB | SqlDb;
 
+  private _persistErrorHandler: ((detail: PersistErrorDetail) => void) | null = null;
+
   constructor(options: OrmOptions = {}) {
     if (Orm.instance) return Orm.instance;
 
@@ -83,6 +90,11 @@ export default class Orm {
   }
 
   async init(): Promise<void> {
+    // 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: Promise<unknown>[] = ['Model', 'Serializer', 'Transform'].map(type => {
@@ -152,6 +164,11 @@ export default class Orm {
       this.sqlDb = new MysqlDB() as SqlDb;
       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() as SqlDb;
+      this.db = this.sqlDb;
+      promises.push(this.sqlDb.init());
     } else if (this.options.dbType !== 'none') {
       const db = new DB();
       this.db = db;
@@ -217,60 +234,29 @@ export default class Orm {
   }
 
   /**
-   * Programmatic create — writes to memory AND persists to SQL database.
-   * Use instead of createRecord() when records must be persisted to PostgreSQL/TimescaleDB.
-   */
-  static async create(modelName: string, data: Record<string, unknown> = {}): Promise<OrmRecord> {
-    if (!Orm.initialized) throw new Error('ORM is not ready');
-
-    const { createRecord } = await import('./manage-record.js');
-    const record = createRecord(modelName, data, { serialize: false }) as unknown as OrmRecord;
-
-    if (Orm.instance.sqlDb) {
-      const response: { data: { id: unknown } } = { data: { id: record.id } };
-      await Orm.instance.sqlDb.persist('create', modelName, {}, response);
-    }
-
-    return record;
-  }
-
-  /**
-   * 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 async update(modelName: string, id: string | number, data: Record<string, unknown>): Promise<OrmRecord> {
-    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 }, {});
-    }
-
-    return record;
+  onPersistError(handler: ((detail: PersistErrorDetail) => void) | null): void {
+    this._persistErrorHandler = handler;
   }
 
   /**
-   * 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 async remove(modelName: string, id: string | number): Promise<void> {
-    if (!Orm.initialized) throw new Error('ORM is not ready');
-
-    if (Orm.instance.sqlDb) {
-      await Orm.instance.sqlDb.persist('delete', modelName, { recordId: id }, {});
+  emitPersistError(detail: PersistErrorDetail): void {
+    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)}`);
+      }
+    } else {
+      fallbackLog();
     }
-
-    Orm.store.remove(modelName, id);
   }
 
   // Queue warnings to avoid the same error from being logged in the same iteration

package/src/manage-record.ts

@@ -9,6 +9,7 @@ interface CreateRecordOptions {
   serialize?: boolean;
   transform?: boolean;
   update?: boolean;
+  _skipAutoPersist?: boolean;
   [key: string]: unknown;
 }
 
@@ -25,6 +26,8 @@ const defaultOptions: CreateRecordOptions = {
   transform: true
 };
 
+let pendingIdCounter = 0;
+
 export function createRecord(modelName: string, rawData: { [key: string]: unknown } = {}, userOptions: CreateRecordOptions = {}): OrmRecord {
   const orm = Orm.instance;
   const { initialized } = Orm;
@@ -111,6 +114,20 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
     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) {
+    const response = { data: { id: record.id } };
+    orm!.sqlDb!.persist('create', modelName, { rawData }, response).catch((err: unknown) => {
+      orm!.emitPersistError({
+        operation: 'create',
+        modelName,
+        recordId: record.id,
+        error: err instanceof Error ? err : new Error(String(err)),
+      });
+    });
+  }
+
   return record;
 }
 
@@ -125,7 +142,24 @@ export function updateRecord(record: OrmRecord, rawData: unknown, userOptions: C
 
   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: unknown) => {
+      orm!.emitPersistError({
+        operation: 'update',
+        modelName,
+        recordId: record.id,
+        error: err instanceof Error ? err : new Error(String(err)),
+      });
+    });
+  }
 }
 
 /**
@@ -137,9 +171,11 @@ export function updateRecord(record: OrmRecord, rawData: unknown, userOptions: C
 function assignRecordId(modelName: string, rawData: { [key: string]: unknown }): void {
   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/src/mysql/mysql-db.ts

@@ -21,6 +21,7 @@ interface PersistContext {
   record?: OrmRecord;
   recordId?: unknown;
   oldState?: Record<string, unknown>;
+  rawData?: Record<string, unknown>;
 }
 
 interface PersistResponse {
@@ -420,8 +421,10 @@ export default class MysqlDB {
 
     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/src/orm-request.ts

@@ -330,7 +330,7 @@ export default class OrmRequest extends Request {
       }
 
       const recordAttributes = id !== undefined ? { id, ...sanitizedAttributes } : sanitizedAttributes;
-      const created = createRecord(model, recordAttributes as { [key: string]: unknown }, { serialize: false });
+      const created = createRecord(model, recordAttributes as { [key: string]: unknown }, { serialize: false, _skipAutoPersist: true });
       const record = isOrmRecord(created) ? created : null;
       if (!record) return 500;
 
@@ -368,7 +368,7 @@ export default class OrmRequest extends Request {
           }
         }
         if (Object.keys(relUpdates).length > 0) {
-          updateRecord(record as never, relUpdates);
+          updateRecord(record as never, relUpdates, { _skipAutoPersist: true });
         }
       }
 
@@ -443,9 +443,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);
       }
 

package/src/postgres/postgres-db.ts

@@ -19,6 +19,7 @@ interface PersistContext {
   record?: OrmRecord;
   recordId?: unknown;
   oldState?: Record<string, unknown>;
+  rawData?: Record<string, unknown>;
 }
 
 interface PersistResponse {
@@ -477,7 +478,7 @@ export default class PostgresDB {
     }
   }
 
-  private async _persistCreate(modelName: string, _context: PersistContext, response: PersistResponse): Promise<void> {
+  private async _persistCreate(modelName: string, context: PersistContext, response: PersistResponse): Promise<void> {
     const schemas = this.deps.introspectModels();
     const schema = schemas[modelName];
 
@@ -491,10 +492,12 @@ export default class PostgresDB {
 
     if (!record) return;
 
-    const insertData = this._recordToRow(record, schema);
+    const insertData = this._recordToRow(record, schema, context.rawData);
 
-    // 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;
@@ -549,7 +552,10 @@ export default class PostgresDB {
     // Check FK changes too
     for (const fkCol of Object.keys(schema.foreignKeys)) {
       const relName = fkCol.replace(/_id$/, '');
-      const currentFkValue = (record.__relationships[relName] as { id: unknown } | undefined)?.id ?? null;
+      const relValue = record.__relationships[relName];
+      const currentFkValue = (relValue && typeof relValue === 'object' && relValue !== null)
+        ? (relValue as { id: unknown }).id ?? null
+        : relValue ?? record.__data[relName] ?? null;
       const oldFkValue = oldState[relName] ?? null;
 
       if (currentFkValue !== oldFkValue) {
@@ -579,7 +585,7 @@ export default class PostgresDB {
     await this.requirePool().query(sql, values);
   }
 
-  private _recordToRow(record: OrmRecord, schema: ModelSchema): Record<string, unknown> {
+  private _recordToRow(record: OrmRecord, schema: ModelSchema, rawData?: Record<string, unknown>): Record<string, unknown> {
     const row: Record<string, unknown> = {};
     const data = record.__data;
 
@@ -603,11 +609,16 @@ export default class PostgresDB {
       const relName = fkCol.replace(/_id$/, '');
       const related = record.__relationships[relName];
 
-      if (related) {
+      if (related && typeof related === 'object' && related !== null) {
         row[fkCol] = (related as { id: unknown }).id;
+      } else if (related != null) {
+        // Raw FK value (e.g., string ID stored directly in __relationships)
+        row[fkCol] = related;
       } else if (data[relName] !== undefined) {
-        // Raw FK value (e.g., from create payload)
         row[fkCol] = data[relName];
+      } else if (rawData?.[relName] !== undefined) {
+        // Fallback to original create payload for unresolved belongsTo FKs
+        row[fkCol] = rawData[relName];
       }
     }
 

package/src/store.ts

@@ -176,6 +176,18 @@ export default class Store {
       throw new Error(`Cannot remove records from read-only view '${key}'`);
     }
 
+    // Auto-persist delete to SQL
+    if (id && Orm.instance?.sqlDb) {
+      Orm.instance.sqlDb.persist('delete', key, { recordId: id }, {}).catch((err: unknown) => {
+        Orm.instance.emitPersistError({
+          operation: 'delete',
+          modelName: key,
+          recordId: id,
+          error: err instanceof Error ? err : new Error(String(err)),
+        });
+      });
+    }
+
     if (id) return this.unloadRecord(key, id);
 
     this.unloadAllRecords(key);

package/src/types/orm-types.ts

@@ -48,6 +48,12 @@ export interface OrmRestServerConfig {
   metaRoute: boolean;
 }
 
+export interface OrmDynamoDBConfig {
+  region?: string;
+  endpoint?: string;
+  [key: string]: unknown;
+}
+
 export interface OrmSection {
   db: OrmDbConfig;
   paths: OrmPaths;
@@ -55,6 +61,9 @@ export interface OrmSection {
   mysql?: OrmMysqlConfig;
   postgres?: OrmPostgresConfig;
   timescale?: OrmPostgresConfig;
+  dynamodb?: OrmDynamoDBConfig;
+  logColor?: string;
+  logMethod?: string;
   [key: string]: unknown;
 }
 

package/src/types/stonyx.d.ts

@@ -5,7 +5,13 @@ declare module 'stonyx/config' {
 }
 
 declare module 'stonyx/log' {
-  const log: Record<string, ((...args: unknown[]) => void) | undefined>;
+  interface Log {
+    db(message: string): void;
+    error(message: string, ...args: unknown[]): void;
+    defineType(type: string, setting: string, options?: Record<string, unknown> | null): void;
+    [key: string]: ((...args: unknown[]) => void) | undefined;
+  }
+  const log: Log;
   export default log;
 }