alepha 0.15.0 → 0.15.2

package/dist/cache/core/index.d.ts

@@ -12,38 +12,50 @@ import * as alepha_logger0 from "alepha/logger";
  */
 declare abstract class CacheProvider {
   /**
-       * Get the value of a key.
-       *
-       * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
-       * @param key The key of the value to get.
-       *
-       * @return The value of the key, or undefined if the key does not exist.
-       */
+   * Get the value of a key.
+   *
+   * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
+   * @param key The key of the value to get.
+   *
+   * @return The value of the key, or undefined if the key does not exist.
+   */
   abstract get(name: string, key: string): Promise<Uint8Array | undefined>;
   /**
-       * Set the string value of a key.
-       *
-       * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
-       * @param key The key of the value to set.
-       * @param value The value to set.
-       * @param ttl The time-to-live of the key, in milliseconds.
-       *
-       * @return The value of the key.
-       */
+   * Set the string value of a key.
+   *
+   * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
+   * @param key The key of the value to set.
+   * @param value The value to set.
+   * @param ttl The time-to-live of the key, in milliseconds.
+   *
+   * @return The value of the key.
+   */
   abstract set(name: string, key: string, value: Uint8Array, ttl?: number): Promise<Uint8Array>;
   /**
-       * Remove the specified keys.
-       *
-       * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
-       * @param keys The keys to delete.
-       */
+   * Remove the specified keys.
+   *
+   * @param name Cache name, used to group keys. Should be Redis-like "some:group:name" format.
+   * @param keys The keys to delete.
+   */
   abstract del(name: string, ...keys: string[]): Promise<void>;
   abstract has(name: string, key: string): Promise<boolean>;
   abstract keys(name: string, filter?: string): Promise<string[]>;
   /**
-       * Remove all keys from all cache names.
-       */
+   * Remove all keys from all cache names.
+   */
   abstract clear(): Promise<void>;
+  /**
+   * Increment the integer value of a key by the given amount.
+   *
+   * If the key does not exist, it is set to 0 before performing the operation.
+   * This operation is atomic when using Redis.
+   *
+   * @param name Cache name, used to group keys.
+   * @param key The key to increment.
+   * @param amount The amount to increment by.
+   * @returns The new value after incrementing.
+   */
+  abstract incr(name: string, key: string, amount: number): Promise<number>;
 }
 //#endregion
 //#region ../../src/cache/core/primitives/$cache.d.ts
@@ -101,37 +113,37 @@ declare const $cache: {
 };
 interface CachePrimitiveOptions<TReturn = any, TParameter extends any[] = any[]> {
   /**
-       * The cache name. This is useful for invalidating multiple caches at once.
-       *
-       * Store key as `cache:$name:$key`.
-       *
-       * @default Name of the key of the class.
-       */
+   * The cache name. This is useful for invalidating multiple caches at once.
+   *
+   * Store key as `cache:$name:$key`.
+   *
+   * @default Name of the key of the class.
+   */
   name?: string;
   /**
-       * Function which returns cached data.
-       */
+   * Function which returns cached data.
+   */
   handler?: (...args: TParameter) => TReturn;
   /**
-       * The key generator for the cache.
-       * If not provided, the arguments will be json.stringify().
-       */
+   * The key generator for the cache.
+   * If not provided, the arguments will be json.stringify().
+   */
   key?: (...args: TParameter) => string;
   /**
-       * The store provider for the cache.
-       * If not provided, the default store provider will be used.
-       */
+   * The store provider for the cache.
+   * If not provided, the default store provider will be used.
+   */
   provider?: InstantiableClass<CacheProvider> | "memory";
   /**
-       * The time-to-live for the cache in seconds.
-       * Set 0 to skip expiration.
-       *
-       * @default 300 (5 minutes).
-       */
+   * The time-to-live for the cache in seconds.
+   * Set 0 to skip expiration.
+   *
+   * @default 300 (5 minutes).
+   */
   ttl?: DurationLike;
   /**
-       * If the cache is disabled.
-       */
+   * If the cache is disabled.
+   */
   disabled?: boolean;
 }
 declare class CachePrimitive<TReturn = any, TParameter extends any[] = any[]> extends Primitive<CachePrimitiveOptions<TReturn, TParameter>> {
@@ -160,8 +172,8 @@ declare class CachePrimitive<TReturn = any, TParameter extends any[] = any[]> ex
 }
 interface CachePrimitiveFn<TReturn = any, TParameter extends any[] = any[]> extends CachePrimitive<TReturn, TParameter> {
   /**
-       * Run the cache primitive with the provided arguments.
-       */
+   * Run the cache primitive with the provided arguments.
+   */
   (...args: TParameter): Promise<TReturn>;
 }
 //#endregion
