@kikiutils/shared 18.2.0 → 18.3.0

package/dist/classes/path.d.ts

@@ -360,4 +360,5 @@ export declare class Path {
   writeFile(...args: DropFirstParameters<typeof fsp.writeFile>): Promise<void>;
 }
 //#endregion
+export {};
 //# sourceMappingURL=path.d.ts.map

package/dist/classes/ssh-client.d.ts

@@ -36,4 +36,5 @@ export declare class SshClient {
   setLoggerLevel(level: keyof typeof loggerLevelStringToConsolaLogLevelMap): void;
 }
 //#endregion
+export {};
 //# sourceMappingURL=ssh-client.d.ts.map

package/dist/clipboard.d.ts

@@ -62,4 +62,5 @@ export declare function copyBlobToClipboard(blob: Blob, options?: ClipboardItemO
  */
 export declare function copyTextToClipboard(text: string): Promise<CopyResult>;
 //#endregion
+export {};
 //# sourceMappingURL=clipboard.d.ts.map

package/dist/file.d.ts

@@ -0,0 +1,27 @@
+import { BinaryInput } from "./types/index.js";
+//#region src/file.d.ts
+/**
+ * Detects a lowercase MIME type from binary content rather than its name or declared type.
+ *
+ * @remarks
+ * Requires the optional `file-type` peer dependency. Only formats supported by its binary detection
+ * are recognized; this is not a general text-file detector or a guarantee that a file is safe.
+ * Blob and File inputs are read through the detector's tokenizer instead of being fully buffered up front.
+ * The amount of content inspected depends on its format; this does not impose a fixed read limit.
+ * Detection and input-reading errors propagate to the caller.
+ *
+ * @param input - The binary content to inspect.
+ *
+ * @returns The detected lowercase MIME type, or `undefined` when the content is not recognized.
+ *
+ * @example
+ *
+ * ```ts
+ * import { getFileMimeType } from '@kikiutils/shared/file';
+ *
+ * const mimeType = await getFileMimeType(file);
+ * ```
+ */
+export declare function getFileMimeType(input: BinaryInput): Promise<string | undefined>;
+//#endregion
+//# sourceMappingURL=file.d.ts.map

package/dist/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","names":[],"sources":["../src/file.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;wBA6BsB,gBAAgB,OAAO,cAAW"}

package/dist/file.js

@@ -0,0 +1,31 @@
+import { fileTypeFromBlob, fileTypeFromBuffer } from "file-type";
+//#region src/file.ts
+/**
+* Detects a lowercase MIME type from binary content rather than its name or declared type.
+*
+* @remarks
+* Requires the optional `file-type` peer dependency. Only formats supported by its binary detection
+* are recognized; this is not a general text-file detector or a guarantee that a file is safe.
+* Blob and File inputs are read through the detector's tokenizer instead of being fully buffered up front.
+* The amount of content inspected depends on its format; this does not impose a fixed read limit.
+* Detection and input-reading errors propagate to the caller.
+*
+* @param input - The binary content to inspect.
+*
+* @returns The detected lowercase MIME type, or `undefined` when the content is not recognized.
+*
+* @example
+*
+* ```ts
+* import { getFileMimeType } from '@kikiutils/shared/file';
+*
+* const mimeType = await getFileMimeType(file);
+* ```
+*/
+async function getFileMimeType(input) {
+	return (input instanceof ArrayBuffer || input instanceof Uint8Array ? await fileTypeFromBuffer(input) : await fileTypeFromBlob(input))?.mime.toLowerCase();
+}
+//#endregion
+export { getFileMimeType };
+
+//# sourceMappingURL=file.js.map

package/dist/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","names":[],"sources":["../src/file.ts"],"sourcesContent":["import {\n    fileTypeFromBlob,\n    fileTypeFromBuffer,\n} from 'file-type';\n\nimport type { BinaryInput } from './types';\n\n/**\n * Detects a lowercase MIME type from binary content rather than its name or declared type.\n *\n * @remarks\n * Requires the optional `file-type` peer dependency. Only formats supported by its binary detection\n * are recognized; this is not a general text-file detector or a guarantee that a file is safe.\n * Blob and File inputs are read through the detector's tokenizer instead of being fully buffered up front.\n * The amount of content inspected depends on its format; this does not impose a fixed read limit.\n * Detection and input-reading errors propagate to the caller.\n *\n * @param input - The binary content to inspect.\n *\n * @returns The detected lowercase MIME type, or `undefined` when the content is not recognized.\n *\n * @example\n *\n * ```ts\n * import { getFileMimeType } from '@kikiutils/shared/file';\n *\n * const mimeType = await getFileMimeType(file);\n * ```\n */\nexport async function getFileMimeType(input: BinaryInput) {\n    // The tokenizer only uses size, slice, and arrayBuffer; Node/DOM Blob stream typings differ.\n    const result = input instanceof ArrayBuffer || input instanceof Uint8Array\n        ? await fileTypeFromBuffer(input)\n        : await fileTypeFromBlob(input as Blob);\n\n    return result?.mime.toLowerCase();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA6BA,eAAsB,gBAAgB,OAAoB;CAMtD,QAJe,iBAAiB,eAAe,iBAAiB,aAC1D,MAAM,mBAAmB,KAAK,IAC9B,MAAM,iBAAiB,KAAa,EAAA,EAE3B,KAAK,YAAY;AACpC"}

package/dist/math.d.ts

@@ -46,4 +46,5 @@ export interface ToPercentageStringOptions {
  */
 export declare function toPercentageString(molecular: CalculableValue, denominator: CalculableValue, options?: ToPercentageStringOptions): string;
 //#endregion
+export {};
 //# sourceMappingURL=math.d.ts.map

package/dist/storages/lru/keyed-store.d.ts

@@ -7,6 +7,7 @@ import { LRUCache } from "lru-cache";
  * The key resolver is called synchronously once per operation, and its exceptions propagate.
  * Reads return the cached value without copying it, or `null` for missing or nullish values.
  * `getItemTtl` exposes the underlying remaining TTL in milliseconds; `setItem` returns the underlying cache.
+ * `setItemWithTtl` accepts its TTL in milliseconds before the value and key arguments and returns the cache.
  * The facade does not dispose the supplied cache, and LRU defaults remain those of the supplied instance.
  *
  * @typeParam D - The stored value type used by reads and writes.
@@ -42,6 +43,7 @@ export declare function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<a
    */
   resolveKey: (...args: P) => string;
   setItem: (value: D, ...args: P) => LRUCache<any, any, any>;
+  setItemWithTtl(ttlMilliseconds: number, value: D, ...args: P): LRUCache<any, any, any>;
 }>;
 //#endregion
 //# sourceMappingURL=keyed-store.d.ts.map

package/dist/storages/lru/keyed-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keyed-store.d.ts","names":[],"sources":["../../../src/storages/lru/keyed-store.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA6BgB,oBAAoB,aAAa,aAAa,2BAClD,iBAAiB,WAAW,MAAM,iBAAY;;;;;;EAMjC,WAAA,MAAA,IAAC,YAAA;EAII,gBAAA,MAAA;EACH,aAAA,MAAA;EACG,gBAAA,MAAA;;;;EAIA,gBAAA,MAAA;EACL,UAAA,OAAA,MAAC,MAAW,MAAC"}
+{"version":3,"file":"keyed-store.d.ts","names":[],"sources":["../../../src/storages/lru/keyed-store.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA8BgB,oBAAoB,aAAa,aAAa,2BAClD,iBAAiB,WAAW,MAAM,iBAAY;;;;;;EAMjC,WAAA,MAAA,IAAC,YAAA;EAII,gBAAA,MAAA;EACH,aAAA,MAAA;EACG,gBAAA,MAAA;;;;EAIA,gBAAA,MAAA;EACL,UAAA,OAAA,MAAC,MAAW,MAAC;EACE,eAAA,yBAAM,OAAS,MAAC,MAAW,IAAC"}

package/dist/storages/lru/keyed-store.js

@@ -6,6 +6,7 @@
 * The key resolver is called synchronously once per operation, and its exceptions propagate.
 * Reads return the cached value without copying it, or `null` for missing or nullish values.
 * `getItemTtl` exposes the underlying remaining TTL in milliseconds; `setItem` returns the underlying cache.
+* `setItemWithTtl` accepts its TTL in milliseconds before the value and key arguments and returns the cache.
 * The facade does not dispose the supplied cache, and LRU defaults remain those of the supplied instance.
 *
 * @typeParam D - The stored value type used by reads and writes.
@@ -43,7 +44,10 @@ function createLruKeyedStore(lruInstance) {
 		* Resolves the full cache key from the given arguments.
 		*/
 		resolveKey: (...args) => keyFn(...args),
-		setItem: (value, ...args) => lruInstance.set(keyFn(...args), value)
+		setItem: (value, ...args) => lruInstance.set(keyFn(...args), value),
+		setItemWithTtl(ttlMilliseconds, value, ...args) {
+			return lruInstance.set(keyFn(...args), value, { ttl: ttlMilliseconds });
+		}
 	});
 }
 //#endregion

package/dist/storages/lru/keyed-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"keyed-store.js","names":[],"sources":["../../../src/storages/lru/keyed-store.ts"],"sourcesContent":["import type { LRUCache } from 'lru-cache';\n\n/**\n * Creates a keyed cache factory sharing a caller-owned LRU cache.\n *\n * @remarks\n * The key resolver is called synchronously once per operation, and its exceptions propagate.\n * Reads return the cached value without copying it, or `null` for missing or nullish values.\n * `getItemTtl` exposes the underlying remaining TTL in milliseconds; `setItem` returns the underlying cache.\n * The facade does not dispose the supplied cache, and LRU defaults remain those of the supplied instance.\n *\n * @typeParam D - The stored value type used by reads and writes.\n *\n * @param lruInstance - The shared LRU cache instance.\n *\n * @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the cache.\n *\n * @example\n *\n * ```ts\n * import { createLruKeyedStore } from '@kikiutils/shared/storages/lru/keyed-store';\n * import { LRUCache } from 'lru-cache';\n *\n * const cache = new LRUCache<string, { name: string }>({ max: 100 });\n * const keyedStore = createLruKeyedStore<{ name: string }>(cache)((userId: string) => `user:${userId}`);\n * keyedStore.setItem({ name: 'Alice' }, 'user-123');\n * console.log(keyedStore.getItem('user-123')); // => { name: 'Alice' }\n * ```\n */\nexport function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any, any>) {\n    return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({\n        /**\n         * Returns the cached value and applies the underlying cache's read-recency policy.\n         *\n         * @returns The cached value without copying it, or `null` when absent or nullish.\n         */\n        getItem(...args: P) {\n            const rawValue = lruInstance.get(keyFn(...args));\n            return rawValue as D ?? null;\n        },\n        getItemTtl: (...args: P) => lruInstance.getRemainingTTL(keyFn(...args)),\n        hasItem: (...args: P) => lruInstance.has(keyFn(...args)),\n        removeItem: (...args: P) => lruInstance.delete(keyFn(...args)),\n        /**\n         * Resolves the full cache key from the given arguments.\n         */\n        resolveKey: (...args: P) => keyFn(...args),\n        setItem: (value: D, ...args: P) => lruInstance.set(keyFn(...args), value),\n    });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,oBAAiC,aAAsC;CACnF,QAAyB,UAAkC,OAAO,OAAO;;;;;;EAMrE,QAAQ,GAAG,MAAS;GAEhB,OADiB,YAAY,IAAI,MAAM,GAAG,IAAI,CAChC,KAAU;EAC5B;EACA,aAAa,GAAG,SAAY,YAAY,gBAAgB,MAAM,GAAG,IAAI,CAAC;EACtE,UAAU,GAAG,SAAY,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;EACvD,aAAa,GAAG,SAAY,YAAY,OAAO,MAAM,GAAG,IAAI,CAAC;;;;EAI7D,aAAa,GAAG,SAAY,MAAM,GAAG,IAAI;EACzC,UAAU,OAAU,GAAG,SAAY,YAAY,IAAI,MAAM,GAAG,IAAI,GAAG,KAAK;CAC5E,CAAC;AACL"}
+{"version":3,"file":"keyed-store.js","names":[],"sources":["../../../src/storages/lru/keyed-store.ts"],"sourcesContent":["import type { LRUCache } from 'lru-cache';\n\n/**\n * Creates a keyed cache factory sharing a caller-owned LRU cache.\n *\n * @remarks\n * The key resolver is called synchronously once per operation, and its exceptions propagate.\n * Reads return the cached value without copying it, or `null` for missing or nullish values.\n * `getItemTtl` exposes the underlying remaining TTL in milliseconds; `setItem` returns the underlying cache.\n * `setItemWithTtl` accepts its TTL in milliseconds before the value and key arguments and returns the cache.\n * The facade does not dispose the supplied cache, and LRU defaults remain those of the supplied instance.\n *\n * @typeParam D - The stored value type used by reads and writes.\n *\n * @param lruInstance - The shared LRU cache instance.\n *\n * @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the cache.\n *\n * @example\n *\n * ```ts\n * import { createLruKeyedStore } from '@kikiutils/shared/storages/lru/keyed-store';\n * import { LRUCache } from 'lru-cache';\n *\n * const cache = new LRUCache<string, { name: string }>({ max: 100 });\n * const keyedStore = createLruKeyedStore<{ name: string }>(cache)((userId: string) => `user:${userId}`);\n * keyedStore.setItem({ name: 'Alice' }, 'user-123');\n * console.log(keyedStore.getItem('user-123')); // => { name: 'Alice' }\n * ```\n */\nexport function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any, any>) {\n    return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({\n        /**\n         * Returns the cached value and applies the underlying cache's read-recency policy.\n         *\n         * @returns The cached value without copying it, or `null` when absent or nullish.\n         */\n        getItem(...args: P) {\n            const rawValue = lruInstance.get(keyFn(...args));\n            return rawValue as D ?? null;\n        },\n        getItemTtl: (...args: P) => lruInstance.getRemainingTTL(keyFn(...args)),\n        hasItem: (...args: P) => lruInstance.has(keyFn(...args)),\n        removeItem: (...args: P) => lruInstance.delete(keyFn(...args)),\n        /**\n         * Resolves the full cache key from the given arguments.\n         */\n        resolveKey: (...args: P) => keyFn(...args),\n        setItem: (value: D, ...args: P) => lruInstance.set(keyFn(...args), value),\n        setItemWithTtl(ttlMilliseconds: number, value: D, ...args: P) {\n            return lruInstance.set(keyFn(...args), value, { ttl: ttlMilliseconds });\n        },\n    });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,oBAAiC,aAAsC;CACnF,QAAyB,UAAkC,OAAO,OAAO;;;;;;EAMrE,QAAQ,GAAG,MAAS;GAEhB,OADiB,YAAY,IAAI,MAAM,GAAG,IAAI,CAChC,KAAU;EAC5B;EACA,aAAa,GAAG,SAAY,YAAY,gBAAgB,MAAM,GAAG,IAAI,CAAC;EACtE,UAAU,GAAG,SAAY,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;EACvD,aAAa,GAAG,SAAY,YAAY,OAAO,MAAM,GAAG,IAAI,CAAC;;;;EAI7D,aAAa,GAAG,SAAY,MAAM,GAAG,IAAI;EACzC,UAAU,OAAU,GAAG,SAAY,YAAY,IAAI,MAAM,GAAG,IAAI,GAAG,KAAK;EACxE,eAAe,iBAAyB,OAAU,GAAG,MAAS;GAC1D,OAAO,YAAY,IAAI,MAAM,GAAG,IAAI,GAAG,OAAO,EAAE,KAAK,gBAAgB,CAAC;EAC1E;CACJ,CAAC;AACL"}

package/dist/types/filtered-key-path.d.ts

@@ -14,4 +14,5 @@ type PathImpl<K extends number | string, V, U> = [U] extends [never] ? DefaultPa
 type TerminalType = bigint | Blob | boolean | Date | File | null | number | ObjectId | RegExp | string | symbol | undefined;
 type TupleKey<T extends ReadonlyArray<any>> = Exclude<keyof T, keyof any[]>;
 //#endregion
+export {};
 //# sourceMappingURL=filtered-key-path.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kikiutils/shared",
   "type": "module",
-  "version": "18.2.0",
+  "version": "18.3.0",
   "description": "A lightweight and modular utility library for modern JavaScript and TypeScript — includes secure hashing, flexible logging, datetime tools, Vue/web helpers, storage abstraction, and more.",
   "author": "kiki-kanri",
   "license": "MIT",
@@ -75,6 +75,7 @@
     "date-fns": "^4.4.0",
     "decimal.js": "^10.6.0",
     "element-plus": "^2.14.4",
+    "file-type": "^22.1.1",
     "lru-cache": "^11.5.2",
     "millify": "^6.1.0",
     "msgpackr": "^2.0.5",
@@ -109,6 +110,9 @@
     "element-plus": {
       "optional": true
     },
+    "file-type": {
+      "optional": true
+    },
     "lru-cache": {
       "optional": true
     },
@@ -136,12 +140,12 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "^9.5.1",
-    "@kikiutils/eslint-config": "^9.2.1",
+    "@kikiutils/eslint-config": "^9.3.0",
     "@kikiutils/tsconfigs": "^7.0.0",
     "@noble/hashes": "^2.4.0",
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "@types/ssh2": "^1.15.6",
-    "@vitest/coverage-v8": "^5.0.3",
+    "@vitest/coverage-v8": "^5.0.4",
     "async-validator": "^4.2.5",
     "bson": "^7.3.3",
     "changelogen": "^0.6.2",
@@ -151,20 +155,21 @@
     "decimal.js": "^10.6.0",
     "element-plus": "^2.14.7",
     "eslint": "^10.12.0",
-    "jsdom": "^30.1.1",
-    "knip": "^6.39.0",
+    "file-type": "^22.1.1",
+    "jsdom": "^30.1.2",
+    "knip": "^6.41.0",
     "lru-cache": "^11.5.3",
     "millify": "^6.1.0",
     "msgpackr": "^2.1.0",
     "node-ssh": "^13.2.1",
     "pino": "^10.4.0",
-    "pino-pretty": "^13.1.3",
+    "pino-pretty": "^13.2.0",
     "publint": "^0.3.25",
-    "tsdown": "^0.23.0",
+    "tsdown": "^0.23.1",
     "typescript": "^6.0.3",
     "unplugin-unused": "^0.6.0",
-    "vitest": "^5.0.3",
+    "vitest": "^5.0.4",
     "vue": "^3.5.43",
-    "vue-router": "^5.3.1"
+    "vue-router": "^5.4.0"
   }
 }

