@gravito/stasis 3.1.0 → 3.2.0

package/dist/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Unique identifier for a cached item.
+ *
+ * Used to reference and retrieve specific data entries within the cache storage.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const key: CacheKey = 'user:123:profile';
+ * ```
+ */
+export type CacheKey = string;
+/**
+ * Time-to-live (TTL) configuration for cache entries.
+ *
+ * Defines the duration or point in time when a cache entry becomes invalid.
+ * - `number`: Relative duration in seconds from the current time.
+ * - `Date`: Absolute point in time for expiration.
+ * - `null`: Persistent storage that never expires automatically.
+ * - `undefined`: Fallback to the default TTL configured in the store or repository.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const ttl: CacheTtl = 3600; // 1 hour
+ * const absoluteTtl: CacheTtl = new Date('2026-12-31');
+ * ```
+ */
+export type CacheTtl = number | Date | null | undefined;
+/**
+ * Result of a cache retrieval operation.
+ *
+ * Represents the cached data of type `T`, or `null` if the entry is missing or has expired.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const val: CacheValue<string> = 'cached content';
+ * const miss: CacheValue<number> = null;
+ * ```
+ */
+export type CacheValue<T = unknown> = T | null;
+/**
+ * Validates and prepares a cache key for storage operations.
+ *
+ * Ensures the key meets the minimum requirements for cache storage, such as being non-empty.
+ *
+ * @param key - The raw string to be used as a cache key.
+ * @returns The validated cache key.
+ * @throws {Error} Thrown if the provided key is an empty string or falsy.
+ *
+ * @example
+ * ```typescript
+ * const key = normalizeCacheKey('user_profile_123');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function normalizeCacheKey(key: string): string;
+/**
+ * Converts a flexible TTL definition into an absolute Unix epoch timestamp.
+ *
+ * Normalizes various TTL formats into a consistent millisecond-based timestamp
+ * used for expiration checks.
+ *
+ * @param ttl - The TTL configuration to convert.
+ * @param now - Reference timestamp in milliseconds for relative calculations. Defaults to current time.
+ * @returns The expiration timestamp in milliseconds, `null` for permanent storage, or `undefined` for default behavior.
+ *
+ * @example
+ * ```typescript
+ * // Relative TTL (60 seconds)
+ * const expiresAt = ttlToExpiresAt(60);
+ *
+ * // Absolute Date
+ * const expiresAtDate = ttlToExpiresAt(new Date('2026-12-31'));
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function ttlToExpiresAt(ttl: CacheTtl, now?: number): number | null | undefined;
+/**
+ * Evaluates whether a cache entry has exceeded its expiration time.
+ *
+ * Compares the provided expiration timestamp against a reference time to determine
+ * if the cached data should be considered stale.
+ *
+ * @param expiresAt - The expiration timestamp in milliseconds, or `null`/`undefined` for non-expiring entries.
+ * @param now - Reference timestamp in milliseconds for the comparison. Defaults to current time.
+ * @returns `true` if the current time has passed the expiration point; otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * const expired = isExpired(Date.now() - 1000); // true
+ * const persistent = isExpired(null); // false
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare function isExpired(expiresAt: number | null | undefined, now?: number): boolean;
+/**
+ * Options for data compression within the cache.
+ *
+ * Defines how and when data should be compressed before storage to save space
+ * and reduce I/O overhead.
+ *
+ * @public
+ * @since 3.1.0
+ *
+ * @example
+ * ```typescript
+ * const options: CompressionOptions = {
+ *   enabled: true,
+ *   minSize: 2048,
+ *   level: 9
+ * };
+ * ```
+ */
+export type CompressionOptions = {
+    /**
+     * Whether to enable compression for cached values.
+     *
+     * @defaultValue false
+     */
+    enabled: boolean;
+    /**
+     * Minimum size in bytes for the value to be compressed.
+     * Values smaller than this threshold will be stored uncompressed.
+     *
+     * @defaultValue 1024
+     */
+    minSize?: number;
+    /**
+     * Compression level for zlib (1-9).
+     * Higher levels provide better compression but require more CPU.
+     *
+     * @defaultValue 6
+     */
+    level?: number;
+};

package/dist/utils/LRUCache.d.ts

