@md-oss/cache 0.1.0

package/dist/types.d.cts

@@ -0,0 +1,60 @@
+import EventEmitter from 'node:events';
+import { CreateCacheOptions, Events } from 'cache-manager';
+import Keyv from 'keyv';
+
+type AbstractCache<T> = {
+    get: (key: string) => Promise<T | null | undefined>;
+    mget: (keys: string[]) => Promise<(T | null | undefined)[]>;
+    ttl: (key: string) => Promise<number | null>;
+    set: (key: string, value: T | null, ttl?: number) => Promise<T | null>;
+    mset: (list: SetCacheArguments<T | null>[]) => Promise<SetCacheArguments<T | null>[]>;
+    del: (key: string) => Promise<boolean>;
+    mdel: (keys: string[]) => Promise<[boolean, boolean[]]>;
+    clear: () => Promise<boolean>;
+    wrap: (key: string, fnc: () => T | Promise<T>, ttl?: number | ((value: T) => number), refreshThreshold?: number) => Promise<T>;
+    on: <E extends keyof Events>(event: E, listener: Events[E]) => EventEmitter;
+    off: <E extends keyof Events>(event: E, listener: Events[E]) => EventEmitter;
+    disconnect: () => Promise<undefined>;
+};
+type ResolvedCreateCacheOptions<T extends NonNullable<unknown>> = Omit<CreateCacheOptions, 'stores'> & {
+    stores: Keyv<T>[];
+};
+type SetCacheArguments<T> = {
+    key: string;
+    value: T;
+    ttl?: number;
+};
+type CacheManagerMetadata = {
+    hits: number;
+    misses: number;
+    added: number;
+    deleted: number;
+    updated: number;
+    cleared: number;
+};
+type WithCacheSource = 'cache' | 'no-cache';
+type WithCacheDetails = {
+    source: WithCacheSource;
+    cached: boolean;
+    /**
+     * - If `cached` is `true`, the time in milliseconds the data was cached for
+     * - If `cached` is `false`, the remaining time in milliseconds until the cache expires
+     */
+    cachedFor: number | null;
+};
+type WithCacheDataFn<K, T, O = undefined> = O extends undefined ? (key: K) => T | null | undefined | Promise<T | null | undefined> : (key: K) => T | O | null | undefined | Promise<T | O | null | undefined>;
+type WithCacheValidator<T, O> = (item: T | O) => item is T;
+type WithCacheTransformer<T, O> = (item: T | O, details: WithCacheDetails) => O extends undefined ? T : T | O;
+type WithCacheReturnType<T extends NonNullable<unknown>> = [
+    T | null | undefined,
+    WithCacheDetails
+];
+type WithCacheOptions<K, T, O = undefined> = {
+    key: K;
+    dataFunction: WithCacheDataFn<K, T, O>;
+    validationFunction?: WithCacheValidator<T | null | undefined, O>;
+    transformFunction?: WithCacheTransformer<T | null | undefined, O>;
+    ttl?: number;
+};
+
+export type { AbstractCache, CacheManagerMetadata, ResolvedCreateCacheOptions, SetCacheArguments, WithCacheDataFn, WithCacheDetails, WithCacheOptions, WithCacheReturnType, WithCacheSource, WithCacheTransformer, WithCacheValidator };

package/dist/types.d.mts

