@stonyx/orm 0.3.2-alpha.125 → 0.3.2-alpha.126

package/README.md

@@ -1057,6 +1057,8 @@ test('validation hook rejects negative age', async () => {
 | `hasMany`       | Define a one-to-many relationship.                                      |
 | `createRecord`  | Instantiate a record with proper serialization and relationships.       |
 | `updateRecord`  | Update an existing record with new data.                                |
+| `createRecordAndPersist` | `createRecord`, awaited: resolves once the write has landed, rejects with its error. Not on DynamoDB yet (#299). |
+| `updateRecordAndPersist` | `updateRecord`, awaited: resolves once the write has landed, rejects with its error. Not on DynamoDB yet (#299). |
 | `store`         | Singleton store for all model instances.                                |
 | `relationships` | Access all relationships (`hasMany`, `belongsTo`, `global`, `pending`). |
 | `beforeHook`    | Register a before hook that can halt operations.                        |

package/dist/index.d.ts

@@ -4,13 +4,13 @@ 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 };
-export { attr, belongsTo, hasMany, createRecord, updateRecord };
+export { attr, belongsTo, hasMany, createRecord, updateRecord, createRecordAndPersist, updateRecordAndPersist };
 export { count, avg, sum, min, max };
 export { default as normalizeRecordId } from './normalize-record-id.js';
 export type { OrmRequest$ as OrmAccessRequest } from './orm-request.js';

package/dist/index.js

@@ -19,12 +19,12 @@ 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 { 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 { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks

package/dist/main.d.ts

@@ -7,6 +7,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[]>;
 }

package/dist/manage-record.d.ts

@@ -11,4 +11,8 @@ export declare function createRecord(modelName: string, rawData?: {
     [key: string]: unknown;
 }, userOptions?: CreateRecordOptions): OrmRecord;
 export declare function updateRecord(record: OrmRecord, rawData: unknown, userOptions?: CreateRecordOptions): void;
+export declare function createRecordAndPersist(modelName: string, rawData?: {
+    [key: string]: unknown;
+}, userOptions?: CreateRecordOptions): Promise<OrmRecord>;
+export declare function updateRecordAndPersist(record: OrmRecord, rawData: unknown, userOptions?: CreateRecordOptions): Promise<void>;
 export {};

package/dist/manage-record.js

@@ -8,7 +8,57 @@ const defaultOptions = {
     transform: true
 };
 let pendingIdCounter = 0;
+const writeNotRequested = Promise.resolve();
+function ignoreReportedFailure() { }
+function persistRequested(options, userOptions) {
+    return !options.isDbRecord && !userOptions._relationshipKey && !options._skipAutoPersist;
+}
+function reportPersistFailure(operation, modelName, recordId, failure) {
+    const error = failure instanceof Error ? failure : new Error(String(failure));
+    Orm.instance.emitPersistError({ operation, modelName, recordId, error });
+    return error;
+}
 export function createRecord(modelName, rawData = {}, userOptions = {}) {
+    const { result: record, written } = createRecordWrite(modelName, rawData, userOptions);
+    written.catch(ignoreReportedFailure);
+    return record;
+}
+export function updateRecord(record, rawData, userOptions = {}) {
+    updateRecordWrite(record, rawData, userOptions).written.catch(ignoreReportedFailure);
+}
+export async function createRecordAndPersist(modelName, rawData = {}, userOptions = {}) {
+    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, rawData, userOptions = {}) {
+    assertWriteCanBeAwaited();
+    await updateRecordWrite(record, rawData, userOptions).written;
+    await saveJsonDatabase('update', record?.__model?.__name ?? '', record.id, { ...defaultOptions, ...userOptions }, userOptions);
+}
+function assertWriteCanBeAwaited() {
+    const sqlDb = Orm.instance?.sqlDb;
+    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, modelName, recordId, options, userOptions) {
+    const orm = Orm.instance;
+    if (orm.sqlDb || !persistRequested(options, userOptions))
+        return;
+    const jsonDatabase = orm.db;
+    if (!jsonDatabase?.save)
+        return;
+    try {
+        await jsonDatabase.save();
+    }
+    catch (failure) {
+        throw reportPersistFailure(operation, modelName, recordId, failure);
+    }
+}
+function createRecordWrite(modelName, rawData, userOptions) {
     const orm = Orm.instance;
     const { initialized } = Orm;
     const options = { ...defaultOptions, ...userOptions };
@@ -26,9 +76,7 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
     assignRecordId(modelName, rawData);
     const existingRecord = modelStore.get(rawData.id);
     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);
     const modelClass = recordClasses.modelClass;
@@ -101,56 +149,38 @@ 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;
+    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) => {
+        throw reportPersistFailure('create', modelName, record.id, failure);
+    })
+        .finally(() => {
+        if (store._memoryResolver && !store._memoryResolver(modelName)) {
+            store.evictRecord(modelName, record.id, registryIdBeforePersist);
+        }
+    });
+    return { result: record, written };
 }
-export function updateRecord(record, rawData, userOptions = {}) {
+function updateRecordWrite(record, rawData, userOptions) {
     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}'`);
     }
     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)),
