@geekmidas/cache 0.2.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @geekmidas/cache
+
+## 1.1.0
+
+### Minor Changes
+
+- ✨ [`be4f7a9`](https://github.com/geekmidas/toolbox/commit/be4f7a9bd5de7f08adbca582916d6902e0c24de2) Thanks [@geekmidas](https://github.com/geekmidas)! - Add partition support for manifest generation. Users can now group constructs (routes, functions, crons, subscribers) into named partitions by providing a `partition` callback per construct type in the config. Manifests output partitioned fields as `Record<string, T[]>` while remaining flat `T[]` arrays when no partitions are configured.
+
+  Fix mutation type inference in endpoint hooks by using `UseMutationResult` and `UseQueryResult` types directly instead of `ReturnType<typeof useMutation>`, which could resolve to `never` for complex path definitions.
+
+  Add `FileCache` implementation that persists cache entries to a JSON file on disk. Default location is `process.cwd()/.gkm/cache.json`. Uses an in-process mutex combined with `proper-lockfile` for safe concurrent and cross-process writes.
+
+## 1.0.0
+
+### Major Changes
+
+- [`ff7b115`](https://github.com/geekmidas/toolbox/commit/ff7b11599f60f84ac6cdc73714c853ecf786b2e8) Thanks [@geekmidas](https://github.com/geekmidas)! - Version 1 Stable release

package/README.md

@@ -6,7 +6,7 @@ A type-safe, flexible caching library for TypeScript applications with support f
 
 - **Type-safe**: Full TypeScript support with generics for strongly-typed cache values
 - **Unified interface**: Common `Cache<T>` interface for all implementations
-- **Multiple backends**: In-memory, Redis (Upstash), and Expo Secure Store implementations
+- **Multiple backends**: In-memory, Redis (Upstash), Expo Secure Store, and file-based implementations
 - **Async API**: Promise-based interface for consistency across implementations
 - **Flexible TTL**: Support for time-to-live across all implementations
 - **Easy testing**: Simple interface makes mocking and testing straightforward
@@ -31,6 +31,8 @@ For React Native support via Expo:
 npm install expo-secure-store
 ```
 
+The file-based cache includes all required dependencies automatically.
+
 ## Quick Start
 
 ### In-Memory Cache
@@ -77,6 +79,35 @@ const user = await cache.get('user:123'); // User | undefined
 await cache.delete('user:123');
 ```
 
+### File Cache
+
+Persistent file-based cache for CLI tools and build systems. Data is stored as JSON on disk and survives process restarts:
+
+```typescript
+import { FileCache } from '@geekmidas/cache/file';
+
+// Default path: process.cwd()/.gkm/cache.json
+const cache = new FileCache();
+
+// Custom path and TTL
+const cache = new FileCache({
+  path: '/tmp/my-app/cache.json',
+  ttl: 3600, // 1 hour default TTL
+});
+
+// Set a value with TTL (in seconds)
+await cache.set('build:hash', 'abc123', 300);
+
+// Get a value
+const hash = await cache.get('build:hash'); // string | undefined
+
+// Check remaining TTL
+const remaining = await cache.ttl('build:hash'); // seconds
+
+// Delete a value
+await cache.delete('build:hash');
+```
+
 ## API Reference
 
 ### Cache Interface
@@ -214,6 +245,44 @@ await cache.set('user:1', {
 const user = await cache.get('user:1');
 ```
 
+### FileCache
+
+Persistent file-based cache that stores entries as JSON on disk.
+
+```typescript
+import { FileCache } from '@geekmidas/cache/file';
+
+class FileCache implements Cache
+```
+
+#### Constructor
+
+```typescript
+new FileCache(options?: FileCacheOptions)
+```
+
+- `path`: Path to the cache JSON file (default: `process.cwd()/.gkm/cache.json`)
+- `ttl`: Default TTL in seconds (default: `600`)
+
+#### Features
+
+- ✅ Persistent storage across process restarts
+- ✅ TTL support with automatic expiration
+- ✅ Safe concurrent writes (in-process mutex + cross-process file locking)
+- ✅ Auto-creates parent directories
+- ✅ No external services required
+- ❌ Not suitable for high-throughput applications
+- ❌ Not suitable for multi-machine distributed caching
+
+#### Example
+
+```typescript
+const cache = new FileCache({ path: '/tmp/app-cache.json', ttl: 3600 });
+await cache.set('config', { theme: 'dark' });
+const config = await cache.get('config'); // { theme: 'dark' }
+const remaining = await cache.ttl('config'); // ~3600
+```
+
 ### ExpoSecureCache
 
 Secure storage for React Native apps using Expo SecureStore.
@@ -347,11 +416,15 @@ Create cache instances based on configuration:
 
 ```typescript
 interface CacheConfig {
-  type: 'memory' | 'redis' | 'expo';
+  type: 'memory' | 'redis' | 'file' | 'expo';
   redis?: {
     url: string;
     token: string;
   };
+  file?: {
+    path?: string;
+    ttl?: number;
+  };
 }
 
 function createCache<T>(config: CacheConfig): Cache<T> {
@@ -361,6 +434,8 @@ function createCache<T>(config: CacheConfig): Cache<T> {
     case 'redis':
       if (!config.redis) throw new Error('Redis config required');
       return new UpstashCache<T>(config.redis.url, config.redis.token);
+    case 'file':
+      return new FileCache(config.file);
     case 'expo':
       return new ExpoSecureCache<T>();
     default:
@@ -478,6 +553,11 @@ describe('UserService', () => {
 - **Cons**: Network latency, external dependency
 - **Best for**: Production, multi-instance apps, shared cache
 
+### FileCache
+- **Pros**: Persistent, no external services, cross-process safe
+- **Cons**: Disk I/O latency, not suitable for high throughput
+- **Best for**: CLI tools, build systems, local development caching
+
 ### ExpoSecureCache
 - **Pros**: Secure, encrypted, persistent on device
 - **Cons**: React Native only, storage limits, slower operations

package/dist/file.cjs

@@ -0,0 +1,101 @@
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+const require_src = require('./src-zfYb7mdS.cjs');
+const date_fns = require_chunk.__toESM(require("date-fns"));
+const node_fs = require_chunk.__toESM(require("node:fs"));
+const node_fs_promises = require_chunk.__toESM(require("node:fs/promises"));
+const node_path = require_chunk.__toESM(require("node:path"));
+const proper_lockfile = require_chunk.__toESM(require("proper-lockfile"));
+
+//#region src/file.ts
+var FileCache = class {
+	path;
+	defaultTtl;
+	/** In-process mutex to serialize concurrent writes within the same process. */
+	mutex = Promise.resolve();
+	constructor(options = {}) {
+		this.path = options.path ?? (0, node_path.join)(process.cwd(), ".gkm", "cache.json");
+		this.defaultTtl = options.ttl ?? 600;
+	}
+	async get(key) {
+		const data = await this.readData();
+		const entry = data[key];
+		if (!entry) return void 0;
+		const remaining = require_src.getExpirationInSeconds(entry.expiresAt);
+		if (remaining <= 0) {
+			await this.withLock(async (current) => {
+				delete current[key];
+				return current;
+			});
+			return void 0;
+		}
+		return entry.value;
+	}
+	async set(key, value, ttl) {
+		const seconds = ttl ?? this.defaultTtl;
+		const expiresAt = (0, date_fns.addSeconds)(/* @__PURE__ */ new Date(), seconds).toISOString();
+		await this.withLock(async (data) => {
+			data[key] = {
+				value,
+				expiresAt
+			};
+			return data;
+		});
+	}
+	async delete(key) {
+		await this.withLock(async (data) => {
+			delete data[key];
+			return data;
+		});
+	}
+	async ttl(key) {
+		const data = await this.readData();
+		const entry = data[key];
+		if (!entry) return 0;
+		return require_src.getExpirationInSeconds(entry.expiresAt);
+	}
+	async readData() {
+		try {
+			const content = await (0, node_fs_promises.readFile)(this.path, "utf-8");
+			return JSON.parse(content);
+		} catch {
+			return {};
+		}
+	}
+	async ensureDir() {
+		const dir = (0, node_path.dirname)(this.path);
+		if (!(0, node_fs.existsSync)(dir)) await (0, node_fs_promises.mkdir)(dir, { recursive: true });
+	}
+	async withLock(fn) {
+		const prev = this.mutex;
+		let resolve;
+		this.mutex = new Promise((r) => {
+			resolve = r;
+		});
+		try {
+			await prev;
+			await this.ensureDir();
+			if (!(0, node_fs.existsSync)(this.path)) await (0, node_fs_promises.writeFile)(this.path, "{}");
+			const release = await proper_lockfile.default.lock(this.path, {
+				retries: {
+					retries: 3,
+					minTimeout: 100,
+					maxTimeout: 1e3
+				},
+				stale: 1e4
+			});
+			try {
+				const data = await this.readData();
+				const updated = await fn(data);
+				await (0, node_fs_promises.writeFile)(this.path, JSON.stringify(updated, null, 2));
+			} finally {
+				await release();
+			}
+		} finally {
+			resolve();
+		}
+	}
+};
+
+//#endregion
+exports.FileCache = FileCache;
+//# sourceMappingURL=file.cjs.map

package/dist/file.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.cjs","names":["options: FileCacheOptions","key: string","value: T","ttl?: number","fn: (data: FileCacheData) => Promise<FileCacheData>","resolve: () => void"],"sources":["../src/file.ts"],"sourcesContent":["import { existsSync } from 'node:fs';\nimport { mkdir, readFile, writeFile } from 'node:fs/promises';\nimport { dirname, join } from 'node:path';\nimport { addSeconds } from 'date-fns';\nimport lockfile from 'proper-lockfile';\nimport { type Cache, getExpirationInSeconds } from './';\n\ninterface FileCacheEntry {\n\tvalue: unknown;\n\texpiresAt: string;\n}\n\ntype FileCacheData = Record<string, FileCacheEntry>;\n\nexport interface FileCacheOptions {\n\t/** Path to the cache JSON file. Default: `process.cwd()/.gkm/cache.json` */\n\tpath?: string;\n\t/** Default TTL in seconds. Default: 600 */\n\tttl?: number;\n}\n\nexport class FileCache implements Cache {\n\tprivate readonly path: string;\n\tprivate readonly defaultTtl: number;\n\t/** In-process mutex to serialize concurrent writes within the same process. */\n\tprivate mutex: Promise<void> = Promise.resolve();\n\n\tconstructor(options: FileCacheOptions = {}) {\n\t\tthis.path = options.path ?? join(process.cwd(), '.gkm', 'cache.json');\n\t\tthis.defaultTtl = options.ttl ?? 600;\n\t}\n\n\tasync get<T>(key: string): Promise<T | undefined> {\n\t\tconst data = await this.readData();\n\t\tconst entry = data[key];\n\t\tif (!entry) return undefined;\n\n\t\tconst remaining = getExpirationInSeconds(entry.expiresAt);\n\t\tif (remaining <= 0) {\n\t\t\tawait this.withLock(async (current) => {\n\t\t\t\tdelete current[key];\n\t\t\t\treturn current;\n\t\t\t});\n\t\t\treturn undefined;\n\t\t}\n\n\t\treturn entry.value as T;\n\t}\n\n\tasync set<T>(key: string, value: T, ttl?: number): Promise<void> {\n\t\tconst seconds = ttl ?? this.defaultTtl;\n\t\tconst expiresAt = addSeconds(new Date(), seconds).toISOString();\n\n\t\tawait this.withLock(async (data) => {\n\t\t\tdata[key] = { value, expiresAt };\n\t\t\treturn data;\n\t\t});\n\t}\n\n\tasync delete(key: string): Promise<void> {\n\t\tawait this.withLock(async (data) => {\n\t\t\tdelete data[key];\n\t\t\treturn data;\n\t\t});\n\t}\n\n\tasync ttl(key: string): Promise<number> {\n\t\tconst data = await this.readData();\n\t\tconst entry = data[key];\n\t\tif (!entry) return 0;\n\n\t\treturn getExpirationInSeconds(entry.expiresAt);\n\t}\n\n\tprivate async readData(): Promise<FileCacheData> {\n\t\ttry {\n\t\t\tconst content = await readFile(this.path, 'utf-8');\n\t\t\treturn JSON.parse(content) as FileCacheData;\n\t\t} catch {\n\t\t\treturn {};\n\t\t}\n\t}\n\n\tprivate async ensureDir(): Promise<void> {\n\t\tconst dir = dirname(this.path);\n\t\tif (!existsSync(dir)) {\n\t\t\tawait mkdir(dir, { recursive: true });\n\t\t}\n\t}\n\n\tprivate async withLock(\n\t\tfn: (data: FileCacheData) => Promise<FileCacheData>,\n\t): Promise<void> {\n\t\t// Queue behind any pending in-process operations\n\t\tconst prev = this.mutex;\n\t\tlet resolve: () => void;\n\t\tthis.mutex = new Promise<void>((r) => {\n\t\t\tresolve = r;\n\t\t});\n\n\t\ttry {\n\t\t\tawait prev;\n\t\t\tawait this.ensureDir();\n\n\t\t\t// Ensure file exists before locking (proper-lockfile requires it)\n\t\t\tif (!existsSync(this.path)) {\n\t\t\t\tawait writeFile(this.path, '{}');\n\t\t\t}\n\n\t\t\tconst release = await lockfile.lock(this.path, {\n\t\t\t\tretries: { retries: 3, minTimeout: 100, maxTimeout: 1000 },\n\t\t\t\tstale: 10000,\n\t\t\t});\n\n\t\t\ttry {\n\t\t\t\tconst data = await this.readData();\n\t\t\t\tconst updated = await fn(data);\n\t\t\t\tawait writeFile(this.path, JSON.stringify(updated, null, 2));\n\t\t\t} finally {\n\t\t\t\tawait release();\n\t\t\t}\n\t\t} finally {\n\t\t\tresolve!();\n\t\t}\n\t}\n}\n"],"mappings":";;;;;;;;;AAqBA,IAAa,YAAb,MAAwC;CACvC,AAAiB;CACjB,AAAiB;;CAEjB,AAAQ,QAAuB,QAAQ,SAAS;CAEhD,YAAYA,UAA4B,CAAE,GAAE;AAC3C,OAAK,OAAO,QAAQ,QAAQ,oBAAK,QAAQ,KAAK,EAAE,QAAQ,aAAa;AACrE,OAAK,aAAa,QAAQ,OAAO;CACjC;CAED,MAAM,IAAOC,KAAqC;EACjD,MAAM,OAAO,MAAM,KAAK,UAAU;EAClC,MAAM,QAAQ,KAAK;AACnB,OAAK,MAAO;EAEZ,MAAM,YAAY,mCAAuB,MAAM,UAAU;AACzD,MAAI,aAAa,GAAG;AACnB,SAAM,KAAK,SAAS,OAAO,YAAY;AACtC,WAAO,QAAQ;AACf,WAAO;GACP,EAAC;AACF;EACA;AAED,SAAO,MAAM;CACb;CAED,MAAM,IAAOA,KAAaC,OAAUC,KAA6B;EAChE,MAAM,UAAU,OAAO,KAAK;EAC5B,MAAM,YAAY,yCAAW,IAAI,QAAQ,QAAQ,CAAC,aAAa;AAE/D,QAAM,KAAK,SAAS,OAAO,SAAS;AACnC,QAAK,OAAO;IAAE;IAAO;GAAW;AAChC,UAAO;EACP,EAAC;CACF;CAED,MAAM,OAAOF,KAA4B;AACxC,QAAM,KAAK,SAAS,OAAO,SAAS;AACnC,UAAO,KAAK;AACZ,UAAO;EACP,EAAC;CACF;CAED,MAAM,IAAIA,KAA8B;EACvC,MAAM,OAAO,MAAM,KAAK,UAAU;EAClC,MAAM,QAAQ,KAAK;AACnB,OAAK,MAAO,QAAO;AAEnB,SAAO,mCAAuB,MAAM,UAAU;CAC9C;CAED,MAAc,WAAmC;AAChD,MAAI;GACH,MAAM,UAAU,MAAM,+BAAS,KAAK,MAAM,QAAQ;AAClD,UAAO,KAAK,MAAM,QAAQ;EAC1B,QAAO;AACP,UAAO,CAAE;EACT;CACD;CAED,MAAc,YAA2B;EACxC,MAAM,MAAM,uBAAQ,KAAK,KAAK;AAC9B,OAAK,wBAAW,IAAI,CACnB,OAAM,4BAAM,KAAK,EAAE,WAAW,KAAM,EAAC;CAEtC;CAED,MAAc,SACbG,IACgB;EAEhB,MAAM,OAAO,KAAK;EAClB,IAAIC;AACJ,OAAK,QAAQ,IAAI,QAAc,CAAC,MAAM;AACrC,aAAU;EACV;AAED,MAAI;AACH,SAAM;AACN,SAAM,KAAK,WAAW;AAGtB,QAAK,wBAAW,KAAK,KAAK,CACzB,OAAM,gCAAU,KAAK,MAAM,KAAK;GAGjC,MAAM,UAAU,MAAM,wBAAS,KAAK,KAAK,MAAM;IAC9C,SAAS;KAAE,SAAS;KAAG,YAAY;KAAK,YAAY;IAAM;IAC1D,OAAO;GACP,EAAC;AAEF,OAAI;IACH,MAAM,OAAO,MAAM,KAAK,UAAU;IAClC,MAAM,UAAU,MAAM,GAAG,KAAK;AAC9B,UAAM,gCAAU,KAAK,MAAM,KAAK,UAAU,SAAS,MAAM,EAAE,CAAC;GAC5D,UAAS;AACT,UAAM,SAAS;GACf;EACD,UAAS;AACT,YAAU;EACV;CACD;AACD"}

package/dist/file.d.cts

@@ -0,0 +1,27 @@
+import { Cache } from "./index-BSYYdwRm.cjs";
+
+//#region src/file.d.ts
+interface FileCacheOptions {
+  /** Path to the cache JSON file. Default: `process.cwd()/.gkm/cache.json` */
+  path?: string;
+  /** Default TTL in seconds. Default: 600 */
+  ttl?: number;
+}
+declare class FileCache implements Cache {
+  private readonly path;
+  private readonly defaultTtl;
+  /** In-process mutex to serialize concurrent writes within the same process. */
+  private mutex;
+  constructor(options?: FileCacheOptions);
+  get<T>(key: string): Promise<T | undefined>;
+  set<T>(key: string, value: T, ttl?: number): Promise<void>;
+  delete(key: string): Promise<void>;
+  ttl(key: string): Promise<number>;
+  private readData;
+  private ensureDir;
+  private withLock;
+}
+//# sourceMappingURL=file.d.ts.map
+//#endregion
+export { FileCache, FileCacheOptions };
+//# sourceMappingURL=file.d.cts.map

package/dist/file.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.cts","names":[],"sources":["../src/file.ts"],"sourcesContent":[],"mappings":";;;UAciB,gBAAA;;EAAA,IAAA,CAAA,EAAA,MAAA;EAOJ;EAAU,GAAA,CAAA,EAAA,MAAA;;AAWa,cAXvB,SAAA,YAAqB,KAWE,CAAA;EAAC,iBAAT,IAAA;EAAO,iBAiBD,UAAA;EAAC;EAAwB,QAU/B,KAAA;EAAO,WAOV,CAAA,OAAA,CAAA,EAvCH,gBAuCG;EAAO,GA7CE,CAAA,CAAA,CAAA,CAAA,GAAA,EAAA,MAAA,CAAA,EAWN,OAXM,CAWE,CAXF,GAAA,SAAA,CAAA;EAAK,GAAA,CAAA,CAAA,CAAA,CAAA,GAAA,EAAA,MAAA,EAAA,KAAA,EA4BL,CA5BK,EAAA,GAAA,CAAA,EAAA,MAAA,CAAA,EA4Ba,OA5Bb,CAAA,IAAA,CAAA;uBAsCX;oBAOH"}

package/dist/file.d.mts

@@ -0,0 +1,27 @@
+import { Cache } from "./index-Dx96gr-9.mjs";
+
+//#region src/file.d.ts
+interface FileCacheOptions {
+  /** Path to the cache JSON file. Default: `process.cwd()/.gkm/cache.json` */
+  path?: string;
+  /** Default TTL in seconds. Default: 600 */
+  ttl?: number;
+}
+declare class FileCache implements Cache {
+  private readonly path;
+  private readonly defaultTtl;
+  /** In-process mutex to serialize concurrent writes within the same process. */
+  private mutex;
+  constructor(options?: FileCacheOptions);
+  get<T>(key: string): Promise<T | undefined>;
+  set<T>(key: string, value: T, ttl?: number): Promise<void>;
+  delete(key: string): Promise<void>;
+  ttl(key: string): Promise<number>;
+  private readData;
+  private ensureDir;
+  private withLock;
+}
+//# sourceMappingURL=file.d.ts.map
+//#endregion
+export { FileCache, FileCacheOptions };
+//# sourceMappingURL=file.d.mts.map

package/dist/file.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.mts","names":[],"sources":["../src/file.ts"],"sourcesContent":[],"mappings":";;;UAciB,gBAAA;;EAAA,IAAA,CAAA,EAAA,MAAA;EAOJ;EAAU,GAAA,CAAA,EAAA,MAAA;;AAWa,cAXvB,SAAA,YAAqB,KAWE,CAAA;EAAC,iBAAT,IAAA;EAAO,iBAiBD,UAAA;EAAC;EAAwB,QAU/B,KAAA;EAAO,WAOV,CAAA,OAAA,CAAA,EAvCH,gBAuCG;EAAO,GA7CE,CAAA,CAAA,CAAA,CAAA,GAAA,EAAA,MAAA,CAAA,EAWN,OAXM,CAWE,CAXF,GAAA,SAAA,CAAA;EAAK,GAAA,CAAA,CAAA,CAAA,CAAA,GAAA,EAAA,MAAA,EAAA,KAAA,EA4BL,CA5BK,EAAA,GAAA,CAAA,EAAA,MAAA,CAAA,EA4Ba,OA5Bb,CAAA,IAAA,CAAA;uBAsCX;oBAOH"}

package/dist/file.mjs

@@ -0,0 +1,100 @@
+import { getExpirationInSeconds } from "./src-CrE4Nl5T.mjs";
+import { addSeconds } from "date-fns";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import lockfile from "proper-lockfile";
+
+//#region src/file.ts
+var FileCache = class {
+	path;
+	defaultTtl;
+	/** In-process mutex to serialize concurrent writes within the same process. */
+	mutex = Promise.resolve();
+	constructor(options = {}) {
+		this.path = options.path ?? join(process.cwd(), ".gkm", "cache.json");
+		this.defaultTtl = options.ttl ?? 600;
+	}
+	async get(key) {
+		const data = await this.readData();
+		const entry = data[key];
+		if (!entry) return void 0;
+		const remaining = getExpirationInSeconds(entry.expiresAt);
+		if (remaining <= 0) {
+			await this.withLock(async (current) => {
+				delete current[key];
+				return current;
+			});
+			return void 0;
+		}
+		return entry.value;
+	}
+	async set(key, value, ttl) {
+		const seconds = ttl ?? this.defaultTtl;
+		const expiresAt = addSeconds(/* @__PURE__ */ new Date(), seconds).toISOString();
+		await this.withLock(async (data) => {
+			data[key] = {
+				value,
+				expiresAt
+			};
+			return data;
+		});
+	}
+	async delete(key) {
+		await this.withLock(async (data) => {
+			delete data[key];
+			return data;
+		});
+	}
+	async ttl(key) {
+		const data = await this.readData();
+		const entry = data[key];
+		if (!entry) return 0;
+		return getExpirationInSeconds(entry.expiresAt);
+	}
+	async readData() {
+		try {
+			const content = await readFile(this.path, "utf-8");
+			return JSON.parse(content);
+		} catch {
+			return {};
+		}
+	}
+	async ensureDir() {
+		const dir = dirname(this.path);
+		if (!existsSync(dir)) await mkdir(dir, { recursive: true });
+	}
+	async withLock(fn) {
+		const prev = this.mutex;
+		let resolve;
+		this.mutex = new Promise((r) => {
+			resolve = r;
+		});
+		try {
+			await prev;
+			await this.ensureDir();
+			if (!existsSync(this.path)) await writeFile(this.path, "{}");
+			const release = await lockfile.lock(this.path, {
+				retries: {
+					retries: 3,
+					minTimeout: 100,
+					maxTimeout: 1e3
+				},
+				stale: 1e4
+			});
+			try {
+				const data = await this.readData();
+				const updated = await fn(data);
+				await writeFile(this.path, JSON.stringify(updated, null, 2));
+			} finally {
+				await release();
+			}
+		} finally {
+			resolve();
+		}
+	}
+};
+
+//#endregion
+export { FileCache };
+//# sourceMappingURL=file.mjs.map

package/dist/file.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.mjs","names":["options: FileCacheOptions","key: string","value: T","ttl?: number","fn: (data: FileCacheData) => Promise<FileCacheData>","resolve: () => void"],"sources":["../src/file.ts"],"sourcesContent":["import { existsSync } from 'node:fs';\nimport { mkdir, readFile, writeFile } from 'node:fs/promises';\nimport { dirname, join } from 'node:path';\nimport { addSeconds } from 'date-fns';\nimport lockfile from 'proper-lockfile';\nimport { type Cache, getExpirationInSeconds } from './';\n\ninterface FileCacheEntry {\n\tvalue: unknown;\n\texpiresAt: string;\n}\n\ntype FileCacheData = Record<string, FileCacheEntry>;\n\nexport interface FileCacheOptions {\n\t/** Path to the cache JSON file. Default: `process.cwd()/.gkm/cache.json` */\n\tpath?: string;\n\t/** Default TTL in seconds. Default: 600 */\n\tttl?: number;\n}\n\nexport class FileCache implements Cache {\n\tprivate readonly path: string;\n\tprivate readonly defaultTtl: number;\n\t/** In-process mutex to serialize concurrent writes within the same process. */\n\tprivate mutex: Promise<void> = Promise.resolve();\n\n\tconstructor(options: FileCacheOptions = {}) {\n\t\tthis.path = options.path ?? join(process.cwd(), '.gkm', 'cache.json');\n\t\tthis.defaultTtl = options.ttl ?? 600;\n\t}\n\n\tasync get<T>(key: string): Promise<T | undefined> {\n\t\tconst data = await this.readData();\n\t\tconst entry = data[key];\n\t\tif (!entry) return undefined;\n\n\t\tconst remaining = getExpirationInSeconds(entry.expiresAt);\n\t\tif (remaining <= 0) {\n\t\t\tawait this.withLock(async (current) => {\n\t\t\t\tdelete current[key];\n\t\t\t\treturn current;\n\t\t\t});\n\t\t\treturn undefined;\n\t\t}\n\n\t\treturn entry.value as T;\n\t}\n\n\tasync set<T>(key: string, value: T, ttl?: number): Promise<void> {\n\t\tconst seconds = ttl ?? this.defaultTtl;\n\t\tconst expiresAt = addSeconds(new Date(), seconds).toISOString();\n\n\t\tawait this.withLock(async (data) => {\n\t\t\tdata[key] = { value, expiresAt };\n\t\t\treturn data;\n\t\t});\n\t}\n\n\tasync delete(key: string): Promise<void> {\n\t\tawait this.withLock(async (data) => {\n\t\t\tdelete data[key];\n\t\t\treturn data;\n\t\t});\n\t}\n\n\tasync ttl(key: string): Promise<number> {\n\t\tconst data = await this.readData();\n\t\tconst entry = data[key];\n\t\tif (!entry) return 0;\n\n\t\treturn getExpirationInSeconds(entry.expiresAt);\n\t}\n\n\tprivate async readData(): Promise<FileCacheData> {\n\t\ttry {\n\t\t\tconst content = await readFile(this.path, 'utf-8');\n\t\t\treturn JSON.parse(content) as FileCacheData;\n\t\t} catch {\n\t\t\treturn {};\n\t\t}\n\t}\n\n\tprivate async ensureDir(): Promise<void> {\n\t\tconst dir = dirname(this.path);\n\t\tif (!existsSync(dir)) {\n\t\t\tawait mkdir(dir, { recursive: true });\n\t\t}\n\t}\n\n\tprivate async withLock(\n\t\tfn: (data: FileCacheData) => Promise<FileCacheData>,\n\t): Promise<void> {\n\t\t// Queue behind any pending in-process operations\n\t\tconst prev = this.mutex;\n\t\tlet resolve: () => void;\n\t\tthis.mutex = new Promise<void>((r) => {\n\t\t\tresolve = r;\n\t\t});\n\n\t\ttry {\n\t\t\tawait prev;\n\t\t\tawait this.ensureDir();\n\n\t\t\t// Ensure file exists before locking (proper-lockfile requires it)\n\t\t\tif (!existsSync(this.path)) {\n\t\t\t\tawait writeFile(this.path, '{}');\n\t\t\t}\n\n\t\t\tconst release = await lockfile.lock(this.path, {\n\t\t\t\tretries: { retries: 3, minTimeout: 100, maxTimeout: 1000 },\n\t\t\t\tstale: 10000,\n\t\t\t});\n\n\t\t\ttry {\n\t\t\t\tconst data = await this.readData();\n\t\t\t\tconst updated = await fn(data);\n\t\t\t\tawait writeFile(this.path, JSON.stringify(updated, null, 2));\n\t\t\t} finally {\n\t\t\t\tawait release();\n\t\t\t}\n\t\t} finally {\n\t\t\tresolve!();\n\t\t}\n\t}\n}\n"],"mappings":";;;;;;;;AAqBA,IAAa,YAAb,MAAwC;CACvC,AAAiB;CACjB,AAAiB;;CAEjB,AAAQ,QAAuB,QAAQ,SAAS;CAEhD,YAAYA,UAA4B,CAAE,GAAE;AAC3C,OAAK,OAAO,QAAQ,QAAQ,KAAK,QAAQ,KAAK,EAAE,QAAQ,aAAa;AACrE,OAAK,aAAa,QAAQ,OAAO;CACjC;CAED,MAAM,IAAOC,KAAqC;EACjD,MAAM,OAAO,MAAM,KAAK,UAAU;EAClC,MAAM,QAAQ,KAAK;AACnB,OAAK,MAAO;EAEZ,MAAM,YAAY,uBAAuB,MAAM,UAAU;AACzD,MAAI,aAAa,GAAG;AACnB,SAAM,KAAK,SAAS,OAAO,YAAY;AACtC,WAAO,QAAQ;AACf,WAAO;GACP,EAAC;AACF;EACA;AAED,SAAO,MAAM;CACb;CAED,MAAM,IAAOA,KAAaC,OAAUC,KAA6B;EAChE,MAAM,UAAU,OAAO,KAAK;EAC5B,MAAM,YAAY,2BAAW,IAAI,QAAQ,QAAQ,CAAC,aAAa;AAE/D,QAAM,KAAK,SAAS,OAAO,SAAS;AACnC,QAAK,OAAO;IAAE;IAAO;GAAW;AAChC,UAAO;EACP,EAAC;CACF;CAED,MAAM,OAAOF,KAA4B;AACxC,QAAM,KAAK,SAAS,OAAO,SAAS;AACnC,UAAO,KAAK;AACZ,UAAO;EACP,EAAC;CACF;CAED,MAAM,IAAIA,KAA8B;EACvC,MAAM,OAAO,MAAM,KAAK,UAAU;EAClC,MAAM,QAAQ,KAAK;AACnB,OAAK,MAAO,QAAO;AAEnB,SAAO,uBAAuB,MAAM,UAAU;CAC9C;CAED,MAAc,WAAmC;AAChD,MAAI;GACH,MAAM,UAAU,MAAM,SAAS,KAAK,MAAM,QAAQ;AAClD,UAAO,KAAK,MAAM,QAAQ;EAC1B,QAAO;AACP,UAAO,CAAE;EACT;CACD;CAED,MAAc,YAA2B;EACxC,MAAM,MAAM,QAAQ,KAAK,KAAK;AAC9B,OAAK,WAAW,IAAI,CACnB,OAAM,MAAM,KAAK,EAAE,WAAW,KAAM,EAAC;CAEtC;CAED,MAAc,SACbG,IACgB;EAEhB,MAAM,OAAO,KAAK;EAClB,IAAIC;AACJ,OAAK,QAAQ,IAAI,QAAc,CAAC,MAAM;AACrC,aAAU;EACV;AAED,MAAI;AACH,SAAM;AACN,SAAM,KAAK,WAAW;AAGtB,QAAK,WAAW,KAAK,KAAK,CACzB,OAAM,UAAU,KAAK,MAAM,KAAK;GAGjC,MAAM,UAAU,MAAM,SAAS,KAAK,KAAK,MAAM;IAC9C,SAAS;KAAE,SAAS;KAAG,YAAY;KAAK,YAAY;IAAM;IAC1D,OAAO;GACP,EAAC;AAEF,OAAI;IACH,MAAM,OAAO,MAAM,KAAK,UAAU;IAClC,MAAM,UAAU,MAAM,GAAG,KAAK;AAC9B,UAAM,UAAU,KAAK,MAAM,KAAK,UAAU,SAAS,MAAM,EAAE,CAAC;GAC5D,UAAS;AACT,UAAM,SAAS;GACf;EACD,UAAS;AACT,YAAU;EACV;CACD;AACD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/cache",
-  "version": "0.2.0",
+  "version": "1.1.0",
   "description": "Unified cache interface with multiple storage implementations",
   "private": false,
   "type": "module",
@@ -24,6 +24,11 @@
       "types": "./dist/expo.d.ts",
       "import": "./dist/expo.mjs",
       "require": "./dist/expo.cjs"
+    },
+    "./file": {
+      "types": "./dist/file.d.ts",
+      "import": "./dist/file.mjs",
+      "require": "./dist/file.cjs"
     }
   },
   "repository": {
@@ -35,11 +40,14 @@
     "access": "public"
   },
   "dependencies": {
-    "date-fns": "~4.1.0"
+    "date-fns": "~4.1.0",
+    "proper-lockfile": "^4.1.2"
   },
-  "devDependencies": {},
   "peerDependencies": {
     "@upstash/redis": "~1.35.1",
     "expo-secure-store": "^14.2.3"
+  },
+  "devDependencies": {
+    "@types/proper-lockfile": "^4.1.4"
   }
 }

package/src/__tests__/file.spec.ts

@@ -0,0 +1,192 @@
+import { existsSync } from 'node:fs';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { FileCache } from '../file';
+
+describe('FileCache', () => {
+	let dir: string;
+	let cachePath: string;
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), 'file-cache-test-'));
+		cachePath = join(dir, 'cache.json');
+	});
+
+	afterEach(async () => {
+		vi.useRealTimers();
+		await rm(dir, { recursive: true, force: true });
+	});
+
+	describe('get', () => {
+		it('should return undefined for non-existent key', async () => {
+			const cache = new FileCache({ path: cachePath });
+			const result = await cache.get('non-existent');
+			expect(result).toBeUndefined();
+		});
+
+		it('should return undefined when file does not exist', async () => {
+			const cache = new FileCache({
+				path: join(dir, 'subdir', 'cache.json'),
+			});
+			const result = await cache.get('any-key');
+			expect(result).toBeUndefined();
+		});
+
+		it('should return stored value', async () => {
+			const cache = new FileCache({ path: cachePath });
+			await cache.set('key', 'hello');
+			const result = await cache.get('key');
+			expect(result).toBe('hello');
+		});
+
+		it('should handle different data types', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			await cache.set('string', 'value');
+			await cache.set('number', 42);
+			await cache.set('boolean', true);
+			await cache.set('object', { id: 1, name: 'test' });
+			await cache.set('array', [1, 2, 3]);
+			await cache.set('null', null);
+
+			expect(await cache.get('string')).toBe('value');
+			expect(await cache.get('number')).toBe(42);
+			expect(await cache.get('boolean')).toBe(true);
+			expect(await cache.get('object')).toEqual({ id: 1, name: 'test' });
+			expect(await cache.get('array')).toEqual([1, 2, 3]);
+			expect(await cache.get('null')).toBeNull();
+		});
+
+		it('should return undefined for expired entries', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			vi.useFakeTimers();
+			await cache.set('expiring', 'value', 1);
+
+			// Advance past expiration
+			vi.advanceTimersByTime(2000);
+
+			const result = await cache.get('expiring');
+			expect(result).toBeUndefined();
+
+			vi.useRealTimers();
+		});
+	});
+
+	describe('set', () => {
+		it('should create file and parent directory', async () => {
+			const nested = join(dir, 'nested', 'dir', 'cache.json');
+			const cache = new FileCache({ path: nested });
+
+			await cache.set('key', 'value');
+
+			expect(existsSync(nested)).toBe(true);
+		});
+
+		it('should overwrite existing value', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			await cache.set('key', 'first');
+			await cache.set('key', 'second');
+
+			expect(await cache.get('key')).toBe('second');
+		});
+
+		it('should persist data in valid JSON format', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			await cache.set('test', { hello: 'world' });
+
+			const raw = await readFile(cachePath, 'utf-8');
+			const parsed = JSON.parse(raw);
+
+			expect(parsed.test).toBeDefined();
+			expect(parsed.test.value).toEqual({ hello: 'world' });
+			expect(parsed.test.expiresAt).toBeDefined();
+		});
+
+		it('should use custom default TTL', async () => {
+			const cache = new FileCache({ path: cachePath, ttl: 3600 });
+
+			await cache.set('key', 'value');
+
+			const remaining = await cache.ttl('key');
+			expect(remaining).toBeGreaterThan(3500);
+			expect(remaining).toBeLessThanOrEqual(3600);
+		});
+	});
+
+	describe('delete', () => {
+		it('should remove existing key', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			await cache.set('key', 'value');
+			await cache.delete('key');
+
+			expect(await cache.get('key')).toBeUndefined();
+		});
+
+		it('should not throw for non-existent key', async () => {
+			const cache = new FileCache({ path: cachePath });
+			await expect(cache.delete('non-existent')).resolves.not.toThrow();
+		});
+
+		it('should only delete specified key', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			await cache.set('key1', 'value1');
+			await cache.set('key2', 'value2');
+			await cache.delete('key1');
+
+			expect(await cache.get('key1')).toBeUndefined();
+			expect(await cache.get('key2')).toBe('value2');
+		});
+	});
+
+	describe('ttl', () => {
+		it('should return 0 for non-existent key', async () => {
+			const cache = new FileCache({ path: cachePath });
+			expect(await cache.ttl('non-existent')).toBe(0);
+		});
+
+		it('should return remaining seconds for existing key', async () => {
+			const cache = new FileCache({ path: cachePath });
+			await cache.set('key', 'value', 300);
+
+			const remaining = await cache.ttl('key');
+			expect(remaining).toBeGreaterThan(298);
+			expect(remaining).toBeLessThanOrEqual(300);
+		});
+	});
+
+	describe('concurrency', () => {
+		it('should handle concurrent writes without corruption', async () => {
+			const cache = new FileCache({ path: cachePath });
+
+			// Write 10 keys concurrently
+			await Promise.all(
+				Array.from({ length: 10 }, (_, i) =>
+					cache.set(`key-${i}`, `value-${i}`),
+				),
+			);
+
+			// Verify all keys were written
+			for (let i = 0; i < 10; i++) {
+				const value = await cache.get(`key-${i}`);
+				expect(value).toBe(`value-${i}`);
+			}
+		});
+	});
+
+	describe('persistence', () => {
+		it('should persist across cache instances', async () => {
+			const cache1 = new FileCache({ path: cachePath });
+			await cache1.set('persistent', 'data');
+
+			const cache2 = new FileCache({ path: cachePath });
+			expect(await cache2.get('persistent')).toBe('data');
+		});
+	});
+});

