@acodeninja/persist 3.3.1 → 3.3.2-next.1

package/docs/transactions.md

@@ -15,8 +15,24 @@ export class Tag extends Persist.Model {
     static tag = Persist.Property.String.required;
 }
 
-const transaction = connection.start();
+const transaction = connection.transaction();
 
 await transaction.put(new Tag({tag: 'documentation'}));
 await transaction.commit();
 ```
+
+Nothing reaches storage until `commit()`. Reads inside a transaction go straight
+to the engine, so they see the data as it was before the transaction started.
+
+### Write ordering
+
+Both `put` and `delete` order their writes so that a reader never sees an index
+entry without the model it points at:
+
+- `put` writes the model, then the indexes that list it. An index that has not
+  caught up hides a model that is stored, so it reads as missing.
+- `delete` writes the indexes, then deletes the model. A model nothing lists is
+  unreachable, so it costs storage.
+
+The inverse of either leaves an index pointing at a model that is not there,
+which fails every read of that id.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acodeninja/persist",
-  "version": "3.3.1",
+  "version": "3.3.2-next.1",
   "description": "A JSON based data modelling and persistence module with alternate storage mechanisms.",
   "type": "module",
   "scripts": {
@@ -39,6 +39,9 @@
     "@eslint/js": "^10.0.1",
     "@jest/globals": "^30.4.1",
     "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^12.0.10",
+    "@semantic-release/npm": "^13.2.0",
+    "@semantic-release/release-notes-generator": "^14.1.1",
     "eslint": "^10.9.1",
     "globals": "^17.11.0",
     "husky": "^9.1.7",

package/src/Connection.js

@@ -290,8 +290,12 @@ export default class Connection {
 
         await processModel(model);
 
+        // Models before the indexes that list them. Written the other way round,
+        // a reader that queries an index between the two writes finds an id whose
+        // model is not there yet, and a get on it fails.
+        await Promise.all(modelsToPut.map(m => this.#storage.putModel(m.toData())));
+
         await Promise.all([
-            Promise.all(modelsToPut.map(m => this.#storage.putModel(m.toData()))),
             Promise.all(Object.entries(modelsToReindex).map(async ([constructorName, models]) => {
                 const modelConstructor = this.#models.get(constructorName);
                 const index = await this.#storage.getIndex(modelConstructor);
@@ -446,9 +450,11 @@ export default class Connection {
             state.updateIndex(indexName, index);
         }
 
+        // Indexes before the models they stop listing. Deleted first, an index
+        // left pointing at a model that is gone breaks every read of it, where a
+        // model no index lists is merely unreachable.
         await Promise.all([
             Promise.all([...modelsToUpdate].map(id => this.#storage.putModel(state.modelCache.get(id).toData()))),
-            Promise.all([...modelsToDelete].map(id => this.#storage.deleteModel(id))),
             Promise.all(state
                 .getTaintedIndexes()
                 .entries()
@@ -464,6 +470,8 @@ export default class Connection {
                 ),
             ),
         ]);
+
+        await Promise.all([...modelsToDelete].map(id => this.#storage.deleteModel(id)));
     }
 
     /**

package/src/engine/storage/StorageEngine.js

@@ -160,34 +160,35 @@ export class Operation {
     }
 }
 
+const QUEUED_OPERATIONS = ['putModel', 'deleteModel', 'putIndex', 'putSearchIndex'];
+
 /**
+ * Wrap a storage engine so that writes queue as operations and reads pass through.
  *
- * @param {Array<Operation>} transactions
+ * @param {Array<Operation>} operations
  * @param {StorageEngine} engine
  * @return {StorageEngine}
  */
 export function CreateTransactionalStorageEngine(operations, engine) {
-    const transactionalEngine = Object.create(engine);
-
-    transactionalEngine.putModel = (...args) => {
-        operations.push(new Operation('putModel', ...args));
-        return Promise.resolve();
-    };
-
-    transactionalEngine.deleteModel = (...args) => {
-        operations.push(new Operation('deleteModel', ...args));
-        return Promise.resolve();
-    };
-
-    transactionalEngine.putIndex = (...args) => {
-        operations.push(new Operation('putIndex', ...args));
-        return Promise.resolve();
-    };
-
-    transactionalEngine.putSearchIndex = (...args) => {
-        operations.push(new Operation('putSearchIndex', ...args));
-        return Promise.resolve();
-    };
-
-    return transactionalEngine;
+    return new Proxy(engine, {
+        get(target, property) {
+            if (QUEUED_OPERATIONS.includes(property))
+                return (...args) => {
+                    operations.push(new Operation(property, ...args));
+                    return Promise.resolve();
+                };
+
+            const value = Reflect.get(target, property, target);
+
+            // Methods are bound to the engine rather than to the wrapper. An
+            // engine holding its state in private class members cannot run its
+            // own methods with anything else as the receiver, and every read
+            // made through the transaction threw "Receiver must be an instance
+            // of". The class itself is left alone, because binding it renames it
+            // to "bound <Engine>" and the engine's errors quote that name.
+            return typeof value === 'function' && property !== 'constructor'
+                ? value.bind(target)
+                : value;
+        },
+    });
 }