@marianmeres/ownsuite 1.0.1

package/API.md

@@ -0,0 +1,423 @@
+# API
+
+## Functions
+
+### `createOwnsuite(config?)`
+
+Convenience factory mirroring the ecsuite `createECSuite` convention. Equivalent to `new Ownsuite(config)`.
+
+**Parameters:**
+- `config` (`OwnsuiteConfig`, optional) — see [`OwnsuiteConfig`](#ownsuiteconfig).
+
+**Returns:** `Ownsuite`
+
+**Example:**
+```typescript
+import { createOwnsuite } from "@marianmeres/ownsuite";
+
+const suite = createOwnsuite({
+	context: { subjectId: "user-123" },
+	domains: {
+		orders: { adapter: myOrdersAdapter },
+		addresses: { adapter: myAddressesAdapter },
+	},
+});
+await suite.initialize();
+```
+
+---
+
+### `createMockOwnedCollectionAdapter(options?)`
+
+In-memory mock adapter for tests. Stores rows in a local `Map` keyed by `model_id`. Applies optional latency and can inject failures per operation — useful for exercising the optimistic-update rollback path deterministically.
+
+**Parameters:**
+- `options` (`MockAdapterOptions<TRow>`, optional)
+  - `options.seed` (`TRow[]`, optional) — initial rows
+  - `options.delayMs` (`number`, optional) — artificial latency per call. Default: `0`
+  - `options.failOn` (`object`, optional) — per-operation failure injection: `{ list?, getOne?, create?, update?, delete? }`
+  - `options.getRowId` (`(row) => string`, optional) — row-id resolver. Default: `row.model_id ?? row.id`
+  - `options.newId` (`() => string`, optional) — id factory for new rows. Default: `crypto.randomUUID`
+
+**Returns:** `OwnedCollectionAdapter<TRow> & { _rows(): TRow[] }`
+
+The returned adapter exposes an extra `_rows()` method for test assertions that doesn't exist on production adapters.
+
+**Example:**
+```typescript
+const adapter = createMockOwnedCollectionAdapter({
+	seed: [{ model_id: "1", data: { label: "a" } }],
+	failOn: { create: true },
+});
+```
+
+---
+
+## Classes
+
+### `Ownsuite`
+
+Orchestrator that coordinates owner-scoped domain managers and provides a shared event bus.
+
+#### `new Ownsuite(config?)`
+
+**Parameters:** same as `createOwnsuite`.
+
+#### `suite.registerDomain(name, cfg)`
+
+Register a new domain after construction. Throws if `name` is already registered.
+
+**Parameters:**
+- `name` (`string`) — unique domain label
+- `cfg` (`OwnsuiteDomainConfig<TRow, TCreate, TUpdate>`)
+  - `cfg.adapter` (`OwnedCollectionAdapter`) — required
+  - `cfg.getRowId` (`(row) => string`, optional) — custom row-id resolver
+
+**Returns:** `OwnedCollectionManager<TRow, TCreate, TUpdate>`
+
+#### `suite.domain(name)`
+
+Look up a domain manager by name. Throws if unknown.
+
+**Returns:** `OwnedCollectionManager<TRow, TCreate, TUpdate>`
+
+#### `suite.hasDomain(name): boolean`
+
+True if a domain by this name is registered.
+
+#### `suite.domainNames(): string[]`
+
+List registered domain names.
+
+#### `suite.initialize(names?)`
+
+Initialize all registered domains (or a subset). Runs in parallel. Individual domain errors land in that domain's error state and **do not** reject the returned promise.
+
+**Parameters:**
+- `names` (`string[]`, optional) — domain names to initialize. Default: all registered domains.
+
+**Returns:** `Promise<void>`
+
+#### `suite.setContext(ctx)`
+
+Merge `ctx` into the shared context and propagate to every registered domain manager.
+
+**Parameters:**
+- `ctx` (`OwnsuiteContext`)
+
+#### `suite.getContext(): OwnsuiteContext`
+
+Snapshot of current shared context.
+
+#### `suite.on(type, subscriber)`
+
+Subscribe to a specific event type.
+
+**Parameters:**
+- `type` (`OwnsuiteEventType`)
+- `subscriber` (`Subscriber`) — from `@marianmeres/pubsub`
+
+**Returns:** `Unsubscriber`
+
+**Example:**
+```typescript
+const unsub = suite.on("own:row:created", (e) => {
+	console.log("created row", e.rowId, "in domain", e.domain);
+});
+```
+
+#### `suite.onAny(subscriber)`
+
+Subscribe to all events. Wildcard subscribers receive an envelope `{ event: string, data: OwnsuiteEvent }` — see `@marianmeres/pubsub`.
+
+**Returns:** `Unsubscriber`
+
+#### `suite.reset()`
+
+Reset every domain manager to the `initializing` state. Drops cached lists.
+
+---
+
+### `OwnedCollectionManager<TRow, TCreate, TUpdate>`
+
+Generic manager for a single owner-scoped collection domain. One instance per collection path on the server.
+
+#### `new OwnedCollectionManager(domainName, options?)`
+
+Typically created via `Ownsuite.registerDomain()` — manual construction is possible but bypasses the shared pubsub.
+
+**Parameters:**
+- `domainName` (`string`) — label (informational, used in event payloads and logs)
+- `options` (`OwnedCollectionManagerOptions<TRow, TCreate, TUpdate>`, optional)
+  - `options.adapter` (`OwnedCollectionAdapter`, optional)
+  - `options.getRowId` (`(row) => string`, optional) — default: `row.model_id ?? row.id`
+  - `options.context` (`OwnsuiteContext`, optional)
+  - `options.pubsub` (`PubSub`, optional) — shared event bus
+
+#### `manager.subscribe(listener)`
+
+Svelte-compatible subscribe. Listener receives the full [`DomainStateWrapper<OwnedCollectionState<TRow>>`](#domainstatewrappert).
+
+**Returns:** `Unsubscriber`
+
+#### `manager.get(): DomainStateWrapper<OwnedCollectionState<TRow>>`
+
+Synchronous snapshot of the current state.
+
+#### `manager.initialize(): Promise<void>`
+
+Fetch the list from the server. Populates `data.rows` + `data.meta` and transitions to `ready`.
+
+#### `manager.refresh(query?): Promise<void>`
+
+Re-fetch the list. Same as `initialize` but re-entrant; accepts an adapter-specific query object.
+
+**Parameters:**
+- `query` (`Record<string, unknown>`, optional) — forwarded to `adapter.list(ctx, query)`
+
+#### `manager.getOne(id): Promise<TRow | null>`
+
+Fetch a single row by id. Does **not** mutate the list. Returns `null` on error and transitions the manager to `error` state.
+
+#### `manager.create(data): Promise<TRow | null>`
+
+Create a new row. On success, prepends the server-returned row to the list. On failure, the list is unchanged and the manager transitions to `error`.
+
+**Parameters:**
+- `data` (`TCreate`) — creation payload. The server stamps `owner_id` — do not set it client-side.
+
+**Returns:** the server-returned row, or `null` on failure.
+
+#### `manager.update(id, data): Promise<TRow | null>`
+
+Update a row. Optimistically merges `data` into the existing row; on server failure the list is rolled back to its pre-call state. On success, the server-returned row replaces the optimistic one.
+
+**Parameters:**
+- `id` (`string`)
+- `data` (`TUpdate`)
+
+#### `manager.delete(id): Promise<boolean>`
+
+Delete a row. Optimistically removes it from the list; on server failure the list is rolled back.
+
+**Returns:** `true` on success, `false` on failure.
+
+#### `manager.getRows(): TRow[]`
+
+Snapshot of current rows (empty array if not loaded).
+
+#### `manager.findRow(id): TRow | undefined`
+
+Find a row by id in the current list without hitting the server.
+
+#### `manager.setAdapter(adapter)` / `manager.getAdapter()`
+
+Swap or inspect the adapter at runtime.
+
+#### `manager.setContext(ctx)` / `manager.getContext()`
+
+Per-manager context. `Ownsuite.setContext()` propagates to every manager.
+
+#### `manager.reset()`
+
+Reset to `initializing` state.
+
+---
+
+### `BaseDomainManager<TData, TAdapter>`
+
+Abstract base class. Not typically used directly — `OwnedCollectionManager` extends it. Provides reactive state, state-machine transitions, optimistic-update pattern, and event emission. Matches the shape of ecsuite's `BaseDomainManager`.
+
+---
+
+## Types
+
+### `OwnsuiteConfig`
+
+```typescript
+interface OwnsuiteConfig {
+	context?: OwnsuiteContext;
+	domains?: Record<string, OwnsuiteDomainConfig>;
+	autoInitialize?: boolean;
+}
+```
+
+- `context` — initial context passed to every adapter call.
+- `domains` — domain registry at construction time. Keys are arbitrary labels.
+- `autoInitialize` — fire-and-forget `initialize()` in the constructor. Default: `false`.
+
+### `OwnsuiteDomainConfig<TRow, TCreate, TUpdate>`
+
+```typescript
+interface OwnsuiteDomainConfig<TRow, TCreate, TUpdate> {
+	adapter: OwnedCollectionAdapter<TRow, TCreate, TUpdate>;
+	getRowId?: (row: TRow) => string;
+}
+```
+
+### `OwnsuiteContext`
+
+```typescript
+interface OwnsuiteContext {
+	subjectId?: string;
+	[key: string]: unknown;
+}
+```
+
+Context passed to adapters. **`subjectId` is a hint only** — the server authoritatively resolves the owner from the authenticated JWT. The context object is the extension point for passing host-app data (correlation ids, feature flags, tenants) through adapter calls.
+
+### `OwnedCollectionAdapter<TRow, TCreate, TUpdate>`
+
+```typescript
+interface OwnedCollectionAdapter<TRow, TCreate = unknown, TUpdate = unknown> {
+	list(ctx: OwnsuiteContext, query?: Record<string, unknown>): Promise<OwnedListResult<TRow>>;
+	getOne(id: string, ctx: OwnsuiteContext): Promise<OwnedRowResult<TRow>>;
+	create(data: TCreate, ctx: OwnsuiteContext): Promise<OwnedRowResult<TRow>>;
+	update(id: string, data: TUpdate, ctx: OwnsuiteContext): Promise<OwnedRowResult<TRow>>;
+	delete(id: string, ctx: OwnsuiteContext): Promise<boolean>;
+}
+```
+
+Implementations throw on failure (ideally `HTTP_ERROR` from `@marianmeres/http-utils`); the manager handles rollback.
+
+### `OwnedListResult<TRow>` / `OwnedRowResult<TRow>`
+
+```typescript
+interface OwnedListResult<TRow> {
+	data: TRow[];
+	meta: Record<string, unknown>;
+}
+
+interface OwnedRowResult<TRow> {
+	data: TRow;
+	meta?: Record<string, unknown>;
+}
+```
+
+Matches `@marianmeres/collection`'s REST envelope.
+
+### `OwnedCollectionState<TRow>`
+
+```typescript
+interface OwnedCollectionState<TRow> {
+	rows: TRow[];
+	meta: Record<string, unknown>;
+}
+```
+
+### `DomainStateWrapper<T>`
+
+```typescript
+interface DomainStateWrapper<T> {
+	state: DomainState;           // "initializing" | "ready" | "syncing" | "error"
+	data: T | null;
+	error: DomainError | null;
+	lastSyncedAt: number | null;
+}
+```
+
+### `DomainState`
+
+```typescript
+type DomainState = "initializing" | "ready" | "syncing" | "error";
+```
+
+State transitions:
+
+```
+initializing → ready
+ready        ↔ syncing
+syncing      → error      (on failure; list is rolled back)
+error        → syncing    (retry)
+```
+
+### `DomainError`
+
+```typescript
+interface DomainError {
+	code: string;             // e.g. "SYNC_FAILED", "FETCH_FAILED"
+	message: string;
+	operation: string;        // e.g. "create", "update", "delete"
+	originalError?: unknown;
+}
+```
+
+### `OwnsuiteEventType`
+
+```typescript
+type OwnsuiteEventType =
+	| "domain:state:changed"
+	| "domain:error"
+	| "domain:synced"
+	| "own:list:fetched"
+	| "own:row:fetched"
+	| "own:row:created"
+	| "own:row:updated"
+	| "own:row:deleted";
+```
+
+### `OwnsuiteEvent`
+
+Discriminated union of all event payloads. Every event has `type`, `timestamp`, and `domain` fields.
+
+```typescript
+type OwnsuiteEvent =
+	| StateChangedEvent
+	| ErrorEvent
+	| SyncedEvent
+	| ListFetchedEvent      // + count
+	| RowFetchedEvent       // + rowId
+	| RowCreatedEvent       // + rowId
+	| RowUpdatedEvent       // + rowId
+	| RowDeletedEvent;      // + rowId
+```
+
+See [src/types/events.ts](src/types/events.ts) for individual event interfaces.
+
+### `MockAdapterOptions<TRow>`
+
+```typescript
+interface MockAdapterOptions<TRow> {
+	seed?: TRow[];
+	delayMs?: number;
+	failOn?: { list?: boolean; getOne?: boolean; create?: boolean; update?: boolean; delete?: boolean };
+	getRowId?: (row: TRow) => string;
+	newId?: () => string;
+}
+```
+
+---
+
+## Implementing a real adapter
+
+Point the adapter at your server's owner-scoped mount (typically `/api/<stack>/me/col/<entity>/...`). The server is responsible for `owner_id` enforcement — the client only talks to `/me/*`.
+
+```typescript
+import type { OwnedCollectionAdapter } from "@marianmeres/ownsuite";
+import { HTTP_ERROR } from "@marianmeres/http-utils";
+
+export function createRestAdapter(stack: string, entity: string): OwnedCollectionAdapter {
+	const base = `/api/${stack}/me/col/${entity}`;
+	const json = async <T>(method: string, url: string, body?: unknown): Promise<T> => {
+		const res = await fetch(url, {
+			method,
+			headers: { "content-type": "application/json" },
+			body: body === undefined ? undefined : JSON.stringify(body),
+		});
+		if (!res.ok) throw new HTTP_ERROR.BadRequest(await res.text());
+		return await res.json();
+	};
+	return {
+		list: (_ctx) => json("GET", `${base}/mod`),
+		getOne: (id, _ctx) => json("GET", `${base}/mod/${id}`),
+		create: (data, _ctx) => json("POST", `${base}/mod`, data),
+		update: (id, data, _ctx) => json("PUT", `${base}/mod/${id}`, data),
+		delete: async (id, _ctx) => {
+			await json("DELETE", `${base}/mod/${id}`);
+			return true;
+		},
+	};
+}
+```
+
+The [`@marianmeres/joy`](https://github.com/marianmeres/full-stack-app-template) admin SPA ships a reusable factory — `createOwnedCollectionAdapter()` in `src/routes/me/owned-collection-adapter.ts` — that implements exactly this shape.

package/CLAUDE.md

@@ -0,0 +1,3 @@
+# Project Instructions
+
+See [AGENTS.md](./AGENTS.md) for complete project documentation and AI agent instructions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marian Meres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @marianmeres/ownsuite
+
+[![NPM Version](https://img.shields.io/npm/v/@marianmeres/ownsuite)](https://www.npmjs.com/package/@marianmeres/ownsuite)
+[![JSR Version](https://img.shields.io/jsr/v/@marianmeres/ownsuite)](https://jsr.io/@marianmeres/ownsuite)
+[![License](https://img.shields.io/github/license/marianmeres/ownsuite)](LICENSE)
+
+Client-side helper library for owner-scoped UIs. Generic domain managers with optimistic updates, Svelte-compatible stores, and adapter-based server sync — the owner-scoped counterpart to [`@marianmeres/ecsuite`](https://jsr.io/@marianmeres/ecsuite).
+
+## What it does
+
+Ownsuite gives front-end applications a uniform way to read, create, update and delete records from owner-scoped REST endpoints (typically `/me/*`). Each row is implicitly scoped to the authenticated subject by the server — the client never sets `owner_id`. The library pairs with:
+
+- **[`@marianmeres/collection`](https://jsr.io/@marianmeres/collection)** — the `ownerIdScope` route hook enforces owner-based filtering on the server.
+- **[`@marianmeres/stack-common`](https://jsr.io/@marianmeres/stack-common)** — the `ownsuiteOptions()` helper wires the server mount.
+
+## Features
+
+- **Generic domain managers** — register any owner-scoped collection by name; no hard-coded domain list
+- **Optimistic updates** — UI mutates immediately; the manager rolls back on server failure
+- **Svelte-compatible stores** — every domain exposes a `subscribe()` method
+- **Adapter pattern** — plug in any HTTP/WebSocket/mock transport
+- **Event system** — subscribe to list fetches, row CRUD, and lifecycle transitions
+- **Mock adapter** — in-memory fixture for tests, with configurable failure injection
+
+## Installation
+
+```bash
+# Deno
+deno add @marianmeres/ownsuite
+
+# npm
+npm install @marianmeres/ownsuite
+```
+
+## Quick Start
+
+```typescript
+import { createOwnsuite } from "@marianmeres/ownsuite";
+import { createOwnedCollectionAdapter } from "./my-adapters";
+
+// 1. Build adapters that point at owner-scoped endpoints
+const ordersAdapter = createOwnedCollectionAdapter({
+	apiRoot: "/api",
+	stack: "shop",
+	entity: "order",
+});
+
+// 2. Register domains under any name
+const suite = createOwnsuite({
+	context: { subjectId: "user-123" },
+	domains: {
+		orders: { adapter: ordersAdapter },
+	},
+});
+
+// 3. Load the list from the server
+await suite.initialize();
+
+// 4. Subscribe (Svelte-compatible)
+suite.domain("orders").subscribe((s) => {
+	console.log(s.state, s.data?.rows);
+});
+
+// 5. CRUD — the server stamps owner_id from the JWT; the client never sets it
+await suite.domain("orders").create({ data: { total: 99 } });
+await suite.domain("orders").update(id, { data: { total: 120 } });
+await suite.domain("orders").delete(id);
+```
+
+## Architecture at a glance
+
+```
+Ownsuite (orchestrator)
+├── domain("orders") ──┐
+├── domain("notes")  ──┼──► OwnedCollectionManager<TRow>
+├── domain("...")    ──┘         ├── store   (Svelte-compatible)
+                                  ├── pubsub  (events)
+                                  └── adapter (HTTP/mock)
+```
+
+Each domain holds a single list of rows owned by the authenticated subject. List operations replace the list; single-row operations mutate it in place so subscribers see stable references without a re-fetch.
+
+## Testing with the mock adapter
+
+```typescript
+import {
+	createMockOwnedCollectionAdapter,
+	createOwnsuite,
+} from "@marianmeres/ownsuite";
+
+const adapter = createMockOwnedCollectionAdapter({
+	seed: [{ model_id: "1", data: { label: "hello" } }],
+	failOn: { update: true },   // force update failures for rollback tests
+});
+
+const suite = createOwnsuite({ domains: { notes: { adapter } } });
+await suite.initialize();
+await suite.domain("notes").update("1", { data: { label: "new" } });
+// list is rolled back; suite.domain("notes").get().state === "error"
+```
+
+## API
+
+See [API.md](API.md) for complete API documentation.
+
+## License
+
+[MIT](LICENSE)

package/dist/adapters/mock.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @module adapters/mock
+ *
+ * In-memory mock adapter for testing. Stores rows in a local Map keyed by
+ * `model_id`, applies an optional latency, and can inject failures. Useful
+ * for unit tests without a real server, and for exercising the manager's
+ * optimistic-update rollback path deterministically.
+ */
+import type { OwnedCollectionAdapter } from "../types/adapter.js";
+export interface MockAdapterOptions<TRow> {
+    /** Initial seed rows. */
+    seed?: TRow[];
+    /** Artificial latency per call (ms). */
+    delayMs?: number;
+    /** If set, every call on matching operation throws. Use for rollback tests. */
+    failOn?: {
+        list?: boolean;
+        getOne?: boolean;
+        create?: boolean;
+        update?: boolean;
+        delete?: boolean;
+    };
+    /** Row-id resolver. Defaults to `row.model_id` or `row.id`. */
+    getRowId?: (row: TRow) => string;
+    /** Factory for new row ids (defaults to `crypto.randomUUID`). */
+    newId?: () => string;
+}
+/**
+ * Build an in-memory `OwnedCollectionAdapter` for tests.
+ */
+export declare function createMockOwnedCollectionAdapter<TRow extends Record<string, unknown> = Record<string, unknown>, TCreate = Partial<TRow>, TUpdate = Partial<TRow>>(options?: MockAdapterOptions<TRow>): OwnedCollectionAdapter<TRow, TCreate, TUpdate> & {
+    /** Peek at the underlying store (tests only). */
+    _rows(): TRow[];
+};

package/dist/adapters/mock.js

@@ -0,0 +1,73 @@
+/**
+ * @module adapters/mock
+ *
+ * In-memory mock adapter for testing. Stores rows in a local Map keyed by
+ * `model_id`, applies an optional latency, and can inject failures. Useful
+ * for unit tests without a real server, and for exercising the manager's
+ * optimistic-update rollback path deterministically.
+ */
+const defaultGetRowId = (r) => {
+    const rec = r;
+    const id = rec.model_id ?? rec.id;
+    if (typeof id !== "string") {
+        throw new Error("MockAdapter: row has no string `model_id` or `id`; pass `getRowId`");
+    }
+    return id;
+};
+/**
+ * Build an in-memory `OwnedCollectionAdapter` for tests.
+ */
+export function createMockOwnedCollectionAdapter(options = {}) {
+    const { delayMs = 0, failOn = {}, getRowId = defaultGetRowId, newId = () => crypto.randomUUID(), } = options;
+    const store = new Map();
+    for (const r of options.seed ?? [])
+        store.set(getRowId(r), r);
+    const sleep = () => delayMs > 0
+        ? new Promise((res) => setTimeout(res, delayMs))
+        : Promise.resolve();
+    return {
+        async list(_ctx, _query) {
+            await sleep();
+            if (failOn.list)
+                throw new Error("mock: list failed");
+            const rows = [...store.values()];
+            return { data: rows, meta: { total: rows.length } };
+        },
+        async getOne(id, _ctx) {
+            await sleep();
+            if (failOn.getOne)
+                throw new Error("mock: getOne failed");
+            const row = store.get(id);
+            if (!row)
+                throw new Error(`mock: row ${id} not found`);
+            return { data: row };
+        },
+        async create(data, _ctx) {
+            await sleep();
+            if (failOn.create)
+                throw new Error("mock: create failed");
+            const id = newId();
+            const row = { ...data, model_id: id };
+            store.set(id, row);
+            return { data: row };
+        },
+        async update(id, data, _ctx) {
+            await sleep();
+            if (failOn.update)
+                throw new Error("mock: update failed");
+            const existing = store.get(id);
+            if (!existing)
+                throw new Error(`mock: row ${id} not found`);
+            const merged = { ...existing, ...data };
+            store.set(id, merged);
+            return { data: merged };
+        },
+        async delete(id, _ctx) {
+            await sleep();
+            if (failOn.delete)
+                throw new Error("mock: delete failed");
+            return store.delete(id);
+        },
+        _rows: () => [...store.values()],
+    };
+}

package/dist/adapters/mod.d.ts

@@ -0,0 +1 @@
+export * from "./mock.js";

package/dist/adapters/mod.js

@@ -0,0 +1 @@
+export * from "./mock.js";