@rzl-zone/utils-js 3.12.0 → 3.12.1-beta.1

package/dist/isInteger-naMbJsxJ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isInteger-naMbJsxJ.js","names":[],"sources":["../src/predicates/is/isInteger.ts"],"sourcesContent":["/** ---------------------------------------------------------\n * * ***Type guard: `isInteger`.***\n * ----------------------------------------------------------\n * **Checks if a value is an integer number.**\n * - **ℹ️ Note:**\n *    - This method is based on\n *      [`Number.isInteger`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isInteger).\n * @param {*} value The value to check.\n * @returns {boolean} Returns `true` if `value` is an integer, else `false`.\n * @example\n * isInteger(3);\n * // ➔ true\n * isInteger(Number.MIN_VALUE);\n * // ➔ false\n * isInteger(NaN);\n * // ➔ false\n * isInteger(Infinity);\n * // ➔ false\n * isInteger(-Infinity);\n * // ➔ false\n * isInteger('3');\n * // ➔ false\n */\nexport function isInteger(value: unknown): value is number {\n  return typeof value === \"number\" && Number.isInteger(value);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,UAAU,OAAiC;CACzD,OAAO,OAAO,UAAU,YAAY,OAAO,UAAU,MAAM"}

package/dist/isPlainObject-BF-2-phb.d.cts

