@neezco/cache 0.1.1 → 0.2.1

package/dist/node/index.d.cts

@@ -45,9 +45,15 @@ interface CacheConfigBase {
   /**
   * Maximum number of entries the cache can hold.
   * Beyond this limit, new entries are ignored.
-  * @default null (unlimited)
+  * @default Infinite (unlimited)
   */
-  maxSize?: number;
+  maxSize: number;
+  /**
+  * Maximum memory size in MB the cache can use.
+  * Beyond this limit, new entries are ignored.
+  * @default Infinite (unlimited)
+  */
+  maxMemorySize: number;
   /**
   * Controls how stale entries are handled when read from the cache.
   *
@@ -177,14 +183,19 @@ declare class LocalTtlCache {
   * @param options.ttl - Time-To-Live in milliseconds. Defaults to `defaultTtl`
   * @param options.staleWindow - How long to serve stale data after expiration (milliseconds)
   * @param options.tags - One or more tags for group invalidation
+  * @returns True if the entry was set or updated, false if rejected due to limits or invalid input
   *
   * @example
   * ```typescript
-  * cache.set("user:123", { name: "Alice" }, {
+  * const success = cache.set("user:123", { name: "Alice" }, {
   *   ttl: 5 * 60 * 1000,
   *   staleWindow: 1 * 60 * 1000,
   *   tags: "user:123",
   * });
+  *
+  * if (!success) {
+  *   console.log("Entry was rejected due to size or memory limits");
+  * }
   * ```
   *
   * @edge-cases
@@ -192,12 +203,16 @@ declare class LocalTtlCache {
   * - If `ttl` is 0 or Infinite, the entry never expires
   * - If `staleWindow` is larger than `ttl`, the entry can be served as stale longer than it was fresh
   * - Tags are optional; only necessary for group invalidation via `invalidateTag()`
+  * - Returns `false` if value is `undefined` (existing value remains untouched)
+  * - Returns `false` if new key would exceed [`maxSize`](./docs/configuration.md#maxsize-number) limit
+  * - Returns `false` if new key would exceed [`maxMemorySize`](./docs/configuration.md#maxmemorysize-number) limit
+  * - Updating existing keys always succeeds, even at limit
   */
   set(key: string, value: unknown, options?: {
     ttl?: number;
     staleWindow?: number;
     tags?: string | string[];
-  }): void;
+  }): boolean;
   /**
   * Deletes a specific key from the cache.
   *

package/dist/node/index.d.mts

@@ -45,9 +45,15 @@ interface CacheConfigBase {
   /**
   * Maximum number of entries the cache can hold.
   * Beyond this limit, new entries are ignored.
-  * @default null (unlimited)
+  * @default Infinite (unlimited)
   */
