@neezco/cache 0.4.1 → 0.6.0

package/docs/api-reference.md

@@ -89,6 +89,9 @@ interface EntryMetadata<T = unknown> {
   // The cached value.
   data: T;
 
+  // Absolute timestamp when the entry was created (in milliseconds).
+  createdAt: number;
+
   // Absolute timestamp when this entry becomes fully expired (in milliseconds).
   expirationTime: number;
 
@@ -123,6 +126,7 @@ const user = cache.get("user:123");
 const entry = cache.get("user:123", { includeMetadata: true });
 if (entry) {
   console.log(entry.data);
+  console.log(entry.createdAt);
   console.log(entry.status);
   console.log(entry.expirationTime);
   console.log(entry.staleWindowExpiration);

package/package.json

@@ -67,10 +67,6 @@
     "@commitlint/cli": "20.3.0",
     "@commitlint/config-conventional": "20.3.0",
     "@eslint/js": "9.39.2",
-    "@semantic-release/changelog": "6.0.3",
-    "@semantic-release/git": "10.0.1",
-    "@semantic-release/github": "12.0.6",
-    "@semantic-release/npm": "13.1.4",
     "@types/bun": "latest",
     "@types/node": "25.0.6",
     "@vitest/coverage-v8": "4.0.17",
@@ -97,10 +93,20 @@
   },
   "pnpm": {
     "overrides": {
-      "minimatch": "^10.2.1",
+      "handlebars": "^4.7.9",
+      "lodash-es": "^4.18.0",
+      "minimatch": "^10.2.3",
+      "rollup": "^4.59.0",
+      "vite": "^7.3.2",
+      "flatted": "^3.4.2",
+      "defu": "^6.1.5",
+      "picomatch@<2.3.2": "2.3.2",
+      "picomatch@>=4.0.0 <4.0.4": "4.0.4",
+      "undici@<6.24.0": "6.24.0",
+      "undici@>=7.0.0 <7.24.0": "7.24.0",
       "ajv@<6.14.0": "6.14.0",
       "ajv@>=7.0.0 <8.18.0": "8.18.0"
     }
   },
-  "version": "0.4.1"
+  "version": "0.6.0"
 }

package/CHANGELOG.md

