@rzl-zone/utils-js 2.1.0 → 3.0.1-beta.0

package/dist/NumberRangeUnion-DC-C3_Kq.d.ts

@@ -0,0 +1,26 @@
+type Enumerate<N extends number,Acc extends number[]=[]>=Acc["length"] extends N?Acc[number]:Enumerate<N,[...Acc,Acc["length"]]>;
+/** --------------------------------------------------
+* * ***Generate a union type of numbers from `From` to `To` using enumeration.***
+* --------------------------------------------------
+*
+* @template From - Starting number of the range (inclusive).
+* @template To - Ending number of the range (inclusive).
+*
+* @description
+* Produces a **numeric union type** from `From` to `To` (inclusive),
+* using a simpler approach based on `Enumerate<N>` helper type.
+*
+* - ✅ Straightforward & easy to reason about.
+* - ⚠️ Still limited by TypeScript recursion depth (safe up to `999`).
+* - ⚙️ Best used for **smaller ranges** or when readability matters.
+*
+* @example
+* ```ts
+* type RangeX = NumberRangeUnion<3, 6>;
+* //    ^? 3 | 4 | 5 | 6
+*
+* type RangeY = NumberRangeUnion<0, 2>;
+* //    ^? 0 | 1 | 2
+* ```
+*/
+type NumberRangeUnion<From extends number,To extends number>=From extends To?From:Exclude<Enumerate<To>,Enumerate<From>>extends never?never:Exclude<Enumerate<To>,Enumerate<From>>|To;export type{NumberRangeUnion as N};

package/dist/any-BmdI8UbK.d.ts

@@ -0,0 +1,67 @@
+import{I as If}from'./if-CvT4R7Kh.js';
+/** -------------------------------------------------------
+* * ***IsAny.***
+* -------------------------------------------------------
+* A type-level utility that checks whether a type is ***`any`***.
+* - Returns `true` if `T` is `any`.
+* - Returns `false` otherwise.
+*
+* @template T - The type to evaluate.
+* @example
+* ```ts
+* type A = IsAny<any>;     // ➔ true
+* type B = IsAny<string>;  // ➔ false
+* type C = IsAny<unknown>; // ➔ false
+* type D = IsAny<never>;   // ➔ false
+* ```
+*/
+type IsAny<T>=0 extends 1 & T?true:false;
+/** -------------------------------------------------------
+* * ***IfAny.***
+* -------------------------------------------------------
+*
+* A type-level conditional utility that returns one type if ***`T` is `any`***,
+* and another type otherwise.
+* - Defaults to `true` when `T` is `any`.
+* - Defaults to `false` otherwise.
+*
+* @template T - The type to check.
+* @template IfTrue - The type to return if `T` is `any`. *(default: `true`)*
+* @template IfFalse - The type to return if `T` is not `any`. *(default: `false`)*
+*
+* @example
+* ```ts
+* type A = IfAny<any, string, number>;
+* // ➔ string
+* type B = IfAny<string, string, number>;
+* // ➔ number
+* ```
+*/
+type IfAny<T,IfTrue=true,IfFalse=false>=If<IsAny<T>,IfTrue,IfFalse>;
+/** Configuration options for a type-level utility `AnifyProperties`. */
+type AnifyPropertiesOptions={
+/** If `makeOptional: true`, all properties become optional, otherwise, all properties are required and typed as `any`, defaultValue: `false`.
+*
+* @default false
+*/
+makeOptional:boolean;};
+/** -------------------------------------------------------
+* * ***AnifyProperties.***
+* -------------------------------------------------------
+*
+* A type-level utility that transforms all properties of an object into ***`any`***.
+* - If `makeOptional: true`, all properties become optional.
+* - Otherwise, all properties are required and typed as `any`.
+*
+* @template T - The object type to transform.
+* @template Options - Configuration options. Defaults to `{ makeOptional: false }`.
+* @example
+* ```ts
+* type A = AnifyProperties<{a: string; b: number}>;
+* // ➔ { a: any; b: any }
+*
+* type B = AnifyProperties<{a: string; b: number}, { makeOptional: true }>;
+* // ➔ { a?: any; b?: any }
+* ```
+*/
+type AnifyProperties<T extends object,Options extends AnifyPropertiesOptions={makeOptional:false;}>={[K in keyof T]:any;}extends infer Result?If<Options["makeOptional"],Partial<Result>,Result>:never;export type{AnifyProperties as A,IsAny as I,AnifyPropertiesOptions as a,IfAny as b};

