@marianmeres/ecsuite 1.3.2 → 2.1.0

package/dist/suite.js

@@ -12,6 +12,15 @@ import { OrderManager } from "./domains/order.js";
 import { CustomerManager } from "./domains/customer.js";
 import { PaymentManager } from "./domains/payment.js";
 import { ProductManager } from "./domains/product.js";
+/** Combine multiple unsubscribers into one (also `Symbol.dispose`-compatible). */
+function combineUnsubscribers(...unsubs) {
+    const fn = () => {
+        for (const u of unsubs)
+            u();
+    };
+    fn[Symbol.dispose] = fn;
+    return fn;
+}
 /**
  * Main ECSuite class - orchestrates all e-commerce domain managers.
  *
@@ -33,6 +42,21 @@ export class ECSuite {
     #clog = createClog("ecsuite", { color: "auto" });
     #pubsub;
     #context;
+    #initDomains;
+    #autoResetOnIdentityChange;
+    /**
+     * Resolves when the most recent `initialize()` (auto or manual, including
+     * the one triggered by an identity switch) has settled. Always available;
+     * defaults to `Promise.resolve()` if `autoInitialize: false`.
+     *
+     * @example
+     * ```typescript
+     * const suite = createECSuite({ adapters: { cart } });
+     * await suite.ready;            // wait for initial fetches
+     * await suite.cart.addItem(...);
+     * ```
+     */
+    ready = Promise.resolve();
     /** Cart domain manager */
     cart;
     /** Wishlist domain manager */
@@ -52,6 +76,8 @@ export class ECSuite {
         });
         this.#pubsub = createPubSub();
         this.#context = config.context ?? {};
+        this.#initDomains = config.initializeDomains;
+        this.#autoResetOnIdentityChange = config.autoResetOnIdentityChange !== false;
         const storageType = config.storage?.type ?? "local";
         // Initialize domain managers with shared pubsub
         this.cart = new CartManager({
@@ -89,9 +115,10 @@ export class ECSuite {
             pubsub: this.#pubsub,
             cacheTtl: config.productCacheTtl,
         });
-        // Auto-initialize if configured
+        // Auto-initialize if configured. `ready` exposes the in-flight promise
+        // so callers don't race the constructor.
         if (config.autoInitialize !== false) {
-            this.initialize(config.initializeDomains);
+            this.ready = this.initialize(this.#initDomains);
         }
     }
     /** Initialize domains. When called without arguments, initializes all domains.
@@ -118,15 +145,55 @@ export class ECSuite {
             "order",
             "customer",
             "payment",
+            "product",
         ];
-        const toInit = domains ?? all;
+        const toInit = domains ?? this.#initDomains ?? all;
+        // Remember the most recently initialized set so identity switches
+        // (and other re-inits) re-fetch the same domains.
+        this.#initDomains = toInit;
         this.#clog.debug("initializing domains", toInit);
         await Promise.all(toInit.map((name) => this[name].initialize()));
         this.#clog.debug("domains initialized", toInit);
     }
-    /** Update context across all domains */
+    /**
+     * Update context across all domains.
+     *
+     * If `customerId` transitions (including to/from undefined) and
+     * `autoResetOnIdentityChange` is enabled (default), this also resets
+     * all domains and re-initializes them — assigning the new in-flight
+     * promise to `ready`. Callers that need to wait for the new identity's
+     * data should `await suite.ready` afterwards (or use `switchIdentity`).
+     */
     setContext(context) {
         this.#clog.debug("setContext", context);
+        const prevCustomerId = this.#context.customerId;
+        this.#context = { ...this.#context, ...context };
+        this.cart.setContext(context);
+        this.wishlist.setContext(context);
+        this.order.setContext(context);
+        this.customer.setContext(context);
+        this.payment.setContext(context);
+        this.product.setContext(context);
+        const newCustomerId = this.#context.customerId;
+        if (this.#autoResetOnIdentityChange && prevCustomerId !== newCustomerId) {
+            this.#clog.debug("identity changed; resetting domains", {
+                from: prevCustomerId,
+                to: newCustomerId,
+            });
+            this.reset();
+            this.ready = this.initialize(this.#initDomains);
+        }
+    }
+    /**
+     * Atomically switch to a new identity: merge context, reset all domains,
+     * and re-initialize. Returns a promise that settles when the re-init
+     * completes. Use this instead of `setContext` when you need to await
+     * the identity switch (also updates `suite.ready`).
+     *
+     * Works even when `autoResetOnIdentityChange: false`.
+     */
+    async switchIdentity(context) {
+        this.#clog.debug("switchIdentity", context);
         this.#context = { ...this.#context, ...context };
         this.cart.setContext(context);
         this.wishlist.setContext(context);
@@ -134,6 +201,9 @@ export class ECSuite {
         this.customer.setContext(context);
         this.payment.setContext(context);
         this.product.setContext(context);
+        this.reset();
+        this.ready = this.initialize(this.#initDomains);
+        await this.ready;
     }
     /** Get the current context */
     getContext() {
@@ -186,10 +256,7 @@ export class ECSuite {
                 error: event.error,
             });
         });