@@ -172,31 +184,191 @@ type CacheValue = {
   data?: Uint8Array;
   timeout?: Timeout;
 };
+interface MemoryCacheCall {
+  name: string;
+  key: string;
+  timestamp: number;
+}
+interface MemoryCacheSetCall extends MemoryCacheCall {
+  value: Uint8Array;
+  ttl?: number;
+}
+interface MemoryCacheDelCall {
+  name: string;
+  keys: string[];
+  timestamp: number;
+}
+interface MemoryCacheStats {
+  hits: number;
+  misses: number;
+  sets: number;
+  deletes: number;
+}
+interface MemoryCacheProviderOptions {
+  /**
+   * Error to throw on get operations (for testing error handling)
+   */
+  getError?: Error | null;
+  /**
+   * Error to throw on set operations (for testing error handling)
+   */
+  setError?: Error | null;
+  /**
+   * Error to throw on del operations (for testing error handling)
+   */
+  delError?: Error | null;
+}
+/**
+ * In-memory implementation of CacheProvider for testing.
+ *
+ * This provider stores all cache entries in memory, making it ideal for
+ * unit tests that need to verify cache operations without touching Redis or other backends.
+ *
+ * @example
+ * ```typescript
+ * // In tests, substitute the real CacheProvider with MemoryCacheProvider
+ * const alepha = Alepha.create().with({
+ *   provide: CacheProvider,
+ *   use: MemoryCacheProvider,
+ * });
+ *
+ * // Run code that uses caching
+ * const service = alepha.inject(MyService);
+ * await service.fetchWithCache("key");
+ *
+ * // Verify cache behavior
+ * const cache = alepha.inject(MemoryCacheProvider);
+ * expect(cache.stats().misses).toBe(1);
+ * await service.fetchWithCache("key");
+ * expect(cache.stats().hits).toBe(1);
+ * ```
+ */
 declare class MemoryCacheProvider implements CacheProvider {
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly log: alepha_logger0.Logger;
   protected store: Record<CacheName, Record<CacheKey, CacheValue>>;
+  /**
+   * All recorded get calls.
+   */
+  getCalls: MemoryCacheCall[];
+  /**
+   * All recorded set calls.
+   */
+  setCalls: MemoryCacheSetCall[];
+  /**
+   * All recorded del calls.
+   */
+  delCalls: MemoryCacheDelCall[];
+  /**
+   * Cache statistics.
+   */
+  protected _stats: MemoryCacheStats;
+  /**
+   * Error to throw on get (for testing error handling)
+   */
+  getError: Error | null;
+  /**
+   * Error to throw on set (for testing error handling)
+   */
+  setError: Error | null;
+  /**
+   * Error to throw on del (for testing error handling)
+   */
+  delError: Error | null;
+  constructor(options?: MemoryCacheProviderOptions);
   get(name: string, key: string): Promise<Uint8Array | undefined>;
   set(name: string, key: string, value: Uint8Array, ttl?: number): Promise<Uint8Array>;
   del(name: string, ...keys: string[]): Promise<void>;
   has(name: string, key: string): Promise<boolean>;
   keys(name: string, filter?: string): Promise<string[]>;
   clear(): Promise<void>;
+  incr(name: string, key: string, amount: number): Promise<number>;
+  /**
+   * Get cache statistics (hits, misses, sets, deletes).
+   *
+   * @example
+   * ```typescript
+   * expect(cache.stats().hits).toBe(1);
+   * expect(cache.stats().misses).toBe(0);
+   * ```
+   */
+  stats(): MemoryCacheStats;
+  /**
+   * Check if a key was set during the test.
+   *
+   * @example
+   * ```typescript
+   * expect(cache.wasSet("my-cache", "user:123")).toBe(true);
+   * ```
+   */
+  wasSet(name: string, key?: string): boolean;
+  /**
+   * Check if a key was retrieved during the test.
+   *
+   * @example
+   * ```typescript
+   * expect(cache.wasGet("my-cache", "user:123")).toBe(true);
+   * ```
+   */
+  wasGet(name: string, key?: string): boolean;
+  /**
+   * Check if a key was deleted during the test.
+   *
+   * @example
+   * ```typescript
+   * expect(cache.wasDeleted("my-cache", "user:123")).toBe(true);
+   * ```
+   */
+  wasDeleted(name: string, key?: string): boolean;
+  /**
+   * Get the number of cached entries for a specific cache name.
+   *
+   * @example
+   * ```typescript
+   * expect(cache.size("my-cache")).toBe(5);
+   * ```
+   */
+  size(name?: string): number;
+  /**
+   * Get all cache names.
+   *
+   * @example
+   * ```typescript
+   * expect(cache.names()).toContain("my-cache");
+   * ```
+   */
+  names(): string[];
+  /**
+   * Reset all in-memory state (useful between tests).
+   *
+   * @example
+   * ```typescript
+   * beforeEach(() => {
+   *   cache.reset();
+   * });
+   * ```
+   */
+  reset(): void;
 }
 //#endregion
 //#region ../../src/cache/core/index.d.ts
 /**
- * Provides high-performance caching capabilities for Alepha applications with configurable TTL and multiple storage backends.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | rare | stable |
+ *
+ * Type-safe caching with TTL support.
  *
- * The cache module enables declarative caching through the `$cache` primitive, allowing you to cache method results,
- * API responses, or computed values with automatic invalidation and type safety. It supports both in-memory and
- * persistent storage backends for different performance and durability requirements.
+ * **Features:**
+ * - Cached computations with type-safe keys and values
+ * - Configurable TTL
+ * - Cache invalidation
+ * - Automatic cache population
+ * - Providers: Memory (default), Redis
  *
- * @see {@link $cache}
- * @see {@link CacheProvider}
  * @module alepha.cache
  */
 declare const AlephaCache: alepha0.Service<alepha0.Module>;
 //#endregion
