@kikiutils/shared 13.4.0 → 13.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kikiutils/shared",
   "type": "module",
-  "version": "13.4.0",
+  "version": "13.5.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",
@@ -33,34 +33,38 @@
   ],
   "sideEffects": false,
   "exports": {
-    "./buffer": "./dist/buffer.js",
-    "./clipboard": "./dist/clipboard.js",
-    "./consola": "./dist/consola.js",
-    "./crypto-hash": "./dist/crypto-hash.js",
-    "./datetime": "./dist/datetime.js",
-    "./element-plus": "./dist/element-plus.js",
-    "./enum": "./dist/enum.js",
-    "./env": "./dist/env.js",
-    "./event-awaiter": "./dist/event-awaiter.js",
-    "./general": "./dist/general.js",
-    "./hash": "./dist/hash.js",
-    "./math": "./dist/math.js",
-    "./number": "./dist/number.js",
-    "./object": "./dist/object.js",
-    "./pino": "./dist/pino.js",
-    "./random": "./dist/random.js",
-    "./storage/enhanced/local": "./dist/storage/enhanced/local/index.js",
-    "./storage/enhanced/local/core": "./dist/storage/enhanced/local/core.js",
-    "./storage/enhanced/local/keyed-store": "./dist/storage/enhanced/local/keyed-store.js",
-    "./storage/enhanced/redis": "./dist/storage/enhanced/redis/index.js",
-    "./storage/enhanced/redis/core": "./dist/storage/enhanced/redis/core.js",
-    "./storage/enhanced/redis/keyed-store": "./dist/storage/enhanced/redis/keyed-store.js",
-    "./storage/lru/keyed-store": "./dist/storage/lru/keyed-store.js",
-    "./string": "./dist/string.js",
-    "./url": "./dist/url.js",
-    "./vue": "./dist/vue.js",
-    "./web": "./dist/web.js",
-    "./package.json": "./package.json"
+    "./*": "./dist/*.js",
+    "./package.json": "./package.json",
+    "./storage/enhanced/local": {
+      "types": "./dist/storage/enhanced/local/index.d.ts",
+      "import": "./dist/storage/enhanced/local/index.js",
+      "require": null
+    },
+    "./storage/enhanced/local/index": {
+      "types": null,
+      "import": null,
+      "require": null
+    },
+    "./storage/enhanced/redis": {
+      "types": "./dist/storage/enhanced/redis/index.d.ts",
+      "import": "./dist/storage/enhanced/redis/index.js",
+      "require": null
+    },
+    "./storage/enhanced/redis/index": {
+      "types": null,
+      "import": null,
+      "require": null
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": null,
+      "require": null
+    },
+    "./types/index": {
+      "types": null,
+      "import": null,
+      "require": null
+    }
   },
   "files": [
     "./dist",
@@ -147,26 +151,31 @@
     "@kikiutils/eslint-config": "^3.0.1",
     "@kikiutils/tsconfigs": "^5.0.5",
     "@noble/hashes": "^2.0.0",
-    "@types/node": "^24.5.0",
+    "@types/fs-extra": "^11.0.4",
+    "@types/jsonfile": "^6.1.4",
+    "@types/node": "^24.5.2",
+    "@types/ssh2": "^1.15.5",
     "@vitest/coverage-v8": "^3.2.4",
     "async-validator": "^4.2.5",
+    "bson": "^6.10.4",
     "consola": "^3.4.2",
     "cross-env": "^10.0.0",
     "date-fns": "^4.1.0",
     "decimal.js": "^10.6.0",
     "depcheck": "^1.4.7",
-    "element-plus": "^2.11.2",
+    "element-plus": "^2.11.3",
+    "fs-extra": "^11.3.2",
     "ioredis": "^5.7.0",
     "jsdom": "^27.0.0",
     "lru-cache": "^11.2.1",
     "millify": "^6.1.0",
-    "pino": "^9.9.5",
+    "node-ssh": "^13.2.1",
+    "pino": "^9.10.0",
     "pino-pretty": "^13.1.1",
-    "publint": "^0.3.12",
+    "publint": "^0.3.13",
     "superjson": "^2.2.2",
     "ts-unused-exports": "^11.0.1",
-    "tsconfck": "^3.1.6",
-    "tsdown": "^0.15.1",
+    "tsdown": "^0.15.2",
     "typescript": "^5.9.2",
     "unplugin-unused": "^0.5.3",
     "vitest": "^3.2.4",
@@ -175,7 +184,9 @@
   },
   "pnpm": {
     "onlyBuiltDependencies": [
+      "cpu-features",
       "esbuild",
+      "ssh2",
       "unrs-resolver",
       "vue-demi"
     ]

package/src/classes/path.ts

@@ -0,0 +1,428 @@
+import type { Buffer } from 'node:buffer';
+import type { Abortable } from 'node:events';
+import type * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import {
+    basename,
+    dirname,
+    extname,
+    format,
+    isAbsolute,
+    join,
+    normalize,
+    parse,
+    relative,
+    resolve,
+    toNamespacedPath,
+} from 'node:path';
+import type * as nodePath from 'node:path';
+
+import * as fsExtra from 'fs-extra';
+import type {
+    JFReadOptions,
+    JFWriteOptions,
+} from 'jsonfile';
+
+export type DoNotRemoveOrUseThisType = typeof fsExtra;
+type DropFirstParameters<T extends (...args: any) => any> = Parameters<T> extends [any, ...infer R] ? R : never;
+export type PathLike = fs.PathLike | Path;
+
+/**
+ * Class representing a file system path with various utility methods for path operations.
+ *
+ * All methods in the `Path` class are immutable, returning new instances with modified values
+ * and leaving the original instance unchanged.
+ */
+export class Path {
+    readonly #value: string;
+
+    constructor(...paths: PathLike[]) {
+        this.#value = join(...this.#toStrings(paths));
+    }
+
+    // Symbols
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return this.#value;
+    }
+
+    [Symbol.toPrimitive](hint: string) {
+        if (hint === 'number') throw new TypeError('Cannot convert a Path to a number');
+        return this.#value;
+    }
+
+    // Private methods
+    #newInstance(...paths: PathLike[]) {
+        return new Path(...paths);
+    }
+
+    #toStrings(paths: PathLike[]) {
+        return paths.map((path) => path.toString());
+    }
+
+    // Public getters
+
+    /**
+     * @see {@link nodePath.dirname}
+     */
+    get parent() {
+        return this.dirname();
+    }
+
+    /**
+     * Returns the internal path string value.
+     */
+    get value() {
+        return this.#value;
+    }
+
+    // Public static methods
+
+    /**
+     * @see {@link nodePath.format}
+     */
+    static format(pathObject: nodePath.FormatInputPathObject) {
+        return new Path(format(pathObject));
+    }
+
+    /**
+     * @see {@link nodePath.resolve}
+     */
+    static resolve(...paths: PathLike[]) {
+        return new this(...paths).resolve();
+    }
+
+    // Public base methods
+
+    /**
+     * @see {@link nodePath.basename}
+     */
+    basename(suffix?: string) {
+        return basename(this.#value, suffix);
+    }
+
+    /**
+     * @see {@link nodePath.dirname}
+     */
+    dirname() {
+        return this.#newInstance(dirname(this.#value));
+    }
+
+    /**
+     * @see {@link nodePath.extname}
+     */
+    extname() {
+        return extname(this.#value);
+    }
+
+    /**
+     * @see {@link nodePath.isAbsolute}
+     */
+    isAbsolute() {
+        return isAbsolute(this.#value);
+    }
+
+    /**
+     * @see {@link nodePath.normalize}
+     */
+    normalize() {
+        return this.#newInstance(normalize(this.#value));
+    }
+
+    /**
+     * @see {@link nodePath.join}
+     */
+    join(...paths: PathLike[]) {
+        return this.#newInstance(this.#value, ...this.#toStrings(paths));
+    }
+
+    /**
+     * @see {@link nodePath.parse}
+     */
+    parse() {
+        return parse(this.#value);
+    }
+
+    /**
+     * @see {@link nodePath.relative}
+     */
+    relative(to: PathLike) {
+        return this.#newInstance(relative(this.#value, to.toString()));
+    }
+
+    /**
+     * @see {@link nodePath.resolve}
+     */
+    resolve() {
+        return this.#newInstance(resolve(this.#value));
+    }
+
+    toJSON() {
+        return this.#value;
+    }
+
+    /**
+     * @see {@link nodePath.toNamespacedPath}
+     */
+    toNamespacedPath() {
+        return toNamespacedPath(this.#value);
+    }
+
+    /**
+     * Converts the Path instance to a string.
+     * This method returns the internal path string value,
+     * making it useful for implicit and explicit string conversions.
+     */
+    toString() {
+        return this.#value;
+    }
+
+    // Some commonly used promise fs methods
+
+    /**
+     * @see {@link fsp.access}
+     */
+    access(...args: DropFirstParameters<typeof fsp.access>) {
+        return fsp.access(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.appendFile}
+     */
+    appendFile(...args: DropFirstParameters<typeof fsp.appendFile>) {
+        return fsp.appendFile(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.chmod}
+     */
+    chmod(...args: DropFirstParameters<typeof fsp.chmod>) {
+        return fsp.chmod(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.chown}
+     */
+    chown(...args: DropFirstParameters<typeof fsp.chown>) {
+        return fsp.chown(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.copyFile}
+     */
+    copyFile(...args: DropFirstParameters<typeof fsp.copyFile>) {
+        return fsp.copyFile(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.mkdir}
+     */
+    mkdir(
+        options: fs.MakeDirectoryOptions & {
+            recursive: true;
+        },
+    ): Promise<string>;
+    mkdir(
+        options?:
+          | (fs.MakeDirectoryOptions & {
+              recursive?: false;
+          })
+          | fs.Mode
+          | null,
+    ): Promise<void>;
+    mkdir(options?: fs.MakeDirectoryOptions | fs.Mode | null): Promise<string | undefined>;
+    mkdir(...args: any): any {
+        return fsp.mkdir(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.open}
+     */
+    open(...args: DropFirstParameters<typeof fsp.open>) {
+        return fsp.open(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.readdir}
+     */
+    readdir(
+        path: PathLike,
+        options?:
+          | BufferEncoding
+          | (fs.ObjectEncodingOptions & {
+              recursive?: boolean;
+              withFileTypes?: false;
+          })
+          | null,
+    ): Promise<string[]>;
+    readdir(
+        path: PathLike,
+        options:
+          | 'buffer'
+          | {
+              encoding: 'buffer';
+              recursive?: boolean;
+              withFileTypes?: false;
+          },
+    ): Promise<Buffer[]>;
+    readdir(
+        path: PathLike,
+        options?:
+          | BufferEncoding
+          | (fs.ObjectEncodingOptions & {
+              recursive?: boolean;
+              withFileTypes?: false;
+          })
+          | null,
+    ): Promise<Buffer[] | string[]>;
+    readdir(
+        path: PathLike,
+        options: fs.ObjectEncodingOptions & {
+            recursive?: boolean;
+            withFileTypes: true;
+        },
+    ): Promise<fs.Dirent[]>;
+    readdir(
+        path: PathLike,
+        options: {
+            encoding: 'buffer';
+            recursive?: boolean;
+            withFileTypes: true;
+        },
+    ): Promise<fs.Dirent<Buffer>[]>;
+    readdir(...args: any): any {
+        return fsp.readdir(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.readFile}
+     */
+    readFile(
+        options?:
+          | (Abortable & {
+              encoding?: null;
+              flag?: fs.OpenMode;
+          })
+          | null,
+    ): Promise<Buffer>;
+    readFile(
+        options:
+          | (Abortable & {
+              encoding: BufferEncoding;
+              flag?: fs.OpenMode;
+          })
+          | BufferEncoding,
+    ): Promise<string>;
+    readFile(
+        options?:
+            | (
+              & Abortable
+              & fs.ObjectEncodingOptions
+              & { flag?: fs.OpenMode }
+            )
+            | BufferEncoding
+            | null,
+    ): Promise<Buffer | string>;
+    readFile(...args: any): any {
+        return fsp.readFile(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.rename}
+     */
+    rename(newPath: PathLike) {
+        return fsp.rename(this.#value, newPath.toString());
+    }
+
+    /**
+     * @see {@link fsp.rm}
+     */
+    rm(...args: DropFirstParameters<typeof fsp.rm>) {
+        return fsp.rm(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.rmdir}
+     */
+    rmdir(...args: DropFirstParameters<typeof fsp.rmdir>) {
+        return fsp.rmdir(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.stat}
+     */
+    stat(
+        opts?: fs.StatOptions & {
+            bigint?: false;
+        },
+    ): Promise<fs.Stats>;
+    stat(
+        opts: fs.StatOptions & {
+            bigint: true;
+        },
+    ): Promise<fs.BigIntStats>;
+    stat(opts?: fs.StatOptions): Promise<fs.BigIntStats | fs.Stats>;
+    stat(...args: any): any {
+        return fsp.stat(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.truncate}
+     */
+    truncate(...args: DropFirstParameters<typeof fsp.truncate>) {
+        return fsp.truncate(this.#value, ...args);
+    }
+
+    /**
+     * @see {@link fsp.unlink}
+     */
+    unlink() {
+        return fsp.unlink(this.#value);
+    }
+
+    /**
+     * @see {@link fsp.writeFile}
+     */
+    writeFile(...args: DropFirstParameters<typeof fsp.writeFile>) {
+        return fsp.writeFile(this.#value, ...args);
+    }
+
+    // Some commonly used promise fs extra methods
+
+    /**
+     * @see {@link fsExtra.ensureDir}
+     */
+    ensureDir(options?: fsExtra.EnsureDirOptions | number) {
+        return fsExtra.ensureDir(this.#value, options);
+    }
+
+    /**
+     * @see {@link fsExtra.ensureDir}
+     */
+    mkdirp = this.ensureDir;
+
+    /**
+     * @see {@link fsExtra.ensureDir}
+     */
+    mkdirs = this.ensureDir;
+
+    /**
+     * @see {@link fsExtra.readJson}
+     */
+    async readJson<T = any>(options?: JFReadOptions) {
+        return await fsExtra.readJson(this.#value, options) as T;
+    }
+
+    /**
+     * @see {@link fsExtra.remove}
+     */
+    remove() {
+        return fsExtra.remove(this.#value);
+    }
+
+    /**
+     * @see {@link fsExtra.writeJson}
+     */
+    writeJson(data: any, options?: JFWriteOptions) {
+        return fsExtra.writeJson(this.#value, data, options);
+    }
+}