@neezco/cache 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2023 github.com/DanhezCode
+
+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,55 @@
+## 🚧 Project Status
+
+> **⚠️ Under active development**  
+> This library has not yet reached its first stable release.  
+> The API is still evolving, and **breaking changes** may occur at any time.  
+> Production use is **not recommended** until a stable version is published.
+
+# Short-Live 🚀
+
+**A smart, lightweight caching library that helps you store data temporarily with automatic cleanup.**
+
+## Why Short-Live?
+
+### 🧹 **Automatic Cleanup**
+
+Expired data is cleaned up automatically in the background without your intervention.
+
+### 📊 **Scales Well**
+
+Whether caching 10 items or millions, Short-Live is designed to stay fast and efficient.
+
+### 🏷️ **Tag-Based Invalidation**
+
+Group related data and clear it all with a single command.
+
+### 🎯 **Smart Memory Management**
+
+Intelligently prioritizes what to clean up based on usage patterns and memory constraints.
+
+### ⚡ **CPU Efficient**
+
+All core operations are O(1) with minimal CPU overhead. Background cleanup runs intelligently without blocking your application. Perfect for resource-constrained environments and high-throughput scenarios.
+
+---
+
+## Documentation
+
+- **[Getting Started](./docs/getting-started.md)** - Installation and basic usage
+- **[Examples](./docs/examples.md)** - Real-world use cases (API caching, sessions, database queries, etc.)
+- **[API Reference](./docs/api-reference.md)** - Complete API documentation with edge cases
+- **[Configuration](./docs/configuration.md)** - All configuration options explained
+
+---
+
+## License
+
+MIT © [Daniel Hernández Ochoa](https://github.com/DanhezCode)
+
+---
+
+## Contributing
+
+We'd love your help! Check out [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+**Questions? Found a bug?** [Open an issue](https://github.com/neezco/cache/issues) on GitHub.

package/dist/browser/index.d.ts

@@ -0,0 +1,276 @@
+//#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 a key expires naturally.
+  * @param key - The expired key.
+  * @param value - The value associated with the expired key.
+  * @param reason - The reason for deletion ('expired', or 'stale').
+  */
+  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 that do not
+  * specify their own `staleWindowMs`.
+  *
+  * This window determines how long an entry may continue to be
+  * served as stale after it reaches its expiration time.
+  *
+  * The window is always relative to the entry’s own expiration
+  * moment, regardless of whether that expiration comes from an
+  * explicit `ttl` or from the cache’s default TTL.
+  * @default null (No stale window)
+  */
+  defaultStaleWindow: number;
+  /**
+  * Maximum number of entries the cache can hold.
+  * Beyond this limit, new entries are ignored.
+  * @default null (unlimited)
+  */
+  maxSize?: number;
+  /**
+  * Controls how stale entries are handled when read from the cache.
+  *
+  * - true  → stale entries are purged immediately after being returned.
+  * - false → stale entries are retained after being returned.
+  *
+  * @default false
+  */
+  purgeStaleOnGet: boolean;
+  /**
+  * Controls how stale entries are handled during sweep operations.
+  *
+  * - true  → stale entries are purged during sweeps.
+  * - false → stale entries are retained during sweeps.
+  *
+  * @default false
+  */
+  purgeStaleOnSweep: boolean;
+  /**
+  * Whether to automatically start the sweep process when the cache is created.
+  *
+  * - true  → sweep starts automatically.
+  * - false → sweep does not start automatically, allowing manual control.
+  *
+  * @internal
+  * @default true
+  */
+  _autoStartSweep: boolean;
+  /**
+  * Allowed expired ratio for the cache instance.
+  */
+  _maxAllowExpiredRatio: number;
+}
+/**
+* Public configuration options for the TTL cache.
+*/
+type CacheOptions = Partial<CacheConfigBase>;
+//#endregion
+//#region src/index.d.ts
+/**
+* A TTL (Time-To-Live) cache implementation with support for expiration,
+* stale windows, tag-based invalidation, and automatic sweeping.
+*
+* Provides O(1) constant-time operations for all core methods.
+*
+* @example
+* ```typescript
+* const cache = new LocalTtlCache();
+* cache.set("user:123", { name: "Alice" }, { ttl: 5 * 60 * 1000 });
+* const user = cache.get("user:123"); // { name: "Alice" }
+* ```
+*/
+declare class LocalTtlCache {
+  private state;
+  /**
+  * Creates a new cache instance.
+  *
+  * @param options - Configuration options for the cache (defaultTtl, defaultStaleWindow, maxSize, etc.)
+  *
+  * @example
+  * ```typescript
+  * const cache = new LocalTtlCache({
+  *   defaultTtl: 30 * 60 * 1000, // 30 minutes
+  *   defaultStaleWindow: 5 * 60 * 1000, // 5 minutes
+  *   maxSize: 500_000, // Maximum 500_000 entries
+  *   onExpire: (key, value) => console.log(`Expired: ${key}`),
+  *   onDelete: (key, value, reason) => console.log(`Deleted: ${key}, reason: ${reason}`),
+  * });
+  * ```
+  */
+  constructor(options?: CacheOptions);
+  /**
+  * Gets the current number of entries tracked by the cache.
+  *
+  * This value may include entries that are already expired but have not yet been
+  * removed by the lazy cleanup system. Expired keys are cleaned only when it is
+  * efficient to do so, so the count can temporarily be higher than the number of
+  * actually valid (non‑expired) entries.
+  *
+  * @returns The number of entries currently stored (including entries pending cleanup)
+  *
+  * @example
+  * ```typescript
+  * console.log(cache.size); // e.g., 42
+  * ```
+  */
+  get size(): number;
+  /**
+  * Retrieves a value from the cache.
+  *
+  * Returns the value if it exists and is not fully expired. If an entry is in the
+  * stale window (expired but still within staleWindow), the stale value is returned.
+  *
+  
+  * @param key - The key to retrieve
+  * @returns The cached value if valid, undefined otherwise
+  *
+  * @example
+  * ```typescript
+  * const user = cache.get<{ name: string }>("user:123");
+  * ```
+  *
+  * @edge-cases
+  * - Returns `undefined` if the key doesn't exist
+  * - Returns `undefined` if the key has expired beyond the stale window
+  * - Returns the stale value if within the stale window
+  * - If `purgeStaleOnGet` is enabled, stale entries are deleted after being returned
+  */
+  get<T = unknown>(key: string): T | undefined;
+  /**
+  * Sets or updates a value in the cache.
+  *
+  * If the key already exists, it will be completely replaced.
+  *
+  * @param key - The key under which to store the value
+  * @param value - The value to cache (any type)
+  * @param options - Optional configuration for this specific entry
+  * @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
+  *
+  * @example
+  * ```typescript
+  * cache.set("user:123", { name: "Alice" }, {
+  *   ttl: 5 * 60 * 1000,
+  *   staleWindow: 1 * 60 * 1000,
+  *   tags: "user:123",
+  * });
+  * ```
+  *
+  * @edge-cases
+  * - Overwriting an existing key replaces it completely
+  * - 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()`
+  */
+  set(key: string, value: unknown, options?: {
+    ttl?: number;
+    staleWindow?: number;
+    tags?: string | string[];
+  }): void;
+  /**
+  * Deletes a specific key from the cache.
+  *
+  * @param key - The key to delete
+  * @returns True if the key was deleted, false if it didn't exist
+  *
+  * @example
+  * ```typescript
+  * const wasDeleted = cache.delete("user:123");
+  * ```
+  *
+  * @edge-cases
+  * - Triggers the `onDelete` callback with reason `'manual'`
+  * - Does not trigger the `onExpire` callback
+  * - Returns `false` if the key was already expired
+  * - Deleting a non-existent key returns `false` without error
+  */
+  delete(key: string): boolean;
+  /**
+  * Checks if a key exists in the cache and is not fully expired.
+  *
+  * Returns true if the key exists and is either fresh or within the stale window.
+  * Use this when you only need to check existence without retrieving the value.
+  *
+  * @param key - The key to check
+  * @returns True if the key exists and is valid, false otherwise
+  *
+  * @example
+  * ```typescript
+  * if (cache.has("user:123")) {
+  *   // Key exists (either fresh or stale)
+  * }
+  * ```
+  *
+  * @edge-cases
+  * - Returns `false` if the key doesn't exist
+  * - Returns `false` if the key has expired beyond the stale window
+  * - Returns `true` if the key is in the stale window (still being served)
+  * - Both `has()` and `get()` have O(1) complexity; prefer `get()` if you need the value
+  */
+  has(key: string): boolean;
+  /**
+  * Removes all entries from the cache at once.
+  *
+  * This is useful for resetting the cache or freeing memory when needed.
+  * The `onDelete` callback is NOT invoked during clear (intentional optimization).
+  *
+  * @example
+  * ```typescript
+  * cache.clear(); // cache.size is now 0
+  * ```
+  *
+  * @edge-cases
+  * - The `onDelete` callback is NOT triggered during clear
+  * - Clears both expired and fresh entries
+  * - Resets `cache.size` to 0
+  */
+  clear(): void;
+  /**
+  * Marks all entries with one or more tags as expired (or stale, if requested).
+  *
+  * If an entry has multiple tags, invalidating ANY of those tags will invalidate the entry.
+  *
+  * @param tags - A single tag (string) or array of tags to invalidate
+  * @param asStale - If true, marks entries as stale instead of fully expired (still served from stale window)
+  *
+  * @example
+  * ```typescript
+  * // Invalidate a single tag
+  * cache.invalidateTag("user:123");
+  *
+  * // Invalidate multiple tags
+  * cache.invalidateTag(["user:123", "posts:456"]);
+  * ```
+  *
+  * @edge-cases
+  * - Does not throw errors if a tag has no associated entries
+  * - Invalidating a tag doesn't prevent new entries from being tagged with it later
+  * - The `onDelete` callback is triggered with reason `'expired'` (even if `asStale` is true)
+  */
+  invalidateTag(tags: string | string[], asStale?: boolean): void;
+}
+//#endregion
+export { type CacheOptions, LocalTtlCache };
+//# sourceMappingURL=index.d.ts.map