@marianmeres/ownsuite 1.0.1

package/dist/domains/base.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @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.
+ */
+import { type Clog } from "@marianmeres/clog";
+import { type StoreLike } from "@marianmeres/store";
+import { type PubSub } from "@marianmeres/pubsub";
+import type { DomainError, DomainState, DomainStateWrapper, OwnsuiteContext } from "../types/state.js";
+import type { DomainName, OwnsuiteEvent } from "../types/events.js";
+/** Base options for domain managers. */
+export interface BaseDomainOptions {
+    /** Initial context passed to adapters. */
+    context?: OwnsuiteContext;
+    /** Shared pubsub instance for events. */
+    pubsub?: PubSub;
+}
+/**
+ * Abstract base class for ownsuite domain managers.
+ *
+ * @typeParam TData - The domain data shape (for ownsuite, typically `OwnedCollectionState<TRow>`).
+ * @typeParam TAdapter - The adapter interface type for server communication.
+ */
+export declare abstract class BaseDomainManager<TData, TAdapter> {
+    protected readonly store: StoreLike<DomainStateWrapper<TData>>;
+    protected readonly pubsub: PubSub;
+    protected readonly domainName: DomainName;
+    protected readonly clog: Clog;
+    protected adapter: TAdapter | null;
+    protected context: OwnsuiteContext;
+    constructor(domainName: DomainName, options?: BaseDomainOptions);
+    /** Svelte-compatible subscribe method. */
+    get subscribe(): StoreLike<DomainStateWrapper<TData>>["subscribe"];
+    /** Get current state synchronously. */
+    get(): DomainStateWrapper<TData>;
+    setAdapter(adapter: TAdapter): void;
+    getAdapter(): TAdapter | null;
+    setContext(context: OwnsuiteContext): void;
+    getContext(): OwnsuiteContext;
+    /** Transition to a new state. */
+    protected setState(state: DomainState): void;
+    /** Update data and optionally flip to ready. */
+    protected setData(data: TData, markReady?: boolean): void;
+    /** Set error state. */
+    protected setError(error: DomainError): void;
+    /** Mark as synced. */
+    protected markSynced(): void;
+    /** 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
+     */
+    protected withOptimisticUpdate<T>(operation: string, optimisticUpdate: () => void, serverSync: () => Promise<T>, onSuccess?: (result: T) => void, onError?: (error: DomainError) => void): Promise<void>;
+    abstract initialize(): Promise<void>;
+    reset(): void;
+}

package/dist/domains/base.js

@@ -0,0 +1,151 @@
+/**
+ * @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.
+ */
+import { createClog } from "@marianmeres/clog";
+import { createStore } from "@marianmeres/store";
+import { createPubSub } from "@marianmeres/pubsub";
+/**
+ * Abstract base class for ownsuite domain managers.
+ *
+ * @typeParam TData - The domain data shape (for ownsuite, typically `OwnedCollectionState<TRow>`).
+ * @typeParam TAdapter - The adapter interface type for server communication.
+ */
+export class BaseDomainManager {
+    store;
+    pubsub;
+    domainName;
+    clog;
+    adapter = null;
+    context = {};
+    constructor(domainName, options = {}) {
+        this.domainName = domainName;
+        this.clog = createClog(`ownsuite:${domainName}`, { color: "auto" });
+        this.pubsub = options.pubsub ?? createPubSub();
+        this.context = options.context ?? {};
+        const initialState = {
+            state: "initializing",
+            data: null,
+            error: null,
+            lastSyncedAt: null,
+        };
+        this.store = createStore(initialState);
+    }
+    /** Svelte-compatible subscribe method. */
+    get subscribe() {
+        return this.store.subscribe;
+    }
+    /** Get current state synchronously. */
+    get() {
+        return this.store.get();
+    }
+    setAdapter(adapter) {
+        this.adapter = adapter;
+    }
+    getAdapter() {
+        return this.adapter;
+    }
+    setContext(context) {
+        this.context = { ...this.context, ...context };
+    }
+    getContext() {
+        return { ...this.context };
+    }
+    /** Transition to a new state. */
+    setState(state) {
+        const current = this.store.get();
+        if (current.state !== state) {
+            this.store.update((s) => ({ ...s, state }));
+            this.emit({
+                type: "domain:state:changed",
+                domain: this.domainName,
+                timestamp: Date.now(),
+                previousState: current.state,
+                newState: state,
+            });
+        }
+    }
+    /** Update data and optionally flip to ready. */
+    setData(data, markReady = true) {
+        this.store.update((s) => ({
+            ...s,
+            data,
+            state: markReady ? "ready" : s.state,
+            error: null,
+        }));
+    }
+    /** Set error state. */
+    setError(error) {
+        this.clog.error("error", {
+            code: error.code,
+            message: error.message,
+            operation: error.operation,
+        });
+        this.store.update((s) => ({ ...s, state: "error", error }));
+        this.emit({
+            type: "domain:error",
+            domain: this.domainName,
+            timestamp: Date.now(),
+            error,
+        });
+    }
+    /** Mark as synced. */
+    markSynced() {
+        this.store.update((s) => ({
+            ...s,
+            state: "ready",
+            lastSyncedAt: Date.now(),
+        }));
+        this.emit({
+            type: "domain:synced",
+            domain: this.domainName,
+            timestamp: Date.now(),
+        });
+    }
+    /** Emit an event via pubsub. */
+    emit(event) {
+        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
+     */
+    async withOptimisticUpdate(operation, optimisticUpdate, serverSync, onSuccess, onError) {
+        const previousData = this.store.get().data;
+        optimisticUpdate();
+        this.setState("syncing");
+        try {
+            const result = await serverSync();
+            this.markSynced();
+            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,
+            };
+            this.setError(error);
+            onError?.(error);
+        }
+    }
+    reset() {
+        this.store.set({
+            state: "initializing",
+            data: null,
+            error: null,
+            lastSyncedAt: null,
+        });
+    }
+}

