@veekhere/just-cache-it 1.0.3

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vitaliy Kuguenko
+
+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,285 @@
+# just-cache-it
+
+A generic cache implementation with optional TTL support and subscriptions
+
+- **Immutable** values
+- **Lightweight** and "**zero-dependency**"
+- **TTL** support
+- **Cache update** subscriptions
+- **Cache value update** subscriptions
+- **Cache key** utilities
+- **TypeScript** support
+
+## Dependencies
+
+**Runtime**
+
+- [uuid](https://github.com/uuidjs/uuid) for UUID generation (zero-dependency)
+- [lodash.clonedeep](https://github.com/lodash/lodash) for deep cloning (zero-dependency)
+
+**Development**
+
+- [jest](https://github.com/facebook/jest)
+- [ts-jest](https://github.com/kulshekhar/ts-jest)
+- [prettier](https://github.com/prettier/prettier)
+- [typescript](https://github.com/microsoft/TypeScript)
+
+## Quickstart
+
+**1. Install**
+
+```bash
+npm i @veekhere/just-cache-it
+```
+
+**2. Create a cache**
+
+```typescript
+import { CacheIt } from '@veekhere/just-cache-it';
+
+const cache = new CacheIt<string>();
+
+const cacheValue: CacheValue<string> = cache.set('key', 'value');
+
+cacheValue.unwrapPrevious(); // ⇨ undefined
+cacheValue.unwrapCurrent(); // ⇨ 'value'
+
+cacheValue.subscribe({
+  next: (value: CacheValue<string>) => {
+    const previousValue = value.unwrapPrevious();
+    const currentValue = value.unwrapCurrent();
+
+    // Do something with the previous and current values
+  },
+  complete: () => {
+    // Trigger something when the subscription is cancelled
+  },
+});
+```
+
+## API Summary
+
+**Main cache**
+
+|                                                         |                                                    |                 |
+| ------------------------------------------------------- | -------------------------------------------------- | --------------- |
+| [`CacheIt`](#cacheit)                                   | The main cache class                               | New in `v1.0.0` |
+| [`CacheSubscriptionHandler`](#cachesubscriptionhandler) | Represents a handler to call when cache is updated | New in `v1.0.0` |
+| [`CacheSubscription`](#cachesubscription)               | Represents a subscription to cache changes         | New in `v1.0.0` |
+
+**Cache values**
+
+|                                                                     |                                                                 |                 |
+| ------------------------------------------------------------------- | --------------------------------------------------------------- | --------------- |
+| [`CacheValue`](#cachevalue)                                         | Represents a cached value that can be updated and subscribed to | New in `v1.0.0` |
+| [`UnwrapHandlers`](#unwraphandlers)                                 | Represents the handlers to call when unwrapping a cache value   | New in `v1.0.0` |
+| [`CacheValueSubscriptionHandlers`](#cachevaluesubscriptionhandlers) | Represents the handlers to call when cache value changes        | New in `v1.0.0` |
+| [`CacheValueSubscription`](#cachevaluesubscription)                 | Represents a subscription to a cache value                      | New in `v1.0.0` |
+
+**Types and utilities**
+
+|                                 |                                                   |                 |
+| ------------------------------- | ------------------------------------------------- | --------------- |
+| [`CacheItUtils`](#cacheitutils) | Utility functions for working with cache entries  | New in `v1.0.0` |
+| [`Maybe`](#maybe)               | Represents a value that may or may not be present | New in `v1.0.0` |
+
+## API
+
+### CacheIt
+
+Main cache class. Returned values are immutable
+
+**1. Primitive values**
+
+```typescript
+import { CacheIt } from '@veekhere/just-cache-it';
+
+const cache = new CacheIt<string>(); // string cache
+
+cache.set('key', 'value');
+
+cache.get('key'); // ⇨ 'value'
+```
+
+**2. User defined values**
+
+```typescript
+import { CacheIt } from '@veekhere/just-cache-it';
+
+class User {
+  constructor(public name: string) {}
+
+  whois(): string {
+    return `Hello, my name is ${this.name}`;
+  }
+}
+
+const cache = new CacheIt<User>(); // User cache
+
+cache.set('key', new User('John'));
+
+cache.get('key')?.unwrapCurrent(); // ⇨ User { name: 'John' }
+```
+
+**3. Arrays**
+
+```typescript
+import { CacheIt } from '@veekhere/just-cache-it';
+
+const cache = new CacheIt<string[]>(); // string[] cache
+
+cache.set('key', ['value']);
+
+cache.get('key'); // ⇨ ['value']
+```
+
+**And so on...**
+
+### CacheSubscriptionHandler
+
+Represents a handler to call when cache is updated
+
+```typescript
+import { CacheIt } from '@veekhere/just-cache-it';
+
+const cache = new CacheIt<string>();
+
+const handler: CacheSubscriptionHandler = () => {
+  // Trigger something when the cache is updated
+};
+
+const subscription = cache.subscribe(handler);
+```
+
+### CacheSubscription
+
+Represents a subscription to cache changes
+
+```typescript
+import { CacheIt } from '@veekhere/just-cache-it';
+
+const cache = new CacheIt<string>();
+
+const subscription = cache.subscribe(() => {
+  // Trigger something when the cache changes
+});
+```
+
+### CacheValue
+
+Represents a cached value that can be updated and subscribed to
+
+```typescript
+import { CacheIt, CacheValue } from '@veekhere/just-cache-it';
+
+const cache = new CacheIt<string>();
+
+const cacheValue: CacheValue<string> = cache.set('key', 'value');
+
+cacheValue.unwrapPrevious(); // ⇨ undefined
+cacheValue.unwrapCurrent(); // ⇨ 'value'
+
+cacheValue.subscribe({
+  next: (value: CacheValue<string>) => {
+    // Do something with the previous and current values
+  },
+  complete: () => {
+    // Trigger something when the subscription is cancelled
+  },
+});
+```
+
+### UnwrapHandlers
+
+Represents the handlers to call when unwrapping a cache value
+
+```typescript
+import { CacheIt, CacheValue } from '@veekhere/just-cache-it';
+
+const cache = new CacheIt<string>();
+
+const cacheValue: CacheValue<string> = cache.set('key', 'value');
+
+const handlers: UnwrapHandlers<string> = {
+  onPresent: (value: string) => {
+    // Do something with the value
+  },
+  onAbsent: () => {
+    // Do something when the value is absent
+  },
+};
+
+cacheValue.unwrapPrevious(handlers);
+cacheValue.unwrapCurrent(handlers);
+```
+
+### CacheValueSubscriptionHandlers
+
+Represents the handlers to call when cache value changes
+
+```typescript
+import { CacheValue, CacheValueSubscriptionHandlers } from '@veekhere/just-cache-it';
+
+const handlers: CacheValueSubscriptionHandlers<string> = {
+  next: (value: CacheValue<string>) => {
+    // Do something with the previous and current values
+  },
+  complete: () => {
+    // Trigger something when the subscription is cancelled
+  },
+};
+
+// register cache ...
+
+cache.subscribe(handlers);
+```
+
+### CacheValueSubscription
+
+Represents a subscription to a cache value
+
+```typescript
+import { CacheIt, CacheValue } from '@veekhere/just-cache-it';
+
+const cache = new CacheIt<string>();
+
+const cacheValue: CacheValue<string> = cache.set('key', 'value');
+
+const subscription = cacheValue.subscribe({
+  // handlers
+});
+
+// some complex logic
+
+subscription.unsubscribe();
+```
+
+### CacheItUtils
+
+Utility functions for working with cache entries
+
+```typescript
+import { CacheItUtils } from '@veekhere/just-cache-it';
+
+const keyGenerator = CacheItUtils.addBaseKey('BASE#KEY');
+
+keyGenerator.generateKey('my', 'additional', 'parts'); // ⇨ '$CACHE-IT_BASE#KEY_my-additional-parts_2a4f54b2-700a-41b3-8008-ac641a550ee5'
+```
+
+### Maybe
+
+Represents a value that may or may not be present
+
+```typescript
+import { Maybe } from '@veekhere/just-cache-it';
+
+const maybe: Maybe<string> = getData(); // ⇨ string | undefined
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## License
+
+[MIT](https://github.com/veekhere/just-cache-it/blob/master/LICENSE.md)

package/dist/index.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Cache-It is a generic cache implementation with optional TTL support and subscriptions. It can be used to cache any value, including objects, arrays, and primitives.
+ * @template T The type of values stored in the cache
+ * @see https://github.com/veekhere/cache-it
+ * @author veekhere
+ * @license MIT
+ * @version 1.0.0
+ */
+/**
+ * Represents a value that may or may not be present
+ * @template T The type of the value
+ */
+type Maybe<T> = T | undefined;
+/**
+ * Represents the handlers to call when unwrapping a cache value
+ * @template T The type of the value
+ */
+type UnwrapHandlers<T> = {
+    /**
+     * Called when the value is present
+     * @param value The value
+     */
+    onPresent?: (value: T) => void;
+    /**
+     * Called when the value is absent
+     */
+    onAbsent?: () => void;
+};
+/**
+ * Subscription to a cache value
+ */
+type CacheValueSubscription = {
+    /**
+     * Unsubscribes from the cache value
+     */
+    unsubscribe: () => void;
+};
+/**
+ * Represents the handlers to call when cache value changes
+ */
+type CacheValueSubscriptionHandlers<T> = {
+    /**
+     * Called when the value changes
+     * @param value The new value of the cache
+     */
+    next?: (value: Omit<CacheValue<T>, "subscribe" | "unsubscribeAll">) => void;
+    /**
+     * Called when the subscription is cancelled
+     */
+    complete?: () => void;
+};
+/**
+ * Represents a value that can be cached and subscribed to
+ * @template T The type of the value
+ */
+declare class CacheValue<T> {
+    private readonly value;
+    private readonly subscribers;
+    /**
+     * Creates a new cache value
+     * @param ttl The time-to-live in milliseconds
+     */
+    constructor(ttl?: number);
+    /**
+     * Updates the value in the cache
+     * @param value The new value to set
+     */
+    update(value: Maybe<T>): void;
+    /**
+     * Returns the current value, or undefined if not present
+     */
+    unwrapCurrent(): Maybe<T>;
+    /**
+     * Calls the provided handlers with the current value, or undefined if not present
+     * @param handlers The handlers to call
+     */
+    unwrapCurrent(handlers: UnwrapHandlers<T>): void;
+    /**
+     * Returns the previous value, or undefined if not present
+     */
+    unwrapPrevious(): Maybe<T>;
+    /**
+     * Calls the provided handlers with the previous value, or undefined if not present
+     * @param handlers The handlers to call
+     */
+    unwrapPrevious(handlers: UnwrapHandlers<T>): void;
+    /**
+     * Removes the current and previous values
+     */
+    clear(): void;
+    /**
+     * Subscribes to changes in the cache value
+     * @param handlers The handlers to call when the value changes
+     * @returns A subscription object that can be used to unsubscribe
+     */
+    subscribe(handlers: CacheValueSubscriptionHandlers<T>): CacheValueSubscription;
+    /**
+     * Unsubscribes from all subscribers
+     */
+    unsubscribeAll(): void;
+    private notifySubscribers;
+}
+/**
+ * Subscription to a cache changes
+ */
+type CacheSubscription = {
+    /**
+     * Unsubscribes from the cache changes
+     */
+    unsubscribe: () => void;
+};
+/**
+ * Represents a handler to call when cache is updated
+ */
+type CacheSubscriptionHandler = () => void;
+/**
+ * A generic cache implementation with optional TTL support
+ * @template T The type of values stored in the cache
+ */
+declare class CacheIt<T> {
+    private readonly cache;
+    private readonly subscribers;
+    /**
+     * Sets a value in the cache
+     * @param key The key to store the value under
+     * @param value The value to store
+     * @param ttl Optional time-to-live in milliseconds
+     */
+    set(key: string, value: T, ttl?: number): CacheValue<T>;
+    /**
+     * Retrieves a value from the cache
+     * @param key The key to lookup
+     * @returns The stored value, or undefined if not found or expired
+     */
+    get(key: string): CacheValue<T> | undefined;
+    /**
+     * Removes a value from the cache
+     * @param key The key to remove
+     * @returns true if the key was found and removed, false otherwise
+     */
+    delete(key: string): boolean;
+    /**
+     * Removes all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Returns the number of entries in the cache
+     */
+    size(): number;
+    /**
+     * Checks if a key exists in the cache and is not expired
+     * @param key The key to check
+     * @returns true if the key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Subscribes to changes in the cache
+     * @param handler The handler to call when the cache changes
+     * @returns A subscription object that can be used to unsubscribe
+     */
+    subscribe(handler: CacheSubscriptionHandler): CacheSubscription;
+    /**
+     * Unsubscribes from all subscribers without emitting any events
+     */
+    unsubscribeAll(): void;
+    private notifySubscribers;
+}
+/**
+ * Represents a key generator for cache entries
+ */
+type CacheKeyGenerator = {
+    /**
+     * Generates a key with additional parts
+     * @param additional Additional parts to add to the key
+     */
+    generateKey: (...additional: string[]) => string;
+};
+/**
+ * Utility functions for working with cache entries
+ */
+declare class CacheItUtils {
+    /**
+     * Adds a base key to a key generator
+     * @param baseKey The base key to add
+     * @returns A key generator with the base key added
+     */
+    static addBaseKey(baseKey: string): CacheKeyGenerator;
+    /**
+     * Generates a key with additional parts
+     * @param additional Additional parts to add to the key
+     */
+    static generateKey(...additional: string[]): string;
+    private static generateKeyWithBase;
+}
+export { CacheIt, CacheItUtils, CacheValue, CacheValueSubscription, UnwrapHandlers };

package/dist/index.js

@@ -0,0 +1,237 @@
+import cloneDeep from 'lodash.clonedeep';
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * Represents a value that can be cached and subscribed to
+ * @template T The type of the value
+ */
+class CacheValue {
+    /**
+     * Creates a new cache value
+     * @param ttl The time-to-live in milliseconds
+     */
+    constructor(ttl) {
+        this.value = {
+            current: undefined,
+            previous: undefined,
+        };
+        this.subscribers = new Map();
+        if (ttl != null) {
+            setTimeout(() => {
+                this.update(undefined);
+            }, ttl);
+        }
+    }
+    /**
+     * Updates the value in the cache
+     * @param value The new value to set
+     */
+    update(value) {
+        const oldValue = typeof this.value.current === 'object' && this.value.current != null
+            ? cloneDeep(this.value.current)
+            : this.value.current;
+        const newValue = typeof value === 'object' && value != null
+            ? cloneDeep(value)
+            : value;
+        this.value.previous = oldValue;
+        this.value.current = newValue;
+        this.notifySubscribers();
+    }
+    unwrapCurrent(handlers) {
+        var _a, _b;
+        if (handlers) {
+            if (this.value.current) {
+                (_a = handlers.onPresent) === null || _a === void 0 ? void 0 : _a.call(handlers, this.value.current);
+            }
+            else {
+                (_b = handlers.onAbsent) === null || _b === void 0 ? void 0 : _b.call(handlers);
+            }
+        }
+        else {
+            return this.value.current;
+        }
+    }
+    unwrapPrevious(handlers) {
+        var _a, _b;
+        if (handlers) {
+            if (this.value.previous) {
+                (_a = handlers.onPresent) === null || _a === void 0 ? void 0 : _a.call(handlers, this.value.previous);
+            }
+            else {
+                (_b = handlers.onAbsent) === null || _b === void 0 ? void 0 : _b.call(handlers);
+            }
+        }
+        else {
+            return this.value.previous;
+        }
+    }
+    /**
+     * Removes the current and previous values
+     */
+    clear() {
+        this.value.current = undefined;
+        this.value.previous = undefined;
+        this.notifySubscribers();
+    }
+    /**
+     * Subscribes to changes in the cache value
+     * @param handlers The handlers to call when the value changes
+     * @returns A subscription object that can be used to unsubscribe
+     */
+    subscribe(handlers) {
+        const symbol = Symbol();
+        this.subscribers.set(symbol, handlers);
+        return {
+            unsubscribe: () => {
+                var _a;
+                (_a = handlers === null || handlers === void 0 ? void 0 : handlers.complete) === null || _a === void 0 ? void 0 : _a.call(handlers);
+                this.subscribers.delete(symbol);
+            },
+        };
+    }
+    /**
+     * Unsubscribes from all subscribers
+     */
+    unsubscribeAll() {
+        this.notifySubscribers(true);
+        this.subscribers.clear();
+    }
+    notifySubscribers(isComplete) {
+        this.subscribers.forEach((handlers) => {
+            var _a, _b;
+            if (isComplete) {
+                (_a = handlers.complete) === null || _a === void 0 ? void 0 : _a.call(handlers);
+            }
+            else {
+                (_b = handlers.next) === null || _b === void 0 ? void 0 : _b.call(handlers, this);
+            }
+        });
+    }
+}
+/**
+ * A generic cache implementation with optional TTL support
+ * @template T The type of values stored in the cache
+ */
+class CacheIt {
+    constructor() {
+        this.cache = new Map();
+        this.subscribers = new Map();
+    }
+    /**
+     * Sets a value in the cache
+     * @param key The key to store the value under
+     * @param value The value to store
+     * @param ttl Optional time-to-live in milliseconds
+     */
+    set(key, value, ttl) {
+        const cacheValue = new CacheValue(ttl);
+        cacheValue.update(value);
+        this.cache.set(key, cacheValue);
+        this.notifySubscribers();
+        return cacheValue;
+    }
+    /**
+     * Retrieves a value from the cache
+     * @param key The key to lookup
+     * @returns The stored value, or undefined if not found or expired
+     */
+    get(key) {
+        const cacheValue = this.cache.get(key);
+        if (!cacheValue) {
+            return undefined;
+        }
+        return cacheValue;
+    }
+    /**
+     * Removes a value from the cache
+     * @param key The key to remove
+     * @returns true if the key was found and removed, false otherwise
+     */
+    delete(key) {
+        const isDeleted = this.cache.delete(key);
+        if (isDeleted) {
+            this.notifySubscribers();
+        }
+        return isDeleted;
+    }
+    /**
+     * Removes all entries from the cache
+     */
+    clear() {
+        this.cache.clear();
+        this.notifySubscribers();
+    }
+    /**
+     * Returns the number of entries in the cache
+     */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Checks if a key exists in the cache and is not expired
+     * @param key The key to check
+     * @returns true if the key exists and is not expired
+     */
+    has(key) {
+        const cacheValue = this.cache.get(key);
+        if (!cacheValue) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Subscribes to changes in the cache
+     * @param handler The handler to call when the cache changes
+     * @returns A subscription object that can be used to unsubscribe
+     */
+    subscribe(handler) {
+        const symbol = Symbol();
+        this.subscribers.set(symbol, handler);
+        return {
+            unsubscribe: () => {
+                this.subscribers.delete(symbol);
+            },
+        };
+    }
+    /**
+     * Unsubscribes from all subscribers without emitting any events
+     */
+    unsubscribeAll() {
+        this.subscribers.clear();
+    }
+    notifySubscribers() {
+        this.subscribers.forEach((handler) => handler());
+    }
+}
+/**
+ * Utility functions for working with cache entries
+ */
+class CacheItUtils {
+    /**
+     * Adds a base key to a key generator
+     * @param baseKey The base key to add
+     * @returns A key generator with the base key added
+     */
+    static addBaseKey(baseKey) {
+        if (!baseKey) {
+            throw new Error('Base key cannot be empty');
+        }
+        return {
+            generateKey: (...additional) => CacheItUtils.generateKeyWithBase(baseKey, ...additional),
+        };
+    }
+    /**
+     * Generates a key with additional parts
+     * @param additional Additional parts to add to the key
+     */
+    static generateKey(...additional) {
+        return CacheItUtils.generateKeyWithBase(undefined, ...additional);
+    }
+    static generateKeyWithBase(baseKey, ...additional) {
+        const baseKeyPart = baseKey != null ? `${baseKey}_` : '';
+        const additionalPart = additional != null && (additional === null || additional === void 0 ? void 0 : additional.length) > 0
+            ? `${additional === null || additional === void 0 ? void 0 : additional.join('-')}_`
+            : '';
+        return `$CACHE-IT_${baseKeyPart}${additionalPart}${uuidv4()}`;
+    }
+}
+export { CacheIt, CacheItUtils, CacheValue };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@veekhere/just-cache-it",
+  "version": "1.0.3",
+  "description": "A generic cache implementation with optional TTL support and subscriptions",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  },
+  "keywords": [
+    "cache",
+    "ttl",
+    "subscriptions",
+    "immutable",
+    "zero-dependency",
+    "typescript"
+  ],
+  "author": "veekhere",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "package.json"
+  ],
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.13.4",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.1",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.0.4"
+  },
+  "dependencies": {
+    "@types/lodash.clonedeep": "^4.5.9",
+    "lodash.clonedeep": "^4.5.0",
+    "uuid": "^11.0.0"
+  }
+}