@lossless.org/client 1.10.0 → 1.11.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@lossless.org/client',
-    version: '1.10.0',
+    version: '1.11.0',
     description: 'One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxzQkFBc0I7SUFDNUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLDBGQUEwRjtDQUN4RyxDQUFBIn0=

package/dist_ts/nosqldb/classes.easystore.d.ts

@@ -23,32 +23,61 @@ export declare class EasyStore<T> {
     private easyStorePromise?;
     private getEasyStore;
     /**
-     * reads all keyValue pairs at once and returns them
+     * Runs store operations one at a time, in the order they were called. Every
+     * read and write of this instance goes through here, so a write builds its
+     * next state from the state every earlier write left, and a read never sees
+     * the state of a write whose save has not resolved yet. A rejected operation
+     * does not stop the ones queued behind it.
      */
-    readAll(): Promise<any>;
+    private operationQueue;
+    private runExclusive;
     /**
-     * reads a keyValueFile from disk
+     * Persists `nextDataArg` as the store's data. The document's `save()` writes
+     * the instance's own fields, so the next state is installed for the save and
+     * the previous one is put back when the save rejects: a failed write leaves
+     * the cache as it was. Callers hold the operation queue.
+     */
+    private commit;
+    /**
+     * reads all keyValue pairs at once and returns them as a copy in the
+     * persisted form: mutating the result does not change the store, and later
+     * writes do not change the result.
+     */
+    readAll(): Promise<Partial<T>>;
+    /**
+     * reads one key and returns a copy of its value in the persisted form, or
+     * `undefined` when the key is absent
      */
     readKey<TKey extends keyof T>(keyArg: TKey): Promise<Partial<T>[TKey]>;
     /**
-     * writes a specific key to the keyValueStore
+     * writes a specific key to the keyValueStore. The store keeps a copy, so
+     * mutating `valueArg` afterwards does not change the store. When the save
+     * rejects, the store keeps its previous state.
      */
     writeKey<TKey extends keyof T>(keyArg: TKey, valueArg: T[TKey]): Promise<void>;
+    /**
+     * deletes a key. When the save rejects, the store keeps its previous state.
+     */
     deleteKey(keyArg: keyof T): Promise<void>;
     /**
      * merges all keyValue pairs from the object argument into the store.
      * Existing keys that are not present in `keyValueObject` are preserved.
      * To overwrite the entire store and drop missing keys, use `replace()`.
+     * The store keeps a copy, so mutating `keyValueObject` afterwards does not
+     * change the store. When the save rejects, the store keeps its previous state.
      */
     writeAll(keyValueObject: Partial<T>): Promise<void>;
     /**
      * atomically replaces the entire store with the given object.
      * Unlike `writeAll` (which merges), `replace` clears any keys not
      * present in `keyValueObject`. Useful when you need to drop a key.
+     * The store keeps a copy, so mutating `keyValueObject` afterwards does not
+     * change the store. When the save rejects, the store keeps its previous state.
      */
     replace(keyValueObject: Partial<T>): Promise<void>;
     /**
-     * wipes a key value store from disk
+     * wipes a key value store from disk. When the save rejects, the store keeps
+     * its previous state.
      */
     wipe(): Promise<void>;
     cleanUpEphemeral(): Promise<void>;

package/dist_ts/nosqldb/classes.easystore.js

@@ -91,6 +91,21 @@ const getEasyStoreClassForDb = (smartdataDbArg) => {
     easyStoreClassByDb.set(smartdataDbArg, SmartdataEasyStore);
     return SmartdataEasyStore;
 };
+/**
+ * Copies a store value into the form the store persists: undefined object
+ * properties are dropped, an undefined array element becomes null and every
+ * value takes its BSON form, exactly as a save and a later read from the
+ * database do. The copy shares no object with the argument, so neither side can
+ * change the other afterwards. A value BSON cannot encode (a cycle, for
+ * example) throws here, before the store's cache is touched.
+ */
+const copyInPersistedForm = (valueArg) => {
+    if (valueArg === undefined) {
+        return valueArg;
+    }
+    const document = plugins.mongodb.BSON.deserialize(plugins.mongodb.BSON.serialize({ value: valueArg }, { ignoreUndefined: true }));
+    return document.value;
+};
 /**
  * EasyStore allows the storage of easy objects. It also allows easy sharing of the object between different instances
  */
@@ -148,59 +163,118 @@ export class EasyStore {
         return deferred.promise;
     }
     /**
-     * reads all keyValue pairs at once and returns them
+     * Runs store operations one at a time, in the order they were called. Every
+     * read and write of this instance goes through here, so a write builds its
+     * next state from the state every earlier write left, and a read never sees
+     * the state of a write whose save has not resolved yet. A rejected operation
+     * does not stop the ones queued behind it.
+     */
+    operationQueue = Promise.resolve();
+    runExclusive(operationArg) {
+        const result = this.operationQueue.then(operationArg);
+        this.operationQueue = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    /**
+     * Persists `nextDataArg` as the store's data. The document's `save()` writes
+     * the instance's own fields, so the next state is installed for the save and
+     * the previous one is put back when the save rejects: a failed write leaves
+     * the cache as it was. Callers hold the operation queue.
+     */
+    async commit(easyStoreArg, nextDataArg) {
+        const previousData = easyStoreArg.data;
+        easyStoreArg.data = nextDataArg;
+        try {
+            await easyStoreArg.save();
+        }
+        catch (error) {
+            easyStoreArg.data = previousData;
+            throw error;
+        }
+    }
+    /**
+     * reads all keyValue pairs at once and returns them as a copy in the
+     * persisted form: mutating the result does not change the store, and later
+     * writes do not change the result.
      */
     async readAll() {
-        const easyStore = await this.getEasyStore();
-        return easyStore.data;
+        return this.runExclusive(async () => {
+            const easyStore = await this.getEasyStore();
+            return copyInPersistedForm(easyStore.data);
+        });
     }
     /**
-     * reads a keyValueFile from disk
+     * reads one key and returns a copy of its value in the persisted form, or
+     * `undefined` when the key is absent
      */
     async readKey(keyArg) {
-        const easyStore = await this.getEasyStore();
-        return easyStore.data[keyArg];
+        return this.runExclusive(async () => {
+            const easyStore = await this.getEasyStore();
+            return copyInPersistedForm(easyStore.data[keyArg]);
+        });
     }
     /**
-     * writes a specific key to the keyValueStore
+     * writes a specific key to the keyValueStore. The store keeps a copy, so
+     * mutating `valueArg` afterwards does not change the store. When the save
+     * rejects, the store keeps its previous state.
      */
     async writeKey(keyArg, valueArg) {
-        const easyStore = await this.getEasyStore();
-        easyStore.data[keyArg] = valueArg;
-        await easyStore.save();
+        const value = copyInPersistedForm(valueArg);
+        await this.runExclusive(async () => {
+            const easyStore = await this.getEasyStore();
+            const nextData = { ...easyStore.data };
+            nextData[keyArg] = value;
+            await this.commit(easyStore, nextData);
+        });
     }
+    /**
+     * deletes a key. When the save rejects, the store keeps its previous state.
+     */
     async deleteKey(keyArg) {
-        const easyStore = await this.getEasyStore();
-        delete easyStore.data[keyArg];
-        await easyStore.save();
+        await this.runExclusive(async () => {
+            const easyStore = await this.getEasyStore();
+            const nextData = { ...easyStore.data };
+            delete nextData[keyArg];
+            await this.commit(easyStore, nextData);
+        });
     }
     /**
      * merges all keyValue pairs from the object argument into the store.
      * Existing keys that are not present in `keyValueObject` are preserved.
      * To overwrite the entire store and drop missing keys, use `replace()`.
+     * The store keeps a copy, so mutating `keyValueObject` afterwards does not
+     * change the store. When the save rejects, the store keeps its previous state.
      */
     async writeAll(keyValueObject) {
-        const easyStore = await this.getEasyStore();
-        easyStore.data = { ...easyStore.data, ...keyValueObject };
-        await easyStore.save();
+        const values = copyInPersistedForm(keyValueObject);
+        await this.runExclusive(async () => {
+            const easyStore = await this.getEasyStore();
+            await this.commit(easyStore, { ...easyStore.data, ...values });
+        });
     }
     /**
      * atomically replaces the entire store with the given object.
      * Unlike `writeAll` (which merges), `replace` clears any keys not
      * present in `keyValueObject`. Useful when you need to drop a key.
+     * The store keeps a copy, so mutating `keyValueObject` afterwards does not
+     * change the store. When the save rejects, the store keeps its previous state.
      */
     async replace(keyValueObject) {
-        const easyStore = await this.getEasyStore();
-        easyStore.data = { ...keyValueObject };
-        await easyStore.save();
+        const values = copyInPersistedForm(keyValueObject);
+        await this.runExclusive(async () => {
+            const easyStore = await this.getEasyStore();
+            await this.commit(easyStore, values);
+        });
     }
     /**
-     * wipes a key value store from disk
+     * wipes a key value store from disk. When the save rejects, the store keeps
+     * its previous state.
      */
     async wipe() {
-        const easyStore = await this.getEasyStore();
-        easyStore.data = {};
-        await easyStore.save();
+        await this.runExclusive(async () => {
+            const easyStore = await this.getEasyStore();
+            await this.commit(easyStore, {});
+        });
     }
     async cleanUpEphemeral() {
         // Clean up ephemeral data periodically while connected
@@ -211,4 +285,4 @@ export class EasyStore {
         }
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5lYXN5c3RvcmUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9ub3NxbGRiL2NsYXNzZXMuZWFzeXN0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUN4QyxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFDckQsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBQzlDLE9BQU8sRUFBRSxjQUFjLEVBQUUsSUFBSSxFQUFFLEdBQUcsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBRTdELE1BQU0sa0JBQWtCLEdBQUcsSUFBSSxPQUFPLEVBQW9CLENBQUM7QUFFM0QsTUFBTSxzQkFBc0IsR0FBRyxDQUFJLGNBQTJCLEVBQUUsRUFBRTtJQUNoRSxNQUFNLGFBQWEsR0FBRyxrQkFBa0IsQ0FBQyxHQUFHLENBQUMsY0FBYyxDQUFDLENBQUM7SUFDN0QsSUFBSSxhQUFhLEVBQUUsQ0FBQztRQUNsQixPQUFPLGFBQWEsQ0FBQztJQUN2QixDQUFDO1FBRUssa0JBQWtCO2dDQUR2QixVQUFVLENBQUMsR0FBRyxFQUFFLENBQUMsY0FBYyxDQUFDOzs7OzBCQUNBLGNBQWM7Ozs7Ozs7Ozs7Ozs7c0NBQXRCLFNBQVEsV0FHaEM7Ozs7c0NBQ0UsR0FBRyxFQUFFO3lDQUdMLElBQUksRUFBRTt3Q0FNTixJQUFJLEVBQUU7b0NBR04sSUFBSSxFQUFFO2dCQVhQLG9LQUFPLE1BQU0sNkJBQU4sTUFBTSx1RkFBVTtnQkFHdkIsNktBQU8sU0FBUyw2QkFBVCxTQUFTLDZGQUdkO2dCQUdGLDBLQUFBLFFBQVEsNkJBQVIsUUFBUSwyRkFBVTtnQkFHbEIsOEpBQU8sSUFBSSw2QkFBSixJQUFJLG1GQUFjO2dCQWpCM0IsNktBa0JDOzs7Z0JBbEJLLHVEQUFrQjs7WUFLZixNQUFN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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5lYXN5c3RvcmUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9ub3NxbGRiL2NsYXNzZXMuZWFzeXN0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUN4QyxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFDckQsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBQzlDLE9BQU8sRUFBRSxjQUFjLEVBQUUsSUFBSSxFQUFFLEdBQUcsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBRTdELE1BQU0sa0JBQWtCLEdBQUcsSUFBSSxPQUFPLEVBQW9CLENBQUM7QUFFM0QsTUFBTSxzQkFBc0IsR0FBRyxDQUFJLGNBQTJCLEVBQUUsRUFBRTtJQUNoRSxNQUFNLGFBQWEsR0FBRyxrQkFBa0IsQ0FBQyxHQUFHLENBQUMsY0FBYyxDQUFDLENBQUM7SUFDN0QsSUFBSSxhQUFhLEVBQUUsQ0FBQztRQUNsQixPQUFPLGFBQWEsQ0FBQztJQUN2QixDQUFDO1FBRUssa0JBQWtCO2dDQUR2QixVQUFVLENBQUMsR0FBRyxFQUFFLENBQUMsY0FBYyxDQUFDOzs7OzBCQUNBLGNBQWM7Ozs7Ozs7Ozs7Ozs7c0NBQXRCLFNBQVEsV0FHaEM7Ozs7c0NBQ0UsR0FBRyxFQUFFO3lDQUdMLElBQUksRUFBRTt3Q0FNTixJQUFJLEVBQUU7b0NBR04sSUFBSSxFQUFFO2dCQVhQLG9LQUFPLE1BQU0sNkJBQU4sTUFBTSx1RkFBVTtnQkFHdkIsNktBQU8sU0FBUyw2QkFBVCxTQUFTLDZGQUdkO2dCQUdGLDBLQUFBLFFBQVEsNkJBQVIsUUFBUSwyRkFBVTtnQkFHbEIsOEpBQU8sSUFBSSw2QkFBSixJQUFJLG1GQUFjO2dCQWpCM0IsNktBa0JDOzs7Z0JBbEJLLHVEQUFrQjs7WUFLZixNQUFN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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lossless.org/client",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "private": false,
   "description": "One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.",
   "exports": {

package/readme.md

@@ -102,6 +102,7 @@ Family imports preserve the established SmartData and SmartBucket names and cons
 | Migration-owned indexes | `toleratedIndexNames` on the model — named undeclared indexes are observed, never created, dropped or verified, and no longer make the topology divergent |
 | Partial index filters in inspection | `inspectNamespace()`, `inspectCollectionTopology()` and `getIndexInfo()` report a partial index's `partialFilterExpression` exactly as the backend lists it, as a frozen snapshot present only on a partial index |
 | Key-value store readiness | `EasyStore.ensureInitialized()` — installs the store's declared index at startup, outside any transaction window, so a first `readKey()`/`writeKey()` needs no index DDL |
+| Key-value store copies | `EasyStore` `readKey()`/`readAll()` return copies and `writeKey()`/`writeAll()`/`replace()` store copies, in the persisted BSON form, so a read result is a stable snapshot and a caller-side mutation never reaches the store |
 | Client deadlines | `timeoutMS` (1..120000) on every ordinary model read and write, instance `save()`/`saveIf()`/`delete()` included, on every exact call, and `session.withTransaction(callback, { timeoutMS })` for a whole transaction, retries and commit included; expiry rejects with `SmartdataPersistenceError` code `timeout`, and an exact write interrupted in flight with `ambiguous_write` |
 | Cancellation | `signal` on every exact call, `atomicDeleteMany()` and `session.withTransaction(callback, { signal })`, which interrupts the session's operation in flight, rolls the attempt back and never commits after an abort |
 | Disposable test databases on a unix socket | `SmartdataTestDatabase.create({ connection: { socketPath } })` from `@lossless.org/client/testsupport` reaches an engine that listens only on a unix-domain socket, fault helpers included; the loopback `host`/`port` form is unchanged |

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@lossless.org/client',
-  version: '1.10.0',
+  version: '1.11.0',
   description: 'One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.'
 }

package/ts/nosqldb/classes.easystore.ts

@@ -34,6 +34,24 @@ const getEasyStoreClassForDb = <T>(smartdataDbArg: SmartdataDb) => {
   return SmartdataEasyStore;
 };
 
+/**
+ * Copies a store value into the form the store persists: undefined object
+ * properties are dropped, an undefined array element becomes null and every
+ * value takes its BSON form, exactly as a save and a later read from the
+ * database do. The copy shares no object with the argument, so neither side can
+ * change the other afterwards. A value BSON cannot encode (a cycle, for
+ * example) throws here, before the store's cache is touched.
+ */
+const copyInPersistedForm = <TValue>(valueArg: TValue): TValue => {
+  if (valueArg === undefined) {
+    return valueArg;
+  }
+  const document = plugins.mongodb.BSON.deserialize(
+    plugins.mongodb.BSON.serialize({ value: valueArg }, { ignoreUndefined: true }),
+  );
+  return document.value as TValue;
+};
+
 /**
  * EasyStore allows the storage of easy objects. It also allows easy sharing of the object between different instances
  */
@@ -98,65 +116,131 @@ export class EasyStore<T> {
   }
 
   /**
-   * reads all keyValue pairs at once and returns them
+   * Runs store operations one at a time, in the order they were called. Every
+   * read and write of this instance goes through here, so a write builds its
+   * next state from the state every earlier write left, and a read never sees
+   * the state of a write whose save has not resolved yet. A rejected operation
+   * does not stop the ones queued behind it.
+   */
+  private operationQueue: Promise<void> = Promise.resolve();
+  private runExclusive<TResult>(operationArg: () => Promise<TResult>): Promise<TResult> {
+    const result = this.operationQueue.then(operationArg);
+    this.operationQueue = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+
+  /**
+   * Persists `nextDataArg` as the store's data. The document's `save()` writes
+   * the instance's own fields, so the next state is installed for the save and
+   * the previous one is put back when the save rejects: a failed write leaves
+   * the cache as it was. Callers hold the operation queue.
    */
-  public async readAll() {
-    const easyStore = await this.getEasyStore();
-    return easyStore.data;
+  private async commit(
+    easyStoreArg: InstanceType<typeof this.easyStoreClass>,
+    nextDataArg: Partial<T>,
+  ): Promise<void> {
+    const previousData = easyStoreArg.data;
+    easyStoreArg.data = nextDataArg;
+    try {
+      await easyStoreArg.save();
+    } catch (error) {
+      easyStoreArg.data = previousData;
+      throw error;
+    }
   }
 
   /**
-   * reads a keyValueFile from disk
+   * reads all keyValue pairs at once and returns them as a copy in the
+   * persisted form: mutating the result does not change the store, and later
+   * writes do not change the result.
+   */
+  public async readAll(): Promise<Partial<T>> {
+    return this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      return copyInPersistedForm(easyStore.data);
+    });
+  }
+
+  /**
+   * reads one key and returns a copy of its value in the persisted form, or
+   * `undefined` when the key is absent
    */
   public async readKey<TKey extends keyof T>(keyArg: TKey): Promise<Partial<T>[TKey]> {
-    const easyStore = await this.getEasyStore();
-    return easyStore.data[keyArg];
+    return this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      return copyInPersistedForm(easyStore.data[keyArg]);
+    });
   }
 
   /**
-   * writes a specific key to the keyValueStore
+   * writes a specific key to the keyValueStore. The store keeps a copy, so
+   * mutating `valueArg` afterwards does not change the store. When the save
+   * rejects, the store keeps its previous state.
    */
   public async writeKey<TKey extends keyof T>(keyArg: TKey, valueArg: T[TKey]) {
-    const easyStore = await this.getEasyStore();
-    easyStore.data[keyArg] = valueArg;
-    await easyStore.save();
+    const value = copyInPersistedForm(valueArg);
+    await this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      const nextData: Partial<T> = { ...easyStore.data };
+      nextData[keyArg] = value;
+      await this.commit(easyStore, nextData);
+    });
   }
 