-  maxSize?: number;
+  maxSize: number;
+  /**
+  * Maximum memory size in MB the cache can use.
+  * Beyond this limit, new entries are ignored.
+  * @default Infinite (unlimited)
+  */
+  maxMemorySize: number;
   /**
   * Controls how stale entries are handled when read from the cache.
   *
@@ -177,14 +183,19 @@ declare class LocalTtlCache {
   * @param options.ttl - Time-To-Live in milliseconds. Defaults to `defaultTtl`
   * @param options.staleWindow - How long to serve stale data after expiration (milliseconds)
   * @param options.tags - One or more tags for group invalidation
+  * @returns True if the entry was set or updated, false if rejected due to limits or invalid input
   *
   * @example
   * ```typescript
-  * cache.set("user:123", { name: "Alice" }, {
+  * const success = cache.set("user:123", { name: "Alice" }, {
   *   ttl: 5 * 60 * 1000,
   *   staleWindow: 1 * 60 * 1000,
   *   tags: "user:123",
   * });
+  *
+  * if (!success) {
+  *   console.log("Entry was rejected due to size or memory limits");
+  * }
   * ```
   *
   * @edge-cases
@@ -192,12 +203,16 @@ declare class LocalTtlCache {
   * - If `ttl` is 0 or Infinite, the entry never expires
   * - If `staleWindow` is larger than `ttl`, the entry can be served as stale longer than it was fresh
   * - Tags are optional; only necessary for group invalidation via `invalidateTag()`
+  * - Returns `false` if value is `undefined` (existing value remains untouched)
+  * - Returns `false` if new key would exceed [`maxSize`](./docs/configuration.md#maxsize-number) limit
+  * - Returns `false` if new key would exceed [`maxMemorySize`](./docs/configuration.md#maxmemorysize-number) limit
+  * - Updating existing keys always succeeds, even at limit
   */
   set(key: string, value: unknown, options?: {
     ttl?: number;
     staleWindow?: number;
     tags?: string | string[];
-  }): void;
+  }): boolean;
   /**
   * Deletes a specific key from the cache.
   *

package/dist/node/index.mjs

@@ -38,10 +38,16 @@ const DEFAULT_TTL = 30 * ONE_MINUTE;
 const DEFAULT_STALE_WINDOW = 0;
 /**
 * Maximum number of entries the cache can hold.
-* Beyond this limit, less-used entries are evicted.
+* Beyond this limit, new entries are ignored.
 */
 const DEFAULT_MAX_SIZE = Infinity;
 /**
+* Default maximum memory size in MB the cache can use.
+* Beyond this limit, new entries are ignored.
+* @default Infinite (unlimited)
+*/
+const DEFAULT_MAX_MEMORY_SIZE = Infinity;
+/**
 * ===================================================================
 * Sweep & Cleanup Operations
 * Parameters controlling how and when expired entries are removed.
@@ -560,11 +566,18 @@ function computeEntryStatus(state, entry, now) {
 * - It has not expired according to its own timestamps, and
 * - No associated tag imposes a stricter stale or expired rule.
 *
+* `entry` can be either a {@link CacheEntry} or a pre-computed {@link ENTRY_STATUS}.
+* Passing a pre-computed status avoids recalculating the entry status.
+*
 * @param state - The cache state containing tag metadata.
-* @param entry - The cache entry being evaluated.
+* @param entry - The cache entry or pre-computed status being evaluated.
+* @param now - The current timestamp.
 * @returns True if the entry is fresh.
 */
-const isFresh = (state, entry, now) => computeEntryStatus(state, entry, now) === ENTRY_STATUS.FRESH;
+const isFresh = (state, entry, now) => {
+	if (typeof entry === "string") return entry === ENTRY_STATUS.FRESH;
+	return computeEntryStatus(state, entry, now) === ENTRY_STATUS.FRESH;
+};
 /**
 * Determines whether a cache entry is stale.
 *
@@ -572,11 +585,18 @@ const isFresh = (state, entry, now) => computeEntryStatus(state, entry, now) ===
 * - It has passed its TTL but is still within its stale window, or
 * - A tag imposes a stale rule that applies to this entry.
 *
+* `entry` can be either a {@link CacheEntry} or a pre-computed {@link ENTRY_STATUS}.
+* Passing a pre-computed status avoids recalculating the entry status.
+*
 * @param state - The cache state containing tag metadata.
-* @param entry - The cache entry being evaluated.
+* @param entry - The cache entry or pre-computed status being evaluated.
+* @param now - The current timestamp.
 * @returns True if the entry is stale.
 */