@@ -1,56 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-## [0.4.1](https://github.com/neezco/cache/compare/v0.4.0...v0.4.1) (2026-02-21)
-
-
-### Bug Fixes
-
-* adjust semantic-release title and section configuration for proper changelog grouping ([919729a](https://github.com/neezco/cache/commit/919729a9d4d826e5ea78e7147914fc52f8d12149))
-
-## 0.4.0 (2026-02-14)
-
-* chore: implement startSweep function to manage cache sweep process ([78ded7a](https://github.com/neezco/cache/commit/78ded7a))
-* chore: install semantic-release plugins and add unified release script ([5b7a8b3](https://github.com/neezco/cache/commit/5b7a8b3))
-* test: add comprehensive tests for LocalTtlCache purge strategies and basic operations ([a410f2d](https://github.com/neezco/cache/commit/a410f2d))
-* test: ensure tag invalidation does not affect entries created after the tag ([9282397](https://github.com/neezco/cache/commit/9282397))
-* fix: enforce stale window upper bound when applying tag-based stale invalidation ([593c1d4](https://github.com/neezco/cache/commit/593c1d4)), closes [#19](https://github.com/neezco/cache/issues/19)
-* feat: enhance cache purging strategy with configurable thresholds ([ee762c1](https://github.com/neezco/cache/commit/ee762c1))
-* feat: refactor purge configuration logic and enhance validation for thresholds ([350b9de](https://github.com/neezco/cache/commit/350b9de)), closes [#18](https://github.com/neezco/cache/issues/18)
-* style: add conventional-changelog-conventionalcommits package for improved changelog generation ([5435048](https://github.com/neezco/cache/commit/5435048))
-* style: simplify commit-analyzer plugin configuration ([ecff6a0](https://github.com/neezco/cache/commit/ecff6a0))
-* style: update release notes generator configuration for improved changelog formatting ([1ac4776](https://github.com/neezco/cache/commit/1ac4776))
-
-# [0.3.0](https://github.com/neezco/cache/compare/v0.2.1...v0.3.0) (2026-02-11)
-
-
-### Features
-
-* enhance cache retrieval with metadata support in `get()` method ([eb198d6](https://github.com/neezco/cache/commit/eb198d66c9e1abda86c448fb81a35f14e376a79c)), closes [#17](https://github.com/neezco/cache/issues/17)
-
-## [0.2.1](https://github.com/neezco/cache/compare/v0.2.0...v0.2.1) (2026-02-11)
-
-
-### Performance Improvements
-
-* optimize cache entry validation by introducing pre-computed status handling ([bafb6a0](https://github.com/neezco/cache/commit/bafb6a024b0082a1b81f2d0e959c883df4136976))
-
-# [0.2.0](https://github.com/neezco/cache/compare/v0.1.1...v0.2.0) (2026-02-09)
-
-
-### Bug Fixes
-
-* add regex for todo-tree to enhance tag recognition ([e0c3292](https://github.com/neezco/cache/commit/e0c3292cd83f5e6d1c5cd9b9c2e199b4a7c9eda0))
-
-
-### Features
-
-* add maxMemorySize configuration and update cache behavior for size limits ([fb3f173](https://github.com/neezco/cache/commit/fb3f173b891fc4f345596904ad82b606e5cbc00c))
-
-## [0.1.1](https://github.com/neezco/cache/compare/v0.1.0...v0.1.1) (2026-02-09)
-
-
-### Bug Fixes
-
-* update `invalidateTag` method to use `InvalidateTagOptions` for extensibility ([8184098](https://github.com/neezco/cache/commit/8184098a3b7eed24dc8ebf211b4929f4b383b4a9))

package/dist/browser/index.d.ts

@@ -1,338 +0,0 @@
-//#region src/cache/delete.d.ts
-declare const enum DELETE_REASON {
-  MANUAL = "manual",
-  EXPIRED = "expired",
-  STALE = "stale",
-}
-//#endregion
-//#region src/types.d.ts
-/**
-* Base configuration shared between CacheOptions and CacheState.
-*/
-interface CacheConfigBase {
-  /**
-  * Callback invoked when an entry expires naturally (not manually deleted).
-  * @param key - The expired key.
-  * @param value - The value associated with the expired key.
-  * @param reason - The reason for expiration: 'expired' (fully expired) or 'stale' (stale window expired).
-  */
-  onExpire?: (key: string, value: unknown, reason: Exclude<DELETE_REASON, DELETE_REASON.MANUAL>) => void;
-  /**
-  * Callback invoked when a key is deleted, either manually or due to expiration.
-  * @param key - The deleted key.
-  * @param value - The value of the deleted key.
-  * @param reason - The reason for deletion ('manual', 'expired', or 'stale').
-  */
-  onDelete?: (key: string, value: unknown, reason: DELETE_REASON) => void;
-  /**
-  * Default TTL (Time-To-Live) in milliseconds for entries without explicit TTL.
-  * @default 1_800_000 (30 minutes)
-  */
-  defaultTtl: number;
-  /**
-  * Default stale window in milliseconds for entries without explicit `staleWindow`.
-  *
-  * Defines how long an entry can be served as stale after expiration.
-  * The window is relative to each entry's expiration moment, whether from
-  * explicit `ttl` or the cache's `defaultTtl`.
-  *
-  * @default 0 (no stale window)
-  */
-  defaultStaleWindow: number;
-  /**
-  * Maximum number of entries the cache can hold.
-  * Beyond this limit, new entries are ignored.
-  * @default Infinite (unlimited)
-  */
-  maxSize: number;
-  /**
-  * Maximum memory size in MB the cache can use.
-  * Beyond this limit, new entries are ignored.
-  * @default Infinite (unlimited)
-  */
-  maxMemorySize: number;
-  /**
-  * Controls stale entry purging behavior on `get()` operations.
-  *
-  * Possible values:
-  * - `true` → purge stale entries immediately after read.
-  * - `false` → retain stale entries after read.
-  * - `number (0-1)` → purge when `resourceUsage ≥ threshold` (uses `purgeResourceMetric`).
-  *
-  * Numeric threshold validation:
-  * - Must be 0 < value ≤ 1 (boolean fallback if invalid range)
-  * - Requires purgeResourceMetric to support thresholds (not 'fixed')
-  * - Requires matching configuration limits for the metric:
-  *   * 'size' metric requires maxSize
-  *   * 'memory' metric requires maxMemorySize
-  *   * 'higher' metric requires both maxSize and maxMemorySize
-  * - Invalid numeric values fallback to default: 0.80 (with limits) or false (without)
-  *
-  * Environment notes:
-  * - Backend: `"memory"` and `"higher"` metrics available; frontend: only `"size"`.
-  * - Can be overridden per-read via `get(key, { purgeStale })`.
-  *
-  * Defaults:
-  * - With matching limits → `0.80` (80% resource usage).
-  * - Without matching limits → `false`.
-  */
-  purgeStaleOnGet: PurgeMode;
-  /**
-  * Controls stale entry purging behavior during sweep operations.
-  *
-  * Possible values:
-  * - `true` → purge stale entries during sweeps.
-  * - `false` → retain stale entries during sweeps.
-  * - `number (0-1)` → purge when `resourceUsage ≥ threshold` (uses `purgeResourceMetric`).
-  *
-  * Numeric threshold validation:
-  * - Must be 0 < value ≤ 1 (boolean fallback if invalid range)
-  * - Requires purgeResourceMetric to support thresholds (not 'fixed')
-  * - Requires matching configuration limits for the metric:
-  *   * 'size' metric requires maxSize
-  *   * 'memory' metric requires maxMemorySize
-  *   * 'higher' metric requires both maxSize and maxMemorySize
-  * - Invalid numeric values fallback to default: 0.5 (with limits) or true (without)
-  *
-  * Prevents stale entry accumulation when enabled. Without limits, defaults to `true`
-  * to prevent unbounded growth.
-  *
-  * Environment notes:
-  * - Backend: `"memory"` and `"higher"` metrics available; frontend: only `"size"`.
-  *
-  * Defaults:
-  * - With matching limits → `0.5` (50% resource usage).
-  * - Without matching limits → `true` (prevent unbounded accumulation).
-  */
-  purgeStaleOnSweep: PurgeMode;
-  /**
-  * Metric used to evaluate resource usage for threshold-based stale purging.
-  *
-  * Applies when `purgeStaleOnGet` or `purgeStaleOnSweep` are numeric (0-1).
-  *
-  * Metric options:
-  * - `"size"` → normalized entry count (`current / maxSize`).
-  * - `"memory"` → normalized RAM (`currentMB / maxMemorySize`).
-  * - `"higher"` → max of both metrics (recommended for dual limits).
-  * - `"fixed"` → disable threshold purging; only bool values apply.
-  *
-  * Environment support:
-  * - Backend: all metrics available.
-  * - Frontend: only `"size"`; numeric thresholds fallback to `"fixed"`.
-  *
-  * Auto-selection (if not specified):
-  * - Backend: `"higher"` (both limits) → `"memory"` → `"size"` → `"fixed"`.
-  * - Frontend: `"size"` (if valid) → `"fixed"`.
-  *
-  * @default Depends on environment and valid limits.
-  */
-  purgeResourceMetric?: "memory" | "size" | "higher" | "fixed";
-  /**
-  * Auto-start sweep process on cache initialization.
-  *
-  * @internal
-  * @default true
-  */
-  _autoStartSweep: boolean;
-  /**
-  * @internal Maximum allowed ratio of expired entries before aggressive sweep.
-  */
-  _maxAllowExpiredRatio: number;
-}
-/**
-* Purge mode: boolean for immediate/skip, or 0-1 for threshold-based purging.
-*/
-type PurgeMode = boolean | number;
-/**
-* Public cache configuration (all fields optional).
-*/
-type CacheOptions = Partial<CacheConfigBase>;
-/**
-* Options for tag invalidation. Extensible for forward-compatibility.
-*/
-interface InvalidateTagOptions {
-  /**
-  * If true, mark entries as stale instead of fully expired.
-  * They remain accessible via stale window if configured.
-  */
-  asStale?: boolean;
-  [key: string]: unknown;
-}
-/**
-* Entry status: fresh, stale, or expired.
-*/
-declare enum ENTRY_STATUS {
-  /** Valid and within TTL. */
-  FRESH = "fresh",
-  /** Expired but within stale window; still served. */
-  STALE = "stale",
-  /** Beyond stale window; not served. */
-  EXPIRED = "expired",
-}
-/**
-* Metadata returned from `get()` with `includeMetadata: true`.
-* Provides complete entry state including timing, status, and tags.
-*/
-interface EntryMetadata<T = unknown> {
-  /** The cached value. */
-  data: T;
-  /** Absolute timestamp (ms) when entry expires. */
-  expirationTime: number;
-  /** Absolute timestamp (ms) when stale window ends. */
-  staleWindowExpiration: number;
-  /** Current entry status. */
-  status: ENTRY_STATUS;
-  /** Associated tags for group invalidation, or null. */
-  tags: string[] | null;
-}
-/**
-* Options for `get()` without metadata (default).
-* Returns only the cached value.
-*/
-interface GetOptionsWithoutMetadata {
-  /**
-  * If false (or omitted), returns value only without metadata.
-  * @default false
-  */
-  includeMetadata?: false;
-  /**
-  * Controls stale entry purging on this read.
-  *
-  * - `true` → purge immediately after return.
-  * - `false` → keep stale entries.
-  * - `number (0-1)` → purge at resource usage threshold.
-  *
-  * Overrides global `purgeStaleOnGet` setting.
-  */
-  purgeStale?: PurgeMode;
-}
-/**
-* Options for `get()` with metadata.
-* Returns value and complete entry state.
-*/
-interface GetOptionsWithMetadata {
-  /**
-  * If true, returns `EntryMetadata<T>` object with value, timing, and tags.
-  */
-  includeMetadata: true;
-  /**
-  * Controls stale entry purging on this read.
-  *
-  * - `true` → purge immediately after return.
-  * - `false` → keep stale entries.
-  * - `number (0-1)` → purge at resource usage threshold.
-  *
-  * Overrides global `purgeStaleOnGet` setting.
-  */
-  purgeStale?: PurgeMode;
-}
-/**
-* Options for `set()` method.
-* Controls TTL, stale window, and tagging per entry.
-*/
-interface SetOptions {
-  /**
-  * Time-To-Live in milliseconds.
-  * Determines fresh period before expiration.
-  *
-  * Special values:
-  * - `0` | `Infinity` → entry never expires
-  *
-  * Falls back to cache's `defaultTtl` if omitted.
-  */
-  ttl?: number;
-  /**
-  * Stale window duration in milliseconds.
-  *
-  * Determines how long entry serves stale after expiration.
-  * Falls back to cache's `defaultStaleWindow` if omitted.
-  */
-  staleWindow?: number;
-  /**
-  * One or more tags for group-based invalidation.
-  *
-  * Tags enable batch invalidation via `invalidateTag()`.
-  * Invalidating ANY tag on an entry invalidates the whole entry.
-  *
-  * Falls back to cache's default if omitted.
-  */
-  tags?: string | string[];
-}
-/**
-* TTL cache public interface.
-* Implemented by `LocalTtlCache` class.
-*/
-interface LocalTtlCacheInterface {
-  /**
-  * Current number of entries (may include expired entries pending cleanup).
-  */
-  readonly size: number;
-  /**
-  * Retrieves value from cache.
-  * Returns fresh, stale, or undefined (expired or not found).
-  *
-  * @overload `get<T>(key)` → `T | undefined` (no metadata)
-  * @overload `get<T>(key, { includeMetadata: true })` → `EntryMetadata<T> | undefined` (with metadata)
-  */
-  get<T = unknown>(key: string): T | undefined;
-  get<T = unknown>(key: string, options: GetOptionsWithMetadata): EntryMetadata<T> | undefined;
-  get<T = unknown>(key: string, options: GetOptionsWithoutMetadata): T | undefined;
-  /**
-  * Sets or replaces a cache entry.
-  * @returns true if set/updated, false if rejected (limits/invalid).
-  */
-  set(key: string, value: unknown, options?: SetOptions): boolean;
-  /**
-  * Deletes a specific key from cache.
-  * @returns true if deleted, false if not found.
-  */
-  delete(key: string): boolean;
-  /**
-  * Checks if key exists (fresh or stale).
-  * @returns true if valid, false if not found or fully expired.
-  */
-  has(key: string): boolean;
-  /**
-  * Removes all entries from cache.
-  * Does NOT trigger `onDelete` callbacks (optimization).
-  */
-  clear(): void;
-  /**
-  * Marks entries with given tags as expired (or stale).
-  * Invalidating ANY tag on an entry invalidates it.
-  */
-  invalidateTag(tags: string | string[], options?: InvalidateTagOptions): void;
-}
-//#endregion
-//#region src/index.d.ts
-/**
-* A TTL (Time-To-Live) cache implementation with support for expiration,
-* stale windows, tag-based invalidation, and smart automatic sweeping.
-*
-* Provides O(1) constant-time operations for all core methods with support for:
-* - Expiration and stale windows
-* - Tag-based invalidation
-* - Automatic sweeping
-*/
-declare class LocalTtlCache implements LocalTtlCacheInterface {
-  private state;
-  /**
-  * Creates a new cache instance.
-  *
-  * @param options - Configuration options for the cache (defaultTtl, defaultStaleWindow, maxSize, etc.)
-  *
-  */
-  constructor(options?: CacheOptions);
-  get size(): number;
-  get<T = unknown>(key: string): T | undefined;
-  get<T = unknown>(key: string, options: GetOptionsWithMetadata): EntryMetadata<T>;
-  get<T = unknown>(key: string, options: GetOptionsWithoutMetadata): T | undefined;
-  set(key: string, value: unknown, options?: SetOptions): boolean;
-  delete(key: string): boolean;
-  has(key: string): boolean;
-  clear(): void;
-  invalidateTag(tags: string | string[], options?: InvalidateTagOptions): void;
-}
-//#endregion
-export { type CacheOptions, ENTRY_STATUS, type EntryMetadata, type GetOptionsWithMetadata, type GetOptionsWithoutMetadata, type InvalidateTagOptions, LocalTtlCache, type LocalTtlCacheInterface, type PurgeMode, type SetOptions };
-//# sourceMappingURL=index.d.ts.map