@stonyx/orm 0.3.2-beta.8 → 0.3.2-beta.80

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/main.ts

@@ -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;

package/src/manage-record.ts

@@ -79,6 +79,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 +108,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 +125,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);
@@ -117,15 +139,25 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
   // 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: unknown) => {
-      orm!.emitPersistError({
-        operation: 'create',
-        modelName,
-        recordId: record.id,
-        error: err instanceof Error ? err : new Error(String(err)),
+    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)),
+        });
+      })
+      .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/src/postgres/connection.ts

@@ -8,6 +8,7 @@ interface PgConfig {
   password: string;
   database: string;
   connectionLimit: number;
+  [key: string]: unknown;
 }
 
 let pool: PgPool | null = null;
@@ -20,15 +21,18 @@ export async function getPool(pgConfig: PgConfig, extensions: string[] = ['vecto
 
   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

package/src/relationships.ts

@@ -51,4 +51,4 @@ export function getPendingBelongsToRegistry(): PendingBelongsToMap {
   return relationships.get('pendingBelongsTo') as PendingBelongsToMap;
 }
 
-export const TYPES: string[] = ['global', 'hasMany', 'belongsTo', 'pending'];
+export const TYPES: string[] = ['global', 'hasMany', 'belongsTo', 'pending', 'pendingBelongsTo'];

package/src/serializer.ts

@@ -94,8 +94,33 @@ export default class Serializer {
         const handlerOptions = { ...options, _relationshipKey: key };
         const childRecord = handler(record, data, handlerOptions);
 
-        rec[key] = childRecord;
-        relatedRecords[key] = childRecord;
+        // hasMany relationships use a getter so format()/toJSON() always read
+        // the live registry array instead of a stale snapshot captured at
+        // serialization time.  This is critical when child records are created
+        // in a later async frame — the belongsTo inverse wiring pushes into
+        // the shared registry array, and the getter ensures the parent sees it.
+        const isHasMany = (handler as { __relationshipType?: string }).__relationshipType === 'hasMany';
+
+        if (isHasMany) {
+          // `childRecord` IS the shared registry array — define a getter that
+          // always dereferences through the same array reference.
+          const registryArray = childRecord as unknown[];
+          Object.defineProperty(rec, key, {
+            enumerable: true,
+            configurable: true,
+            get: () => registryArray,
+            set(v: unknown) { relatedRecords[key] = v; }
+          });
+          Object.defineProperty(relatedRecords, key, {
+            enumerable: true,
+            configurable: true,
+            get: () => registryArray,
+            set(v: unknown) { Object.defineProperty(relatedRecords, key, { value: v, writable: true, enumerable: true, configurable: true }); }
+          });
+        } else {
+          rec[key] = childRecord;
+          relatedRecords[key] = childRecord;
+        }
 
         continue;
       }

package/src/store.ts

@@ -1,5 +1,5 @@
 import Orm, { relationships } from '@stonyx/orm';
-import { TYPES, getHasManyRegistry, getBelongsToRegistry, getPendingRegistry } from './relationships.js';
+import { TYPES, getHasManyRegistry, getBelongsToRegistry, getPendingRegistry, getPendingBelongsToRegistry } from './relationships.js';
 import ViewResolver from './view-resolver.js';
 
 interface UnloadOptions {
@@ -193,6 +193,44 @@ export default class Store {
     this.unloadAllRecords(key);
   }
 
+  /**
+   * Evict a record from the store with full relationship registry cleanup,
+   * WITHOUT calling record.clean(). This preserves the caller's reference
+   * to the returned record (used by memory:false post-persist eviction).
+   *
+   * @param registryId - The ID used when the record's relationships were
+   *   registered. For SQL models with pending IDs, this is the original
+   *   negative pending ID (before the adapter re-keyed to the real DB ID).
+   */
+  evictRecord(modelName: string, id: unknown, registryId?: unknown): void {
+    const modelStore = this.data.get(modelName);
+    if (!modelStore) return;
+
+    if (typeof id !== 'string' && typeof id !== 'number') return;
+    const raw = modelStore.get(id);
+    if (!raw || !isStoreRecord(raw)) return;
+
+    const visited = new Set([`${modelName}:${id}`]);
+
+    // Remove from hasMany arrays and nullify belongsTo references using current ID
+    // (the adapter updates record.id, so value-based matches need the current ID)
+    this._removeFromHasManyArrays(modelName, id, visited);
+    this._nullifyBelongsToReferences(modelName, id, visited);
+
+    // Clean up relationship registry entries using the registry key
+    // (belongsTo/hasMany registries were keyed by the ID at registration time,
+    // which may differ from the current ID if SQL persist re-keyed the record)
+    const cleanupId = registryId ?? id;
+    this._cleanupRelationshipRegistries(modelName, cleanupId);
+
+    // If registryId differs from id, also clean with current id as safety net
+    if (registryId !== undefined && registryId !== id) {
+      this._cleanupRelationshipRegistries(modelName, id);
+    }
+
+    modelStore.delete(id);
+  }
+
   unloadRecord(model: string, id: unknown, options: UnloadOptions = {}): void {
     const modelStore = this.data.get(model);
 
@@ -308,6 +346,30 @@ export default class Store {
 
     const pendingMap = getPendingRegistry().get(modelName);
     if (pendingMap) pendingMap.delete(recordId);
+
+    // Clean pendingBelongsTo entries in both directions
+    const pendingBelongsToMap = getPendingBelongsToRegistry();
+    if (pendingBelongsToMap) {
+      // Direction 1: evicted record was the TARGET others were waiting for
+      const targetEntries = pendingBelongsToMap.get(modelName);
+      if (targetEntries) targetEntries.delete(recordId);
+
+      // Direction 2: evicted record was the SOURCE with unresolved forward-references
+      for (const [, targetIdMap] of pendingBelongsToMap) {
+        for (const [targetId, entries] of targetIdMap) {
+          if (!Array.isArray(entries)) continue;
+          const filtered = entries.filter((e: unknown) => {
+            const entry = e as { sourceModelName?: string; relationshipId?: unknown };
+            return !(entry.sourceModelName === modelName && entry.relationshipId === recordId);
+          });
+          if (filtered.length === 0) {
+            targetIdMap.delete(targetId);
+          } else if (filtered.length < entries.length) {
+            targetIdMap.set(targetId, filtered);
+          }
+        }
+      }
+    }
   }
 
   /**

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;
 }
 

package/config/environment.ts

@@ -1,91 +0,0 @@
-const {
-  ORM_ACCESS_PATH,
-  ORM_MODEL_PATH,
-  ORM_REST_ROUTE,
-  ORM_SERIALIZER_PATH,
-  ORM_TRANSFORM_PATH,
-  ORM_VIEW_PATH,
-  ORM_USE_REST_SERVER,
-  DB_AUTO_SAVE,
-  DB_FILE,
-  DB_MODE,
-  DB_DIRECTORY,
-  DB_SCHEMA_PATH,
-  DB_SAVE_INTERVAL,
-  MYSQL_HOST,
-  MYSQL_PORT,
-  MYSQL_USER,
-  MYSQL_PASSWORD,
-  MYSQL_DATABASE,
-  MYSQL_CONNECTION_LIMIT,
-  MYSQL_MIGRATIONS_DIR,
-  PG_HOST,
-  PG_PORT,
-  PG_USER,
-  PG_PASSWORD,
-  PG_DATABASE,
-  PG_CONNECTION_LIMIT,
-  PG_MIGRATIONS_DIR,
-  TIMESCALE_HOST,
-  TIMESCALE_PORT,
-  TIMESCALE_USER,
-  TIMESCALE_PASSWORD,
-  TIMESCALE_DATABASE,
-  TIMESCALE_CONNECTION_LIMIT,
-  TIMESCALE_MIGRATIONS_DIR,
-} = process.env;
-
-export default {
-  logColor: 'white',
-  logMethod: 'db',
-  
-  db: {
-    autosave: DB_AUTO_SAVE ?? 'false', // 'true' (cron interval), 'false' (disabled), 'onUpdate' (save after each write op)
-    file: DB_FILE ?? 'db.json',
-    mode: DB_MODE ?? 'file', // 'file' (single db.json) or 'directory' (one file per collection)
-    directory: DB_DIRECTORY ?? 'db', // directory name for collection files when mode is 'directory'
-    saveInterval: DB_SAVE_INTERVAL ?? 60 * 60, // 1 hour
-    schema: DB_SCHEMA_PATH ?? './config/db-schema.js'
-  },
-  paths: {
-    access: ORM_ACCESS_PATH ?? './access', // Optional for restServer access hooks
-    model: ORM_MODEL_PATH ?? './models',
-    serializer: ORM_SERIALIZER_PATH ?? './serializers',
-    transform: ORM_TRANSFORM_PATH ?? './transforms',
-    view: ORM_VIEW_PATH ?? './views'
-  },
-  mysql: MYSQL_HOST ? {
-    host: MYSQL_HOST ?? 'localhost',
-    port: parseInt(MYSQL_PORT ?? '3306'),
-    user: MYSQL_USER ?? 'root',
-    password: MYSQL_PASSWORD ?? '',
-    database: MYSQL_DATABASE ?? 'stonyx',
-    connectionLimit: parseInt(MYSQL_CONNECTION_LIMIT ?? '10'),
-    migrationsDir: MYSQL_MIGRATIONS_DIR ?? 'migrations',
-    migrationsTable: '__migrations',
-  } : undefined,
-  postgres: PG_HOST ? {
-    host: PG_HOST ?? 'localhost',
-    port: parseInt(PG_PORT ?? '5432'),
-    user: PG_USER ?? 'postgres',
-    password: PG_PASSWORD ?? '',
-    database: PG_DATABASE ?? 'stonyx',
-    connectionLimit: parseInt(PG_CONNECTION_LIMIT ?? '10'),
-    migrationsDir: PG_MIGRATIONS_DIR ?? 'migrations',
-    migrationsTable: '__migrations',
-  } : undefined,
-  timescale: TIMESCALE_HOST ? {
-    host: TIMESCALE_HOST ?? 'localhost',
-    port: parseInt(TIMESCALE_PORT ?? '5432'),
-    user: TIMESCALE_USER ?? 'postgres',
-    password: TIMESCALE_PASSWORD ?? '',
-    database: TIMESCALE_DATABASE ?? 'stonyx',
-    connectionLimit: parseInt(TIMESCALE_CONNECTION_LIMIT ?? '10'),
-    migrationsDir: TIMESCALE_MIGRATIONS_DIR ?? 'migrations',
-    migrationsTable: '__migrations',
-  } : undefined,
-  restServer: {
-    enabled: ORM_USE_REST_SERVER ?? 'true', // Whether to load restServer for automatic route setup or
-    route: ORM_REST_ROUTE ?? '/',
-  }
-}