-const isStale = (state, entry, now) => computeEntryStatus(state, entry, now) === ENTRY_STATUS.STALE;
+const isStale = (state, entry, now) => {
+	if (typeof entry === "string") return entry === ENTRY_STATUS.STALE;
+	return computeEntryStatus(state, entry, now) === ENTRY_STATUS.STALE;
+};
 /**
 * Determines whether a cache entry is expired.
 *
@@ -584,11 +604,18 @@ const isStale = (state, entry, now) => computeEntryStatus(state, entry, now) ===
 * - It has exceeded both its TTL and stale TTL, or
 * - A tag imposes an expiration rule that applies to this entry.
 *
+* `entry` can be either a {@link CacheEntry} or a pre-computed {@link ENTRY_STATUS}.
+* Passing a pre-computed status avoids recalculating the entry status.
+*
 * @param state - The cache state containing tag metadata.
-* @param entry - The cache entry being evaluated.
+* @param entry - The cache entry or pre-computed status being evaluated.
+* @param now - The current timestamp.
 * @returns True if the entry is expired.
 */
-const isExpired = (state, entry, now) => computeEntryStatus(state, entry, now) === ENTRY_STATUS.EXPIRED;
+const isExpired = (state, entry, now) => {
+	if (typeof entry === "string") return entry === ENTRY_STATUS.EXPIRED;
+	return computeEntryStatus(state, entry, now) === ENTRY_STATUS.EXPIRED;
+};
 
 //#endregion
 //#region src/sweep/sweep-once.ts
