@kikiutils/shared 9.0.0

package/dist/string.mjs

@@ -0,0 +1,42 @@
+const DIGITS = '0123456789';
+const LOWERCASE = 'abcdefghijklmnopqrstuvwxyz';
+const UPPERCASE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const CHARSETS = {
+    'alphabetic': LOWERCASE + UPPERCASE,
+    'alphanumeric': DIGITS + LOWERCASE + UPPERCASE,
+    'lowercase': LOWERCASE,
+    'lowercase-numeric': DIGITS + LOWERCASE,
+    'numeric': DIGITS,
+    'uppercase': UPPERCASE,
+    'uppercase-numeric': DIGITS + UPPERCASE,
+};
+/**
+ * Generates a random string of a given length using a specified character set.
+ *
+ * @param {number} length - The length of the string to generate. Must be a positive integer.
+ * @param {RandomStringMode} [mode] - The character set to use.
+ * @returns {string} The generated random string.
+ *
+ * @throws {Error} If the length is not a positive integer or the mode is unsupported.
+ *
+ * @example
+ * ```typescript
+ * import { randomString } from '@kikiutils/shared/string';
+ *
+ * console.log(randomString(8)); // e.g. 'aZbXwTyQ' (alphabetic)
+ * console.log(randomString(6, 'numeric')); // e.g. '402398'
+ * console.log(randomString(10, 'alphanumeric')); // e.g. 'a9Z4pQ8xY2'
+ * ```
+ */
+function randomString(length, mode = 'alphabetic') {
+    if (!Number.isInteger(length) || length <= 0) {
+        throw new Error(`Invalid length: ${length}. Must be a positive integer.`);
+    }
+    const charset = CHARSETS[mode];
+    if (!charset)
+        throw new Error(`Unsupported mode: ${mode}`);
+    return Array.from({ length }, () => charset[Math.floor(Math.random() * charset.length)]).join('');
+}
+
+export { randomString };
+//# sourceMappingURL=string.mjs.map

