Enhancement/cache

.changeset/brown-mangos-rule.md

@@ -0,0 +1,8 @@
+---
+"@daiso-tech/core": minor
+---
+
+## Changes
+- Moved cache group logic from the <i>Cache</i> class into the adapters classes.  
+  - **Key Impact**: Each adapter is now required to implement the <i>getGroup</i> and <i>withGroup</i> methods.  
+  - This change enhances flexibility for adapter-specific logic.

package.json

@@ -74,8 +74,7 @@
         "typedoc-plugin-merge-modules": "^6.0.0",
         "typescript": "^5.5.4",
         "vite-tsconfig-paths": "^4.3.2",
-        "vitest": "^2.0.5",
-        "zod": "^3.24.1"
+        "vitest": "^3.0.2"
     },
     "peerDependencies": {
         "@libsql/client": "^0.4.1",
@@ -95,16 +94,11 @@
         },
         "@libsql/client": {
             "optional": true
-        },
-        "zod": {
-            "optional": true
         }
     },
     "dependencies": {
         "@libsql/kysely-libsql": "^0.4.0",
-        "escape-string-regexp": "^5.0.0",
         "kysely": "^0.27.0",
-        "superjson": "^2.2.0",
-        "zod": "^3.24.0"
+        "superjson": "^2.2.0"
     }
 }

src/cache/contracts/cache-adapter.contract.ts

@@ -2,7 +2,7 @@
  * @module Cache
  */
 
