safe-memory-layer 1.0.0

package/src/Stats.ts

@@ -0,0 +1,138 @@
+/**
+ * Statistics tracking for safe-memory-layer.
+ *
+ * Tracks store metrics including entry counts, expiration counts,
+ * deletion counts, cleanup cycles, uptime, and memory estimates.
+ *
+ * @module Stats
+ */
+
+import type { StoreStats, CleanupStats } from "./types.js";
+
+/**
+ * Tracks statistics for a MemoryStore instance.
+ *
+ * All counters are monotonically increasing (except entries).
+ */
+export class Stats {
+  /** Total number of entries that have expired. */
+  #expired = 0;
+
+  /** Total number of entries that have been deleted. */
+  #deleted = 0;
+
+  /** Total number of cleanup cycles completed. */
+  #cleaned = 0;
+
+  /** Timestamp when the store was created. */
+  readonly #createdAt: number;
+
+  /** Current number of entries in the store. */
+  #entries = 0;
+
+  /**
+   * Creates a new Stats instance.
+   *
+   * @param createdAt - Timestamp when the store was created.
+   */
+  constructor(createdAt: number) {
+    this.#createdAt = createdAt;
+  }
+
+  /**
+   * Increments the expired counter.
+   */
+  incrementExpired(): void {
+    this.#expired++;
+  }
+
+  /**
+   * Increments the deleted counter.
+   */
+  incrementDeleted(): void {
+    this.#deleted++;
+  }
+
+  /**
+   * Increments the cleaned counter.
+   */
+  incrementCleaned(): void {
+    this.#cleaned++;
+  }
+
+  /**
+   * Sets the current number of entries.
+   *
+   * @param count - The current entry count.
+   */
+  setEntries(count: number): void {
+    this.#entries = count;
+  }
+
+  /**
+   * Returns the current statistics snapshot.
+   *
+   * @param currentEntries - Current number of entries (overrides internal count).
+   * @returns A snapshot of the current statistics.
+   */
+  snapshot(currentEntries?: number): StoreStats {
+    const uptime = Date.now() - this.#createdAt;
+    const entries = currentEntries ?? this.#entries;
+
+    return {
+      entries,
+      expired: this.#expired,
+      deleted: this.#deleted,
+      cleaned: this.#cleaned,
+      uptime,
+      memoryEstimate: this.estimateMemory(entries),
+    };
+  }
+
+  /**
+   * Creates a cleanup stats object.
+   *
+   * @param removed - Number of entries removed.
+   * @param totalBefore - Total entries before cleanup.
+   * @param totalAfter - Total entries after cleanup.
+   * @param duration - Duration of cleanup in ms.
+   * @returns A CleanupStats object.
+   */
+  createCleanupStats(
+    removed: number,
+    totalBefore: number,
+    totalAfter: number,
+    duration: number,
+  ): CleanupStats {
+    return {
+      removed,
+      totalBefore,
+      totalAfter,
+      duration,
+    };
+  }
+
+  /**
+   * Estimates memory usage based on entry count.
+   * This is a rough approximation for monitoring purposes.
+   *
+   * @param entryCount - Number of entries.
+   * @returns Estimated memory usage in bytes.
+   */
+  estimateMemory(entryCount: number): number {
+    // Rough estimate: each entry is approximately 200 bytes
+    // This includes the key, value reference, and metadata
+    // Actual memory usage varies based on key/value sizes
+    return entryCount * 200;
+  }
+
+  /**
+   * Resets all statistics.
+   */
+  reset(): void {
+    this.#expired = 0;
+    this.#deleted = 0;
+    this.#cleaned = 0;
+    this.#entries = 0;
+  }
+}

package/src/WeakMemoryStore.ts