package/dist/domains/mod.d.ts

@@ -0,0 +1,2 @@
+export * from "./base.js";
+export * from "./owned-collection.js";

package/dist/domains/mod.js

@@ -0,0 +1,2 @@
+export * from "./base.js";
+export * from "./owned-collection.js";

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

@@ -0,0 +1,43 @@
+/**
+ * @module domains/owned-collection
+ *
+ * Generic manager for a single owner-scoped collection domain. Operates on
+ * 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`.
+ */
+import type { OwnedCollectionAdapter } from "../types/adapter.js";
+import type { OwnedCollectionState } from "../types/state.js";
+import { BaseDomainManager, type BaseDomainOptions } from "./base.js";
+export interface OwnedCollectionManagerOptions<TRow, TCreate, TUpdate> extends BaseDomainOptions {
+    adapter?: OwnedCollectionAdapter<TRow, TCreate, TUpdate>;
+    /** Function that extracts the row id from a row. Defaults to `row.model_id`. */
+    getRowId?: (row: TRow) => string;
+}
+/**
+ * Generic domain manager for one owner-scoped collection.
+ *
+ * State shape: `{ rows: TRow[]; meta: {...} }`. List operations replace
+ * rows wholesale; single-row operations (create/update/delete) apply
+ * in-place mutations so the list stays stable without a re-fetch.
+ */
+export declare class OwnedCollectionManager<TRow = Record<string, unknown>, TCreate = Partial<TRow>, TUpdate = Partial<TRow>> extends BaseDomainManager<OwnedCollectionState<TRow>, OwnedCollectionAdapter<TRow, TCreate, TUpdate>> {
+    #private;
+    constructor(domainName: string, options?: OwnedCollectionManagerOptions<TRow, TCreate, TUpdate>);
+    /** Initialize by fetching the list from the server. */
+    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. */
+    getOne(id: string): Promise<TRow | null>;
+    /** Create a new row. Optimistically prepends to the list. */
+    create(data: TCreate): Promise<TRow | null>;
+    /** Update a row. Optimistically merges into the list. */
+    update(id: string, data: TUpdate): Promise<TRow | null>;
+    /** Delete a row. Optimistically removes from the list. */
+    delete(id: string): Promise<boolean>;
+    /** Snapshot of current rows (empty array if not loaded). */
+    getRows(): TRow[];
+    /** Find a row by id in the current list (without hitting the server). */
+    findRow(id: string): TRow | undefined;
+}

package/dist/domains/owned-collection.js

