@dereekb/nestjs 13.10.9 → 13.11.1

package/mailgun/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/mailgun",
-  "version": "13.10.9",
+  "version": "13.11.1",
   "peerDependencies": {
-    "@dereekb/date": "13.10.9",
-    "@dereekb/model": "13.10.9",
-    "@dereekb/nestjs": "13.10.9",
-    "@dereekb/rxjs": "13.10.9",
-    "@dereekb/util": "13.10.9",
+    "@dereekb/date": "13.11.1",
+    "@dereekb/model": "13.11.1",
+    "@dereekb/nestjs": "13.11.1",
+    "@dereekb/rxjs": "13.11.1",
+    "@dereekb/util": "13.11.1",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "form-data": "^4.0.5",

package/openai/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/openai",
-  "version": "13.10.9",
+  "version": "13.11.1",
   "peerDependencies": {
-    "@dereekb/date": "13.10.9",
-    "@dereekb/model": "13.10.9",
-    "@dereekb/nestjs": "13.10.9",
-    "@dereekb/rxjs": "13.10.9",
-    "@dereekb/util": "13.10.9",
+    "@dereekb/date": "13.11.1",
+    "@dereekb/model": "13.11.1",
+    "@dereekb/nestjs": "13.11.1",
+    "@dereekb/rxjs": "13.11.1",
+    "@dereekb/util": "13.11.1",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/nestjs",
-  "version": "13.10.9",
+  "version": "13.11.1",
   "types": "./src/index.d.ts",
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
@@ -56,8 +56,8 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/rxjs": "13.10.9",
-    "@dereekb/util": "13.10.9",
+    "@dereekb/rxjs": "13.11.1",
+    "@dereekb/util": "13.11.1",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "@typeform/api-client": "^2.10.2",

package/src/lib/util/cache/cache.file.d.ts

@@ -0,0 +1,106 @@
+import { type AsyncKeyedValueCache, type AsyncValueCache, type Maybe } from '@dereekb/util';
+/**
+ * Default file mode used by the JSON-file caches when none is provided.
+ *
+ * 0o600 restricts the file to read/write for the owning user only — appropriate for
+ * secrets like cached access/refresh tokens.
+ */
+export declare const DEFAULT_JSON_FILE_CACHE_MODE = 384;
+/**
+ * Input for {@link createJsonFileAsyncValueCache} and {@link createMemoizedJsonFileAsyncValueCache}.
+ */
+export interface CreateJsonFileAsyncValueCacheInput<T> {
+    /**
+     * Absolute path to the JSON file that backs the cache.
+     */
+    readonly filePath: string;
+    /**
+     * File mode applied on write. Defaults to {@link DEFAULT_JSON_FILE_CACHE_MODE} (0o600).
+     */
+    readonly mode?: Maybe<number>;
+    /**
+     * Optional transform applied to the raw JSON-parsed payload before it is returned from `load()`.
+     *
+     * Use this to revive types that don't roundtrip through JSON — e.g. a `Date` field stored as an ISO string.
+     */
+    readonly reviver?: Maybe<(raw: unknown) => Maybe<T>>;
+    /**
+     * Optional transform applied to the value before it is stringified to JSON on `update()`.
+     */
+    readonly replacer?: Maybe<(value: T) => unknown>;
+}
+/**
+ * Creates an {@link AsyncValueCache} backed by a single JSON file on disk.
+ *
+ * Reads always touch disk; wrap with {@link memoizeAsyncValueCache} (or use
+ * {@link createMemoizedJsonFileAsyncValueCache}) to add per-process memoization.
+ *
+ * Multi-process invalidation is not provided. Two processes writing to the same file
+ * will last-writer-wins; once memoized, a long-running process will not observe writes
+ * from another process.
+ *
+ * @param input - Configuration bag describing the backing file and optional JSON revive/replace hooks.
+ * @param input.filePath - Absolute path to the JSON file that backs the cache.
+ * @param input.mode - Optional file mode applied on write; defaults to {@link DEFAULT_JSON_FILE_CACHE_MODE} (0o600).
+ * @param input.reviver - Optional transform applied to the raw JSON-parsed payload before it is returned from `load()` (e.g. revive `Date` fields).
+ * @param input.replacer - Optional transform applied to the value before it is stringified to JSON on `update()`.
+ * @returns An {@link AsyncValueCache} that persists the value to the configured JSON file.
+ */
+export declare function createJsonFileAsyncValueCache<T>(input: CreateJsonFileAsyncValueCacheInput<T>): AsyncValueCache<T>;
+/**
+ * Convenience wrapper around {@link createJsonFileAsyncValueCache} composed with
+ * {@link memoizeAsyncValueCache}.
+ *
+ * @param input - Same configuration accepted by {@link createJsonFileAsyncValueCache}; see {@link CreateJsonFileAsyncValueCacheInput}.
+ * @returns An {@link AsyncValueCache} backed by the JSON file with a per-process single-load memoization layer in front.
+ */
+export declare function createMemoizedJsonFileAsyncValueCache<T>(input: CreateJsonFileAsyncValueCacheInput<T>): AsyncValueCache<T>;
+/**
+ * Input for {@link createJsonFileAsyncKeyedValueCache} and {@link createMemoizedJsonFileAsyncKeyedValueCache}.
+ */
+export interface CreateJsonFileAsyncKeyedValueCacheInput<T> {
+    /**
+     * Absolute path to the JSON file that backs the cache. The file holds the entire `Record<string, T>`.
+     */
+    readonly filePath: string;
+    /**
+     * File mode applied on write. Defaults to {@link DEFAULT_JSON_FILE_CACHE_MODE} (0o600).
+     */
+    readonly mode?: Maybe<number>;
+    /**
+     * Optional transform applied to each entry after it is JSON-parsed on `load()`/`get()`.
+     */
+    readonly reviver?: Maybe<(raw: unknown) => Maybe<T>>;
+    /**
+     * Optional transform applied to each entry before it is stringified on `set()`.
+     */
+    readonly replacer?: Maybe<(value: T) => unknown>;
+}
+/**
+ * Creates an {@link AsyncKeyedValueCache} backed by a single JSON file holding a `Record<string, T>`.
+ *
+ * Reads/writes always touch disk; wrap with {@link memoizeAsyncKeyedValueCache} (or use
+ * {@link createMemoizedJsonFileAsyncKeyedValueCache}) to add per-process memoization of the
+ * entire record.
+ *
+ * Multi-process invalidation is not provided; see {@link createJsonFileAsyncValueCache} for caveats.
+ *
+ * Concurrent `set`/`remove`/`clear` calls are serialized through a per-instance promise chain so
+ * the read-modify-write of the entire record file does not race within the same process.
+ *
+ * @param input - Configuration bag describing the backing file and optional per-entry revive/replace hooks.
+ * @param input.filePath - Absolute path to the JSON file that holds the entire `Record<string, T>`.
+ * @param input.mode - Optional file mode applied on write; defaults to {@link DEFAULT_JSON_FILE_CACHE_MODE} (0o600).
+ * @param input.reviver - Optional transform applied to each entry after it is JSON-parsed on `load()`/`get()`. Returning null/undefined drops the entry.
+ * @param input.replacer - Optional transform applied to each entry before it is stringified on `set()`.
+ * @returns An {@link AsyncKeyedValueCache} that persists all entries in the configured JSON file.
+ */
+export declare function createJsonFileAsyncKeyedValueCache<T>(input: CreateJsonFileAsyncKeyedValueCacheInput<T>): AsyncKeyedValueCache<T>;
+/**
+ * Convenience wrapper around {@link createJsonFileAsyncKeyedValueCache} composed with
+ * {@link memoizeAsyncKeyedValueCache}.
+ *
+ * @param input - Same configuration accepted by {@link createJsonFileAsyncKeyedValueCache}; see {@link CreateJsonFileAsyncKeyedValueCacheInput}.
+ * @returns An {@link AsyncKeyedValueCache} backed by the JSON file with a per-process record-level memoization layer in front.
+ */
+export declare function createMemoizedJsonFileAsyncKeyedValueCache<T>(input: CreateJsonFileAsyncKeyedValueCacheInput<T>): AsyncKeyedValueCache<T>;

package/src/lib/util/cache/index.d.ts

@@ -0,0 +1 @@
+export * from './cache.file';

package/src/lib/util/file/file.json.d.ts

@@ -0,0 +1,57 @@
+import { type Maybe } from '@dereekb/util';
+/**
+ * Reads JSON from disk, resolving `undefined` when the file is missing (ENOENT) or its
+ * contents fail to parse as JSON. Other I/O errors (permission denied, busy handles) are
+ * forwarded to the caller — silently swallowing them masks real failures.
+ *
+ * @param filePath - Absolute path to the JSON file to read.
+ * @returns The parsed JSON cast to `T`, or `undefined` when the file does not exist or its contents are not valid JSON.
+ */
+export declare function readJsonFile<T>(filePath: string): Promise<Maybe<T>>;
+/**
+ * Configuration bag for {@link writeJsonFile}.
+ */
+export interface WriteJsonFileInput {
+    /**
+     * Absolute path to the file to write.
+     */
+    readonly filePath: string;
+    /**
+     * Absolute path to the parent directory; created (recursively) if missing before the write.
+     */
+    readonly dirPath: string;
+    /**
+     * Value to serialize as JSON.
+     */
+    readonly data: unknown;
+    /**
+     * Optional numeric file mode (e.g. `0o600`) enforced via an explicit `chmod` after the write.
+     */
+    readonly mode?: number;
+}
+/**
+ * Writes a value to disk as JSON. Creates the parent directory if it does not exist.
+ *
+ * The `mode` option is enforced via an explicit `chmod` after the write — `writeFile`'s `mode`
+ * parameter is ignored when the file already exists, which would otherwise leave a
+ * pre-existing file at its original (potentially world-readable) permissions.
+ *
+ * @param input - Configuration describing the destination, payload, and optional file mode.
+ * @param input.filePath - Absolute path to the file to write.
+ * @param input.dirPath - Absolute path to the parent directory; created (recursively) when missing.
+ * @param input.data - Value to serialize as JSON (pretty-printed with two-space indentation).
+ * @param input.mode - Optional numeric file mode (e.g. `0o600`) applied via `chmod` after the write.
+ * @returns A promise that resolves once the JSON has been written and the optional `chmod` has completed.
+ */
+export declare function writeJsonFile(input: WriteJsonFileInput): Promise<void>;
+/**
+ * Removes the file at the given path.
+ *
+ * Resolves silently when the file does not exist (`force: true`); other errors
+ * (permission denied, busy file handles) are forwarded to the caller — silently
+ * swallowing them masks real failures and makes operations appear to have succeeded.
+ *
+ * @param filePath - Absolute path to the file to remove.
+ * @returns A promise that resolves once the file is removed (or was already absent).
+ */
+export declare function removeFile(filePath: string): Promise<void>;

package/src/lib/util/file/index.d.ts

@@ -0,0 +1 @@
+export * from './file.json';

package/src/lib/util/index.d.ts

@@ -1,2 +1,4 @@
+export * from './cache';
 export * from './encryption';
+export * from './file';
 export * from './pdf';

package/stripe/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/stripe",
-  "version": "13.10.9",
+  "version": "13.11.1",
   "peerDependencies": {
-    "@dereekb/date": "13.10.9",
-    "@dereekb/model": "13.10.9",
-    "@dereekb/nestjs": "13.10.9",
-    "@dereekb/rxjs": "13.10.9",
-    "@dereekb/util": "13.10.9",
+    "@dereekb/date": "13.11.1",
+    "@dereekb/model": "13.11.1",
+    "@dereekb/nestjs": "13.11.1",
+    "@dereekb/rxjs": "13.11.1",
+    "@dereekb/util": "13.11.1",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/typeform/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/typeform",
-  "version": "13.10.9",
+  "version": "13.11.1",
   "peerDependencies": {
-    "@dereekb/date": "13.10.9",
-    "@dereekb/model": "13.10.9",
-    "@dereekb/nestjs": "13.10.9",
-    "@dereekb/rxjs": "13.10.9",
-    "@dereekb/util": "13.10.9",
+    "@dereekb/date": "13.11.1",
+    "@dereekb/model": "13.11.1",
+    "@dereekb/nestjs": "13.11.1",
+    "@dereekb/rxjs": "13.11.1",
+    "@dereekb/util": "13.11.1",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "@typeform/api-client": "^2.10.2",

package/vapiai/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/vapiai",
-  "version": "13.10.9",
+  "version": "13.11.1",
   "peerDependencies": {
-    "@dereekb/date": "13.10.9",
-    "@dereekb/model": "13.10.9",
-    "@dereekb/nestjs": "13.10.9",
-    "@dereekb/rxjs": "13.10.9",
-    "@dereekb/util": "13.10.9",
+    "@dereekb/date": "13.11.1",
+    "@dereekb/model": "13.11.1",
+    "@dereekb/nestjs": "13.11.1",
+    "@dereekb/rxjs": "13.11.1",
+    "@dereekb/util": "13.11.1",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "@vapi-ai/server-sdk": "^0.11.0",