@@ -0,0 +1,229 @@
+/**
+ * WeakMemoryStore implementation for safe-memory-layer.
+ *
+ * Provides an object-only storage layer using WeakMap internally.
+ * Objects disappear automatically after garbage collection.
+ * No iteration, no manual cleanup required.
+ *
+ * @module WeakMemoryStore
+ */
+
+import type { WeakMemoryStoreOptions } from "./types.js";
+
+/**
+ * A memory store that uses WeakMap for object-only storage.
+ *
+ * Keys must be objects. Values are held weakly and will be
+ * automatically garbage collected when no longer referenced elsewhere.
+ *
+ * **Limitations:**
+ * - Keys must be objects (not primitives)
+ * - No iteration support (WeakMap is not iterable)
+ * - No size property
+ * - No TTL support
+ * - No automatic cleanup needed
+ *
+ * @typeParam V - The type of values stored in the map.
+ *
+ * @example
+ * ```ts
+ * const weakStore = new WeakMemoryStore<User>();
+ *
+ * const user = { id: 1, name: "Alice" };
+ * weakStore.set(user, userData);
+ *
+ * // When 'user' is no longer referenced, the entry is automatically removed
+ * ```
+ */
+export class WeakMemoryStore<V> {
+  /** Internal WeakMap for storage. */
+  #map = new WeakMap<object, V>();
+
+  /** Store configuration options. */
+  readonly #options: WeakMemoryStoreOptions<V>;
+
+  /** Statistics tracker. */
+  #deleted = 0;
+
+  /** Timestamp when the store was created. */
+  readonly #createdAt: number;
+
+  /** Whether the store has been disposed. */
+  #disposed = false;
+
+  /**
+   * Creates a new WeakMemoryStore instance.
+   *
+   * @param options - Configuration options for the store.
+   *
+   * @example
+   * ```ts
+   * const store = new WeakMemoryStore({
+   *   onDelete: (value) => console.log("Deleted:", value)
+   * });
+   * ```
+   */
+  constructor(options: WeakMemoryStoreOptions<V> = {}) {
+    this.#options = options;
+    this.#createdAt = Date.now();
+  }
+
+  /**
+   * Stores a value with the given object key.
+   *
+   * @param key - The object key to store the value under. Must be an object.
+   * @param value - The value to store.
+   * @returns True if the value was stored.
+   *
+   * @example
+   * ```ts
+   * const obj = { id: 1 };
+   * weakStore.set(obj, { name: "Alice" });
+   * ```
+   */
+  set(key: object, value: V): boolean {
+    this.#checkDisposed();
+
+    // Type guard: ensure key is an object
+    if (typeof key !== "object" || key === null) {
+      throw new TypeError("WeakMemoryStore keys must be objects");
+    }
+
+    this.#map.set(key, value);
+    return true;
+  }
+
+  /**
+   * Retrieves a value by object key.
+   *
+   * @param key - The object key to look up.
+   * @returns The value if found, undefined otherwise.
+   *
+   * @example
+   * ```ts
+   * const user = weakStore.get(obj);
+   * ```
+   */
+  get(key: object): V | undefined {
+    this.#checkDisposed();
+
+    if (typeof key !== "object" || key === null) {
+      return undefined;
+    }
+
+    return this.#map.get(key);
+  }
+
+  /**
+   * Checks if a key exists in the store.
+   *
+   * @param key - The object key to check.
+   * @returns True if the key exists.
+   */
+  has(key: object): boolean {
+    this.#checkDisposed();
+
+    if (typeof key !== "object" || key === null) {
+      return false;
+    }
+
+    return this.#map.has(key);
+  }
+
+  /**
+   * Deletes a value by object key.
+   *
+   * @param key - The object key to delete.
+   * @returns True if the key was present, false otherwise.
+   */
+  delete(key: object): boolean {
+    this.#checkDisposed();
+
+    if (typeof key !== "object" || key === null) {
+      return false;
+    }
+
+    const value = this.#map.get(key);
+    if (value === undefined) return false;
+
+    this.#map.delete(key);
+    this.#deleted++;
+
+    // Emit delete event
+    if (this.#options.onDelete !== undefined) {
+      try {
+        this.#options.onDelete(value);
+      } catch {
+        // Isolate errors from callbacks
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Removes all entries from the store.
+   * Note: This does not prevent garbage collection of the keys.
+   */
+  clear(): void {
+    this.#checkDisposed();
+
+    // We cannot iterate over WeakMap to emit events
+    // Just clear the map
+    this.#map = new WeakMap<object, V>();
+    this.#deleted++;
+  }
+
+  /**
+   * Returns the number of deleted entries.
+   * Note: Cannot return current size (WeakMap limitation).
+   */
+  get deleted(): number {
+    return this.#deleted;
+  }
+
+  /**
+   * Returns statistics about the store.
+   * Note: entries count is not available for WeakMap.
+   *
+   * @returns A snapshot of the current statistics.
+   */
+  stats(): {
+    deleted: number;
+    uptime: number;
+  } {
+    this.#checkDisposed();
+
+    return {
+      deleted: this.#deleted,
+      uptime: Date.now() - this.#createdAt,
+    };
+  }
+
+  /**
+   * Disposes the store, releasing the WeakMap reference.
+   * After disposal, the store cannot be used.
+   */
+  dispose(): void {
+    if (this.#disposed) return;
+
+    this.#disposed = true;
+    this.#map = new WeakMap<object, V>();
+  }
+
+  /**
+   * Checks if the store has been disposed.
+   */
+  get disposed(): boolean {
+    return this.#disposed;
+  }
+
+  /**
+   * Checks if the store has been disposed and throws if so.
+   */
+  #checkDisposed(): void {
+    if (this.#disposed) {
+      throw new Error("WeakMemoryStore has been disposed");
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Safe Memory Layer - Secure, lightweight, dependency-free in-memory storage
+ *
+ * @module safe-memory-layer
+ *
+ * @example
+ * ```ts
+ * import { MemoryStore, WeakMemoryStore } from "safe-memory-layer";
+ *
+ * // Basic usage
+ * const store = new MemoryStore<string, User>();
+ * store.set("user:123", user, { ttl: 60000 });
+ * const user = store.get("user:123");
+ * ```
+ */
+
+// Main store implementation
+export { MemoryStore } from "./MemoryStore.js";
+
+// Weak reference store
+export { WeakMemoryStore } from "./WeakMemoryStore.js";
+
+// Supporting modules (for advanced usage)
+export { Scheduler } from "./Scheduler.js";
+export { Stats } from "./Stats.js";
+export { EventEmitter } from "./Events.js";
+
+// Utility functions
+export {
+  createEntry,
+  isExpired,
+  touchEntry,
+  getRemainingTTL,
+} from "./Entry.js";
+
+export { createTimer, createInterval } from "./utils/timer.js";
+export {
+  detectFeatures,
+  getFeatures,
+  createSafeFinalizationRegistry,
+} from "./utils/featureDetection.js";
+
+// Type exports
+export type {
+  MaxEntriesStrategy,
+  SetOptions,
+  MemoryStoreOptions,
+  CleanupStats,
+  StoreStats,
+  InternalEntry,
+  InternalStoreOptions,
+  WeakMemoryStoreOptions,
+  FeatureSupport,
+} from "./types.js";
+
+export type { CleanupFn } from "./Scheduler.js";
+export type { TimerHandle } from "./utils/timer.js";

package/src/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Core type definitions for safe-memory-layer.
+ *
+ * @module types
+ */
+
+/** Strategy to use when the store reaches its maximum entry limit. */
+export type MaxEntriesStrategy = "reject" | "FIFO" | "LRU";
+
+/** Options for setting an individual entry. */
+export interface SetOptions {
+  /** Time-to-live in milliseconds. After this duration, the entry expires. */
+  ttl?: number;
+}
+
+/** Configuration options for creating a MemoryStore. */
+export interface MemoryStoreOptions<K, V> {
+  /** Default TTL in milliseconds for all entries (default: no expiration). */
+  defaultTTL?: number;
+  /** Interval in milliseconds between automatic cleanup runs (default: 10000). */
+  cleanupInterval?: number;
+  /** Whether to automatically run cleanup on an interval (default: true). */
+  autoCleanup?: boolean;
+  /** Whether to automatically dispose the store after being empty for a configurable time (default: false). */
+  autoDispose?: boolean;
+  /** Time in milliseconds to wait after empty before auto-disposing (default: 60000). */
+  autoDisposeDelay?: number;
+  /** Maximum number of entries allowed in the store (default: no limit). */
+  maxEntries?: number;
+  /** Strategy when max entries is reached (default: "reject"). */
+  maxEntriesStrategy?: MaxEntriesStrategy;
+  /** Callback invoked when an entry expires. */
+  onExpire?: (key: K, value: V) => void;
+  /** Callback invoked when an entry is deleted. */
+  onDelete?: (key: K, value: V) => void;
+  /** Callback invoked after a cleanup cycle completes. */
+  onCleanup?: (stats: CleanupStats) => void;
+}
+
+/** Statistics about a cleanup cycle. */
+export interface CleanupStats {
+  /** Number of entries removed during cleanup. */
+  removed: number;
+  /** Total number of entries before cleanup. */
+  totalBefore: number;
+  /** Total number of entries after cleanup. */
+  totalAfter: number;
+  /** Duration of the cleanup cycle in milliseconds. */
+  duration: number;
+}
+
+/** Statistics about the store. */
+export interface StoreStats {
+  /** Current number of entries in the store. */
+  entries: number;
+  /** Total number of entries that have expired. */
+  expired: number;
+  /** Total number of entries that have been deleted. */
+  deleted: number;
+  /** Total number of cleanup cycles completed. */
+  cleaned: number;
+  /** Uptime of the store in milliseconds. */
+  uptime: number;
+  /** Estimated memory usage in bytes (approximate). */
+  memoryEstimate: number;
+}
+
+/** Internal entry stored in the map. */
+export interface InternalEntry<K, V> {
+  /** The stored value. */
+  value: V;
+  /** The key (stored for cleanup callbacks). */
+  key: K;
+  /** Expiration timestamp (ms since epoch), or undefined if no expiration. */
+  expiresAt: number | undefined;
+  /** Timestamp of last access (for LRU). */
+  lastAccessed: number;
+  /** Timestamp of creation. */
+  createdAt: number;
+}
+
+/** Internal options for the MemoryStore constructor. */
+export interface InternalStoreOptions<K, V> {
+  defaultTTL: number | undefined;
+  cleanupInterval: number;
+  autoCleanup: boolean;
+  autoDispose: boolean;
+  autoDisposeDelay: number;
+  maxEntries: number | undefined;
+  maxEntriesStrategy: MaxEntriesStrategy;
+  onExpire: ((key: K, value: V) => void) | undefined;
+  onDelete: ((key: K, value: V) => void) | undefined;
+  onCleanup: ((stats: CleanupStats) => void) | undefined;
+}
+
+/** Options for WeakMemoryStore. */
+export interface WeakMemoryStoreOptions<V> {
+  /** Callback invoked when an entry is deleted. */
+  onDelete?: (value: V) => void;
+}
+
+/** Feature detection result for FinalizationRegistry. */
+export interface FeatureSupport {
+  /** Whether FinalizationRegistry is available. */
+  finalizationRegistry: boolean;
+}

package/src/utils/featureDetection.ts

@@ -0,0 +1,52 @@
+/**
+ * Feature detection utilities for safe-memory-layer.
+ *
+ * Detects available platform features and provides graceful fallbacks.
+ *
+ * @module utils/featureDetection
+ */
+
+import type { FeatureSupport } from "../types.js";
+
+/**
+ * Detects which platform features are available.
+ * This is called once at module load time and cached.
+ */
+export function detectFeatures(): FeatureSupport {
+  return {
+    finalizationRegistry:
+      typeof globalThis.FinalizationRegistry !== "undefined",
+  };
+}
+
+/** Cached feature support flags. */
+let cachedFeatures: FeatureSupport | undefined;
+
+/**
+ * Returns the cached feature support flags, detecting them on first call.
+ */
+export function getFeatures(): FeatureSupport {
+  if (cachedFeatures === undefined) {
+    cachedFeatures = detectFeatures();
+  }
+  return cachedFeatures;
+}
+
+/**
+ * Creates a FinalizationRegistry if available, otherwise returns null.
+ * Never throws if FinalizationRegistry is unavailable.
+ */
+export function createSafeFinalizationRegistry<T>(
+  cleanup: (heldValue: T) => void,
+): FinalizationRegistry<T> | null {
+  const features = getFeatures();
+  if (features.finalizationRegistry) {
+    try {
+      return new FinalizationRegistry(cleanup);
+    } catch {
+      // Graceful fallback if construction fails
+      return null;
+    }
+  }
+  return null;
+}

package/src/utils/timer.ts

@@ -0,0 +1,93 @@
+/**
+ * Safe timer utilities for safe-memory-layer.
+ *
+ * Provides platform-agnostic timer creation and cleanup.
+ * Uses only Web-compatible APIs (setTimeout/clearTimeout).
+ *
+ * @module utils/timer
+ */
+
+/** Represents a timer handle that can be cancelled. */
+export interface TimerHandle {
+  /** Cancels the timer. Safe to call multiple times. */
+  cancel: () => void;
+  /** Whether the timer has been cancelled. */
+  readonly cancelled: boolean;
+}
+
+/**
+ * Creates a safe timer that can be cancelled.
+ * Uses setTimeout internally for maximum compatibility.
+ *
+ * @param fn - The function to execute after the delay.
+ * @param delay - The delay in milliseconds.
+ * @returns A TimerHandle that can be used to cancel the timer.
+ */
+export function createTimer(fn: () => void, delay: number): TimerHandle {
+  let cancelled = false;
+  let timerId: ReturnType<typeof setTimeout> | undefined;
+
+  const wrappedFn = (): void => {
+    if (cancelled) return;
+    timerId = undefined;
+    try {
+      fn();
+    } catch {
+      // Isolate errors from timer callbacks to prevent crashes
+    }
+  };
+
+  timerId = setTimeout(wrappedFn, delay);
+
+  return {
+    cancel: (): void => {
+      cancelled = true;
+      if (timerId !== undefined) {
+        clearTimeout(timerId);
+        timerId = undefined;
+      }
+    },
+    get cancelled(): boolean {
+      return cancelled;
+    },
+  };
+}
+
+/**
+ * Creates an interval timer that runs a function repeatedly.
+ *
+ * @param fn - The function to execute on each interval.
+ * @param interval - The interval in milliseconds.
+ * @returns A TimerHandle that can be used to cancel the interval.
+ */
+export function createInterval(
+  fn: () => void,
+  interval: number,
+): TimerHandle {
+  let cancelled = false;
+  let timerId: ReturnType<typeof setInterval> | undefined;
+
+  const wrappedFn = (): void => {
+    if (cancelled) return;
+    try {
+      fn();
+    } catch {
+      // Isolate errors from interval callbacks
+    }
+  };
+
+  timerId = setInterval(wrappedFn, interval);
+
+  return {
+    cancel: (): void => {
+      cancelled = true;
+      if (timerId !== undefined) {
+        clearInterval(timerId);
+        timerId = undefined;
+      }
+    },
+    get cancelled(): boolean {
+      return cancelled;
+    },
+  };
+}