package/dist/string.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.mjs","sources":["../src/string.ts"],"sourcesContent":["export type RandomStringMode =\n  | 'alphabetic'\n  | 'alphanumeric'\n  | 'lowercase'\n  | 'lowercase-numeric'\n  | 'numeric'\n  | 'uppercase'\n  | 'uppercase-numeric';\n\nconst DIGITS = '0123456789';\nconst LOWERCASE = 'abcdefghijklmnopqrstuvwxyz';\nconst UPPERCASE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';\nconst CHARSETS: Record<RandomStringMode, string> = {\n    'alphabetic': LOWERCASE + UPPERCASE,\n    'alphanumeric': DIGITS + LOWERCASE + UPPERCASE,\n    'lowercase': LOWERCASE,\n    'lowercase-numeric': DIGITS + LOWERCASE,\n    'numeric': DIGITS,\n    'uppercase': UPPERCASE,\n    'uppercase-numeric': DIGITS + UPPERCASE,\n};\n\n/**\n * Generates a random string of a given length using a specified character set.\n *\n * @param {number} length - The length of the string to generate. Must be a positive integer.\n * @param {RandomStringMode} [mode] - The character set to use.\n * @returns {string} The generated random string.\n *\n * @throws {Error} If the length is not a positive integer or the mode is unsupported.\n *\n * @example\n * ```typescript\n * import { randomString } from '@kikiutils/shared/string';\n *\n * console.log(randomString(8)); // e.g. 'aZbXwTyQ' (alphabetic)\n * console.log(randomString(6, 'numeric')); // e.g. '402398'\n * console.log(randomString(10, 'alphanumeric')); // e.g. 'a9Z4pQ8xY2'\n * ```\n */\nexport function randomString(length: number, mode: RandomStringMode = 'alphabetic') {\n    if (!Number.isInteger(length) || length <= 0) {\n        throw new Error(`Invalid length: ${length}. Must be a positive integer.`);\n    }\n\n    const charset = CHARSETS[mode];\n    if (!charset) throw new Error(`Unsupported mode: ${mode}`);\n    return Array.from({ length }, () => charset[Math.floor(Math.random() * charset.length)]).join('');\n}\n"],"names":[],"mappings":"AASA,MAAM,MAAM,GAAG,YAAY;AAC3B,MAAM,SAAS,GAAG,4BAA4B;AAC9C,MAAM,SAAS,GAAG,4BAA4B;AAC9C,MAAM,QAAQ,GAAqC;IAC/C,YAAY,EAAE,SAAS,GAAG,SAAS;AACnC,IAAA,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;AAC9C,IAAA,WAAW,EAAE,SAAS;IACtB,mBAAmB,EAAE,MAAM,GAAG,SAAS;AACvC,IAAA,SAAS,EAAE,MAAM;AACjB,IAAA,WAAW,EAAE,SAAS;IACtB,mBAAmB,EAAE,MAAM,GAAG,SAAS;CAC1C;AAED;;;;;;;;;;;;;;;;;AAiBG;SACa,YAAY,CAAC,MAAc,EAAE,OAAyB,YAAY,EAAA;AAC9E,IAAA,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE;AAC1C,QAAA,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,CAAA,6BAAA,CAA+B,CAAC;;AAG7E,IAAA,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC;AAC9B,IAAA,IAAI,CAAC,OAAO;AAAE,QAAA,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,CAAA,CAAE,CAAC;AAC1D,IAAA,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;AACrG;;;;"}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@kikiutils/shared",
+  "version": "9.0.0",
+  "description": "A lightweight modular utility library for JavaScript and TypeScript, offering secure hashing, flexible logging, date utilities, Vue/web helpers, and more.",
+  "author": "kiki-kanri",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kikiutils/node-shared.git"
+  },
+  "keywords": [
+    "browser",
+    "consola",
+    "crypto",
+    "datetime",
+    "enum",
+    "env",
+    "hashing",
+    "javascript",
+    "logging",
+    "math",
+    "node",
+    "pino",
+    "string",
+    "typescript",
+    "url",
+    "utilities",
+    "utils",
+    "vue",
+    "web"
+  ],
+  "sideEffects": false,
+  "exports": {
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.mjs",
+      "require": "./dist/*.cjs"
+    }
+  },
+  "files": [
+    "./dist",
+    "./src"
+  ],
+  "engines": {
+    "node": ">=18.12.1"
+  },
+  "scripts": {
+    "build": "ts-project-builder './src/**/*.ts' --clean --sourcemaps",
+    "bumplog": "changelogen --bump --hideAuthorEmail",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "prepack": "pnpm run build",
+    "release": "pnpm run lint && pnpm run test && pnpm run build && changelogen --hideAuthorEmail --push --release && npm publish",
+    "test": "tsc -p ./tsconfig.test-check.json && cross-env TZ=UTC jest --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@kikiutils/changelogen": "^0.8.0",
+    "@kikiutils/eslint-config": "^1.0.1",
+    "@kikiutils/tsconfigs": "^5.0.1",
+    "@noble/hashes": "^1.8.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.15.3",
+    "consola": "^3.4.2",
+    "cross-env": "^7.0.3",
+    "date-fns": "^4.1.0",
+    "decimal.js": "^10.5.0",
+    "jest": "^29.7.0",
+    "millify": "^6.1.0",
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.0.0",
+    "ts-jest": "^29.3.2",
+    "ts-project-builder": "5.0.1",
+    "typescript": "^5.8.3"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "unrs-resolver"
+    ]
+  }
+}

package/src/consola.ts

