@rzl-zone/utils-js 3.10.0 → 3.11.0

package/dist/isPlainObject-BTPjv6zB.d.ts

@@ -1,178 +0,0 @@
-/*!
- * ====================================================
- * Rzl Utils-JS.
- * ----------------------------------------------------
- * Version: 3.10.0.
- * Author: Rizalvin Dwiky.
- * Repository: https://github.com/rzl-zone/utils-js.
- * ====================================================
- */
-import{NonPlainObject}from'@rzl-zone/ts-types-plus';
-/** ---------------------------------------------------------------------------
- * * ***Type Options for {@link getPreciseType | `getPreciseType`}.***
- * ---------------------------------------------------------------------------
- */
-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 "toLowerCase"
- * @description
- * Supported formats:
- * - `"toLowerCase"` (default) — converts all letters to lowercase.
- *   - ➔ `"result example type"`
- * - `"toDotCase"` — words separated by dots.
- *   - ➔ `"result.example.type"`
- * - `"toCamelCase"` — first word lowercase, subsequent words capitalized.
- *   - ➔ `"resultExampleType"`
- * - `"toKebabCase"` — words separated by hyphens.
- *   - ➔ `"result-example-type"`
- * - `"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 `"toLowerCase"`.
- */
-formatCase?:"toPascalCaseSpace"|"toPascalCase"|"toCamelCase"|"toKebabCase"|"toSnakeCase"|"toDotCase"|"slugify"|"toLowerCase";};
-/** ----------------------------------------------------------
- * * ***Utility-Predicate: `getPreciseType`.***
- * ----------------------------------------------------------
- * **Returns a detailed and normalized type string for the given value.**
- * @description
- * The returned string is human-readable _**toLowerCase**_ 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)`
- *    - Generator instances
- *    - Node.js `Buffer` instances
- *    - Proxy detection (returns `"Proxy"` if detected; detection is not 100% accurate)
- *    - Uses cached mapping table (`FIXES`) 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.
- * @returns {string} The normalized and formatted type string
- * @example
- * getPreciseType(123);  // ➔ "number"
- * getPreciseType(null); // ➔ "null"
- * getPreciseType(/regex/,{ formatCase: "toKebabCase" });
- * // ➔ "reg-exp"
- * getPreciseType(function* () {}, { formatCase: "toCamelCase" });
- * // ➔ "generatorFunction"
- * getPreciseType(async function () {}, { formatCase: "toPascalCaseSpace" });
- * // ➔ "Async Function"
- * getPreciseType(NaN, { formatCase: "toKebabCase" });
- * // ➔ "NaN" (SPECIAL_CASES remain)
- */
-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 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{type GetPreciseTypeOptions as G,type IsNumberOptions as I,type IsPlainObjectResult as a,isPlainObject as b,type IsHasKeysObject as c,getPreciseType as g,isNumber as i};