@hitslop/svelte 0.2.0 → 0.3.0

package/README.md

@@ -37,7 +37,34 @@ validates initial, loaded, externally changed, and outgoing values using the
 TypeBox interpreter; it does not coerce, insert defaults, strip unknown fields,
 or write browser storage.
 
-See the [Svelte authoring examples](https://github.com/hitslop/hitslop/tree/main/examples/slops).
+Once loaded, JSON edits save after 150 ms without another change, or after one
+second of continuous editing. Only one write runs at a time; edits during a write
+coalesce into the newest follow-up snapshot. `await document.flush()` captures
+current state immediately, bypasses the delay, and waits for pending writes.
+Concurrent flushes share the same drain. Schema validation runs at I/O boundaries,
+so invalid edits remain in memory and are never written.
+
+`isDirty` stays true while changes are waiting, saving, or failed; `isSaving` is
+true during a write. `error` contains the display message and `errorCode` contains
+the `SlopError` code when available, including `validation_failed`,
+`revision_conflict`, and `storage_error`. A failed save retains the latest edits.
+Call `flush()` to retry, or make a new edit to resume automatic saving. Repeated
+observations of an identical value do not retry a failed save.
+
+External file changes load while the store is clean. While dirty, local edits
+win: a revision conflict reads the new revision and retries the latest full
+local snapshot once. This does not merge another writer's fields. Another
+conflict stops saving and surfaces an error. After loading, explicit `reload()`
+discards edits made before the call and adopts the file; edits made during the
+read survive. Retrying a failed initial load also preserves local edits.
+
+Call `destroy()` on teardown to stop observation and immediately drain a detached
+final snapshot. It is synchronous and safe to call twice. Pending or failed saves
+stay registered with the runtime flush barrier until a flush succeeds. For a
+user-initiated teardown where errors should prevent navigation, await `flush()`
+before removing the component. A destroyed store cannot reload or resume editing.
+
+See the [Svelte authoring examples](https://github.com/hitslop/hitslop/tree/master/examples/slops).
 
 MIT © 2026 hitSlop contributors.
 

package/dist/json-store.svelte.d.ts

@@ -10,6 +10,7 @@ export declare class JsonStore<S extends TSchema> {
     isDirty: boolean;
     isSaving: boolean;
     error: string | null;
+    errorCode: "invalid_request" | "unsupported" | "revision_conflict" | "validation_failed" | "storage_error" | "limit_exceeded" | "closed" | null;
     revision: string | null;
     lastChangeSource: string;
     private persister;
@@ -17,10 +18,15 @@ export declare class JsonStore<S extends TSchema> {
     private unwatch;
     private stopEffect;
     private unregisterFlush;
+    private destroyed;
+    private finalSnapshot;
+    private finalError;
     constructor(options: JsonStoreOptions<S>);
     reload(): Promise<void>;
     destroy(): void;
     flush(): Promise<void>;
+    private getLocal;
+    private setError;
     private parse;
 }
 export declare function jsonStore<S extends TSchema>(options: JsonStoreOptions<S>): JsonStore<S>;

package/dist/json-store.svelte.js

@@ -1,13 +1,17 @@
-import { slop } from "@hitslop/runtime";
+import { slop, SlopError } from "@hitslop/runtime";
 import { JsonPersister, registerFlush } from "@hitslop/runtime/adapter";
 import { untrack } from "svelte";
 import { validate } from "@hitslop/schema/validation";
 import { assertJSON } from "@hitslop/schema/json";
 const snapshot = (value) => {
-    const detached = $state.snapshot(value);
-    assertJSON(detached);
-    const json = JSON.stringify(detached);
-    return { json, value: JSON.parse(json) };
+    try {
+        const detached = $state.snapshot(value);
+        assertJSON(detached);
+        return { json: JSON.stringify(detached), value: detached };
+    }
+    catch (error) {
+        throw new SlopError("validation_failed", error instanceof Error ? error.message : String(error));
+    }
 };
 export class JsonStore {
     current = $state();
@@ -16,6 +20,7 @@ export class JsonStore {
     isDirty = $state(false);
     isSaving = $state(false);
     error = $state(null);
+    errorCode = $state(null);
     revision = $state(null);
     lastChangeSource = $state("package");
     persister;
@@ -23,6 +28,9 @@ export class JsonStore {
     unwatch = null;
     stopEffect = null;
     unregisterFlush = null;
+    destroyed = false;
+    finalSnapshot = null;
+    finalError = null;
     constructor(options) {
         this.schema = options.schema;
         const fallbackSnapshot = snapshot(this.parse(options.initial));
@@ -38,13 +46,18 @@ export class JsonStore {
                     const result = await slop.json.read();
                     return { ...result, value: this.parse(result.value) };
                 },
-                write: (value, revision) => slop.json.write(this.parse(value), revision),
+                write: (value, revision) => slop.json.write(this.parse(value, false), revision),
+            },
+            getLocal: () => this.getLocal(),
+            onAdopt: (value, source) => {
+                this.current = value;
+                this.lastChangeSource = source;
+                if (this.destroyed)
+                    this.finalSnapshot = snapshot(value);
             },
-            getLocal: () => snapshot(this.parse(this.current)),
-            onAdopt: (value, source) => { this.current = value; this.lastChangeSource = source; },
             onRevision: (revision) => { this.revision = revision; },
             onSource: (source) => { this.lastChangeSource = source; },
-            onError: (message) => { this.error = message; },
+            onError: (error) => this.setError(error),
             onStatus: ({ isDirty, isSaving }) => { this.isDirty = isDirty; this.isSaving = isSaving; },
         });
         // Snapshotting reads the complete proxy tree, so one effect run observes all
@@ -54,10 +67,10 @@ export class JsonStore {
             $effect(() => {
                 let local;
                 try {
-                    local = snapshot(this.parse(this.current));
+                    local = snapshot(this.current);
                 }
                 catch (error) {
-                    untrack(() => { this.error = error instanceof Error ? error.message : String(error); });
+                    untrack(() => this.persister.localInvalid(error));
                     return;
                 }
                 untrack(() => this.persister.localChanged(local.json, local.value));
@@ -68,36 +81,77 @@ export class JsonStore {
         this.unwatch = slop.json.onChange((event) => this.persister.externalChanged(event.revision));
     }
     async reload() {
+        if (this.destroyed)
+            throw new SlopError("closed", "JSON store is destroyed");
         this.isLoading = true;
         try {
             await this.persister.reload();
             this.isReady = true;
         }
         catch (error) {
-            this.error = error instanceof Error ? error.message : String(error);
+            this.setError(error);
         }
         finally {
             this.isLoading = false;
         }
     }
     destroy() {
-        if (!this.isLoading)
-            void this.flush().catch(() => undefined);
-        this.unregisterFlush?.();
-        this.unregisterFlush = null;
+        if (this.destroyed)
+            return;
+        try {
+            this.finalSnapshot = snapshot(this.current);
+        }
+        catch (error) {
+            this.finalError = error;
+        }
+        this.destroyed = true;
         this.unwatch?.();
         this.unwatch = null;
         this.stopEffect?.();
         this.stopEffect = null;
+        // Keep failed writes registered so the host barrier can report/retry them.
+        void this.flush().catch(() => undefined);
     }
     async flush() {
-        const local = snapshot(this.parse(this.current));
-        this.persister.localChanged(local.json, local.value);
-        await this.persister.flush();
+        try {
+            let local;
+            try {
+                local = this.getLocal();
+            }
+            catch (error) {
+                this.persister.localInvalid(error);
+                throw error;
+            }
+            this.persister.localChanged(local.json, local.value);
+            await this.persister.flush();
+            if (this.destroyed) {
+                this.unregisterFlush?.();
+                this.unregisterFlush = null;
+            }
+        }
+        catch (error) {
+            this.setError(error);
+            throw error;
+        }
+    }
+    getLocal() {
+        if (this.finalError)
+            throw this.finalError;
+        return this.finalSnapshot ?? snapshot(this.current);
+    }
+    setError(error) {
+        this.error = error == null ? null : error instanceof Error ? error.message : String(error);
+        this.errorCode = error instanceof SlopError ? error.code : null;
     }
-    parse(value) {
-        assertJSON(value);
-        return validate(this.schema, value);
+    parse(value, checkJSON = true) {
+        try {
+            if (checkJSON)
+                assertJSON(value);
+            return validate(this.schema, value);
+        }
+        catch (error) {
+            throw new SlopError("validation_failed", error instanceof Error ? error.message : String(error));
+        }
     }
 }
 export function jsonStore(options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hitslop/svelte",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Svelte 5 state adapters for the hitSlop runtime.",
   "license": "MIT",
   "repository": {
@@ -38,8 +38,8 @@
     "test": "bun run --cwd ../runtime build && bun test"
   },
   "dependencies": {
-    "@hitslop/runtime": "^0.2.0",
-    "@hitslop/schema": "^0.2.0",
+    "@hitslop/runtime": "^0.3.0",
+    "@hitslop/schema": "^0.3.0",
     "typebox": "^1.3.26"
   },
   "peerDependencies": {