@@ -0,0 +1,27 @@
+import { createConsola } from 'consola';
+
+/**
+ * A consola logger instance.
+ *
+ * The logger's level is determined based on the `CONSOLA_LOGGER_LEVEL` and `NODE_ENV` environment variables.
+ * If `CONSOLA_LOGGER_LEVEL` is set, it will be used; otherwise, if `NODE_ENV` is `production`,
+ * the level will be set to `0`.
+ *
+ * To manually change the level, assign the desired level to `logger.level`.
+ *
+ * See available levels [here](https://github.com/unjs/consola?tab=readme-ov-file#log-level).
+ *
+ * @example
+ * ```typescript
+ * import logger from '@kikiutils/shared/consola';
+ *
+ * logger.info('test'); // ℹ test 3:56:30 AM
+ *
+ * // Manually change the level
+ * logger.level = 3;
+ * ```
+ */
+export const consolaLogger = createConsola();
+export const logger = consolaLogger;
+if (process.env.CONSOLA_LOGGER_LEVEL !== undefined) consolaLogger.level = +process.env.CONSOLA_LOGGER_LEVEL;
+else consolaLogger.level = process.env.NODE_ENV === 'production' ? 0 : consolaLogger.level;

package/src/crypto-hash.ts

@@ -0,0 +1,60 @@
+/**
+ * This file provides a set of functions for creating hash digests using different algorithms and bit lengths.
+ * It includes functions for generating SHA-3 hash digests with bit lengths of 224, 256, 384, and 512,
+ * as well as a function for generating MD5 hash digests.
+ * These functions use the Node.js crypto module to generate the hashes.
+ * Can only be used in Node.js/Deno/Bun runtimes.
+ *
+ * @example
+ * ```typescript
+ * import { cryptoSha3256 } from '@kikiutils/shared/crypto-hash';
+ *
+ * console.log(cryptoSha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
+ * ```
+ */
+
+import { createHash } from 'node:crypto';
+import type {
+    BinaryLike,
+    BinaryToTextEncoding,
+} from 'node:crypto';
+
+export function cryptoMd5(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
+    return createHash('md5').update(data).digest(outputEncoding);
+}
+
+export function cryptoMd5ToBuffer(data: BinaryLike) {
+    return createHash('md5').update(data).digest();
+}
+
+export function cryptoSha3224(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
+    return createHash('sha3-224').update(data).digest(outputEncoding);
+}
+
+export function cryptoSha3224ToBuffer(data: BinaryLike) {
+    return createHash('sha3-224').update(data).digest();
+}
+
+export function cryptoSha3256(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
+    return createHash('sha3-256').update(data).digest(outputEncoding);
+}
+
+export function cryptoSha3256ToBuffer(data: BinaryLike) {
+    return createHash('sha3-256').update(data).digest();
+}
+
+export function cryptoSha3384(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
+    return createHash('sha3-384').update(data).digest(outputEncoding);
+}
+
+export function cryptoSha3384ToBuffer(data: BinaryLike) {
+    return createHash('sha3-384').update(data).digest();
+}
+
+export function cryptoSha3512(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
+    return createHash('sha3-512').update(data).digest(outputEncoding);
+}
+
+export function cryptoSha3512ToBuffer(data: BinaryLike) {
+    return createHash('sha3-512').update(data).digest();
+}

package/src/datetime.ts

