@marianmeres/ecsuite 1.3.2 → 2.0.0

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.

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 */