@@ -613,10 +640,11 @@ function _sweepOnce(state, _maxKeysPerBatch = MAX_KEYS_PER_BATCH) {
 		processed += 1;
 		const [key, entry] = next.value;
 		const now = Date.now();
-		if (isExpired(state, entry, now)) {
+		const status = computeEntryStatus(state, entry, now);
+		if (isExpired(state, status, now)) {
 			deleteKey(state, key, DELETE_REASON.EXPIRED);
 			expiredCount += 1;
-		} else if (isStale(state, entry, now)) {
+		} else if (isStale(state, status, now)) {
 			staleCount += 1;
 			if (state.purgeStaleOnSweep) deleteKey(state, key, DELETE_REASON.STALE);
 		}
@@ -776,7 +804,7 @@ let _initSweepScheduled = false;
 * @returns The initial cache state.
 */
 const createCache = (options = {}) => {
-	const { onExpire, onDelete, defaultTtl = DEFAULT_TTL, maxSize = DEFAULT_MAX_SIZE, _maxAllowExpiredRatio = DEFAULT_MAX_EXPIRED_RATIO, defaultStaleWindow = DEFAULT_STALE_WINDOW, purgeStaleOnGet = false, purgeStaleOnSweep = false, _autoStartSweep = true } = options;
+	const { onExpire, onDelete, defaultTtl = DEFAULT_TTL, maxSize = DEFAULT_MAX_SIZE, maxMemorySize = DEFAULT_MAX_MEMORY_SIZE, _maxAllowExpiredRatio = DEFAULT_MAX_EXPIRED_RATIO, defaultStaleWindow = DEFAULT_STALE_WINDOW, purgeStaleOnGet = false, purgeStaleOnSweep = false, _autoStartSweep = true } = options;
 	_instanceCount++;
 	if (_instanceCount > INSTANCE_WARNING_THRESHOLD) console.warn(`Too many instances detected (${_instanceCount}). This may indicate a configuration issue; consider minimizing instance creation or grouping keys by expected expiration ranges. See the documentation: https://github.com/neezco/cache/docs/getting-started.md`);
 	const state = {
@@ -788,6 +816,7 @@ const createCache = (options = {}) => {
 		onExpire,
 		onDelete,
 		maxSize,
+		maxMemorySize,
 		defaultTtl,
 		defaultStaleWindow,
 		purgeStaleOnGet,
@@ -821,8 +850,9 @@ const createCache = (options = {}) => {
 const get = (state, key, now = Date.now()) => {
 	const entry = state.store.get(key);
 	if (!entry) return void 0;
-	if (isFresh(state, entry, now)) return entry[1];
-	if (isStale(state, entry, now)) {
+	const status = computeEntryStatus(state, entry, now);
+	if (isFresh(state, status, now)) return entry[1];
+	if (isStale(state, status, now)) {
 		if (state.purgeStaleOnGet) deleteKey(state, key, DELETE_REASON.STALE);
 		return entry[1];
 	}
@@ -888,16 +918,23 @@ function invalidateTag(state, tags, options = {}, _now = Date.now()) {
 * @param state - The cache state.
 * @param input - Cache entry definition (key, value, ttl, staleWindow, tags).
 * @param now - Optional timestamp override used as the base time (defaults to Date.now()).
+* @returns True if the entry was created or updated, false if rejected due to limits or invalid input.
 *
 * @remarks
 * - `ttl` defines when the entry becomes expired.
 * - `staleWindow` defines how long the entry may still be served as stale
 *   after the expiration moment (`now + ttl`).
+* - Returns false if value is `undefined` (entry ignored, existing value untouched).
+* - Returns false if new entry would exceed `maxSize` limit (existing keys always allowed).
+* - Returns false if new entry would exceed `maxMemorySize` limit (existing keys always allowed).
+* - Returns true if entry was set or updated (or if existing key was updated at limit).
 */
 const setOrUpdate = (state, input, now = Date.now()) => {
 	const { key, value, ttl: ttlInput, staleWindow: staleWindowInput, tags } = input;
-	if (value === void 0) return;
+	if (value === void 0) return false;
 	if (key == null) throw new Error("Missing key.");
+	if (state.size >= state.maxSize && !state.store.has(key)) return false;
+	if (_metrics?.memory.total.rss && _metrics?.memory.total.rss >= state.maxMemorySize * 1024 * 1024 && !state.store.has(key)) return false;
 	const ttl = ttlInput ?? state.defaultTtl;
 	const staleWindow = staleWindowInput ?? state.defaultStaleWindow;
 	const expiresAt = ttl > 0 ? now + ttl : Infinity;
@@ -911,6 +948,7 @@ const setOrUpdate = (state, input, now = Date.now()) => {
 		typeof tags === "string" ? [tags] : Array.isArray(tags) ? tags : null
 	];
 	state.store.set(key, entry);
+	return true;
 };
 
 //#endregion
@@ -1002,14 +1040,19 @@ var LocalTtlCache = class {
 	* @param options.ttl - Time-To-Live in milliseconds. Defaults to `defaultTtl`
 	* @param options.staleWindow - How long to serve stale data after expiration (milliseconds)
 	* @param options.tags - One or more tags for group invalidation
+	* @returns True if the entry was set or updated, false if rejected due to limits or invalid input
 	*
 	* @example
 	* ```typescript
-	* cache.set("user:123", { name: "Alice" }, {
+	* const success = cache.set("user:123", { name: "Alice" }, {
 	*   ttl: 5 * 60 * 1000,
 	*   staleWindow: 1 * 60 * 1000,
 	*   tags: "user:123",
 	* });
+	*
+	* if (!success) {
+	*   console.log("Entry was rejected due to size or memory limits");
+	* }
 	* ```
 	*
 	* @edge-cases
@@ -1017,9 +1060,13 @@ var LocalTtlCache = class {
 	* - If `ttl` is 0 or Infinite, the entry never expires
 	* - If `staleWindow` is larger than `ttl`, the entry can be served as stale longer than it was fresh
 	* - Tags are optional; only necessary for group invalidation via `invalidateTag()`
+	* - Returns `false` if value is `undefined` (existing value remains untouched)
+	* - Returns `false` if new key would exceed [`maxSize`](./docs/configuration.md#maxsize-number) limit
+	* - Returns `false` if new key would exceed [`maxMemorySize`](./docs/configuration.md#maxmemorysize-number) limit
+	* - Updating existing keys always succeeds, even at limit
 	*/
 	set(key, value, options) {
-		setOrUpdate(this.state, {
+		return setOrUpdate(this.state, {
 			key,
 			value,
 			ttl: options?.ttl,