package/src/file.ts

@@ -0,0 +1,126 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { addSeconds } from 'date-fns';
+import lockfile from 'proper-lockfile';
+import { type Cache, getExpirationInSeconds } from './';
+
+interface FileCacheEntry {
+	value: unknown;
+	expiresAt: string;
+}
+
+type FileCacheData = Record<string, FileCacheEntry>;
+
+export interface FileCacheOptions {
+	/** Path to the cache JSON file. Default: `process.cwd()/.gkm/cache.json` */
+	path?: string;
+	/** Default TTL in seconds. Default: 600 */
+	ttl?: number;
+}
+
+export class FileCache implements Cache {
+	private readonly path: string;
+	private readonly defaultTtl: number;
+	/** In-process mutex to serialize concurrent writes within the same process. */
+	private mutex: Promise<void> = Promise.resolve();
+
+	constructor(options: FileCacheOptions = {}) {
+		this.path = options.path ?? join(process.cwd(), '.gkm', 'cache.json');
+		this.defaultTtl = options.ttl ?? 600;
+	}
+
+	async get<T>(key: string): Promise<T | undefined> {
+		const data = await this.readData();
+		const entry = data[key];
+		if (!entry) return undefined;
+
+		const remaining = getExpirationInSeconds(entry.expiresAt);
+		if (remaining <= 0) {
+			await this.withLock(async (current) => {
+				delete current[key];
+				return current;
+			});
+			return undefined;
+		}
+
+		return entry.value as T;
+	}
+
+	async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+		const seconds = ttl ?? this.defaultTtl;
+		const expiresAt = addSeconds(new Date(), seconds).toISOString();
+
+		await this.withLock(async (data) => {
+			data[key] = { value, expiresAt };
+			return data;
+		});
+	}
+
+	async delete(key: string): Promise<void> {
+		await this.withLock(async (data) => {
+			delete data[key];
+			return data;
+		});
+	}
+
+	async ttl(key: string): Promise<number> {
+		const data = await this.readData();
+		const entry = data[key];
+		if (!entry) return 0;
+
+		return getExpirationInSeconds(entry.expiresAt);
+	}
+
+	private async readData(): Promise<FileCacheData> {
+		try {
+			const content = await readFile(this.path, 'utf-8');
+			return JSON.parse(content) as FileCacheData;
+		} catch {
+			return {};
+		}
+	}
+
+	private async ensureDir(): Promise<void> {
+		const dir = dirname(this.path);
+		if (!existsSync(dir)) {
+			await mkdir(dir, { recursive: true });
+		}
+	}
+
+	private async withLock(
+		fn: (data: FileCacheData) => Promise<FileCacheData>,
+	): Promise<void> {
+		// Queue behind any pending in-process operations
+		const prev = this.mutex;
+		let resolve: () => void;
+		this.mutex = new Promise<void>((r) => {
+			resolve = r;
+		});
+
+		try {
+			await prev;
+			await this.ensureDir();
+
+			// Ensure file exists before locking (proper-lockfile requires it)
+			if (!existsSync(this.path)) {
+				await writeFile(this.path, '{}');
+			}
+
+			const release = await lockfile.lock(this.path, {
+				retries: { retries: 3, minTimeout: 100, maxTimeout: 1000 },
+				stale: 10000,
+			});
+
+			try {
+				const data = await this.readData();
+				const updated = await fn(data);
+				await writeFile(this.path, JSON.stringify(updated, null, 2));
+			} finally {
+				await release();
+			}
+		} finally {
+			resolve!();
+		}
+	}
+}