@drakkar.software/sunglasses-core 0.5.0 → 0.7.0

package/dist/index.d.mts

@@ -399,6 +399,20 @@ interface StarfishAdapterConfig {
      * Can be the same adapter as `SunglassesConfig.storage`.
      */
     pathStorage?: IStorageAdapter;
+    /**
+     * When `true`, events are pushed directly without a prior pull.
+     * No merge, no optimistic locking, no conflict detection.
+     *
+     * Use this for Starfish collections configured with `queueOnly: true` —
+     * the server ignores `baseHash` and returns no stored data on pull,
+     * so a pull round-trip is always wasted.
+     *
+     * On push failure the adapter **throws**, allowing SunglassesCore to keep
+     * events in the local queue and retry on the next flush interval.
+     *
+     * Cannot be combined with `rotatePathOnSuccess`.
+     */
+    pushOnly?: boolean;
 }
 /**
  * In-memory + persisted session state.
@@ -653,15 +667,11 @@ declare class MiddlewarePipeline {
 /**
  * Persists per-event counts bucketed by time period (daily, weekly, monthly, all-time).
  *
- * Storage key format:
- *   `sg:count:{period}:{bucket}:{eventName}`
- *
- * where `bucket` is:
- *   - daily:    "2024-01-15"
- *   - weekly:   "2024-W03"   (ISO week)
- *   - monthly:  "2024-01"
- *   - all-time: "all"
+ * All counts are stored in a single `sg:counts` JSON blob, keyed internally by
+ * `{period}:{bucket}:{eventName}` within the object:
+ *   `{ "daily:2024-01-15:click": 3, "weekly:2024-W03:click": 7, ... }`
  *
+ * One storage key regardless of how many event types are tracked.
  * Counts survive app restarts (persisted to IStorageAdapter).
  * Designed to be written from the enqueue hot path — must not throw.
  */
