@depup/type-fest 5.4.4-depup.0

package/source/is-tuple.d.ts

@@ -0,0 +1,92 @@
+import type {If} from './if.d.ts';
+import type {ApplyDefaultOptions} from './internal/index.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {IsNever} from './is-never.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
+/**
+@see {@link IsTuple}
+*/
+export type IsTupleOptions = {
+	/**
+	Consider only fixed length arrays as tuples.
+
+	- When set to `true` (default), arrays with rest elements (e.g., `[1, ...number[]]`) are _not_ considered as tuples.
+	- When set to `false`, arrays with at least one non-rest element (e.g., `[1, ...number[]]`) are considered as tuples.
+
+	@default true
+
+	@example
+	```ts
+	import type {IsTuple} from 'type-fest';
+
+	type Example1 = IsTuple<[number, ...number[]], {fixedLengthOnly: true}>;
+	//=> false
+
+	type Example2 = IsTuple<[number, ...number[]], {fixedLengthOnly: false}>;
+	//=> true
+	```
+	*/
+	fixedLengthOnly?: boolean;
+};
+
+type DefaultIsTupleOptions = {
+	fixedLengthOnly: true;
+};
+
+/**
+Returns a boolean for whether the given array is a tuple.
+
+Use-case:
+- If you want to make a conditional branch based on the result of whether an array is a tuple or not.
+
+Note: `IsTuple` returns `boolean` when instantiated with a union of tuple and non-tuple (e.g., `IsTuple<[1, 2] | number[]>`).
+
+@example
+```ts
+import type {IsTuple} from 'type-fest';
+
+type Tuple = IsTuple<[1, 2, 3]>;
+//=> true
+
+type NotTuple = IsTuple<number[]>;
+//=> false
+
+type TupleWithOptionalItems = IsTuple<[1?, 2?]>;
+//=> true
+
+type RestItemsNotAllowed = IsTuple<[1, 2, ...number[]]>;
+//=> false
+
+type RestItemsAllowed = IsTuple<[1, 2, ...number[]], {fixedLengthOnly: false}>;
+//=> true
+```
+
+@see {@link IsTupleOptions}
+
+@category Type Guard
+@category Utilities
+*/
+export type IsTuple<
+	TArray extends UnknownArray,
+	Options extends IsTupleOptions = {},
+> =
+	_IsTuple<TArray, ApplyDefaultOptions<IsTupleOptions, DefaultIsTupleOptions, Options>>;
+
+type _IsTuple<
+	TArray extends UnknownArray,
+	Options extends Required<IsTupleOptions>,
+> =
+	If<IsAny<TArray>, boolean, If<IsNever<TArray>, false,
+		TArray extends unknown // For distributing `TArray`
+			? number extends TArray['length']
+				? Options['fixedLengthOnly'] extends false
+					? If<IsNever<keyof TArray & `${number}`>,
+						TArray extends readonly [...any, any] ? true : false, // To handle cases where a non-rest element follows a rest element, e.g., `[...number[], number]`
+						true>
+					: false
+				: true
+			: false
+	>>;
+
+export {};

package/source/is-undefined.d.ts

@@ -0,0 +1,22 @@
+/**
+Returns a boolean for whether the given type is `undefined`.
+
+@example
+```
+import type {IsUndefined} from 'type-fest';
+
+type UndefinedFallback<T, Fallback> = IsUndefined<T> extends true ? Fallback : T;
+
+type Example1 = UndefinedFallback<undefined, string>;
+//=> string
+
+type Example2 = UndefinedFallback<number, string>;
+//=> number
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsUndefined<T> = [T] extends [undefined] ? true : false;
+
+export {};

package/source/is-union.d.ts

@@ -0,0 +1,40 @@
+import type {IsNever} from './is-never.d.ts';
+import type {IsEqual} from './is-equal.d.ts';
+
+/**
+Returns a boolean for whether the given type is a union.
+
+@example
+```
+import type {IsUnion} from 'type-fest';
+
+type A = IsUnion<string | number>;
+//=> true
+
+type B = IsUnion<string>;
+//=> false
+```
+*/
+export type IsUnion<T> = InternalIsUnion<T>;
+
+/**
+The actual implementation of `IsUnion`.
+*/
+type InternalIsUnion<T, U = T> =
+(
+	IsNever<T> extends true
+		? false
+		: T extends any
+			? IsEqual<U, T> extends true
+				? false
+				: true
+			: never
+) extends infer Result
+	// In some cases `Result` will return `false | true` which is `boolean`,
+	// that means `T` has at least two types and it's a union type,
+	// so we will return `true` instead of `boolean`.
+	? boolean extends Result ? true
+		: Result
+	: never; // Should never happen
+
+export {};