@@ -0,0 +1,60 @@
+import EventEmitter from 'node:events';
+import { CreateCacheOptions, Events } from 'cache-manager';
+import Keyv from 'keyv';
+
+type AbstractCache<T> = {
+    get: (key: string) => Promise<T | null | undefined>;
+    mget: (keys: string[]) => Promise<(T | null | undefined)[]>;
+    ttl: (key: string) => Promise<number | null>;
+    set: (key: string, value: T | null, ttl?: number) => Promise<T | null>;
+    mset: (list: SetCacheArguments<T | null>[]) => Promise<SetCacheArguments<T | null>[]>;
+    del: (key: string) => Promise<boolean>;
+    mdel: (keys: string[]) => Promise<[boolean, boolean[]]>;
+    clear: () => Promise<boolean>;
+    wrap: (key: string, fnc: () => T | Promise<T>, ttl?: number | ((value: T) => number), refreshThreshold?: number) => Promise<T>;
+    on: <E extends keyof Events>(event: E, listener: Events[E]) => EventEmitter;
+    off: <E extends keyof Events>(event: E, listener: Events[E]) => EventEmitter;
+    disconnect: () => Promise<undefined>;
+};
+type ResolvedCreateCacheOptions<T extends NonNullable<unknown>> = Omit<CreateCacheOptions, 'stores'> & {
+    stores: Keyv<T>[];
+};
+type SetCacheArguments<T> = {
+    key: string;
+    value: T;
+    ttl?: number;
+};
+type CacheManagerMetadata = {
+    hits: number;
+    misses: number;
+    added: number;
+    deleted: number;
+    updated: number;
+    cleared: number;
+};
+type WithCacheSource = 'cache' | 'no-cache';
+type WithCacheDetails = {
+    source: WithCacheSource;
+    cached: boolean;
+    /**
+     * - If `cached` is `true`, the time in milliseconds the data was cached for
+     * - If `cached` is `false`, the remaining time in milliseconds until the cache expires
+     */
+    cachedFor: number | null;
+};
+type WithCacheDataFn<K, T, O = undefined> = O extends undefined ? (key: K) => T | null | undefined | Promise<T | null | undefined> : (key: K) => T | O | null | undefined | Promise<T | O | null | undefined>;
+type WithCacheValidator<T, O> = (item: T | O) => item is T;
+type WithCacheTransformer<T, O> = (item: T | O, details: WithCacheDetails) => O extends undefined ? T : T | O;
+type WithCacheReturnType<T extends NonNullable<unknown>> = [
+    T | null | undefined,
+    WithCacheDetails
+];
+type WithCacheOptions<K, T, O = undefined> = {
+    key: K;
+    dataFunction: WithCacheDataFn<K, T, O>;
+    validationFunction?: WithCacheValidator<T | null | undefined, O>;
+    transformFunction?: WithCacheTransformer<T | null | undefined, O>;
+    ttl?: number;
+};
+
+export type { AbstractCache, CacheManagerMetadata, ResolvedCreateCacheOptions, SetCacheArguments, WithCacheDataFn, WithCacheDetails, WithCacheOptions, WithCacheReturnType, WithCacheSource, WithCacheTransformer, WithCacheValidator };

package/package.json

@@ -0,0 +1,127 @@
+{
+  "name": "@md-oss/cache",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/Mirasaki-OSS/monorepo-template.git",
+    "directory": "vendor/cache"
+  },
+  "type": "module",
+  "description": "Multi-layer caching with LRU, Redis, and async data fetching support",
+  "license": "ISC",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    },
+    "./async": {
+      "require": {
+        "types": "./dist/async.d.cts",
+        "default": "./dist/async.cjs"
+      },
+      "import": {
+        "types": "./dist/async.d.mts",
+        "default": "./dist/async.mjs"
+      }
+    },
+    "./env": {
+      "require": {
+        "types": "./dist/env.d.cts",
+        "default": "./dist/env.cjs"
+      },
+      "import": {
+        "types": "./dist/env.d.mts",
+        "default": "./dist/env.mjs"
+      }
+    },
+    "./lru": {
+      "require": {
+        "types": "./dist/lru.d.cts",
+        "default": "./dist/lru.cjs"
+      },
+      "import": {
+        "types": "./dist/lru.d.mts",
+        "default": "./dist/lru.mjs"
+      }
+    },
+    "./manager": {
+      "require": {
+        "types": "./dist/manager.d.cts",
+        "default": "./dist/manager.cjs"
+      },
+      "import": {
+        "types": "./dist/manager.d.mts",
+        "default": "./dist/manager.mjs"
+      }
+    },
+    "./promise": {
+      "require": {
+        "types": "./dist/promise.d.cts",
+        "default": "./dist/promise.cjs"
+      },
+      "import": {
+        "types": "./dist/promise.d.mts",
+        "default": "./dist/promise.mjs"
+      }
+    },
+    "./redis-client": {
+      "require": {
+        "types": "./dist/redis-client.d.cts",
+        "default": "./dist/redis-client.cjs"
+      },
+      "import": {
+        "types": "./dist/redis-client.d.mts",
+        "default": "./dist/redis-client.mjs"
+      }
+    },
+    "./types": {
+      "require": {
+        "types": "./dist/types.d.cts"
+      },
+      "import": {
+        "types": "./dist/types.d.mts"
+      }
+    }
+  },
+  "dependencies": {
+    "@t3-oss/env-nextjs": "^0.13.10",
+    "@types/debug": "^4.1.12",
+    "cache-manager": "^7.2.8",
+    "debug": "^4.4.3",
+    "keyv": "^5.6.0",
+    "lru-cache": "^11.2.5",
+    "redis": "^5.10.0",
+    "zod": "^4.3.6",
+    "@md-oss/config": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "pkgroll": "^2.21.5",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "pkgroll --minify --clean-dist --sourcemap  --define.process.env.NODE_ENV='\"production\"' --define.DEBUG=false",
+    "clean": "git clean -xdf .turbo dist node_modules tsconfig.tsbuildinfo",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}