@marianmeres/ecsuite 1.0.0

package/dist/domains/product.js

@@ -0,0 +1,241 @@
+/**
+ * @module domains/product
+ *
+ * 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.
+ */
+import { createClog } from "@marianmeres/clog";
+import { createPubSub } from "@marianmeres/pubsub";
+/**
+ * Product manager with in-memory 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.
+ *
+ * Features:
+ * - In-memory cache with TTL expiration
+ * - Single and batch product fetching
+ * - Prefetching support for UI optimization
+ * - Event emission on fetch
+ *
+ * @example
+ * ```typescript
+ * const products = new ProductManager({
+ *   adapter: myProductAdapter,
+ *   cacheTtl: 10 * 60 * 1000, // 10 minutes
+ * });
+ *
+ * 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 = {};
+    _cache = new Map();
+    _cacheTtl;
+    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 };
+    }
+    /**
+     * Get the current context.
+     *
+     * @returns Copy of the current context
+     */
+    getContext() {
+        return { ...this._context };
+    }
+    /**
+     * Get a single product by ID.
+     * Returns from cache if valid, otherwise fetches from server.
+     *
+     * @param productId - The product ID to fetch
+     * @returns The product data or null if not found/error
+     * @emits product:fetched - On successful server fetch
+     */
+    async getById(productId) {
+        // Check cache first
+        const cached = this._getFromCache(productId);
+        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 result = await this._adapter.fetchOne(productId, this._context);
+            if (result.success && result.data) {
+                this._setCache(productId, result.data);
+                this._emitFetched(productId);
+                return result.data;
+            }
+            return null;
+        }
+        catch (e) {
+            this._clog.error("getById failed", { productId, error: e });
+            return null;
+        }
+    }
+    /**
+     * Get multiple products by IDs.
+     * Returns from cache when available, fetches missing products in batch.
+     *
+     * @param productIds - Array of product IDs to fetch
+     * @returns Map of productId to ProductData
+     * @emits product:fetched - For each product fetched from server
+     */
+    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) {
+                result.set(id, cached);
+            }
+            else {
+                missingIds.push(id);
+            }
+        }
+        // Fetch missing from server
+        if (missingIds.length > 0 && this._adapter) {
+            this._clog.debug("getByIds: fetching missing", {
+                total: productIds.length,
+                cached: result.size,
+                missing: missingIds.length,
+            });
+            try {
+                const fetchResult = await this._adapter.fetchMany(missingIds, this._context);
+                if (fetchResult.success && fetchResult.data) {
+                    for (const product of fetchResult.data) {
+                        // Products from collection-types have model_id
+                        const productId = product.model_id;
+                        if (productId) {
+                            this._setCache(productId, product);
+                            result.set(productId, product);
+                            this._emitFetched(productId);
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                this._clog.error("getByIds failed", { missingIds, error: e });
+            }
+        }
+        return result;
+    }
+    /**
+     * Prefetch products into cache.
+     * Useful for preloading product data before rendering.
+     *
+     * @param productIds - Array of product IDs to prefetch
+     */
+    async prefetch(productIds) {
+        const missingIds = productIds.filter((id) => !this.isCached(id));
+        if (missingIds.length === 0)
+            return;
+        this._clog.debug("prefetch", { count: missingIds.length });
+        await this.getByIds(missingIds);
+    }
+    /**
+     * Clear the product cache entirely or for a specific product.
+     *
+     * @param productId - Optional product ID to clear (clears all if not provided)
+     */
+    clearCache(productId) {
+        if (productId) {
+            this._cache.delete(productId);
+            this._clog.debug("cache cleared for product", { productId });
+        }
+        else {
+            this._cache.clear();
+            this._clog.debug("cache cleared entirely");
+        }
+    }
+    /**
+     * Check if a product is in the cache and not expired.
+     *
+     * @param productId - The product ID to check
+     * @returns True if the product is cached and valid
+     */
+    isCached(productId) {
+        const entry = this._cache.get(productId);
+        if (!entry)
+            return false;
+        return Date.now() < entry.expiresAt;
+    }
+    /**
+     * Get the current cache size.
+     *
+     * @returns Number of cached products (includes expired entries)
+     */
+    getCacheSize() {
+        return this._cache.size;
+    }
+    /** 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;
+        }
+        return entry.data;
+    }
+    /** Set product in cache */
+    _setCache(productId, data) {
+        this._cache.set(productId, {
+            data,
+            expiresAt: Date.now() + this._cacheTtl,
+        });
+    }
+    /** Emit product:fetched event */
+    _emitFetched(productId) {
+        const event = {
+            type: "product:fetched",
+            domain: "product",
+            timestamp: Date.now(),
+            productId,
+        };
+        this._pubsub.publish(event.type, event);
+    }
+}

package/dist/domains/wishlist.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @module domains/wishlist
+ *
+ * Wishlist domain manager with optimistic updates and localStorage persistence.
+ * Manages wishlist state with automatic server synchronization.
+ */
+import type { UUID } from "@marianmeres/collection-types";
+import type { WishlistAdapter } from "../types/adapter.js";
+import type { EnrichedWishlistItem, WishlistData, WishlistItem } from "../types/state.js";
+import { BaseDomainManager, type BaseDomainOptions } from "./base.js";
+import type { ProductManager } from "./product.js";
+export interface WishlistManagerOptions extends BaseDomainOptions {
+    /** Wishlist adapter for server communication */
+    adapter?: WishlistAdapter;
+}
+/**
+ * Wishlist domain manager with optimistic updates and localStorage persistence.
+ *
+ * Features:
+ * - Automatic localStorage persistence (configurable)
+ * - Optimistic updates with automatic rollback on server error
+ * - Server synchronization via WishlistAdapter
+ * - Toggle functionality for easy add/remove
+ * - Enriched items with product data support
+ *
+ * @example
+ * ```typescript
+ * const wishlist = new WishlistManager({ adapter: myWishlistAdapter });
+ * await wishlist.initialize();
+ *
+ * await wishlist.toggleItem("prod-1"); // Adds item
+ * await wishlist.toggleItem("prod-1"); // Removes item
+ * ```
+ */
+export declare class WishlistManager extends BaseDomainManager<WishlistData, WishlistAdapter> {
+    constructor(options?: WishlistManagerOptions);
+    /** Initialize wishlist (load from storage, then sync with server) */
+    initialize(): Promise<void>;
+    /**
+     * Add a product to the wishlist.
+     * No-op if the product is already in the wishlist.
+     *
+     * @param productId - The product ID to add
+     * @emits wishlist:item:added - On successful addition
+     */
+    addItem(productId: UUID): Promise<void>;
+    /**
+     * Remove a product from the wishlist.
+     *
+     * @param productId - The product ID to remove
+     * @emits wishlist:item:removed - On successful removal
+     */
+    removeItem(productId: UUID): Promise<void>;
+    /**
+     * Toggle a product in the wishlist.
+     * Adds the product if not present, removes it if present.
+     *
+     * @param productId - The product ID to toggle
+     * @returns True if the item was added, false if removed
+     */
+    toggleItem(productId: UUID): Promise<boolean>;
+    /**
+     * Clear all items from the wishlist.
+     *
+     * @emits wishlist:cleared - On successful clear
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the total number of items in the wishlist.
+     *
+     * @returns Total item count
+     */
+    getItemCount(): number;
+    /**
+     * Check if a product is in the wishlist.
+     *
+     * @param productId - The product ID to check
+     * @returns True if the product is in the wishlist
+     */
+    hasProduct(productId: UUID): boolean;
+    /**
+     * Get a wishlist item by product ID.
+     *
+     * @param productId - The product ID to find
+     * @returns The wishlist item or undefined if not found
+     */
+    getItem(productId: UUID): WishlistItem | undefined;
+    /**
+     * Get all product IDs in the wishlist.
+     *
+     * @returns Array of product IDs
+     */
+    getProductIds(): UUID[];
+    /**
+     * Get wishlist items enriched with product data.
+     *
+     * @param productManager - The ProductManager to fetch product data from
+     * @returns Array of enriched wishlist items with product data
+     */
+    getEnrichedItems(productManager: ProductManager): Promise<EnrichedWishlistItem[]>;
+}

package/dist/domains/wishlist.js

@@ -0,0 +1,256 @@
+/**
+ * @module domains/wishlist
+ *
+ * Wishlist domain manager with optimistic updates and localStorage persistence.
+ * Manages wishlist state with automatic server synchronization.
+ */
+import { BaseDomainManager } from "./base.js";
+/**
+ * Wishlist domain manager with optimistic updates and localStorage persistence.
+ *
+ * Features:
+ * - Automatic localStorage persistence (configurable)
+ * - Optimistic updates with automatic rollback on server error
+ * - Server synchronization via WishlistAdapter
+ * - Toggle functionality for easy add/remove
+ * - Enriched items with product data support
+ *
+ * @example
+ * ```typescript
+ * const wishlist = new WishlistManager({ adapter: myWishlistAdapter });
+ * await wishlist.initialize();
+ *
+ * await wishlist.toggleItem("prod-1"); // Adds item
+ * await wishlist.toggleItem("prod-1"); // Removes item
+ * ```
+ */
+export class WishlistManager extends BaseDomainManager {
+    constructor(options = {}) {
+        super("wishlist", {
+            ...options,
+            // Wishlist defaults to localStorage persistence
+            storageKey: options.storageKey ?? "ecsuite:wishlist",
+            storageType: options.storageType ?? "local",
+        });
+        if (options.adapter) {
+            this._adapter = options.adapter;
+        }
+    }
+    /** Initialize wishlist (load from storage, then sync with server) */
+    async initialize() {
+        this._clog.debug("initialize start");
+        const current = this._store.get();
+        // If we have persisted data, use it immediately
+        if (current.data) {
+            this._setState("ready");
+        }
+        // Then sync with server if adapter is available
+        if (this._adapter) {
+            this._setState("syncing");
+            try {
+                const result = await this._adapter.fetch(this._context);
+                if (result.success && result.data) {
+                    this._setData(result.data);
+                    this._markSynced();
+                }
+                else if (result.error) {
+                    this._setError({
+                        code: result.error.code,
+                        message: result.error.message,
+                        operation: "initialize",
+                    });
+                }
+            }
+            catch (e) {
+                this._setError({
+                    code: "FETCH_FAILED",
+                    message: e instanceof Error ? e.message : "Failed to fetch wishlist",
+                    originalError: e,
+                    operation: "initialize",
+                });
+            }
+        }
+        else {
+            // No adapter, just use local storage or create empty wishlist
+            if (!current.data) {
+                this._setData({ items: [] });
+            }
+            this._setState("ready");
+        }
+        this._clog.debug("initialize complete", { itemCount: this.getItemCount() });
+    }
+    /**
+     * Add a product to the wishlist.
+     * No-op if the product is already in the wishlist.
+     *
+     * @param productId - The product ID to add
+     * @emits wishlist:item:added - On successful addition
+     */
+    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)) {
+            return; // Already in wishlist, no-op
+        }
+        const newItem = {
+            product_id: productId,
+            added_at: Date.now(),
+        };
+        await this._withOptimisticUpdate("addItem", () => {
+            const items = [...current.items, newItem];
+            this._setData({ items }, false);
+        }, async () => {
+            if (this._adapter) {
+                const result = await this._adapter.addItem(productId, this._context);
+                if (!result.success) {
+                    throw new Error(result.error?.message ?? "Failed to add item");
+                }
+                return result.data;
+            }
+            return this._store.get().data;
+        }, (serverData) => {
+            if (serverData) {
+                this._setData(serverData);
+            }
+            this._emit({
+                type: "wishlist:item:added",
+                domain: "wishlist",
+                timestamp: Date.now(),
+                productId,
+            });
+        });
+    }
+    /**
+     * Remove a product from the wishlist.
+     *
+     * @param productId - The product ID to remove
+     * @emits wishlist:item:removed - On successful removal
+     */
+    async removeItem(productId) {
+        this._clog.debug("removeItem", { productId });
+        await this._withOptimisticUpdate("removeItem", () => {
+            const current = this._store.get().data ?? { items: [] };
+            const newItems = current.items.filter((i) => i.product_id !== productId);
+            this._setData({ items: newItems }, false);
+        }, async () => {
+            if (this._adapter) {
+                const result = await this._adapter.removeItem(productId, this._context);
+                if (!result.success) {
+                    throw new Error(result.error?.message ?? "Failed to remove item");
+                }
+                return result.data;
+            }
+            return this._store.get().data;
+        }, (serverData) => {
+            if (serverData) {
+                this._setData(serverData);
+            }
+            this._emit({
+                type: "wishlist:item:removed",
+                domain: "wishlist",
+                timestamp: Date.now(),
+                productId,
+            });
+        });
+    }
+    /**
+     * Toggle a product in the wishlist.
+     * Adds the product if not present, removes it if present.
+     *
+     * @param productId - The product ID to toggle
+     * @returns True if the item was added, false if removed
+     */
+    async toggleItem(productId) {
+        this._clog.debug("toggleItem", { productId });
+        if (this.hasProduct(productId)) {
+            await this.removeItem(productId);
+            return false;
+        }
+        else {
+            await this.addItem(productId);
+            return true;
+        }
+    }
+    /**
+     * Clear all items from the wishlist.
+     *
+     * @emits wishlist:cleared - On successful clear
+     */
+    async clear() {
+        this._clog.debug("clear");
+        await this._withOptimisticUpdate("clear", () => {
+            this._setData({ items: [] }, false);
+        }, async () => {
+            if (this._adapter) {
+                const result = await this._adapter.clear(this._context);
+                if (!result.success) {
+                    throw new Error(result.error?.message ?? "Failed to clear wishlist");
+                }
+                return result.data;
+            }
+            return { items: [] };
+        }, () => {
+            this._emit({
+                type: "wishlist:cleared",
+                domain: "wishlist",
+                timestamp: Date.now(),
+            });
+        });
+    }
+    /**
+     * Get the total number of items in the wishlist.
+     *
+     * @returns Total item count
+     */
+    getItemCount() {
+        const data = this._store.get().data;
+        return data?.items.length ?? 0;
+    }
+    /**
+     * Check if a product is in the wishlist.
+     *
+     * @param productId - The product ID to check
+     * @returns True if the product is in the wishlist
+     */
+    hasProduct(productId) {
+        const data = this._store.get().data;
+        return data?.items.some((i) => i.product_id === productId) ?? false;
+    }
+    /**
+     * Get a wishlist item by product ID.
+     *
+     * @param productId - The product ID to find
+     * @returns The wishlist item or undefined if not found
+     */
+    getItem(productId) {
+        const data = this._store.get().data;
+        return data?.items.find((i) => i.product_id === productId);
+    }
+    /**
+     * Get all product IDs in the wishlist.
+     *
+     * @returns Array of product IDs
+     */
+    getProductIds() {
+        const data = this._store.get().data;
+        return data?.items.map((i) => i.product_id) ?? [];
+    }
+    /**
+     * Get wishlist items enriched with product data.
+     *
+     * @param productManager - The ProductManager to fetch product data from
+     * @returns Array of enriched wishlist items with product data
+     */
+    async getEnrichedItems(productManager) {
+        const data = this._store.get().data;
+        if (!data?.items.length)
+            return [];
+        const productIds = data.items.map((i) => i.product_id);
+        const products = await productManager.getByIds(productIds);
+        return data.items.map((item) => ({
+            ...item,
+            product: products.get(item.product_id) ?? null,
+        }));
+    }
+}