package/dist/array-CIZRbqTF.d.ts

@@ -0,0 +1,223 @@
+import{I as If}from'./if-CvT4R7Kh.js';import{I as IsNever}from'./never-BfayMBF9.js';
+/** -------------------------------------------------------
+* * ***Arrayable.***
+* -------------------------------------------------------
+* Represents a type that can be either:
+* - a single value of type `T`, or
+* - an array of values of type `T`.
+*
+* Useful when a function or API accepts **either one item or multiple items**.
+*
+* @template T - The element type.
+*
+* @example
+* ```ts
+* function toArray<T>(input: Arrayable<T>): T[] {
+*   return Array.isArray(input) ? input : [input];
+* }
+*
+* type A = Arrayable<string>;
+* // ➔ string | string[]
+*
+* const a: A = "foo";
+* const b: A = ["foo", "bar"];
+* ```
+*/
+type Arrayable<T>=T|Array<T>;
+/** -------------------------------------------------------
+* * ***MutableArray.***
+* -------------------------------------------------------
+* Recursively creates a **mutable version** of a readonly array, tuple, or object type.
+*
+* By default, TypeScript infers tuple/array literals as `readonly` (especially with `as const`).
+* This utility removes the `readonly` modifier from all elements recursively,
+* turning a readonly tuple, array, or object into a mutable one.
+*
+* Optionally, if `Widen` is `true`, literal types (`1`, `'foo'`, `true`) are widened to
+* their primitive equivalents (`number`, `string`, `boolean`) for easier assignment.
+*
+* @template T - The readonly array, tuple, or object type to make mutable.
+* @template Widen - Whether to widen literal primitive types to their base types (default: `false`).
+*
+* @example
+* ```ts
+* type A = readonly [1, 2, 3];
+* type B = MutableArray<A>;
+* // ➔ [1, 2, 3]
+*
+* const x: A = [1, 2, 3] as const;
+* // x[0] = 9; // ❌ Error: read-only
+*
+* const y: MutableArray<B,true> = [1, 2, 3];
+* y[0] = 9; // ✅ Allowed
+*
+* // Recursive example with objects
+* type Obj = readonly [{ a: 1, b: readonly [2] }];
+* type MutableObj = MutableArray<Obj, true>;
+* // ➔ [{ a: number; b: [number]; }]
+* ```
+*/
+type MutableArray<T,Widen extends boolean=false>=T extends(...args:any)=>any?T:T extends readonly any[]?{-readonly [K in keyof T]:MutableArray<T[K],Widen>;}:T extends object?{-readonly [K in keyof T]:MutableArray<T[K],Widen>;}:Widen extends true?T extends number?number:T extends string?string:T extends boolean?boolean:T extends bigint?bigint:T extends symbol?symbol:T:T;
+/** --------------------------------------------------
+* * ***GetArrayElementType.***
+* --------------------------------------------------
+* Gets the element type from a readonly array or tuple.
+*
+* ✅ Useful when working with `as const` arrays to extract the union of literal types.
+*
+* @template T - A readonly array or tuple type.
+*
+* @example
+* ```ts
+* const roles = ['admin', 'user'] as const;
+* type Role = GetArrayElementType<typeof roles>;
+* // ➔ "admin" | "user"
+* ```
+*/
+type GetArrayElementType<T extends readonly any[]>=T extends readonly(infer U)[]?U:never;
+/** -------------------------------------------------------
+* * ***EmptyArray.***
+* -------------------------------------------------------
+* A type-level utility that returns `T` if it is an ***empty array***,
+* otherwise returns `never`.
+*
+* @template T - The array type to check.
+* @example
+* ```ts
+* type A = EmptyArray<[]>;
+* // ➔ []
+* type B = EmptyArray<[1]>;
+* // ➔ never
+* type C = EmptyArray<string[]>;
+* // ➔ string[]
+* type D = EmptyArray<number[]>;
+* // ➔ number[]
+* type E = EmptyArray<readonly []>;
+* // ➔ readonly []
+* ```
+*/
+type EmptyArray<T extends readonly unknown[]>=T extends readonly [ unknown,...unknown[]]?never:T;
+/** -------------------------------------------------------
+* * ***NonEmptyArray.***
+* -------------------------------------------------------
+* A type-level utility that returns `T` if it is a ***non-empty array***,
+* otherwise returns `never`.
+*
+* @template T - The array type to check.
+* @example
+* ```ts
+* type A = NonEmptyArray<[]>;
+* // ➔ never
+* type B = NonEmptyArray<[1]>;
+* // ➔ [1]
+* type C = NonEmptyArray<string[]>;
+* // ➔ never
+* type D = NonEmptyArray<number[]>;
+* // ➔ never
+* type E = NonEmptyArray<readonly []>;
+* // ➔ never
+* ```
+*/
+type NonEmptyArray<T extends readonly unknown[]>=If<IsNever<EmptyArray<T>>,T,never>;
+/** -------------------------------------------------------
+* * ***IsEmptyArray.***
+* -------------------------------------------------------
+* A type-level utility that evaluates to `true` if `T` is an ***empty array.***
+* (or can be empty per this definition), otherwise `false`.
+*
+* @template T - The array type to check.
+* @example
+* ```ts
+* type A = IsEmptyArray<[]>;
+* // ➔ true
+* type B = IsEmptyArray<[1]>;
+* // ➔ false
+* type C = IsEmptyArray<string[]>;
+* // ➔ true
+* type D = IsEmptyArray<number[]>;
+* // ➔ true
+* type E = IsEmptyArray<readonly []>;
+* // ➔ true
+* ```
+*/
+type IsEmptyArray<T extends readonly unknown[]>=If<IsNever<EmptyArray<T>>,false,true>;
+/** -------------------------------------------------------
+* * ***IsNonEmptyArray.***
+* -------------------------------------------------------
+* A type-level utility that evaluates to `true` if `T` is a ***non-empty array.***
+* (strictly a non-empty tuple), otherwise `false`.
+*
+* @template T - The array type to check.
+* @example
+* ```ts
+* type A = IsNonEmptyArray<[]>;
+* // ➔ false
+* type B = IsNonEmptyArray<[1]>;
+* // ➔ true
+* type C = IsNonEmptyArray<string[]>;
+* // ➔ false
+* type D = IsNonEmptyArray<number[]>;
+* // ➔ false
+* type E = IsNonEmptyArray<readonly []>;
+* // ➔ false
+* ```
+*/
+type IsNonEmptyArray<T extends readonly unknown[]>=If<IsNever<EmptyArray<T>>,true,false>;
+/** -------------------------------------------------------
+* * ***IfEmptyArray.***
+* -------------------------------------------------------
+* Returns the second argument if `T` is an ***empty array*** (per this utility),
+* otherwise returns the third argument.
+* - Defaults: `IfTrue = true`, `IfFalse = false`.
+*
+* @template T - The array type to check.
+* @template IfTrue - Returned type if `T` is empty by this definition.
+* @template IfFalse - Returned type if `T` is not empty by this definition.
+* @example
+* ```ts
+* type A = IfEmptyArray<[]>;
+* // ➔ true
+* type B = IfEmptyArray<[1]>;
+* // ➔ false
+* type C = IfEmptyArray<string[]>;
+* // ➔ true
+* type D = IfEmptyArray<readonly []>;
+* // ➔ true
+* type E = IfEmptyArray<[], "yes", "no">;
+* // ➔ "yes"
+* type F = IfEmptyArray<[1], "yes", "no">;
+* // ➔ "no"
+* type G = IfEmptyArray<string[], "yes", "no">;
+* // ➔ "yes"
+* ```
+*/
+type IfEmptyArray<T extends readonly unknown[],IfTrue=true,IfFalse=false>=If<IsEmptyArray<T>,IfTrue,IfFalse>;
+/** -------------------------------------------------------
+* * ***IfNonEmptyArray.***
+* -------------------------------------------------------
+* Returns the second argument if `T` is a ***non-empty array*** (strict tuple),
+* otherwise returns the third argument.
+* - Defaults: `IfTrue = true`, `IfFalse = false`.
+*
+* @template T - The array type to check.
+* @template IfTrue - Returned type if `T` is non-empty by this definition.
+* @template IfFalse - Returned type if `T` is not non-empty by this definition.
+* @example
+* ```ts
+* type A = IfNonEmptyArray<[]>;
+* // ➔ false
+* type B = IfNonEmptyArray<[1]>;
+* // ➔ true
+* type C = IfNonEmptyArray<string[]>;
+* // ➔ false
+* type D = IfNonEmptyArray<readonly []>;
+* // ➔ false
+* type E = IfNonEmptyArray<[1], "yes", "no">;
+* // ➔ "yes"
+* type F = IfNonEmptyArray<[], "yes", "no">;
+* // ➔ "no"
+* type G = IfNonEmptyArray<string[], "yes", "no">;
+* // ➔ "no"
+* ```
+*/
+type IfNonEmptyArray<T extends readonly unknown[],IfTrue=true,IfFalse=false>=If<IsNonEmptyArray<T>,IfTrue,IfFalse>;export type{Arrayable as A,EmptyArray as E,GetArrayElementType as G,IsEmptyArray as I,MutableArray as M,NonEmptyArray as N,IfEmptyArray as a,IfNonEmptyArray as b,IsNonEmptyArray as c};

