@andrew_l/toolkit 0.0.1 → 0.2.4

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as lodash from 'lodash';
 
 type ItemType<T> = T extends Array<infer X> ? X : T extends string ? string : Exclude<T, null | undefined>;
+type ArrayableValue<T> = T extends object ? Readonly<T> : T;
 /**
  * Converts a value into an array. This function handles different types of input,
  * converting them to arrays as follows:
@@ -21,7 +22,7 @@ type ItemType<T> = T extends Array<infer X> ? X : T extends string ? string : Ex
  *
  * @group Array
  */
-declare function arrayable<T>(value: Readonly<T>): ItemType<T>[];
+declare function arrayable<T>(value: ArrayableValue<T>): ItemType<T>[];
 
 /**
  * Calculates the average value from an array of numbers.
@@ -94,6 +95,42 @@ declare function chunk<T>(list: readonly T[], size?: number): T[][];
  */
 declare function chunkSeries(list: number[], step?: number): number[][];
 
+/**
+ * Computes the difference between arrays.
+ *
+ * This function takes arrays and returns a new array containing the elements
+ * that are not present in any other arrays.
+ *
+ * @template T
+ * @param arrays - The arrays from which to derive the difference.
+ * @returns {T[]} A new array containing the elements that are not present in other arrays.
+ *
+ * @example
+ * const array1 = [1, 2, 3, 4, 5];
+ * const array2 = [2, 4];
+ * const array3 = [1, 5];
+ * const result = difference(array1, array2, array3);
+ * // result will be [3] since 1, 2, 4 and 5 are in other arrays and are excluded from the result.
+ */
+declare function difference<T>(...arrays: readonly T[][]): T[];
+
+/**
+ * Returns the intersection of arrays.
+ *
+ * This function takes arrays and returns a new array containing the elements that are
+ * present in all arrays.
+ *
+ * @template T - The type of elements in the array.
+ * @returns {T[]} A new array containing the elements that are present in both arrays.
+ *
+ * @example
+ * const array1 = [1, 2, 3, 4, 5];
+ * const array2 = [3, 4, 5, 6, 7];
+ * const result = intersection(array1, array2);
+ * // result will be [3, 4, 5] since these elements are in both arrays.
+ */
+declare function intersection<T>(...arrays: readonly T[][]): T[];
+
 type MaybePropertyKey<T> = T extends object
   ? keyof T | PropertyKey
   : PropertyKey;
