@kikiutils/shared 15.0.3 → 15.1.1

package/src/classes/precision-number.ts

@@ -1,22 +1,28 @@
 import { Decimal } from 'decimal.js';
 
+/**
+ * Values accepted by `PrecisionNumber` constructors and arithmetic methods.
+ */
 export type PrecisionNumberValue = Decimal.Value | PrecisionNumber | { toString: () => string };
 
 /**
- * Class representing a precision number with configurable decimal places and rounding.
+ * Chainable fixed-decimal wrapper around `decimal.js`.
  *
- * 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.).
+ * `PrecisionNumber` stores values as `Decimal`, rounds every mutating operation to
+ * the configured decimal places, and exposes both mutable and immutable arithmetic
+ * methods. Mutable methods (`plus`, `minus`, `times`, `dividedBy`, `modulo`,
+ * `pow`, `clamp`, `ceil`, `floor`, `negate`, `absoluteValue`) update the current
+ * instance and return `this`; immutable methods prefixed with `to` return a new
+ * `PrecisionNumber` with the same precision settings.
  *
- * The class also includes custom symbol methods to support Node.js inspection and primitive
- * type conversion.
+ * @example
+ * ```typescript
+ * import { PrecisionNumber } from '@kikiutils/shared/classes/precision-number';
  *
- * 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.
+ * const value = new PrecisionNumber('1.239', 2).plus('2.111');
+ * value.toString(); // '3.35'
+ * value.toMinus('1').toString(); // '2.35' (original value remains '3.35')
+ * ```
  */
 export class PrecisionNumber {
     // Private properties
@@ -24,6 +30,13 @@ export class PrecisionNumber {
     readonly #rounding: Decimal.Rounding;
     #decimal: Decimal;
 
+    /**
+     * Creates a fixed-decimal number.
+     *
+     * @param {PrecisionNumberValue} [value] - Initial value (default: `'0'`)
+     * @param {number} [decimalPlaces] - Decimal places retained after operations (default: `2`)
+     * @param {Decimal.Rounding} [rounding] - Decimal.js rounding mode (default: `Decimal.ROUND_DOWN`)
+     */
     constructor(
         value: PrecisionNumberValue = '0',
         decimalPlaces: number = 2,
@@ -35,10 +48,19 @@ export class PrecisionNumber {
     }
 
     // Symbols
+
+    /**
+     * Returns the formatted value when inspected by Node.js utilities.
+     */
     [Symbol.for('nodejs.util.inspect.custom')]() {
         return this.value;
     }
 
+    /**
+     * Converts to a number for numeric coercion and to the fixed string otherwise.
+     *
+     * @param {string} hint - JavaScript primitive-conversion hint
+     */
     [Symbol.toPrimitive](hint: string) {
         if (hint === 'number') return this.#decimal.toNumber();
         return this.value;
@@ -49,12 +71,42 @@ export class PrecisionNumber {
         return decimal.toDecimalPlaces(this.#decimalPlaces, this.#rounding);
     }
 
+    #valueToString(value: PrecisionNumberValue) {
+        return value.toString().trim();
+    }
+
     // Public getters
+
+    /**
+     * Decimal places retained by mutating operations and default formatting.
+     */
+    get decimalPlaces() {
+        return this.#decimalPlaces;
+    }
+
+    /**
+     * Decimal.js rounding mode used by mutating operations and default formatting.
+     */
+    get rounding() {
+        return this.#rounding;
+    }
+
+    /**
+     * Fixed-decimal string using the instance precision and rounding mode.
+     */
     get value() {
         return this.#decimal.toFixed(this.#decimalPlaces, this.#rounding);
     }
 
-    // Static methods
+    /**
+     * Formats a value with decimal.js without creating a reusable instance.
+     *
+     * @param {PrecisionNumberValue} value - Value to format
+     * @param {number} [decimalPlaces] - Decimal places to output (default: `2`)
+     * @param {Decimal.Rounding} [rounding] - Decimal.js rounding mode (default: `Decimal.ROUND_DOWN`)
+     *
+     * @returns {string} Fixed-decimal string
+     */
     static toFixed(
         value: PrecisionNumberValue,
         decimalPlaces: number = 2,
@@ -64,117 +116,340 @@ export class PrecisionNumber {
     }
 
     // Public methods
+
+    /**
+     * Replaces the current value with its absolute value.
+     *
+     * @returns {this} The current instance for chaining
+     */
     absoluteValue() {
         this.#decimal = this.#decimalToFixedDecimal(this.#decimal.absoluteValue());
         return this;
     }
 
+    /**
+     * Rounds the current value up to the nearest integer in place.
+     *
+     * The stored value still uses this instance's configured decimal places for output.
+     *
+     * @returns {this} The current instance for chaining
+     */
+    ceil() {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.ceil());
+        return this;
+    }
+
+    /**
+     * Restricts the current value to the inclusive range `[min, max]` in place.
+     *
+     * @param {PrecisionNumberValue} min - Lower bound
+     * @param {PrecisionNumberValue} max - Upper bound
+     *
+     * @returns {this} The current instance for chaining
+     *
+     * @throws {Error} If `min` is greater than `max`
+     */
+    clamp(min: PrecisionNumberValue, max: PrecisionNumberValue) {
+        const minDecimal = new Decimal(this.#valueToString(min));
+        const maxDecimal = new Decimal(this.#valueToString(max));
+        if (minDecimal.gt(maxDecimal)) throw new Error('Invalid clamp range: min cannot be greater than max');
+        this.#decimal = this.#decimalToFixedDecimal(Decimal.min(Decimal.max(this.#decimal, minDecimal), maxDecimal));
+        return this;
+    }
+
+    /**
+     * Returns a new instance with the same value, decimal places, and rounding mode.
+     */
+    clone() {
+        return new PrecisionNumber(this.#decimal, this.#decimalPlaces, this.#rounding);
+    }
+
+    /**
+     * Divides the current value by another value in place.
+     *
+     * @param {PrecisionNumberValue} value - Divisor
+     *
+     * @returns {this} The current instance for chaining
+     */
     dividedBy(value: PrecisionNumberValue) {
-        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.dividedBy(value.toString().trim()));
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.dividedBy(this.#valueToString(value)));
         return this;
     }
 
+    /**
+     * Checks whether the current value equals another value.
+     *
+     * @param {PrecisionNumberValue} value - Value to compare
+     *
+     * @returns {boolean} `true` when both numeric values are equal
+     */
     equals(value: PrecisionNumberValue) {
-        return this.#decimal.equals(value.toString().trim());
+        return this.#decimal.equals(this.#valueToString(value));
+    }
+
+    /**
+     * Rounds the current value down to the nearest integer in place.
+     *
+     * The stored value still uses this instance's configured decimal places for output.
+     *
+     * @returns {this} The current instance for chaining
+     */
+    floor() {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.floor());
+        return this;
     }
 
+    /**
+     * Checks whether the current value is greater than another value.
+     */
     gt(value: PrecisionNumberValue) {
-        return this.#decimal.gt(value.toString().trim());
+        return this.#decimal.gt(this.#valueToString(value));
     }
 
+    /**
+     * Checks whether the current value is greater than or equal to another value.
+     */
     gte(value: PrecisionNumberValue) {
-        return this.#decimal.gte(value.toString().trim());
+        return this.#decimal.gte(this.#valueToString(value));
     }
 
+    /**
+     * Checks whether the current value is finite.
+     */
     isFinite() {
         return this.#decimal.isFinite();
     }
 
+    /**
+     * Checks whether the current value is an integer.
+     */
     isInteger() {
         return this.#decimal.isInteger();
     }
 
+    /**
+     * Checks whether the current value is `NaN`.
+     */
     isNaN() {
         return this.#decimal.isNaN();
     }
 
+    /**
+     * Checks whether the current value is negative.
+     */
     isNegative() {
         return this.#decimal.isNegative();
     }
 
+    /**
+     * Checks whether the current value is positive.
+     */
     isPositive() {
         return this.#decimal.isPositive();
     }
 
+    /**
+     * Checks whether the current value is zero.
+     */
     isZero() {
         return this.#decimal.isZero();
     }
 
+    /**
+     * Checks whether the current value is less than another value.
+     */
     lt(value: PrecisionNumberValue) {
-        return this.#decimal.lt(value.toString().trim());
+        return this.#decimal.lt(this.#valueToString(value));
     }
 
+    /**
+     * Checks whether the current value is less than or equal to another value.
+     */
     lte(value: PrecisionNumberValue) {
-        return this.#decimal.lte(value.toString().trim());
+        return this.#decimal.lte(this.#valueToString(value));
     }
 
+    /**
+     * Subtracts another value from the current value in place.
+     */
     minus(value: PrecisionNumberValue) {
-        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.minus(value.toString().trim()));
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.minus(this.#valueToString(value)));
+        return this;
+    }
+
+    /**
+     * Replaces the current value with the remainder after division by another value.
+     *
+     * @param {PrecisionNumberValue} value - Divisor used to compute the remainder
+     *
+     * @returns {this} The current instance for chaining
+     */
+    modulo(value: PrecisionNumberValue) {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.modulo(this.#valueToString(value)));
         return this;
     }
 
+    /**
+     * Negates the current value in place.
+     */
     negate() {
         this.#decimal = this.#decimalToFixedDecimal(this.#decimal.negated());
         return this;
     }
 
+    /**
+     * Adds another value to the current value in place.
+     */
     plus(value: PrecisionNumberValue) {
-        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.plus(value.toString().trim()));
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.plus(this.#valueToString(value)));
+        return this;
+    }
+
+    /**
+     * Raises the current value to an exponent in place.
+     *
+     * @param {PrecisionNumberValue} value - Exponent
+     *
+     * @returns {this} The current instance for chaining
+     */
+    pow(value: PrecisionNumberValue) {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.pow(this.#valueToString(value)));
         return this;
     }
 
+    /**
+     * Multiplies the current value by another value in place.
+     */
     times(value: PrecisionNumberValue) {
-        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.times(value.toString().trim()));
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.times(this.#valueToString(value)));
         return this;
     }
 
+    /**
+     * Returns a new instance with the absolute value.
+     */
     toAbsoluteValue() {
         return new PrecisionNumber(this.#decimal.absoluteValue(), this.#decimalPlaces, this.#rounding);
     }
 
+    /**
+     * Returns a new instance rounded up to the nearest integer.
+     */
+    toCeil() {
+        return new PrecisionNumber(this.#decimal.ceil(), this.#decimalPlaces, this.#rounding);
+    }
+
+    /**
+     * Returns a new instance restricted to the inclusive range `[min, max]`.
+     *
+     * @param {PrecisionNumberValue} min - Lower bound
+     * @param {PrecisionNumberValue} max - Upper bound
+     *
+     * @throws {Error} If `min` is greater than `max`
+     */
+    toClamped(min: PrecisionNumberValue, max: PrecisionNumberValue) {
+        return this.clone().clamp(min, max);
+    }
+
+    /**
+     * Returns a new instance divided by another value.
+     */
     toDividedBy(value: PrecisionNumberValue) {
         return new PrecisionNumber(
-            this.#decimal.dividedBy(value.toString().trim()),
+            this.#decimal.dividedBy(this.#valueToString(value)),
             this.#decimalPlaces,
             this.#rounding,
         );
     }
 
+    /**
+     * Returns a new instance rounded down to the nearest integer.
+     */
+    toFloor() {
+        return new PrecisionNumber(this.#decimal.floor(), this.#decimalPlaces, this.#rounding);
+    }
+
+    /**
+     * Serializes to the fixed-decimal string.
+     */
     toJSON() {
         return this.value;
     }
 
+    /**
+     * Returns a new instance with another value subtracted.
+     */
     toMinus(value: PrecisionNumberValue) {
-        return new PrecisionNumber(this.#decimal.minus(value.toString().trim()), this.#decimalPlaces, this.#rounding);
+        return new PrecisionNumber(
+            this.#decimal.minus(this.#valueToString(value)),
+            this.#decimalPlaces,
+            this.#rounding,
+        );
     }
 
+    /**
+     * Returns a new instance with the remainder after division by another value.
+     */
+    toModulo(value: PrecisionNumberValue) {
+        return new PrecisionNumber(
+            this.#decimal.modulo(this.#valueToString(value)),
+            this.#decimalPlaces,
+            this.#rounding,
+        );
+    }
+
+    /**
+     * Returns a new instance with the value negated.
+     */
     toNegated() {
         return new PrecisionNumber(this.#decimal.negated(), this.#decimalPlaces, this.#rounding);
     }
 
+    /**
+     * Returns a new instance with another value added.
+     */
     toPlus(value: PrecisionNumberValue) {
-        return new PrecisionNumber(this.#decimal.plus(value.toString().trim()), this.#decimalPlaces, this.#rounding);
+        return new PrecisionNumber(this.#decimal.plus(this.#valueToString(value)), this.#decimalPlaces, this.#rounding);
+    }
+
+    /**
+     * Returns a new instance raised to an exponent.
+     */
+    toPow(value: PrecisionNumberValue) {
+        return new PrecisionNumber(this.#decimal.pow(this.#valueToString(value)), this.#decimalPlaces, this.#rounding);
     }
 
+    /**
+     * Converts the current value to a JavaScript number.
+     *
+     * Use `toString`/`value` when preserving decimal precision is more important than native-number ergonomics.
+     */
+    toNumber() {
+        return this.#decimal.toNumber();
+    }
+
+    /**
+     * Converts the current value to its fixed-decimal string.
+     */
     toString() {
         return this.value;
     }
 
+    /**
+     * Formats the current value with custom precision and rounding for this call only.
+     */
     toFixed(decimalPlaces: number = this.#decimalPlaces, rounding: Decimal.Rounding = this.#rounding) {
         return this.#decimal.toFixed(decimalPlaces, rounding);
     }
 
+    /**
+     * Returns a new instance multiplied by another value.
+     */
     toTimes(value: PrecisionNumberValue) {
-        return new PrecisionNumber(this.#decimal.times(value.toString().trim()), this.#decimalPlaces, this.#rounding);
+        return new PrecisionNumber(
+            this.#decimal.times(this.#valueToString(value)),
+            this.#decimalPlaces,
+            this.#rounding,
+        );
     }
 }

package/src/crypto-hash.ts

@@ -16,7 +16,7 @@ import type {
  * ```typescript
  * import { cryptoMd5 } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoMd5('test')); // 33ed9a05a10b21f0...
+ * console.log(cryptoMd5('test')); // 098f6bcd4621d373cade4e832627b4f6
  * ```
  */
 export function cryptoMd5(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
@@ -53,7 +53,7 @@ export function cryptoMd5ToBuffer(data: BinaryLike) {
  * ```typescript
  * import { cryptoSha3224 } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3224('test')); // 0qW8FoqDcFmkpuqR9J3uT8YX...
+ * console.log(cryptoSha3224('test')); // 3797bf0afbbfca4a7bbba7602a2b552746876517a7f9b7ce2db0ae7b
  * ```
  */
 export function cryptoSha3224(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
@@ -71,7 +71,7 @@ export function cryptoSha3224(data: BinaryLike, outputEncoding: BinaryToTextEnco
  * ```typescript
  * import { cryptoSha3224ToBuffer } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3224ToBuffer('test')); // <Buffer 0q W8 Fo ...>
+ * console.log(cryptoSha3224ToBuffer('test')); // <Buffer 37 97 bf 0a ...>
  * ```
  */
 export function cryptoSha3224ToBuffer(data: BinaryLike) {
@@ -127,7 +127,7 @@ export function cryptoSha3256ToBuffer(data: BinaryLike) {
  * ```typescript
  * import { cryptoSha3384 } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3384('test')); // 1Q2wQAYaZ4o8vWX5bEB2n3Y...
+ * console.log(cryptoSha3384('test')); // e516dabb23b6e30026863543282780a3ae0dccf05551cf0295178d7f...
  * ```
  */
 export function cryptoSha3384(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
@@ -145,7 +145,7 @@ export function cryptoSha3384(data: BinaryLike, outputEncoding: BinaryToTextEnco
  * ```typescript
  * import { cryptoSha3384ToBuffer } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3384ToBuffer('test')); // <Buffer 1Q 2w QZ ...>
+ * console.log(cryptoSha3384ToBuffer('test')); // <Buffer e5 16 da bb ...>
  * ```
  */
 export function cryptoSha3384ToBuffer(data: BinaryLike) {
@@ -164,7 +164,7 @@ export function cryptoSha3384ToBuffer(data: BinaryLike) {
  * ```typescript
  * import { cryptoSha3512 } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3512('test')); // b_NQJ8FJBY9dIjm1q7...
+ * console.log(cryptoSha3512('test')); // 9ece086e9bac491fac5c1d1046ca11d737b92a2b2ebd93f005d7...
  * ```
  */
 export function cryptoSha3512(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
@@ -182,7 +182,7 @@ export function cryptoSha3512(data: BinaryLike, outputEncoding: BinaryToTextEnco
  * ```typescript
  * import { cryptoSha3512ToBuffer } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3512ToBuffer('test')); // <Buffer b_ NQ ...>
+ * console.log(cryptoSha3512ToBuffer('test')); // <Buffer 9e ce 08 6e ...>
  * ```
  */
 export function cryptoSha3512ToBuffer(data: BinaryLike) {

package/src/hash.ts

@@ -20,7 +20,7 @@ import {
  * ```typescript
  * import { sha3224 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3224('test')); // 0qW8FoqDcFmkpuqR9J3uT8YXVb3pWnLYgA4JqyprhqZ5H...
+ * console.log(sha3224('test')); // 3797bf0afbbfca4a7bbba7602a2b552746876517a7f9b7ce2db0ae7b
  * ```
  */
 export function sha3224(data: string | Uint8Array) {
@@ -56,7 +56,7 @@ export function sha3256(data: string | Uint8Array) {
  * ```typescript
  * import { sha3384 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3384('test')); // 1Q2wQAYaZ4o8vWX5bEB2n3Y...
+ * console.log(sha3384('test')); // e516dabb23b6e30026863543282780a3ae0dccf05551cf0295178d7f...
  * ```
  */
 export function sha3384(data: string | Uint8Array) {
@@ -74,7 +74,7 @@ export function sha3384(data: string | Uint8Array) {
  * ```typescript
  * import { sha3512 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3512('test')); // b_NQJ8FJBY9dIjm1q7...
+ * console.log(sha3512('test')); // 9ece086e9bac491fac5c1d1046ca11d737b92a2b2ebd93f005d7...
  * ```
  */
 export function sha3512(data: string | Uint8Array) {

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

@@ -9,7 +9,7 @@ import type { LRUCache } from 'lru-cache';
  *
  * @returns {(keyFn: (...args: P) => string) => Readonly<{
  *   getItem, getItemTtl, hasItem, removeItem, resolveKey, setItem
- * }>} A keyed store factory that takes a key resolution function
+ * }>} A factory that accepts a key resolver and returns a frozen keyed cache facade
  *
  * @example
  * ```typescript
@@ -18,8 +18,8 @@ import type { LRUCache } from 'lru-cache';
  *
  * const lru = new LRUCache({ max: 100 });
  * const keyedStore = createLruKeyedStore(lru)((userId: string) => `user:${userId}`);
- * await keyedStore.setItem({ name: 'Alice' }, 'user-123');
- * const user = await keyedStore.getItem('user-123'); // { name: 'Alice' }
+ * keyedStore.setItem({ name: 'Alice' }, 'user-123');
+ * const user = keyedStore.getItem('user-123'); // { name: 'Alice' }
  * ```
  */
 export function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any, any>) {

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

@@ -11,7 +11,7 @@ import type { RedisLikeStorage } from './types';
  *
  * @returns {(keyFn: (...args: P) => string) => Readonly<{
  *   getItem, getItemTtl, hasItem, removeItem, resolveKey, setItem, setItemWithTtl
- * }>} A keyed store factory that takes a key resolution function
+ * }>} A factory that accepts a key resolver and returns a frozen Redis keyed-store facade
  *
  * @example
  * ```typescript

package/src/string.ts

@@ -1,3 +1,6 @@
+/**
+ * Character-set presets supported by `randomString`.
+ */
 export type RandomStringMode =
   | 'alphabetic'
   | 'alphanumeric'
@@ -21,10 +24,13 @@ const CHARSETS: Record<RandomStringMode, string> = {
 };
 
 /**
- * Generates a random string of a given length using a specified character set.
+ * Generates a random string of a given length using a predefined character set.
+ *
+ * Uses `Math.random`, so this helper is suitable for display tokens, placeholders,
+ * and test data, but not for passwords, API keys, or other cryptographic secrets.
  *
- * @param {number} length - The length of the string to generate. Must be a positive integer
- * @param {RandomStringMode} [mode] - The character set to use
+ * @param {number} length - The positive integer length of the string to generate
+ * @param {RandomStringMode} [mode] - The character set to use (default: `'alphabetic'`)
  *
  * @returns {string} The generated random string
  *
@@ -34,9 +40,9 @@ const CHARSETS: Record<RandomStringMode, string> = {
  * ```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'
+ * randomString(8); // e.g. 'aZbXwTyQ'
+ * randomString(6, 'numeric'); // e.g. '402398'
+ * randomString(10, 'alphanumeric'); // e.g. 'a9Z4pQ8xY2'
  * ```
  */
 export function randomString(length: number, mode: RandomStringMode = 'alphabetic') {

package/src/types/index.ts

@@ -6,13 +6,52 @@ import type {
 
 export type { FilteredKeyPath } from './filtered-key-path';
 
+/**
+ * A generic string-keyed object for utility APIs that intentionally accept any value shape.
+ */
 export type AnyRecord = Record<string, any>;
+
+/**
+ * Binary-like inputs accepted by `toBuffer` across browser and Node.js runtimes.
+ */
 export type BinaryInput = ArrayBuffer | Blob | Buffer | File | NodeBlob | NodeFile | Uint8Array;
+
+/**
+ * Boolean values represented either as booleans or common string literals.
+ */
 export type Booleanish = 'false' | 'true' | boolean;
+
+/**
+ * Accepts either a full object or a partial patch of that object.
+ */
 export type MaybePartial<T> = Partial<T> | T;
+
+/**
+ * Accepts either a mutable value or a readonly view of that value.
+ */
 export type MaybeReadonly<T> = Readonly<T> | T;
+
+/**
+ * Explicitly nullable value helper.
+ */
 export type Nullable<T> = null | T;
+
+/**
+ * Number-like value represented as a number or a numeric string.
+ */
 export type Numberish = number | string;
+
+/**
+ * A `Record` where every key is optional.
+ */
 export type PartialRecord<K extends keyof any, T> = Partial<Record<K, T>>;
+
+/**
+ * A readonly `PartialRecord`.
+ */
 export type ReadonlyPartialRecord<K extends keyof any, T> = Readonly<PartialRecord<K, T>>;
+
+/**
+ * A readonly `Record`.
+ */
 export type ReadonlyRecord<K extends keyof any, T> = Readonly<Record<K, T>>;