@@ -0,0 +1,154 @@
+import {
+    format as dateFnsFormat,
+    endOfDay,
+    endOfMonth,
+    endOfWeek,
+    startOfDay,
+    startOfMonth,
+    startOfWeek,
+    subDays,
+    subMonths,
+    subWeeks,
+} from 'date-fns';
+import type {
+    DateArg,
+    Day,
+    FormatOptions,
+} from 'date-fns';
+
+export type DateRangeType = 'lastMonth' | 'lastWeek' | 'thisMonth' | 'thisWeek' | 'today' | 'yesterday';
+
+/**
+ * Formats a given date, timestamp, or date string into a specified format.
+ *
+ * This function is a wrapper around `date-fns/format`.
+ *
+ * @param {DateArg<Date>} date - The input date to format. Can be a Date object, a timestamp, or a string.
+ * @param {string} [format] - The target format string.
+ * @param {FormatOptions} [options] - Optional formatting options passed to `date-fns/format`.
+ * @returns {string} The formatted date string.
+ *
+ * @example
+ * ```typescript
+ * import { formatDate } from '@kikiutils/shared/datetime';
+ *
+ * // Format a Date object
+ * console.log(formatDate(new Date(), 'yyyy-MM-dd')); // 2024-07-10
+ *
+ * // Format a timestamp
+ * console.log(formatDate(1657814400000, 'yyyy-MM-dd')); // 2022-07-15
+ *
+ * // Format a date string
+ * console.log(formatDate('2024-07-10T00:00:00Z', 'yyyy-MM-dd')); // 2024-07-10
+ * ```
+ *
+ * @see https://date-fns.org/docs/format
+ */
+export function formatDate(date: DateArg<Date> & {}, format: string = 'yyyy-MM-dd HH:mm:ss', options?: FormatOptions) {
+    return dateFnsFormat(date, format, options);
+}
+
+/**
+ * Get the date range (start and end) based on a given date and range type.
+ *
+ * Supports common range types like 'lastMonth', 'lastWeek', 'thisMonth', 'thisWeek', 'today', and 'yesterday'.
+ *
+ * @param {Date} date - The reference date.
+ * @param {DateRangeType} type - The range type to compute.
+ * @param {object} [options] - Optional settings.
+ * @param {boolean} [options.setEndDateToNextDayStart] - If true, set `endDate` to 00:00:00.000 of the next day.
+ * @param {Day} [options.weekStartsOn] - The start day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday).
+ * @returns {{ startDate: Date, endDate: Date }} An object with `startDate` and `endDate`.
+ *
+ * @example
+ * ```typescript
+ * import { getDateRangeFromDate } from '@kikiutils/shared/datetime';
+ *
+ * // Get the date range for last month
+ * const date = new Date('2023-07-01');
+ * console.log(getDateRangeFromDate(date, 'lastMonth'));
+ * // { startDate: 2023-06-01T00:00:00.000Z, endDate: 2023-06-30T23:59:59.999Z }
+ *
+ * // Get this week's range with Sunday as the first day
+ * console.log(getDateRangeFromDate(date, 'thisWeek', { weekStartsOn: 0 }));
+ * // { startDate: 2023-06-25T00:00:00.000Z, endDate: 2023-07-01T23:59:59.999Z }
+ * ```
+ */
+export function getDateRangeFromDate(
+    date: Date,
+    type: DateRangeType,
+    options?: {
+        setEndDateToNextDayStart?: boolean;
+        weekStartsOn?: Day;
+    },
+) {
+    let endDate: Date;
+    let startDate: Date;
+    switch (type) {
+        case 'lastMonth':
+            {
+                const lastMonth = subMonths(date, 1);
+                endDate = endOfMonth(lastMonth);
+                startDate = startOfMonth(lastMonth);
+            }
+
+            break;
+        case 'lastWeek':
+            {
+                const lastWeek = subWeeks(date, 1);
+                endDate = endOfWeek(lastWeek, { weekStartsOn: options?.weekStartsOn ?? 1 });
+                startDate = startOfWeek(lastWeek, { weekStartsOn: options?.weekStartsOn ?? 1 });
+            }
+
+            break;
+        case 'thisMonth':
+            endDate = endOfMonth(date);
+            startDate = startOfMonth(date);
+            break;
+        case 'thisWeek':
+            endDate = endOfWeek(date, { weekStartsOn: options?.weekStartsOn ?? 1 });
+            startDate = startOfWeek(date, { weekStartsOn: options?.weekStartsOn ?? 1 });
+            break;
+        case 'today':
+            endDate = endOfDay(date);
+            startDate = startOfDay(date);
+            break;
+        case 'yesterday':
+            {
+                const yesterday = subDays(date, 1);
+                endDate = endOfDay(yesterday);
+                startDate = startOfDay(yesterday);
+            }
+
+            break;
+        default: throw new Error(`Unsupported date range type: ${type}.`);
+    }
+
+    if (options?.setEndDateToNextDayStart) endDate.setHours(24, 0, 0, 0);
+    return {
+        endDate,
+        startDate,
+    };
+}
+
+/**
+ * Returns a `Date` object set to midnight (00:00:00) of today, with an optional day offset.
+ *
+ * @param {number} [offsetDays] - Number of days to offset from today. Can be negative.
+ * @returns {Date} A `Date` object at 00:00:00 of the offset day.
+ *
+ * @example
+ * ```typescript
+ * import { getMidnightDateFromToday } from '@kikiutils/shared/datetime';
+ *
+ * console.log(getMidnightDateFromToday()); // today at 00:00:00
+ * console.log(getMidnightDateFromToday(3)); // 3 days from today at 00:00:00
+ * console.log(getMidnightDateFromToday(-1)); // yesterday at 00:00:00
+ * ```
+ */
+export function getMidnightDateFromToday(offsetDays: number = 0) {
+    const date = new Date();
+    date.setDate(date.getDate() + offsetDays);
+    date.setHours(0, 0, 0, 0);
+    return date;
+}