package/source/is-unknown.d.ts

@@ -0,0 +1,43 @@
+import type {IsNull} from './is-null.d.ts';
+
+/**
+Returns a boolean for whether the given type is `unknown`.
+
+@link https://github.com/dsherret/conditional-type-checks/pull/16
+
+Useful in type utilities, such as when dealing with unknown data from API calls.
+
+@example
+```
+import type {IsUnknown} from 'type-fest';
+
+type A = IsUnknown<unknown>;
+//=> true
+
+type B = IsUnknown<any>;
+//=> false
+
+type C = IsUnknown<never>;
+//=> false
+
+type D = IsUnknown<unknown[]>;
+//=> false
+
+type E = IsUnknown<object>;
+//=> false
+
+type F = IsUnknown<string>;
+//=> false
+```
+
+@category Utilities
+*/
+export type IsUnknown<T> = (
+	unknown extends T // `T` can be `unknown` or `any`
+		? IsNull<T> extends false // `any` can be `null`, but `unknown` can't be
+			? true
+			: false
+		: false
+);
+
+export {};

package/source/is-uppercase.d.ts

@@ -0,0 +1,38 @@
+import type {AllExtend} from './all-extend.d.ts';
+
+/**
+Returns a boolean for whether the given string literal is uppercase.
+
+@example
+```
+import type {IsUppercase} from 'type-fest';
+
+type A = IsUppercase<'ABC'>;
+//=> true
+
+type B = IsUppercase<'Abc'>;
+//=> false
+
+type C = IsUppercase<string>;
+//=> boolean
+```
+*/
+export type IsUppercase<S extends string> = AllExtend<_IsUppercase<S>, true>;
+
+/**
+Loops through each part in the string and returns a boolean array indicating whether each part is uppercase.
+*/
+type _IsUppercase<S extends string, Accumulator extends boolean[] = []> = S extends `${infer First}${infer Rest}`
+	? _IsUppercase<Rest, [...Accumulator, IsUppercaseHelper<First>]>
+	: [...Accumulator, IsUppercaseHelper<S>];
+
+/**
+Returns a boolean for whether an individual part of the string is uppercase.
+*/
+type IsUppercaseHelper<S extends string> = S extends Uppercase<string>
+	? true
+	: S extends Lowercase<string> | Uncapitalize<string> | `${string}${Lowercase<string>}${string}`
+		? false
+		: boolean;
+
+export {};

package/source/is-writable-key-of.d.ts

@@ -0,0 +1,51 @@
+import type {IsReadonlyKeyOf} from './is-readonly-key-of.d.ts';
+import type {Not} from './internal/type.d.ts';
+import type {IsAny} from './is-any.d.ts';
+
+/**
+Returns a boolean for whether the given key is a writable key of type.
+
+This is useful when writing utility types or schema validators that need to differentiate `writable` keys.
+
+@example
+```
+import type {IsWritableKeyOf} from 'type-fest';
+
+type User = {
+	name: string;
+	surname: string;
+
+	readonly id: number;
+};
+
+type Admin = {
+	name: string;
+	id: string;
+};
+
+type T1 = IsWritableKeyOf<User, 'name'>;
+//=> true
+
+type T2 = IsWritableKeyOf<User, 'id'>;
+//=> false
+
+type T3 = IsWritableKeyOf<User, 'name' | 'id'>;
+//=> boolean
+
+type T4 = IsWritableKeyOf<User | Admin, 'name'>;
+//=> true
+
+type T5 = IsWritableKeyOf<User | Admin, 'id'>;
+//=> boolean
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsWritableKeyOf<Type extends object, Key extends keyof Type> =
+	IsAny<Type | Key> extends true ? never
+		: Key extends keyof Type
+			? Not<IsReadonlyKeyOf<Type, Key>>
+			: false;
+
+export {};

package/source/iterable-element.d.ts

@@ -0,0 +1,66 @@
+/**
+Get the element type of an `Iterable`/`AsyncIterable`. For example, `Array`, `Set`, `Map`, generator, stream, etc.
+
+This can be useful, for example, if you want to get the type that is yielded in a generator function. Often the return type of those functions are not specified.
+
+This type works with both `Iterable`s and `AsyncIterable`s, so it can be use with synchronous and asynchronous generators.
+
+Here is an example of `IterableElement` in action with a generator function:
+
+@example
+```
+import type {IterableElement} from 'type-fest';
+
+function * iAmGenerator() {
+	yield 1;
+	yield 2;
+}
+
+type MeNumber = IterableElement<ReturnType<typeof iAmGenerator>>;
+```
+
+And here is an example with an async generator:
+
+@example
+```
+import type {IterableElement} from 'type-fest';
+
+async function * iAmGeneratorAsync() {
+	yield 'hi';
+	yield true;
+}
+
+type MeStringOrBoolean = IterableElement<ReturnType<typeof iAmGeneratorAsync>>;
+```
+
+Many types in JavaScript/TypeScript are iterables. This type works on all types that implement those interfaces.
+
+An example with an array of strings:
+
+@example
+```
+import type {IterableElement} from 'type-fest';
+
+type MeString = IterableElement<string[]>;
+```
+
+@example
+```
+import type {IterableElement} from 'type-fest';
+
+const fruits = new Set(['🍎', '🍌', '🍉'] as const);
+
+type Fruit = IterableElement<typeof fruits>;
+//=> '🍎' | '🍌' | '🍉'
+```
+
+@category Iterable
+*/
+export type IterableElement<TargetIterable> =
+	TargetIterable extends Iterable<infer ElementType> ?
+		ElementType :
+		TargetIterable extends AsyncIterable<infer ElementType> ?
+			ElementType :
+			never;
+
+export {};

