@stonyx/orm 0.3.2-beta.33 → 0.3.2-beta.330

package/src/dynamodb/operation-builder.ts

@@ -0,0 +1,202 @@
+/**
+ * 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 validEntries = Object.entries(conditions).filter(
+      ([, val]) => val !== undefined && val !== null,
+    );
+
+    if (validEntries.length > 0) {
+      const names: Record<string, string> = {};
+      const values: Record<string, unknown> = {};
+      const clauses: string[] = [];
+
+      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: string,
+  indexName: string,
+  keyConditions: Record<string, unknown>,
+  exclusiveStartKey?: Record<string, unknown>,
+): QueryParams {
+  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: Record<string, string> = {};
+  const values: Record<string, unknown> = {};
+  const clauses: string[] = [];
+
+  for (const [attr, val] of validEntries) {
+    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

@@ -21,15 +21,17 @@ import Serializer from './serializer.js';
 import attr from './attr.js';
 import belongsTo from './belongs-to.js';
 import hasMany from './has-many.js';
-import { createRecord, updateRecord } from './manage-record.js';
+import { createRecord, updateRecord, createRecordAndPersist, updateRecordAndPersist } 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 }; // base classes
-export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
+export { attr, belongsTo, hasMany, createRecord, updateRecord, createRecordAndPersist, updateRecordAndPersist };
 export { count, avg, sum, min, max }; // aggregate helpers
+export { default as normalizeRecordId } from './normalize-record-id.js'; // canonical URL-id -> record-id resolution (#270)
+export type { OrmRequest$ as OrmAccessRequest } from './orm-request.js'; // the request access() is handed, incl. recordId (#270)
 export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
 
 // Store API:

package/src/main.ts

@@ -20,7 +20,6 @@ import log from 'stonyx/log';
 import { forEachFileImport } from '@stonyx/utils/file';
 import { kebabCaseToPascalCase, pluralize } from '@stonyx/utils/string';
 import { registerPluralName } from './plural-registry.js';
-import setupRestServer from './setup-rest-server.js';
 import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
@@ -35,6 +34,7 @@ export interface SqlDb {
   startup(): Promise<void>;
   shutdown(): Promise<void>;
   persist(operation: string, model: string, context: unknown, response: unknown): Promise<void>;
+  persistResolvesAfterWrite?: boolean;
   findRecord(modelName: string, id: unknown): Promise<unknown>;
   findAll(modelName: string, conditions?: Record<string, unknown>): Promise<unknown[]>;
 }
@@ -90,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 => {
@@ -159,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;
@@ -167,6 +177,25 @@ export default class Orm {
     }
 
     if (restServer.enabled === 'true') {
+      // MUST stay dynamic. setup-rest-server.js names the optional
+      // '@stonyx/rest-server' peer in its own static graph — directly, and
+      // through orm-request.ts / meta-request.ts, which import `Request` at
+      // module scope because they extend it (correctly: an `extends` base
+      // class cannot be awaited). Node links a module's entire static graph
+      // before evaluating any of it, so a static import here puts that
+      // specifier on the entry graph and `import('@stonyx/orm')` throws
+      // ERR_MODULE_NOT_FOUND for an ORM-only consumer that never installed the
+      // optional peer.
+      //
+      // NOT the same reason the SQL/DynamoDB drivers above are lazy: those
+      // modules carry no static peer specifier that survives to `dist/`
+      // (postgres-db.ts:15 and mysql-db.ts:17 are `import type`, erased by
+      // tsc), so the `await import()` there is not what isolates pg / mysql2 /
+      // @aws-sdk — that happens one layer down, in src/*/connection.ts (and
+      // src/dynamodb/dynamodb-db.ts).
+      // setup-rest-server.js is the only dist module whose laziness is
+      // load-bearing for peer resolution. (#280)
+      const { default: setupRestServer } = await import('./setup-rest-server.js');
       promises.push(setupRestServer(restServer.route, paths.access, restServer.metaRoute));
     }
 

package/src/manage-record.ts

