@spoosh/plugin-gc 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Spoosh
+
+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/dist/index.d.mts

@@ -0,0 +1,55 @@
+import { SpooshPlugin } from '@spoosh/core';
+
+type GcPluginOptions = {
+    /**
+     * Maximum age in milliseconds for cache entries.
+     * Entries older than this will be removed.
+     * @default undefined (no time-based cleanup)
+     */
+    maxAge?: number;
+    /**
+     * Maximum number of cache entries to keep.
+     * When exceeded, oldest entries are removed first.
+     * @default undefined (no size limit)
+     */
+    maxEntries?: number;
+    /**
+     * Interval in milliseconds between GC runs.
+     * @default 60000 (1 minute)
+     */
+    interval?: number;
+};
+type GcPluginExports = {
+    /** Manually trigger garbage collection. Returns number of entries removed. */
+    runGc: () => number;
+};
+/**
+ * Garbage collection plugin for automatic cache cleanup.
+ *
+ * Removes stale cache entries based on age or total count
+ * to prevent memory bloat in long-running applications.
+ *
+ * @param options - Plugin options
+ *
+ * @see {@link https://spoosh.dev/docs/plugins/gc | GC Plugin Documentation}
+ *
+ * @example
+ * ```ts
+ * const plugins = [
+ *   gcPlugin({
+ *     maxAge: 60000,     // Remove entries older than 1 minute
+ *     maxEntries: 100,   // Keep max 100 entries
+ *     interval: 30000,   // Run GC every 30 seconds
+ *   }),
+ * ];
+ *
+ * // Manual GC trigger
+ * const { runGc } = createReactSpoosh(client);
+ * const removedCount = runGc();
+ * ```
+ */
+declare function gcPlugin(options?: GcPluginOptions): SpooshPlugin<{
+    instanceApi: GcPluginExports;
+}>;
+
+export { type GcPluginExports, type GcPluginOptions, gcPlugin };

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { SpooshPlugin } from '@spoosh/core';
+
+type GcPluginOptions = {
+    /**
+     * Maximum age in milliseconds for cache entries.
+     * Entries older than this will be removed.
+     * @default undefined (no time-based cleanup)
+     */
+    maxAge?: number;
+    /**
+     * Maximum number of cache entries to keep.
+     * When exceeded, oldest entries are removed first.
+     * @default undefined (no size limit)
+     */
+    maxEntries?: number;
+    /**
+     * Interval in milliseconds between GC runs.
+     * @default 60000 (1 minute)
+     */
+    interval?: number;
+};
+type GcPluginExports = {
+    /** Manually trigger garbage collection. Returns number of entries removed. */
+    runGc: () => number;
+};
+/**
+ * Garbage collection plugin for automatic cache cleanup.
+ *
+ * Removes stale cache entries based on age or total count
+ * to prevent memory bloat in long-running applications.
+ *
+ * @param options - Plugin options
+ *
+ * @see {@link https://spoosh.dev/docs/plugins/gc | GC Plugin Documentation}
+ *
+ * @example
+ * ```ts
+ * const plugins = [
+ *   gcPlugin({
+ *     maxAge: 60000,     // Remove entries older than 1 minute
+ *     maxEntries: 100,   // Keep max 100 entries
+ *     interval: 30000,   // Run GC every 30 seconds
+ *   }),
+ * ];
+ *
+ * // Manual GC trigger
+ * const { runGc } = createReactSpoosh(client);
+ * const removedCount = runGc();
+ * ```
+ */
+declare function gcPlugin(options?: GcPluginOptions): SpooshPlugin<{
+    instanceApi: GcPluginExports;
+}>;
+
+export { type GcPluginExports, type GcPluginOptions, gcPlugin };

package/dist/index.js

@@ -0,0 +1,82 @@
+"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 src_exports = {};
+__export(src_exports, {
+  gcPlugin: () => gcPlugin
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/plugin.ts
+function runGarbageCollection(stateManager, options) {
+  const { maxAge, maxEntries } = options;
+  const now = Date.now();
+  let removedCount = 0;
+  const entries = stateManager.getAllCacheEntries();
+  if (maxAge !== void 0) {
+    for (const { key, entry } of entries) {
+      const age = now - entry.state.timestamp;
+      if (age > maxAge) {
+        stateManager.deleteCache(key);
+        removedCount++;
+      }
+    }
+  }
+  if (maxEntries !== void 0) {
+    const currentEntries = stateManager.getAllCacheEntries();
+    const excess = currentEntries.length - maxEntries;
+    if (excess > 0) {
+      const sorted = currentEntries.sort(
+        (a, b) => a.entry.state.timestamp - b.entry.state.timestamp
+      );
+      for (let i = 0; i < excess; i++) {
+        const entry = sorted[i];
+        if (entry) {
+          stateManager.deleteCache(entry.key);
+          removedCount++;
+        }
+      }
+    }
+  }
+  return removedCount;
+}
+function gcPlugin(options = {}) {
+  const { interval = 6e4 } = options;
+  return {
+    name: "spoosh:gc",
+    operations: [],
+    instanceApi(context) {
+      const { stateManager } = context;
+      const runGc = () => {
+        return runGarbageCollection(stateManager, options);
+      };
+      setInterval(() => {
+        runGc();
+      }, interval);
+      return {
+        runGc
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  gcPlugin
+});

package/dist/index.mjs

@@ -0,0 +1,55 @@
+// src/plugin.ts
+function runGarbageCollection(stateManager, options) {
+  const { maxAge, maxEntries } = options;
+  const now = Date.now();
+  let removedCount = 0;
+  const entries = stateManager.getAllCacheEntries();
+  if (maxAge !== void 0) {
+    for (const { key, entry } of entries) {
+      const age = now - entry.state.timestamp;
+      if (age > maxAge) {
+        stateManager.deleteCache(key);
+        removedCount++;
+      }
+    }
+  }
+  if (maxEntries !== void 0) {
+    const currentEntries = stateManager.getAllCacheEntries();
+    const excess = currentEntries.length - maxEntries;
+    if (excess > 0) {
+      const sorted = currentEntries.sort(
+        (a, b) => a.entry.state.timestamp - b.entry.state.timestamp
+      );
+      for (let i = 0; i < excess; i++) {
+        const entry = sorted[i];
+        if (entry) {
+          stateManager.deleteCache(entry.key);
+          removedCount++;
+        }
+      }
+    }
+  }
+  return removedCount;
+}
+function gcPlugin(options = {}) {
+  const { interval = 6e4 } = options;
+  return {
+    name: "spoosh:gc",
+    operations: [],
+    instanceApi(context) {
+      const { stateManager } = context;
+      const runGc = () => {
+        return runGarbageCollection(stateManager, options);
+      };
+      setInterval(() => {
+        runGc();
+      }, interval);
+      return {
+        runGc
+      };
+    }
+  };
+}
+export {
+  gcPlugin
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@spoosh/plugin-gc",
+  "version": "0.1.0-beta.0",
+  "description": "Garbage collection plugin for Spoosh cache with time and size-based cleanup",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nxnom/spoosh.git",
+    "directory": "packages/plugin-gc"
+  },
+  "bugs": {
+    "url": "https://github.com/nxnom/spoosh/issues"
+  },
+  "homepage": "https://spoosh.dev/docs/plugins/gc",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "spoosh",
+    "plugin",
+    "gc",
+    "garbage-collection",
+    "cache",
+    "memory"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@spoosh/core": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@spoosh/core": "0.1.0-beta.0",
+    "@spoosh/test-utils": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --max-warnings 0",
+    "format": "prettier --write 'src/**/*.ts'"
+  }
+}