@marianmeres/ownsuite 1.0.3 → 2.1.0

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[];

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/domains/profile.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @module domains/profile
+ *
+ * ProfileManager — a singleton (one-row) reactive container for the
+ * authenticated subject's `/me` data: email, roles, verification flag,
+ * whether the account has a password, and the list of linked OAuth
+ * connections.
+ *
+ * Deliberately NOT an OwnedCollectionManager. The underlying `/me` endpoint
+ * is a single-record resource: no list, no optimistic create/delete, and
+ * update returns the full profile. Shoehorning it into the collection
+ * manager would leak CRUD semantics that don't apply and complicate
+ * ownership semantics.
+ *
+ * This manager mutates the companion `SessionManager`'s subject in place
+ * when the profile changes (e.g. email edited) so consumers reading from
+ * `suite.session` see the update without a second fetch.
+ */
+import { type StoreLike } from "@marianmeres/store";
+import { type PubSub } from "@marianmeres/pubsub";
+import type { OAuthConnection, OAuthProvider, OwnsuiteContext, ProfileAdapter, ProfileResult } from "../types/mod.js";
+import type { SessionManager } from "./session.js";
+export interface ProfileManagerOptions {
+    adapter: ProfileAdapter;
+    session: SessionManager;
+    /** Shared pubsub for event emission. Private if omitted. */
+    pubsub?: PubSub;
+    /** Initial context passed to adapter calls. Extended per-call with
+     *  `jwt` and `signal` by the manager. */
+    context?: OwnsuiteContext;
+}
+export interface ProfileState {
+    /** Null until the first successful fetch. */
+    profile: ProfileResult | null;
+    /** True while a request is in flight. */
+    loading: boolean;
+    /** Most recent error, or null. Cleared on the next successful call. */
+    error: Error | null;
+}
+/**
+ * Profile manager — singleton state for `/me`.
+ */
+export declare class ProfileManager {
+    #private;
+    constructor(options: ProfileManagerOptions);
+    get subscribe(): StoreLike<ProfileState>["subscribe"];
+    get(): ProfileState;
+    setContext(ctx: OwnsuiteContext): void;
+    replaceContext(ctx: OwnsuiteContext): void;
+    /** Fetch `/me`. Supersedes any in-flight fetch. */
+    fetch(): Promise<ProfileResult>;
+    /** Update profile (currently: email). Triggers a re-verification email
+     *  server-side when the gate is on. Returns the refreshed profile. */
+    update(input: {
+        email?: string;
+        current_password?: string;
+    }): Promise<ProfileResult>;
+    listOAuth(): Promise<OAuthConnection[]>;
+    unlinkOAuth(provider: OAuthProvider): Promise<void>;
+    reset(): void;
+    destroy(): void;
+}