@ts-utilities/core 1.0.0 → 1.0.2

package/dist/index-B2qsrrxx.d.cts

@@ -0,0 +1,610 @@
+//#region src/types/utilities.d.ts
+/**
+ * Extracts the keys of an object type as a union type.
+ *
+ * @template T - The object type to extract keys from
+ * @returns A union of all keys in the object type
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; age: number };
+ * type UserKeys = Keys<User>; // 'name' | 'age'
+ * ```
+ */
+type Keys<T extends object> = keyof T;
+/**
+ * Extracts the values of an object type as a union type.
+ *
+ * @template T - The object type to extract values from
+ * @returns A union of all values in the object type
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; age: number };
+ * type UserValues = Values<User>; // string | number
+ * ```
+ */
+type Values<T extends object> = T[keyof T];
+/**
+ * Makes all properties of an object type optional recursively.
+ *
+ * This type traverses through nested objects and arrays, making all properties optional.
+ * Functions and primitives are left unchanged.
+ *
+ * @template T - The type to make deeply partial
+ * @returns A type with all properties optional recursively
+ *
+ * @example
+ * ```ts
+ * type Config = {
+ *   server: { host: string; port: number };
+ *   features: string[];
+ * };
+ *
+ * type PartialConfig = DeepPartial<Config>;
+ * // {
+ * //   server?: { host?: string; port?: number };
+ * //   features?: string[];
+ * // }
+ * ```
+ */
+type DeepPartial<T> = T extends Function ? T : T extends Array<infer U> ? Array<DeepPartial<U>> : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
+/**
+ * Makes only specified properties of an object type optional.
+ *
+ * @template T - The base object type
+ * @template K - The keys to make optional
+ * @returns An object type with specified properties optional
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; age: number; email: string };
+ * type PartialUser = SelectivePartial<User, 'age' | 'email'>;
+ * // { name: string; age?: number; email?: string }
+ * ```
+ */
+type SelectivePartial<T, K$1 extends keyof T> = Omit<T, K$1> & Partial<Pick<T, K$1>>;
+/**
+ * Makes all properties of an object type required recursively.
+ *
+ * This type traverses through nested objects and arrays, making all properties required.
+ * Functions and primitives are left unchanged.
+ *
+ * @template T - The type to make deeply required
+ * @returns A type with all properties required recursively
+ *
+ * @example
+ * ```ts
+ * type PartialConfig = {
+ *   server?: { host?: string; port?: number };
+ * };
+ *
+ * type RequiredConfig = DeepRequired<PartialConfig>;
+ * // {
+ * //   server: { host: string; port: number };
+ * // }
+ * ```
+ */
+type DeepRequired<T> = T extends Function ? T : T extends Array<infer U> ? Array<DeepRequired<U>> : T extends object ? { [K in keyof T]-?: DeepRequired<T[K]> } : T;
+/**
+ * Makes only specified properties of an object type required.
+ *
+ * @template T - The base object type
+ * @template K - The keys to make required
+ * @returns An object type with specified properties required
+ *
+ * @example
+ * ```ts
+ * type PartialUser = { name?: string; age?: number; email?: string };
+ * type RequiredUser = SelectiveRequired<PartialUser, 'name'>;
+ * // { name: string; age?: number; email?: string }
+ * ```
+ */
+type SelectiveRequired<T, K$1 extends keyof T> = Omit<T, K$1> & Required<Pick<T, K$1>>;
+/**
+ * Creates a type where all properties are never (useful for excluding types).
+ *
+ * This can be used to create mutually exclusive types or to exclude certain properties.
+ *
+ * @template T - The object type to transform
+ * @returns An object type with all properties set to never
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; age: number };
+ * type ExcludedUser = Never<User>; // { name: never; age: never }
+ * ```
+ */
+type Never<T> = { [K in keyof T]: never };
+/**
+ * Makes all properties of an object type nullable recursively.
+ *
+ * @template T - The type to make nullable
+ * @returns A type where all properties can be null
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; profile: { age: number } };
+ * type NullableUser = Nullable<User>;
+ * // { name: string | null; profile: { age: number | null } | null }
+ * ```
+ */
+type Nullable<T> = T extends object ? { [P in keyof T]: Nullable<T[P]> } : T | null;
+/**
+ * Makes all properties of an object type optional (undefined) recursively.
+ *
+ * @template T - The type to make optional
+ * @returns A type where all properties can be undefined
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; profile: { age: number } };
+ * type OptionalUser = Optional<User>;
+ * // { name: string | undefined; profile: { age: number | undefined } | undefined }
+ * ```
+ */
+type Optional<T> = T extends object ? { [P in keyof T]: Optional<T[P]> } : T | undefined;
+/**
+ * Makes all properties of an object type nullish (null or undefined) recursively.
+ *
+ * @template T - The type to make nullish
+ * @returns A type where all properties can be null or undefined
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; profile: { age: number } };
+ * type NullishUser = Nullish<User>;
+ * // { name: string | null | undefined; profile: { age: number | null | undefined } | null | undefined }
+ * ```
+ */
+type Nullish<T> = T extends object ? { [P in keyof T]: Nullish<T[P]> } : T | null | undefined;
+/**
+ * Makes all properties of an object type optional and nullish recursively.
+ *
+ * This combines optional properties with nullish values.
+ *
+ * @template T - The type to make maybe
+ * @returns A type where all properties are optional and can be null or undefined
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; profile: { age: number } };
+ * type MaybeUser = Maybe<User>;
+ * // { name?: string | null | undefined; profile?: { age?: number | null | undefined } | null | undefined }
+ * ```
+ */
+type Maybe<T> = T extends object ? { [P in keyof T]?: Nullish<T[P]> } : T | null | undefined;
+/**
+ * Makes all properties of an object type readonly recursively.
+ *
+ * This type traverses through nested objects and arrays, making all properties readonly.
+ * Functions and primitives are left unchanged.
+ *
+ * @template T - The type to make deeply readonly
+ * @returns A type with all properties readonly recursively
+ *
+ * @example
+ * ```ts
+ * type Config = {
+ *   server: { host: string; port: number };
+ *   features: string[];
+ * };
+ *
+ * type ReadonlyConfig = DeepReadonly<Config>;
+ * // {
+ * //   readonly server: { readonly host: string; readonly port: number };
+ * //   readonly features: readonly string[];
+ * // }
+ * ```
+ */
+type DeepReadonly<T> = T extends Function ? T : T extends Array<infer U> ? ReadonlyArray<DeepReadonly<U>> : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;
+/**
+ * Removes readonly modifier from all properties of an object type recursively.
+ *
+ * @template T - The readonly type to make mutable
+ * @returns A type with all readonly modifiers removed
+ *
+ * @example
+ * ```ts
+ * type ReadonlyUser = { readonly name: string; readonly profile: { readonly age: number } };
+ * type MutableUser = Mutable<ReadonlyUser>;
+ * // { name: string; profile: { age: number } }
+ * ```
+ */
+type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+/**
+ * Extracts keys of an object type that have values of a specific type.
+ *
+ * @template T - The object type to search
+ * @template U - The value type to match
+ * @returns A union of keys whose values match the specified type
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; age: number; active: boolean };
+ * type StringKeys = KeysOfType<User, string>; // 'name'
+ * type NumberKeys = KeysOfType<User, number>; // 'age'
+ * ```
+ */
+type KeysOfType<T, U$1> = { [K in keyof T]: T[K] extends U$1 ? K : never }[keyof T];
+/**
+ * Omits properties from an object type that have values of a specific type.
+ *
+ * @template T - The object type to filter
+ * @template U - The value type to exclude
+ * @returns An object type without properties of the specified value type
+ *
+ * @example
+ * ```ts
+ * type Mixed = { name: string; age: number; active: boolean };
+ * type WithoutStrings = OmitByType<Mixed, string>; // { age: number; active: boolean }
+ * ```
+ */
+type OmitByType<T, U$1> = { [K in keyof T as T[K] extends U$1 ? never : K]: T[K] };
+/**
+ * Makes specified properties required while keeping others as-is.
+ *
+ * @template T - The base object type
+ * @template K - The keys to make required
+ * @returns An object type with specified properties required
+ *
+ * @example
+ * ```ts
+ * type PartialUser = { name?: string; age?: number; email?: string };
+ * type RequiredNameUser = RequiredKeys<PartialUser, 'name'>;
+ * // { name: string; age?: number; email?: string }
+ * ```
+ */
+type RequiredKeys<T, K$1 extends keyof T> = Omit<T, K$1> & Required<Pick<T, K$1>>;
+/**
+ * Computes the symmetric difference between two object types.
+ *
+ * Properties that exist in either T or U but not in both.
+ *
+ * @template T - First object type
+ * @template U - Second object type
+ * @returns Properties unique to T or U
+ *
+ * @example
+ * ```ts
+ * type A = { x: number; y: string };
+ * type B = { y: string; z: boolean };
+ * type DiffAB = Diff<A, B>; // { x: number; z: boolean }
+ * ```
+ */
+type Diff<T, U$1> = Omit<T, keyof U$1> & Omit<U$1, keyof T>;
+/**
+ * Computes the intersection of two object types (properties present in both).
+ *
+ * @template T - First object type
+ * @template U - Second object type
+ * @returns Properties that exist in both T and U
+ *
+ * @example
+ * ```ts
+ * type A = { x: number; y: string };
+ * type B = { y: string; z: boolean };
+ * type IntersectionAB = Intersection<A, B>; // { y: string }
+ * ```
+ */
+type Intersection<T extends object, U$1 extends object> = Pick<T, Extract<keyof T, keyof U$1> & Extract<keyof U$1, keyof T>>;
+/**
+ * Merges two object types, combining their properties.
+ *
+ * @template T - First object type
+ * @template U - Second object type
+ * @returns A merged object type with properties from both
+ *
+ * @example
+ * ```ts
+ * type A = { x: number; y: string };
+ * type B = { y: boolean; z: string };
+ * type Merged = Merge<A, B>; // { x: number; y: boolean; z: string }
+ * ```
+ */
+type Merge<T extends object, U$1 extends object, I = Diff<T, U$1> & Intersection<U$1, T> & Diff<U$1, T>> = Pick<I, keyof I>;
+/**
+ * Subtracts properties of one object type from another.
+ *
+ * @template T - The object type to subtract from
+ * @template U - The object type whose properties to subtract
+ * @returns T without properties that exist in U
+ *
+ * @example
+ * ```ts
+ * type A = { x: number; y: string; z: boolean };
+ * type B = { y: string };
+ * type Subtracted = Substract<A, B>; // { x: number; z: boolean }
+ * ```
+ */
+type Substract<T extends object, U$1 extends object> = Omit<T, keyof U$1>;
+/**
+ * Represents either all properties present or none of them.
+ *
+ * Useful for creating mutually exclusive configurations.
+ *
+ * @template T - The object type
+ * @returns Either the full object or an empty object with optional properties
+ *
+ * @example
+ * ```ts
+ * type Config = { host: string; port: number };
+ * type AllOrNoneConfig = AllOrNone<Config>;
+ * // { host: string; port: number } | {}
+ * ```
+ */
+type AllOrNone<T> = T | { [P in keyof T]?: never };
+/**
+ * Represents exactly one property from an object type being present.
+ *
+ * Useful for creating discriminated unions or mutually exclusive options.
+ *
+ * @template T - The object type
+ * @returns A union where only one property is present at a time
+ *
+ * @example
+ * ```ts
+ * type Action = { type: 'create'; payload: string } | { type: 'update'; id: number };
+ * type OneAction = OneOf<Action>;
+ * // { type: 'create'; payload: string } | { type: 'update'; id: number }
+ * ```
+ */
+type OneOf<T> = { [K in keyof T]: Pick<T, K> }[keyof T];
+/**
+ * Represents exactly two properties from an object type being present.
+ *
+ * @template T - The object type
+ * @returns A union where exactly two properties are present at a time
+ *
+ * @example
+ * ```ts
+ * type Config = { a: number; b: string; c: boolean };
+ * type TwoConfig = TwoOf<Config>;
+ * // { a: number; b: string } | { a: number; c: boolean } | { b: string; c: boolean }
+ * ```
+ */
+type TwoOf<T> = { [K in keyof T]: { [L in Exclude<keyof T, K>]: Pick<T, K | L> }[Exclude<keyof T, K>] }[keyof T];
+/**
+ * Prettifies a complex type by expanding it for better readability in tooltips.
+ *
+ * This type doesn't change the runtime type but helps with IntelliSense display.
+ *
+ * @template T - The type to prettify
+ * @returns The same type but expanded for better readability
+ *
+ * @example
+ * ```ts
+ * type Complex = { a: string } & { b: number };
+ * type PrettyComplex = Prettify<Complex>; // Shows as { a: string; b: number }
+ * ```
+ */
+type Prettify<T> = T extends infer U ? U extends object ? { [K in keyof U]: U[K] } & {} : U : never;
+/**
+ * Extracts all nested keys of an object type as dot-separated strings.
+ *
+ * @template ObjectType - The object type to extract nested keys from
+ * @template IgnoreKeys - Keys to ignore during extraction
+ * @returns A union of dot-separated string paths
+ *
+ * @example
+ * ```ts
+ * type User = {
+ *   name: string;
+ *   profile: { age: number; address: { city: string } };
+ *   tags: string[];
+ * };
+ *
+ * type UserPaths = NestedKeyOf<User>;
+ * // 'name' | 'profile' | 'profile.age' | 'profile.address' | 'profile.address.city' | 'tags'
+ * ```
+ */
+type NestedKeyOf<ObjectType extends object, IgnoreKeys extends string = never> = { [Key in keyof ObjectType & string]: Key extends IgnoreKeys ? never : ObjectType[Key] extends object ? ObjectType[Key] extends Array<any> ? Key : `${Key}` | `${Key}.${NestedKeyOf<ObjectType[Key], IgnoreKeys>}` : `${Key}` }[keyof ObjectType & string];
+/**
+ * Creates a type that excludes properties present in another type.
+ *
+ * This is useful for creating mutually exclusive types.
+ *
+ * @template T - The base type
+ * @template U - The type whose properties to exclude
+ * @returns A type with properties from T that are not in U
+ *
+ * @example
+ * ```ts
+ * type A = { x: number; y: string };
+ * type B = { y: string };
+ * type WithoutB = Without<A, B>; // { x?: never }
+ * ```
+ */
+type Without<T, U$1> = { [P in Exclude<keyof T, keyof U$1>]?: never };
+//#endregion
+//#region src/types/gates.d.ts
+type BUFFER<T> = T;
+type IMPLIES<T, U$1> = T extends U$1 ? true : false;
+type XOR_Binary<T, U$1> = T | U$1 extends object ? (Without<T, U$1> & U$1) | (Without<U$1, T> & T) : T | U$1;
+type XNOR_Binary<T, U$1> = (T & U$1) | (Without<T, U$1> & Without<U$1, T>);
+/**
+ * Computes a type-level AND (all must true) for a tuple of types.
+ *
+ * Truth table for 3 arguments:
+ *
+ * A  B  C  = AND
+ * 1  1  1  = 1
+ * 1  1  0  = 0
+ * 1  0  1  = 0
+ * 1  0  0  = 0
+ * 0  1  1  = 0
+ * 0  1  0  = 0
+ * 0  0  1  = 0
+ * 0  0  0  = 0
+ *
+ * @template T - Tuple of boolean-like types (1/0)
+ */
+type AND<T extends any[]> = T extends [infer F, ...infer R] ? R extends any[] ? F & AND<R> : F : unknown;
+/**
+ * Computes a type-level OR (At least one) for a tuple of types.
+ *
+ * Truth table for 3 arguments:
+ *
+ * A  B  C  = OR
+ * 1  1  1  = 1
+ * 1  1  0  = 1
+ * 1  0  1  = 1
+ * 1  0  0  = 1
+ * 0  1  1  = 1
+ * 0  1  0  = 1
+ * 0  0  1  = 1
+ * 0  0  0  = 0
+ *
+ * @template T - Tuple of boolean-like types (1/0)
+ */
+type OR<T extends any[]> = T extends [infer F, ...infer R] ? R extends any[] ? F | OR<R> : F : never;
+/**
+ * Computes a type-level XOR (only one/odd) for a tuple of types.
+ *
+ * Truth table for 3 arguments:
+ *
+ * A  B  C  = XOR
+ * 1  1  1  = 1
+ * 1  1  0  = 0
+ * 1  0  1  = 0
+ * 1  0  0  = 1
+ * 0  1  1  = 0
+ * 0  1  0  = 1
+ * 0  0  1  = 1
+ * 0  0  0  = 0
+ *
+ * @template T - Tuple of boolean-like types (1/0)
+ */
+type XOR<T extends any[]> = T extends [infer F, ...infer R] ? R extends [infer S, ...infer Rest] ? XOR<[XOR_Binary<F, S>, ...Rest]> : F : never;
+/**
+ * Computes a type-level XNOR (All or None true) for a tuple of types.
+ *
+ * Truth table for 3 arguments:
+ *
+ * A  B  C  = XNOR
+ * 1  1  1  = 0
+ * 1  1  0  = 1
+ * 1  0  1  = 1
+ * 1  0  0  = 0
+ * 0  1  1  = 1
+ * 0  1  0  = 0
+ * 0  0  1  = 0
+ * 0  0  0  = 1
+ *
+ * @template T - Tuple of boolean-like types (1/0)
+ */
+type XNOR<T extends any[]> = T extends [infer F, ...infer R] ? R extends [infer S, ...infer Rest] ? XNOR<[XNOR_Binary<F, S>, ...Rest]> : F : never;
+/**
+ * Computes a type-level NOT for a tuple of types.
+ *
+ * Truth table for 3 arguments:
+ *
+ * A  B  C  = NOT
+ * 1  1  1  = 0
+ * 1  1  0  = 0
+ * 1  0  1  = 0
+ * 1  0  0  = 0
+ * 0  1  1  = 0
+ * 0  1  0  = 0
+ * 0  0  1  = 0
+ * 0  0  0  = 1
+ *
+ * @template T - Tuple of boolean-like types (1/0)
+ */
+type NOT<T> = { [P in keyof T]?: never };
+/**
+ * Computes a type-level NAND for a tuple of types.
+ *
+ * Truth table for 3 arguments:
+ *
+ * A  B  C  = NAND
+ * 1  1  1  = 0
+ * 1  1  0  = 1
+ * 1  0  1  = 1
+ * 1  0  0  = 1
+ * 0  1  1  = 1
+ * 0  1  0  = 1
+ * 0  0  1  = 1
+ * 0  0  0  = 1
+ *
+ * @template T - Tuple of boolean-like types (1/0)
+ */
+type NAND<T extends any[]> = NOT<AND<T>>;
+/**
+ * Computes a type-level NOR for a tuple of types.
+ *
+ * Truth table for 3 arguments:
+ *
+ * A  B  C  = NOR
+ * 1  1  1  = 0
+ * 1  1  0  = 0
+ * 1  0  1  = 0
+ * 1  0  0  = 0
+ * 0  1  1  = 0
+ * 0  1  0  = 0
+ * 0  0  1  = 0
+ * 0  0  0  = 1
+ *
+ * @template T - Tuple of boolean-like types (1/0)
+ */
+type NOR<T extends any[]> = NOT<OR<T>>;
+//#endregion
+//#region src/types/guards.d.ts
+/**
+ * Represents primitive JavaScript types including null and undefined.
+ */
+type Primitive = string | number | bigint | boolean | symbol | null | undefined;
+/**
+ * Represents all falsy values in JavaScript.
+ */
+type Falsy = false | '' | 0 | null | undefined;
+/**
+ * Type guard that checks if a value is falsy.
+ *
+ * @param val - The value to check
+ * @returns True if the value is falsy, false otherwise
+ *
+ * @example
+ * if (isFalsy(value)) {
+ *   console.log('Value is falsy');
+ * }
+ */
+declare const isFalsy: (val: unknown) => val is Falsy;
+/**
+ * Type guard that checks if a value is null or undefined.
+ *
+ * @param val - The value to check
+ * @returns True if the value is null or undefined, false otherwise
+ *
+ * @example
+ * if (isNullish(value)) {
+ *   console.log('Value is null or undefined');
+ * }
+ */
+declare const isNullish: (val: unknown) => val is null | undefined;
+/**
+ * Type guard that checks if a value is a primitive type.
+ *
+ * @param val - The value to check
+ * @returns True if the value is a primitive, false otherwise
+ *
+ * @example
+ * if (isPrimitive(value)) {
+ *   console.log('Value is a primitive type');
+ * }
+ */
+declare const isPrimitive: (val: unknown) => val is Primitive;
+/**
+ * Type guard that checks if a value is a plain object (not an array, function, etc.).
+ *
+ * @param value - The value to check
+ * @returns True if the value is a plain object, false otherwise
+ *
+ * @example
+ * if (isPlainObject(value)) {
+ *   console.log('Value is a plain object');
+ * }
+ */
+declare function isPlainObject(value: unknown): value is Record<string, any>;
+//#endregion
+export { Never as A, Substract as B, Intersection as C, Merge as D, Maybe as E, Optional as F, Values as H, Prettify as I, RequiredKeys as L, Nullish as M, OmitByType as N, Mutable as O, OneOf as P, SelectivePartial as R, Diff as S, KeysOfType as T, Without as U, TwoOf as V, XOR_Binary as _, isPlainObject as a, DeepReadonly as b, BUFFER as c, NOR as d, NOT as f, XOR as g, XNOR_Binary as h, isNullish as i, Nullable as j, NestedKeyOf as k, IMPLIES as l, XNOR as m, Primitive as n, isPrimitive as o, OR as p, isFalsy as r, AND as s, Falsy as t, NAND as u, AllOrNone as v, Keys as w, DeepRequired as x, DeepPartial as y, SelectiveRequired as z };