package/src/file.ts

@@ -0,0 +1,37 @@
+import {
+    fileTypeFromBlob,
+    fileTypeFromBuffer,
+} from 'file-type';
+
+import type { BinaryInput } from './types';
+
+/**
+ * Detects a lowercase MIME type from binary content rather than its name or declared type.
+ *
+ * @remarks
+ * Requires the optional `file-type` peer dependency. Only formats supported by its binary detection
+ * are recognized; this is not a general text-file detector or a guarantee that a file is safe.
+ * Blob and File inputs are read through the detector's tokenizer instead of being fully buffered up front.
+ * The amount of content inspected depends on its format; this does not impose a fixed read limit.
+ * Detection and input-reading errors propagate to the caller.
+ *
+ * @param input - The binary content to inspect.
+ *
+ * @returns The detected lowercase MIME type, or `undefined` when the content is not recognized.
+ *
+ * @example
+ *
+ * ```ts
+ * import { getFileMimeType } from '@kikiutils/shared/file';
+ *
+ * const mimeType = await getFileMimeType(file);
+ * ```
+ */
+export async function getFileMimeType(input: BinaryInput) {
+    // The tokenizer only uses size, slice, and arrayBuffer; Node/DOM Blob stream typings differ.
+    const result = input instanceof ArrayBuffer || input instanceof Uint8Array
+        ? await fileTypeFromBuffer(input)
+        : await fileTypeFromBlob(input as Blob);
+
+    return result?.mime.toLowerCase();
+}

package/src/storages/lru/keyed-store.ts

@@ -7,6 +7,7 @@ import type { LRUCache } from 'lru-cache';
  * The key resolver is called synchronously once per operation, and its exceptions propagate.
  * Reads return the cached value without copying it, or `null` for missing or nullish values.
  * `getItemTtl` exposes the underlying remaining TTL in milliseconds; `setItem` returns the underlying cache.
+ * `setItemWithTtl` accepts its TTL in milliseconds before the value and key arguments and returns the cache.
  * The facade does not dispose the supplied cache, and LRU defaults remain those of the supplied instance.
  *
  * @typeParam D - The stored value type used by reads and writes.
@@ -46,5 +47,8 @@ export function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any,
          */
         resolveKey: (...args: P) => keyFn(...args),
         setItem: (value: D, ...args: P) => lruInstance.set(keyFn(...args), value),
+        setItemWithTtl(ttlMilliseconds: number, value: D, ...args: P) {
+            return lruInstance.set(keyFn(...args), value, { ttl: ttlMilliseconds });
+        },
     });
 }