package/dist/mod.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @module @marianmeres/ecsuite
+ *
+ * E-commerce frontend UI helper library with optimistic updates,
+ * Svelte-compatible stores, and adapter-based server sync.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createECSuite } from "@marianmeres/ecsuite";
+ *
+ * const suite = createECSuite({
+ *   context: { customerId: "user-123" },
+ *   adapters: { cart: myCartAdapter },
+ * });
+ *
+ * // Subscribe to cart state (Svelte-compatible)
+ * suite.cart.subscribe((state) => {
+ *   console.log(state.state, state.data);
+ * });
+ *
+ * // Add item with optimistic update
+ * await suite.cart.addItem({ product_id: "prod-1", quantity: 2 });
+ * ```
+ */
+export { ECSuite, createECSuite, type ECSuiteConfig } from "./suite.js";
+export * from "./types/mod.js";
+export * from "./domains/mod.js";
+export * from "./adapters/mod.js";

package/dist/mod.js

@@ -0,0 +1,32 @@
+/**
+ * @module @marianmeres/ecsuite
+ *
+ * E-commerce frontend UI helper library with optimistic updates,
+ * Svelte-compatible stores, and adapter-based server sync.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createECSuite } from "@marianmeres/ecsuite";
+ *
+ * const suite = createECSuite({
+ *   context: { customerId: "user-123" },
+ *   adapters: { cart: myCartAdapter },
+ * });
+ *
+ * // Subscribe to cart state (Svelte-compatible)
+ * suite.cart.subscribe((state) => {
+ *   console.log(state.state, state.data);
+ * });
+ *
+ * // Add item with optimistic update
+ * await suite.cart.addItem({ product_id: "prod-1", quantity: 2 });
+ * ```
+ */
+// Main exports
+export { ECSuite, createECSuite } from "./suite.js";
+// Types
+export * from "./types/mod.js";
+// Domain managers (for advanced usage)
+export * from "./domains/mod.js";
+// Adapters (including mock adapters for testing)
+export * from "./adapters/mod.js";