+  /**
+   * deletes a key. When the save rejects, the store keeps its previous state.
+   */
   public async deleteKey(keyArg: keyof T) {
-    const easyStore = await this.getEasyStore();
-    delete easyStore.data[keyArg];
-    await easyStore.save();
+    await this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      const nextData: Partial<T> = { ...easyStore.data };
+      delete nextData[keyArg];
+      await this.commit(easyStore, nextData);
+    });
   }
 
   /**
    * merges all keyValue pairs from the object argument into the store.
    * Existing keys that are not present in `keyValueObject` are preserved.
    * To overwrite the entire store and drop missing keys, use `replace()`.
+   * The store keeps a copy, so mutating `keyValueObject` afterwards does not
+   * change the store. When the save rejects, the store keeps its previous state.
    */
   public async writeAll(keyValueObject: Partial<T>) {
-    const easyStore = await this.getEasyStore();
-    easyStore.data = { ...easyStore.data, ...keyValueObject };
-    await easyStore.save();
+    const values = copyInPersistedForm(keyValueObject);
+    await this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      await this.commit(easyStore, { ...easyStore.data, ...values });
+    });
   }
 
   /**
    * atomically replaces the entire store with the given object.
    * Unlike `writeAll` (which merges), `replace` clears any keys not
    * present in `keyValueObject`. Useful when you need to drop a key.
+   * The store keeps a copy, so mutating `keyValueObject` afterwards does not
+   * change the store. When the save rejects, the store keeps its previous state.
    */
   public async replace(keyValueObject: Partial<T>) {
-    const easyStore = await this.getEasyStore();
-    easyStore.data = { ...keyValueObject };
-    await easyStore.save();
+    const values = copyInPersistedForm(keyValueObject);
+    await this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      await this.commit(easyStore, values);
+    });
   }
 
   /**
-   * wipes a key value store from disk
+   * wipes a key value store from disk. When the save rejects, the store keeps
+   * its previous state.
    */
   public async wipe() {
-    const easyStore = await this.getEasyStore();
-    easyStore.data = {};
-    await easyStore.save();
+    await this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      await this.commit(easyStore, {});
+    });
   }
 
   public async cleanUpEphemeral() {