@@ -0,0 +1,201 @@
+/**
+ * @module domains/owned-collection
+ *
+ * Generic manager for a single owner-scoped collection domain. Operates on
+ * 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`.
+ */
+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`; " +
+            "pass a custom `getRowId` in options.");
+    }
+    return id;
+};
+/**
+ * Generic domain manager for one owner-scoped collection.
+ *
+ * State shape: `{ rows: TRow[]; meta: {...} }`. List operations replace
+ * rows wholesale; single-row operations (create/update/delete) apply
+ * in-place mutations so the list stays stable without a re-fetch.
+ */
+export class OwnedCollectionManager extends BaseDomainManager {
+    #getRowId;
+    constructor(domainName, options = {}) {
+        super(domainName, options);
+        this.#getRowId = options.getRowId ?? defaultGetRowId;
+        if (options.adapter)
+            this.adapter = options.adapter;
+    }
+    /** Initialize by fetching the list from the server. */
+    async initialize() {
+        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",
+            });
+        }
+    }
+    /** Refresh the list from server. Same as initialize but re-entrant. */
+    async refresh(query) {
+        if (!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",
+            });
+        }
+    }
+    /** Fetch a single row by id; returns the row but does not update the list. */
+    async getOne(id) {
+        if (!this.adapter)
+            return null;
+        try {
+            const res = await this.adapter.getOne(id, this.context);
+            this.emit({
+                type: "own:row:fetched",
+                domain: this.domainName,
+                timestamp: Date.now(),
+                rowId: id,
+            });
+            return res.data;
+        }
+        catch (e) {
+            this.setError({
+                code: "FETCH_FAILED",
+                message: e instanceof Error ? e.message : "Failed to fetch row",
+                originalError: e,
+                operation: "getOne",
+            });
+            return null;
+        }
+    }
+    /** Create a new row. Optimistically prepends to the list. */
+    async create(data) {
+        if (!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 result;
+    }
+    /** Update a row. Optimistically merges into the list. */
+    async update(id, data) {
+        if (!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 result;
+    }
+    /** Delete a row. Optimistically removes from the list. */
+    async delete(id) {
+        if (!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 ok;
+    }
+    /** Snapshot of current rows (empty array if not loaded). */
+    getRows() {
+        return this.store.get().data?.rows ?? [];
+    }
+    /** Find a row by id in the current list (without hitting the server). */
+    findRow(id) {
+        return this.getRows().find((r) => this.#getRowId(r) === id);
+    }
+}

package/dist/mod.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module @marianmeres/ownsuite
+ *
+ * Client-side helper library for owner-scoped UIs. Generic domain managers
+ * with optimistic updates, Svelte-compatible stores, and adapter-based
+ * server sync — mirrors the shape of `@marianmeres/ecsuite` but applies to
+ * arbitrary owner-scoped collections instead of hard-coded e-commerce
+ * domains.
+ *
+ * Pairs with the server-side `ownsuite` module in
+ * `@marianmeres/stack-common` and the `ownerIdScope` hook in
+ * `@marianmeres/collection`.
+ *
+ * @example
+ * ```typescript
+ * import { createOwnsuite, createMockOwnedCollectionAdapter } from "@marianmeres/ownsuite";
+ *
+ * const suite = createOwnsuite({
+ *   domains: {
+ *     orders: { adapter: myOrdersAdapter },
+ *   },
+ * });
+ * await suite.initialize();
+ * suite.domain("orders").subscribe((s) => render(s.data?.rows));
+ * await suite.domain("orders").create({ data: { total: 99 } });
+ * ```
+ */
+export * from "./ownsuite.js";
+export * from "./domains/mod.js";
+export * from "./types/mod.js";
+export * from "./adapters/mod.js";

package/dist/mod.js

@@ -0,0 +1,31 @@
+/**
+ * @module @marianmeres/ownsuite
+ *
+ * Client-side helper library for owner-scoped UIs. Generic domain managers
+ * with optimistic updates, Svelte-compatible stores, and adapter-based
+ * server sync — mirrors the shape of `@marianmeres/ecsuite` but applies to
+ * arbitrary owner-scoped collections instead of hard-coded e-commerce
+ * domains.
+ *
+ * Pairs with the server-side `ownsuite` module in
+ * `@marianmeres/stack-common` and the `ownerIdScope` hook in
+ * `@marianmeres/collection`.
+ *
+ * @example
+ * ```typescript
+ * import { createOwnsuite, createMockOwnedCollectionAdapter } from "@marianmeres/ownsuite";
+ *
+ * const suite = createOwnsuite({
+ *   domains: {
+ *     orders: { adapter: myOrdersAdapter },
+ *   },
+ * });
+ * await suite.initialize();
+ * suite.domain("orders").subscribe((s) => render(s.data?.rows));
+ * await suite.domain("orders").create({ data: { total: 99 } });
+ * ```
+ */
+export * from "./ownsuite.js";
+export * from "./domains/mod.js";
+export * from "./types/mod.js";
+export * from "./adapters/mod.js";

package/dist/ownsuite.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @module ownsuite
+ *
+ * Ownsuite — orchestrator for owner-scoped domain managers.
+ *
+ * Unlike ecsuite (which hard-codes six e-commerce domains), ownsuite is
+ * generic: consumers register arbitrary owner-scoped collection domains by
+ * name. Each domain operates through an adapter that talks to a server
+ * mount (conventionally `/me/<collection-path>`) with owner scoping
+ * enforced by the server via `@marianmeres/collection`'s `ownerIdScope`
+ * 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 { OwnedCollectionAdapter } from "./types/adapter.js";
+import type { OwnsuiteEventType } from "./types/events.js";
+import { OwnedCollectionManager } from "./domains/owned-collection.js";
+/**
+ * Configuration for a single domain at construction time. The caller
+ * provides a unique name and an adapter. A custom `getRowId` is optional
+ * (defaults to reading `row.model_id` or `row.id`).
+ */
+export interface OwnsuiteDomainConfig<TRow = any, TCreate = any, TUpdate = any> {
+    adapter: OwnedCollectionAdapter<TRow, TCreate, TUpdate>;
+    getRowId?: (row: TRow) => string;
+}
+/** Top-level ownsuite configuration. */
+export interface OwnsuiteConfig {
+    /** Initial context passed to every adapter call. */
+    context?: OwnsuiteContext;
+    /** Domain registry. Keys are domain names (arbitrary labels). */
+    domains?: Record<string, OwnsuiteDomainConfig>;
+    /** Auto-initialize all registered domains on creation (default: false). */
+    autoInitialize?: boolean;
+}
+/**
+ * Main Ownsuite class — coordinates owner-scoped domain managers.
+ *
+ * @example
+ * ```typescript
+ * const suite = createOwnsuite({
+ *   context: { subjectId: "user-123" },
+ *   domains: {
+ *     orders: { adapter: myOrdersAdapter },
+ *     addresses: { adapter: myAddressesAdapter },
+ *   },
+ * });
+ * await suite.initialize(); // or pass autoInitialize: true
+ *
+ * suite.domain("orders").subscribe((s) => console.log(s.state, s.data?.rows));
+ * await suite.domain("orders").create({ data: { ... } });
+ * ```
+ */
+export declare class Ownsuite {
+    #private;
+    constructor(config?: OwnsuiteConfig);
+    /** 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. */
+    domain<TRow = any, TCreate = any, TUpdate = any>(name: string): OwnedCollectionManager<TRow, TCreate, TUpdate>;
+    /** True if a domain by this name is registered. */
+    hasDomain(name: string): boolean;
+    /** List registered domain names. */
+    domainNames(): string[];
+    /**
+     * 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.
+     */
+    initialize(names?: string[]): Promise<void>;
+    /** Update shared context and propagate to all domain managers. */
+    setContext(ctx: OwnsuiteContext): void;
+    getContext(): OwnsuiteContext;
+    /** Subscribe to a specific event type. */
+    on(type: OwnsuiteEventType, subscriber: Subscriber): Unsubscriber;
+    /**
+     * Subscribe to all events. Wildcard subscribers receive an envelope
+     * `{ event: string, data: OwnsuiteEvent }` — see `@marianmeres/pubsub`.
+     */
+    onAny(subscriber: Subscriber): Unsubscriber;
+    /** Reset all domains to initializing state. */
+    reset(): void;
+}
+/** Convenience factory matching the ecsuite `createECSuite` convention. */
+export declare function createOwnsuite(config?: OwnsuiteConfig): Ownsuite;