the-foxy-library 1.0.0 → 1.0.2

package/dist/cjs/app-globals-CXkOeBU1.js

@@ -0,0 +1,39 @@
+'use strict';
+
+var index = require('./index-DiBg0RCo.js');
+
+// Idempotent global init (prevents double execution if script loaded twice)
+// Also resolves Stencil v update expecting a default export from globalScript.
+// Flags kept minimal to avoid polluting window.
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+const w = (typeof window !== 'undefined') ? window : {};
+async function intravenousGlobalInit() {
+    try {
+        if (!w.__IV_API_SETUP_DONE) {
+            index.apiSetup();
+            w.__IV_API_SETUP_DONE = true;
+        }
+        if (!w.__IV_CURRENCY_FETCH_DONE) {
+            try {
+                const code = await index.fetchShopifyCurrencyCode();
+                if (code)
+                    index.state.setCurrencyCode(code);
+            }
+            catch (err) {
+                console.debug('[IV] currency fetch skipped', err);
+            }
+            w.__IV_CURRENCY_FETCH_DONE = true;
+        }
+    }
+    catch (err) {
+        console.error('[IV] Global init failed', err);
+    }
+}
+
+const globalScripts = intravenousGlobalInit;
+
+exports.globalScripts = globalScripts;
+//# sourceMappingURL=app-globals-CXkOeBU1.js.map
+
+//# sourceMappingURL=app-globals-CXkOeBU1.js.map

package/dist/cjs/app-globals-CXkOeBU1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-globals-CXkOeBU1.js","sources":["src/global/app.ts","@stencil/core/internal/app-globals"],"sourcesContent":["import { apiSetup, fetchShopifyCurrencyCode } from '../utils/config/factory';\nimport { state } from '../utils/store/store';\n\n// Idempotent global init (prevents double execution if script loaded twice)\n// Also resolves Stencil v update expecting a default export from globalScript.\n// Flags kept minimal to avoid polluting window.\n// eslint-disable-next-line @typescript-eslint/ban-ts-comment\n// @ts-ignore\nconst w: any = (typeof window !== 'undefined') ? window : {};\n\nexport default async function intravenousGlobalInit() {\n  try {\n    if(!w.__IV_API_SETUP_DONE) {\n      apiSetup();\n      w.__IV_API_SETUP_DONE = true;\n    }\n    if(!w.__IV_CURRENCY_FETCH_DONE) {\n      try {\n        const code = await fetchShopifyCurrencyCode();\n        if(code) state.setCurrencyCode(code);\n      } catch (err) {\n        console.debug('[IV] currency fetch skipped', err);\n      }\n      w.__IV_CURRENCY_FETCH_DONE = true;\n    }\n  } catch(err) {\n    console.error('[IV] Global init failed', err);\n  }\n}","import appGlobalScript from 'C:/Users/BeauBuxton/OneDrive - Herd Agency Limited/Documents/ending/intravenous/src/global/app.ts';\nexport const globalScripts = appGlobalScript;\nexport const globalStyles = \"\";\n"],"names":["apiSetup","fetchShopifyCurrencyCode","state","appGlobalScript"],"mappings":";;;;AAGA;AACA;AACA;AACA;AACA;AACA,MAAM,CAAC,GAAQ,CAAC,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,GAAG,EAAE;AAE7C,eAAe,qBAAqB,GAAA;AACjD,IAAA,IAAI;AACF,QAAA,IAAG,CAAC,CAAC,CAAC,mBAAmB,EAAE;AACzB,YAAAA,cAAQ,EAAE;AACV,YAAA,CAAC,CAAC,mBAAmB,GAAG,IAAI;;AAE9B,QAAA,IAAG,CAAC,CAAC,CAAC,wBAAwB,EAAE;AAC9B,YAAA,IAAI;AACF,gBAAA,MAAM,IAAI,GAAG,MAAMC,8BAAwB,EAAE;AAC7C,gBAAA,IAAG,IAAI;AAAE,oBAAAC,WAAK,CAAC,eAAe,CAAC,IAAI,CAAC;;YACpC,OAAO,GAAG,EAAE;AACZ,gBAAA,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,GAAG,CAAC;;AAEnD,YAAA,CAAC,CAAC,wBAAwB,GAAG,IAAI;;;IAEnC,OAAM,GAAG,EAAE;AACX,QAAA,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,GAAG,CAAC;;AAEjD;;AC3BY,MAAC,aAAa,GAAGC;;;;"}