package/dist/arrays-normalize-recursive-CnjYJ9xg.d.ts

@@ -0,0 +1,72 @@
+/** -------------------------------------------------------
+* * ***FixNeverArrayRecursive.***
+* -------------------------------------------------------
+* A type-level utility that **recursively transforms arrays of type `never[]` into empty arrays**.
+* - Preserves `readonly` modifiers.
+* - Applies recursively for nested arrays.
+* - Leaves other types unchanged.
+*
+* @template T - The input type to recursively fix.
+* @example
+* ```ts
+* type A = FixNeverArrayRecursive<never[]>;
+* // ➔ []
+* type B = FixNeverArrayRecursive<readonly never[]>;
+* // ➔ readonly []
+* type C = FixNeverArrayRecursive<string[]>;
+* // ➔ string[]
+* type D = FixNeverArrayRecursive<(never | string)[]>;
+* // ➔ (never | string)[]
+* type E = FixNeverArrayRecursive<(never[])[]>;
+* // ➔ [][]
+* ```
+*/
+type FixNeverArrayRecursive<T>=T extends readonly never[]?T extends never[]?[]:readonly []:T extends(infer U)[]?FixNeverArrayRecursive<U>[]:T extends readonly(infer U)[]?readonly FixNeverArrayRecursive<U>[]:T;
+/** -------------------------------------------------------
+* * ***NormalizeEmptyArraysRecursive.***
+* -------------------------------------------------------
+* A type-level utility that **recursively normalizes empty array types** by converting arrays whose element type is `never`, `null`, or `undefined` into empty tuple types (`[]`).
+* - Preserves `readonly` modifiers.
+* - Recurses into nested arrays.
+* - Leaves other array types unchanged.
+*
+* @template T - The input type to normalize.
+* @example
+* ```ts
+* type A = NormalizeEmptyArraysRecursive<never[]>;
+* // ➔ []
+* type B = NormalizeEmptyArraysRecursive<readonly never[]>;
+* // ➔ readonly []
+* type C = NormalizeEmptyArraysRecursive<null[]>;
+* // ➔ []
+* type D = NormalizeEmptyArraysRecursive<(null[] | string[])[]>;
+* // ➔ ([] | string[])[]
+* type E = NormalizeEmptyArraysRecursive<string[]>;
+* // ➔ string[]
+* ```
+*/
+type NormalizeEmptyArraysRecursive<T>=T extends readonly(infer U)[]?U extends never|null|undefined?T extends readonly unknown[]?T extends(infer E)[]?[]:readonly []:never:T extends(infer E)[]?NormalizeEmptyArraysRecursive<U>[]:readonly NormalizeEmptyArraysRecursive<U>[]:T;
+/** -------------------------------------------------------
+* * ***RemoveEmptyArrayElements.***
+* -------------------------------------------------------
+* A type-level utility that **recursively removes empty array elements (`[]`) from a tuple type**.
+* - If `T` is a tuple, checks the first element:
+*    - If `Head` is an empty array type (`[]`), it is removed.
+*    - Otherwise, `Head` is preserved.
+* - Repeats recursively on the rest of the tuple.
+* - Leaves non-tuple types unchanged.
+*
+* @template T - The tuple type to process.
+* @example
+* ```ts
+* type A = RemoveEmptyArrayElements<[[], 1, [], 2]>;
+* // ➔ [1, 2]
+* type B = RemoveEmptyArrayElements<[]>;
+* // ➔ []
+* type C = RemoveEmptyArrayElements<[[], [], []]>;
+* // ➔ []
+* type D = RemoveEmptyArrayElements<[1, 2, 3]>;
+* // ➔ [1, 2, 3]
+* ```
+*/
+type RemoveEmptyArrayElements<T>=T extends [infer Head,...infer Tail]?Head extends []?RemoveEmptyArrayElements<Tail>:[Head,...RemoveEmptyArrayElements<Tail>]:T extends []?[]:T;export type{FixNeverArrayRecursive as F,NormalizeEmptyArraysRecursive as N,RemoveEmptyArrayElements as R};

