@marianmeres/ownsuite 1.0.1

package/dist/ownsuite.js

@@ -0,0 +1,120 @@
+/**
+ * @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 { createClog } from "@marianmeres/clog";
+import { createPubSub, } from "@marianmeres/pubsub";
+import { OwnedCollectionManager } from "./domains/owned-collection.js";
+/**
+ * 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 class Ownsuite {
+    #clog = createClog("ownsuite", { color: "auto" });
+    #pubsub;
+    #context;
+    // deno-lint-ignore no-explicit-any
+    #domains = new Map();
+    constructor(config = {}) {
+        this.#pubsub = createPubSub();
+        this.#context = { ...(config.context ?? {}) };
+        for (const [name, cfg] of Object.entries(config.domains ?? {})) {
+            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));
+        }
+    }
+    /** Register a new domain after construction. */
+    // deno-lint-ignore no-explicit-any
+    registerDomain(name, cfg) {
+        if (this.#domains.has(name)) {
+            throw new Error(`Ownsuite: domain "${name}" already registered`);
+        }
+        const manager = new OwnedCollectionManager(name, {
+            adapter: cfg.adapter,
+            getRowId: cfg.getRowId,
+            context: this.#context,
+            pubsub: this.#pubsub,
+        });
+        this.#domains.set(name, manager);
+        return manager;
+    }
+    /** Look up a domain manager by name. Throws if unknown. */
+    // deno-lint-ignore no-explicit-any
+    domain(name) {
+        const m = this.#domains.get(name);
+        if (!m)
+            throw new Error(`Ownsuite: unknown domain "${name}"`);
+        return m;
+    }
+    /** True if a domain by this name is registered. */
+    hasDomain(name) {
+        return this.#domains.has(name);
+    }
+    /** List registered domain names. */
+    domainNames() {
+        return [...this.#domains.keys()];
+    }
+    /**
+     * 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.
+     */
+    async initialize(names) {
+        const targets = names ?? this.domainNames();
+        await Promise.all(targets.map((n) => this.#domains.get(n)?.initialize() ?? Promise.resolve()));
+    }
+    /** 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);
+    }
+    getContext() {
+        return { ...this.#context };
+    }
+    /** Subscribe to a specific event type. */
+    on(type, subscriber) {
+        return this.#pubsub.subscribe(type, subscriber);
+    }
+    /**
+     * Subscribe to all events. Wildcard subscribers receive an envelope
+     * `{ event: string, data: OwnsuiteEvent }` — see `@marianmeres/pubsub`.
+     */
+    onAny(subscriber) {
+        return this.#pubsub.subscribe("*", subscriber);
+    }
+    /** Reset all domains to initializing state. */
+    reset() {
+        for (const m of this.#domains.values())
+            m.reset();
+    }
+}
+/** Convenience factory matching the ecsuite `createECSuite` convention. */
+export function createOwnsuite(config = {}) {
+    return new Ownsuite(config);
+}

package/dist/types/adapter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @module types/adapter
+ *
+ * Adapter interface for server communication. One adapter instance drives
+ * one owner-scoped domain (a single collection path on the server).
+ *
+ * Implementations typically wrap `fetch()` calls against the stack's
+ * `/me/<collection-path>/mod` endpoints; see `stack-common/ownsuite` for
+ * the matching server-side convention.
+ */
+import type { OwnsuiteContext } from "./state.js";
+/**
+ * Standard list result shape: rows + meta. Matches the collection package's
+ * REST response envelope for consistency, but adapters are free to return
+ * whatever shape their server uses and map it here.
+ */
+export interface OwnedListResult<TRow> {
+    data: TRow[];
+    meta: Record<string, unknown>;
+}
+/**
+ * Standard single-row result shape: one row + meta. Also matches the
+ * collection package's REST envelope.
+ */
+export interface OwnedRowResult<TRow> {
+    data: TRow;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Adapter for a single owner-scoped collection domain.
+ *
+ * Notes for implementors:
+ * - `owner_id` is enforced server-side. Do NOT attempt to pass it from the
+ *   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.
+ */
+export interface OwnedCollectionAdapter<TRow, TCreate = unknown, TUpdate = unknown> {
+    /** List rows owned by the current subject. Query params are implementation-defined. */
+    list(ctx: OwnsuiteContext, query?: Record<string, unknown>): Promise<OwnedListResult<TRow>>;
+    /** Get one row by id (server returns 404 if not owned by subject). */
+    getOne(id: string, ctx: OwnsuiteContext): Promise<OwnedRowResult<TRow>>;
+    /** Create a new row (server stamps owner_id from the authenticated subject). */
+    create(data: TCreate, ctx: OwnsuiteContext): Promise<OwnedRowResult<TRow>>;
+    /** Update a row by id (owner_id is immutable server-side). */
+    update(id: string, data: TUpdate, ctx: OwnsuiteContext): Promise<OwnedRowResult<TRow>>;
+    /** Delete a row by id (404 if not owned). */
+    delete(id: string, ctx: OwnsuiteContext): Promise<boolean>;
+}

package/dist/types/adapter.js

@@ -0,0 +1,11 @@
+/**
+ * @module types/adapter
+ *
+ * Adapter interface for server communication. One adapter instance drives
+ * one owner-scoped domain (a single collection path on the server).
+ *
+ * Implementations typically wrap `fetch()` calls against the stack's
+ * `/me/<collection-path>/mod` endpoints; see `stack-common/ownsuite` for
+ * the matching server-side convention.
+ */
+export {};

package/dist/types/events.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @module types/events
+ *
+ * Event type definitions for the ownsuite event system.
+ */
+import type { DomainError, DomainState } from "./state.js";
+/**
+ * Domain identifier in ownsuite is an arbitrary string (the collection name
+ * or any label the consumer chose), unlike ecsuite's fixed enum of six
+ * domains. Users register their own domains by name.
+ */
+export type DomainName = string;
+/** Event types emitted by the suite. */
+export type OwnsuiteEventType = "domain:state:changed" | "domain:error" | "domain:synced" | "own:list:fetched" | "own:row:fetched" | "own:row:created" | "own:row:updated" | "own:row:deleted";
+/** Base event data. */
+export interface OwnsuiteEventBase {
+    /** Event timestamp */
+    timestamp: number;
+    /** Domain that emitted the event */
+    domain: DomainName;
+}
+/** State change event. */
+export interface StateChangedEvent extends OwnsuiteEventBase {
+    type: "domain:state:changed";
+    previousState: DomainState;
+    newState: DomainState;
+}
+/** Error event. */
+export interface ErrorEvent extends OwnsuiteEventBase {
+    type: "domain:error";
+    error: DomainError;
+}
+/** Sync completed event. */
+export interface SyncedEvent extends OwnsuiteEventBase {
+    type: "domain:synced";
+}
+/** List fetched event. */
+export interface ListFetchedEvent extends OwnsuiteEventBase {
+    type: "own:list:fetched";
+    count: number;
+}
+/** Single row fetched event. */
+export interface RowFetchedEvent extends OwnsuiteEventBase {
+    type: "own:row:fetched";
+    rowId: string;
+}
+/** Row created event. */
+export interface RowCreatedEvent extends OwnsuiteEventBase {
+    type: "own:row:created";
+    rowId: string;
+}
+/** Row updated event. */
+export interface RowUpdatedEvent extends OwnsuiteEventBase {
+    type: "own:row:updated";
+    rowId: string;
+}
+/** Row deleted event. */
+export interface RowDeletedEvent extends OwnsuiteEventBase {
+    type: "own:row:deleted";
+    rowId: string;
+}
+/** All event types union. */
+export type OwnsuiteEvent = StateChangedEvent | ErrorEvent | SyncedEvent | ListFetchedEvent | RowFetchedEvent | RowCreatedEvent | RowUpdatedEvent | RowDeletedEvent;

package/dist/types/events.js

@@ -0,0 +1,6 @@
+/**
+ * @module types/events
+ *
+ * Event type definitions for the ownsuite event system.
+ */
+export {};

package/dist/types/mod.d.ts

@@ -0,0 +1,3 @@
+export * from "./state.js";
+export * from "./events.js";
+export * from "./adapter.js";

package/dist/types/mod.js

@@ -0,0 +1,3 @@
+export * from "./state.js";
+export * from "./events.js";
+export * from "./adapter.js";

package/dist/types/state.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @module types/state
+ *
+ * Core state and context types for ownsuite domain managers.
+ * Mirrors the shape of `@marianmeres/ecsuite` but specialized for
+ * owner-scoped collection CRUD (a single list of rows per domain).
+ */
+/** Domain state progression — identical to ecsuite for ecosystem consistency. */
+export type DomainState = "initializing" | "ready" | "syncing" | "error";
+/** Error information structure. */
+export interface DomainError {
+    /** Error code for programmatic handling */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Operation that failed */
+    operation: string;
+    /** Original error for debugging */
+    originalError?: unknown;
+}
+/** Base state wrapper for all domains. */
+export interface DomainStateWrapper<T> {
+    /** Current domain state */
+    state: DomainState;
+    /** Domain data (null during initialization or after a critical error) */
+    data: T | null;
+    /** Error information when state is "error" */
+    error: DomainError | null;
+    /** Timestamp of last successful sync */
+    lastSyncedAt: number | null;
+}
+/**
+ * Context passed to adapters. Ownsuite does not require the caller to know
+ * its own `ownerId` — the server resolves it from the authenticated subject
+ * via the `/me/*` mount. The context is still provided so adapters can pass
+ * arbitrary host-app data (correlation ids, feature flags, etc.) through.
+ */
+export interface OwnsuiteContext {
+    /** Hint — not used for authorization. The server is authoritative. */
+    subjectId?: string;
+    /** Additional context properties for adapter-specific needs. */
+    [key: string]: unknown;
+}
+/**
+ * State shape for a single owner-scoped collection domain: a list of rows
+ * plus pagination/meta info from the last list operation. Individual-row
+ * operations (get/update/delete) mutate the list in place without replacing
+ * meta, so optimistic updates work naturally.
+ */
+export interface OwnedCollectionState<TRow> {
+    /** Rows owned by the current subject (server-scoped). */
+    rows: TRow[];
+    /** Metadata from the last list response (total count, pagination, etc.). */
+    meta: Record<string, unknown>;
+}

package/dist/types/state.js

@@ -0,0 +1,8 @@
+/**
+ * @module types/state
+ *
+ * Core state and context types for ownsuite domain managers.
+ * Mirrors the shape of `@marianmeres/ecsuite` but specialized for
+ * owner-scoped collection CRUD (a single list of rows per domain).
+ */
+export {};

package/package.json

@@ -0,0 +1,29 @@
+{
+	"name": "@marianmeres/ownsuite",
+	"version": "1.0.1",
+	"type": "module",
+	"main": "dist/mod.js",
+	"types": "dist/mod.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"import": "./dist/mod.js"
+		}
+	},
+	"author": "Marian Meres",
+	"license": "MIT",
+	"dependencies": {
+		"@marianmeres/clog": "^3.15.2",
+		"@marianmeres/collection-types": "^1.36.0",
+		"@marianmeres/http-utils": "^2.5.1",
+		"@marianmeres/pubsub": "^2.4.6",
+		"@marianmeres/store": "^2.4.4"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/marianmeres/ownsuite.git"
+	},
+	"bugs": {
+		"url": "https://github.com/marianmeres/ownsuite/issues"
+	}
+}