package/src/enum.ts

@@ -0,0 +1,60 @@
+/**
+ * Extracts the numeric values from an enumeration-like object.
+ *
+ * @param {Record<number | string, number | string>} data - The enumeration-like object to extract numeric values from.
+ * The keys can be numbers or strings, and the values can be numbers or strings.
+ * @returns {number[]} An array of numeric values extracted from the object.
+ *
+ * @example
+ * ```typescript
+ * import { getEnumNumberValues } from '@kikiutils/shared/enum';
+ *
+ * enum RecordType {
+ *   Receive = 0,
+ *   Send = 1,
+ *   Unknown = 'unknown'
+ * }
+ *
+ * console.log(getEnumNumberValues(RecordType)); // [0, 1]
+ * ```
+ */
+export function getEnumNumberValues(data: Record<number | string, number | string>) {
+    return Object.values(data).filter((value) => typeof value === 'number');
+}
+
+/**
+ * Extracts the string values from an enumeration-like object.
+ *
+ * @param {Record<number | string, number | string>} data - The enumeration-like object to extract string values from.
+ * The keys can be numbers or strings, and the values can be numbers or strings.
+ * @returns {string[]} An array of string values extracted from the object.
+ *
+ * @example
+ * ```typescript
+ * import { getEnumStringValues } from '@kikiutils/shared/enum';
+ *
+ * enum RecordType {
+ *   Receive = 0,
+ *   Send = 1,
+ *   Unknown = 'unknown'
+ * }
+ *
+ * console.log(getEnumStringValues(RecordType)); // ['unknown']
+ * ```
+ */
+export function getEnumStringValues(data: Record<number | string, number | string>) {
+    const keys: string[] = [];
+    const keysCount: Record<string, number> = {};
+    const values: any[] = [];
+    Object.entries(data).forEach(([key, value]) => {
+        keys.push(key);
+        values.push(value);
+        if (typeof value !== 'string') return;
+        keysCount[key] = (keysCount[key] ?? 0) + 1;
+        keysCount[value] = (keysCount[value] ?? 0) + 1;
+    });
+
+    return values.filter((value) => {
+        return typeof value === 'string' && (!keys.includes(value) || (keysCount[value] && keysCount[value] > 1));
+    });
+}

package/src/env.ts