-            });
-        });
-    }
+    if (!orm?.sqlDb || !modelName || !persistRequested(options, userOptions))
+        return { result: undefined, written: writeNotRequested };
+    const written = orm.sqlDb.persist('update', modelName, { record, oldState }, {}).catch((failure) => {
+        throw reportPersistFailure('update', modelName, record.id, failure);
+    });
+    return { result: undefined, written };
 }
 /**
  * gets the next available id based on last record entry.

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

@@ -70,6 +70,7 @@ export default class MysqlDB {
     deps: MysqlDBDeps;
     pool: Pool | null;
     mysqlConfig: MysqlConfig;
+    readonly persistResolvesAfterWrite = true;
     private _queuedWrites;
     private _inFlightWrites;
     private _drainingWrites;

package/dist/mysql/mysql-db.js

@@ -41,6 +41,7 @@ export default class MysqlDB {
     deps;
     pool;
     mysqlConfig;
+    persistResolvesAfterWrite = true;
     _queuedWrites = [];
     _inFlightWrites = new Set();
     _drainingWrites = null;

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

@@ -85,6 +85,7 @@ export default class PostgresDB {
     deps: PostgresDeps;
     pool: Pool | null;
     pgConfig: Record<string, unknown>;
+    readonly persistResolvesAfterWrite = true;
     private _queuedWrites;
     private _inFlightWrites;
     private _drainingWrites;

package/dist/postgres/postgres-db.js

@@ -48,6 +48,7 @@ export default class PostgresDB {
     deps;
     pool;
     pgConfig;
+    persistResolvesAfterWrite = true;
     _queuedWrites = [];
     _inFlightWrites = new Set();
     _drainingWrites = null;

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.125",
+  "version": "0.3.2-alpha.126",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/index.ts

@@ -21,14 +21,14 @@ 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)

package/src/main.ts

@@ -34,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[]>;
 }

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);
@@ -136,37 +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) {
-    // 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)),
-        });
-      })
-      .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);
-        }
-      });
-  }
+  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}'`);
@@ -174,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/mysql-db.ts

@@ -123,6 +123,7 @@ export default class MysqlDB {
   pool!: Pool | null;
   mysqlConfig!: MysqlConfig;
 
+  readonly persistResolvesAfterWrite = true;
   private _queuedWrites: QueuedWrite[] = [];
   private _inFlightWrites = new Set<QueuedWrite>();
   private _drainingWrites: Promise<void> | null = null;

package/src/postgres/postgres-db.ts

@@ -134,6 +134,7 @@ export default class PostgresDB {
   pool!: Pool | null;
   pgConfig!: Record<string, unknown>;
 
+  readonly persistResolvesAfterWrite = true;
   private _queuedWrites: QueuedWrite[] = [];
   private _inFlightWrites = new Set<QueuedWrite>();
   private _drainingWrites: Promise<void> | null = null;