@marianmeres/ecsuite 1.3.2 → 2.1.0

package/dist/domains/payment.js

@@ -141,7 +141,15 @@ export class PaymentManager extends BaseDomainManager {
     async initiate(orderId, config) {
         this.clog.debug("initiate", { orderId });
         if (!this.adapter?.initiate) {
-            return null;
+            // Optional adapter method missing — surface as a typed error so
+            // callers don't conflate "not configured" with "server rejected".
+            const error = {
+                code: "NOT_IMPLEMENTED",
+                message: "PaymentAdapter.initiate is not implemented",
+                operation: "initiate",
+            };
+            this.setError(error);
+            throw new Error(error.message);
         }
         this.setState("syncing");
         try {
@@ -178,7 +186,13 @@ export class PaymentManager extends BaseDomainManager {
     async capture(paymentId) {
         this.clog.debug("capture", { paymentId });
         if (!this.adapter?.capture) {
-            return null;
+            const error = {
+                code: "NOT_IMPLEMENTED",
+                message: "PaymentAdapter.capture is not implemented",
+                operation: "capture",
+            };
+            this.setError(error);
+            throw new Error(error.message);
         }
         this.setState("syncing");
         try {

package/dist/domains/product.d.ts

@@ -3,36 +3,37 @@
  *
  * Product domain manager with in-memory caching.
  *
- * Read-only domain for fetching product data with caching support.
- * Does not use state machine - just a simple cache layer.
+ * Read-only domain for fetching product data with TTL caching. Extends
+ * `BaseDomainManager` for unified observability (subscribe, domain:error,
+ * domain:state:changed) but the per-product cache itself is held in a
+ * private Map — the store's `data` is null because there is no single
+ * aggregate state worth subscribing to (use `getCacheSize()` /
+ * `isCached()` for cache introspection).
  */
-import { type PubSub } from "@marianmeres/pubsub";
 import type { ProductData, UUID } from "@marianmeres/collection-types";
 import type { ProductAdapter } from "../types/adapter.js";
-import type { DomainContext } from "../types/state.js";
+import { BaseDomainManager, type BaseDomainOptions } from "./base.js";
 /** Options for ProductManager */
-export interface ProductManagerOptions {
+export interface ProductManagerOptions extends BaseDomainOptions {
     /** Product adapter for server communication */
     adapter?: ProductAdapter;
-    /** Initial context (customerId, sessionId) */
-    context?: DomainContext;
-    /** Shared pubsub instance for events */
-    pubsub?: PubSub;
     /** Cache TTL in milliseconds (default: 5 minutes) */
     cacheTtl?: number;
 }
 /**
- * Product manager with in-memory caching.
+ * Product manager with in-memory TTL caching.
  *
- * Unlike other domain managers, ProductManager uses a simple cache layer
- * instead of a full state machine. Products are fetched on-demand and cached
- * with a configurable TTL.
+ * Extends `BaseDomainManager` for unified observability (Svelte-compatible
+ * `subscribe`, `domain:state:changed`, `domain:error` events) but skips the
+ * per-product state machine — fetching a single product never transitions
+ * the whole domain into "syncing" because that would be misleading.
  *
  * Features:
- * - In-memory cache with TTL expiration
+ * - In-memory cache with per-entry TTL expiration
  * - Single and batch product fetching
+ * - In-flight request dedup (cache stampede prevention)
  * - Prefetching support for UI optimization
- * - Event emission on fetch
+ * - `domain:error` event emission on adapter failures
  *
  * @example
  * ```typescript
@@ -40,45 +41,30 @@ export interface ProductManagerOptions {
  *   adapter: myProductAdapter,
  *   cacheTtl: 10 * 60 * 1000, // 10 minutes
  * });
+ * await products.initialize();
  *
  * const product = await products.getById("prod-123");
  * const many = await products.getByIds(["prod-1", "prod-2"]);
  * ```
  */
-export declare class ProductManager {
+export declare class ProductManager extends BaseDomainManager<null, ProductAdapter> {
     #private;
     constructor(options?: ProductManagerOptions);
     /**
-     * Set the product adapter for server communication.
-     *
-     * @param adapter - The ProductAdapter implementation
-     */
-    setAdapter(adapter: ProductAdapter): void;
-    /**
-     * Get the current adapter.
-     *
-     * @returns The adapter or null if not set
-     */
-    getAdapter(): ProductAdapter | null;
-    /**
-     * Update context (customerId, sessionId).
-     *
-     * @param context - Context to merge with existing context
-     */
-    setContext(context: DomainContext): void;
-    /**
-     * Get the current context.
-     *
-     * @returns Copy of the current context
+     * Initialize. Lazy domain — there's nothing to fetch eagerly. Just
+     * transitions to "ready" so consumers can rely on the same readiness
+     * contract as other domains.
      */
-    getContext(): DomainContext;
+    initialize(): Promise<void>;
     /**
      * Get a single product by ID.
-     * Returns from cache if valid, otherwise fetches from server.
+     * Returns from cache if valid, otherwise fetches from server. Concurrent
+     * callers for the same id share a single in-flight request.
      *
      * @param productId - The product ID to fetch
-     * @returns The product data or null if not found/error
+     * @returns The product data or null if not found / no adapter
      * @emits product:fetched - On successful server fetch
+     * @emits domain:error - On adapter failure
      */
     getById(productId: UUID): Promise<ProductData | null>;
     /**
@@ -88,6 +74,7 @@ export declare class ProductManager {
      * @param productIds - Array of product IDs to fetch
      * @returns Map of productId to ProductData
      * @emits product:fetched - For each product fetched from server
+     * @emits domain:error - On adapter failure
      */
     getByIds(productIds: UUID[]): Promise<Map<UUID, ProductData>>;
     /**
@@ -116,4 +103,6 @@ export declare class ProductManager {
      * @returns Number of cached products (includes expired entries)
      */
     getCacheSize(): number;
+    /** Reset clears the cache too (overrides base reset). */
+    reset(): void;
 }

package/dist/domains/product.js

@@ -3,23 +3,28 @@
  *
  * Product domain manager with in-memory caching.
  *
- * Read-only domain for fetching product data with caching support.
- * Does not use state machine - just a simple cache layer.
+ * Read-only domain for fetching product data with TTL caching. Extends
+ * `BaseDomainManager` for unified observability (subscribe, domain:error,
+ * domain:state:changed) but the per-product cache itself is held in a
+ * private Map — the store's `data` is null because there is no single
+ * aggregate state worth subscribing to (use `getCacheSize()` /
+ * `isCached()` for cache introspection).
  */
-import { createClog } from "@marianmeres/clog";
-import { createPubSub } from "@marianmeres/pubsub";
+import { BaseDomainManager } from "./base.js";
 /**
- * Product manager with in-memory caching.
+ * Product manager with in-memory TTL caching.
  *
- * Unlike other domain managers, ProductManager uses a simple cache layer
- * instead of a full state machine. Products are fetched on-demand and cached
- * with a configurable TTL.
+ * Extends `BaseDomainManager` for unified observability (Svelte-compatible
+ * `subscribe`, `domain:state:changed`, `domain:error` events) but skips the
+ * per-product state machine — fetching a single product never transitions
+ * the whole domain into "syncing" because that would be misleading.
  *
  * Features:
- * - In-memory cache with TTL expiration
+ * - In-memory cache with per-entry TTL expiration
  * - Single and batch product fetching
+ * - In-flight request dedup (cache stampede prevention)
  * - Prefetching support for UI optimization
- * - Event emission on fetch
+ * - `domain:error` event emission on adapter failures
  *
  * @example
  * ```typescript
@@ -27,88 +32,79 @@ import { createPubSub } from "@marianmeres/pubsub";
  *   adapter: myProductAdapter,
  *   cacheTtl: 10 * 60 * 1000, // 10 minutes
  * });
+ * await products.initialize();
  *
  * const product = await products.getById("prod-123");
  * const many = await products.getByIds(["prod-1", "prod-2"]);
  * ```
  */
-export class ProductManager {
-    #clog = createClog("ecsuite:product", { color: "auto" });
-    #pubsub;
-    #adapter = null;
-    #context = {};
+export class ProductManager extends BaseDomainManager {
     #cache = new Map();
     #cacheTtl;
+    /** Pending fetches by id, used to dedup concurrent callers (D8). */
+    #inflight = new Map();
     constructor(options = {}) {
-        this.#adapter = options.adapter ?? null;
-        this.#context = options.context ?? {};
-        this.#pubsub = options.pubsub ?? createPubSub();
-        this.#cacheTtl = options.cacheTtl ?? 5 * 60 * 1000; // 5 minutes default
-        this.#clog.debug("initialized", { cacheTtl: this.#cacheTtl });
-    }
-    /**
-     * Set the product adapter for server communication.
-     *
-     * @param adapter - The ProductAdapter implementation
-     */
-    setAdapter(adapter) {
-        this.#adapter = adapter;
-        this.#clog.debug("adapter set");
-    }
-    /**
-     * Get the current adapter.
-     *
-     * @returns The adapter or null if not set
-     */
-    getAdapter() {
-        return this.#adapter;
-    }
-    /**
-     * Update context (customerId, sessionId).
-     *
-     * @param context - Context to merge with existing context
-     */
-    setContext(context) {
-        this.#context = { ...this.#context, ...context };
+        super("product", {
+            ...options,
+            // Cache lives in a private Map; the store's `data` carries no
+            // aggregate so persistence is meaningless here.
+            storageType: null,
+        });
+        if (options.adapter) {
+            this.adapter = options.adapter;
+        }
+        this.#cacheTtl = options.cacheTtl ?? 5 * 60 * 1000;
     }
     /**
-     * Get the current context.
-     *
-     * @returns Copy of the current context
+     * Initialize. Lazy domain — there's nothing to fetch eagerly. Just
+     * transitions to "ready" so consumers can rely on the same readiness
+     * contract as other domains.
      */
-    getContext() {
-        return { ...this.#context };
+    initialize() {
+        this.clog.debug("initialize");
+        this.setState("ready");
+        return Promise.resolve();
     }
     /**
      * Get a single product by ID.
-     * Returns from cache if valid, otherwise fetches from server.
+     * Returns from cache if valid, otherwise fetches from server. Concurrent
+     * callers for the same id share a single in-flight request.
      *
      * @param productId - The product ID to fetch
-     * @returns The product data or null if not found/error
+     * @returns The product data or null if not found / no adapter
      * @emits product:fetched - On successful server fetch
+     * @emits domain:error - On adapter failure
      */
     async getById(productId) {
-        // Check cache first
         const cached = this.#getFromCache(productId);
-        if (cached) {
+        if (cached)
             return cached;
-        }
-        // Fetch from server
-        if (!this.#adapter) {
-            this.#clog.debug("getById: no adapter", { productId });
-            return null;
-        }
-        this.#clog.debug("getById: fetching", { productId });
-        try {
-            const data = await this.#adapter.fetchOne(productId, this.#context);
-            this.#setCache(productId, data);
-            this.#emitFetched(productId);
-            return data;
-        }
-        catch (e) {
-            this.#clog.error("getById failed", { productId, error: e });
+        if (!this.adapter) {
+            this.clog.debug("getById: no adapter", { productId });
             return null;
         }
+        // Dedup concurrent callers (cache stampede prevention)
+        const pending = this.#inflight.get(productId);
+        if (pending)
+            return pending;
+        const promise = (async () => {
+            this.clog.debug("getById: fetching", { productId });
+            try {
+                const data = await this.adapter.fetchOne(productId, this.context);
+                this.#setCache(productId, data);
+                this.#emitFetched(productId);
+                return data;
+            }
+            catch (e) {
+                this.#emitError("getById", e, { productId });
+                return null;
+            }
+            finally {
+                this.#inflight.delete(productId);
+            }
+        })();
+        this.#inflight.set(productId, promise);
+        return promise;
     }
     /**
      * Get multiple products by IDs.
@@ -117,11 +113,11 @@ export class ProductManager {
      * @param productIds - Array of product IDs to fetch
      * @returns Map of productId to ProductData
      * @emits product:fetched - For each product fetched from server
+     * @emits domain:error - On adapter failure
      */
     async getByIds(productIds) {
         const result = new Map();
         const missingIds = [];
-        // Check cache for each product
         for (const id of productIds) {
             const cached = this.#getFromCache(id);
             if (cached) {
@@ -131,17 +127,15 @@ export class ProductManager {
                 missingIds.push(id);
             }
         }
-        // Fetch missing from server
-        if (missingIds.length > 0 && this.#adapter) {
-            this.#clog.debug("getByIds: fetching missing", {
+        if (missingIds.length > 0 && this.adapter) {
+            this.clog.debug("getByIds: fetching missing", {
                 total: productIds.length,
                 cached: result.size,
                 missing: missingIds.length,
             });
             try {
-                const fetchedData = await this.#adapter.fetchMany(missingIds, this.#context);
+                const fetchedData = await this.adapter.fetchMany(missingIds, this.context);
                 for (const product of fetchedData) {
-                    // Products from collection-types have model_id
                     const productId = product.model_id;
                     if (productId) {
                         this.#setCache(productId, product);
@@ -151,7 +145,7 @@ export class ProductManager {
                 }
             }
             catch (e) {
-                this.#clog.error("getByIds failed", { missingIds, error: e });
+                this.#emitError("getByIds", e, { missingIds });
             }
         }
         return result;
@@ -166,7 +160,7 @@ export class ProductManager {
         const missingIds = productIds.filter((id) => !this.isCached(id));
         if (missingIds.length === 0)
             return;
-        this.#clog.debug("prefetch", { count: missingIds.length });
+        this.clog.debug("prefetch", { count: missingIds.length });
         await this.getByIds(missingIds);
     }
     /**
@@ -177,11 +171,11 @@ export class ProductManager {
     clearCache(productId) {
         if (productId) {
             this.#cache.delete(productId);
-            this.#clog.debug("cache cleared for product", { productId });
+            this.clog.debug("cache cleared for product", { productId });
         }
         else {
             this.#cache.clear();
-            this.#clog.debug("cache cleared entirely");
+            this.clog.debug("cache cleared entirely");
         }
     }
     /**
@@ -204,13 +198,18 @@ export class ProductManager {
     getCacheSize() {
         return this.#cache.size;
     }
+    /** Reset clears the cache too (overrides base reset). */
+    reset() {
+        this.#cache.clear();
+        this.#inflight.clear();
+        super.reset();
+    }
     /** Get product from cache if valid */
     #getFromCache(productId) {
         const entry = this.#cache.get(productId);
         if (!entry)
             return null;
         if (Date.now() >= entry.expiresAt) {
-            // Expired, remove from cache
             this.#cache.delete(productId);
             return null;
         }
@@ -231,6 +230,25 @@ export class ProductManager {
             timestamp: Date.now(),
             productId,
         };
-        this.#pubsub.publish(event.type, event);
+        this.pubsub.publish(event.type, event);
+    }
+    /**
+     * Emit `domain:error` without changing state. A single failed product
+     * fetch should not blanket the whole domain in "error" — other cached
+     * lookups remain valid.
+     */
+    #emitError(operation, e, context) {
+        this.clog.error(`${operation} failed`, { ...context, error: e });
+        this.emit({
+            type: "domain:error",
+            domain: "product",
+            timestamp: Date.now(),
+            error: {
+                code: "FETCH_FAILED",
+                message: e instanceof Error ? e.message : "Failed to fetch",
+                operation,
+                originalError: e,
+            },
+        });
     }
 }

package/dist/domains/wishlist.js

@@ -80,8 +80,7 @@ export class WishlistManager extends BaseDomainManager {
     async addItem(productId) {
         this.clog.debug("addItem", { productId });
         // Check if already in wishlist
-        const current = this.store.get().data ?? { items: [] };
-        if (current.items.some((i) => i.product_id === productId)) {
+        if (this.hasProduct(productId)) {
             return; // Already in wishlist, no-op
         }
         const newItem = {
@@ -89,6 +88,9 @@ export class WishlistManager extends BaseDomainManager {
             added_at: Date.now(),
         };
         await this.withOptimisticUpdate("addItem", () => {
+            // Re-read inside callback so we operate on the latest state
+            // even if a prior in-flight mutation has just settled.
+            const current = this.store.get().data ?? { items: [] };
             const items = [...current.items, newItem];
             this.setData({ items }, false);
         }, async () => {

package/dist/suite.d.ts

@@ -43,6 +43,13 @@ export interface ECSuiteConfig {
     autoInitialize?: boolean;
     /** Domains to initialize (default: all). Used by both autoInitialize and manual initialize(). */
     initializeDomains?: InitializableDomainName[];
+    /**
+     * Reset and re-initialize all domains automatically when `setContext()`
+     * changes `customerId` (or transitions between guest and authenticated).
+     * Default: `true`. Set to `false` to manage identity transitions yourself
+     * via `switchIdentity()` or explicit `reset()` + `initialize()`.
+     */
+    autoResetOnIdentityChange?: boolean;
 }
 /**
  * Main ECSuite class - orchestrates all e-commerce domain managers.
@@ -63,6 +70,19 @@ export interface ECSuiteConfig {
  */
 export declare class ECSuite {
     #private;
+    /**
+     * 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<void>;
     /** Cart domain manager */
     readonly cart: CartManager;
     /** Wishlist domain manager */
@@ -94,8 +114,25 @@ export declare class ECSuite {
      * ```
      */
     initialize(domains?: InitializableDomainName[]): Promise<void>;
-    /** 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: DomainContext): void;
+    /**
+     * 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`.
+     */
+    switchIdentity(context: DomainContext): Promise<void>;
     /** Get the current context */
     getContext(): DomainContext;
     /** Subscribe to specific event type */
@@ -132,6 +169,17 @@ export declare class ECSuite {
     }) => void): Unsubscriber;
     /** Reset all domains to initial state */
     reset(): void;
+    /**
+     * 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(): void;
 }
 /**
  * Factory function to create an ECSuite instance.