@@ -0,0 +1,49 @@
+/**
+ * Custom error class for handling missing environment variables.
+ *
+ * Extends the built-in `Error` class and includes the missing key.
+ *
+ * @extends {Error}
+ */
+export class EnvironmentNotFoundError extends Error {
+    readonly key: string;
+
+    /**
+     * Creates a new EnvironmentNotFoundError.
+     *
+     * @param {string} key - The missing environment variable key.
+     */
+    constructor(key: string) {
+        super(`Missing environment variable: ${key}`);
+        this.key = key;
+        this.name = this.constructor.name;
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+
+/**
+ * Retrieves the value of an environment variable, or throws an error if not set.
+ *
+ * @param {string} key - The environment variable key to check.
+ * @returns {string} The value of the environment variable.
+ * @throws {EnvironmentNotFoundError} If the environment variable is not defined.
+ *
+ * @example
+ * ```typescript
+ * import { checkAndGetEnvValue } from '@kikiutils/shared/env';
+ *
+ * // When the environment variable 'API_KEY' is set:
+ * console.log(checkAndGetEnvValue('API_KEY')); // value of API_KEY
+ *
+ * // When the environment variable 'API_KEY' is not set:
+ * try {
+ *   const apiKey = checkAndGetEnvValue('API_KEY');
+ * } catch (error) {
+ *   console.error(error); // Missing environment variable: API_KEY
+ * }
+ * ```
+ */
+export function checkAndGetEnvValue(key: string): string {
+    if (!process.env[key]) throw new EnvironmentNotFoundError(key);
+    return process.env[key];
+}

package/src/general.ts

@@ -0,0 +1,29 @@
+/**
+ * Extracts the first value from an array or returns the value itself if it's not an array.
+ *
+ * - If `value` is an array, returns the first element.
+ * - If `value` is not an array, returns `value` directly.
+ * - If the result is `null` or `undefined`, and `defaultValue` is provided, returns `defaultValue` instead.
+ *
+ * @template T - The type of the input value(s).
+ * @template D - The type of the default value (if provided).
+ *
+ * @param {T | T[]} value - A single value or an array of values.
+ * @param {D} [defaultValue] - A fallback value if the result is `null` or `undefined`.
+ * @returns {T | D | undefined} The first value or the fallback.
+ *
+ * @example
+ * ```typescript
+ * import { extractFirstValue } from '@kikiutils/shared/general';
+ *
+ * console.log(extractFirstValue([1, 2, 3])); // 1
+ * console.log(extractFirstValue('hello'));  // hello
+ * console.log(extractFirstValue([], 'default')); // default
+ * console.log(extractFirstValue(undefined, 'fallback')); // fallback
+ * ```
+ */
+export function extractFirstValue<T>(value: T | T[]): T | undefined;
+export function extractFirstValue<T, D>(value: T | T[], defaultValue: D): D | NonNullable<T>;
+export function extractFirstValue<T, D>(value: T | T[], defaultValue?: D) {
+    return (Array.isArray(value) ? value[0] : value) ?? defaultValue;
+}

package/src/hash.ts

@@ -0,0 +1,25 @@
+/**
+ * This file provides a set of functions for creating SHA-3 hash digests using different bit lengths (224, 256, 384, 512).
+ * These functions use the [@noble/hashes](https://github.com/paulmillr/noble-hashes) library to generate the hashes.
+ * Can be used in the browser, mainly for Nuxt/Vue and other frameworks compiled and executed in the browser.
+ *
+ * @example
+ * ```typescript
+ * import { sha3256 } from '@kikiutils/shared/hash';
+ *
+ * console.log(sha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
+ * ```
+ */
+
+import {
+    sha3_224,
+    sha3_256,
+    sha3_384,
+    sha3_512,
+} from '@noble/hashes/sha3';
+import { bytesToHex } from '@noble/hashes/utils';
+
+export const sha3224 = (data: string | Uint8Array) => bytesToHex(sha3_224(data));
+export const sha3256 = (data: string | Uint8Array) => bytesToHex(sha3_256(data));
+export const sha3384 = (data: string | Uint8Array) => bytesToHex(sha3_384(data));
+export const sha3512 = (data: string | Uint8Array) => bytesToHex(sha3_512(data));

package/src/math.ts

@@ -0,0 +1,56 @@
+import { Decimal } from 'decimal.js';
+
+type CalculableValue = Decimal.Value | { toString: () => string };
+
+/**
+ * Options for configuring the output of `toPercentageString`.
+ */
+export interface ToPercentageStringOptions {
+    /**
+     * Number of decimal places to include in the result.
+     * @default 2
+     */
+    decimalPlaces?: number;
+
+    /**
+     * Whether to include the '%' symbol in the result.
+     * @default true
+     */
+    withSymbol?: boolean;
+}
+
+/**
+ * Converts a fraction (numerator / denominator) into a percentage string.
+ *
+ * - Uses `decimal.js` for precise decimal calculations.
+ * - Supports custom decimal places and optional percentage symbol.
+ * - Returns `'0.00%'` if result is `NaN` or division is invalid.
+ *
+ * @param {CalculableValue} molecular - The numerator of the fraction.
+ * @param {CalculableValue} denominator - The denominator of the fraction.
+ * @param {ToPercentageStringOptions} [options] - Optional output settings.
+ * @returns {string} Formatted percentage string.
+ *
+ * @example
+ * ```typescript
+ * import { toPercentageString } from '@kikiutils/shared/math';
+ *
+ * console.log(toPercentageString(50, 200)); // 25.00%
+ * console.log(toPercentageString(50, 200, { withSymbol: false })); // 25.00
+ * console.log(toPercentageString(50, 200, { decimalPlaces: 1 })); // 25.0%
+ * ```
+ */
+export function toPercentageString(
+    molecular: CalculableValue,
+    denominator: CalculableValue,
+    options?: ToPercentageStringOptions,
+) {
+    const molecularDecimal = new Decimal(molecular.toString());
+    const denominatorDecimal = new Decimal(denominator.toString());
+    const calculationResult = molecularDecimal.div(denominatorDecimal);
+    const result = calculationResult.isNaN()
+        ? '0.00'
+        : calculationResult.times(100).toFixed(options?.decimalPlaces ?? 2);
+
+    return options?.withSymbol ?? true ? `${result}%` : result;
+}

package/src/number.ts

@@ -0,0 +1,29 @@
+import { millify } from 'millify';
+
+/**
+ * Converts a large number into a compact, human-readable string using `millify`.
+ *
+ * Applies lowercase units (e.g. 'k', 'm') and default precision of 2, unless overridden.
+ *
+ * @param {number} value - The number to format.
+ * @param {Parameters<typeof millify>[1]} [options] - Optional configuration passed to `millify`.
+ * @returns {string} The compact number string.
+ *
+ * @example
+ * ```typescript
+ * import { toCompactNumberString } from '@kikiutils/shared/number';
+ *
+ * console.log(toCompactNumberString(1234567)); // 1.23m
+ * console.log(toCompactNumberString(1234567, { precision: 3 })); // 1.235m
+ * ```
+ */
+export function toCompactNumberString(value: number, options?: Parameters<typeof millify>[1]) {
+    return millify(
+        value,
+        {
+            lowercase: true,
+            precision: 2,
+            ...options,
+        },
+    );
+}

package/src/pino.ts

@@ -0,0 +1,37 @@
+import { pino } from 'pino';
+import { PinoPretty } from 'pino-pretty';
+
+/**
+ * Configure pinoPretty to enhance the log output.
+ */
+const stream = PinoPretty({
+    colorize: true, // Enable colored output for better readability
+    ignore: 'hostname,pid', // Exclude 'hostname' and 'pid' fields from the logs
+    translateTime: 'SYS:yyyy-mm-dd HH:MM:ss.l', // Format the timestamp in 'yyyy-mm-dd HH:MM:ss.l' format
+});
+
+/**
+ * A pino logger instance with the configured stream.
+ *
+ * The logger's level is determined based on the `PINO_LOGGER_LEVEL` and `NODE_ENV` environment variables.
+ * If `PINO_LOGGER_LEVEL` is set, it will be used; otherwise, if `NODE_ENV` is `production`,
+ * the level will be set to `error`.
+ *
+ * To manually change the level, assign the desired level to `logger.level`.
+ *
+ * See available levels [here](https://getpino.io/#/docs/api?id=level-string).
+ *
+ * @example
+ * ```typescript
+ * import logger from '@kikiutils/shared/pino';
+ *
+ * logger.info('test'); // [2024-07-11 12:12:30.085] INFO: test
+ *
+ * // Manually change the level
+ * logger.level = 'info';
+ * ```
+ */
+export const pinoLogger = pino({}, stream);
+export const logger = pinoLogger;
+// eslint-disable-next-line style/max-len
+pinoLogger.level = process.env.PINO_LOGGER_LEVEL || (process.env.NODE_ENV === 'production' ? 'error' : pinoLogger.level);