@hitslop/runtime 0.2.0 → 0.3.0

package/README.md

@@ -14,7 +14,16 @@ ready();
 Use `@hitslop/runtime/adapter` only when implementing a framework adapter; it
 exports the shared JSON persister and safe media helpers.
 
-Documentation: [Architecture](https://github.com/hitslop/hitslop/blob/main/docs/architecture.md) ·
-[Storage](https://github.com/hitslop/hitslop/blob/main/docs/storage.md)
+`JsonPersister` batches idle writes for 150 ms, with a one-second maximum wait.
+Adapters supply detached snapshots and validate values at their I/O boundaries.
+`flush()` bypasses scheduling and drains pending writes; errors retain their
+original identity and code. Register adapter flushers with `registerFlush` so
+the host can await state that has not reached the bridge yet. Keep that
+registration until teardown's final save succeeds.
+The persister's `onError` callback receives `Error | null`; derive display text
+from the error's `message` rather than replacing the error object.
+
+Documentation: [Architecture](https://github.com/hitslop/hitslop/blob/master/docs/architecture.md) ·
+[Storage](https://github.com/hitslop/hitslop/blob/master/docs/storage.md)
 
 MIT © 2026 hitSlop contributors.

package/dist/json-persister.d.ts

@@ -3,6 +3,10 @@ export type JsonSnapshot<T> = {
     value: T;
 };
 type Source = "package" | "app" | "external";
+type Scheduler = {
+    setTimeout: (callback: () => void, delay: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+};
 type Options<T> = {
     fallback: JsonSnapshot<T>;
     io: {
@@ -22,11 +26,12 @@ type Options<T> = {
     onAdopt: (value: T, source: Source) => void;
     onRevision: (revision: string | null) => void;
     onSource: (source: Source) => void;
-    onError: (message: string | null) => void;
+    onError: (error: Error | null) => void;
     onStatus?: (state: {
         isDirty: boolean;
         isSaving: boolean;
     }) => void;
+    scheduler?: Scheduler;
 };
 export declare class JsonPersister<T> {
     private options;
@@ -40,16 +45,27 @@ export declare class JsonPersister<T> {
     private draining;
     private operations;
     private failure;
+    private invalid;
+    private lastLocalJson;
+    private flushing;
+    private debounce;
+    private maximumWait;
+    private readonly scheduler;
     private status;
     flush(): Promise<void>;
+    private flushNow;
     constructor(options: Options<T>);
     localChanged(json: string, value: T): void;
+    /** An unrepresentable local value must block older queued snapshots too. */
+    localInvalid(error: Error): void;
     reload(): Promise<void>;
     externalChanged(eventRevision?: string | null): void;
+    private cancelTimers;
+    private scheduleDrain;
     private requestDrain;
     private drainLoop;
     private adopt;
     private schedule;
-    private message;
+    private asError;
 }
 export {};

package/dist/json-persister.js

@@ -10,16 +10,31 @@ export class JsonPersister {
     draining = null;
     operations = Promise.resolve(undefined);
     failure = null;
-    status() { this.options.onStatus?.({ isDirty: this.pending !== null || this.writing, isSaving: this.writing }); }
-    async flush() {
+    invalid = null;
+    lastLocalJson;
+    flushing = null;
+    debounce;
+    maximumWait;
+    scheduler;
+    status() { this.options.onStatus?.({ isDirty: this.pending !== null || this.writing || this.invalid !== null, isSaving: this.writing }); }
+    flush() {
+        if (this.flushing)
+            return this.flushing;
+        this.cancelTimers();
+        this.flushing = this.flushNow().finally(() => { this.flushing = null; });
+        return this.flushing;
+    }
+    async flushNow() {
         const retry = this.stopped;
         await this.operations;
+        if (this.invalid)
+            throw this.invalid;
         if (this.stopped && !retry && this.failure)
             throw this.failure;
         if (!this.loaded) {
             if (!this.pending)
                 return;
-            throw new Error("Document data has not loaded");
+            throw this.failure ?? new Error("Document data has not loaded");
         }
         this.stopped = false;
         this.failure = null;
@@ -32,13 +47,24 @@ export class JsonPersister {
     constructor(options) {
         this.options = options;
         this.lastPersistedJson = options.fallback.json;
+        this.lastLocalJson = options.fallback.json;
+        this.scheduler = options.scheduler ?? {
+            setTimeout: (callback, delay) => setTimeout(callback, delay),
+            clearTimeout: handle => clearTimeout(handle),
+        };
     }
     localChanged(json, value) {
+        if (!this.invalid && json === this.lastLocalJson)
+            return;
         this.localVersion += 1;
+        this.lastLocalJson = json;
+        this.invalid = null;
+        this.failure = null;
         // A write already in flight may change what is persisted, so a reversion to
         // the previously persisted value still has to remain queued until it lands.
         if (!this.writing && json === this.lastPersistedJson) {
             this.pending = null;
+            this.cancelTimers();
             this.stopped = false;
             this.options.onError(null);
             this.status();
@@ -46,8 +72,20 @@ export class JsonPersister {
         }
         this.pending = { json, value };
         this.stopped = false;
+        this.options.onError(null);
+        this.status();
+        this.scheduleDrain();
+    }
+    /** An unrepresentable local value must block older queued snapshots too. */
+    localInvalid(error) {
+        this.localVersion += 1;
+        this.invalid = error;
+        this.failure = error;
+        this.pending = null;
+        this.stopped = true;
+        this.cancelTimers();
+        this.options.onError(error);
         this.status();
-        this.requestDrain();
     }
     reload() {
         const wasLoaded = this.loaded;
@@ -57,6 +95,9 @@ export class JsonPersister {
         if (wasLoaded) {
             this.pending = null;
             this.stopped = false;
+            this.invalid = null;
+            this.failure = null;
+            this.cancelTimers();
         }
         return this.schedule(async () => {
             try {
@@ -68,25 +109,31 @@ export class JsonPersister {
                 this.revision = result.revision;
                 this.lastPersistedJson = persistedJson;
                 this.options.onRevision(result.revision);
-                const local = this.options.getLocal();
                 const changedDuringReload = this.localVersion !== requestedAtVersion;
+                const local = !wasLoaded || changedDuringReload ? this.options.getLocal() : { json: persistedJson, value: result.value };
                 const localWins = wasLoaded
                     ? changedDuringReload && local.json !== persistedJson
                     : local.json !== this.options.fallback.json;
+                // A write that was already running can fail after reload was requested.
+                // A successful read still recovers the store from that stopped state.
+                this.stopped = false;
+                this.failure = null;
+                this.invalid = null;
                 if (localWins) {
                     this.pending = local;
-                    this.requestDrain();
+                    this.scheduleDrain();
                 }
                 else {
                     this.pending = null;
+                    this.cancelTimers();
                     this.adopt(result.value, result.revision, wasLoaded ? "external" : "package");
                 }
                 this.options.onError(null);
                 this.status();
             }
             catch (error) {
-                const message = this.message(error);
-                this.options.onError(message);
+                this.failure = this.asError(error);
+                this.options.onError(this.failure);
                 throw error;
             }
         });
@@ -108,10 +155,30 @@ export class JsonPersister {
                 this.options.onError(null);
             }
             catch (error) {
-                this.options.onError(this.message(error));
+                this.options.onError(this.asError(error));
             }
         });
     }
+    cancelTimers() {
+        if (this.debounce !== undefined)
+            this.scheduler.clearTimeout(this.debounce);
+        if (this.maximumWait !== undefined)
+            this.scheduler.clearTimeout(this.maximumWait);
+        this.debounce = this.maximumWait = undefined;
+    }
+    scheduleDrain() {
+        if (!this.loaded || this.stopped || !this.pending || this.draining)
+            return;
+        if (this.flushing) {
+            this.requestDrain();
+            return;
+        }
+        const drain = () => { this.cancelTimers(); this.requestDrain(); };
+        if (this.debounce !== undefined)
+            this.scheduler.clearTimeout(this.debounce);
+        this.debounce = this.scheduler.setTimeout(drain, 150);
+        this.maximumWait ??= this.scheduler.setTimeout(drain, 1_000);
+    }
     requestDrain() {
         if (this.draining || !this.loaded || this.stopped || !this.pending)
             return;
@@ -142,8 +209,10 @@ export class JsonPersister {
                     this.lastPersistedJson = snapshot.json;
                     this.options.onRevision(result.revision);
                     this.options.onSource("app");
-                    this.options.onError(null);
-                    this.failure = null;
+                    if (!this.invalid) {
+                        this.options.onError(null);
+                        this.failure = null;
+                    }
                     conflicts = 0;
                 }
                 catch (error) {
@@ -159,8 +228,8 @@ export class JsonPersister {
                         catch (readError) {
                             this.pending ??= snapshot;
                             this.stopped = true;
-                            this.failure = new Error(this.message(readError));
-                            this.options.onError(this.message(readError));
+                            this.failure = this.asError(readError);
+                            this.options.onError(this.failure);
                             continue;
                         }
                     }
@@ -168,8 +237,8 @@ export class JsonPersister {
                     // and re-arms persistence without losing any fields.
                     this.pending ??= snapshot;
                     this.stopped = true;
-                    this.failure = new Error(this.message(error));
-                    this.options.onError(this.message(error));
+                    this.failure = this.asError(error);
+                    this.options.onError(this.failure);
                 }
             }
         }
@@ -181,6 +250,7 @@ export class JsonPersister {
     adopt(value, revision, source) {
         this.revision = revision;
         this.lastPersistedJson = JSON.stringify(value);
+        this.lastLocalJson = this.lastPersistedJson;
         this.options.onRevision(revision);
         this.options.onAdopt(value, source);
     }
@@ -189,7 +259,7 @@ export class JsonPersister {
         this.operations = scheduled.catch(() => undefined);
         return scheduled;
     }
-    message(error) {
-        return error instanceof Error ? error.message : String(error);
+    asError(error) {
+        return error instanceof Error ? error : new Error(String(error));
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hitslop/runtime",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Framework-neutral browser bridge for hitSlop documents.",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/hitslop/hitslop.git", "directory": "packages/runtime" },
@@ -20,6 +20,6 @@
     "check": "tsc -p tsconfig.json",
     "test": "bun test"
   },
-  "dependencies": { "@hitslop/schema": "^0.2.0" },
+  "dependencies": { "@hitslop/schema": "^0.3.0" },
   "devDependencies": { "typescript": "^7.0.2" }
 }