@@ -0,0 +1,339 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.1`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+
+import { IsNever, NonPlainObject } from "@rzl-zone/ts-types-plus";
+declare class PreciseType {
+  constructor(params?: GetPreciseTypeOptions);
+  /** ----------------------------------------------------------
+  * * ***Getting the internal map of type castable relationships used by {@link getPreciseType | `getPreciseType`}.***
+  * ----------------------------------------------------------
+  *
+  * - **Description:**
+  *    - Returns an internal static mapping table that defines which primitive or structural types
+  *      can be cast or interpreted as another related type within the internal logic of
+  *      {@link getPreciseType | `getPreciseType`}.
+  *
+  * - **⚠️ Internal:**
+  *    - This is an internal helper of {@link getPreciseType | `getPreciseType`}.
+  *    - Do not modify or rely on this table directly — it is **readonly** and may change without notice.
+  *
+  * @readonly
+  */
+  static get castableTable(): typeof PreciseType.FIXES_CASTABLE_TABLE;
+  /** ----------------------------------------------------------
+  * * ***Retrieves the internal list of special type cases handled by {@link getPreciseType | `getPreciseType`}.***
+  * ----------------------------------------------------------
+  *
+  * - **Description:**
+  *    - Returns an internal readonly list of specific type identifiers that require
+  *      *custom handling* during type detection.
+  *    - These are **exceptional values** or **edge cases** that don’t follow the normal
+  *      JavaScript type resolution flow.
+  *
+  * - **Example Values:**
+  *    - `"Infinity"`, `"-Infinity"`, `"NaN"`, `"undefined"`, etc.
+  *
+  * - **⚠️ Internal:**
+  *    - Used internally by {@link getPreciseType | `getPreciseType`}.
+  *    - This property is **readonly** and should not be modified directly.
+  *
+  * @readonly
+  */
+  static get specialType(): typeof this.SPECIAL_TYPE;
+  /** ----------------------------------------------------------
+  * * ***Retrieves the internal mapping of JavaScript built-in and environment-specific
+  * type identifiers to their canonical PascalCase names.***
+  * ----------------------------------------------------------
+  *
+  * - **Description:**
+  *    - Provides a mapping table where **keys** represent normalized raw type names
+  *      (as obtained from `Object.prototype.toString.call(value)` or environment checks),
+  *      and **values** represent their **canonical PascalCase equivalents**.
+  *    - This table ensures consistent, human-readable type strings across different environments.
+  *
+  * - **Example Mapping:**
+  *    ```ts
+  *      {
+  *        "[object Map]": "Map",
+  *        "[object WeakMap]": "WeakMap",
+  *        "[object AsyncFunction]": "AsyncFunction",
+  *        "[object GeneratorFunction]": "GeneratorFunction",
+  *        "[object BigInt]": "BigInt",
+  *      }
+  *    ```
+  *
+  * - **⚠️ Internal:**
+  *    - Used internally by {@link getPreciseType | `getPreciseType`}.
+  *    - This property is **readonly** and should not be modified directly.
+  *
+  * @readonly
+  */
+  static get fixesRaw(): typeof this.FIXES_RAW;
+  /** ----------------------------------------------------------
+  * * ***Retrieves the internal list of common acronyms that should remain fully uppercase during string formatting.***
+  * ----------------------------------------------------------
+  *
+  * - **Description:**
+  *    - This list defines acronyms (e.g., `"URL"`, `"HTTP"`, `"HTML"`, `"SVG"`, `"XML"`, `"DOM"`)
+  *      that will be **preserved in uppercase** when applying case transformations through
+  *      {@link getPreciseType | `getPreciseType`} or any formatting utility using it.
+  *    - Ensures consistency in output for technical identifiers that are conventionally capitalized.
+  *
+  * - **Example:**
+  *    ```ts
+  *      ["URL", "HTTP", "HTML", "SVG", "XML", "DOM"]
+  *    ```
+  *
+  * - **⚠️ Internal:**
+  *     - Used internally by {@link getPreciseType | `getPreciseType`}.
+  *     - This property is **readonly** and not intended for modification.
+  *
+  * @readonly
+  */
+  static get acronymsList(): typeof this.ACRONYMS;
+}
+/** ---------------------------------------------------------------------------
+* * ***Options for controlling how {@link getPreciseType | `getPreciseType`} formats and normalizes detected types.***
+* ---------------------------------------------------------------------------
+* These options customize the string transformation behavior and acronym handling
+* when converting JavaScript type names to human-readable strings.
+*/
+type GetPreciseTypeOptions = {
+  /** -------------------------------------------------------
+  * * ***Specifies the format in which the returned string type should be transformed.***
+  * -------------------------------------------------------
+  * **ℹ️ For special string literals in `SPECIAL_CASES` (`"-Infinity" | "Infinity" | "NaN"`), which will remain unchanged.**
+  * @default "toKebabCase"
+  * @description
+  * Supported formats:
+  * - `"toKebabCase"` (default) — words separated by hyphens.
+  *   - ➔ `"result-example-type"`
+  * - `"toLowerCase"` - converts all letters to lowercase.
+  *   - ➔ `"result example type"`
+  * - `"toDotCase"` — words separated by dots.
+  *   - ➔ `"result.example.type"`
+  * - `"toCamelCase"` — first word lowercase, subsequent words capitalized.
+  *   - ➔ `"resultExampleType"`
+  * - `"toSnakeCase"` — words separated by underscores.
+  *   - ➔ `"result_example_type"`
+  * - `"toPascalCase"` — all words capitalized, no spaces.
+  *   - ➔ `"ResultExampleType"`
+  * - `"toPascalCaseSpace"` — all words capitalized with spaces between words.
+  *   - ➔ `"Result Example Type"`
+  * - `"slugify"` — URL-friendly slug (lowercase with hyphens).
+  *   - ➔ `"result-example-type"`
+  * @note
+  * ⚠️ If an invalid value is provided, the function will automatically fallback to the default `"toKebabCase"`.
+  */
+  formatCase?: "toPascalCaseSpace" | "toPascalCase" | "toCamelCase" | "toKebabCase" | "toSnakeCase" | "toDotCase" | "slugify" | "toLowerCase";
+  /** -------------------------------------------------------
+  * * ***Control uppercase preservation of recognized acronyms during formatting.***
+  * -------------------------------------------------------
+  * When enabled (`true`), common technical acronyms (e.g., `"URL"`, `"HTTP"`, `"HTML"`, `"SVG"`, `"XML"`, `"DOM"`)
+  * are preserved in their original uppercase form instead of being lowercased or altered by case-formatting utilities.
+  *
+  *
+  * - **When `false` (default):**
+  *    - Acronyms are treated as normal words and formatted according to the selected `formatCase`.
+  *    - Example:
+  *      - `HTMLDivElement` ➔ `"html-div-element"` (with `"toKebabCase"`)
+  *      - `DOMParser` ➔ `"dom-parser"`
+  * - **When `true`:**
+  *    - Acronyms remain uppercase.
+  *    - Example:
+  *      - `HTMLDivElement` ➔ `"HTML-div-element"` (with `"toKebabCase"`)
+  *      - `DOMParser` ➔ `"DOM-parser"`
+  *
+  * @default false
+  * @description
+  * The list of recognized acronyms is defined in {@link AcronymsList | **`AcronymsList`**},
+  * including entries like `"URL"`, `"HTTP"`, `"HTML"`, `"SVG"`, `"XML"`, `"DOM"`, and others.
+  *
+  * ⚠️ This option affects **formatting output only**, not the underlying type detection, acronym preservation is applied **after** detecting and formatting the base type name.
+  */
+  useAcronyms?: boolean;
+};
+/** ---------------------------------------------------------------------------
+* * ***Type alias for the list of common acronyms preserved in uppercase.***
+* ---------------------------------------------------------------------------
+*
+* Use this type to reference the full set of recognized acronyms
+* used internally by the {@link getPreciseType | **`getPreciseType`**} function for formatting purposes.
+*/
+type AcronymsList = (typeof PreciseType)["acronymsList"];
+/** ----------------------------------------------------------
+* * ***Utility-Predicate: `getPreciseType`.***
+* ----------------------------------------------------------
+* **Returns a detailed and normalized type string for the given value.**
+* @description
+* The returned string is human-readable ***toKebabCase*** with spaces ***(by default)*** or formatted according to the `options.formatCase` setting.
+* - **Handles:**
+*    - Primitives (`string`, `number`, `boolean`, `null`, `undefined`, `symbol`, `bigint`)
+*    - Built-in objects (`Array`, `Map`, `Set`, `Error subclasses`, `Typed Arrays`, `etc`)
+*    - Objects created with `Object.create(null)`
+*    - Objects wrapper (`new String`, `new Number`, `new Boolean`)
+*    - DOM Node type (may not be fully accurate outside the browser environment)
+*    - Generator instances
+*    - Node.js `Buffer` instances
+*    - Proxy detection (returns `"Proxy"` if detected; detection ***is not 100% accurate***)
+*    - Uses cached mapping table (`FIXES_CASTABLE_TABLE`) for known types to provide consistent naming
+*    - Falls back to constructor name or `Object.prototype.toString` tag
+* @param {*} value - The value to detect the precise type of
+* @param {GetPreciseTypeOptions} [options] - Optional configuration
+* @param {GetPreciseTypeOptions["formatCase"]} [options.formatCase="toLowerCase"]
+*   Specifies how the returned type string should be formatted.
+*      - ⚠️ Special string literals in `SPECIAL_CASES`
+*        (`"-Infinity" | "Infinity" | "NaN"`) will remain
+*        unchanged even if a different `formatCase` is applied.
+* @param {boolean} [options.useAcronyms=false]
+*   Control uppercase preservation of recognized acronyms during formatting.
+*      - When `true`, recognized acronyms such as `"URL"`, `"HTTP"`, `"HTML"`, `"SVG"`, `"XML"`, and `"DOM"`
+*        are preserved in uppercase instead of being lowercased or otherwise transformed.
+*      - When `false` (default), acronyms are formatted like regular words according to `formatCase`.
+*      - ⚠️ This option affects **formatting output only**, not type detection.
+*
+* @returns {string} The normalized and formatted type string
+* @example
+* getPreciseType(123);     // ➔ "number"
+* getPreciseType(null);    // ➔ "null"
+* getPreciseType(/regex/); // ➔ "reg-exp"
+* getPreciseType(/regex/, { formatCase: "toPascalCase" });
+* // ➔ "RegExp"
+* getPreciseType(function* () {}, { formatCase: "toCamelCase" });
+* // ➔ "generatorFunction"
+* getPreciseType(async function () {}, { formatCase: "toPascalCaseSpace" });
+* // ➔ "Async Function"
+*
+* // (SPECIAL_CASES remain)
+* getPreciseType(NaN, { formatCase: "toLowerCase" });
+* // ➔ "NaN"
+* getPreciseType(Infinity, { formatCase: "toLowerCase" });
+* // ➔ "Infinity"
+* getPreciseType(-Infinity, { formatCase: "toLowerCase" });
+* // ➔ "-Infinity"
+*
+* // Acronym usage examples:
+* getPreciseType(new URL("https://example.com"));
+* // ➔ "url"
+* getPreciseType(new URL("https://example.com"), { useAcronyms: true });
+* // ➔ "URL"
+*
+* getPreciseType(new URLSearchParams, { formatCase: "toPascalCase" });
+* // ➔ "UrlSearchParams"
+* getPreciseType(new URLSearchParams, { formatCase: "toPascalCase", useAcronyms: true });
+* // ➔ "URLSearchParams"
+*/
+declare const getPreciseType: (value: unknown, options?: GetPreciseTypeOptions) => string;
+type IsNumberOptions = {
+  /** If set to `true`, `NaN` will be considered a valid number, defaultValue: `false`.
+  *
+  * @default false
+  */
+  includeNaN?: boolean;
+};
+/** ---------------------------------------------------------
+* * ***Type guard: `isNumber`.***
+* ----------------------------------------------------------
+* **Checks if a value is of type **`number`**.**
+* - **Behavior:**
+*    - Uses `typeof value === "number"`.
+*    - By default, excludes **`NaN`**.
+*    - If `options.includeNaN` is `true`, then **`NaN`** is also considered valid.
+*    - Still considers `Infinity` and `-Infinity` as **numbers** (consistent with JavaScript).
+* - **ℹ️ Note:**
+*    - To exclude `Infinity` and `-Infinity`, use **{@link isFinite | `isFinite`}** instead.
+* @param {*} value - The value to check.
+* @param {IsNumberOptions} [options] - Optional settings.
+* @param {boolean} [options.includeNaN=false]  If `true`, `NaN` will be considered a valid number, defaults to `false`, which excludes `NaN`.
+* @returns {boolean} Returns `true` if the value is a number (and depending on `includeNaN`, `NaN` is included or excluded).
+* @example
+* isNumber(42);
+* // ➔ true
+* isNumber(Infinity);
+* // ➔ true
+* isNumber(-Infinity);
+* // ➔ true
+* isNumber(NaN);
+* // ➔ false (default)
+* isNumber(NaN, { includeNaN: true });
+* // ➔ true
+* isNumber("42");
+* // ➔ false
+*/
+declare const isNumber: (value: unknown, options?: IsNumberOptions) => value is number;
+type ArrayFallback<T> = IsNever<Extract<T, unknown[] | readonly unknown[]>> extends true ? T & unknown[] : Extract<T, unknown[] | readonly unknown[]>;
+type IsHasKeysObject<T> = keyof T extends never ? false : true;
+/** ----------------------------------------------------------
+* * ***Utility type: `IsPlainObjectResult`.***
+* ----------------------------------------------------------
+* **Represents the inferred type after asserting a value is a **plain object**.**
+* - **Behavior:**
+*    - If `T` is `unknown`, the resulting type is `Record<PropertyKey, unknown> & T`.
+*    - If `T` is an object:
+*        - If it is a non-plain object (class instance, built-in object, etc.), the result is `never`.
+*        - If it has no keys (`IsHasKeysObject<T>` checked by **{@link IsHasKeysObject|`IsHasKeysObject`}** is false), the result is `Record<PropertyKey, unknown> & T`.
+*        - Otherwise, the result is `T` itself.
+*    - For any other types, the result is `never`.
+* @template T - The input type to be asserted as a plain object.
+* @example
+* ```ts
+* type A = IsPlainObjectResult<unknown>;
+* // ➔ Record<PropertyKey, unknown> & unknown
+* type B = IsPlainObjectResult<{}>;
+* // ➔ Record<PropertyKey, unknown> & {}
+* type C = IsPlainObjectResult<{ foo: string }>;
+* // ➔ { foo: string }
+* type D = IsPlainObjectResult<Date>;
+* // ➔ never
+* ```
+*/
+type IsPlainObjectResult<T> = unknown extends T ? Record<PropertyKey, unknown> & T : T extends object ? T extends NonPlainObject ? never : IsHasKeysObject<T> extends false ? Record<PropertyKey, unknown> & T : T : Extract<T, Record<PropertyKey, unknown>>;
+/** ----------------------------------------------------------
+* * ***Type guard: `isPlainObject`.***
+* ----------------------------------------------------------
+* **Checks if a value is a **plain-object**.**
+* - **A plain object is:**
+*    - Created by the `Object` constructor, or
+*    - Has a `[[Prototype]]` of `null` (e.g. `Object.create(null)`).
+* - **✅ Returns `true` for:**
+*    - Empty object literals: `{}`
+*    - Objects with null prototype: `Object.create(null)`
+* - **❌ Returns `false` for:**
+*    - Arrays (`[]`, `new Array()`)
+*    - Functions (regular, arrow, or class constructors)
+*    - Built-in objects: `Date`, `RegExp`, `Error`, `Map`, `Set`, `WeakMap`, `WeakSet`
+*    - Boxed primitives: `new String()`, `new Number()`, `new Boolean()`
+*    - `null` or `undefined`
+*    - Symbols
+*    - Class instances
+* @template T - The type of the value being checked.
+* @param {*} value - The value to check.
+* @returns {boolean} Return `true` if `value` is a `plain-object`, otherwise `false`.
+* @example
+* isPlainObject({});
+* // ➔ true
+* isPlainObject(Object.create(null));
+* // ➔ true
+* isPlainObject(null);
+* // ➔ false
+* isPlainObject(() => {});
+* // ➔ false
+* isPlainObject([1, 2, 3]);
+* // ➔ false
+* isPlainObject(new Date());
+* // ➔ false
+* isPlainObject(new MyClass());
+* // ➔ false
+* isPlainObject(new String("x"));
+* // ➔ false
+*/
+declare function isPlainObject<T>(value: T): value is IsPlainObjectResult<T>;
+declare function isPlainObject<T>(value: T): value is NonNullable<Extract<T, Record<PropertyKey, unknown>>>;
+export { IsNumberOptions as a, GetPreciseTypeOptions as c, ArrayFallback as i, getPreciseType as l, isPlainObject as n, isNumber as o, IsHasKeysObject as r, AcronymsList as s, IsPlainObjectResult as t };