package/source/join.d.ts

@@ -0,0 +1,79 @@
+// The builtin `join` method supports all these natively in the same way that typescript handles them so we can safely accept all of them.
+type JoinableItem = string | number | bigint | boolean | undefined | null;
+
+// `null` and `undefined` are treated uniquely in the built-in join method, in a way that differs from the default `toString` that would result in the type `${undefined}`. That's why we need to handle it specifically with this helper.
+// @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join#description
+type NullishCoalesce<
+	Value extends JoinableItem,
+	Fallback extends string,
+> = Value extends undefined | null ? NonNullable<Value> | Fallback : Value;
+
+/**
+Join an array of strings and/or numbers using the given string as a delimiter.
+
+Use-case: Defining key paths in a nested object. For example, for dot-notation fields in MongoDB queries.
+
+@example
+```
+import type {Join} from 'type-fest';
+
+// Mixed (strings & numbers) items
+const path1 = ['foo', 0, 'baz'].join('.') as Join<['foo', 0, 'baz'], '.'>;
+//=> 'foo.0.baz'
+
+// Only string items
+const path2 = ['foo', 'bar', 'baz'].join('.') as Join<['foo', 'bar', 'baz'], '.'>;
+//=> 'foo.bar.baz'
+
+// Only number items
+const path3 = [1, 2, 3].join('.') as Join<[1, 2, 3], '.'>;
+//=> '1.2.3'
+
+// Only bigint items
+const path4 = [1n, 2n, 3n].join('.') as Join<[1n, 2n, 3n], '.'>;
+//=> '1.2.3'
+
+// Only boolean items
+const path5 = [true, false, true].join('.') as Join<[true, false, true], '.'>;
+//=> 'true.false.true'
+
+// Contains nullish items
+const path6 = ['foo', undefined, 'baz', null, 'xyz'].join('.') as Join<['foo', undefined, 'baz', null, 'xyz'], '.'>;
+//=> 'foo..baz..xyz'
+
+// Partial tuple shapes (rest param last)
+const path7 = ['prefix'].join('.') as Join<['prefix', ...string[]], '.'>;
+//=> `prefix.${string}`
+
+// Partial tuple shapes (rest param first)
+const path8 = ['suffix'].join('.') as Join<[...string[], 'suffix'], '.'>;
+//=> `${string}.suffix`
+
+// Tuples items with nullish unions
+const path9 = ['hello', 'world'].join('.') as Join<['hello' | undefined, 'world' | null], '.'>;
+//=> '.' | '.world' | 'hello.' | 'hello.world'
+```
+
+@category Array
+@category Template literal
+*/
+export type Join<
+	Items extends readonly JoinableItem[],
+	Delimiter extends string,
+> = Items extends readonly []
+	? ''
+	: Items extends readonly [JoinableItem?]
+		? `${NullishCoalesce<Items[0], ''>}`
+		: Items extends readonly [
+			infer First extends JoinableItem,
+			...infer Tail extends readonly JoinableItem[],
+		]
+			? `${NullishCoalesce<First, ''>}${Delimiter}${Join<Tail, Delimiter>}`
+			: Items extends readonly [
+				...infer Head extends readonly JoinableItem[],
+				infer Last extends JoinableItem,
+			]
+				? `${Join<Head, Delimiter>}${Delimiter}${NullishCoalesce<Last, ''>}`
+				: string;
+
+export {};