@@ -0,0 +1,104 @@
+/**
+ * A generic LRU (Least Recently Used) cache implementation.
+ *
+ * Uses a Map for O(1) lookups and a Doubly Linked List for O(1) updates to the access order.
+ * When the cache reaches its maximum capacity, the least recently accessed item is evicted.
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUCache<number>(100, (key, value) => {
+ *   console.log(`Evicted: ${key} = ${value}`);
+ * });
+ * cache.set('key1', 42);
+ * const val = cache.get('key1'); // 42
+ * ```
+ */
+export declare class LRUCache<T> {
+    private maxSize;
+    private onEvict?;
+    private map;
+    private head;
+    private tail;
+    /**
+     * Creates a new LRU cache instance.
+     *
+     * @param maxSize - The maximum number of items allowed in the cache. Set to 0 for unlimited.
+     * @param onEvict - Optional callback triggered when an item is evicted due to capacity limits.
+     */
+    constructor(maxSize: number, onEvict?: (key: string, value: T) => void);
+    /**
+     * The current number of items stored in the cache.
+     */
+    get size(): number;
+    /**
+     * Checks if a key exists in the cache without updating its access order.
+     *
+     * @param key - The identifier to look for.
+     * @returns True if the key exists, false otherwise.
+     */
+    has(key: string): boolean;
+    /**
+     * Retrieves an item from the cache and marks it as most recently used.
+     *
+     * @param key - The identifier of the item to retrieve.
+     * @returns The cached value, or undefined if not found.
+     *
+     * @example
+     * ```typescript
+     * const value = cache.get('my-key');
+     * ```
+     */
+    get(key: string): T | undefined;
+    /**
+     * Retrieves an item from the cache without updating its access order.
+     *
+     * Useful for inspecting the cache without affecting eviction priority.
+     *
+     * @param key - The identifier of the item to peek.
+     * @returns The cached value, or undefined if not found.
+     */
+    peek(key: string): T | undefined;
+    /**
+     * Adds or updates an item in the cache, marking it as most recently used.
+     *
+     * If the cache is at capacity, the least recently used item will be evicted.
+     *
+     * @param key - The identifier for the item.
+     * @param value - The data to store.
+     *
+     * @example
+     * ```typescript
+     * cache.set('user:1', { name: 'Alice' });
+     * ```
+     */
+    set(key: string, value: T): void;
+    /**
+     * Removes an item from the cache.
+     *
+     * @param key - The identifier of the item to remove.
+     * @returns True if the item was found and removed, false otherwise.
+     */
+    delete(key: string): boolean;
+    /**
+     * Removes all items from the cache.
+     */
+    clear(): void;
+    /**
+     * Moves a node to the head of the linked list (most recently used).
+     *
+     * @param node - The node to promote.
+     */
+    private moveToHead;
+    /**
+     * Removes a node from the linked list.
+     *
+     * @param node - The node to remove.
+     */
+    private removeNode;
+    /**
+     * Evicts the least recently used item (the tail of the list).
+     *
+     * Triggers the `onEvict` callback if provided.
+     */
+    private evict;
+}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gravito/stasis",
-  "version": "3.1.0",
+  "sideEffects": false,
+  "version": "3.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -11,6 +12,7 @@
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "bun": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
@@ -22,12 +24,13 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "build": "bun run build.ts",
+    "build:dts": "bun run build.ts --dts-only",
     "test": "bun test --timeout=10000",
     "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
     "test:ci": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
-    "test:unit": "bun test tests/ --timeout=10000",
+    "test:unit": "bun test $(find tests -name '*.test.ts' ! -name '*.integration.test.ts' 2>/dev/null | tr '\\n' ' ') --timeout=10000",
     "test:integration": "test $(find tests -name '*.integration.test.ts' 2>/dev/null | wc -l) -gt 0 && find tests -name '*.integration.test.ts' -print0 | xargs -0 bun test --timeout=10000 || echo 'No integration tests found'"
   },
   "keywords": [
@@ -40,15 +43,14 @@
   "author": "Carl Lee <carllee0520@gmail.com>",
   "license": "MIT",
   "peerDependencies": {
-    "@gravito/core": "workspace:*",
-    "@gravito/plasma": "workspace:*"
+    "@gravito/core": "^2.0.0",
+    "@gravito/plasma": "^2.0.0"
   },
   "devDependencies": {
     "@gravito/plasma": "workspace:*",
     "@gravito/core": "workspace:*",
     "@gravito/photon": "workspace:*",
     "bun-types": "latest",
-    "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
   "homepage": "https://github.com/gravito-framework/gravito#readme",