-        return () => {
-            unsub1();
-            unsub2();
-        };
+        return combineUnsubscribers(unsub1, unsub2);
     }
     /** Reset all domains to initial state */
     reset() {
@@ -201,6 +268,21 @@ export class ECSuite {
         this.payment.reset();
         this.product.clearCache();
     }
+    /**
+     * Tear down the suite: unsubscribe all listeners on the internal pubsub
+     * and clear the product cache. Use when the consumer (e.g., a SPA
+     * lifecycle hook) is done with the suite — long-lived apps that recreate
+     * suites otherwise leak subscribers across instances.
+     *
+     * Persisted storage is intentionally NOT cleared (cart/wishlist data
+     * should survive page reloads); call `reset()` first if you also want
+     * to wipe in-memory state.
+     */
+    destroy() {
+        this.#clog.debug("destroy");
+        this.product.clearCache();
+        this.#pubsub.unsubscribeAll();
+    }
 }
 /**
  * Factory function to create an ECSuite instance.

package/dist/types/adapter.d.ts

@@ -18,8 +18,6 @@ export interface CartAdapter {
     removeItem(productId: UUID, ctx: DomainContext): Promise<CartData>;
     /** Clear all items */
     clear(ctx: DomainContext): Promise<CartData>;
-    /** Sync full cart state (for optimistic update reconciliation) */
-    sync(cart: CartData, ctx: DomainContext): Promise<CartData>;
 }
 /** Wishlist adapter interface */
 export interface WishlistAdapter {
@@ -31,18 +29,23 @@ export interface WishlistAdapter {
     removeItem(productId: UUID, ctx: DomainContext): Promise<WishlistData>;
     /** Clear all items */
     clear(ctx: DomainContext): Promise<WishlistData>;
-    /** Sync full wishlist state */
-    sync(wishlist: WishlistData, ctx: DomainContext): Promise<WishlistData>;
 }
 /** Order create payload (status is set by server) */
 export type OrderCreatePayload = Omit<OrderData, "status">;
 export type { OrderCreateResult } from "@marianmeres/collection-types";
-/** Order adapter interface (read + create) */
+/**
+ * Order adapter interface (read + create).
+ *
+ * All read/create methods return `OrderCreateResult` (`{ model_id, data }`)
+ * so the manager can identify orders by their server-assigned `model_id`.
+ * Returning bare `OrderData` previously made dedup/update impossible because
+ * `OrderData` has no `model_id` field — only an open index signature.
+ */
 export interface OrderAdapter {
     /** Fetch all orders for customer */
-    fetchAll(ctx: DomainContext): Promise<OrderData[]>;
+    fetchAll(ctx: DomainContext): Promise<OrderCreateResult[]>;
     /** Fetch single order by ID */
-    fetchOne(orderId: UUID, ctx: DomainContext): Promise<OrderData>;
+    fetchOne(orderId: UUID, ctx: DomainContext): Promise<OrderCreateResult>;
     /** Create new order — returns data + model_id */
     create(order: OrderCreatePayload, ctx: DomainContext): Promise<OrderCreateResult>;
 }

package/dist/types/events.d.ts

@@ -8,8 +8,12 @@ import type { UUID } from "@marianmeres/collection-types";
 import type { DomainError, DomainState } from "./state.js";
 /** Domain identifiers */
 export type DomainName = "cart" | "wishlist" | "order" | "customer" | "payment" | "product";
-/** Domain names that support initialize() (excludes product which is fully lazy) */
-export type InitializableDomainName = Exclude<DomainName, "product">;
+/**
+ * Domain names that support `initialize()`. As of the unified ProductManager,
+ * every domain implements initialize() — for product it is a no-op that
+ * transitions to "ready" so consumers can rely on the same readiness contract.
+ */
+export type InitializableDomainName = DomainName;
 /** Event types emitted by the suite */
 export type ECSuiteEventType = "domain:state:changed" | "domain:error" | "domain:synced" | "cart:item:added" | "cart:item:updated" | "cart:item:removed" | "cart:cleared" | "wishlist:item:added" | "wishlist:item:removed" | "wishlist:cleared" | "order:created" | "order:fetched" | "customer:updated" | "customer:fetched" | "payment:fetched" | "payment:initiated" | "payment:captured" | "product:fetched";
 /** Base event data */

package/dist/types/state.d.ts

@@ -35,6 +35,8 @@ export interface DomainContext {
     customerId?: UUID;
     /** Optional session ID */
     sessionId?: UUID;
+    /** Optional JWT forwarded to HTTP adapters as `Authorization: Bearer <jwt>`. */
+    jwt?: string;
     /** Additional context properties for adapter-specific needs */
     [key: string]: unknown;
 }

package/docs/future-improvements.md

@@ -0,0 +1,116 @@
+# Ecsuite — Future Improvements
+
+A design review of the current client-side data-flow model, with gaps to consider as usage grows. Not a commitment — a backlog for discussion.
+
+Companion to `@marianmeres/ownsuite`'s `docs/future-improvements.md`. Both suites share `BaseDomainManager`, so most structural items transfer; this document highlights what applies, what doesn't, and what is ecsuite-specific.
+
+## Context
+
+Ecsuite is a **fixed-domain e-commerce state manager** (cart, wishlist, order, customer, payment, product). Unlike ownsuite's generic owner-scoped CRUD, each manager has domain-specific state shape, persistence, and operations. The design is intentionally closed — a known, curated set of domains — which makes "pluggability" a non-goal.
+
+## Where the current design aligns with best practice
+
+- Store-per-domain FSM exposed as a Svelte store.
+- Optimistic updates with rollback on cart/wishlist/customer.
+- Optimistic `create` for cart items with client-assigned temp id, swapped on server response (correct pattern).
+- `localStorage` persistence for cart/wishlist survives reload without a round-trip.
+- ProductManager uses a TTL cache to avoid redundant fetches.
+- Transport-agnostic adapter boundary per domain; full mock coverage for tests.
+- Typed pubsub event bus scoped per domain (`cart:*`, `order:*`, etc.).
+
+## Gaps inherited from the shared base
+
+### 1. No request deduplication or in-flight cancellation
+
+Any domain's `refresh()` can be called twice quickly (route remount, focus event) and produce parallel fetches with a last-write-wins race.
+
+**Possible direction:** track an in-flight promise per operation key; coalesce concurrent callers.
+
+### 2. No `AbortSignal` plumbing through adapters
+
+Component unmount cannot cancel in-flight fetches; results land in a detached store and may overwrite fresher data.
+
+**Possible direction:** thread `AbortSignal` through adapter method signatures; abort on supersession and disposal.
+
+### 3. No staleness / revalidation policy (except ProductManager)
+
+`lastSyncedAt` is tracked but unused on cart/order/customer/payment. No focus/reconnect refetch, no cross-tab sync. ProductManager's TTL is a one-off — no shared cache primitive.
+
+**Possible direction:** lift ProductManager's TTL approach into a reusable base-level option; add optional focus/reconnect listeners behind a flag.
+
+### 4. No per-row pending state during optimistic updates — **acute here**
+
+More important in ecsuite than ownsuite: cart UIs routinely need "this line item is updating" spinners. Currently, modifying one cart item flips the whole cart to `syncing`, so consumers can't show a per-line spinner without their own bookkeeping.
+
+**Possible direction:** track pending item ids in state; expose as a `Set<itemId>` alongside `items`.
+
+### 5. Error state couples to data availability
+
+One failed `update` puts the whole domain in `error`, even though `data` is still valid. Consumers must remember to ignore `state === "error"` when `data` exists.
+
+**Possible direction:** decouple — keep `state` at `ready`, surface the last error as a sibling signal (`lastError`).
+
+### 6. `initialize()` swallows errors
+
+Silent boot failure unless you subscribe to `*:error` events.
+
+**Possible direction:** add `suite.hasErrors()` / `suite.getErrors()` helpers.
+
+### 7. Whole-list rollback snapshot
+
+Less critical than in ownsuite — carts/wishlists are small. Flag for later.
+
+## Gaps that apply to specific domains only
+
+### 8. Query-keyed cache — OrderManager (and partly ProductManager)
+
+Order history is naturally filtered/paginated (status, date range). A single `orders` slot can't hold multiple views concurrently. Cart/wishlist/customer/payment are session-singletons and don't need this.
+
+**Possible direction:** upgrade OrderManager to a `queries: Map<queryKey, {...}>` shape; leave singleton managers alone.
+
+### 9. Pagination / infinite-scroll primitives — OrderManager, ProductManager
+
+`meta` is opaque; cursor/offset merging is consumer-implemented. Needed for order history and product listings.
+
+**Possible direction:** first-class `loadMore()` on those managers with a pluggable merge strategy.
+
+## Ecsuite-specific concerns (no ownsuite analogue)
+
+### 10. localStorage persistence — multiple latent issues
+
+- **No cross-tab sync.** Two tabs mutating the cart diverge until one wins on reload. A `storage` event listener would mirror changes.
+- **No schema versioning / migration.** If cart item shape changes between releases, old persisted carts will either crash deserialization or silently corrupt state. A `version` field + migration hook is standard.
+- **No encryption or redaction.** Carts can contain semi-sensitive data (product ids a user browses privately, promo codes). Probably acceptable for e-commerce norms, but worth an explicit decision.
+- **No quota handling.** `localStorage.setItem` can throw on quota-exceeded; currently unhandled.
+
+### 11. Temp-id → real-id swap on optimistic cart `create`
+
+Known-hazardous pattern. Risks:
+
+- Events fired with the temp id before swap — subscribers caching by id see a ghost.
+- Subsequent `update`/`delete` called on a temp id while the server response is in flight — needs either queuing or id remapping.
+- External references (URLs, analytics) captured against a temp id become stale.
+
+**Possible direction:** document the swap contract explicitly; consider buffering mutations until the real id arrives; emit a dedicated `cart:item:id-reconciled` event so subscribers can rekey.
+
+### 12. ProductManager TTL cache is a one-off
+
+Useful, but not reusable. CustomerManager and OrderManager could benefit from the same primitive. See #3.
+
+## Items that do NOT apply
+
+- **Pluggable manager types** — ecsuite is intentionally closed (fixed 6 domains). This is a design contract, not a flaw. (Applies to ownsuite only.)
+
+## Prioritization sketch
+
+Rough order if tackled:
+
+1. **#4 per-row pending on CartManager** — highest user-visible value; UIs want it now.
+2. **#2 AbortSignal** — cheap correctness win.
+3. **#1 dedup** — cheap, removes a class of races.
+4. **#5 decouple error from state** — small API change, big DX win.
+5. **#10 localStorage cross-tab sync + versioning** — bite-sized, prevents real bugs.
+6. **#11 temp-id swap hardening** — audit existing code; document or fix concretely.
+7. **#3 shared TTL/staleness primitive** — lift from ProductManager.
+8. **#8 + #9 query cache & pagination for OrderManager** — defer until a concrete consumer needs it; design together.
+9. Remaining items — opportunistic.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/ecsuite",
-	"version": "1.3.2",
+	"version": "2.1.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
@@ -10,14 +10,23 @@
 			"import": "./dist/mod.js"
 		}
 	},
+	"files": [
+		"dist",
+		"LICENSE",
+		"README.md",
+		"API.md",
+		"AGENTS.md",
+		"CLAUDE.md",
+		"docs"
+	],
 	"author": "Marian Meres",
 	"license": "MIT",
 	"dependencies": {
-		"@marianmeres/clog": "^3.15.2",
-		"@marianmeres/collection-types": "^1.34.0",
-		"@marianmeres/http-utils": "^2.5.1",
-		"@marianmeres/pubsub": "^2.4.6",
-		"@marianmeres/store": "^2.4.4"
+		"@marianmeres/clog": "^3.17.1",
+		"@marianmeres/collection-types": "^1.37.0",
+		"@marianmeres/http-utils": "^2.6.0",
+		"@marianmeres/pubsub": "^3.0.0",
+		"@marianmeres/store": "^3.0.1"
 	},
 	"repository": {
 		"type": "git",