package/dist/assertions/index.cjs

@@ -0,0 +1 @@
+'use strict';var chunkI4AVNHPA_cjs=require('../chunk-I4AVNHPA.cjs'),chunk62HX5Z45_cjs=require('../chunk-62HX5Z45.cjs'),chunkBVPMMWDL_cjs=require('../chunk-BVPMMWDL.cjs');require('../chunk-7YWAQOA4.cjs');var chunkCN53M4QZ_cjs=require('../chunk-CN53M4QZ.cjs');Object.defineProperty(exports,"assertIsBigInt",{enumerable:true,get:function(){return chunkI4AVNHPA_cjs.a}});Object.defineProperty(exports,"assertIsNumber",{enumerable:true,get:function(){return chunkI4AVNHPA_cjs.b}});Object.defineProperty(exports,"assertIsArray",{enumerable:true,get:function(){return chunk62HX5Z45_cjs.a}});Object.defineProperty(exports,"assertIsString",{enumerable:true,get:function(){return chunkBVPMMWDL_cjs.a}});Object.defineProperty(exports,"assertIsBoolean",{enumerable:true,get:function(){return chunkCN53M4QZ_cjs.G}});Object.defineProperty(exports,"assertIsPlainObject",{enumerable:true,get:function(){return chunkCN53M4QZ_cjs.m}});