@@ -158,6 +195,22 @@ declare function keyBy<T, K extends PropertyKey>(array: readonly T[], keyBy: (it
  */
 declare function orderBy<T>(array: readonly T[], fields: (string | ((item: T) => any))[], orders: ('asc' | 'desc')[]): readonly T[];
 
+/**
+ * Randomizes the order of elements in an array using the Fisher-Yates algorithm.
+ *
+ * This function takes an array and returns a new array with its elements shuffled in a random order.
+ *
+ * @template T - The type of elements in the array.
+ * @param {T[]} arr - The array to shuffle.
+ * @returns {T[]} A new array with its elements shuffled in random order.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * const shuffledArray = shuffle(array);
+ * // shuffledArray will be a new array with elements of array in random order, e.g., [3, 1, 4, 5, 2]
+ */
+declare function shuffle<T>(arr: readonly T[]): T[];
+
 /**
  * Sums the values in an array of numbers, ignoring non-numeric values.
  *
@@ -196,7 +249,7 @@ declare const sum: (values: readonly number[]) => number;
  *
  * @group Array
  */
-declare function union<T>(arr1: readonly T[], arr2: readonly T[]): T[];
+declare function union<T>(...arrays: readonly T[][]): T[];
 
 /**
  * Returns a new array with duplicates removed.
@@ -293,6 +346,345 @@ declare namespace assert {
   export { assert_array as array, assert_arrayNumbers as arrayNumbers, assert_arrayStrings as arrayStrings, assert_boolean as boolean, assert_equal as equal, assert_notEmptyString as notEmptyString, assert_number as number, assert_object as object, assert_ok as ok, assert_string as string };
 }
 
+type Base64ToBytesOptions = {
+    /**
+     * Encoding type
+     */
+    encoding?: 'base64' | 'base64url';
+    /**
+     * Whether to enforce strict Base64 decoding.
+     */
+    strict?: boolean;
+};
+/**
+ * Decodes a Base64 or Base64URL encoded string into a `Uint8Array`.
+ *
+ * This function supports decoding data from both standard Base64 and Base64URL formats.
+ *
+ * @param {string} data - The encoded string to decode. Must be a valid Base64 or Base64URL encoded string.
+ * @param {Base64ToBytesOptions} [options] - Optional configuration options for decoding.
+ * @returns {Uint8Array} - The decoded byte array.
+ *
+ * @example
+ * // Example 1: Decoding a Base64 string
+ * const base64String = 'SGVsbG8gd29ybGQ='; // "Hello world"
+ * const decodedBytes = base64ToBytes(base64String);
+ * console.log(decodedBytes); // Output: Uint8Array [ 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100 ]
+ *
+ * @example
+ * // Example 2: Decoding a Base64URL encoded string
+ * const base64urlString = 'SGVsbG8gd29ybGQ'; // "Hello world"
+ * const decodedBytes2 = base64ToBytes(base64urlString, { encoding: 'base64url' });
+ * console.log(decodedBytes2); // Output: Uint8Array [ 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100 ]
+ *
+ * @example
+ * // Example 3: Strict decoding with Base64
+ * const base64StringStrict = 'SGVsbG8gd29ybGQ=';
+ * const decodedStrict = base64ToBytes(base64StringStrict, { strict: true });
+ * console.log(decodedStrict); // Output: Uint8Array [ 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100 ]
+ *
+ * @group Binary
+ */
+declare function base64ToBytes(data: string, { encoding, strict }?: Base64ToBytesOptions): Uint8Array;
+
+/**
+ * Converts a `bigint` value into a byte array (`Uint8Array`) in big-endian order.
+ *
+ * This function encodes the absolute value of the provided `bigint` into a minimal byte array,
+ * ensuring that the bytes represent the value in big-endian format.
+ *
+ * @param {bigint} value - The input `bigint` value to convert into bytes.
+ * @returns {Uint8Array} - The byte array (`Uint8Array`) representing the provided `bigint`.
+ *
+ * @example
+ * // Example 1: Convert a positive bigint to bytes
+ * const value = 1234567890123456789n;
+ * const bytes = bigIntBytes(value);
+ * console.log(bytes); // Output: Uint8Array representing the bytes in big-endian
+ *
+ * @example
+ * // Example 2: Convert a negative bigint to bytes
+ * const valueNegative = -1234567890123456789n;
+ * const bytesNegative = bigIntBytes(valueNegative);
+ * console.log(bytesNegative); // Output: Uint8Array representing the absolute value in big-endian
+ *
+ * @example
+ * // Example 3: Handle very small bigints
+ * const smallValue = 42n;
+ * const bytesSmall = bigIntBytes(smallValue);
+ * console.log(bytesSmall); // Output: Uint8Array [ 42 ]
+ *
+ * @example
+ * // Example 4: Convert zero value
+ * const zeroValue = 0n;
+ * const bytesZero = bigIntBytes(zeroValue);
+ * console.log(bytesZero); // Output: Uint8Array [ 0 ]
+ *
+ * @group Binary
+ */
+declare function bigIntBytes(value: bigint): Uint8Array;
+
+/**
+ * Converts a byte array (`Uint8Array`) into a `bigint`. The byte array is interpreted in big-endian order.
+ *
+ * This function takes a byte array and decodes it into its corresponding `bigint` value by treating
+ * the byte array as a big-endian encoded number.
+ *
+ * @param {Uint8Array} bytes - The byte array to decode into a `bigint`. Must have at least one byte.
+ * @returns {bigint} - The decoded `bigint` value.
+ *
+ * @throws {Error} Will throw an error if the input byte array is empty.
+ *
+ * @example
+ * // Example 1: Decode a simple byte array
+ * const byteArray = new Uint8Array([0, 0, 0, 42]); // Represents the number 42 in big-endian
+ * const decodedValue = bigIntFromBytes(byteArray);
+ * console.log(decodedValue); // Output: 42n
+ *
+ * @example
+ * // Example 2: Decode a multi-byte number
+ * const byteArrayMulti = new Uint8Array([0x12, 0x34, 0x56, 0x78]); // Represents the number 305419896
+ * const decodedMulti = bigIntFromBytes(byteArrayMulti);
+ * console.log(decodedMulti); // Output: 305419896n
+ *
+ * @example
+ * // Example 3: Decode a single byte number
+ * const byteArraySingle = new Uint8Array([255]); // Represents the number 255
+ * const decodedSingle = bigIntFromBytes(byteArraySingle);
+ * console.log(decodedSingle); // Output: 255n
+ *
+ * @example
+ * // Example 4: Attempt decoding an invalid empty array
+ * try {
+ *   const emptyArray = new Uint8Array([]);
+ *   const decodedEmpty = bigIntFromBytes(emptyArray);
+ * } catch (error) {
+ *   console.error(error); // Output: Error: Empty Uint8Array
+ * }
+ *
+ * @group Binary
+ */
+declare function bigIntFromBytes(bytes: Uint8Array): bigint;
+
+type BytesToBase64Options = {
+    /**
+     * Specifies the encoding type.
+     */
+    encoding?: 'base64' | 'base64url';
+    /**
+     * Whether or not to include padding (`=`) in the encoded result. Defaults to `true` for Base64, `false` for Base64URL.
+     */
+    padding?: boolean;
+};
+/**
+ * Encodes a byte array (`Uint8Array`) into a Base64 or Base64URL encoded string.
+ *
+ * The function can encode bytes in either the standard Base64 format or Base64URL format,
+ * depending on the specified options. It also allows control over whether padding is included.
+ *
+ * @param {Uint8Array} data - The byte array to encode into Base64 or Base64URL.
+ * @param {BytesToBase64Options} [options] - Optional configuration options.
+ * @returns {string} - The encoded Base64 or Base64URL string.
+ *
+ * @example
+ * // Example 1: Encoding with Base64 with default padding
+ * const byteArray = new Uint8Array([72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100]); // "Hello world"
+ * const encodedBase64 = bytesToBase64(byteArray);
+ * console.log(encodedBase64); // Output: 'SGVsbG8gd29ybGQ='
+ *
+ * @example
+ * // Example 2: Encoding with Base64URL without padding
+ * const byteArray2 = new Uint8Array([72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100]); // "Hello world"
+ * const encodedBase64URL = bytesToBase64(byteArray2, { encoding: 'base64url', padding: false });
+ * console.log(encodedBase64URL); // Output: 'SGVsbG8gd29ybGQ'
+ *
+ * @example
+ * // Example 3: Encoding with Base64 with no padding
+ * const byteArray3 = new Uint8Array([1, 2, 3, 4]);
+ * const encodedNoPadding = bytesToBase64(byteArray3, { encoding: 'base64', padding: false });
+ * console.log(encodedNoPadding); // Output: 'AQIDBA'
+ *
+ * @example
+ * // Example 4: Handling invalid encoding options
+ * try {
+ *   const invalidEncoding = bytesToBase64(byteArray3, { encoding: 'invalid' });
+ * } catch (error) {
+ *   console.error(error); // Output: Error: Invalid encoding options: invalid
+ * }
+ *
+ * @group Binary
+ */
+declare function bytesToBase64(data: Uint8Array, { encoding, padding }?: BytesToBase64Options): string;
+
+/**
+ * Compares two `Uint8Array` instances to check if their contents are identical.
+ *
+ * This function compares each byte of the two provided byte arrays. It returns `true`
+ * only if both byte arrays are of the same length **and** contain identical byte values
+ * at every index. Otherwise, it returns `false`.
+ *
+ * @param {Uint8Array} a - The first byte array to compare.
+ * @param {Uint8Array} b - The second byte array to compare.
+ * @returns {boolean} `true` if the byte arrays are identical; otherwise, `false`.
+ *
+ * @example
+ * // Example with identical byte arrays
+ * const a = new Uint8Array([1, 2, 3]);
+ * const b = new Uint8Array([1, 2, 3]);
+ * console.log(compareBytes(a, b)); // Output: true
+ *
+ * @example
+ * // Example with different contents
+ * const a = new Uint8Array([1, 2, 3]);
+ * const b = new Uint8Array([1, 2, 4]);
+ * console.log(compareBytes(a, b)); // Output: false
+ *
+ * @example
+ * // Example with different lengths
+ * const a = new Uint8Array([1, 2]);
+ * const b = new Uint8Array([1, 2, 3]);
+ * console.log(compareBytes(a, b)); // Output: false
+ *
+ * @example
+ * // Example with both arrays empty
+ * const a = new Uint8Array([]);
+ * const b = new Uint8Array([]);
+ * console.log(compareBytes(a, b)); // Output: true
+ *
+ * @group Binary
+ */
+declare function compareBytes(a: Uint8Array, b: Uint8Array): boolean;
+
+/**
+ * Concatenates two `Uint8Array` instances into a single new `Uint8Array`.
+ *
+ * This function takes two byte arrays, `a` and `b`, and creates a new `Uint8Array`
+ * that combines their contents in order. The result will have a length equal to the
+ * sum of the lengths of `a` and `b`.
+ *
+ * @param {Uint8Array} a - The first byte array to concatenate.
+ * @param {Uint8Array} b - The second byte array to concatenate.
+ * @returns {Uint8Array} A new `Uint8Array` containing the concatenation of `a` and `b`.
+ *
+ * @example
+ * // Example with simple byte arrays
+ * const a = new Uint8Array([1, 2, 3]);
+ * const b = new Uint8Array([4, 5, 6]);
+ * const result = concatenateBytes(a, b);
+ * console.log(result); // Output: Uint8Array(6) [1, 2, 3, 4, 5, 6]
+ *
+ * @example
+ * // Example with empty arrays
+ * const a = new Uint8Array([]);
+ * const b = new Uint8Array([1, 2, 3]);
+ * const result = concatenateBytes(a, b);
+ * console.log(result); // Output: Uint8Array(3) [1, 2, 3]
+ *
+ * @example
+ * // Example with reversed order
+ * const a = new Uint8Array([10, 20]);
+ * const b = new Uint8Array([30, 40]);
+ * const result = concatenateBytes(a, b);
+ * console.log(result); // Output: Uint8Array(4) [10, 20, 30, 40]
+ *
+ * @group Binary
+ */
+declare function concatenateBytes(a: Uint8Array, b: Uint8Array): Uint8Array;
+
+/**
+ * Converts a `Uint16Array` into a `Uint8Array`.
+ *
+ * @param {Uint16Array} value - The input `Uint16Array` to convert.
+ * @returns {Uint8Array} - The resulting `Uint8Array`, with length twice that of the input `Uint16Array`.
+ *
+ * @example
+ * // Example 1: Converting a valid Uint16Array into a Uint8Array
+ * const uint16Array = new Uint16Array([0x1234, 0x5678]);
+ * const uint8Array = uint16ToUint8(uint16Array);
+ * console.log(uint8Array); // Output: Uint8Array [ 0x34, 0x12, 0x78, 0x56 ]
+ *
+ * @example
+ * // Example 2: Another conversion example
+ * const uint16Array2 = new Uint16Array([0xabcd, 0x1234, 0x5678]);
+ * const uint8Array2 = uint16ToUint8(uint16Array2);
+ * console.log(uint8Array2); // Output: Uint8Array [ 0xcd, 0xab, 0x34, 0x12, 0x78, 0x56 ]
+ *
+ * @group Binary
+ */
+declare function uint16ToUint8(value: Uint16Array): Uint8Array;
+
+/**
+ * Converts a `Uint32Array` into a `Uint8Array`.
+ *
+ * @param {Uint32Array} value - The input `Uint32Array` to convert.
+ * @returns {Uint8Array} - The resulting `Uint8Array`, with length four times that of the input `Uint32Array`.
+ *
+ * @example
+ * // Example 1: Converting a valid Uint32Array into a Uint8Array
+ * const uint32Array = new Uint32Array([0x12345678, 0x9abcdef0]);
+ * const uint8Array = uint32ToUint8(uint32Array);
+ * console.log(uint8Array); // Output: Uint8Array [ 0x78, 0x56, 0x34, 0x12, 0xf0, 0xde, 0xbc, 0x9a ]
+ *
+ * @example
+ * // Example 2: Another conversion example with different numbers
+ * const uint32Array2 = new Uint32Array([0xffffffff, 0x00000000]);
+ * const uint8Array2 = uint32ToUint8(uint32Array2);
+ * console.log(uint8Array2); // Output: Uint8Array [ 0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00 ]
+ *
+ * @example
+ * // Example 3: Handling edge values
+ * const uint32Array3 = new Uint32Array([0x0, 0x00000001]);
+ * const uint8Array3 = uint32ToUint8(uint32Array3);
+ * console.log(uint8Array3); // Output: Uint8Array [ 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00 ]
+ *
+ * @group Binary
+ */
+declare function uint32ToUint8(value: Uint32Array): Uint8Array;
+
+/**
+ * Converts a Uint8Array to a Uint16Array.
+ *
+ * @param {Uint8Array} value - The input byte array to convert. Must have an even length.
+ * @returns {Uint16Array} - The converted Uint16Array.
+ *
+ * @example
+ * // Example 1: Converting a valid Uint8Array into a Uint16Array
+ * const uint8Array = new Uint8Array([0x12, 0x34, 0x56, 0x78]);
+ * const uint16Array = uint8ToUint16(uint8Array);
+ * console.log(uint16Array); // Output: Uint16Array [ 0x1234, 0x5678 ]
+ *
+ * @example
+ * // Example 2: Another conversion example
+ * const uint8Array2 = new Uint8Array([0xff, 0xee, 0xdd, 0xcc]);
+ * const uint16Array2 = uint8ToUint16(uint8Array2);
+ * console.log(uint16Array2); // Output: Uint16Array [ 0xffee, 0xddcc ]
+ *
+ * @group Binary
+ */
+declare function uint8ToUint16(value: Uint8Array): Uint16Array;
+
+/**
+ * Converts a `Uint8Array` into a `Uint32Array`.
+ *
+ * @param {Uint8Array} value - The input byte array to convert. Length must be a multiple of 4.
+ * @returns {Uint32Array} - The converted array of 32-bit unsigned integers.
+ *
+ * @example
+ * // Example 1: Converting a valid Uint8Array into a Uint32Array
+ * const uint8Array = new Uint8Array([0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0]);
+ * const uint32Array = uint8ToUint32(uint8Array);
+ * console.log(uint32Array); // Output: Uint32Array [ 0x78563412, 0xf0debc9a ]
+ *
+ * @example
+ * // Example 2: Another conversion example
+ * const uint8Array2 = new Uint8Array([0xff, 0xee, 0xdd, 0xcc, 0xab, 0xcd, 0xef, 0x01]);
+ * const uint32Array2 = uint8ToUint32(uint8Array2);
+ * console.log(uint32Array2); // Output: Uint32Array [ 0xccddeeff, 0x01abcded ]
+ *
+ *  @group Binary
+ */
+declare function uint8ToUint32(value: Uint8Array): Uint32Array;
+
 type Arrayable<T> = T[] | T;
 
 type Awaitable<T> = Promise<T> | T;
@@ -342,11 +734,53 @@ type PromisifyFn<T extends AnyFunction> = (
   ...args: ArgumentsType<T>
 ) => Promise<ReturnType<T>>;
 
+/**
+ * A time value, which can be a string (e.g., "HH:MM"),
+ * an object with `h` (hours) and `m` (minutes) properties, or a similar format
+ * that `createTimeObject` can parse.
+ */
+type TimeValue = TimeString | TimeObject;
+
+/**
+ * Represent time string in 24h format
+ */
+type TimeString = string;
+
+/**
+ * Represent time object in 24h format ("HH:MM")
+ */
 type TimeObject = {
+  /**
+   * Hour (0 - 23).
+   */
   h: number;
+
+  /**
+   * Minutes (0 - 59).
+   */
   m: number;
 };
 
+/**
+ * Represent date object
+ */
+type DateObject = {
+  /**
+   * The year of the date (e.g., 2024).
+   */
+  year: number;
+
+  /**
+   * The month of the date (1 = January, 12 = December).
+   */
+  month: number;
+
+  /**
+   * The day of the month (1-31).
+   */
+  date: number;
+};
+
 interface ThemeConfig {
   colors: {
     [x: string]: Record<string, string>;
@@ -891,9 +1325,9 @@ declare function withPointerCache<T>(pointer: object, dependencies: string[], fn
  */
 declare function captureStackTrace(till: AnyFunction): string;
 
-type ToCatchResult<T> = T extends Promise<any> ? Promise<CatchSuccessResult<Awaited<T>> | CatchErrorResult> : CatchSuccessResult<T> | CatchErrorResult;
-type CatchErrorResult = [Error, undefined];
-type CatchSuccessResult<T> = [undefined, T];
+type CatchErrorResult<T> = T extends Promise<unknown> ? Promise<OkResult<Awaited<T>> | ErrorResult> : OkResult<T> | ErrorResult;
+type ErrorResult = [Error, undefined];
+type OkResult<T> = [undefined, T];
 /**
  * You're tired to write `try... catch`, and so are we.
  *
@@ -906,7 +1340,7 @@ type CatchSuccessResult<T> = [undefined, T];
  *
  * @group Errors
  */
-declare function catchError<T>(fn: () => T): ToCatchResult<T>;
+declare function catchError<T>(fn: () => T): CatchErrorResult<T>;
 
 declare namespace Color {
     /**
@@ -1143,110 +1577,899 @@ declare const ColorParser: {
  */
 declare function crc32(str: string, seed?: number): number;
 
-type Dict<T> = {
-    [key: string]: T | undefined;
-};
-type ListTypeName = 'bool' | 'int' | 'decimal' | 'string';
-type ListTypeNameToType<T extends ListTypeName> = T extends 'bool' ? boolean : T extends 'int' ? number : T extends 'decimal' ? number : T extends 'string' ? string : never;
+type DateObjectInput = Date | string | number | DateObject;
+declare function createDateObject(value: DateObjectInput): DateObject;
+declare function createDateObject(value: DateObjectInput, returnsNullWhenInvalid: true): DateObject | null;
+
+type TimeObjectInput = Date | number | string | TimeObject;
+declare function createTimeObject(value: TimeObjectInput): TimeObject;
+declare function createTimeObject(value: TimeObjectInput, returnsNullWhenInvalid: true): TimeObject | null;
+
+type TimeSpanUnit = 'ms' | 's' | 'm' | 'h' | 'd' | 'w';
 /**
- * Environment variable parser
- *
- * @group Environment
+ * A class representing a span of time with a specific value and unit of measurement.
+ * Provides methods for conversion between time units and arithmetic operations (add, subtract).
  */
-interface EnvParser {
+declare class TimeSpan {
+    constructor(value: number, unit: TimeSpanUnit);
     /**
-     * NODE_ENV is `development`
+     * The numeric value of the time span
      */
-    isDevelopment: boolean;
+    value: number;
     /**
-     * NODE_ENV is `production`
+     * The unit of the time span.
      */
-    isProduction: boolean;
+    unit: TimeSpanUnit;
     /**
-     * NODE_ENV is `stage`
+     * Converts the time span to milliseconds.
+     *
+     * @returns {number} The equivalent time span in milliseconds.
+     * @example
+     * const ts = new TimeSpan(2, 'h');
+     * ts.milliseconds(); // Returns 7200000
      */
-    isStage: boolean;
+    milliseconds(): number;
     /**
-     * Returns `true` when environment key has set to `"true"`
+     * Converts the time span to seconds.
      *
-     * Returns `defaultValue` when key is not defined
+     * @returns {number} The equivalent time span in seconds.
+     * @example
+     * const ts = new TimeSpan(2, 'm');
+     * ts.seconds(); // Returns 120
      */
-    bool(key: string, defaultValue?: boolean): boolean;
+    seconds(): number;
     /**
-     * Returns `number` when environment key has correct number value.
+     * Converts the time span to minutes.
      *
-     * Returns `defaultValue` when environment key is not defined or has invalid number value
+     * @returns {number} The equivalent time span in minutes.
+     * @example
+     * const ts = new TimeSpan(120, 's');
+     * ts.minutes(); // Returns 2
      */
-    int(key: string, defaultValue?: number): number;
+    minutes(): number;
     /**
-     * Returns `number` when environment key has correct number value.
+     * Converts the time span to hours.
      *
-     * Returns `defaultValue` when environment key is not defined or has invalid number value
+     * @returns {number} The equivalent time span in hours.
+     * @example
+     * const ts = new TimeSpan(120, 'm');
+     * ts.hours(); // Returns 2
      */
-    decimal(key: string, dights?: number, defaultValue?: number): number;
+    hours(): number;
     /**
-     * Returns `string` when environment key has defined.
+     * Converts the time span to days.
      *
-     * Returns `defaultValue` when environment key is not defined
+     * @returns {number} The equivalent time span in days.
+     * @example
+     * const ts = new TimeSpan(48, 'h');
+     * ts.days(); // Returns 2
      */
-    string(key: string, defaultValue?: string): string;
+    days(): number;
     /**
-     * Returns `array` of parsed environment value.
+     * Converts the time span to weeks.
      *
-     * Returns `defaultValue` when key is not defined
+     * @returns {number} The equivalent time span in weeks.
+     * @example
+     * const ts = new TimeSpan(14, 'd');
+     * ts.weeks(); // Returns 2
      */
-    list<T extends ListTypeName>(key: string, itemType: T, defaultValue?: ListTypeNameToType<T>[]): ListTypeNameToType<T>[];
+    weeks(): number;
     /**
-     * Returns parsed json value.
+     * Adds a specified value and unit to the current time span.
      *
-     * Returns `defaultValue` when key is not defined or invalid json value
+     * Returns new instance.
+     *
+     * @param {number} value - The value to add.
+     * @param {TimeSpanUnit} [unit='ms'] - The unit of the value to add (default is milliseconds).
+     * @returns {TimeSpan} A new TimeSpan instance with the added value.
+     * @example
+     * const ts = new TimeSpan(1, 'h');
+     * ts.add(30, 'm'); // Represents 1.5 hours
      */
-    json<T = any>(key: string, defaultValue?: T | null): T | null;
+    add(value: number, unit?: TimeSpanUnit): TimeSpan;
+    /**
+     * Subtracts a specified value and unit from the current time span.
+     *
+     * Returns new instance.
+     *
+     * @param {number} value - The value to subtract.
+     * @param {TimeSpanUnit} [unit='ms'] - The unit of the value to subtract (default is milliseconds).
+     * @returns {TimeSpan} A new TimeSpan instance with the subtracted value.
+     * @example
+     * const ts = new TimeSpan(1, 'h');
+     * ts.subtract(30, 'm'); // Represents 30 minutes less than 1 hour
+     */
+    subtract(value: number, unit?: TimeSpanUnit): TimeSpan;
 }
+
 /**
- * Ready-to-use environment parser.
+ * Creates a new instance of `TimeSpan`.
  *
- * Target: `process.env`
+ * This utility function allows you to create a `TimeSpan` object by providing a numeric value and a unit of time.
+ * The default unit is `'ms'` (milliseconds).
  *
- * Fallback: `import.meta.env`
+ * @param {number} value - The numeric value representing the timespan.
+ * @param {TimeSpanUnit} [unit='ms'] - The unit of time for the timespan value. Options are `'ms'`, `'s'`, `'m'`, `'h'`, `'d'`, `'w'`.
+ * @returns {TimeSpan} An instance of the `TimeSpan` class.
+ * @example
+ * // Create a TimeSpan with 500 milliseconds
+ * const ts = createTimeSpan(500);
+ * console.log(ts.milliseconds()); // 500
  *
  * @example
+ * // Create a TimeSpan with 2 hours
+ * const ts = createTimeSpan(2, 'h');
+ * console.log(ts.seconds()); // 120
  *
- * // env.string
- * const API_KEY = env.string('API_KEY', 'test_key');
+ * @example
+ * // Create a TimeSpan with 7 days
+ * const ts = createTimeSpan(7, 'd');
+ * console.log(ts.weeks()); // 1
  *
- * // env.bool
- * const TEST_FEATURE = env.bool('TEST_FEATURE', false);
+ * @group Date
+ */
+declare function createTimeSpan(value: number, unit?: TimeSpanUnit): TimeSpan;
+
+/**
+ * The base time as a timestamp, `Date` object,
+ * or a similar format that the `timestampMs` function can parse.
+ */
+type TimestampMsInput = Date | string | number;
+/**
+ * Returns or converts the given input into milliseconds since the Unix epoch.
  *
- * // env.int
- * const RETRY_ATTEMPTS = env.int('RETRY_ATTEMPTS', 5);
+ * @param {TimestampMsInput} [fromValue=Date.now()] - The input value to be converted to milliseconds.
+ *                          Can be a `Date` object, a timestamp (number), or a string representing a date.
+ *                          Defaults to the current time.
+ * @returns {number} The number of milliseconds since the Unix epoch. Returns `0` if the input is invalid.
  *
- * // env.decimal
- * const DELAY_SECONDS = env.decimal('DELAY_SECONDS', 2, 5); // round to 2 dights
+ * @example
+ * // Get milliseconds from a Date object
+ * timestampMs(new Date('2023-01-01T00:00:00Z')); // 1672531200000
  *
- * // env.list
- * const TARGET_ROLES = env.list('TARGET_ROLES', 'string', ['ADMIN']);
+ * @example
+ * // Get milliseconds from a timestamp
+ * timestampMs(1672531200000); // 1672531200000
  *
- * // env.json
- * const GOOGLE_CREDS = env.json<{ projectId: string; token: string; }>('GOOGLE_CREDS');
+ * @example
+ * // Get milliseconds from a date string
+ * timestampMs('2023-01-01T00:00:00Z'); // 1672531200000
  *
- * @group Environment
- */
-declare const env: Readonly<EnvParser>;
-/**
  * @example
- * const env = createEnvParser(process.env);
- * // const env = createEnvParser(import.meta.env);
+ * // Handle invalid input
+ * timestampMs('invalid-date'); // 0
  *
- * const API_KEY = env.string('API_KEY', 'test_key');
+ * @example
+ * // Use the default value (current time)
+ * timestampMs(); // Current timestamp in milliseconds
  *
- * @group Environment
+ * @group Date
  */
-declare function createEnvParser(targetObject: Record<string, string> | Dict<string>): Readonly<EnvParser>;
+declare function timestampMs(fromValue?: TimestampMsInput): number;
 
 /**
- * Simple application error class with the code
- * @group Errors
+ * Returns a `Date` object representing a time that is the given number of days
+ * before or after a base time.
+ *
+ * @param {number} days - The number of days to add to or subtract from the base time.
+ *                        Positive values move forward in time, and negative values move backward.
+ * @param {TimestampMsInput} [fromValue=Date.now()] - The base time as a timestamp.
+ * @returns {Date} A `Date` object representing the computed time.
+ *
+ * @example
+ * // Get the date 7 days from now
+ * dateInDays(7); // Returns a Date object 7 days in the future
+ *
+ * @example
+ * // Get the date 5 days before a specific time
+ * dateInDays(-5, new Date('2023-01-01T00:00:00Z')); // Returns 2022-12-27T00:00:00Z
+ *
+ * @example
+ * // Use a timestamp as the base time
+ * dateInDays(2, 1672531200000); // Returns a Date object 2 days after the base timestamp
+ *
+ * @group Date
+ */
+declare function dateInDays(days: number, fromValue?: TimestampMsInput): Date;
+
+/**
+ * Returns a `Date` object representing a time that is the given number of seconds
+ * before or after a base time.
+ *
+ * @param {number} seconds - The number of seconds to add to or subtract from the base time.
+ *                           Positive values move forward in time, and negative values move backward.
+ * @param {TimestampMsInput} [fromValue=Date.now()] - The base time.
+ * @returns {Date} A `Date` object representing the computed time.
+ *
+ * @example
+ * // Get the date 60 seconds from now
+ * dateInSeconds(60); // Returns a Date object 1 minute in the future
+ *
+ * @example
+ * // Get the date 30 seconds before a specific time
+ * dateInSeconds(-30, new Date('2023-01-01T00:00:00Z')); // Returns 2022-12-31T23:59:30Z
+ *
+ * @example
+ * // Use a timestamp as the base time
+ * dateInSeconds(10, 1672531200000); // Returns a Date object 10 seconds after the base timestamp
+ *
+ * @group Date
+ */
+declare function dateInSeconds(seconds: number, fromValue?: TimestampMsInput): Date;
+
+/**
+ * Gets a random time within the specified range.
+ *
+ * Generates a random hour (`h`) and minute (`m`) between the given `startTime` and `endTime`.
+ * If no range is provided, it defaults to the full day from `{ h: 0, m: 0 }` to `{ h: 23, m: 59 }`.
+ *
+ * @param {TimeObject} [startTime={ h: 0, m: 0 }] - The starting range for the random time.
+ * @param {TimeObject} [endTime={ h: 23, m: 59 }] - The ending range for the random time.
+ * @returns {TimeObject} - A random time object with `h` and `m` values within the given range.
+ *
+ * @example
+ * // Generate a random time within the full day
+ * const randomTime = getRandomTime();
+ * console.log(randomTime); // e.g., { h: 12, m: 34 }
+ *
+ * @example
+ * // Generate a random time between 9:00 and 17:00
+ * const randomTime = getRandomTime({ h: 9, m: 0 }, { h: 17, m: 0 });
+ * console.log(randomTime); // e.g., { h: 12, m: 15 }
+ *
+ * @example
+ * // Generate a random time between 8:30 and 10:30
+ * const randomTime = getRandomTime({ h: 8, m: 30 }, { h: 10, m: 30 });
+ * console.log(randomTime); // e.g., { h: 9, m: 45 }
+ *
+ * @group Date
+ */
+declare function getRandomTime(startTime?: TimeObject, endTime?: TimeObject): TimeObject;
+
+/**
+ * Converts a decimal representation of hours and minutes (HH.MM) into total seconds.
+ *
+ * This function takes a decimal number in the format `HH.MM`, where:
+ * - The integer part represents the number of hours.
+ * - The fractional part represents the minutes (in decimal) and is converted accordingly.
+ *
+ * It returns the total time in seconds.
+ *
+ * @param {number} hm - The time represented in HH.MM format (e.g., 2.30 for 2 hours and 30 minutes).
+ * @returns {number} - The total number of seconds equivalent to the provided HH.MM value.
+ *
+ * @example
+ * hmToSeconds(1.00);
+ * // Returns 3600 (1 hour = 3600 seconds)
+ *
+ * @example
+ * hmToSeconds(2.30);
+ * // Returns 9000 (2 hours and 30 minutes = 2 * 3600 + 30 * 60 = 9000 seconds)
+ *
+ * @example
+ * hmToSeconds(0.15);
+ * // Returns 900 (0 hours and 15 minutes = 15 minutes = 900 seconds)
+ *
+ * @example
+ * hmToSeconds(3.45);
+ * // Returns 13500 (3 hours and 45 minutes = 3 * 3600 + 45 * 60 = 13500 seconds)
+ *
+ * @group Date
+ */
+declare function hmToSeconds(hm: number): number;
+
+/**
+ * Checks if a given value is a valid `DateObject`.
+ *
+ * A valid `DateObject` is an object that contains numeric `year`, `month`, and `date` properties.
+ *
+ * @param {unknown} value - The value to be checked.
+ * @returns {value is DateObject} - Returns `true` if the value is a valid `DateObject`; otherwise, `false`.
+ *
+ * @example
+ * // Valid DateObject
+ * isDateObject({ year: 2024, month: 11, date: 8 }); // true
+ *
+ * @example
+ * // Missing properties
+ * isDateObject({ year: 2024, month: 11 }); // false
+ *
+ * @example
+ * // Non-numeric values
+ * isDateObject({ year: '2024', month: 11, date: 8 }); // false
+ *
+ * @example
+ * // Non-object input
+ * isDateObject('invalid'); // false
+ *
+ * @example
+ * // Additional properties (still valid)
+ * isDateObject({ year: 2024, month: 11, date: 8, extra: 'property' }); // true
+ *
+ * @group Date
+ */
+declare function isDateObject(value: unknown): value is DateObject;
+
+/**
+ * Checks if a given value is a valid `TimeObject`.
+ *
+ * @param {unknown} value - The value to check if it's a valid `TimeObject`.
+ * @returns {value is TimeObject} - Returns `true` if the value is a valid `TimeObject`, otherwise `false`.
+ *
+ * @example
+ * // Valid TimeObject
+ * isTimeObject({ h: 15, m: 30 }); // true
+ *
+ * @example
+ * // Invalid TimeObject (missing `m`)
+ * isTimeObject({ h: 15 }); // false
+ *
+ * @example
+ * // Invalid TimeObject (non-number values)
+ * isTimeObject({ h: '15', m: 30 }); // false
+ * isTimeObject({ h: 15, m: '30' }); // false
+ *
+ * @example
+ * // Invalid TimeObject (out-of-range hours)
+ * isTimeObject({ h: -1, m: 30 }); // false
+ * isTimeObject({ h: 24, m: 30 }); // false
+ *
+ * @example
+ * // Invalid TimeObject (out-of-range minutes)
+ * isTimeObject({ h: 15, m: -1 }); // false
+ * isTimeObject({ h: 15, m: 60 }); // false
+ *
+ * @example
+ * // Invalid TimeObject (non-object input)
+ * isTimeObject('string'); // false
+ * isTimeObject(123); // false
+ * isTimeObject([]); // false
+ *
+ * @group Date
+ */
+declare function isTimeObject(value: unknown): value is TimeObject;
+
+/**
+ * Checks if a given value is a valid `TimeString`.
+ *
+ * @param {unknown} value - The value to check if it's a valid `TimeString`.
+ * @returns {value is TimeObject} - Returns `true` if the value is a valid `TimeString`, otherwise `false`.
+ *
+ * @example
+ * // Valid TimeString
+ * isTimeString('15:30'); // true
+ *
+ * @example
+ * // Invalid TimeString
+ * isTimeObject('15:30:00'); // false
+ *
+ * @example
+ * // Invalid TimeString (out-of-range hours)
+ * isTimeObject('26:00'); // false
+ *
+ * @group Date
+ */
+declare function isTimeString(value: unknown): value is TimeString;
+
+/**
+ * Checks if a given value is a valid `TimeValue`.
+ *
+ * @param {unknown} value - The value to check if it's a valid `TimeValue`.
+ * @returns {value is TimeObject} - Returns `true` if the value is a valid `TimeValue`, otherwise `false`.
+ *
+ * @example
+ * // Valid TimeObject
+ * isTimeValue({ h: 15, m: 30 }); // true
+ *
+ * @example
+ * // Valid TimeString
+ * isTimeValue('15:30'); // true
+ *
+ * @group Date
+ */
+declare function isTimeValue(value: unknown): value is TimeValue;
+
+/**
+ * Checks if a given value is a valid weekday number.
+ *
+ * A valid weekday number is a number between 1 (Monday) and 7 (Sunday), inclusive.
+ *
+ * @param {unknown} value - The value to check if it's a valid weekday number.
+ * @returns {value is number} - Returns `true` if the value is a number and represents a valid weekday, otherwise `false`.
+ *
+ * @example
+ * // Valid weekday numbers
+ * isValidWeekDay(1); // true
+ * isValidWeekDay(7); // true
+ *
+ * @example
+ * // Invalid weekday numbers
+ * isValidWeekDay(0); // false
+ * isValidWeekDay(8); // false
+ * isValidWeekDay(-1); // false
+ * isValidWeekDay('3'); // false
+ * isValidWeekDay(null); // false
+ * isValidWeekDay(undefined); // false
+ *
+ * @group Date
+ */
+declare function isValidWeekDay(value: unknown): value is number;
+
+/**
+ * Converts seconds to a decimal representation of hours and minutes (HH.MM) rounded to two decimal places.
+ *
+ * This function takes a number of seconds, calculates the number of whole hours and minutes,
+ * and converts them into a two-decimal representation where:
+ * - The integer part represents the hours.
+ * - The fractional part represents the minutes (rounded to 2 digits).
+ *
+ * @param {number} seconds - The total number of seconds to convert into hours and minutes.
+ * @returns {number} - A decimal number in the format HH.MM representing the converted time.
+ *
+ * @example
+ * secondsToHm(3661);
+ * // Returns 1.01 (1 hour and 1 minute)
+ *
+ * @example
+ * secondsToHm(7322);
+ * // Returns 2.02 (2 hours and 2 minutes)
+ *
+ * @example
+ * secondsToHm(59);
+ * // Returns 0.59 (0 hours and 59 minutes)
+ *
+ * @example
+ * secondsToHm(3600);
+ * // Returns 1.00 (exactly 1 hour)
+ *
+ * @group Date
+ */
+declare function secondsToHm(seconds: number): number;
+
+declare function timeFromMinutes(value: number): TimeObject;
+declare function timeFromMinutes(value: number, returnsNullWhenInvalid: true): TimeObject | null;
+
+/**
+ * Returns the number of seconds since the Unix epoch (January 1, 1970).
+ *
+ * This function accepts either a `Date` object or a timestamp in milliseconds (number).
+ * If no argument is provided, it defaults to the current timestamp in seconds.
+ *
+ * @param {Date | number} [fromValue=Date.now()] - The date or timestamp to convert.
+ * If not provided, the current date and time will be used.
+ *
+ * @returns {number} The number of seconds since the Unix epoch for the provided date or timestamp.
+ *
+ * @example
+ * // Using a Date object
+ * const date = new Date('2020-01-01T00:00:00Z');
+ * console.log(timestamp(date)); // Returns 1577836800 (seconds since Unix epoch)
+ *
+ * // Using a timestamp in milliseconds
+ * const timestampInMs = 1609459200000;
+ * console.log(timestamp(timestampInMs)); // Returns 1609459200 (seconds since Unix epoch)
+ *
+ * // Using the current time
+ * console.log(timestamp()); // Returns current seconds since Unix epoch
+ *
+ * @group Date
+ */
+declare function timestamp(fromValue?: Date | number): number;
+
+/**
+ * Converts a Unix timestamp (in seconds) to a `Date` object.
+ *
+ * This function accepts a timestamp in seconds (number) and returns a `Date` object
+ * corresponding to that timestamp. If an invalid number is passed (non-numeric or NaN),
+ * it returns `null`.
+ *
+ * @param {number} value - The Unix timestamp (in seconds) to convert into a `Date` object.
+ * @returns {Date | null} The `Date` object corresponding to the provided timestamp, or `null`
+ * if the value is not a valid number.
+ *
+ * @example
+ * const date = timestampToDate(1609459200);
+ * console.log(date); // Outputs: Thu Jan 01 2021 00:00:00 GMT+0000 (UTC)
+ *
+ * // Invalid input
+ * console.log(timestampToDate('invalid')); // Outputs: null
+ * console.log(timestampToDate(NaN)); // Outputs: null
+ * console.log(timestampToDate(null)); // Outputs: null
+ *
+ * @group Date
+ */
+declare function timestampToDate(value: number): Date | null;
+
+declare function timeStringify(value: TimeValue): string;
+declare function timeStringify(value: TimeValue, returnsNullWhenInvalid: true): string | null;
+
+/**
+ * Converts a time value into the total number of minutes.
+ *
+ * @param {TimeValue} value - A time value
+ *
+ * @returns {number} The total number of minutes represented by the time value.
+ *
+ * @example
+ * // Assuming createTimeObject("2:30") returns { h: 2, m: 30 }
+ * timeToMinutes("2:30"); // 150
+ *
+ * // Assuming createTimeObject({ h: 1, m: 45 }) returns { h: 1, m: 45 }
+ * timeToMinutes({ h: 1, m: 45 }); // 105
+ *
+ * @group Date
+ */
+declare function timeToMinutes(value: TimeValue): number;
+
+/**
+ * Determines the number of ISO weeks in a given year.
+ *
+ * The ISO week numbering system defines a year as having 52 or 53 full weeks.
+ *
+ * @param {number} year - The year for which to calculate the number of ISO weeks.
+ * @returns {number} - Returns 52 or 53 based on the ISO 8601 standard.
+ *
+ * @example
+ * // Common year with 52 weeks
+ * weeksInYear(2023); // 52
+ *
+ * @example
+ * // Leap year with 53 weeks
+ * weeksInYear(2020); // 53
+ *
+ * @group Date
+ */
+declare function weeksInYear(year: number): number;
+
+type EJSONType = {
+    /**
+     * The string placeholder (must start with `$`) that represents the custom type.
+     */
+    placeholder: string;
+    /**
+     * Should encoded value inlined to original key
+     */
+    encodeInline?: boolean;
+    /**
+     * Function to encode a value into a custom representation using a custom type handler.
+     *
+     * If the function returns `undefined`, it signals that encoding for this value should
+     * be delegated to another type handler or encoding logic.
+     *
+     * @param {any} value - The value to be encoded.
+     * @param {(value: any) => any} encode - A reference to the general encoding function
+     *                                       (useful for recursive encoding logic if necessary).
+     * @returns {any} - The custom-encoded value or `undefined` to delegate encoding to another type handler.
+     */
+    encode: (value: any, encode: (value: any) => any) => any;
+    /**
+     * A function to decode a custom representation back into a valid JavaScript value.
+     */
+    decode: (value: any) => any;
+};
+/**
+ * EJSON - Extended JSON handler class for custom encoding and decoding with vendor support.
+ * This class provides methods to encode, decode, stringify, and parse JSON with custom type handlers.
+ */
+declare class EJSON {
+    /** @internal */
+    protected typeHandlers: Map<string, Readonly<EJSONType>>;
+    /** @internal */
+    protected replacerReady: (value: any, key: string) => any;
+    /** @internal */
+    protected encode: (value: any) => any;
+    /** @internal */
+    protected reviewerReady: (_: string, value: any) => any;
+    /** @internal */
+    protected pure: boolean;
+    protected _vendorName: string | null;
+    /**
+     * MIME type based on the provided vendor name or defaults to 'application/json'.
+     */
+    mimetype: string;
+    readonly Type: {
+        readonly Date: EJSONType;
+        readonly Map: EJSONType;
+        readonly Set: EJSONType;
+        readonly RegExp: EJSONType;
+        readonly Infinity: EJSONType;
+        readonly BigInt: EJSONType;
+        readonly Binary: EJSONType;
+    };
+    constructor();
+    /**
+     * The vendor name used for the custom MIME type definition.
+     * If null, defaults to 'application/json'.
+     */
+    get vendorName(): string | null;
+    set vendorName(value: string | null);
+    /**
+     * Adds a custom type handler for encoding/decoding logic.
+     * Ensures type placeholders are unique and adhere to conventions.
+     */
+    addType(type: Readonly<EJSONType>): this;
+    /**
+     * Stringifies a JavaScript value using custom encoding logic.
+     * @param {any} value - The value to encode and stringify.
+     * @param {string | number} [space] - Optional space for pretty-printing.
+     * @returns {string} - The JSON stringified value.
+     */
+    stringify(value: any, space?: string | number): string;
+    /**
+     * Parses a JSON string using custom decoding logic.
+     * @param {string} value - The JSON string to parse.
+     * @returns {any} - The decoded JavaScript object.
+     */
+    parse(value: string): any;
+    /** @internal */
+    protected _replacer(value: any, key: string): any;
+    /** @internal */
+    protected _reviewer(_: string, value: any): any;
+}
+
+/**
+ * Creates a new instance of the `EJSON` (Extensible JSON) with optional basic types pre-registered.
+ *
+ * This function allows you to initialize an `EJSON` instance with commonly used types like `Map`, `Set`,
+ * `Date`, `RegExp`, `Infinity`, `BigInt` and `Uint8Array`. These types are added to the type handlers only when `withBasicTypes` is set to `true`.
+ *
+ * | Type        | Placeholder | Alias          |
+ * |-------------|-------------|----------------|
+ * | Date        | $date       | EJSON.Date     |
+ * | Map         | $map        | EJSON.Map      |
+ * | Set         | $set        | EJSON.Set      |
+ * | Infinity    | $inf        | EJSON.Infinity |
+ * | BigInt      | $bigint     | EJSON.BigInt   |
+ * | RegExp      | $regexp     | EJSON.RegExp   |
+ * | Uint8Array  | $binary     | EJSON.Binary   |
+ * | Uint16Array | $binary     | EJSON.Binary   |
+ * | Uint32Array | $binary     | EJSON.Binary   |
+ *
+ * @param {boolean} [withBasicTypes=false] - Indicates whether to include basic types like Map, Set, Date, and BigInt.
+ * @returns {EJSON} - A new instance of the `EJSON` class configured with optional basic types.
+ *
+ * @example
+ * // Instance with basic types (Map, Set, Date, BigInt, Uint8Array)
+ * import { EJSON } from '@andrew_l/toolkit';
+ *
+ * EJSON.stringify({ value: new Date(0) });
+ * // {"value":{"$date": 0}}
+ *
+ * @example
+ * // Create an EJSON instance without any additional types
+ * const ejson = createEJSON();
+ *
+ * ejson.stringify({ value: new Date(0) });
+ * // {"value":"1970-01-01T00:00:00.000Z"}
+ *
+ * @example
+ * // Custom type
+ * import { EJSON, createEJSON } from '@andrew_l/toolkit';
+ *
+ * const ejson = createEJSON();
+ *
+ * ejson.vendorName = 'Andrew';
+ *
+ * // Add pre-build date type
+ * ejson.addType(EJSON.Date);
+ *
+ * // Add custom buffer type
+ * ejson.addType({
+ *   placeholder: '$buffer',
+ *   encode(value) {
+ *     if (Buffer.isBuffer(value)) {
+ *       return value.toString('hex');
+ *     }
+ *   },
+ *   decode(value) {
+ *     return Buffer.from(value, 'hex');
+ *   }
+ * });
+ *
+ * ejson.stringify({
+ *   value: [
+ *     Buffer.from('Hello World', 'utf8'),
+ *     new Date(0)
+ *   ]
+ * });
+ * // {"value":[{"$buffer":"48656c6c6f20576f726c64"},{"$date":0}]}
+ *
+ * console.log(ejson.mimetype); // application/vnd.andrew+json
+ *
+ * @group EJSON
+ */
+declare function createEJSON(withBasicTypes?: boolean): EJSON;
+
+interface EJSONStreamOptions {
+    /**
+     * EJSON Instance
+     */
+    ejson: EJSON;
+    /**
+     * Starting encoding symbol
+     */
+    op: string;
+    /**
+     * Separator symbol
+     */
+    sep: string;
+    /**
+     * Ending symbol
+     */
+    cl: string;
+    /** @internal */
+    onStart?: (controller: TransformStreamDefaultController) => Promise<void>;
+    /** @internal */
+    onFlush?: (controller: TransformStreamDefaultController) => Promise<void>;
+}
+declare class EJSONStream extends TransformStream<any, string> {
+    protected ejson: EJSON;
+    constructor({ ejson, cl, op, sep, onFlush, onStart }: EJSONStreamOptions);
+    /**
+     * The vendor name used for the custom MIME type definition.
+     * If null, defaults to 'application/json'.
+     */
+    get vendorName(): string | null;
+    /**
+     * MIME type based on the provided vendor name or defaults to 'application/json'.
+     */
+    get mimetype(): string;
+}
+
+interface EJSONStreamOptionsWithPayload extends Partial<EJSONStreamOptions> {
+    prepend?: () => Awaitable<object | null | undefined>;
+    append?: () => Awaitable<object | null | undefined>;
+    resultKey: string;
+}
+/**
+ * Creates an instance of `EJSONStream`. This function provides flexibility to create a simple stream
+ * or one with custom payload transformations, such as appending or prepending data.
+ *
+ * The function has overloads to handle either basic streaming options or more advanced use cases
+ * with payload functions (`append`, `prepend`, `resultKey`) to modify how JSON payloads are streamed.
+ *
+ * @function
+ * @param {Partial<EJSONStreamOptions> | EJSONStreamOptionsWithPayload} [options] - Options to configure the EJSONStream.
+ * @returns {EJSONStream} An instance of the `EJSONStream`.
+ *
+ * @example
+ * // Example 1: Create a simple EJSONStream without custom payload transformations
+ * const stream = createEJSONStream();
+ *
+ * @example
+ * // Example 2: Create EJSONStream with specific options
+ * const stream = createEJSONStream({
+ *   cl: ']',
+ *   op: '[',
+ *   sep: ',',
+ *   ejson: someInstance
+ * });
+ *
+ * @example
+ * // Example 3: Using prepend and append payloads
+ * const streamWithPayloads = createEJSONStream({
+ *   prepend: async () => ({ key1: 'value1' }),
+ *   append: async () => ({ key2: 'value2' }),
+ *   resultKey: 'payload'
+ * });
+ *
+ * // {"key1":"value1","payload": [...data],"key2":"value2"}
+ *
+ * @group EJSON
+ */
+declare function createEJSONStream(options?: Partial<EJSONStreamOptions>): EJSONStream;
+declare function createEJSONStream(options: EJSONStreamOptionsWithPayload): EJSONStream;
+
+declare const instance: EJSON;
+
+type Dict<T> = {
+    [key: string]: T | undefined;
+};
+type ListTypeName = 'bool' | 'int' | 'decimal' | 'string';
+type ListTypeNameToType<T extends ListTypeName> = T extends 'bool' ? boolean : T extends 'int' ? number : T extends 'decimal' ? number : T extends 'string' ? string : never;
+/**
+ * Environment variable parser
+ *
+ * @group Environment
+ */
+interface EnvParser {
+    /**
+     * NODE_ENV is `development`
+     */
+    isDevelopment: boolean;
+    /**
+     * NODE_ENV is `production`
+     */
+    isProduction: boolean;
+    /**
+     * NODE_ENV is `stage`
+     */
+    isStage: boolean;
+    /**
+     * NODE_ENV is `test`
+     */
+    isTest: boolean;
+    /**
+     * Returns `true` when environment key has set to `"true"`
+     *
+     * Returns `defaultValue` when key is not defined
+     */
+    bool(key: string, defaultValue?: boolean): boolean;
+    /**
+     * Returns `number` when environment key has correct number value.
+     *
+     * Returns `defaultValue` when environment key is not defined or has invalid number value
+     */
+    int(key: string, defaultValue?: number): number;
+    /**
+     * Returns `number` when environment key has correct number value.
+     *
+     * Returns `defaultValue` when environment key is not defined or has invalid number value
+     */
+    decimal(key: string, dights?: number, defaultValue?: number): number;
+    /**
+     * Returns `string` when environment key has defined.
+     *
+     * Returns `defaultValue` when environment key is not defined
+     */
+    string(key: string, defaultValue?: string): string;
+    /**
+     * Returns `array` of parsed environment value.
+     *
+     * Returns `defaultValue` when key is not defined
+     */
+    list<T extends ListTypeName>(key: string, itemType: T, defaultValue?: ListTypeNameToType<T>[]): ListTypeNameToType<T>[];
+    /**
+     * Returns parsed json value.
+     *
+     * Returns `defaultValue` when key is not defined or invalid json value
+     */
+    json<T = any>(key: string, defaultValue?: T | null): T | null;
+}
+/**
+ * Ready-to-use environment parser.
+ *
+ * Target: `process.env`
+ *
+ * Fallback: `import.meta.env`
+ *
+ * @example
+ *
+ * // env.string
+ * const API_KEY = env.string('API_KEY', 'test_key');
+ *
+ * // env.bool
+ * const TEST_FEATURE = env.bool('TEST_FEATURE', false);
+ *
+ * // env.int
+ * const RETRY_ATTEMPTS = env.int('RETRY_ATTEMPTS', 5);
+ *
+ * // env.decimal
+ * const DELAY_SECONDS = env.decimal('DELAY_SECONDS', 2, 5); // round to 2 dights
+ *
+ * // env.list
+ * const TARGET_ROLES = env.list('TARGET_ROLES', 'string', ['ADMIN']);
+ *
+ * // env.json
+ * const GOOGLE_CREDS = env.json<{ projectId: string; token: string; }>('GOOGLE_CREDS');
+ *
+ * @group Environment
+ */
+declare const env: Readonly<EnvParser>;
+/**
+ * @example
+ * const env = createEnvParser(process.env);
+ * // const env = createEnvParser(import.meta.env);
+ *
+ * const API_KEY = env.string('API_KEY', 'test_key');
+ *
+ * @group Environment
+ */
+declare function createEnvParser(targetObject: Record<string, string> | Dict<string>): Readonly<EnvParser>;
+
+/**
+ * Simple application error class with the code
+ * @group Errors
  */
 declare class AppError extends Error {
     code: number;
@@ -1374,16 +2597,32 @@ declare const isFunction: <T extends Function>(val: any) => val is T;
  * @group Predicates
  */
 declare const isNumber: (val: any) => val is number;
+/**
+ * Checks if the given value is a `Infinity` number.
+ *
+ * @example
+ * console.log(isInfinity(123)); // false
+ * console.log(isNumber(Infinity)); // true
+ * console.log(isNumber(-Infinity)); // true
+ *
+ * @group Predicates
+ */
+declare const isInfinity: (val: any) => val is number;
 /**
  * Checks if the given value is a `string`
  * @group Predicates
  */
 declare const isString: (val: unknown) => val is string;
 /**
- * Checks if the given value is a plain `object`
+ * Checks if the given value is a `object`
  * @group Predicates
  */
 declare const isObject: (val: any) => val is object;
+/**
+ * Checks if the given value is a plain `object`
+ * @group Predicates
+ */
+declare const isPlainObject: (val: any) => val is object;
 /**
  * Checks if the given value is valid `Date`
  * @group Predicates
@@ -1956,57 +3195,6 @@ declare function percentOf(value: number, percent: number, digits?: number): num
  */
 declare function round2digits(value: number, digits?: number): number;
 
-/**
- * Returns the number of seconds since the Unix epoch (January 1, 1970).
- *
- * This function accepts either a `Date` object or a timestamp in milliseconds (number).
- * If no argument is provided, it defaults to the current timestamp in seconds.
- *
- * @param {Date | number} [fromValue=Date.now()] - The date or timestamp to convert.
- * If not provided, the current date and time will be used.
- *
- * @returns {number} The number of seconds since the Unix epoch for the provided date or timestamp.
- *
- * @example
- * // Using a Date object
- * const date = new Date('2020-01-01T00:00:00Z');
- * console.log(timestamp(date)); // Returns 1577836800 (seconds since Unix epoch)
- *
- * // Using a timestamp in milliseconds
- * const timestampInMs = 1609459200000;
- * console.log(timestamp(timestampInMs)); // Returns 1609459200 (seconds since Unix epoch)
- *
- * // Using the current time
- * console.log(timestamp()); // Returns current seconds since Unix epoch
- *
- * @group Numbers
- */
-declare function timestamp(fromValue?: Date | number): number;
-
-/**
- * Converts a Unix timestamp (in seconds) to a `Date` object.
- *
- * This function accepts a timestamp in seconds (number) and returns a `Date` object
- * corresponding to that timestamp. If an invalid number is passed (non-numeric or NaN),
- * it returns `null`.
- *
- * @param {number} value - The Unix timestamp (in seconds) to convert into a `Date` object.
- * @returns {Date | null} The `Date` object corresponding to the provided timestamp, or `null`
- * if the value is not a valid number.
- *
- * @example
- * const date = timestampToDate(1609459200);
- * console.log(date); // Outputs: Thu Jan 01 2021 00:00:00 GMT+0000 (UTC)
- *
- * // Invalid input
- * console.log(timestampToDate('invalid')); // Outputs: null
- * console.log(timestampToDate(NaN)); // Outputs: null
- * console.log(timestampToDate(null)); // Outputs: null
- *
- * @group Numbers
- */
-declare function timestampToDate(value: number): Date | null;
-
 /**
  * Removes properties with empty values from an object.
  *
@@ -3152,7 +4340,7 @@ type RetryOnErrorConfig = {
     /**
      * Error validation function. If returns true, the main callback's considered ready to be executed again
      */
-    shouldRetryBasedOnError: (error: unknown, attempt: number) => boolean;
+    shouldRetryBasedOnError?: (error: unknown, attempt: number) => boolean;
     /**
      * Number of retries until the execution fails
      */
@@ -3186,7 +4374,7 @@ type RetryOnErrorConfig = {
  *
  * @group Errors
  */
-declare function retryOnError<T extends AnyFunction>({ beforeRetryCallback, maxRetriesNumber, shouldRetryBasedOnError, delayFactor, delayMaxMs, delayMinMs, }: RetryOnErrorConfig, fn: T): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
+declare function retryOnError<T extends AnyFunction>({ beforeRetryCallback, shouldRetryBasedOnError, maxRetriesNumber, delayFactor, delayMaxMs, delayMinMs, }: RetryOnErrorConfig, fn: T): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
 
 /**
  * Converts a string to camel case.
@@ -3722,4 +4910,4 @@ declare function wrapText(value: string, maxLength?: number): string;
  */
 declare function toError<T>(value: T, unknownMessage?: string): T extends Error ? T : Error;
 
-export { type AnyFunction, AppError, type ArgumentsType, type Arrayable, AsyncIterableQueue, type Awaitable, BrowserAssertionError, CancellablePromise, Color, type ColorChannels, ColorParser, type Data, type DeepPartial, type Defer, type EnvParser, type ExecResult, type ExecResultToSkip, type ExecResultToSuccess, type ExecSkip, type ExecSuccess, FixedMap, FixedWeakMap, type Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, type RetryOnErrorConfig, type SelectOptionItem, type SelectOptions, type SimpleDefaultEventMap, SimpleEventEmitter, type SimpleEventMap, _default as TWEMOJI_REGEX, type ThemeConfig, TimeBucket, type TimeBucketOptions, type TimeObject, type TypeOf, type TypeOfMap, type ValuesOfObject, type WithCache, type WithCacheBucketBatchOptions, type WithCacheBucketOptions, type WithCacheFixedOptions, type WithCacheLruOptions, type WithCacheOptions, type WithCachePointer, type WithCacheResult, type WithCacheStorage, type WithCustomizer, type WithCustomizerFactory, type WithCustomizerValue, alpha, arrayable, assert, asyncFilter, asyncFind, asyncForEach, asyncMap, avg, blendColors, buildCssColor, cache, cacheBucket, cacheFixed, cacheLRU, camelCase, capitalize, captureStackTrace, catchError, channelsToHSL, channelsToHex, channelsToRGB, checkBitmask, chunk, chunkSeries, clamp, cleanEmpty, cleanObject, colorToChannels, contrastRatio, convertToUnit, crc32, createCustomizer, createCustomizerFactory, createDeepCloneWith, createEnvParser, createRandomizer, createSecureCustomizer, createWithCache, cssVariable, deepAssign, deepClone, deepCloneWith, deepDefaults, deepFreeze, def, defer, delay, dropCache, env, escapeHtml, escapeNumeric, escapeRegExp, fastIdle, fastIdlePromise, fastRaf, findMean, flagsToMap, flatten, formatMoney, formatNumber, get, getFileExtension, getFileName, getInitials, getRandomInt, getWords, has, hasOwn, hasProtocol, hex, hexToChannels, hslToChannels, humanFileSize, humanize, interpolateColor, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDef, isEmpty, isEqual, isError, isFunction, isMap, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPrimitive, isPromise, isSet, isSkip, isString, isSuccess, isSymbol, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, round2digits, set, snakeCase, sprintf, startCase, strAssign, sum, timeout, timestamp, timestampToDate, tintedTextColor, toError, toMap, truncate, typeOf, unflatten, union, uniq, uniqBy, unset, withCache, withCacheBucket, withCacheBucketBatch, withCacheFixed, withCacheLRU, withDeepClone, withPointerCache, wrapText };
+export { type AnyFunction, AppError, type ArgumentsType, type Arrayable, AsyncIterableQueue, type Awaitable, type Base64ToBytesOptions, BrowserAssertionError, type BytesToBase64Options, CancellablePromise, type CatchErrorResult, Color, type ColorChannels, ColorParser, type Data, type DateObject, type DateObjectInput, type DeepPartial, type Defer, instance as EJSON, EJSONStream, type EJSONStreamOptions, type EJSONStreamOptionsWithPayload, type EnvParser, type ExecResult, type ExecResultToSkip, type ExecResultToSuccess, type ExecSkip, type ExecSuccess, FindMean, FixedMap, FixedWeakMap, type Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, type RetryOnErrorConfig, type SelectOptionItem, type SelectOptions, type SimpleDefaultEventMap, SimpleEventEmitter, type SimpleEventMap, _default as TWEMOJI_REGEX, type ThemeConfig, TimeBucket, type TimeBucketOptions, type TimeObject, type TimeObjectInput, TimeSpan, type TimeSpanUnit, type TimeString, type TimeValue, type TimestampMsInput, type TypeOf, type TypeOfMap, type ValuesOfObject, type WithCache, type WithCacheBucketBatchOptions, type WithCacheBucketOptions, type WithCacheFixedOptions, type WithCacheLruOptions, type WithCacheOptions, type WithCachePointer, type WithCacheResult, type WithCacheStorage, type WithCustomizer, type WithCustomizerFactory, type WithCustomizerValue, alpha, arrayable, assert, asyncFilter, asyncFind, asyncForEach, asyncMap, avg, base64ToBytes, bigIntBytes, bigIntFromBytes, blendColors, buildCssColor, bytesToBase64, cache, cacheBucket, cacheFixed, cacheLRU, camelCase, capitalize, captureStackTrace, catchError, channelsToHSL, channelsToHex, channelsToRGB, checkBitmask, chunk, chunkSeries, clamp, cleanEmpty, cleanObject, colorToChannels, compareBytes, concatenateBytes, contrastRatio, convertToUnit, crc32, createCustomizer, createCustomizerFactory, createDateObject, createDeepCloneWith, createEJSON, createEJSONStream, createEnvParser, createRandomizer, createSecureCustomizer, createTimeObject, createTimeSpan, createWithCache, cssVariable, dateInDays, dateInSeconds, deepAssign, deepClone, deepCloneWith, deepDefaults, deepFreeze, def, defer, delay, difference, dropCache, env, escapeHtml, escapeNumeric, escapeRegExp, fastIdle, fastIdlePromise, fastRaf, findMean, flagsToMap, flatten, formatMoney, formatNumber, get, getFileExtension, getFileName, getInitials, getRandomInt, getRandomTime, getWords, has, hasOwn, hasProtocol, hex, hexToChannels, hmToSeconds, hslToChannels, humanFileSize, humanize, interpolateColor, intersection, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPlainObject, isPrimitive, isPromise, isSet, isSkip, isString, isSuccess, isSymbol, isTimeObject, isTimeString, isTimeValue, isValidWeekDay, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, round2digits, secondsToHm, set, shuffle, snakeCase, sprintf, startCase, strAssign, sum, timeFromMinutes, timeStringify, timeToMinutes, timeout, timestamp, timestampMs, timestampToDate, tintedTextColor, toError, toMap, truncate, typeOf, uint16ToUint8, uint32ToUint8, uint8ToUint16, uint8ToUint32, unflatten, union, uniq, uniqBy, unset, weeksInYear, withCache, withCacheBucket, withCacheBucketBatch, withCacheFixed, withCacheLRU, withDeepClone, withPointerCache, wrapText };