-import type { TimeSpan } from "@/utilities/_module";
+import type { OneOrMore, TimeSpan } from "@/utilities/_module";
 import {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     type TypeCacheError,
@@ -15,13 +15,18 @@ import {
  */
 export type ICacheAdapter<TType = unknown> = {
     /**
-     * The <i>get</i> returns the value of <i>keys</i> that are found otherwise null will be returned.
+     * The <i>exists</i> returns true if the <i>key</i> if exists otherwise false will be returned.
+     */
+    exists(key: string): PromiseLike<boolean>;
+
+    /**
+     * The <i>get</i> returns the <i>key</i> value if found otherwise null will be returned.
      */
     get(key: string): PromiseLike<TType | null>;
 
     /**
      * The <i>add</i> method add a new <i>key</i>. Returns true if the <i>key</i> where added otherwise false will be returned.
-     * You can provide a <i>ttl</i> value. If null is passed, the item will not expire.
+     * You must provide a <i>ttl</i> value. If null is passed, the item will not expire.
      */
     add(key: string, value: TType, ttl: TimeSpan | null): PromiseLike<boolean>;
 
@@ -31,8 +36,9 @@ export type ICacheAdapter<TType = unknown> = {
     update(key: string, value: TType): PromiseLike<boolean>;
 
     /**
-     * The <i>put</i> method replaces a <i>key</i> that exists or adds <i>key</i> that do not exists. Returns true if the <i>key</i> where updated otherwise false is returned.
-     * You can provide a <i>ttl</i> value. If null is passed, the item will not expire.
+     * The <i>put</i> method replaces a <i>key</i> if the <i>key</i> exists including the ttl value or adds <i>key</i> that do not exists with a given <i>ttl</i>.
+     * Returns true if the <i>key</i> where replaced otherwise false is returned.
+     * You must provide a <i>ttl</i> value. If null is passed, the item will not expire.
      */
     put(key: string, value: TType, ttl: TimeSpan | null): PromiseLike<boolean>;
 
@@ -52,5 +58,16 @@ export type ICacheAdapter<TType = unknown> = {
     /**
      * The <i>clear</i> method removes all keys that starts <i>prefix</i>.
      */
-    clear(prefix: string): PromiseLike<void>;
+    clear(): PromiseLike<void>;
+
+    /**
+     * The <i>getGroup</i> method returns the group name.
+     */
+    getGroup(): string;
+
+    /**
+     * The <i>withGroup</i> method returns a new <i>{@link ICacheAdapter}</i> instance that groups keys together.
+     * Only keys in the group can be updated, removed, or retrieved, leaving keys outside the group unaffected.
+     */
+    withGroup(group: OneOrMore<string>): ICacheAdapter<TType>;
 };

src/cache/contracts/cache-factory.contract.ts

@@ -42,7 +42,7 @@ export type ICacheFactory<TDrivers extends string = string, TType = unknown> = {
      * The <i>withTypes</i> method is used to set the value types of the cache.
      * @example
      * ```ts
-     * import { type ICacheFactory zodValidator } from "@daiso-tech/core";
+     * import { type ICacheFactory } from "@daiso-tech/core";
      *
      * async function main(cacheFactory: ICacheFactory): Promise<void> {
      *   await cacheFactory

src/cache/contracts/cache.contract.ts

@@ -120,13 +120,15 @@ export type ICache<TType = unknown> = ICacheListenable & {
     ): LazyPromise<Record<TKeys, boolean>>;
 
     /**
-     * The <i>put</i> method replaces the key with given <i>value</i> if found. If the <i>key</i> is not found it will just be added. True is returned if the key is found otherwise false will be returned.
-     * You can provide a <i>ttl</i> value. If null is passed, the item will not expire.
+     * The <i>put</i> method replaces a <i>key</i> if the <i>key</i> exists including the ttl value or adds <i>key</i> that do not exists with a given <i>ttl</i>.
+     * Returns true if the <i>key</i> where replaced otherwise false is returned.
+     * You must provide a <i>ttl</i> value. If null is passed, the item will not expire.
      */
     put(key: string, value: TType, ttl?: TimeSpan | null): LazyPromise<boolean>;
 
     /**
-     * The <i>putMany</i> method replaces the keys that exists. Adds keys that do not exists. Returns true for all the keys that where updated otherwise false is returned.
+     * The <i>putMany</i> method replaces the keys that exists including their ttl values or adds keys that do not exists.
+     * Returns true for all the keys that where replaced otherwise false is returned.
      */
     putMany<TKeys extends string>(
         values: Record<TKeys, WithTtlValue<TType>>,
@@ -187,18 +189,18 @@ export type ICache<TType = unknown> = ICacheListenable & {
     clear(): LazyPromise<void>;
 
     /**
-     * The <i>getGroup</i> method returns the complete group.
+     * The <i>getGroup</i> method returns the group name.
      * @example
      * ```ts
      * import type { ICache } from "@daiso-tech/core";
      *
      * async function main(cache: ICache) {
-     *   // Will be "@root"
+     *   // Will be "@global"
      *   console.log(cache.getGroup())
      *
      *   const cacheA = cache.withGroup("a");
      *
-     *   // Will be "@root/a"
+     *   // Will be "@global/a"
      *   console.log(cacheA.getGroup())
      * }
      * ```
@@ -213,7 +215,8 @@ export type ICache<TType = unknown> = ICacheListenable & {
  */
 export type IGroupableCache<TType = unknown> = ICache<TType> & {
     /**
-     * The <i>withGroup</i> method returns new instance of <i>{@link ICache}</i> where all the keys will be prefixed with a given <i>group</i>.
+     * The <i>withGroup</i> method returns a new <i>{@link ICache}</i> instance that groups keys together.
+     * Only keys in the group can be updated, removed, or retrieved, leaving keys outside the group unaffected.
      * This useful for multitennat applications.
      * @example
      * ```ts

src/cache/contracts/cache.events.ts

@@ -3,49 +3,43 @@
  */
 
 import type { TimeSpan } from "@/utilities/_module";
-import type { ICacheAdapter } from "@/cache/contracts/cache-adapter.contract";
-
-/**
- * @group Events
- */
-export type CacheEvent = {
-    group: string;
-    adapter: ICacheAdapter<any>;
-};
-
-/**
- * This event will be triggered when cache is cleared.
- * @group Events
- */
-export type KeysClearedCacheEvent = CacheEvent & {};
 
 export type CacheEvents<TType = unknown> = {
-    key_found: CacheEvent & {
+    key_found: {
+        group: string;
         key: string;
         value: TType;
     };
-    key_not_found: CacheEvent & {
+    key_not_found: {
+        group: string;
         key: string;
     };
-    key_added: CacheEvent & {
+    key_added: {
+        group: string;
         key: string;
         value: TType;
         ttl: TimeSpan | null;
     };
-    key_updated: CacheEvent & {
+    key_updated: {
+        group: string;
         key: string;
         value: TType;
     };
-    key_removed: CacheEvent & {
+    key_removed: {
+        group: string;
         key: string;
     };
-    key_incremented: CacheEvent & {
+    key_incremented: {
+        group: string;
         key: string;
         value: number;
     };
-    key_decremented: CacheEvent & {
+    key_decremented: {
+        group: string;
         key: string;
         value: number;
     };
-    keys_cleared: CacheEvent;
+    keys_cleared: {
+        group: string;
+    };
 };