@kikiutils/shared 13.4.0 → 13.5.0

package/src/classes/precision-number.ts

@@ -0,0 +1,180 @@
+import { Decimal } from 'decimal.js';
+
+export type PrecisionNumberValue = Decimal.Value | PrecisionNumber | { toString: () => string };
+
+/**
+ * Class representing a precision number with configurable decimal places and rounding.
+ *
+ * This class leverages the Decimal.js library to ensure accurate arithmetic operations
+ * with floating point numbers. It provides methods for various arithmetic operations
+ * (addition, subtraction, multiplication, division) as well as comparison and utility
+ * methods to check the state of the number (e.g., if it is finite, an integer, zero, etc.).
+ *
+ * The class also includes custom symbol methods to support Node.js inspection and primitive
+ * type conversion.
+ *
+ * The class supports in-place modification methods that alter the current instance's value,
+ * such as `plus`, `minus`, `times`, `dividedBy`, and others. Additionally, methods prefixed
+ * with `to` (e.g., `toPlus`, `toMinus`) return a new instance of `PrecisionNumber` with the
+ * modified value, leaving the original instance unchanged.
+ */
+export class PrecisionNumber {
+    // Private properties
+    readonly #decimalPlaces: number;
+    readonly #rounding: Decimal.Rounding;
+    #decimal: Decimal;
+
+    constructor(
+        value: PrecisionNumberValue = '0',
+        decimalPlaces: number = 2,
+        rounding: Decimal.Rounding = Decimal.ROUND_DOWN,
+    ) {
+        this.#decimalPlaces = decimalPlaces;
+        this.#rounding = rounding;
+        this.#decimal = this.#decimalToFixedDecimal(new Decimal(value.toString().trim()));
+    }
+
+    // Symbols
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return this.value;
+    }
+
+    [Symbol.toPrimitive](hint: string) {
+        if (hint === 'number') return this.#decimal.toNumber();
+        return this.value;
+    }
+
+    // Private methods
+    #decimalToFixedDecimal(decimal: Decimal) {
+        return decimal.toDecimalPlaces(this.#decimalPlaces, this.#rounding);
+    }
+
+    // Public getters
+    get value() {
+        return this.#decimal.toFixed(this.#decimalPlaces, this.#rounding);
+    }
+
+    // Static methods
+    static toFixed(
+        value: PrecisionNumberValue,
+        decimalPlaces: number = 2,
+        rounding: Decimal.Rounding = Decimal.ROUND_DOWN,
+    ) {
+        return new Decimal(value.toString().trim()).toFixed(decimalPlaces, rounding);
+    }
+
+    // Public methods
+    absoluteValue() {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.absoluteValue());
+        return this;
+    }
+
+    dividedBy(value: PrecisionNumberValue) {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.dividedBy(value.toString().trim()));
+        return this;
+    }
+
+    equals(value: PrecisionNumberValue) {
+        return this.#decimal.equals(value.toString().trim());
+    }
+
+    gt(value: PrecisionNumberValue) {
+        return this.#decimal.gt(value.toString().trim());
+    }
+
+    gte(value: PrecisionNumberValue) {
+        return this.#decimal.gte(value.toString().trim());
+    }
+
+    isFinite() {
+        return this.#decimal.isFinite();
+    }
+
+    isInteger() {
+        return this.#decimal.isInteger();
+    }
+
+    isNaN() {
+        return this.#decimal.isNaN();
+    }
+
+    isNegative() {
+        return this.#decimal.isNegative();
+    }
+
+    isPositive() {
+        return this.#decimal.isPositive();
+    }
+
+    isZero() {
+        return this.#decimal.isZero();
+    }
+
+    lt(value: PrecisionNumberValue) {
+        return this.#decimal.lt(value.toString().trim());
+    }
+
+    lte(value: PrecisionNumberValue) {
+        return this.#decimal.lte(value.toString().trim());
+    }
+
+    minus(value: PrecisionNumberValue) {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.minus(value.toString().trim()));
+        return this;
+    }
+
+    negate() {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.negated());
+        return this;
+    }
+
+    plus(value: PrecisionNumberValue) {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.plus(value.toString().trim()));
+        return this;
+    }
+
+    times(value: PrecisionNumberValue) {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.times(value.toString().trim()));
+        return this;
+    }
+
+    toAbsoluteValue() {
+        return new PrecisionNumber(this.#decimal.absoluteValue(), this.#decimalPlaces, this.#rounding);
+    }
+
+    toDividedBy(value: PrecisionNumberValue) {
+        return new PrecisionNumber(
+            this.#decimal.dividedBy(value.toString().trim()),
+            this.#decimalPlaces,
+            this.#rounding,
+        );
+    }
+
+    toJSON() {
+        return this.value;
+    }
+
+    toMinus(value: PrecisionNumberValue) {
+        return new PrecisionNumber(this.#decimal.minus(value.toString().trim()), this.#decimalPlaces, this.#rounding);
+    }
+
+    toNegated() {
+        return new PrecisionNumber(this.#decimal.negated(), this.#decimalPlaces, this.#rounding);
+    }
+
+    toPlus(value: PrecisionNumberValue) {
+        return new PrecisionNumber(this.#decimal.plus(value.toString().trim()), this.#decimalPlaces, this.#rounding);
+    }
+
+    toString() {
+        return this.value;
+    }
+
+    toFixed(decimalPlaces: number = this.#decimalPlaces, rounding: Decimal.Rounding = this.#rounding) {
+        return this.#decimal.toFixed(decimalPlaces, rounding);
+    }
+
+    toTimes(value: PrecisionNumberValue) {
+        return new PrecisionNumber(this.#decimal.times(value.toString().trim()), this.#decimalPlaces, this.#rounding);
+    }
+}

package/src/classes/ssh-client.ts

@@ -0,0 +1,174 @@
+import { createConsola } from 'consola';
+import type { ConsolaInstance } from 'consola';
+import { NodeSSH } from 'node-ssh';
+import type {
+    Config,
+    SSHExecCommandOptions,
+    SSHGetPutDirectoryOptions,
+    SSHPutFilesOptions,
+} from 'node-ssh';
+import type {
+    SFTPWrapper,
+    TransferOptions,
+} from 'ssh2';
+
+import type { Nullable } from '../types';
+
+import type { PathLike } from './path';
+
+const loggerLevelStringToConsolaLogLevelMap = {
+    debug: 4,
+    error: 0,
+    fatal: 0,
+    info: 3,
+    normal: 2,
+    silent: -999,
+    trace: 5,
+    verbose: 999,
+    warn: 1,
+} as const;
+
+export class SshClient {
+    readonly #connectConfig: Config;
+    readonly #logger: ConsolaInstance;
+
+    #nodeSsh: NodeSSH;
+
+    constructor(host: string, username: string, password: string, port: number = 22, connectConfig?: Config) {
+        this.#connectConfig = {
+            ...connectConfig,
+            host,
+            password,
+            port,
+            username,
+        };
+
+        this.#logger = createConsola();
+        this.#nodeSsh = new NodeSSH();
+        if (process.env.NODE_ENV === 'production') this.setLoggerLevel('error');
+    }
+
+    get nodeSsh() {
+        return this.#nodeSsh;
+    }
+
+    async connect() {
+        try {
+            this.#nodeSsh = await this.#nodeSsh.connect(this.#connectConfig);
+            return true;
+        } catch (error) {
+            this.#logger.error(error);
+            return false;
+        }
+    }
+
+    disconnect() {
+        try {
+            this.#nodeSsh.dispose();
+            return true;
+        } catch (error) {
+            this.#logger.error(error);
+            return false;
+        }
+    }
+
+    execCommand(command: string, options?: SSHExecCommandOptions) {
+        return this.#nodeSsh.execCommand(command, options).catch(() => {});
+    }
+
+    execCommandWithIo(command: string, options?: SSHExecCommandOptions) {
+        return this.execCommand(
+            command,
+            {
+                ...options,
+                onStderr: (data) => process.stderr.write(data.toString()),
+                onStdout: (data) => process.stdout.write(data.toString()),
+            },
+        );
+    }
+
+    getDir = this.getDirectory;
+
+    async getDirectory(localDirectory: PathLike, remoteDirectory: PathLike, options?: SSHGetPutDirectoryOptions) {
+        try {
+            return await this.#nodeSsh.getDirectory(localDirectory.toString(), remoteDirectory.toString(), options);
+        } catch (error) {
+            this.#logger.error(error);
+            return false;
+        }
+    }
+
+    async getFile(
+        localFile: PathLike,
+        remoteFile: PathLike,
+        givenSftp?: Nullable<SFTPWrapper>,
+        transferOptions?: Nullable<TransferOptions>,
+    ) {
+        try {
+            await this.#nodeSsh.getFile(localFile.toString(), remoteFile.toString(), givenSftp, transferOptions);
+            return true;
+        } catch (error) {
+            this.#logger.error(error);
+            return false;
+        }
+    }
+
+    isConnected() {
+        return this.#nodeSsh.isConnected();
+    }
+
+    async mkdir(path: PathLike) {
+        try {
+            await this.#nodeSsh.mkdir(path.toString());
+            return true;
+        } catch (error) {
+            this.#logger.error(error);
+            return false;
+        }
+    }
+
+    putDir = this.putDirectory;
+
+    async putDirectory(localDirectory: PathLike, remoteDirectory: PathLike, options?: SSHGetPutDirectoryOptions) {
+        try {
+            return await this.#nodeSsh.putDirectory(localDirectory.toString(), remoteDirectory.toString(), options);
+        } catch (error) {
+            this.#logger.error(error);
+            return false;
+        }
+    }
+
+    async putFile(
+        localFile: PathLike,
+        remoteFile: PathLike,
+        givenSftp?: Nullable<SFTPWrapper>,
+        transferOptions?: Nullable<TransferOptions>,
+    ) {
+        try {
+            await this.#nodeSsh.putFile(localFile.toString(), remoteFile.toString(), givenSftp, transferOptions);
+            return true;
+        } catch (error) {
+            this.#logger.error(error);
+            return false;
+        }
+    }
+
+    async putFiles(files: { local: PathLike; remote: PathLike }[], options?: SSHPutFilesOptions) {
+        try {
+            const convertedFiles = files.map(({ local, remote }) => ({
+                local: local.toString(),
+                remote: remote.toString(),
+            }));
+
+            await this.#nodeSsh.putFiles(convertedFiles, options);
+            return true;
+        } catch (error) {
+            this.#logger.error(error);
+            return false;
+        }
+    }
+
+    setLoggerLevel(level: keyof typeof loggerLevelStringToConsolaLogLevelMap) {
+        this.#logger.level = loggerLevelStringToConsolaLogLevelMap[level];
+    }
+}

package/src/types/filtered-key-path.ts

@@ -0,0 +1,46 @@
+import type { ObjectId } from 'bson';
+
+/**
+ * The following types are based on or inspired by types from the Element Plus project.
+ * Source: https://github.com/element-plus/element-plus
+ * License: MIT (https://opensource.org/licenses/MIT)
+ *
+ * Original types might have been modified to suit this project’s needs.
+ */
+
+/***/
+type ConditionalPath<K extends number | string, V, U> = V extends U ? `${K}` : DefaultPath<K, V, U, never>;
+type DefaultPath<
+    K extends number | string,
+    V,
+    U = never,
+    RK = `${K}`,
+> = V extends TerminalType ? RK : `${K}.${FilteredKeyPath<V, U>}`;
+
+/**
+ * A utility type that generates a union of key paths from a given object type `T`,
+ * filtered by a specific type `U`. If `U` is
+ * not provided, it defaults to including all key paths.
+ *
+ * @template T - The object type to traverse.
+ * @template U - The type used to filter key paths. Defaults to `never`, meaning no filtering.
+ */
+// eslint-disable-next-line style/max-len
+export type FilteredKeyPath<T, U = never> = T extends ReadonlyArray<infer V> ? (IsTuple<T> extends true ? { [K in TupleKey<T>]-?: PathImpl<Exclude<K, symbol>, T[K], U> }[TupleKey<T>] : PathImpl<number, V, U>) : { [K in keyof T]-?: PathImpl<Exclude<K, symbol>, T[K], U> }[keyof T];
+type IsTuple<T extends ReadonlyArray<any>> = number extends T['length'] ? false : true;
+type PathImpl<K extends number | string, V, U> = [U] extends [never] ? DefaultPath<K, V> : ConditionalPath<K, V, U>;
+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[]>;

package/src/types/index.ts

@@ -0,0 +1,18 @@
+import type {
+    Buffer,
+    Blob as NodeBlob,
+    File as NodeFile,
+} from 'node:buffer';
+
+export type { FilteredKeyPath } from './filtered-key-path';
+
+export type AnyRecord = Record<string, any>;
+export type BinaryInput = Blob | Buffer | File | NodeBlob | NodeFile;
+export type Booleanish = 'false' | 'true' | boolean;
+export type MaybePartial<T> = Partial<T> | T;
+export type MaybeReadonly<T> = Readonly<T> | T;
+export type Nullable<T> = null | T;
+export type Numberish = number | string;
+export type PartialRecord<K extends keyof any, T> = Partial<Record<K, T>>;
+export type ReadonlyPartialRecord<K extends keyof any, T> = Readonly<PartialRecord<K, T>>;
+export type ReadonlyRecord<K extends keyof any, T> = Readonly<Record<K, T>>;

package/src/types/vue.ts

@@ -0,0 +1,18 @@
+import type { GlobalComponents } from 'vue';
+
+import type { Nullable } from './';
+
+/**
+ * A type that represents a reference to a Vue component instance.
+ * The reference can be either an instance of the specified component or null.
+ *
+ * @template K - The key of the component in the GlobalComponents.
+ *
+ * @example
+ * ```typescript
+ * import type { ComponentRef } from '@kikiutils/types/vue';
+ *
+ * const keepAliveRef = ref<ComponentRef<'KeepAlive'>>(null);
+ * ```
+ */
+export type ComponentRef<K extends keyof GlobalComponents> = Nullable<InstanceType<GlobalComponents[K]>>;

package/src/vue.ts

@@ -5,7 +5,8 @@ import {
     useRoute,
 } from 'vue-router';
 
-import { appendRedirectParamToUrl } from '@/url';
+import type { Nullable } from './types';
+import { appendRedirectParamToUrl } from './url';
 
 /**
  * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.
@@ -21,9 +22,9 @@ export function appendRedirectParamFromCurrentRouteToUrl(url: string) {
 /**
  * Clears an interval referenced by a Vue ref and sets it to null.
  *
- * @param {Ref<null | ReturnType<typeof setInterval>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null
+ * @param {Ref<Nullable<ReturnType<typeof setInterval>>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null
  */
-export function clearIntervalRef(intervalRef: Ref<null | ReturnType<typeof setInterval>>) {
+export function clearIntervalRef(intervalRef: Ref<Nullable<ReturnType<typeof setInterval>>>) {
     if (intervalRef.value) clearInterval(intervalRef.value);
     intervalRef.value = null;
 }
@@ -31,9 +32,9 @@ export function clearIntervalRef(intervalRef: Ref<null | ReturnType<typeof setIn
 /**
  * Clears a timeout referenced by a Vue ref and sets it to null.
  *
- * @param {Ref<null | ReturnType<typeof setTimeout>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null
+ * @param {Ref<Nullable<ReturnType<typeof setTimeout>>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null
  */
-export function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof setTimeout>>) {
+export function clearTimeoutRef(timeoutRef: Ref<Nullable<ReturnType<typeof setTimeout>>>) {
     if (timeoutRef.value) clearTimeout(timeoutRef.value);
     timeoutRef.value = null;
 }
@@ -44,9 +45,9 @@ export function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof setTime
  *
  * @template T - The type of the scrollable element (defaults to HTMLElement)
  *
- * @param {Ref<null | T>} containerRef - A ref to the scrollable HTML element
+ * @param {Ref<Nullable<T>>} containerRef - A ref to the scrollable HTML element
  */
-export function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<null | T>) {
+export function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<Nullable<T>>) {
     let scrollLeft = 0;
     let scrollTop = 0;
     onActivated(() => {

package/src/web.ts

@@ -1,4 +1,4 @@
-import { appendRedirectParamToUrl } from '@/url';
+import { appendRedirectParamToUrl } from './url';
 
 /**
  * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.