-export { $cache, AlephaCache, CachePrimitive, CachePrimitiveFn, CachePrimitiveOptions, CacheProvider, MemoryCacheProvider };
+export { $cache, AlephaCache, CachePrimitive, CachePrimitiveFn, CachePrimitiveOptions, CacheProvider, MemoryCacheCall, MemoryCacheDelCall, MemoryCacheProvider, MemoryCacheProviderOptions, MemoryCacheSetCall, MemoryCacheStats };
 //# sourceMappingURL=index.d.ts.map

package/dist/cache/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/cache/core/providers/CacheProvider.ts","../../../src/cache/core/primitives/$cache.ts","../../../src/cache/core/providers/MemoryCacheProvider.ts","../../../src/cache/core/index.ts"],"mappings":";;;;;;;AAMA;;;;;uBAAsB,aAAA;EAAA;;;;;;;;EAAA,SAAA,IAAA,IAAA,UAAA,GAAA,WAYjB,OAAA,CAAQ,UAAA;EAAA;;;;;;;;;;EAAA,SAAA,IAAA,IAAA,UAAA,GAAA,UAAA,KAAA,EAeF,UAAA,EAAA,GAAA,YAEN,OAAA,CAAQ,UAAA;EAAA;;;;;;EAAA,SAAA,IAAA,IAAA,aAAA,IAAA,aAQ2C,OAAA;EAAA,SAAA,IAAA,IAAA,UAAA,GAAA,WAEN,OAAA;EAAA,SAAA,KAAA,IAAA,UAAA,MAAA,YAEK,OAAA;EAAA;;;EAAA,SAAA,MAAA,GAK5B,OAAA;AAAA;;;;ACU3B;;;;;;;;;;AAgBA;;;;;;;;AAsDA;;;;;;;;;;;;;;;;;;;;;;;;;;AAmJA;;;cAzNa,MAAA;EAAA,qDAAA,OAAA,GACF,qBAAA,CAAsB,OAAA,EAAS,UAAA,IACvC,gBAAA,CAAiB,OAAA,EAAS,UAAA;EAAA;;UAcZ,qBAAA;EAAA;;;;;;;EAAA,IAAA;EAAA;;;EAAA,OAAA,OAAA,IAAA,EAgBK,UAAA,KAAe,OAAA;EAAA;;;;EAAA,GAAA,OAAA,IAAA,EAMnB,UAAA;EAAA;;;;EAAA,QAAA,GAML,iBAAA,CAAkB,aAAA;EAAA;;;;AA0B/B;;EA1B+B,GAAA,GAQvB,YAAA;EAAA;;AAkBR;EAlBQ,QAAA;AAAA;AAAA,cAkBK,cAAA,0DAGH,SAAA,CAAU,qBAAA,CAAsB,OAAA,EAAS,UAAA;EAAA,mBAAA,GAAA;IAAA,aAAA;IAAA,iBAAA;EAAA;EAAA,mBAAA,gBAAA,EAEd,gBAAA;EAAA,mBAAA,QAAA,EACR,aAAA;EAAA,UAAA,OAAA,EACR,WAAA;EAAA,UAAA,OAAA,EACA,WAAA;EAAA,UAAA,KAAA;IAAA,MAAA;IAAA,IAAA;IAAA,MAAA;EAAA;EAAA,IAAA,UAAA;EAAA,IAAA,GAAA,IAAA,EAcO,UAAA,GAAa,OAAA,CAAQ,OAAA;EAAA,IAAA,GAAA,IAAA,EAoB3B,UAAA;EAAA,WAAA,GAAA,IAAA,aAIwB,OAAA;EAAA,IAAA,GAAA,UAAA,KAAA,EAoBnC,OAAA,EAAA,GAAA,GACD,YAAA,GACL,OAAA;EAAA,IAAA,GAAA,WAe4B,OAAA,CAAQ,OAAA;EAAA,UAAA,SAAA,SAAA,CAAA,KAAA,EAiBH,OAAA,GAAU,UAAA;EAAA,UAAA,WAAA,SAAA,CAAA,UAAA,EAgBhC,UAAA,GACX,OAAA,CAAQ,OAAA;EAAA,UAAA,UAAA,GAiBY,aAAA;AAAA;AAAA,UAaR,gBAAA,0DAGP,cAAA,CAAe,OAAA,EAAS,UAAA;EAAA;;;EAAA,IAAA,IAAA,EAItB,UAAA,GAAa,OAAA,CAAQ,OAAA;AAAA;;;KCzR5B,SAAA;AAAA,KACA,QAAA;AAAA,KACA,UAAA;EAAA,IAAA,GACI,UAAA;EAAA,OAAA,GACG,OAAA;AAAA;AAAA,cAGC,mBAAA,YAA+B,aAAA;EAAA,mBAAA,gBAAA,EACP,gBAAA;EAAA,mBAAA,GAAA,EAAA,cAAA,CACb,MAAA;EAAA,UAAA,KAAA,EAEL,MAAA,CAAO,SAAA,EAAW,MAAA,CAAO,QAAA,EAAU,UAAA;EAAA,IAAA,IAAA,UAAA,GAAA,WAEP,OAAA,CAAQ,UAAA;EAAA,IAAA,IAAA,UAAA,GAAA,UAAA,KAAA,EAO5C,UAAA,EAAA,GAAA,YAEN,OAAA,CAAQ,UAAA;EAAA,IAAA,IAAA,aAAA,IAAA,aA0BwC,OAAA;EAAA,IAAA,IAAA,UAAA,GAAA,WAqCN,OAAA;EAAA,KAAA,IAAA,UAAA,MAAA,YAIK,OAAA;EAAA,MAAA,GAS5B,OAAA;AAAA;;;;AC/ExB;;;;;;;;;;cAAa,WAAA,EAAW,OAAA,CAAA,OAAA,CAUtB,OAAA,CAVsB,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/cache/core/providers/CacheProvider.ts","../../../src/cache/core/primitives/$cache.ts","../../../src/cache/core/providers/MemoryCacheProvider.ts","../../../src/cache/core/index.ts"],"mappings":"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"}

