@marianmeres/ownsuite 1.0.2 → 2.0.0

package/dist/domains/owned-collection.js

@@ -5,13 +5,20 @@
  * 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 { BaseDomainManager } from "./base.js";
 const defaultGetRowId = (row) => {
     const r = row;
     const id = r.model_id ?? r.id;
-    if (typeof id !== "string") {
-        throw new Error("OwnedCollectionManager: row has no string `model_id` or `id`; " +
+    if (typeof id !== "string" || id === "") {
+        throw new Error("OwnedCollectionManager: row has no non-empty string `model_id` or `id`; " +
             "pass a custom `getRowId` in options.");
     }
     return id;
@@ -31,64 +38,98 @@ export class OwnedCollectionManager extends BaseDomainManager {
         if (options.adapter)
             this.adapter = options.adapter;
     }
+    /** Build the per-op adapter context with the injected signal. */
+    #ctx(signal) {
+        return { ...this.context, signal };
+    }
+    /** Current data or an empty shell. */
+    #live() {
+        return this.store.get().data ?? { rows: [], meta: {} };
+    }
     /** Initialize by fetching the list from the server. */
     async initialize() {
+        if (this.isDestroyed)
+            return;
         if (!this.adapter) {
             this.setState("ready");
             return;
         }
-        this.setState("syncing");
-        try {
-            const res = await this.adapter.list(this.context);
-            this.setData({ rows: res.data, meta: res.meta });
-            this.markSynced();
-            this.emit({
-                type: "own:list:fetched",
-                domain: this.domainName,
-                timestamp: Date.now(),
-                count: res.data.length,
-            });
-        }
-        catch (e) {
-            this.setError({
-                code: "FETCH_FAILED",
-                message: e instanceof Error ? e.message : "Failed to fetch list",
-                originalError: e,
-                operation: "initialize",
-            });
-        }
+        await this.serializeRead(async (signal) => {
+            this.setState("syncing");
+            try {
+                const res = await this.adapter.list(this.#ctx(signal));
+                if (signal.aborted)
+                    return;
+                this.setData({ rows: res.data, meta: res.meta });
+                this.markSynced();
+                this.emit({
+                    type: "own:list:fetched",
+                    domain: this.domainName,
+                    timestamp: Date.now(),
+                    count: res.data.length,
+                });
+            }
+            catch (e) {
+                if (signal.aborted)
+                    return;
+                this.setError({
+                    code: "FETCH_FAILED",
+                    message: e instanceof Error ? e.message : "Failed to fetch list",
+                    originalError: e,
+                    operation: "initialize",
+                });
+            }
+        });
     }
     /** Refresh the list from server. Same as initialize but re-entrant. */
     async refresh(query) {
-        if (!this.adapter)
+        if (this.isDestroyed || !this.adapter)
             return;
-        this.setState("syncing");
-        try {
-            const res = await this.adapter.list(this.context, query);
-            this.setData({ rows: res.data, meta: res.meta });
-            this.markSynced();
-            this.emit({
-                type: "own:list:fetched",
-                domain: this.domainName,
-                timestamp: Date.now(),
-                count: res.data.length,
-            });
-        }
-        catch (e) {
-            this.setError({
-                code: "FETCH_FAILED",
-                message: e instanceof Error ? e.message : "Failed to refresh list",
-                originalError: e,
-                operation: "refresh",
-            });
-        }
+        await this.serializeRead(async (signal) => {
+            this.setState("syncing");
+            try {
+                const res = await this.adapter.list(this.#ctx(signal), query);
+                if (signal.aborted)
+                    return;
+                this.setData({ rows: res.data, meta: res.meta });
+                this.markSynced();
+                this.emit({
+                    type: "own:list:fetched",
+                    domain: this.domainName,
+                    timestamp: Date.now(),
+                    count: res.data.length,
+                });
+            }
+            catch (e) {
+                if (signal.aborted)
+                    return;
+                this.setError({
+                    code: "FETCH_FAILED",
+                    message: e instanceof Error ? e.message : "Failed to refresh list",
+                    originalError: e,
+                    operation: "refresh",
+                });
+            }
+        });
     }
-    /** 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.
+     */
     async getOne(id) {
-        if (!this.adapter)
+        if (this.isDestroyed || !this.adapter)
             return null;
+        const ctrl = this.newController();
         try {
-            const res = await this.adapter.getOne(id, this.context);
+            const res = await this.adapter.getOne(id, this.#ctx(ctrl.signal));
+            if (ctrl.signal.aborted)
+                return null;
             this.emit({
                 type: "own:row:fetched",
                 domain: this.domainName,
@@ -98,97 +139,176 @@ export class OwnedCollectionManager extends BaseDomainManager {
             return res.data;
         }
         catch (e) {
-            this.setError({
-                code: "FETCH_FAILED",
-                message: e instanceof Error ? e.message : "Failed to fetch row",
-                originalError: e,
-                operation: "getOne",
+            if (ctrl.signal.aborted)
+                return null;
+            this.clog.debug("getOne failed", {
+                id,
+                error: e instanceof Error ? e.message : e,
             });
             return null;
         }
+        finally {
+            this.releaseController(ctrl);
+        }
     }
-    /** Create a new row. Optimistically prepends to the list. */
+    /** Create a new row. Server assigns the id; on success, prepends to the list. */
     async create(data) {
-        if (!this.adapter)
+        if (this.isDestroyed || !this.adapter)
             return null;
-        const current = this.store.get().data ?? { rows: [], meta: {} };
-        let result = null;
-        await this.withOptimisticUpdate("create", () => {
-            // No optimistic row insertion: we don't know the server-assigned id.
-            // Just keep the list unchanged; flip to syncing is handled for us.
-        }, async () => {
-            const res = await this.adapter.create(data, this.context);
-            return res.data;
-        }, (serverRow) => {
-            result = serverRow;
-            this.setData({
-                rows: [serverRow, ...current.rows],
-                meta: current.meta,
-            });
-            this.emit({
-                type: "own:row:created",
-                domain: this.domainName,
-                timestamp: Date.now(),
-                rowId: this.#getRowId(serverRow),
-            });
+        return this.serializeMutation(async () => {
+            let result = null;
+            await this.withOptimisticUpdate("create", () => {
+                // No optimistic insertion — no client-assigned id. `syncing`
+                // transition still happens so subscribers see the pending state.
+            }, async () => {
+                const ctrl = this.newController();
+                try {
+                    const res = await this.adapter.create(data, this.#ctx(ctrl.signal));
+                    return res.data;
+                }
+                finally {
+                    this.releaseController(ctrl);
+                }
+            }, (serverRow) => {
+                result = serverRow;
+                // Read live state (not snapshot) so a concurrent delete/refresh is preserved.
+                const live = this.#live();
+                this.setData({
+                    rows: [serverRow, ...live.rows],
+                    meta: live.meta,
+                });
+                this.emit({
+                    type: "own:row:created",
+                    domain: this.domainName,
+                    timestamp: Date.now(),
+                    rowId: this.#getRowId(serverRow),
+                });
+            }, 
+            // No onError: create has no optimistic state to revert; default
+            // rollback (restore snapshot) also not needed since we never mutated.
+            () => { });
+            return result;
         });
-        return result;
     }
-    /** 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.
+     */
     async update(id, data) {
-        if (!this.adapter)
+        if (this.isDestroyed || !this.adapter)
             return null;
-        const current = this.store.get().data ?? { rows: [], meta: {} };
-        const idx = current.rows.findIndex((r) => this.#getRowId(r) === id);
-        let result = null;
-        await this.withOptimisticUpdate("update", () => {
-            if (idx === -1)
-                return;
-            const optimistic = { ...current.rows[idx], ...data };
-            const rows = current.rows.slice();
-            rows[idx] = optimistic;
-            this.setData({ rows, meta: current.meta }, false);
-        }, async () => {
-            const res = await this.adapter.update(id, data, this.context);
-            return res.data;
-        }, (serverRow) => {
-            result = serverRow;
-            const rows = idx === -1
-                ? [serverRow, ...current.rows]
-                : current.rows.map((r, i) => (i === idx ? serverRow : r));
-            this.setData({ rows, meta: current.meta });
-            this.emit({
-                type: "own:row:updated",
-                domain: this.domainName,
-                timestamp: Date.now(),
-                rowId: id,
+        return this.serializeMutation(async () => {
+            const startData = this.#live();
+            const startIdx = startData.rows.findIndex((r) => this.#getRowId(r) === id);
+            const originalRow = startIdx !== -1 ? startData.rows[startIdx] : null;
+            let result = null;
+            await this.withOptimisticUpdate("update", () => {
+                if (originalRow === null)
+                    return;
+                const optimistic = {
+                    ...originalRow,
+                    ...data,
+                };
+                const live = this.#live();
+                const liveIdx = live.rows.findIndex((r) => this.#getRowId(r) === id);
+                if (liveIdx === -1)
+                    return;
+                const rows = live.rows.slice();
+                rows[liveIdx] = optimistic;
+                this.setData({ rows, meta: live.meta }, false);
+            }, async () => {
+                const ctrl = this.newController();
+                try {
+                    const res = await this.adapter.update(id, data, this.#ctx(ctrl.signal));
+                    return res.data;
+                }
+                finally {
+                    this.releaseController(ctrl);
+                }
+            }, (serverRow) => {
+                result = serverRow;
+                const live = this.#live();
+                const liveIdx = live.rows.findIndex((r) => this.#getRowId(r) === id);
+                if (liveIdx !== -1) {
+                    const rows = live.rows.map((r, i) => (i === liveIdx ? serverRow : r));
+                    this.setData({ rows, meta: live.meta });
+                }
+                // If liveIdx === -1 the row is not in the current list; do NOT
+                // insert (avoids phantom rows when filtered/unknown).
+                this.emit({
+                    type: "own:row:updated",
+                    domain: this.domainName,
+                    timestamp: Date.now(),
+                    rowId: id,
+                });
+            }, (_error, _snapshot) => {
+                // Per-row rollback: restore the one row we mutated (or nothing).
+                if (originalRow === null)
+                    return;
+                const live = this.#live();
+                const liveIdx = live.rows.findIndex((r) => this.#getRowId(r) === id);
+                if (liveIdx === -1)
+                    return; // row was removed by another op; don't re-add
+                const rows = live.rows.slice();
+                rows[liveIdx] = originalRow;
+                this.setData({ rows, meta: live.meta }, false);
             });
+            return result;
         });
-        return result;
     }
-    /** Delete a row. Optimistically removes from the list. */
+    /** Delete a row. Optimistically removes from the list; re-inserts on failure. */
     async delete(id) {
-        if (!this.adapter)
+        if (this.isDestroyed || !this.adapter)
             return false;
-        const current = this.store.get().data ?? { rows: [], meta: {} };
-        let ok = false;
-        await this.withOptimisticUpdate("delete", () => {
-            this.setData({
-                rows: current.rows.filter((r) => this.#getRowId(r) !== id),
-                meta: current.meta,
-            }, false);
-        }, async () => {
-            return await this.adapter.delete(id, this.context);
-        }, (serverOk) => {
-            ok = serverOk;
-            this.emit({
-                type: "own:row:deleted",
-                domain: this.domainName,
-                timestamp: Date.now(),
-                rowId: id,
+        return this.serializeMutation(async () => {
+            const startData = this.#live();
+            const startIdx = startData.rows.findIndex((r) => this.#getRowId(r) === id);
+            const originalRow = startIdx !== -1 ? startData.rows[startIdx] : null;
+            let ok = false;
+            await this.withOptimisticUpdate("delete", () => {
+                const live = this.#live();
+                this.setData({
+                    rows: live.rows.filter((r) => this.#getRowId(r) !== id),
+                    meta: live.meta,
+                }, false);
+            }, async () => {
+                const ctrl = this.newController();
+                try {
+                    return await this.adapter.delete(id, this.#ctx(ctrl.signal));
+                }
+                finally {
+                    this.releaseController(ctrl);
+                }
+            }, (serverOk) => {
+                ok = serverOk;
+                this.emit({
+                    type: "own:row:deleted",
+                    domain: this.domainName,
+                    timestamp: Date.now(),
+                    rowId: id,
+                });
+            }, (_error, _snapshot) => {
+                // Per-row rollback: re-insert the deleted row at its original
+                // position, unless it was independently re-added by another op.
+                if (originalRow === null)
+                    return;
+                const live = this.#live();
+                if (live.rows.some((r) => this.#getRowId(r) === id))
+                    return;
+                const rows = live.rows.slice();
+                // Clamp insertion index to current list length.
+                const insertAt = Math.min(startIdx, rows.length);
+                rows.splice(insertAt < 0 ? 0 : insertAt, 0, originalRow);
+                this.setData({ rows, meta: live.meta }, false);
             });
+            return ok;
         });
-        return ok;
     }
     /** Snapshot of current rows (empty array if not loaded). */
     getRows() {

package/dist/ownsuite.d.ts

@@ -11,7 +11,7 @@
  * hook and `@marianmeres/stack-common`'s `ownsuiteOptions()` helper.
  */
 import { type Subscriber, type Unsubscriber } from "@marianmeres/pubsub";
-import type { OwnsuiteContext } from "./types/state.js";
+import type { DomainError, OwnsuiteContext } from "./types/state.js";
 import type { OwnedCollectionAdapter } from "./types/adapter.js";
 import type { OwnsuiteEventType } from "./types/events.js";
 import { OwnedCollectionManager } from "./domains/owned-collection.js";
@@ -33,6 +33,13 @@ export interface OwnsuiteConfig {
     /** Auto-initialize all registered domains on creation (default: false). */
     autoInitialize?: boolean;
 }
+/** Options for {@link Ownsuite.setContext}. */
+export interface SetContextOptions {
+    /** If true, replace the context entirely instead of merging. Default: false (merge). */
+    replace?: boolean;
+    /** If true, fire `refresh()` on every domain after the context change. Default: false. */
+    refresh?: boolean;
+}
 /**
  * Main Ownsuite class — coordinates owner-scoped domain managers.
  *
@@ -54,6 +61,8 @@ export interface OwnsuiteConfig {
 export declare class Ownsuite {
     #private;
     constructor(config?: OwnsuiteConfig);
+    /** True after `destroy()` has been called. */
+    get isDestroyed(): boolean;
     /** Register a new domain after construction. */
     registerDomain<TRow = any, TCreate = any, TUpdate = any>(name: string, cfg: OwnsuiteDomainConfig<TRow, TCreate, TUpdate>): OwnedCollectionManager<TRow, TCreate, TUpdate>;
     /** Look up a domain manager by name. Throws if unknown. */
@@ -65,11 +74,20 @@ export declare class Ownsuite {
     /**
      * Initialize all registered domains (or a subset). Runs in parallel.
      * Individual domain errors land in that domain's error state — they
-     * do not reject the overall promise.
+     * do not reject the overall promise. Use `hasErrors()` / `errors()` to
+     * inspect the result. Unknown domain names in `names` are logged and
+     * skipped.
      */
     initialize(names?: string[]): Promise<void>;
-    /** Update shared context and propagate to all domain managers. */
-    setContext(ctx: OwnsuiteContext): void;
+    /**
+     * Update shared context and propagate to every domain manager.
+     *
+     * - `options.replace: true` — replace the context wholesale (no merge).
+     * - `options.refresh: true` — fire-and-forget `refresh()` on every
+     *   domain after the context change (so stale per-subject caches don't
+     *   linger when, e.g., `subjectId` changes).
+     */
+    setContext(ctx: OwnsuiteContext, options?: SetContextOptions): void;
     getContext(): OwnsuiteContext;
     /** Subscribe to a specific event type. */
     on(type: OwnsuiteEventType, subscriber: Subscriber): Unsubscriber;
@@ -78,8 +96,22 @@ export declare class Ownsuite {
      * `{ event: string, data: OwnsuiteEvent }` — see `@marianmeres/pubsub`.
      */
     onAny(subscriber: Subscriber): Unsubscriber;
-    /** Reset all domains to initializing state. */
+    /** Map of currently-errored domains to their error, empty if none. */
+    errors(): Record<string, DomainError>;
+    /** True if any domain is currently in `error` state. */
+    hasErrors(): boolean;
+    /** Reset all domains to initializing state. Aborts in-flight ops. */
     reset(): void;
+    /**
+     * Dispose of the suite: destroys every registered domain (aborting
+     * in-flight requests), drops the domain map, and unsubscribes every
+     * listener this suite owns on its pubsub. Safe to call multiple times.
+     *
+     * Note: if the pubsub was constructed internally (the default), all
+     * subscribers are unsubscribed. If consumers passed an external pubsub
+     * to managers directly, that shared pubsub is not cleared — they own it.
+     */
+    destroy(): void;
 }
 /** Convenience factory matching the ecsuite `createECSuite` convention. */
 export declare function createOwnsuite(config?: OwnsuiteConfig): Ownsuite;

package/dist/ownsuite.js

@@ -37,6 +37,7 @@ export class Ownsuite {
     #context;
     // deno-lint-ignore no-explicit-any
     #domains = new Map();
+    #destroyed = false;
     constructor(config = {}) {
         this.#pubsub = createPubSub();
         this.#context = { ...(config.context ?? {}) };
@@ -44,13 +45,22 @@ export class Ownsuite {
             this.registerDomain(name, cfg);
         }
         if (config.autoInitialize) {
-            // fire-and-forget; consumers who care should await initialize() explicitly
-            this.initialize().catch((e) => this.#clog.error("autoInitialize", e));
+            // `initialize()` is non-rejecting by contract; per-domain errors
+            // land in that domain's error state. See `hasErrors()` / `errors()`
+            // to detect them after boot.
+            void this.initialize();
         }
     }
+    /** True after `destroy()` has been called. */
+    get isDestroyed() {
+        return this.#destroyed;
+    }
     /** Register a new domain after construction. */
     // deno-lint-ignore no-explicit-any
     registerDomain(name, cfg) {
+        if (this.#destroyed) {
+            throw new Error("Ownsuite: cannot register on a destroyed suite");
+        }
         if (this.#domains.has(name)) {
             throw new Error(`Ownsuite: domain "${name}" already registered`);
         }
@@ -82,17 +92,50 @@ export class Ownsuite {
     /**
      * Initialize all registered domains (or a subset). Runs in parallel.
      * Individual domain errors land in that domain's error state — they
-     * do not reject the overall promise.
+     * do not reject the overall promise. Use `hasErrors()` / `errors()` to
+     * inspect the result. Unknown domain names in `names` are logged and
+     * skipped.
      */
     async initialize(names) {
+        if (this.#destroyed)
+            return;
         const targets = names ?? this.domainNames();
-        await Promise.all(targets.map((n) => this.#domains.get(n)?.initialize() ?? Promise.resolve()));
+        await Promise.all(targets.map((n) => {
+            const m = this.#domains.get(n);
+            if (!m) {
+                this.#clog.warn(`initialize: unknown domain "${n}", skipping`);
+                return Promise.resolve();
+            }
+            return m.initialize();
+        }));
     }
-    /** Update shared context and propagate to all domain managers. */
-    setContext(ctx) {
-        this.#context = { ...this.#context, ...ctx };
-        for (const m of this.#domains.values())
-            m.setContext(this.#context);
+    /**
+     * Update shared context and propagate to every domain manager.
+     *
+     * - `options.replace: true` — replace the context wholesale (no merge).
+     * - `options.refresh: true` — fire-and-forget `refresh()` on every
+     *   domain after the context change (so stale per-subject caches don't
+     *   linger when, e.g., `subjectId` changes).
+     */
+    setContext(ctx, options = {}) {
+        if (this.#destroyed)
+            return;
+        this.#context = options.replace
+            ? { ...ctx }
+            : { ...this.#context, ...ctx };
+        for (const m of this.#domains.values()) {
+            if (options.replace)
+                m.replaceContext(this.#context);
+            else
+                m.setContext(this.#context);
+        }
+        if (options.refresh) {
+            for (const m of this.#domains.values()) {
+                // Fire-and-forget. refresh() is non-rejecting (lands in error state
+                // on failure), but we defensively swallow anything unexpected.
+                void m.refresh().catch((e) => this.#clog.error("setContext: refresh failed", e));
+            }
+        }
     }
     getContext() {
         return { ...this.#context };
@@ -108,11 +151,50 @@ export class Ownsuite {
     onAny(subscriber) {
         return this.#pubsub.subscribe("*", subscriber);
     }
-    /** Reset all domains to initializing state. */
+    /** Map of currently-errored domains to their error, empty if none. */
+    errors() {
+        const out = {};
+        for (const [name, m] of this.#domains) {
+            const s = m.get();
+            if (s.state === "error" && s.error)
+                out[name] = s.error;
+        }
+        return out;
+    }
+    /** True if any domain is currently in `error` state. */
+    hasErrors() {
+        for (const m of this.#domains.values()) {
+            if (m.get().state === "error")
+                return true;
+        }
+        return false;
+    }
+    /** Reset all domains to initializing state. Aborts in-flight ops. */
     reset() {
         for (const m of this.#domains.values())
             m.reset();
     }
+    /**
+     * Dispose of the suite: destroys every registered domain (aborting
+     * in-flight requests), drops the domain map, and unsubscribes every
+     * listener this suite owns on its pubsub. Safe to call multiple times.
+     *
+     * Note: if the pubsub was constructed internally (the default), all
+     * subscribers are unsubscribed. If consumers passed an external pubsub
+     * to managers directly, that shared pubsub is not cleared — they own it.
+     */
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        for (const m of this.#domains.values())
+            m.destroy();
+        this.#domains.clear();
+        // Our internal pubsub: clear all subscribers. Best-effort — if a custom
+        // pubsub implementation doesn't expose `unsubscribeAll`, skip it.
+        const ps = this.#pubsub;
+        ps.unsubscribeAll?.();
+    }
 }
 /** Convenience factory matching the ecsuite `createECSuite` convention. */
 export function createOwnsuite(config = {}) {

package/dist/types/adapter.d.ts

@@ -34,6 +34,10 @@ export interface OwnedRowResult<TRow> {
  *   client. The client can only act on rows it owns.
  * - Errors should throw (ideally `HTTP_ERROR` from `@marianmeres/http-utils`);
  *   the manager handles rollback and error state.
+ * - `ctx.signal` is populated by the manager on every call — forward it to
+ *   `fetch(url, { signal: ctx.signal })` to support route-change and
+ *   destroy cancellation. Ignoring the signal is safe but leaves abandoned
+ *   requests running to completion (wasted bandwidth; no state corruption).
  */
 export interface OwnedCollectionAdapter<TRow, TCreate = unknown, TUpdate = unknown> {
     /** List rows owned by the current subject. Query params are implementation-defined. */