@@ -28,7 +28,73 @@ const defaultOptions: CreateRecordOptions = {
 
 let pendingIdCounter = 0;
 
+interface RecordWrite<Result> {
+  result: Result;
+  written: Promise<void>;
+}
+
+type AwaitedOperation = 'create' | 'update';
+
+const writeNotRequested = Promise.resolve();
+
+function ignoreReportedFailure(): void {}
+
+function persistRequested(options: CreateRecordOptions, userOptions: CreateRecordOptions): boolean {
+  return !options.isDbRecord && !userOptions._relationshipKey && !options._skipAutoPersist;
+}
+
+function reportPersistFailure(operation: AwaitedOperation, modelName: string, recordId: unknown, failure: unknown): Error {
+  const error = failure instanceof Error ? failure : new Error(String(failure));
+  Orm.instance.emitPersistError({ operation, modelName, recordId, error });
+  return error;
+}
+
 export function createRecord(modelName: string, rawData: { [key: string]: unknown } = {}, userOptions: CreateRecordOptions = {}): OrmRecord {
+  const { result: record, written } = createRecordWrite(modelName, rawData, userOptions);
+  written.catch(ignoreReportedFailure);
+  return record;
+}
+
+export function updateRecord(record: OrmRecord, rawData: unknown, userOptions: CreateRecordOptions = {}): void {
+  updateRecordWrite(record, rawData, userOptions).written.catch(ignoreReportedFailure);
+}
+
+export async function createRecordAndPersist(modelName: string, rawData: { [key: string]: unknown } = {}, userOptions: CreateRecordOptions = {}): Promise<OrmRecord> {
+  assertWriteCanBeAwaited();
+  const { result: record, written } = createRecordWrite(modelName, rawData, userOptions);
+  await written;
+  await saveJsonDatabase('create', modelName, record.id, { ...defaultOptions, ...userOptions }, userOptions);
+  return record;
+}
+
+export async function updateRecordAndPersist(record: OrmRecord, rawData: unknown, userOptions: CreateRecordOptions = {}): Promise<void> {
+  assertWriteCanBeAwaited();
+  await updateRecordWrite(record, rawData, userOptions).written;
+  await saveJsonDatabase('update', record?.__model?.__name ?? '', record.id, { ...defaultOptions, ...userOptions }, userOptions);
+}
+
+function assertWriteCanBeAwaited(): void {
+  const sqlDb = Orm.instance?.sqlDb as { persistResolvesAfterWrite?: boolean } | undefined;
+  if (sqlDb && sqlDb.persistResolvesAfterWrite !== true) {
+    throw new Error('The configured database adapter cannot confirm a write has landed, so createRecordAndPersist/updateRecordAndPersist are unavailable for it (DynamoDB: abofs/stonyx-orm#299)');
+  }
+}
+
+async function saveJsonDatabase(operation: AwaitedOperation, modelName: string, recordId: unknown, options: CreateRecordOptions, userOptions: CreateRecordOptions): Promise<void> {
+  const orm = Orm.instance;
+  if (orm.sqlDb || !persistRequested(options, userOptions)) return;
+
+  const jsonDatabase = orm.db as { save?: () => Promise<void> } | undefined;
+  if (!jsonDatabase?.save) return;
+
+  try {
+    await jsonDatabase.save();
+  } catch (failure) {
+    throw reportPersistFailure(operation, modelName, recordId, failure);
+  }
+}
+
+function createRecordWrite(modelName: string, rawData: { [key: string]: unknown }, userOptions: CreateRecordOptions): RecordWrite<OrmRecord> {
   const orm = Orm.instance;
   const { initialized } = Orm;
   const options = { ...defaultOptions, ...userOptions };
@@ -50,9 +116,7 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
   const existingRecord = modelStore.get(rawData.id as number | string);
 
   if (existingRecord instanceof OrmRecord) {
-    // Update the existing record with new data so the last entry wins
-    updateRecord(existingRecord, rawData, { ...options, update: true });
-    return existingRecord;
+    return { result: existingRecord, written: updateRecordWrite(existingRecord, rawData, { ...options, update: true }).written };
   }
 
   const recordClasses = orm.getRecordClasses(modelName);
@@ -79,6 +143,28 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
     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);
@@ -86,7 +172,7 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
 
   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
@@ -103,7 +189,7 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
       }
 
       // 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);
@@ -114,27 +200,26 @@ 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)),
-      });
+  if (!orm?.sqlDb || !persistRequested(options, userOptions)) return { result: record, written: writeNotRequested };
+
+  const registryIdBeforePersist = record.id;
+  const response = { data: { id: record.id } };
+  const written = orm.sqlDb.persist('create', modelName, { rawData }, response)
+    .catch((failure: unknown) => {
+      throw reportPersistFailure('create', modelName, record.id, failure);
+    })
+    .finally(() => {
+      if (store._memoryResolver && !store._memoryResolver(modelName)) {
+        store.evictRecord(modelName, record.id, registryIdBeforePersist);
+      }
     });
-  }
 
-  return record;
+  return { result: record, written };
 }
 
-export function updateRecord(record: OrmRecord, rawData: unknown, userOptions: CreateRecordOptions = {}): void {
+function updateRecordWrite(record: OrmRecord, rawData: unknown, userOptions: CreateRecordOptions): RecordWrite<void> {
   if (!rawData) throw new Error('rawData must be passed in to updateRecord call');
 
-  // Guard: read-only views cannot be updated
   const modelName = record?.__model?.__name;
   if (modelName && Orm.instance?.isView?.(modelName)) {
     throw new Error(`Cannot update records for read-only view '${modelName}'`);
@@ -142,24 +227,18 @@ 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)),
-      });
-    });
-  }
+  if (!orm?.sqlDb || !modelName || !persistRequested(options, userOptions)) return { result: undefined, written: writeNotRequested };
+
+  const written = orm.sqlDb.persist('update', modelName, { record, oldState }, {}).catch((failure: unknown) => {
+    throw reportPersistFailure('update', modelName, record.id, failure);
+  });
+
+  return { result: undefined, written };
 }
 
 /**

package/src/mysql/connection.ts

@@ -9,6 +9,9 @@ interface MysqlConfig {
   connectionLimit?: number;
   migrationsTable?: string;
   migrationsDir?: string;
+  autoMigrate?: boolean;
+  writeBatchSize?: number;
+  writeQueueLimit?: number;
 }
 
 let pool: Pool | null = null;