package/source/json-value.d.ts

@@ -0,0 +1,33 @@
+/**
+Matches a JSON object.
+
+This type can be useful to enforce some input to be JSON-compatible or as a super-type to be extended from. Don't use this as a direct return type as the user would have to double-cast it: `jsonObject as unknown as CustomResponse`. Instead, you could extend your CustomResponse type from it to ensure your type only uses JSON-compatible types: `interface CustomResponse extends JsonObject { … }`.
+
+@category JSON
+*/
+export type JsonObject = {[Key in string]: JsonValue};
+
+/**
+Matches a JSON array.
+
+@category JSON
+*/
+export type JsonArray = JsonValue[] | readonly JsonValue[];
+
+/**
+Matches any valid JSON primitive value.
+
+@category JSON
+*/
+export type JsonPrimitive = string | number | boolean | null;
+
+/**
+Matches any valid JSON value.
+
+@see `Jsonify` if you need to transform a type to one that is assignable to `JsonValue`.
+
+@category JSON
+*/
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+
+export {};

package/source/jsonifiable.d.ts

@@ -0,0 +1,37 @@
+import type {JsonPrimitive} from './json-value.d.ts';
+
+type JsonifiableObject = {[Key in string]?: Jsonifiable} | {toJSON: () => Jsonifiable};
+type JsonifiableArray = readonly Jsonifiable[];
+
+/**
+Matches a value that can be losslessly converted to JSON.
+
+Can be used to type values that you expect to pass to `JSON.stringify`.
+
+`undefined` is allowed in object fields (for example, `{a?: number}`) as a special case even though `JSON.stringify({a: undefined})` is `{}` because it makes this class more widely useful and checking for undefined-but-present values is likely an anti-pattern.
+
+@example
+```
+import type {Jsonifiable} from 'type-fest';
+
+// @ts-expect-error
+const error: Jsonifiable = {
+	map: new Map([['a', 1]]),
+};
+
+console.log(JSON.stringify(error)); // {"map": {}}
+
+const good: Jsonifiable = {
+	number: 3,
+	date: new Date('2025-12-25'),
+	missing: undefined,
+};
+
+console.log(JSON.stringify(good)); // {"number": 3, "date": "2025-12-25T00:00:00.000Z"}
+```
+
+@category JSON
+*/
+export type Jsonifiable = JsonPrimitive | JsonifiableObject | JsonifiableArray;
+
+export {};

package/source/jsonify.d.ts