package/dist/cache/core/index.js

@@ -17,14 +17,95 @@ var CacheProvider = class {};
 
 //#endregion
 //#region ../../src/cache/core/providers/MemoryCacheProvider.ts
+/**
+* In-memory implementation of CacheProvider for testing.
+*
+* This provider stores all cache entries in memory, making it ideal for
+* unit tests that need to verify cache operations without touching Redis or other backends.
+*
+* @example
+* ```typescript
+* // In tests, substitute the real CacheProvider with MemoryCacheProvider
+* const alepha = Alepha.create().with({
+*   provide: CacheProvider,
+*   use: MemoryCacheProvider,
+* });
+*
+* // Run code that uses caching
+* const service = alepha.inject(MyService);
+* await service.fetchWithCache("key");
+*
+* // Verify cache behavior
+* const cache = alepha.inject(MemoryCacheProvider);
+* expect(cache.stats().misses).toBe(1);
+* await service.fetchWithCache("key");
+* expect(cache.stats().hits).toBe(1);
+* ```
+*/
 var MemoryCacheProvider = class {
 	dateTimeProvider = $inject(DateTimeProvider);
 	log = $logger();
 	store = {};
+	/**
+	* All recorded get calls.
+	*/
+	getCalls = [];
+	/**
+	* All recorded set calls.
+	*/
+	setCalls = [];
+	/**
+	* All recorded del calls.
+	*/
+	delCalls = [];
+	/**
+	* Cache statistics.
+	*/
+	_stats = {
+		hits: 0,
+		misses: 0,
+		sets: 0,
+		deletes: 0
+	};
+	/**
+	* Error to throw on get (for testing error handling)
+	*/
+	getError = null;
+	/**
+	* Error to throw on set (for testing error handling)
+	*/
+	setError = null;
+	/**
+	* Error to throw on del (for testing error handling)
+	*/
+	delError = null;
+	constructor(options = {}) {
+		this.getError = options.getError ?? null;
+		this.setError = options.setError ?? null;
+		this.delError = options.delError ?? null;
+	}
 	async get(name, key) {
-		return this.store[name]?.[key]?.data;
+		this.getCalls.push({
+			name,
+			key,
+			timestamp: Date.now()
+		});
+		if (this.getError) throw this.getError;
+		const data = this.store[name]?.[key]?.data;
+		if (data !== void 0) this._stats.hits++;
+		else this._stats.misses++;
+		return data;
 	}
 	async set(name, key, value, ttl) {
+		this.setCalls.push({
+			name,
+			key,
+			value,
+			ttl,
+			timestamp: Date.now()
+		});
+		this._stats.sets++;
+		if (this.setError) throw this.setError;
 		if (this.store[name] == null) this.store[name] = {};
 		this.store[name][key] ??= {};
 		this.store[name][key].data = value;
@@ -41,6 +122,13 @@ var MemoryCacheProvider = class {
 		return this.store[name][key].data;
 	}
 	async del(name, ...keys) {
+		this.delCalls.push({
+			name,
+			keys,
+			timestamp: Date.now()
+		});
+		this._stats.deletes++;
+		if (this.delError) throw this.delError;
 		if (keys.length === 0) {
 			this.log.debug(`Deleting all cache for name`, { name });
 			if (this.store[name]) for (const key of Object.keys(this.store[name])) {
@@ -79,6 +167,119 @@ var MemoryCacheProvider = class {
 		}
 		this.store = {};
 	}
+	async incr(name, key, amount) {
+		if (this.store[name] == null) this.store[name] = {};
+		const existing = this.store[name][key]?.data;
+		let current = 0;
+		if (existing) {
+			const str = new TextDecoder().decode(existing);
+			current = Number.parseInt(str, 10) || 0;
+		}
+		const newValue = current + amount;
+		this.store[name][key] ??= {};
+		this.store[name][key].data = new TextEncoder().encode(String(newValue));
+		return newValue;
+	}
+	/**
+	* Get cache statistics (hits, misses, sets, deletes).
+	*
+	* @example
+	* ```typescript
+	* expect(cache.stats().hits).toBe(1);
+	* expect(cache.stats().misses).toBe(0);
+	* ```
+	*/
+	stats() {
+		return { ...this._stats };
+	}
+	/**
+	* Check if a key was set during the test.
+	*
+	* @example
+	* ```typescript
+	* expect(cache.wasSet("my-cache", "user:123")).toBe(true);
+	* ```
+	*/
+	wasSet(name, key) {
+		if (key === void 0) return this.setCalls.some((call) => call.name === name);
+		return this.setCalls.some((call) => call.name === name && call.key === key);
+	}
+	/**
+	* Check if a key was retrieved during the test.
+	*
+	* @example
+	* ```typescript
+	* expect(cache.wasGet("my-cache", "user:123")).toBe(true);
+	* ```
+	*/
+	wasGet(name, key) {
+		if (key === void 0) return this.getCalls.some((call) => call.name === name);
+		return this.getCalls.some((call) => call.name === name && call.key === key);
+	}
+	/**
+	* Check if a key was deleted during the test.
+	*
+	* @example
+	* ```typescript
+	* expect(cache.wasDeleted("my-cache", "user:123")).toBe(true);
+	* ```
+	*/
+	wasDeleted(name, key) {
+		if (key === void 0) return this.delCalls.some((call) => call.name === name);
+		return this.delCalls.some((call) => call.name === name && call.keys.includes(key));
+	}
+	/**
+	* Get the number of cached entries for a specific cache name.
+	*
+	* @example
+	* ```typescript
+	* expect(cache.size("my-cache")).toBe(5);
+	* ```
+	*/
+	size(name) {
+		if (name === void 0) return Object.values(this.store).reduce((total, entries) => total + Object.keys(entries).length, 0);
+		return Object.keys(this.store[name] ?? {}).length;
+	}
+	/**
+	* Get all cache names.
+	*
+	* @example
+	* ```typescript
+	* expect(cache.names()).toContain("my-cache");
+	* ```
+	*/
+	names() {
+		return Object.keys(this.store);
+	}
+	/**
+	* Reset all in-memory state (useful between tests).
+	*
+	* @example
+	* ```typescript
+	* beforeEach(() => {
+	*   cache.reset();
+	* });
+	* ```
+	*/
+	reset() {
+		for (const name of Object.keys(this.store)) for (const key of Object.keys(this.store[name])) {
+			const timeout = this.store[name][key]?.timeout;
+			if (timeout) this.dateTimeProvider.clearTimeout(timeout);
+		}
+		this.store = {};
+		this.getCalls = [];
+		this.setCalls = [];
+		this.delCalls = [];
+		this._stats = {
+			hits: 0,
+			misses: 0,
+			sets: 0,
+			deletes: 0
+		};
+		this.getError = null;
+		this.setError = null;
+		this.delError = null;
+	}
 };
 
 //#endregion
@@ -211,14 +412,19 @@ $cache[KIND] = CachePrimitive;
 //#endregion
 //#region ../../src/cache/core/index.ts
 /**
-* Provides high-performance caching capabilities for Alepha applications with configurable TTL and multiple storage backends.
+* | type | quality | stability |
+* |------|---------|-----------|
+* | backend | rare | stable |
+*
+* Type-safe caching with TTL support.
 *
-* The cache module enables declarative caching through the `$cache` primitive, allowing you to cache method results,
-* API responses, or computed values with automatic invalidation and type safety. It supports both in-memory and
-* persistent storage backends for different performance and durability requirements.
+* **Features:**
+* - Cached computations with type-safe keys and values
+* - Configurable TTL
+* - Cache invalidation
+* - Automatic cache population
+* - Providers: Memory (default), Redis
 *
-* @see {@link $cache}
-* @see {@link CacheProvider}
 * @module alepha.cache
 */
 const AlephaCache = $module({