@@ -669,17 +679,12 @@ declare class EventCounter implements IEventCounter {
     private readonly storage;
     private readonly logger;
     /**
-     * In-memory cache of counts keyed by storage key.
-     * Updated synchronously on increment so getCount() can return immediately
-     * without waiting for storage writes to complete.
+     * In-memory cache of counts keyed by sub-key (`{period}:{bucket}:{eventName}`).
+     * Updated synchronously on increment so getCount() can return immediately.
      */
     private readonly cache;
-    /**
-     * Tracks all storage keys written during this session.
-     * Used to reliably clear an event's timed buckets on reset(),
-     * even when they fall outside the 90-day sweep window.
-     */
-    private readonly writtenKeys;
+    /** Whether the counts blob has been loaded from storage into cache. */
+    private loaded;
     constructor(storage: IStorageAdapter, logger: Logger);
     /**
      * Increment the count for `eventName` across all four periods for `date`.
@@ -688,20 +693,21 @@ declare class EventCounter implements IEventCounter {
     getCount(eventName: string, period: EventCountPeriod, date?: Date): Promise<number>;
     /**
      * Reset counts for a specific event (all periods), or all events if omitted.
-     *
-     * Note: resetting all events requires listing storage keys. This is a best-effort
-     * operation — adapters that don't support key enumeration will only clear
-     * the provided event name's keys.
      */
     reset(eventName?: string): Promise<void>;
-    private incrementPeriod;
-    private clearEvent;
-    /** Build the storage key for a given event, period, and date. */
-    storageKey(eventName: string, period: EventCountPeriod, date: Date): string;
+    /**
+     * Load the counts blob from storage into the in-memory cache.
+     * Only runs once; subsequent calls are no-ops.
+     */
+    private loadIfNeeded;
+    /** Serialize the full in-memory cache to `sg:counts`. */
+    private persist;
+    /** Build the sub-key within the counts blob for a given event, period, and date. */
+    private subKey;
     /**
      * Return the time-bucket string for a given period and date.
      * - daily:    "2024-01-15"
-     * - weekly:   "2024-W03"
+     * - weekly:   "2024-W03"   (ISO week)
      * - monthly:  "2024-01"
      * - all-time: "all"
      */

package/dist/index.d.ts

@@ -399,6 +399,20 @@ interface StarfishAdapterConfig {
      * Can be the same adapter as `SunglassesConfig.storage`.
      */
     pathStorage?: IStorageAdapter;
+    /**
+     * When `true`, events are pushed directly without a prior pull.
+     * No merge, no optimistic locking, no conflict detection.
+     *
+     * Use this for Starfish collections configured with `queueOnly: true` —
+     * the server ignores `baseHash` and returns no stored data on pull,
+     * so a pull round-trip is always wasted.
+     *
+     * On push failure the adapter **throws**, allowing SunglassesCore to keep
+     * events in the local queue and retry on the next flush interval.
+     *
+     * Cannot be combined with `rotatePathOnSuccess`.
+     */
+    pushOnly?: boolean;
 }
 /**
  * In-memory + persisted session state.
@@ -653,15 +667,11 @@ declare class MiddlewarePipeline {
 /**
  * Persists per-event counts bucketed by time period (daily, weekly, monthly, all-time).
  *
- * Storage key format:
- *   `sg:count:{period}:{bucket}:{eventName}`
- *
- * where `bucket` is:
- *   - daily:    "2024-01-15"
- *   - weekly:   "2024-W03"   (ISO week)
- *   - monthly:  "2024-01"
- *   - all-time: "all"
+ * All counts are stored in a single `sg:counts` JSON blob, keyed internally by
+ * `{period}:{bucket}:{eventName}` within the object:
+ *   `{ "daily:2024-01-15:click": 3, "weekly:2024-W03:click": 7, ... }`
  *
+ * One storage key regardless of how many event types are tracked.
  * Counts survive app restarts (persisted to IStorageAdapter).
  * Designed to be written from the enqueue hot path — must not throw.
  */
@@ -669,17 +679,12 @@ declare class EventCounter implements IEventCounter {
     private readonly storage;
     private readonly logger;
     /**
-     * In-memory cache of counts keyed by storage key.
-     * Updated synchronously on increment so getCount() can return immediately
-     * without waiting for storage writes to complete.
+     * In-memory cache of counts keyed by sub-key (`{period}:{bucket}:{eventName}`).
+     * Updated synchronously on increment so getCount() can return immediately.
      */
     private readonly cache;
-    /**
-     * Tracks all storage keys written during this session.
-     * Used to reliably clear an event's timed buckets on reset(),
-     * even when they fall outside the 90-day sweep window.
-     */
-    private readonly writtenKeys;
+    /** Whether the counts blob has been loaded from storage into cache. */
+    private loaded;
     constructor(storage: IStorageAdapter, logger: Logger);
     /**
      * Increment the count for `eventName` across all four periods for `date`.
@@ -688,20 +693,21 @@ declare class EventCounter implements IEventCounter {
     getCount(eventName: string, period: EventCountPeriod, date?: Date): Promise<number>;
     /**
      * Reset counts for a specific event (all periods), or all events if omitted.
-     *
-     * Note: resetting all events requires listing storage keys. This is a best-effort
-     * operation — adapters that don't support key enumeration will only clear
-     * the provided event name's keys.
      */
     reset(eventName?: string): Promise<void>;
-    private incrementPeriod;
-    private clearEvent;
-    /** Build the storage key for a given event, period, and date. */
-    storageKey(eventName: string, period: EventCountPeriod, date: Date): string;
+    /**
+     * Load the counts blob from storage into the in-memory cache.
+     * Only runs once; subsequent calls are no-ops.
+     */
+    private loadIfNeeded;
+    /** Serialize the full in-memory cache to `sg:counts`. */
+    private persist;
+    /** Build the sub-key within the counts blob for a given event, period, and date. */
+    private subKey;
     /**
      * Return the time-bucket string for a given period and date.
      * - daily:    "2024-01-15"
-     * - weekly:   "2024-W03"
+     * - weekly:   "2024-W03"   (ISO week)
      * - monthly:  "2024-01"
      * - all-time: "all"
      */

package/dist/index.js

@@ -205,150 +205,91 @@ var ConsentManager = class {
 };
 
 // src/EventCounter.ts
-var KEY_PREFIX = "sg:count";
+var COUNTS_KEY = "sg:counts";
 var EventCounter = class {
   constructor(storage, logger) {
     this.storage = storage;
     this.logger = logger;
     /**
-     * In-memory cache of counts keyed by storage key.
-     * Updated synchronously on increment so getCount() can return immediately
-     * without waiting for storage writes to complete.
+     * In-memory cache of counts keyed by sub-key (`{period}:{bucket}:{eventName}`).
+     * Updated synchronously on increment so getCount() can return immediately.
      */
     this.cache = /* @__PURE__ */ new Map();
-    /**
-     * Tracks all storage keys written during this session.
-     * Used to reliably clear an event's timed buckets on reset(),
-     * even when they fall outside the 90-day sweep window.
-     */
-    this.writtenKeys = /* @__PURE__ */ new Set();
+    /** Whether the counts blob has been loaded from storage into cache. */
+    this.loaded = false;
   }
   /**
    * Increment the count for `eventName` across all four periods for `date`.
    */
   async increment(eventName, date = /* @__PURE__ */ new Date()) {
+    await this.loadIfNeeded();
     const periods = ["daily", "weekly", "monthly", "all-time"];
-    await Promise.all(periods.map((period) => this.incrementPeriod(eventName, period, date)));
+    for (const period of periods) {
+      const key = this.subKey(eventName, period, date);
+      this.cache.set(key, (this.cache.get(key) ?? 0) + 1);
+    }
+    await this.persist();
   }
   async getCount(eventName, period, date = /* @__PURE__ */ new Date()) {
-    const key = this.storageKey(eventName, period, date);
-    const cached = this.cache.get(key);
-    if (cached !== void 0) return cached;
-    try {
-      const raw = await this.storage.read(key);
-      if (raw === null) return 0;
-      const n = parseInt(raw, 10);
-      const count = Number.isNaN(n) ? 0 : n;
-      this.cache.set(key, count);
-      return count;
-    } catch (err) {
-      this.logger.warn("EventCounter: failed to read count", err);
-      return 0;
-    }
+    await this.loadIfNeeded();
+    return this.cache.get(this.subKey(eventName, period, date)) ?? 0;
   }
   /**
    * Reset counts for a specific event (all periods), or all events if omitted.
-   *
-   * Note: resetting all events requires listing storage keys. This is a best-effort
-   * operation — adapters that don't support key enumeration will only clear
-   * the provided event name's keys.
    */
   async reset(eventName) {
+    await this.loadIfNeeded();
     if (eventName) {
-      await this.clearEvent(eventName);
-    } else {
-      const allKeys = [...this.writtenKeys];
-      for (const key of allKeys) {
-        try {
-          await this.storage.delete(key);
-        } catch {
-        }
-        this.writtenKeys.delete(key);
-        this.cache.delete(key);
-      }
-      const now = /* @__PURE__ */ new Date();
-      const seenKeys = new Set(allKeys);
-      const periods = ["daily", "weekly", "monthly", "all-time"];
-      const eventNames = new Set(
-        allKeys.map((k) => k.split(":").pop()).filter(Boolean)
-      );
-      for (let i = 0; i < 90; i++) {
-        const d = new Date(now);
-        d.setDate(d.getDate() - i);
-        for (const name of eventNames) {
-          for (const period of periods) {
-            const key = this.storageKey(name, period, d);
-            if (!seenKeys.has(key)) {
-              seenKeys.add(key);
-              try {
-                await this.storage.delete(key);
-              } catch {
-              }
-            }
-          }
+      const safeEvent = eventName.replace(/[^a-zA-Z0-9_\-]/g, "_");
+      for (const key of this.cache.keys()) {
+        if (key.endsWith(`:${safeEvent}`)) {
+          this.cache.delete(key);
         }
       }
-      this.logger.debug("EventCounter.reset(): cleared all tracked event counters");
+    } else {
+      this.cache.clear();
     }
+    await this.persist();
+    this.logger.debug("EventCounter.reset(): cleared event counters");
   }
   // ── Private ──────────────────────────────────────────────────────────────
-  async incrementPeriod(eventName, period, date) {
-    const key = this.storageKey(eventName, period, date);
-    this.writtenKeys.add(key);
-    const currentCached = this.cache.get(key) ?? 0;
-    const next = currentCached + 1;
-    this.cache.set(key, next);
+  /**
+   * Load the counts blob from storage into the in-memory cache.
+   * Only runs once; subsequent calls are no-ops.
+   */
+  async loadIfNeeded() {
+    if (this.loaded) return;
+    this.loaded = true;
     try {
-      await this.storage.write(key, String(next));
+      const raw = await this.storage.read(COUNTS_KEY);
+      if (!raw) return;
+      const parsed = JSON.parse(raw);
+      for (const [k, v] of Object.entries(parsed)) {
+        if (typeof v === "number") this.cache.set(k, v);
+      }
     } catch (err) {
-      this.logger.warn("EventCounter: failed to persist count", err);
+      this.logger.warn("EventCounter: failed to load counts blob", err);
     }
   }
-  async clearEvent(eventName) {
-    const safeEvent = eventName.replace(/[^a-zA-Z0-9_\-]/g, "_");
-    const sessionKeys = [...this.writtenKeys].filter(
-      (k) => k.endsWith(`:${safeEvent}`)
-    );
-    for (const key of sessionKeys) {
-      try {
-        await this.storage.delete(key);
-      } catch {
-      }
-      this.writtenKeys.delete(key);
-      this.cache.delete(key);
-    }
-    const now = /* @__PURE__ */ new Date();
-    const seenBuckets = new Set(sessionKeys);
-    for (let i = 0; i < 90; i++) {
-      const d = new Date(now);
-      d.setDate(d.getDate() - i);
-      const periods = ["daily", "weekly", "monthly"];
-      for (const period of periods) {
-        const key = this.storageKey(eventName, period, d);
-        if (!seenBuckets.has(key)) {
-          seenBuckets.add(key);
-          try {
-            await this.storage.delete(key);
-          } catch {
-          }
-        }
-      }
-    }
+  /** Serialize the full in-memory cache to `sg:counts`. */
+  async persist() {
+    const obj = {};
+    for (const [k, v] of this.cache) obj[k] = v;
     try {
-      await this.storage.delete(this.storageKey(eventName, "all-time", /* @__PURE__ */ new Date()));
-    } catch {
+      await this.storage.write(COUNTS_KEY, JSON.stringify(obj));
+    } catch (err) {
+      this.logger.warn("EventCounter: failed to persist counts blob", err);
     }
   }
-  /** Build the storage key for a given event, period, and date. */
-  storageKey(eventName, period, date) {
-    const bucket = this.bucketFor(period, date);
+  /** Build the sub-key within the counts blob for a given event, period, and date. */
+  subKey(eventName, period, date) {
     const safeEvent = eventName.replace(/[^a-zA-Z0-9_\-]/g, "_");
-    return `${KEY_PREFIX}:${period}:${bucket}:${safeEvent}`;
+    return `${period}:${this.bucketFor(period, date)}:${safeEvent}`;
   }
   /**
    * Return the time-bucket string for a given period and date.
    * - daily:    "2024-01-15"
-   * - weekly:   "2024-W03"
+   * - weekly:   "2024-W03"   (ISO week)
    * - monthly:  "2024-01"
    * - all-time: "all"
    */
@@ -357,10 +298,9 @@ var EventCounter = class {
       case "daily":
         return date.toISOString().slice(0, 10);
       // "YYYY-MM-DD"
-      case "weekly": {
-        const iso = toISOWeek(date);
-        return iso;
-      }
+      case "weekly":
+        return toISOWeek(date);
+      // "YYYY-Www"
       case "monthly":
         return date.toISOString().slice(0, 7);
       // "YYYY-MM"

package/dist/index.mjs

@@ -162,150 +162,91 @@ var ConsentManager = class {
 };
 
 // src/EventCounter.ts
-var KEY_PREFIX = "sg:count";
+var COUNTS_KEY = "sg:counts";
 var EventCounter = class {
   constructor(storage, logger) {
     this.storage = storage;
     this.logger = logger;
     /**
-     * In-memory cache of counts keyed by storage key.
-     * Updated synchronously on increment so getCount() can return immediately
-     * without waiting for storage writes to complete.
+     * In-memory cache of counts keyed by sub-key (`{period}:{bucket}:{eventName}`).
+     * Updated synchronously on increment so getCount() can return immediately.
      */
     this.cache = /* @__PURE__ */ new Map();
-    /**
-     * Tracks all storage keys written during this session.
-     * Used to reliably clear an event's timed buckets on reset(),
-     * even when they fall outside the 90-day sweep window.
-     */
-    this.writtenKeys = /* @__PURE__ */ new Set();
+    /** Whether the counts blob has been loaded from storage into cache. */
+    this.loaded = false;
   }
   /**
    * Increment the count for `eventName` across all four periods for `date`.
    */
   async increment(eventName, date = /* @__PURE__ */ new Date()) {
+    await this.loadIfNeeded();
     const periods = ["daily", "weekly", "monthly", "all-time"];
-    await Promise.all(periods.map((period) => this.incrementPeriod(eventName, period, date)));
+    for (const period of periods) {
+      const key = this.subKey(eventName, period, date);
+      this.cache.set(key, (this.cache.get(key) ?? 0) + 1);
+    }
+    await this.persist();
   }
   async getCount(eventName, period, date = /* @__PURE__ */ new Date()) {
-    const key = this.storageKey(eventName, period, date);
-    const cached = this.cache.get(key);
-    if (cached !== void 0) return cached;
-    try {
-      const raw = await this.storage.read(key);
-      if (raw === null) return 0;
-      const n = parseInt(raw, 10);
-      const count = Number.isNaN(n) ? 0 : n;
-      this.cache.set(key, count);
-      return count;
-    } catch (err) {
-      this.logger.warn("EventCounter: failed to read count", err);
-      return 0;
-    }
+    await this.loadIfNeeded();
+    return this.cache.get(this.subKey(eventName, period, date)) ?? 0;
   }
   /**
    * Reset counts for a specific event (all periods), or all events if omitted.
-   *
-   * Note: resetting all events requires listing storage keys. This is a best-effort
-   * operation — adapters that don't support key enumeration will only clear
-   * the provided event name's keys.
    */
   async reset(eventName) {
+    await this.loadIfNeeded();
     if (eventName) {
-      await this.clearEvent(eventName);
-    } else {
-      const allKeys = [...this.writtenKeys];
-      for (const key of allKeys) {
-        try {
-          await this.storage.delete(key);
-        } catch {
-        }
-        this.writtenKeys.delete(key);
-        this.cache.delete(key);
-      }
-      const now = /* @__PURE__ */ new Date();
-      const seenKeys = new Set(allKeys);
-      const periods = ["daily", "weekly", "monthly", "all-time"];
-      const eventNames = new Set(
-        allKeys.map((k) => k.split(":").pop()).filter(Boolean)
-      );
-      for (let i = 0; i < 90; i++) {
-        const d = new Date(now);
-        d.setDate(d.getDate() - i);
-        for (const name of eventNames) {
-          for (const period of periods) {
-            const key = this.storageKey(name, period, d);
-            if (!seenKeys.has(key)) {
-              seenKeys.add(key);
-              try {
-                await this.storage.delete(key);
-              } catch {
-              }
-            }
-          }
+      const safeEvent = eventName.replace(/[^a-zA-Z0-9_\-]/g, "_");
+      for (const key of this.cache.keys()) {
+        if (key.endsWith(`:${safeEvent}`)) {
+          this.cache.delete(key);
         }
       }
-      this.logger.debug("EventCounter.reset(): cleared all tracked event counters");
+    } else {
+      this.cache.clear();
     }
+    await this.persist();
+    this.logger.debug("EventCounter.reset(): cleared event counters");
   }
   // ── Private ──────────────────────────────────────────────────────────────
-  async incrementPeriod(eventName, period, date) {
-    const key = this.storageKey(eventName, period, date);
-    this.writtenKeys.add(key);
-    const currentCached = this.cache.get(key) ?? 0;
-    const next = currentCached + 1;
-    this.cache.set(key, next);
+  /**
+   * Load the counts blob from storage into the in-memory cache.
+   * Only runs once; subsequent calls are no-ops.
+   */
+  async loadIfNeeded() {
+    if (this.loaded) return;
+    this.loaded = true;
     try {
-      await this.storage.write(key, String(next));
+      const raw = await this.storage.read(COUNTS_KEY);
+      if (!raw) return;
+      const parsed = JSON.parse(raw);
+      for (const [k, v] of Object.entries(parsed)) {
+        if (typeof v === "number") this.cache.set(k, v);
+      }
     } catch (err) {
-      this.logger.warn("EventCounter: failed to persist count", err);
+      this.logger.warn("EventCounter: failed to load counts blob", err);
     }
   }
-  async clearEvent(eventName) {
-    const safeEvent = eventName.replace(/[^a-zA-Z0-9_\-]/g, "_");
-    const sessionKeys = [...this.writtenKeys].filter(
-      (k) => k.endsWith(`:${safeEvent}`)
-    );
-    for (const key of sessionKeys) {
-      try {
-        await this.storage.delete(key);
-      } catch {
-      }
-      this.writtenKeys.delete(key);
-      this.cache.delete(key);
-    }
-    const now = /* @__PURE__ */ new Date();
-    const seenBuckets = new Set(sessionKeys);
-    for (let i = 0; i < 90; i++) {
-      const d = new Date(now);
-      d.setDate(d.getDate() - i);
-      const periods = ["daily", "weekly", "monthly"];
-      for (const period of periods) {
-        const key = this.storageKey(eventName, period, d);
-        if (!seenBuckets.has(key)) {
-          seenBuckets.add(key);
-          try {
-            await this.storage.delete(key);
-          } catch {
-          }
-        }
-      }
-    }
+  /** Serialize the full in-memory cache to `sg:counts`. */
+  async persist() {
+    const obj = {};
+    for (const [k, v] of this.cache) obj[k] = v;
     try {
-      await this.storage.delete(this.storageKey(eventName, "all-time", /* @__PURE__ */ new Date()));
-    } catch {
+      await this.storage.write(COUNTS_KEY, JSON.stringify(obj));
+    } catch (err) {
+      this.logger.warn("EventCounter: failed to persist counts blob", err);
     }
   }
-  /** Build the storage key for a given event, period, and date. */
-  storageKey(eventName, period, date) {
-    const bucket = this.bucketFor(period, date);
+  /** Build the sub-key within the counts blob for a given event, period, and date. */
+  subKey(eventName, period, date) {
     const safeEvent = eventName.replace(/[^a-zA-Z0-9_\-]/g, "_");
-    return `${KEY_PREFIX}:${period}:${bucket}:${safeEvent}`;
+    return `${period}:${this.bucketFor(period, date)}:${safeEvent}`;
   }
   /**
    * Return the time-bucket string for a given period and date.
    * - daily:    "2024-01-15"
-   * - weekly:   "2024-W03"
+   * - weekly:   "2024-W03"   (ISO week)
    * - monthly:  "2024-01"
    * - all-time: "all"
    */
@@ -314,10 +255,9 @@ var EventCounter = class {
       case "daily":
         return date.toISOString().slice(0, 10);
       // "YYYY-MM-DD"
-      case "weekly": {
-        const iso = toISOWeek(date);
-        return iso;
-      }
+      case "weekly":
+        return toISOWeek(date);
+      // "YYYY-Www"
       case "monthly":
         return date.toISOString().slice(0, 7);
       // "YYYY-MM"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/sunglasses-core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Platform-agnostic event tracking engine for SunGlasses",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",