@@ -0,0 +1,127 @@
+import type {JsonPrimitive, JsonValue} from './json-value.d.ts';
+import type {EmptyObject} from './empty-object.d.ts';
+import type {UndefinedToOptional} from './internal/index.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {IsNever} from './is-never.d.ts';
+import type {IsUnknown} from './is-unknown.d.ts';
+import type {NegativeInfinity, PositiveInfinity} from './numeric.d.ts';
+import type {TypedArray} from './typed-array.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
+// Note: The return value has to be `any` and not `unknown` so it can match `void`.
+type NotJsonable = ((...arguments_: any[]) => any) | undefined | symbol;
+
+type NeverToNull<T> = IsNever<T> extends true ? null : T;
+type UndefinedToNull<T> = T extends undefined ? null : T;
+
+// Handles tuples and arrays
+type JsonifyList<T extends UnknownArray> = T extends readonly []
+	? []
+	: T extends readonly [infer F, ...infer R]
+		? [F, ...R] extends T // With TS 5.8.3, if `string[] & ['foo']`, `R` is `unknown[]` here, making the inferred types not equal to the original one
+			? [NeverToNull<Jsonify<F>>, ...JsonifyList<R>]
+			: [NeverToNull<Jsonify<F>>]
+		: IsUnknown<T[number]> extends true
+			? JsonValue[]
+			: Array<T[number] extends NotJsonable ? null : Jsonify<UndefinedToNull<T[number]>>>;
+
+type FilterJsonableKeys<T extends object> = {
+	[Key in keyof T]: T[Key] extends NotJsonable ? never : Key;
+}[keyof T];
+
+/**
+JSON serialize objects (not including arrays) and classes.
+*/
+type JsonifyObject<T extends object> = {
+	[Key in keyof Pick<T, FilterJsonableKeys<T>>]: Jsonify<T[Key]>;
+};
+
+/**
+Transform a type to one that is assignable to the `JsonValue` type.
+
+This includes:
+1. Transforming JSON `interface` to a `type` that is assignable to `JsonValue`.
+2. Transforming non-JSON value that is *jsonable* to a type that is assignable to `JsonValue`, where *jsonable* means the non-JSON value implements the `.toJSON()` method that returns a value that is assignable to `JsonValue`.
+
+@remarks
+
+An interface cannot be structurally compared to `JsonValue` because an interface can be re-opened to add properties that may not satisfy `JsonValue`.
+
+@example
+```
+import type {Jsonify, JsonValue} from 'type-fest';
+
+interface Geometry {
+	type: 'Point' | 'Polygon';
+	coordinates: [number, number];
+}
+
+const point: Geometry = {
+	type: 'Point',
+	coordinates: [1, 1],
+};
+
+declare function problemFn(data: JsonValue): void;
+
+// @ts-expect-error
+problemFn(point); // Error: type Geometry is not assignable to parameter of type JsonValue because it is an interface
+
+declare function fixedFn<T>(data: Jsonify<T>): void;
+
+fixedFn(point); // Good: point is assignable. Jsonify<T> transforms Geometry into value assignable to JsonValue
+
+// @ts-expect-error
+fixedFn(new Date()); // Error: As expected, Date is not assignable. Jsonify<T> cannot transform Date into a value assignable to JsonValue
+```
+
+Non-JSON values such as `Date` implement `.toJSON()`, so they can be transformed to a value assignable to `JsonValue`:
+
+@example
+```
+import type {Jsonify} from 'type-fest';
+
+const time = {
+	timeValue: new Date(),
+};
+
+// `Jsonify<typeof time>` is equivalent to `{timeValue: string}`
+const timeJson = JSON.parse(JSON.stringify(time)) as Jsonify<typeof time>;
+```
+
+@link https://github.com/Microsoft/TypeScript/issues/1897#issuecomment-710744173
+
+@category JSON
+*/
+export type Jsonify<T> = IsAny<T> extends true
+	? any
+	: T extends PositiveInfinity | NegativeInfinity
+		? null
+		: T extends JsonPrimitive
+			? T
+			: // Any object with toJSON is special case
+			T extends {toJSON(): infer J}
+				? (() => J) extends () => JsonValue // Is J assignable to JsonValue?
+					? J // Then T is Jsonable and its Jsonable value is J
+					: Jsonify<J> // Maybe if we look a level deeper we'll find a JsonValue
+				: // Instanced primitives are objects
+				T extends Number
+					? number
+					: T extends String
+						? string
+						: T extends Boolean
+							? boolean
+							: T extends Map<any, any> | Set<any>
+								? EmptyObject
+								: T extends TypedArray
+									? Record<string, number>
+									: T extends NotJsonable
+										? never // Non-JSONable type union was found not empty
+										: T extends UnknownArray
+											? JsonifyList<T>
+											: T extends object
+												? JsonifyObject<UndefinedToOptional<T>> // JsonifyObject recursive call for its children
+												: IsUnknown<T> extends true
+													? JsonValue
+													: never; // Otherwise any other non-object is removed
+
+export {};

package/source/kebab-case.d.ts

@@ -0,0 +1,46 @@
+import type {_DefaultDelimiterCaseOptions, DelimiterCase} from './delimiter-case.d.ts';
+import type {ApplyDefaultOptions} from './internal/index.d.ts';
+import type {WordsOptions} from './words.d.ts';
+
+/**
+Convert a string literal to kebab-case.
+
+This can be useful when, for example, converting a camel-cased object property to a kebab-cased CSS class name or a command-line flag.
+
+@example
+```
+import type {KebabCase} from 'type-fest';
+
+// Simple
+
+const someVariable: KebabCase<'fooBar'> = 'foo-bar';
+const someVariableNoSplitOnNumbers: KebabCase<'p2pNetwork', {splitOnNumbers: false}> = 'p2p-network';
+
+// Advanced
+
+type KebabCasedProperties<T> = {
+	[K in keyof T as KebabCase<K>]: T[K]
+};
+
+type CliOptions = {
+	dryRun: boolean;
+	includeFile: string;
+	foo: number;
+};
+
+const rawCliOptions: KebabCasedProperties<CliOptions> = {
+	'dry-run': true,
+	'include-file': 'bar.js',
+	foo: 123,
+};
+```
+
+@category Change case
+@category Template literal
+*/
+export type KebabCase<
+	Value,
+	Options extends WordsOptions = {},
+> = DelimiterCase<Value, '-', ApplyDefaultOptions<WordsOptions, _DefaultDelimiterCaseOptions, Options>>;
+
+export {};