@js-nerds/batch-collector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 js-nerds
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @js-nerds/batch-collector
+
+[![npm version](https://img.shields.io/npm/v/@js-nerds/batch-collector)](https://www.npmjs.com/package/@js-nerds/batch-collector)
+[![npm downloads](https://img.shields.io/npm/dm/@js-nerds/batch-collector)](https://www.npmjs.com/package/@js-nerds/batch-collector)
+[![tests](https://github.com/js-nerds/batch-collector/actions/workflows/build-test.yml/badge.svg?branch=main&label=tests)](https://github.com/js-nerds/batch-collector/actions/workflows/build-test.yml)
+[![coverage](https://codecov.io/gh/js-nerds/batch-collector/branch/main/graph/badge.svg)](https://codecov.io/gh/js-nerds/batch-collector)
+
+Lightweight TypeScript batch collector with delayed flush, optional timer reset, and local/session storage persistence.
+
+## Install
+
+```bash
+npm install @js-nerds/batch-collector
+```
+
+```bash
+pnpm add @js-nerds/batch-collector
+```
+
+```bash
+yarn add @js-nerds/batch-collector
+```
+
+## Usage
+
+```ts
+import { BATCH_FLUSH_EVENT, BatchCollector } from "@js-nerds/batch-collector";
+
+const collector = new BatchCollector<{ action: string; id: string }>({
+	delayMs: 5000,
+	resetTimerOnPush: true,
+	storageType: "localStorage",
+	storageKey: "my-app-log-batch"
+});
+
+collector.subscribe(BATCH_FLUSH_EVENT, (items) => {
+	console.log("Flush:", items);
+});
+
+collector.push({ action: "button_click", id: "submit-btn" });
+collector.push({ action: "menu_open", id: "profile" });
+```
+
+## API
+
+### `new BatchCollector(config)`
+
+Creates a collector instance.
+
+**Config**
+- `delayMs: number` — delay before flush.
+- `resetTimerOnPush?: boolean` — reset timer on every push (default `true`).
+- `storageType?: "memory" | "localStorage" | "sessionStorage"` — where to keep pending batch (default `"memory"`).
+- `storageKey?: string` — key for local/session storage (default `"batch-collector-pending"`).
+- `autoClear?: boolean` — clear after timer flush (default `true`).
+
+### `subscribe(event, callback)`
+
+Subscribes to collector events.
+
+**Params**
+- `event: string` — use `BATCH_FLUSH_EVENT` (`"flush"`).
+- `callback: (items: T[]) => void`
+
+**Returns**
+- `() => void` — unsubscribe function.
+
+### `push(item)`
+
+Adds item to batch and schedules flush.
+
+### `items()`
+
+Returns a shallow copy of current batch.
+
+### `clear()`
+
+Clears timer, in-memory batch, and persisted batch.
+
+## License
+
+MIT
+
+## Changelog
+
+See `CHANGELOG.md`.

package/dist/index.cjs

@@ -0,0 +1,226 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BATCH_FLUSH_EVENT: () => BATCH_FLUSH_EVENT,
+  BatchCollector: () => BatchCollector
+});
+module.exports = __toCommonJS(index_exports);
+var BATCH_FLUSH_EVENT = "flush";
+var DEFAULT_STORAGE_KEY = "batch-collector-pending";
+var BatchCollector = class {
+  /**
+   * Creates a batch collector instance.
+   *
+   * @param {BatchCollectorConfig} config - Configuration object with delay, optional reset behaviour, and optional storageType.
+   */
+  constructor(config) {
+    this.buffer = [];
+    this.timerId = null;
+    this.listeners = /* @__PURE__ */ new Map();
+    var _a, _b, _c, _d;
+    this.delayMs = config.delayMs;
+    this.resetTimerOnPush = (_a = config.resetTimerOnPush) != null ? _a : true;
+    this.storageType = (_b = config.storageType) != null ? _b : "memory";
+    this.storageKey = (_c = config.storageKey) != null ? _c : DEFAULT_STORAGE_KEY;
+    this.autoClear = (_d = config.autoClear) != null ? _d : true;
+    if (this.storageType !== "memory") {
+      const pending = this.readPersisted();
+      if (pending.length !== 0) {
+        this.writePersisted([]);
+        this.emit(BATCH_FLUSH_EVENT, pending);
+      }
+    }
+  }
+  /**
+   * Subscribe to an event. When the batch is flushed, the "flush" event is emitted with the batched items.
+   *
+   * @param {string} event - Event name; use BATCH_FLUSH_EVENT ("flush") for flush events.
+   * @param {FlushListener<T>} callback - Function called with the batched items when the event is emitted.
+   * @returns {() => void} Unsubscribe function; call to remove the listener.
+   */
+  subscribe(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(callback);
+    return () => {
+      var _a;
+      return (_a = this.listeners.get(event)) == null ? void 0 : _a.delete(callback);
+    };
+  }
+  /**
+   * Add an item to the batch and (re)start the flush timer. When storageType is not memory, also persists the buffer.
+   *
+   * @param {T} item - Item to add to the current batch.
+   * @returns {void}
+   */
+  push(item) {
+    this.buffer.push(item);
+    if (this.storageType !== "memory") {
+      this.writePersisted(this.buffer);
+    }
+    this.scheduleFlush();
+  }
+  /**
+   * Returns a copy of the current buffer. Does not emit, clear, or change state.
+   *
+   * @returns {T[]} Copy of all items in the batch.
+   */
+  items() {
+    return [...this.buffer];
+  }
+  /**
+   * Clears the pending timer, the buffer, and persisted storage. Does not emit.
+   *
+   * @returns {boolean} True.
+   */
+  clear() {
+    this.clearTimer();
+    this.buffer = [];
+    if (this.storageType !== "memory") {
+      this.writePersisted([]);
+    }
+    return true;
+  }
+  /**
+   * Returns the Storage instance for the configured storage type, or null if unavailable (e.g. SSR).
+   *
+   * @returns {Storage | null} window.localStorage, window.sessionStorage, or null.
+   */
+  getStorage() {
+    if (typeof window === "undefined") {
+      return null;
+    }
+    if (this.storageType === "localStorage") {
+      return window.localStorage;
+    }
+    if (this.storageType === "sessionStorage") {
+      return window.sessionStorage;
+    }
+    return null;
+  }
+  /**
+   * Reads the persisted buffer from storage.
+   *
+   * @returns {T[]} Parsed buffer from storage, or empty array if unavailable or parse error.
+   */
+  readPersisted() {
+    const storage = this.getStorage();
+    if (!storage) {
+      return [];
+    }
+    try {
+      const raw = storage.getItem(this.storageKey);
+      return raw ? JSON.parse(raw) : [];
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Writes the buffer to storage, or removes the key when the buffer is empty.
+   *
+   * @param {T[]} items - Current buffer to persist.
+   * @returns {boolean} True if write succeeded, false otherwise.
+   */
+  writePersisted(items) {
+    const storage = this.getStorage();
+    if (!storage) {
+      return false;
+    }
+    try {
+      if (items.length === 0) {
+        storage.removeItem(this.storageKey);
+      } else {
+        storage.setItem(this.storageKey, JSON.stringify(items));
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Emits the current batch to subscribers and optionally clears buffer and storage. Used internally by the timer.
+   * When autoClear is false, the timer calls flush(false) so only manual clear() clears.
+   *
+   * @param {boolean} clear - If true (default), clear buffer and storage after emit. If false, only emit.
+   * @returns {boolean} True if the batch was emitted, false if buffer was empty.
+   */
+  flush(clear = true) {
+    this.clearTimer();
+    if (this.buffer.length === 0) {
+      return false;
+    }
+    const items = [...this.buffer];
+    if (clear) {
+      this.buffer = [];
+      if (this.storageType !== "memory") {
+        this.writePersisted([]);
+      }
+    }
+    this.emit(BATCH_FLUSH_EVENT, items);
+    return true;
+  }
+  /**
+   * Emits an event with the given payload to all subscribers of that event.
+   *
+   * @param {string} event - Event name to emit.
+   * @param {T[]} payload - Data to pass to each listener.
+   * @returns {void}
+   */
+  emit(event, payload) {
+    var _a;
+    (_a = this.listeners.get(event)) == null ? void 0 : _a.forEach((cb) => cb(payload));
+  }
+  /**
+   * Schedules a flush after the configured delay. If resetTimerOnPush is true, clears existing timer first.
+   *
+   * @returns {boolean} True if timer was scheduled, false if already scheduled (resetTimerOnPush false).
+   */
+  scheduleFlush() {
+    if (this.resetTimerOnPush) {
+      this.clearTimer();
+    } else if (this.timerId !== null) {
+      return false;
+    }
+    this.timerId = setTimeout(() => this.flush(this.autoClear), this.delayMs);
+    return true;
+  }
+  /**
+   * Clears the pending flush timer if one is set. Does nothing if no timer is set.
+   *
+   * @returns {boolean} True if a timer was cleared, false if there was no timer.
+   */
+  clearTimer() {
+    if (this.timerId !== null) {
+      clearTimeout(this.timerId);
+      this.timerId = null;
+      return true;
+    }
+    return false;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BATCH_FLUSH_EVENT,
+  BatchCollector
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Batches items and emits a \"flush\" event after a delay (e.g. after last push).\n * Event-based: create instance, subscribe via subscribe(BATCH_FLUSH_EVENT, callback), call push() from UI.\n * Optional persistence: storageType can be memory, localStorage, or sessionStorage so the batch survives refresh/close.\n */\n\nexport type BatchCollectorStorageType = \"memory\" | \"localStorage\" | \"sessionStorage\";\n\nexport type BatchCollectorConfig = {\n  /** Delay in milliseconds before flushing the batch (e.g. 5000 = 5 seconds). */\n  delayMs: number;\n  /** If true, timer resets on each push (flush N ms after last push). If false, flush exactly N ms after first push. Default true. */\n  resetTimerOnPush?: boolean;\n  /** Where to keep the buffer: \"memory\" (default), \"localStorage\", or \"sessionStorage\". When not memory, buffer is persisted and re-flushed on next load if any. */\n  storageType?: BatchCollectorStorageType;\n  /** Storage key when storageType is localStorage or sessionStorage. Should be unique per collector instance. Default \"batch-collector-pending\". */\n  storageKey?: string;\n  /** If true (default), buffer and storage are cleared when the timer fires. If false, only on manual clear() call. */\n  autoClear?: boolean;\n};\n\n/** Event name emitted when the batch is flushed. */\nexport const BATCH_FLUSH_EVENT = \"flush\";\n\ntype FlushListener<T> = (items: T[]) => void;\n\nconst DEFAULT_STORAGE_KEY = \"batch-collector-pending\";\n\n/**\n * Collects items in a buffer and emits BATCH_FLUSH_EVENT with the batched array after a delay (e.g. after the last push).\n * Use for batching UI events (clicks, logs) before sending to server or analytics. Item type is generic (objects, numbers, strings, or any T).\n *\n * Parameters (config):\n * - delayMs (required) — delay in ms before emitting the batch (e.g. 5000 = 5 seconds).\n * - resetTimerOnPush (optional) — if true (default), timer resets on each push; if false, emit exactly delayMs after first push.\n * - storageType (optional) — \"memory\" (default), \"localStorage\", or \"sessionStorage\". When not memory, batch is persisted and re-emitted on next load.\n * - storageKey (optional) — storage key when using localStorage/sessionStorage. Unique per instance. Default \"batch-collector-pending\".\n * - autoClear (optional) — if true (default), buffer and storage are cleared when the timer fires; if false, only on manual clear().\n *\n * Public API:\n * - subscribe(event, callback) — subscribe to flush events; callback receives the batch. Returns unsubscribe function.\n * - push(item) — add an item and (re)start the timer.\n * - items() — returns a copy of the current batch (optional; does not emit or clear).\n * - clear() — clears buffer and storage (optional; e.g. call from the subscriber after a successful send).\n *\n * @example\n * const collector = new BatchCollector<{ action: string; id: string }>({\n *   delayMs: 5000,\n *   storageType: \"localStorage\",\n *   storageKey: \"my-app-log-batch\"\n * });\n * collector.subscribe(BATCH_FLUSH_EVENT, (items) => sendToBackend(items));\n * collector.push({ action: \"button_click\", id: \"submit-btn\" });\n *\n * Optional:\n * collector.items()  // copy of current batch\n * collector.clear() // clear buffer and storage (e.g. after successful send in subscriber)\n */\nexport class BatchCollector<T = unknown> {\n  private buffer: T[] = [];\n  private timerId: ReturnType<typeof setTimeout> | null = null;\n\n  private readonly delayMs: number;\n  private readonly resetTimerOnPush: boolean;\n  private readonly storageType: BatchCollectorStorageType;\n  private readonly storageKey: string;\n  private readonly autoClear: boolean;\n  private readonly listeners = new Map<string, Set<FlushListener<T>>>();\n\n  /**\n   * Creates a batch collector instance.\n   *\n   * @param {BatchCollectorConfig} config - Configuration object with delay, optional reset behaviour, and optional storageType.\n   */\n  constructor(config: BatchCollectorConfig) {\n    this.delayMs = config.delayMs;\n    this.resetTimerOnPush = config.resetTimerOnPush ?? true;\n    this.storageType = config.storageType ?? \"memory\";\n    this.storageKey = config.storageKey ?? DEFAULT_STORAGE_KEY;\n    this.autoClear = config.autoClear ?? true;\n\n    if (this.storageType !== \"memory\") {\n      const pending = this.readPersisted();\n\n      if (pending.length !== 0) {\n        this.writePersisted([]);\n        this.emit(BATCH_FLUSH_EVENT, pending);\n      }\n    }\n  }\n\n  /**\n   * Subscribe to an event. When the batch is flushed, the \"flush\" event is emitted with the batched items.\n   *\n   * @param {string} event - Event name; use BATCH_FLUSH_EVENT (\"flush\") for flush events.\n   * @param {FlushListener<T>} callback - Function called with the batched items when the event is emitted.\n   * @returns {() => void} Unsubscribe function; call to remove the listener.\n   */\n  public subscribe(event: string, callback: FlushListener<T>): () => void {\n    if (!this.listeners.has(event)) {\n      this.listeners.set(event, new Set());\n    }\n\n    this.listeners.get(event)!.add(callback);\n\n    return () => this.listeners.get(event)?.delete(callback);\n  }\n\n  /**\n   * Add an item to the batch and (re)start the flush timer. When storageType is not memory, also persists the buffer.\n   *\n   * @param {T} item - Item to add to the current batch.\n   * @returns {void}\n   */\n  public push(item: T): void {\n    this.buffer.push(item);\n\n    if (this.storageType !== \"memory\") {\n      this.writePersisted(this.buffer);\n    }\n\n    this.scheduleFlush();\n  }\n\n  /**\n   * Returns a copy of the current buffer. Does not emit, clear, or change state.\n   *\n   * @returns {T[]} Copy of all items in the batch.\n   */\n  public items(): T[] {\n    return [...this.buffer];\n  }\n\n  /**\n   * Clears the pending timer, the buffer, and persisted storage. Does not emit.\n   *\n   * @returns {boolean} True.\n   */\n  public clear(): boolean {\n    this.clearTimer();\n    this.buffer = [];\n\n    if (this.storageType !== \"memory\") {\n      this.writePersisted([]);\n    }\n\n    return true;\n  }\n\n  /**\n   * Returns the Storage instance for the configured storage type, or null if unavailable (e.g. SSR).\n   *\n   * @returns {Storage | null} window.localStorage, window.sessionStorage, or null.\n   */\n  private getStorage(): Storage | null {\n    if (typeof window === \"undefined\") {\n      return null;\n    }\n\n    if (this.storageType === \"localStorage\") {\n      return window.localStorage;\n    }\n\n    if (this.storageType === \"sessionStorage\") {\n      return window.sessionStorage;\n    }\n\n    return null;\n  }\n\n  /**\n   * Reads the persisted buffer from storage.\n   *\n   * @returns {T[]} Parsed buffer from storage, or empty array if unavailable or parse error.\n   */\n  private readPersisted(): T[] {\n    const storage = this.getStorage();\n\n    if (!storage) {\n      return [];\n    }\n\n    try {\n      const raw = storage.getItem(this.storageKey);\n\n      return raw ? (JSON.parse(raw) as T[]) : [];\n    } catch {\n      return [];\n    }\n  }\n\n  /**\n   * Writes the buffer to storage, or removes the key when the buffer is empty.\n   *\n   * @param {T[]} items - Current buffer to persist.\n   * @returns {boolean} True if write succeeded, false otherwise.\n   */\n  private writePersisted(items: T[]): boolean {\n    const storage = this.getStorage();\n\n    if (!storage) {\n      return false;\n    }\n\n    try {\n      if (items.length === 0) {\n        storage.removeItem(this.storageKey);\n      } else {\n        storage.setItem(this.storageKey, JSON.stringify(items));\n      }\n\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Emits the current batch to subscribers and optionally clears buffer and storage. Used internally by the timer.\n   * When autoClear is false, the timer calls flush(false) so only manual clear() clears.\n   *\n   * @param {boolean} clear - If true (default), clear buffer and storage after emit. If false, only emit.\n   * @returns {boolean} True if the batch was emitted, false if buffer was empty.\n   */\n  private flush(clear: boolean = true): boolean {\n    this.clearTimer();\n\n    if (this.buffer.length === 0) {\n      return false;\n    }\n\n    const items = [...this.buffer];\n\n    if (clear) {\n      this.buffer = [];\n\n      if (this.storageType !== \"memory\") {\n        this.writePersisted([]);\n      }\n    }\n\n    this.emit(BATCH_FLUSH_EVENT, items);\n\n    return true;\n  }\n\n  /**\n   * Emits an event with the given payload to all subscribers of that event.\n   *\n   * @param {string} event - Event name to emit.\n   * @param {T[]} payload - Data to pass to each listener.\n   * @returns {void}\n   */\n  private emit(event: string, payload: T[]): void {\n    this.listeners.get(event)?.forEach((cb) => cb(payload));\n  }\n\n  /**\n   * Schedules a flush after the configured delay. If resetTimerOnPush is true, clears existing timer first.\n   *\n   * @returns {boolean} True if timer was scheduled, false if already scheduled (resetTimerOnPush false).\n   */\n  private scheduleFlush(): boolean {\n    if (this.resetTimerOnPush) {\n      this.clearTimer();\n    } else if (this.timerId !== null) {\n      return false; // already scheduled from first push\n    }\n\n    this.timerId = setTimeout(() => this.flush(this.autoClear), this.delayMs);\n\n    return true;\n  }\n\n  /**\n   * Clears the pending flush timer if one is set. Does nothing if no timer is set.\n   *\n   * @returns {boolean} True if a timer was cleared, false if there was no timer.\n   */\n  private clearTimer(): boolean {\n    if (this.timerId !== null) {\n      clearTimeout(this.timerId);\n\n      this.timerId = null;\n\n      return true;\n    }\n\n    return false;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,143 @@
+/**
+ * Batches items and emits a "flush" event after a delay (e.g. after last push).
+ * Event-based: create instance, subscribe via subscribe(BATCH_FLUSH_EVENT, callback), call push() from UI.
+ * Optional persistence: storageType can be memory, localStorage, or sessionStorage so the batch survives refresh/close.
+ */
+type BatchCollectorStorageType = "memory" | "localStorage" | "sessionStorage";
+type BatchCollectorConfig = {
+    /** Delay in milliseconds before flushing the batch (e.g. 5000 = 5 seconds). */
+    delayMs: number;
+    /** If true, timer resets on each push (flush N ms after last push). If false, flush exactly N ms after first push. Default true. */
+    resetTimerOnPush?: boolean;
+    /** Where to keep the buffer: "memory" (default), "localStorage", or "sessionStorage". When not memory, buffer is persisted and re-flushed on next load if any. */
+    storageType?: BatchCollectorStorageType;
+    /** Storage key when storageType is localStorage or sessionStorage. Should be unique per collector instance. Default "batch-collector-pending". */
+    storageKey?: string;
+    /** If true (default), buffer and storage are cleared when the timer fires. If false, only on manual clear() call. */
+    autoClear?: boolean;
+};
+/** Event name emitted when the batch is flushed. */
+declare const BATCH_FLUSH_EVENT = "flush";
+type FlushListener<T> = (items: T[]) => void;
+/**
+ * Collects items in a buffer and emits BATCH_FLUSH_EVENT with the batched array after a delay (e.g. after the last push).
+ * Use for batching UI events (clicks, logs) before sending to server or analytics. Item type is generic (objects, numbers, strings, or any T).
+ *
+ * Parameters (config):
+ * - delayMs (required) — delay in ms before emitting the batch (e.g. 5000 = 5 seconds).
+ * - resetTimerOnPush (optional) — if true (default), timer resets on each push; if false, emit exactly delayMs after first push.
+ * - storageType (optional) — "memory" (default), "localStorage", or "sessionStorage". When not memory, batch is persisted and re-emitted on next load.
+ * - storageKey (optional) — storage key when using localStorage/sessionStorage. Unique per instance. Default "batch-collector-pending".
+ * - autoClear (optional) — if true (default), buffer and storage are cleared when the timer fires; if false, only on manual clear().
+ *
+ * Public API:
+ * - subscribe(event, callback) — subscribe to flush events; callback receives the batch. Returns unsubscribe function.
+ * - push(item) — add an item and (re)start the timer.
+ * - items() — returns a copy of the current batch (optional; does not emit or clear).
+ * - clear() — clears buffer and storage (optional; e.g. call from the subscriber after a successful send).
+ *
+ * @example
+ * const collector = new BatchCollector<{ action: string; id: string }>({
+ *   delayMs: 5000,
+ *   storageType: "localStorage",
+ *   storageKey: "my-app-log-batch"
+ * });
+ * collector.subscribe(BATCH_FLUSH_EVENT, (items) => sendToBackend(items));
+ * collector.push({ action: "button_click", id: "submit-btn" });
+ *
+ * Optional:
+ * collector.items()  // copy of current batch
+ * collector.clear() // clear buffer and storage (e.g. after successful send in subscriber)
+ */
+declare class BatchCollector<T = unknown> {
+    private buffer;
+    private timerId;
+    private readonly delayMs;
+    private readonly resetTimerOnPush;
+    private readonly storageType;
+    private readonly storageKey;
+    private readonly autoClear;
+    private readonly listeners;
+    /**
+     * Creates a batch collector instance.
+     *
+     * @param {BatchCollectorConfig} config - Configuration object with delay, optional reset behaviour, and optional storageType.
+     */
+    constructor(config: BatchCollectorConfig);
+    /**
+     * Subscribe to an event. When the batch is flushed, the "flush" event is emitted with the batched items.
+     *
+     * @param {string} event - Event name; use BATCH_FLUSH_EVENT ("flush") for flush events.
+     * @param {FlushListener<T>} callback - Function called with the batched items when the event is emitted.
+     * @returns {() => void} Unsubscribe function; call to remove the listener.
+     */
+    subscribe(event: string, callback: FlushListener<T>): () => void;
+    /**
+     * Add an item to the batch and (re)start the flush timer. When storageType is not memory, also persists the buffer.
+     *
+     * @param {T} item - Item to add to the current batch.
+     * @returns {void}
+     */
+    push(item: T): void;
+    /**
+     * Returns a copy of the current buffer. Does not emit, clear, or change state.
+     *
+     * @returns {T[]} Copy of all items in the batch.
+     */
+    items(): T[];
+    /**
+     * Clears the pending timer, the buffer, and persisted storage. Does not emit.
+     *
+     * @returns {boolean} True.
+     */
+    clear(): boolean;
+    /**
+     * Returns the Storage instance for the configured storage type, or null if unavailable (e.g. SSR).
+     *
+     * @returns {Storage | null} window.localStorage, window.sessionStorage, or null.
+     */
+    private getStorage;
+    /**
+     * Reads the persisted buffer from storage.
+     *
+     * @returns {T[]} Parsed buffer from storage, or empty array if unavailable or parse error.
+     */
+    private readPersisted;
+    /**
+     * Writes the buffer to storage, or removes the key when the buffer is empty.
+     *
+     * @param {T[]} items - Current buffer to persist.
+     * @returns {boolean} True if write succeeded, false otherwise.
+     */
+    private writePersisted;
+    /**
+     * Emits the current batch to subscribers and optionally clears buffer and storage. Used internally by the timer.
+     * When autoClear is false, the timer calls flush(false) so only manual clear() clears.
+     *
+     * @param {boolean} clear - If true (default), clear buffer and storage after emit. If false, only emit.
+     * @returns {boolean} True if the batch was emitted, false if buffer was empty.
+     */
+    private flush;
+    /**
+     * Emits an event with the given payload to all subscribers of that event.
+     *
+     * @param {string} event - Event name to emit.
+     * @param {T[]} payload - Data to pass to each listener.
+     * @returns {void}
+     */
+    private emit;
+    /**
+     * Schedules a flush after the configured delay. If resetTimerOnPush is true, clears existing timer first.
+     *
+     * @returns {boolean} True if timer was scheduled, false if already scheduled (resetTimerOnPush false).
+     */
+    private scheduleFlush;
+    /**
+     * Clears the pending flush timer if one is set. Does nothing if no timer is set.
+     *
+     * @returns {boolean} True if a timer was cleared, false if there was no timer.
+     */
+    private clearTimer;
+}
+
+export { BATCH_FLUSH_EVENT, BatchCollector, type BatchCollectorConfig, type BatchCollectorStorageType };

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Batches items and emits a "flush" event after a delay (e.g. after last push).
+ * Event-based: create instance, subscribe via subscribe(BATCH_FLUSH_EVENT, callback), call push() from UI.
+ * Optional persistence: storageType can be memory, localStorage, or sessionStorage so the batch survives refresh/close.
+ */
+type BatchCollectorStorageType = "memory" | "localStorage" | "sessionStorage";
+type BatchCollectorConfig = {
+    /** Delay in milliseconds before flushing the batch (e.g. 5000 = 5 seconds). */
+    delayMs: number;
+    /** If true, timer resets on each push (flush N ms after last push). If false, flush exactly N ms after first push. Default true. */
+    resetTimerOnPush?: boolean;
+    /** Where to keep the buffer: "memory" (default), "localStorage", or "sessionStorage". When not memory, buffer is persisted and re-flushed on next load if any. */
+    storageType?: BatchCollectorStorageType;
+    /** Storage key when storageType is localStorage or sessionStorage. Should be unique per collector instance. Default "batch-collector-pending". */
+    storageKey?: string;
+    /** If true (default), buffer and storage are cleared when the timer fires. If false, only on manual clear() call. */
+    autoClear?: boolean;
+};
+/** Event name emitted when the batch is flushed. */
+declare const BATCH_FLUSH_EVENT = "flush";
+type FlushListener<T> = (items: T[]) => void;
+/**
+ * Collects items in a buffer and emits BATCH_FLUSH_EVENT with the batched array after a delay (e.g. after the last push).
+ * Use for batching UI events (clicks, logs) before sending to server or analytics. Item type is generic (objects, numbers, strings, or any T).
+ *
+ * Parameters (config):
+ * - delayMs (required) — delay in ms before emitting the batch (e.g. 5000 = 5 seconds).
+ * - resetTimerOnPush (optional) — if true (default), timer resets on each push; if false, emit exactly delayMs after first push.
+ * - storageType (optional) — "memory" (default), "localStorage", or "sessionStorage". When not memory, batch is persisted and re-emitted on next load.
+ * - storageKey (optional) — storage key when using localStorage/sessionStorage. Unique per instance. Default "batch-collector-pending".
+ * - autoClear (optional) — if true (default), buffer and storage are cleared when the timer fires; if false, only on manual clear().
+ *
+ * Public API:
+ * - subscribe(event, callback) — subscribe to flush events; callback receives the batch. Returns unsubscribe function.
+ * - push(item) — add an item and (re)start the timer.
+ * - items() — returns a copy of the current batch (optional; does not emit or clear).
+ * - clear() — clears buffer and storage (optional; e.g. call from the subscriber after a successful send).
+ *
+ * @example
+ * const collector = new BatchCollector<{ action: string; id: string }>({
+ *   delayMs: 5000,
+ *   storageType: "localStorage",
+ *   storageKey: "my-app-log-batch"
+ * });
+ * collector.subscribe(BATCH_FLUSH_EVENT, (items) => sendToBackend(items));
+ * collector.push({ action: "button_click", id: "submit-btn" });
+ *
+ * Optional:
+ * collector.items()  // copy of current batch
+ * collector.clear() // clear buffer and storage (e.g. after successful send in subscriber)
+ */
+declare class BatchCollector<T = unknown> {
+    private buffer;
+    private timerId;
+    private readonly delayMs;
+    private readonly resetTimerOnPush;
+    private readonly storageType;
+    private readonly storageKey;
+    private readonly autoClear;
+    private readonly listeners;
+    /**
+     * Creates a batch collector instance.
+     *
+     * @param {BatchCollectorConfig} config - Configuration object with delay, optional reset behaviour, and optional storageType.
+     */
+    constructor(config: BatchCollectorConfig);
+    /**
+     * Subscribe to an event. When the batch is flushed, the "flush" event is emitted with the batched items.
+     *
+     * @param {string} event - Event name; use BATCH_FLUSH_EVENT ("flush") for flush events.
+     * @param {FlushListener<T>} callback - Function called with the batched items when the event is emitted.
+     * @returns {() => void} Unsubscribe function; call to remove the listener.
+     */
+    subscribe(event: string, callback: FlushListener<T>): () => void;
+    /**
+     * Add an item to the batch and (re)start the flush timer. When storageType is not memory, also persists the buffer.
+     *
+     * @param {T} item - Item to add to the current batch.
+     * @returns {void}
+     */
+    push(item: T): void;
+    /**
+     * Returns a copy of the current buffer. Does not emit, clear, or change state.
+     *
+     * @returns {T[]} Copy of all items in the batch.
+     */
+    items(): T[];
+    /**
+     * Clears the pending timer, the buffer, and persisted storage. Does not emit.
+     *
+     * @returns {boolean} True.
+     */
+    clear(): boolean;
+    /**
+     * Returns the Storage instance for the configured storage type, or null if unavailable (e.g. SSR).
+     *
+     * @returns {Storage | null} window.localStorage, window.sessionStorage, or null.
+     */
+    private getStorage;
+    /**
+     * Reads the persisted buffer from storage.
+     *
+     * @returns {T[]} Parsed buffer from storage, or empty array if unavailable or parse error.
+     */
+    private readPersisted;
+    /**
+     * Writes the buffer to storage, or removes the key when the buffer is empty.
+     *
+     * @param {T[]} items - Current buffer to persist.
+     * @returns {boolean} True if write succeeded, false otherwise.
+     */
+    private writePersisted;
+    /**
+     * Emits the current batch to subscribers and optionally clears buffer and storage. Used internally by the timer.
+     * When autoClear is false, the timer calls flush(false) so only manual clear() clears.
+     *
+     * @param {boolean} clear - If true (default), clear buffer and storage after emit. If false, only emit.
+     * @returns {boolean} True if the batch was emitted, false if buffer was empty.
+     */
+    private flush;
+    /**
+     * Emits an event with the given payload to all subscribers of that event.
+     *
+     * @param {string} event - Event name to emit.
+     * @param {T[]} payload - Data to pass to each listener.
+     * @returns {void}
+     */
+    private emit;
+    /**
+     * Schedules a flush after the configured delay. If resetTimerOnPush is true, clears existing timer first.
+     *
+     * @returns {boolean} True if timer was scheduled, false if already scheduled (resetTimerOnPush false).
+     */
+    private scheduleFlush;
+    /**
+     * Clears the pending flush timer if one is set. Does nothing if no timer is set.
+     *
+     * @returns {boolean} True if a timer was cleared, false if there was no timer.
+     */
+    private clearTimer;
+}
+
+export { BATCH_FLUSH_EVENT, BatchCollector, type BatchCollectorConfig, type BatchCollectorStorageType };

package/dist/index.js

@@ -0,0 +1,200 @@
+// src/index.ts
+var BATCH_FLUSH_EVENT = "flush";
+var DEFAULT_STORAGE_KEY = "batch-collector-pending";
+var BatchCollector = class {
+  /**
+   * Creates a batch collector instance.
+   *
+   * @param {BatchCollectorConfig} config - Configuration object with delay, optional reset behaviour, and optional storageType.
+   */
+  constructor(config) {
+    this.buffer = [];
+    this.timerId = null;
+    this.listeners = /* @__PURE__ */ new Map();
+    var _a, _b, _c, _d;
+    this.delayMs = config.delayMs;
+    this.resetTimerOnPush = (_a = config.resetTimerOnPush) != null ? _a : true;
+    this.storageType = (_b = config.storageType) != null ? _b : "memory";
+    this.storageKey = (_c = config.storageKey) != null ? _c : DEFAULT_STORAGE_KEY;
+    this.autoClear = (_d = config.autoClear) != null ? _d : true;
+    if (this.storageType !== "memory") {
+      const pending = this.readPersisted();
+      if (pending.length !== 0) {
+        this.writePersisted([]);
+        this.emit(BATCH_FLUSH_EVENT, pending);
+      }
+    }
+  }
+  /**
+   * Subscribe to an event. When the batch is flushed, the "flush" event is emitted with the batched items.
+   *
+   * @param {string} event - Event name; use BATCH_FLUSH_EVENT ("flush") for flush events.
+   * @param {FlushListener<T>} callback - Function called with the batched items when the event is emitted.
+   * @returns {() => void} Unsubscribe function; call to remove the listener.
+   */
+  subscribe(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(callback);
+    return () => {
+      var _a;
+      return (_a = this.listeners.get(event)) == null ? void 0 : _a.delete(callback);
+    };
+  }
+  /**
+   * Add an item to the batch and (re)start the flush timer. When storageType is not memory, also persists the buffer.
+   *
+   * @param {T} item - Item to add to the current batch.
+   * @returns {void}
+   */
+  push(item) {
+    this.buffer.push(item);
+    if (this.storageType !== "memory") {
+      this.writePersisted(this.buffer);
+    }
+    this.scheduleFlush();
+  }
+  /**
+   * Returns a copy of the current buffer. Does not emit, clear, or change state.
+   *
+   * @returns {T[]} Copy of all items in the batch.
+   */
+  items() {
+    return [...this.buffer];
+  }
+  /**
+   * Clears the pending timer, the buffer, and persisted storage. Does not emit.
+   *
+   * @returns {boolean} True.
+   */
+  clear() {
+    this.clearTimer();
+    this.buffer = [];
+    if (this.storageType !== "memory") {
+      this.writePersisted([]);
+    }
+    return true;
+  }
+  /**
+   * Returns the Storage instance for the configured storage type, or null if unavailable (e.g. SSR).
+   *
+   * @returns {Storage | null} window.localStorage, window.sessionStorage, or null.
+   */
+  getStorage() {
+    if (typeof window === "undefined") {
+      return null;
+    }
+    if (this.storageType === "localStorage") {
+      return window.localStorage;
+    }
+    if (this.storageType === "sessionStorage") {
+      return window.sessionStorage;
+    }
+    return null;
+  }
+  /**
+   * Reads the persisted buffer from storage.
+   *
+   * @returns {T[]} Parsed buffer from storage, or empty array if unavailable or parse error.
+   */
+  readPersisted() {
+    const storage = this.getStorage();
+    if (!storage) {
+      return [];
+    }
+    try {
+      const raw = storage.getItem(this.storageKey);
+      return raw ? JSON.parse(raw) : [];
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Writes the buffer to storage, or removes the key when the buffer is empty.
+   *
+   * @param {T[]} items - Current buffer to persist.
+   * @returns {boolean} True if write succeeded, false otherwise.
+   */
+  writePersisted(items) {
+    const storage = this.getStorage();
+    if (!storage) {
+      return false;
+    }
+    try {
+      if (items.length === 0) {
+        storage.removeItem(this.storageKey);
+      } else {
+        storage.setItem(this.storageKey, JSON.stringify(items));
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Emits the current batch to subscribers and optionally clears buffer and storage. Used internally by the timer.
+   * When autoClear is false, the timer calls flush(false) so only manual clear() clears.
+   *
+   * @param {boolean} clear - If true (default), clear buffer and storage after emit. If false, only emit.
+   * @returns {boolean} True if the batch was emitted, false if buffer was empty.
+   */
+  flush(clear = true) {
+    this.clearTimer();
+    if (this.buffer.length === 0) {
+      return false;
+    }
+    const items = [...this.buffer];
+    if (clear) {
+      this.buffer = [];
+      if (this.storageType !== "memory") {
+        this.writePersisted([]);
+      }
+    }
+    this.emit(BATCH_FLUSH_EVENT, items);
+    return true;
+  }
+  /**
+   * Emits an event with the given payload to all subscribers of that event.
+   *
+   * @param {string} event - Event name to emit.
+   * @param {T[]} payload - Data to pass to each listener.
+   * @returns {void}
+   */
+  emit(event, payload) {
+    var _a;
+    (_a = this.listeners.get(event)) == null ? void 0 : _a.forEach((cb) => cb(payload));
+  }
+  /**
+   * Schedules a flush after the configured delay. If resetTimerOnPush is true, clears existing timer first.
+   *
+   * @returns {boolean} True if timer was scheduled, false if already scheduled (resetTimerOnPush false).
+   */
+  scheduleFlush() {
+    if (this.resetTimerOnPush) {
+      this.clearTimer();
+    } else if (this.timerId !== null) {
+      return false;
+    }
+    this.timerId = setTimeout(() => this.flush(this.autoClear), this.delayMs);
+    return true;
+  }
+  /**
+   * Clears the pending flush timer if one is set. Does nothing if no timer is set.
+   *
+   * @returns {boolean} True if a timer was cleared, false if there was no timer.
+   */
+  clearTimer() {
+    if (this.timerId !== null) {
+      clearTimeout(this.timerId);
+      this.timerId = null;
+      return true;
+    }
+    return false;
+  }
+};
+export {
+  BATCH_FLUSH_EVENT,
+  BatchCollector
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Batches items and emits a \"flush\" event after a delay (e.g. after last push).\n * Event-based: create instance, subscribe via subscribe(BATCH_FLUSH_EVENT, callback), call push() from UI.\n * Optional persistence: storageType can be memory, localStorage, or sessionStorage so the batch survives refresh/close.\n */\n\nexport type BatchCollectorStorageType = \"memory\" | \"localStorage\" | \"sessionStorage\";\n\nexport type BatchCollectorConfig = {\n  /** Delay in milliseconds before flushing the batch (e.g. 5000 = 5 seconds). */\n  delayMs: number;\n  /** If true, timer resets on each push (flush N ms after last push). If false, flush exactly N ms after first push. Default true. */\n  resetTimerOnPush?: boolean;\n  /** Where to keep the buffer: \"memory\" (default), \"localStorage\", or \"sessionStorage\". When not memory, buffer is persisted and re-flushed on next load if any. */\n  storageType?: BatchCollectorStorageType;\n  /** Storage key when storageType is localStorage or sessionStorage. Should be unique per collector instance. Default \"batch-collector-pending\". */\n  storageKey?: string;\n  /** If true (default), buffer and storage are cleared when the timer fires. If false, only on manual clear() call. */\n  autoClear?: boolean;\n};\n\n/** Event name emitted when the batch is flushed. */\nexport const BATCH_FLUSH_EVENT = \"flush\";\n\ntype FlushListener<T> = (items: T[]) => void;\n\nconst DEFAULT_STORAGE_KEY = \"batch-collector-pending\";\n\n/**\n * Collects items in a buffer and emits BATCH_FLUSH_EVENT with the batched array after a delay (e.g. after the last push).\n * Use for batching UI events (clicks, logs) before sending to server or analytics. Item type is generic (objects, numbers, strings, or any T).\n *\n * Parameters (config):\n * - delayMs (required) — delay in ms before emitting the batch (e.g. 5000 = 5 seconds).\n * - resetTimerOnPush (optional) — if true (default), timer resets on each push; if false, emit exactly delayMs after first push.\n * - storageType (optional) — \"memory\" (default), \"localStorage\", or \"sessionStorage\". When not memory, batch is persisted and re-emitted on next load.\n * - storageKey (optional) — storage key when using localStorage/sessionStorage. Unique per instance. Default \"batch-collector-pending\".\n * - autoClear (optional) — if true (default), buffer and storage are cleared when the timer fires; if false, only on manual clear().\n *\n * Public API:\n * - subscribe(event, callback) — subscribe to flush events; callback receives the batch. Returns unsubscribe function.\n * - push(item) — add an item and (re)start the timer.\n * - items() — returns a copy of the current batch (optional; does not emit or clear).\n * - clear() — clears buffer and storage (optional; e.g. call from the subscriber after a successful send).\n *\n * @example\n * const collector = new BatchCollector<{ action: string; id: string }>({\n *   delayMs: 5000,\n *   storageType: \"localStorage\",\n *   storageKey: \"my-app-log-batch\"\n * });\n * collector.subscribe(BATCH_FLUSH_EVENT, (items) => sendToBackend(items));\n * collector.push({ action: \"button_click\", id: \"submit-btn\" });\n *\n * Optional:\n * collector.items()  // copy of current batch\n * collector.clear() // clear buffer and storage (e.g. after successful send in subscriber)\n */\nexport class BatchCollector<T = unknown> {\n  private buffer: T[] = [];\n  private timerId: ReturnType<typeof setTimeout> | null = null;\n\n  private readonly delayMs: number;\n  private readonly resetTimerOnPush: boolean;\n  private readonly storageType: BatchCollectorStorageType;\n  private readonly storageKey: string;\n  private readonly autoClear: boolean;\n  private readonly listeners = new Map<string, Set<FlushListener<T>>>();\n\n  /**\n   * Creates a batch collector instance.\n   *\n   * @param {BatchCollectorConfig} config - Configuration object with delay, optional reset behaviour, and optional storageType.\n   */\n  constructor(config: BatchCollectorConfig) {\n    this.delayMs = config.delayMs;\n    this.resetTimerOnPush = config.resetTimerOnPush ?? true;\n    this.storageType = config.storageType ?? \"memory\";\n    this.storageKey = config.storageKey ?? DEFAULT_STORAGE_KEY;\n    this.autoClear = config.autoClear ?? true;\n\n    if (this.storageType !== \"memory\") {\n      const pending = this.readPersisted();\n\n      if (pending.length !== 0) {\n        this.writePersisted([]);\n        this.emit(BATCH_FLUSH_EVENT, pending);\n      }\n    }\n  }\n\n  /**\n   * Subscribe to an event. When the batch is flushed, the \"flush\" event is emitted with the batched items.\n   *\n   * @param {string} event - Event name; use BATCH_FLUSH_EVENT (\"flush\") for flush events.\n   * @param {FlushListener<T>} callback - Function called with the batched items when the event is emitted.\n   * @returns {() => void} Unsubscribe function; call to remove the listener.\n   */\n  public subscribe(event: string, callback: FlushListener<T>): () => void {\n    if (!this.listeners.has(event)) {\n      this.listeners.set(event, new Set());\n    }\n\n    this.listeners.get(event)!.add(callback);\n\n    return () => this.listeners.get(event)?.delete(callback);\n  }\n\n  /**\n   * Add an item to the batch and (re)start the flush timer. When storageType is not memory, also persists the buffer.\n   *\n   * @param {T} item - Item to add to the current batch.\n   * @returns {void}\n   */\n  public push(item: T): void {\n    this.buffer.push(item);\n\n    if (this.storageType !== \"memory\") {\n      this.writePersisted(this.buffer);\n    }\n\n    this.scheduleFlush();\n  }\n\n  /**\n   * Returns a copy of the current buffer. Does not emit, clear, or change state.\n   *\n   * @returns {T[]} Copy of all items in the batch.\n   */\n  public items(): T[] {\n    return [...this.buffer];\n  }\n\n  /**\n   * Clears the pending timer, the buffer, and persisted storage. Does not emit.\n   *\n   * @returns {boolean} True.\n   */\n  public clear(): boolean {\n    this.clearTimer();\n    this.buffer = [];\n\n    if (this.storageType !== \"memory\") {\n      this.writePersisted([]);\n    }\n\n    return true;\n  }\n\n  /**\n   * Returns the Storage instance for the configured storage type, or null if unavailable (e.g. SSR).\n   *\n   * @returns {Storage | null} window.localStorage, window.sessionStorage, or null.\n   */\n  private getStorage(): Storage | null {\n    if (typeof window === \"undefined\") {\n      return null;\n    }\n\n    if (this.storageType === \"localStorage\") {\n      return window.localStorage;\n    }\n\n    if (this.storageType === \"sessionStorage\") {\n      return window.sessionStorage;\n    }\n\n    return null;\n  }\n\n  /**\n   * Reads the persisted buffer from storage.\n   *\n   * @returns {T[]} Parsed buffer from storage, or empty array if unavailable or parse error.\n   */\n  private readPersisted(): T[] {\n    const storage = this.getStorage();\n\n    if (!storage) {\n      return [];\n    }\n\n    try {\n      const raw = storage.getItem(this.storageKey);\n\n      return raw ? (JSON.parse(raw) as T[]) : [];\n    } catch {\n      return [];\n    }\n  }\n\n  /**\n   * Writes the buffer to storage, or removes the key when the buffer is empty.\n   *\n   * @param {T[]} items - Current buffer to persist.\n   * @returns {boolean} True if write succeeded, false otherwise.\n   */\n  private writePersisted(items: T[]): boolean {\n    const storage = this.getStorage();\n\n    if (!storage) {\n      return false;\n    }\n\n    try {\n      if (items.length === 0) {\n        storage.removeItem(this.storageKey);\n      } else {\n        storage.setItem(this.storageKey, JSON.stringify(items));\n      }\n\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Emits the current batch to subscribers and optionally clears buffer and storage. Used internally by the timer.\n   * When autoClear is false, the timer calls flush(false) so only manual clear() clears.\n   *\n   * @param {boolean} clear - If true (default), clear buffer and storage after emit. If false, only emit.\n   * @returns {boolean} True if the batch was emitted, false if buffer was empty.\n   */\n  private flush(clear: boolean = true): boolean {\n    this.clearTimer();\n\n    if (this.buffer.length === 0) {\n      return false;\n    }\n\n    const items = [...this.buffer];\n\n    if (clear) {\n      this.buffer = [];\n\n      if (this.storageType !== \"memory\") {\n        this.writePersisted([]);\n      }\n    }\n\n    this.emit(BATCH_FLUSH_EVENT, items);\n\n    return true;\n  }\n\n  /**\n   * Emits an event with the given payload to all subscribers of that event.\n   *\n   * @param {string} event - Event name to emit.\n   * @param {T[]} payload - Data to pass to each listener.\n   * @returns {void}\n   */\n  private emit(event: string, payload: T[]): void {\n    this.listeners.get(event)?.forEach((cb) => cb(payload));\n  }\n\n  /**\n   * Schedules a flush after the configured delay. If resetTimerOnPush is true, clears existing timer first.\n   *\n   * @returns {boolean} True if timer was scheduled, false if already scheduled (resetTimerOnPush false).\n   */\n  private scheduleFlush(): boolean {\n    if (this.resetTimerOnPush) {\n      this.clearTimer();\n    } else if (this.timerId !== null) {\n      return false; // already scheduled from first push\n    }\n\n    this.timerId = setTimeout(() => this.flush(this.autoClear), this.delayMs);\n\n    return true;\n  }\n\n  /**\n   * Clears the pending flush timer if one is set. Does nothing if no timer is set.\n   *\n   * @returns {boolean} True if a timer was cleared, false if there was no timer.\n   */\n  private clearTimer(): boolean {\n    if (this.timerId !== null) {\n      clearTimeout(this.timerId);\n\n      this.timerId = null;\n\n      return true;\n    }\n\n    return false;\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@js-nerds/batch-collector",
+  "version": "0.1.0",
+  "description": "Lightweight TypeScript batch collector with delayed flush and optional persistence.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "keywords": [
+    "batch",
+    "collector",
+    "queue",
+    "typescript",
+    "buffer"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/js-nerds/batch-collector.git"
+  },
+  "homepage": "https://github.com/js-nerds/batch-collector#readme",
+  "bugs": {
+    "url": "https://github.com/js-nerds/batch-collector/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --dts --format cjs,esm --sourcemap --clean",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "pnpm build"
+  },
+  "packageManager": "pnpm@9.0.0",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "jsdom": "^25.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.4"
+  }
+}