@marianmeres/ownsuite 1.0.3 → 2.0.0

package/dist/domains/base.d.ts

@@ -2,9 +2,10 @@
  * @module domains/base
  *
  * Base domain manager. Provides reactive state, state-machine transitions,
- * optimistic update pattern, and event emission. Mirrors the shape of
- * `@marianmeres/ecsuite`'s `BaseDomainManager` so consumers already familiar
- * with ecsuite can read/subscribe to ownsuite domains identically.
+ * optimistic update pattern, mutation serialization, abort-supersede reads,
+ * and event emission. Mirrors the shape of `@marianmeres/ecsuite`'s
+ * `BaseDomainManager` so consumers already familiar with ecsuite can
+ * read/subscribe to ownsuite domains identically.
  */
 import { type Clog } from "@marianmeres/clog";
 import { type StoreLike } from "@marianmeres/store";
@@ -25,6 +26,7 @@ export interface BaseDomainOptions {
  * @typeParam TAdapter - The adapter interface type for server communication.
  */
 export declare abstract class BaseDomainManager<TData, TAdapter> {
+    #private;
     protected readonly store: StoreLike<DomainStateWrapper<TData>>;
     protected readonly pubsub: PubSub;
     protected readonly domainName: DomainName;
@@ -36,9 +38,17 @@ export declare abstract class BaseDomainManager<TData, TAdapter> {
     get subscribe(): StoreLike<DomainStateWrapper<TData>>["subscribe"];
     /** Get current state synchronously. */
     get(): DomainStateWrapper<TData>;
+    /** True after `destroy()` has been called. */
+    get isDestroyed(): boolean;
     setAdapter(adapter: TAdapter): void;
     getAdapter(): TAdapter | null;
+    /**
+     * Merge `ctx` into the current context. Keys not present in `ctx` are
+     * preserved. To replace the context entirely use `replaceContext`.
+     */
     setContext(context: OwnsuiteContext): void;
+    /** Replace the context object entirely (no merge with existing). */
+    replaceContext(context: OwnsuiteContext): void;
     getContext(): OwnsuiteContext;
     /** Transition to a new state. */
     protected setState(state: DomainState): void;
@@ -51,14 +61,60 @@ export declare abstract class BaseDomainManager<TData, TAdapter> {
     /** Emit an event via pubsub. */
     protected emit(event: OwnsuiteEvent): void;
     /**
-     * Execute an async operation with the optimistic-update pattern:
-     *   1. capture current data for rollback
-     *   2. apply optimistic update immediately
-     *   3. flip to "syncing"
-     *   4. on success: mark synced, call onSuccess
-     *   5. on error: restore previous data, set error, call onError
+     * Create a new AbortController registered with this manager. `destroy()`
+     * and `reset()` abort all active controllers. Call `releaseController`
+     * when the operation is done (success or failure) to let the controller
+     * be garbage-collected.
+     */
+    protected newController(): AbortController;
+    /** Stop tracking a controller. Call after the associated op completes. */
+    protected releaseController(ctrl: AbortController): void;
+    /** Abort every active controller (reads, mutations, other). */
+    protected abortAll(reason?: string): void;
+    /**
+     * Serialize mutations. Each call queues behind any in-flight mutation on
+     * this manager. Rejections are swallowed on the chain so subsequent
+     * callers always proceed (their own fn can still throw/reject and the
+     * caller sees it).
+     */
+    protected serializeMutation<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Run a read with abort-supersede semantics. Calling a second read
+     * aborts the first (its signal flips to aborted before/after the
+     * adapter resolves). The callback receives the signal and should check
+     * `signal.aborted` after any async step to skip state writes that would
+     * overwrite a fresher response.
      */
-    protected withOptimisticUpdate<T>(operation: string, optimisticUpdate: () => void, serverSync: () => Promise<T>, onSuccess?: (result: T) => void, onError?: (error: DomainError) => void): Promise<void>;
+    protected serializeRead(fn: (signal: AbortSignal) => Promise<void>): Promise<void>;
+    /**
+     * Execute an async mutation with the optimistic-update pattern:
+     *   1. apply optimistic update immediately
+     *   2. flip to "syncing"
+     *   3. on success: mark synced, call onSuccess
+     *   4. on error: call onError for caller-driven rollback, then set error
+     *
+     * Callers provide both the optimistic mutation and its inverse (via
+     * `onError`). The inverse runs against the *live* store, which matters
+     * when a refresh landed between the optimistic write and the failure.
+     *
+     * A snapshot is captured via `safeClone` and passed to `onError` for
+     * callers that prefer a whole-data restore over per-change inversion.
+     */
+    protected withOptimisticUpdate<T>(operation: string, optimisticUpdate: () => void, serverSync: () => Promise<T>, onSuccess?: (result: T) => void, onError?: (error: DomainError, snapshot: TData | null) => void): Promise<void>;
     abstract initialize(): Promise<void>;
+    /**
+     * Reset to `initializing` state. Aborts any in-flight reads/mutations
+     * (their completions become no-ops once they observe `signal.aborted`),
+     * clears cached data, and emits `domain:state:changed`.
+     */
     reset(): void;
+    /**
+     * Dispose of this manager: abort in-flight ops, drop the adapter
+     * reference, and mark destroyed. Subsequent method calls are a best-
+     * effort no-op (they observe aborted controllers and return early).
+     *
+     * Note: the shared pubsub is NOT cleared — other consumers may still
+     * hold subscriptions against it. `Ownsuite.destroy()` owns that.
+     */
+    destroy(): void;
 }

package/dist/domains/base.js

@@ -2,13 +2,35 @@
  * @module domains/base
  *
  * Base domain manager. Provides reactive state, state-machine transitions,
- * optimistic update pattern, and event emission. Mirrors the shape of
- * `@marianmeres/ecsuite`'s `BaseDomainManager` so consumers already familiar
- * with ecsuite can read/subscribe to ownsuite domains identically.
+ * optimistic update pattern, mutation serialization, abort-supersede reads,
+ * and event emission. Mirrors the shape of `@marianmeres/ecsuite`'s
+ * `BaseDomainManager` so consumers already familiar with ecsuite can
+ * read/subscribe to ownsuite domains identically.
  */
 import { createClog } from "@marianmeres/clog";
 import { createStore } from "@marianmeres/store";
 import { createPubSub } from "@marianmeres/pubsub";
+/**
+ * Deep-clone helper with fallback. Uses `structuredClone` where available;
+ * if a payload contains non-cloneable values (functions, class instances),
+ * falls back to a JSON round-trip. A final fallback returns the original
+ * reference (preserves pre-cloning behavior rather than throwing).
+ */
+function safeClone(value) {
+    if (value === null || value === undefined)
+        return value;
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        try {
+            return JSON.parse(JSON.stringify(value));
+        }
+        catch {
+            return value;
+        }
+    }
+}
 /**
  * Abstract base class for ownsuite domain managers.
  *
@@ -22,6 +44,13 @@ export class BaseDomainManager {
     clog;
     adapter = null;
     context = {};
+    /** Mutation chain head. Each create/update/delete appends itself here. */
+    #mutationChain = Promise.resolve();
+    /** Controller for the currently-active read (initialize/refresh). */
+    #readController = null;
+    /** All active controllers created via `newController()`, for bulk abort. */
+    #activeControllers = new Set();
+    #destroyed = false;
     constructor(domainName, options = {}) {
         this.domainName = domainName;
         this.clog = createClog(`ownsuite:${domainName}`, { color: "auto" });
@@ -43,15 +72,27 @@ export class BaseDomainManager {
     get() {
         return this.store.get();
     }
+    /** True after `destroy()` has been called. */
+    get isDestroyed() {
+        return this.#destroyed;
+    }
     setAdapter(adapter) {
         this.adapter = adapter;
     }
     getAdapter() {
         return this.adapter;
     }
+    /**
+     * Merge `ctx` into the current context. Keys not present in `ctx` are
+     * preserved. To replace the context entirely use `replaceContext`.
+     */
     setContext(context) {
         this.context = { ...this.context, ...context };
     }
+    /** Replace the context object entirely (no merge with existing). */
+    replaceContext(context) {
+        this.context = { ...context };
+    }
     getContext() {
         return { ...this.context };
     }
@@ -111,15 +152,91 @@ export class BaseDomainManager {
         this.pubsub.publish(event.type, event);
     }
     /**
-     * Execute an async operation with the optimistic-update pattern:
-     *   1. capture current data for rollback
-     *   2. apply optimistic update immediately
-     *   3. flip to "syncing"
-     *   4. on success: mark synced, call onSuccess
-     *   5. on error: restore previous data, set error, call onError
+     * Create a new AbortController registered with this manager. `destroy()`
+     * and `reset()` abort all active controllers. Call `releaseController`
+     * when the operation is done (success or failure) to let the controller
+     * be garbage-collected.
+     */
+    newController() {
+        const ctrl = new AbortController();
+        this.#activeControllers.add(ctrl);
+        return ctrl;
+    }
+    /** Stop tracking a controller. Call after the associated op completes. */
+    releaseController(ctrl) {
+        this.#activeControllers.delete(ctrl);
+    }
+    /** Abort every active controller (reads, mutations, other). */
+    abortAll(reason) {
+        for (const c of this.#activeControllers) {
+            try {
+                c.abort(reason);
+            }
+            catch {
+                // ignore — abort() is idempotent in practice
+            }
+        }
+        this.#activeControllers.clear();
+        this.#readController = null;
+    }
+    /**
+     * Serialize mutations. Each call queues behind any in-flight mutation on
+     * this manager. Rejections are swallowed on the chain so subsequent
+     * callers always proceed (their own fn can still throw/reject and the
+     * caller sees it).
+     */
+    async serializeMutation(fn) {
+        const prev = this.#mutationChain;
+        // Chain tail intentionally swallows rejection — serial order only.
+        const mine = prev.then(() => fn(), () => fn());
+        this.#mutationChain = mine.then(() => undefined, () => undefined);
+        return mine;
+    }
+    /**
+     * Run a read with abort-supersede semantics. Calling a second read
+     * aborts the first (its signal flips to aborted before/after the
+     * adapter resolves). The callback receives the signal and should check
+     * `signal.aborted` after any async step to skip state writes that would
+     * overwrite a fresher response.
+     */
+    async serializeRead(fn) {
+        // Supersede: abort the previous read if any.
+        if (this.#readController) {
+            try {
+                this.#readController.abort("superseded");
+            }
+            catch {
+                // ignore
+            }
+            this.#activeControllers.delete(this.#readController);
+        }
+        const ctrl = this.newController();
+        this.#readController = ctrl;
+        try {
+            await fn(ctrl.signal);
+        }
+        finally {
+            if (this.#readController === ctrl)
+                this.#readController = null;
+            this.releaseController(ctrl);
+        }
+    }
+    /**
+     * Execute an async mutation with the optimistic-update pattern:
+     *   1. apply optimistic update immediately
+     *   2. flip to "syncing"
+     *   3. on success: mark synced, call onSuccess
+     *   4. on error: call onError for caller-driven rollback, then set error
+     *
+     * Callers provide both the optimistic mutation and its inverse (via
+     * `onError`). The inverse runs against the *live* store, which matters
+     * when a refresh landed between the optimistic write and the failure.
+     *
+     * A snapshot is captured via `safeClone` and passed to `onError` for
+     * callers that prefer a whole-data restore over per-change inversion.
      */
     async withOptimisticUpdate(operation, optimisticUpdate, serverSync, onSuccess, onError) {
-        const previousData = this.store.get().data;
+        const snapshot = safeClone(this.store.get().data);
         optimisticUpdate();
         this.setState("syncing");
         try {
@@ -128,24 +245,59 @@ export class BaseDomainManager {
             onSuccess?.(result);
         }
         catch (e) {
-            if (previousData !== null)
-                this.setData(previousData, false);
             const error = {
                 code: "SYNC_FAILED",
                 message: e instanceof Error ? e.message : "Unknown error",
                 originalError: e,
                 operation,
             };
+            if (onError) {
+                onError(error, snapshot);
+            }
+            else if (snapshot !== null) {
+                // Default rollback: restore full snapshot (pre-1.1.0 behavior).
+                this.setData(snapshot, false);
+            }
             this.setError(error);
-            onError?.(error);
         }
     }
+    /**
+     * Reset to `initializing` state. Aborts any in-flight reads/mutations
+     * (their completions become no-ops once they observe `signal.aborted`),
+     * clears cached data, and emits `domain:state:changed`.
+     */
     reset() {
+        this.abortAll("reset");
+        const prev = this.store.get().state;
         this.store.set({
             state: "initializing",
             data: null,
             error: null,
             lastSyncedAt: null,
         });
+        if (prev !== "initializing") {
+            this.emit({
+                type: "domain:state:changed",
+                domain: this.domainName,
+                timestamp: Date.now(),
+                previousState: prev,
+                newState: "initializing",
+            });
+        }
+    }
+    /**
+     * Dispose of this manager: abort in-flight ops, drop the adapter
+     * reference, and mark destroyed. Subsequent method calls are a best-
+     * effort no-op (they observe aborted controllers and return early).
+     *
+     * Note: the shared pubsub is NOT cleared — other consumers may still
+     * hold subscriptions against it. `Ownsuite.destroy()` owns that.
+     */
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        this.abortAll("destroyed");
+        this.adapter = null;
     }
 }

package/dist/domains/owned-collection.d.ts

@@ -5,6 +5,13 @@
  * any row shape `TRow` via an injected `OwnedCollectionAdapter`. All CRUD
  * operations are implicitly scoped to the authenticated subject by the
  * server — the client never sets `owner_id`.
+ *
+ * Concurrency model:
+ * - Mutations (create/update/delete) serialize through a per-manager chain.
+ * - Reads (initialize/refresh) use abort-supersede: a newer read aborts
+ *   any in-flight older read.
+ * - `onSuccess` callbacks read the live store (not a captured snapshot) so
+ *   interleaving reads do not erase each other's writes.
  */
 import type { OwnedCollectionAdapter } from "../types/adapter.js";
 import type { OwnedCollectionState } from "../types/state.js";
@@ -28,13 +35,31 @@ export declare class OwnedCollectionManager<TRow = Record<string, unknown>, TCre
     initialize(): Promise<void>;
     /** Refresh the list from server. Same as initialize but re-entrant. */
     refresh(query?: Record<string, unknown>): Promise<void>;
-    /** Fetch a single row by id; returns the row but does not update the list. */
+    /**
+     * Fetch a single row by id. Does NOT update the list and does NOT
+     * transition the domain to `error` on failure — a 404 for an un-owned
+     * row or a network blip on a read shouldn't invalidate a healthy list
+     * view. Emits `own:row:fetched` on success.
+     *
+     * Returns `null` on any failure (including missing adapter). Callers
+     * that need error detail should wrap this method and inspect the thrown
+     * adapter error themselves.
+     */
     getOne(id: string): Promise<TRow | null>;
-    /** Create a new row. Optimistically prepends to the list. */
+    /** Create a new row. Server assigns the id; on success, prepends to the list. */
     create(data: TCreate): Promise<TRow | null>;
-    /** Update a row. Optimistically merges into the list. */
+    /**
+     * Update a row. Optimistically merges `data` into the existing row; on
+     * server failure reverts that single row to its pre-call value (without
+     * clobbering any interleaved refresh or other mutations).
+     *
+     * If `id` is not in the current list (e.g., filtered out by an active
+     * query or not owned), the optimistic step is a no-op AND the successful
+     * server response is NOT inserted — call `refresh()` if you want the
+     * row to appear. Emits `own:row:updated` on success regardless.
+     */
     update(id: string, data: TUpdate): Promise<TRow | null>;
-    /** Delete a row. Optimistically removes from the list. */
+    /** Delete a row. Optimistically removes from the list; re-inserts on failure. */
     delete(id: string): Promise<boolean>;
     /** Snapshot of current rows (empty array if not loaded). */
     getRows(): TRow[];