package/dist/cjs/factory-CIGw8cuP.js

@@ -0,0 +1,37 @@
+'use strict';
+
+function decodeJsonString(str) {
+    return str.replace(/"/g, '"');
+}
+function requestedFields(fields) {
+    return fields ? fields.split(',').map(f => f.trim()) : null;
+}
+function formatMoney(amount, currencyCode = 'GBP', locale = 'en-GB') {
+    // return new Intl.NumberFormat(locale, { style: 'currency', currency: currencyCode }).format(amount / 100);
+    return new Intl.NumberFormat(locale, { style: 'currency', currency: currencyCode }).format(amount);
+}
+function getCurrencySymbol(currencyCode = 'GBP', locale = 'en-GB') {
+    return (0).toLocaleString(locale, {
+        style: 'currency',
+        currency: currencyCode,
+        minimumFractionDigits: 0,
+        maximumFractionDigits: 0
+    }).replace(/\d/g, '').trim();
+}
+function getProductIDFromGid(id) {
+    return Number(id.split('/').pop());
+}
+function getProductHandle() {
+    const path = window.location.pathname;
+    return path.startsWith('/products/') ? path.replace('/products/', '').split('/')[0] : null;
+}
+
+exports.decodeJsonString = decodeJsonString;
+exports.formatMoney = formatMoney;
+exports.getCurrencySymbol = getCurrencySymbol;
+exports.getProductHandle = getProductHandle;
+exports.getProductIDFromGid = getProductIDFromGid;
+exports.requestedFields = requestedFields;
+//# sourceMappingURL=factory-CIGw8cuP.js.map
+
+//# sourceMappingURL=factory-CIGw8cuP.js.map

package/dist/cjs/factory-CIGw8cuP.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory-CIGw8cuP.js","sources":["src/utils/helpers/factory.ts"],"sourcesContent":["export function decodeJsonString(str: string): string {\n  return str.replace(/"/g, '\"');\n};\n\nexport function requestedFields(fields: string): string[] | null {\n  return fields ? fields.split(',').map(f => f.trim()) : null;\n}; \n\nexport function formatMoney(amount: number, currencyCode: string = 'GBP', locale: string = 'en-GB'): string {\n  // return new Intl.NumberFormat(locale, { style: 'currency', currency: currencyCode }).format(amount / 100);\n  return new Intl.NumberFormat(locale, { style: 'currency', currency: currencyCode }).format(amount);\n};\n\nexport function getCurrencySymbol(currencyCode: string = 'GBP', locale: string = 'en-GB'): string {\n  return (0).toLocaleString(locale, {\n    style: 'currency',\n    currency: currencyCode,\n    minimumFractionDigits: 0,\n    maximumFractionDigits: 0\n  }).replace(/\\d/g, '').trim();\n};\n\nexport function getProductIDFromGid(id: string): number {\n  return Number(id.split('/').pop()); \n};\n\nexport function getProductHandle(): string {\n  const path = window.location.pathname;\n  return path.startsWith('/products/') ? path.replace('/products/', '').split('/')[0] : null;\n};"],"names":[],"mappings":";;AAAM,SAAU,gBAAgB,CAAC,GAAW,EAAA;IAC1C,OAAO,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;AACpC;AAEM,SAAU,eAAe,CAAC,MAAc,EAAA;IAC5C,OAAO,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;AAC7D;AAEM,SAAU,WAAW,CAAC,MAAc,EAAE,YAAuB,GAAA,KAAK,EAAE,MAAA,GAAiB,OAAO,EAAA;;IAEhG,OAAO,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;AACpG;AAEM,SAAU,iBAAiB,CAAC,eAAuB,KAAK,EAAE,SAAiB,OAAO,EAAA;AACtF,IAAA,OAAO,CAAC,CAAC,EAAE,cAAc,CAAC,MAAM,EAAE;AAChC,QAAA,KAAK,EAAE,UAAU;AACjB,QAAA,QAAQ,EAAE,YAAY;AACtB,QAAA,qBAAqB,EAAE,CAAC;AACxB,QAAA,qBAAqB,EAAE;KACxB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE;AAC9B;AAEM,SAAU,mBAAmB,CAAC,EAAU,EAAA;AAC5C,IAAA,OAAO,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;AACpC;SAEgB,gBAAgB,GAAA;AAC9B,IAAA,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ;AACrC,IAAA,OAAO,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;AAC5F;;;;;;;;;"}

package/dist/cjs/factory-CffqQl1G.js

@@ -0,0 +1,580 @@
+'use strict';
+
+var index = require('./index-DiBg0RCo.js');
+
+/*
+  Generic caching factory for component data (and optionally pre-rendered markup).
+  Focus: Avoid repeated Storefront API calls across page loads & multiple instances.
+
+  Strategy:
+  - Cache normalized data (preferred) so Stencil still renders & binds events.
+  - Optional markup caching (only for fully static / idempotent HTML) via setMarkup/getMarkup helpers.
+  - Deterministic key: namespace + stable-hash(params + version + type).
+  - Supports localStorage / sessionStorage / memory fallback.
+  - TTL + optional staleWhileRevalidate.
+  - Inflight request dedupe (single network fetch per key at a time).
+  - Event emission (CustomEvent 'iv-cache') for diagnostics (hit/miss/stale/set/purge/error).
+
+  IMPORTANT NOTE ABOUT MARKUP CACHING:
+  Injecting raw cached markup can skip Stencil lifecycle & event listener binding.
+  Prefer data caching and regular render path. Use markup caching only for static read-only fragments.
+*/
+function createCache(options) {
+    const { namespace, version = '1', storage = 'local', prefix = 'iv:cache:', defaultTTL = 1000 * 60 * 5, staleTTL, maxEntries = 200, maxValueBytes = 250_000, // ~250 KB safety guard
+    serialize = JSON.stringify, deserialize = JSON.parse, dispatchEvents = true, target = (typeof window !== 'undefined' ? window : undefined) } = options;
+    const adapter = resolveAdapter(storage);
+    const inflight = new Map();
+    let opCount = 0;
+    function emit(action, key, info) {
+        if (!dispatchEvents || !target || typeof target.dispatchEvent !== 'function')
+            return;
+        try {
+            const detail = { action, key, namespace, info };
+            target.dispatchEvent(new CustomEvent('iv-cache', { detail, bubbles: true, composed: true }));
+        }
+        catch (_) { }
+    }
+    function stableString(obj) {
+        if (obj === null)
+            return 'null';
+        const type = typeof obj;
+        if (type !== 'object')
+            return JSON.stringify(obj);
+        if (Array.isArray(obj))
+            return '[' + obj.map(stableString).join(',') + ']';
+        const keys = Object.keys(obj).sort();
+        return '{' + keys.map(k => JSON.stringify(k) + ':' + stableString(obj[k])).join(',') + '}';
+    }
+    function hash(str) {
+        let h = 5381, i = str.length;
+        while (i)
+            h = (h * 33) ^ str.charCodeAt(--i);
+        return (h >>> 0).toString(36);
+    }
+    function buildKey(type, params) {
+        const base = stableString(params);
+        return `${prefix}${namespace}:${type}:${version}:${hash(base)}`;
+    }
+    function read(key) {
+        try {
+            const rawStr = adapter.getItem(key);
+            if (!rawStr)
+                return { isExpired: true, isStale: false, ageMs: 0 };
+            const stored = deserialize(rawStr);
+            if (!stored || stored.v !== version)
+                return { isExpired: true, isStale: false, ageMs: 0 };
+            const ageMs = Date.now() - stored.ts;
+            const isExpired = ageMs > stored.ttl;
+            const isStale = isExpired && staleTTL ? ageMs <= stored.ttl + staleTTL : false;
+            return { data: stored.data, meta: stored.meta, isExpired, isStale, ageMs, raw: stored };
+        }
+        catch (err) {
+            emit('error', key, { err: err?.message });
+            return { isExpired: true, isStale: false, ageMs: 0 };
+        }
+    }
+    function write(key, type, data, cfg) {
+        const ttl = cfg?.ttl ?? defaultTTL;
+        const stored = { v: version, ts: Date.now(), ttl, t: type, data, meta: cfg?.meta };
+        try {
+            const payload = serialize(stored);
+            if (maxValueBytes && byteLength(payload) > maxValueBytes) {
+                emit('error', key, { reason: 'oversize', bytes: byteLength(payload) });
+                return;
+            }
+            adapter.setItem(key, payload);
+            emit('set', key, { ttl, type });
+            enforceLimit();
+        }
+        catch (err) {
+            emit('error', key, { err: err?.message });
+        }
+    }
+    function get(key) {
+        const res = read(key);
+        if (res.data && !res.isExpired)
+            emit('hit', key, { ageMs: res.ageMs });
+        else if (res.data && res.isExpired && res.isStale)
+            emit('stale', key, { ageMs: res.ageMs });
+        else
+            emit('miss', key);
+        return res;
+    }
+    async function getOrSet(key, type, fetcher, opts) {
+        const existing = get(key);
+        if (existing.data && !existing.isExpired)
+            return existing.data;
+        if (existing.data && existing.isStale && opts?.staleWhileRevalidate) {
+            // return stale, refresh in background
+            refresh(key, type, fetcher, opts);
+            return existing.data;
+        }
+        if (inflight.has(key))
+            return inflight.get(key);
+        const p = (async () => {
+            try {
+                const raw = await fetcher();
+                const transformed = opts?.transform ? opts.transform(raw) : raw;
+                write(key, type, transformed, { ttl: opts?.ttl, meta: opts?.meta });
+                return transformed;
+            }
+            finally {
+                inflight.delete(key);
+            }
+        })();
+        inflight.set(key, p);
+        return p;
+    }
+    function refresh(key, type, fetcher, opts) {
+        return getOrSet(key, type, fetcher, opts); // reuse logic
+    }
+    function purge(key) {
+        adapter.removeItem(key);
+        emit('purge', key);
+    }
+    function purgePattern(pattern) {
+        const keys = adapter.keys();
+        for (const k of keys) {
+            if (!k.startsWith(`${prefix}${namespace}:`))
+                continue;
+            const matched = typeof pattern === 'function' ? pattern(k) : pattern.test(k);
+            if (matched)
+                purge(k);
+        }
+    }
+    function clearNamespace() { purgePattern(() => true); }
+    function enforceLimit() {
+        if (!adapter.keys)
+            return;
+        opCount++;
+        // only enforce every 20 writes to reduce overhead
+        if (opCount % 20 !== 0)
+            return;
+        const keys = adapter.keys().filter(k => k.startsWith(`${prefix}${namespace}:`));
+        if (keys.length <= maxEntries)
+            return;
+        const arr = keys.map(k => {
+            try {
+                const raw = deserialize(adapter.getItem(k));
+                return { k, ts: raw?.ts || 0 };
+            }
+            catch {
+                return { k, ts: 0 };
+            }
+        }).sort((a, b) => a.ts - b.ts); // oldest first
+        const removeCount = keys.length - maxEntries;
+        arr.slice(0, removeCount).forEach(e => { purge(e.k); emit('evict', e.k); });
+    }
+    // Convenience wrappers for common patterns
+    function keyForData(params) { return buildKey('data', params); }
+    function keyForMarkup(params) { return buildKey('markup', params); }
+    function setData(params, data, cfg) {
+        write(keyForData(params), 'data', data, cfg);
+    }
+    function getData(params) {
+        return get(keyForData(params));
+    }
+    function getOrSetData(params, fetcher, opts) {
+        return getOrSet(keyForData(params), 'data', fetcher, opts);
+    }
+    function setMarkup(params, html, cfg) {
+        write(keyForMarkup(params), 'markup', html, cfg);
+    }
+    function getMarkup(params) {
+        return get(keyForMarkup(params));
+    }
+    function getOrSetMarkup(params, producer, opts) {
+        return getOrSet(keyForMarkup(params), 'markup', producer, opts);
+    }
+    return {
+        // generic
+        buildKey,
+        get,
+        set: write,
+        getOrSet,
+        refresh,
+        purge,
+        purgePattern,
+        clearNamespace,
+        inflight,
+        // data-specific helpers
+        keyForData,
+        getData,
+        setData,
+        getOrSetData,
+        // markup-specific helpers
+        keyForMarkup,
+        getMarkup,
+        setMarkup,
+        getOrSetMarkup
+    };
+}
+function resolveAdapter(sel) {
+    if (sel === 'memory')
+        return createMemoryAdapter();
+    const store = safeStorage(sel === 'session' ? 'session' : 'local');
+    if (!store)
+        return createMemoryAdapter();
+    return {
+        getItem: k => store.getItem(k),
+        setItem: (k, v) => store.setItem(k, v),
+        removeItem: k => store.removeItem(k),
+        keys: () => {
+            const arr = [];
+            for (let i = 0; i < store.length; i++) {
+                const key = store.key(i);
+                if (key)
+                    arr.push(key);
+            }
+            return arr;
+        }
+    };
+}
+function safeStorage(type) {
+    try {
+        if (typeof window === 'undefined')
+            return undefined;
+        const s = type === 'local' ? window.localStorage : window.sessionStorage;
+        const testKey = '__iv_cache_test__';
+        s.setItem(testKey, '1');
+        s.removeItem(testKey);
+        return s;
+    }
+    catch {
+        return undefined;
+    }
+}
+function createMemoryAdapter() {
+    const map = new Map();
+    return {
+        getItem: k => map.get(k) || null,
+        setItem: (k, v) => { map.set(k, v); },
+        removeItem: k => { map.delete(k); },
+        keys: () => Array.from(map.keys())
+    };
+}
+function byteLength(str) {
+    if (typeof Blob !== 'undefined')
+        return new Blob([str]).size;
+    // fallback rough estimate
+    return encodeURIComponent(str).replace(/%../g, 'x').length;
+}
+/*
+USAGE EXAMPLES (iv-dynamic-products):
+
+import { createCache } from '../../utils/caching/factory';
+import { fetchProducts } from '../../utils/storefront_api/factory';
+
+const productCache = createCache({
+  namespace: 'iv-dynamic-products',
+  version: '1',
+  storage: 'local',
+  defaultTTL: 1000 * 60 * 5,        // 5 minutes fresh
+  staleTTL: 1000 * 60 * 5           // additional 5 minutes stale window
+});
+
+async function loadProducts(params) {
+  const data = await productCache.getOrSetData(
+    { handle: params.handle, sort: params.sort, fields: params.fields, limit: params.limit, currency: params.currency },
+    () => fetchProducts(params),
+    { ttl: 1000 * 60 * 5, staleWhileRevalidate: true }
+  );
+  // assign to component state & let Stencil render
+  this.products = data;
+}
+
+// Optional MARKUP caching (only if safe & static):
+async function getMarkupFast(params) {
+  return productCache.getOrSetMarkup(
+    { handle: params.handle, sort: params.sort, limit: params.limit },
+    async () => {
+      const data = await fetchProducts(params);
+      // build HTML string (ensure no dynamic listeners needed)
+      return data.map(p => `<div class=\"iv-card\">${p.title}</div>`).join('');
+    },
+    { ttl: 1000 * 60 * 2, staleWhileRevalidate: true }
+  );
+}
+
+/*
+============================================================
+CACHING FACTORY – USAGE & RATIONALE NOTES
+============================================================
+Purpose:
+  Provide a unified, lightweight, observable cache for normalized DATA (preferred) and optionally static MARKUP.
+  Designed to prevent redundant Shopify Storefront API calls across multiple component instances / navigations.
+
+Core Concepts:
+  Key Derivation: stable, deterministic hash of (params + namespace + version + type).
+  Data vs Markup: Markup support exists but is discouraged for interactive Stencil components (event binding loss).
+  Fresh vs Stale vs Expired:
+    - fresh: age <= ttl
+    - expired + stale window active: treat as stale (returned immediately if staleWhileRevalidate enabled)
+    - expired beyond stale window: treated as miss
+  Stale‑While‑Revalidate: returns stale value immediately while background refresh updates cache.
+  Inflight Dedupe: concurrent requests for same key share the same Promise.
+  Size Guard: prevents storing overly large payloads (default ~250KB serialized).
+  Soft Eviction: oldest entries removed when exceeding maxEntries (checked every 20 writes).
+  Events: CustomEvent 'iv-cache' with actions (hit|miss|stale|set|purge|error|evict) for telemetry / debugging.
+
+Recommended Usage Pattern (Data):
+  1. Create one shared cache per domain concern (e.g. productCache, predictiveSearchCache).
+  2. Always cache normalized data objects – keep UI rendering inside Stencil.
+  3. Include parameters that materially affect the response in the key params object (collection handle, sort key, limit, currency).
+  4. Use staleWhileRevalidate for UX smoothness (fast paint + silent refresh).
+  5. Avoid caching partial markup for interactive components.
+
+Example (Products):
+  import { productCache } from '../caching/productCache';
+  import { fetchProducts } from '../storefront_api/factory';
+  const products = await productCache.getOrSetData(
+    { handle, sort, limit, fields, currency },
+    () => fetchProducts({ collectionHandle: handle, sortKey: sort, limit, fields }),
+    { ttl: 1000 * 60 * 5, staleWhileRevalidate: true }
+  );
+
+Deciding TTL / Stale:
+  High traffic / slow changing catalog: longer ttl (5–15m) + generous stale window.
+  Rapidly changing pricing/inventory: shorter ttl (1–2m) or disable stale if consistency is critical.
+
+When NOT to Use This Cache:
+  - Server authoritative real-time inventory checks pre‑purchase.
+  - Personalized data (user-specific recommendations) unless key includes identity.
+  - Security sensitive payloads (never store secrets / tokens).
+
+Extensibility Ideas:
+  - BroadcastChannel or storage event listener to sync invalidations across tabs.
+  - Add diff hashing of payload to skip downstream re-renders.
+  - Integrate global telemetry to record hit/miss ratio.
+
+Debugging Tips:
+  window.addEventListener('iv-cache', e => console.log('cache event', e.detail));
+  productCache.clearNamespace() // manual purge
+
+Migration Path If Dropping Markup:
+  1. Remove 'markup' references and helpers.
+  2. Narrow CacheStored.t to implicit 'data'.
+  3. Delete keyForMarkup / setMarkup / getMarkup / getOrSetMarkup usages.
+
+Safety Notes:
+  - Serialization errors are caught and emitted as 'error' events.
+  - Oversize entries are skipped (no partial writes).
+  - Stale return path never blocks UI; refresh runs through same deduped pipeline.
+============================================================
+*/
+
+// Shared product cache singleton for product-related data across components.
+// Focused on data (not markup) to preserve Stencil lifecycle & event binding.
+// Includes stale-while-revalidate so multiple component instances reuse results.
+const productCache = createCache({
+    namespace: 'products',
+    version: '1',
+    storage: 'local',
+    defaultTTL: 1000 * 60 * 5, // 5 minutes fresh
+    staleTTL: 1000 * 60 * 5, // additional 5 minutes stale window
+    dispatchEvents: true
+});
+/*
+============================================================
+PRODUCT CACHE – USAGE NOTES
+============================================================
+Goal:
+  Provide a shared, cross-component data cache for normalized Shopify product lists.
+  Prevents duplicate Storefront API queries when multiple components (e.g. carousels, grids) request the same dataset.
+
+Why Data (Not Markup):
+  Data caching keeps Stencil's render lifecycle & event listeners intact.
+  Markup caching risks stale styling, missed hydration, lost interactivity.
+
+Key Parameters Included in Cache Key:
+  handle   : collection or 'all'
+  sort     : sort key (BEST_SELLING, PRICE, etc.)
+  fields   : requested GraphQL fields (affects shape / payload size)
+  limit    : number of products
+  currency : ensures price formatting differences are segregated
+
+Stale-While-Revalidate Flow:
+  1. Fresh hit -> returned immediately.
+  2. Expired but within stale window + staleWhileRevalidate=true -> stale data returned; background refresh updates cache.
+  3. Expired beyond stale window -> treated as miss; new fetch awaited.
+
+Basic Usage in a Component:
+  import { productCache } from '../../utils/caching/productCache';
+  import { fetchProducts } from '../../utils/storefront_api/factory';
+
+  async function load() {
+    const params = { handle: 'all', sort: 'BEST_SELLING', fields: 'id,title,images', limit: 8, currency: 'GBP' };
+    const products = await productCache.getOrSetData(
+      params,
+      () => fetchProducts({
+        collectionHandle: params.handle,
+        sortKey: params.sort,
+        limit: params.limit,
+        fields: params.fields,
+      }),
+      { ttl: 1000 * 60 * 5, staleWhileRevalidate: true }
+    );
+    // render products...
+  }
+
+Listening for Cache Diagnostics:
+  window.addEventListener('iv-cache', e => {
+    const { action, key, namespace, info } = (e as CustomEvent).detail;
+    if(namespace === 'products') console.debug('[productCache]', action, { key, info });
+  });
+
+Manual Invalidation Examples:
+  productCache.clearNamespace(); // purge everything in 'products'
+  // or targeted:
+  // productCache.purge(specificKey);
+
+Adjusting Freshness Strategy:
+  - High stability content: increase defaultTTL (10–15m) + keep staleTTL (same or larger).
+  - Rapid inventory changes: shorten TTL (1–2m) or disable staleWhileRevalidate on critical views.
+
+Extending:
+  - Add a lightweight wrapper that injects user segment into params if personalization introduced.
+  - Introduce a background warm-up (call getOrSetData on route prefetch).
+
+Safety:
+  - Oversize payloads are ignored (error event emitted) to guard storage quota.
+  - Serialization failures fail open (miss on next access).
+============================================================
+*/
+
+function createErrorHandler(config = {}) {
+    const { component, toast, toastDuration = 3000, emitEvents = true, target = window, classifier, dedupeMs = 4000, defaultUserMessage = 'Something went wrong. Please try again.', maxConsoleStack = 6, telemetry, _sharedRecent } = config;
+    const recent = _sharedRecent || new Map();
+    function severityToToastType(sev) {
+        if (sev === 'warn')
+            return 'warning';
+        if (sev === 'debug' || sev === 'info')
+            return 'info';
+        return 'error';
+    }
+    function dispatchToast(message, severity) {
+        const type = severityToToastType(severity);
+        try {
+            toast ? toast({ message, variant: type }) : index.showToast(message, type, toastDuration);
+        }
+        catch (_) { /* swallow toast errors */ }
+    }
+    function classify(base) {
+        let severity = base.severity || base.level || 'error';
+        let userSafe = !!base.userMessage;
+        let userMessage = base.userMessage;
+        const err = base.error;
+        const isNetwork = err?.name === 'TypeError' && /fetch/i.test(err?.message || '');
+        if (isNetwork) {
+            userSafe = true;
+            userMessage ||= 'Network issue. Please retry.';
+        }
+        const status = err?.status || err?.response?.status;
+        if (status) {
+            if (status >= 400 && status < 500)
+                userSafe = true;
+            if (status >= 500) {
+                userSafe = false;
+                severity = 'error';
+            }
+        }
+        if (!userMessage && userSafe)
+            userMessage = defaultUserMessage;
+        if (classifier) {
+            const override = classifier({ error: err, scope: base.scope }) || {};
+            if (override.userSafe !== undefined)
+                userSafe = override.userSafe;
+            if (override.severity)
+                severity = override.severity;
+            if (override.userMessage)
+                userMessage = override.userMessage;
+        }
+        if (!userSafe)
+            userMessage = undefined;
+        return { userSafe, severity, userMessage };
+    }
+    function dedupeKey(n) {
+        return `${n.component || ''}|${n.scope}|${n.devMessage || n.userMessage || n.raw?.message || ''}|${n.severity}`;
+    }
+    function handle(opts) {
+        const { error, scope, devMessage, meta } = opts;
+        const { userSafe, severity, userMessage } = classify(opts);
+        const stack = (error?.stack || '').split('\n').slice(0, maxConsoleStack).join('\n');
+        const normalized = {
+            id: crypto?.randomUUID ? crypto.randomUUID() : Date.now().toString(36) + Math.random().toString(36).slice(2),
+            ts: Date.now(),
+            component,
+            scope,
+            severity,
+            userSafe,
+            userMessage,
+            devMessage: devMessage ?? (userSafe ? error?.message : undefined),
+            raw: error,
+            meta,
+            stack
+        };
+        if (telemetry?.enrich) {
+            try {
+                Object.assign(normalized, telemetry.enrich(normalized));
+            }
+            catch (_) { }
+        }
+        const key = dedupeKey(normalized);
+        const last = recent.get(key);
+        last && (Date.now() - last) < dedupeMs ? normalized.deduped = true : recent.set(key, Date.now());
+        const consolePayload = { ...normalized, raw: undefined };
+        if (severity === 'debug')
+            console.debug('[iv-error]', consolePayload, error);
+        else if (severity === 'info')
+            console.info('[iv-error]', consolePayload, error);
+        else if (severity === 'warn')
+            console.warn('[iv-error]', consolePayload, error);
+        else
+            console.error('[iv-error]', consolePayload, error);
+        if (userSafe && !normalized.deduped && userMessage) {
+            dispatchToast(userMessage, severity);
+        }
+        if (emitEvents && (opts.emitEvent !== false) && target && typeof target.dispatchEvent === 'function') {
+            try {
+                target.dispatchEvent(new CustomEvent('iv-error', { detail: normalized, bubbles: true, composed: true }));
+            }
+            catch (_) { }
+        }
+        if (telemetry && (!telemetry.sampleRate || Math.random() < telemetry.sampleRate)) {
+            if (!telemetry.filter || telemetry.filter(normalized)) {
+                try {
+                    Promise.resolve(telemetry.record(normalized)).catch(() => { });
+                }
+                catch (_) { }
+            }
+        }
+        return normalized;
+    }
+    return { handle };
+}
+// Usage in a component:
+/*
+import { createErrorHandler } from '../../utils/error_handling/factory';
+const errors = createErrorHandler({ component: 'iv-dynamic-products', toast: showToast });
+
+try {
+  await fetchProducts(...);
+} catch(err) {
+  errors.handle({
+    error: err,
+    scope: 'fetchProducts',
+    userMessage: 'Could not load products.',
+    devMessage: 'Storefront API fetch failed',
+    severity: 'error'
+  });
+}
+
+So simplest component usage:
+const errors = createErrorHandler({ component: 'iv-card' }); try { ... } catch (e) { errors.handle({ error: e, scope: 'load', userMessage: 'Failed to load.' }); }
+*/
+
+exports.createErrorHandler = createErrorHandler;
+exports.productCache = productCache;
+//# sourceMappingURL=factory-CffqQl1G.js.map
+
+//# sourceMappingURL=factory-CffqQl1G.js.map