@depup/type-fest 5.5.0-depup.0 → 5.9.0-depup.0

package/source/is-literal.d.ts

@@ -1,270 +1,14 @@
-import type {Primitive} from './primitive.d.ts';
-import type {_Numeric} from './numeric.d.ts';
-import type {CollapseLiterals, IfNotAnyOrNever, IsNotFalse, IsPrimitive} from './internal/index.d.ts';
+import type {IsStringLiteral} from './is-string-literal.d.ts';
+import type {IsNumericLiteral} from './is-numeric-literal.d.ts';
+import type {IsBooleanLiteral} from './is-boolean-literal.d.ts';
+import type {IsSymbolLiteral} from './is-symbol-literal.d.ts';
 import type {IsNever} from './is-never.d.ts';
-import type {TagContainer, UnwrapTagged} from './tagged.d.ts';
-
-/**
-Returns a boolean for whether the given type `T` is the specified `LiteralType`.
-
-@link https://stackoverflow.com/a/52806744/10292952
-
-@example
-```
-type A = LiteralCheck<1, number>;
-//=> true
-
-type B = LiteralCheck<number, number>;
-//=> false
-
-type C = LiteralCheck<1, string>;
-//=> false
-```
-*/
-type LiteralCheck<T, LiteralType extends Primitive> = (
-	IsNever<T> extends false // Must be wider than `never`
-		? [T] extends [LiteralType & infer U] // Remove any branding
-			? [U] extends [LiteralType] // Must be narrower than `LiteralType`
-				? [LiteralType] extends [U] // Cannot be wider than `LiteralType`
-					? false
-					: true
-				: false
-			: false
-		: false
-);
-
-/**
-Returns a boolean for whether the given type `T` is one of the specified literal types in `LiteralUnionType`.
-
-@example
-```
-type A = LiteralChecks<1, Numeric>;
-//=> true
-
-type B = LiteralChecks<1n, Numeric>;
-//=> true
-
-type C = LiteralChecks<bigint, Numeric>;
-//=> false
-```
-*/
-type LiteralChecks<T, LiteralUnionType> = (
-	// Conditional type to force union distribution.
-	// If `T` is none of the literal types in the union `LiteralUnionType`, then `LiteralCheck<T, LiteralType>` will evaluate to `false` for the whole union.
-	// If `T` is one of the literal types in the union, it will evaluate to `boolean` (i.e. `true | false`)
-	IsNotFalse<LiteralUnionType extends Primitive
-		? LiteralCheck<T, LiteralUnionType>
-		: never
-	>
-);
-
-/**
-Returns a boolean for whether the given type is a `string` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
-
-Useful for:
-	- providing strongly-typed string manipulation functions
-	- constraining strings to be a string literal
-	- type utilities, such as when constructing parsers and ASTs
-
-The implementation of this type is inspired by the trick mentioned in this [StackOverflow answer](https://stackoverflow.com/a/68261113/420747).
-
-@example
-```
-import type {IsStringLiteral} from 'type-fest';
-
-type CapitalizedString<T extends string> = IsStringLiteral<T> extends true ? Capitalize<T> : string;
-
-// https://github.com/yankeeinlondon/native-dash/blob/master/src/capitalize.ts
-function capitalize<T extends Readonly<string>>(input: T): CapitalizedString<T> {
-	return (input.slice(0, 1).toUpperCase() + input.slice(1)) as CapitalizedString<T>;
-}
-
-const output = capitalize('hello, world!');
-//=> 'Hello, world!'
-```
-
-@example
-```
-// String types with infinite set of possible values return `false`.
-
-import type {IsStringLiteral} from 'type-fest';
-
-type AllUppercaseStrings = IsStringLiteral<Uppercase<string>>;
-//=> false
-
-type StringsStartingWithOn = IsStringLiteral<`on${string}`>;
-//=> false
-
-// This behaviour is particularly useful in string manipulation utilities, as infinite string types often require separate handling.
-
-type Length<S extends string, Counter extends never[] = []> =
-	IsStringLiteral<S> extends false
-		? number // return `number` for infinite string types
-		: S extends `${string}${infer Tail}`
-			? Length<Tail, [...Counter, never]>
-			: Counter['length'];
-
-type L1 = Length<Lowercase<string>>;
-//=> number
-
-type L2 = Length<`${number}`>;
-//=> number
-```
-
-@category Type Guard
-@category Utilities
-*/
-export type IsStringLiteral<S> = IfNotAnyOrNever<S,
-	_IsStringLiteral<CollapseLiterals<S extends TagContainer<any> ? UnwrapTagged<S> : S>>,
-	false, false>;
-
-export type _IsStringLiteral<S> =
-// If `T` is an infinite string type (e.g., `on${string}`), `Record<T, never>` produces an index signature,
-// and since `{}` extends index signatures, the result becomes `false`.
-S extends string
-	? {} extends Record<S, never>
-		? false
-		: true
-	: false;
-
-/**
-Returns a boolean for whether the given type is a `number` or `bigint` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
-
-Useful for:
-	- providing strongly-typed functions when given literal arguments
-	- type utilities, such as when constructing parsers and ASTs
-
-@example
-```
-import type {IsNumericLiteral, IsStringLiteral} from 'type-fest';
-
-// https://github.com/inocan-group/inferred-types/blob/master/modules/types/src/boolean-logic/operators/EndsWith.ts
-type EndsWith<TValue, TEndsWith extends string> =
-	TValue extends string
-		? IsStringLiteral<TEndsWith> extends true
-			? IsStringLiteral<TValue> extends true
-				? TValue extends `${string}${TEndsWith}`
-					? true
-					: false
-				: boolean
-			: boolean
-		: TValue extends number
-			? IsNumericLiteral<TValue> extends true
-				? EndsWith<`${TValue}`, TEndsWith>
-				: false
-			: false;
-
-function endsWith<Input extends string | number, End extends string>(input: Input, end: End) {
-	return `${input}`.endsWith(end) as EndsWith<Input, End>;
-}
-
-endsWith('abc', 'c');
-//=> true
-
-endsWith(123_456, '456');
-//=> true
-
-const end = '123' as string;
-
-endsWith('abc123', end);
-//=> boolean
-```
-
-@category Type Guard
-@category Utilities
-*/
-export type IsNumericLiteral<T> = LiteralChecks<T, _Numeric>;
-
-/**
-Returns a boolean for whether the given type is a `true` or `false` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
-
-Useful for:
-	- providing strongly-typed functions when given literal arguments
-	- type utilities, such as when constructing parsers and ASTs
-
-@example
-```
-import type {IsBooleanLiteral} from 'type-fest';
-
-const id = 123;
-
-type GetId<AsString extends boolean> =
-	IsBooleanLiteral<AsString> extends true
-		? AsString extends true
-			? `${typeof id}`
-			: typeof id
-		: number | string;
-
-function getId<AsString extends boolean = false>(options?: {asString: AsString}) {
-	return (options?.asString ? `${id}` : id) as GetId<AsString>;
-}
-
-const numberId = getId();
-//=> 123
-
-const stringId = getId({asString: true});
-//=> '123'
-
-declare const runtimeBoolean: boolean;
-const eitherId = getId({asString: runtimeBoolean});
-//=> string | number
-```
-
-@category Type Guard
-@category Utilities
-*/
-export type IsBooleanLiteral<T> = LiteralCheck<T, boolean>;
-
-/**
-Returns a boolean for whether the given type is a `symbol` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
-
-Useful for:
-	- providing strongly-typed functions when given literal arguments
-	- type utilities, such as when constructing parsers and ASTs
-
-@example
-```
-import type {IsSymbolLiteral} from 'type-fest';
-
-type Get<Object_ extends Record<symbol, number>, Key extends keyof Object_> =
-	IsSymbolLiteral<Key> extends true
-		? Object_[Key]
-		: number;
-
-function get<Object_ extends Record<symbol, number>, Key extends keyof Object_>(o: Object_, key: Key) {
-	return o[key] as Get<Object_, Key>;
-}
-
-const symbolLiteral = Symbol('literal');
-let symbolValue = Symbol('value1');
-symbolValue = Symbol('value2');
-
-get({[symbolLiteral]: 1} as const, symbolLiteral);
-//=> 1
-
-get({[symbolValue]: 1} as const, symbolValue);
-//=> number
-```
-
-@category Type Guard
-@category Utilities
-*/
-export type IsSymbolLiteral<T> = LiteralCheck<T, symbol>;
-
-/** Helper type for `IsLiteral`. */
-type IsLiteralUnion<T> =
-	| IsStringLiteral<T>
-	| IsNumericLiteral<T>
-	| IsBooleanLiteral<T>
-	| IsSymbolLiteral<T>;
+import type {IfNotAnyOrNever} from './internal/type.d.ts';
+import type {CollapseLiterals, UnwrapBrand} from './internal/object.d.ts';
 
 /**
 Returns a boolean for whether the given type is a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
 
-Useful for:
-	- providing strongly-typed functions when given literal arguments
-	- type utilities, such as when constructing parsers and ASTs
-
 @example
 ```
 import type {IsLiteral} from 'type-fest';
@@ -300,16 +44,48 @@ type I = IsLiteral<symbol>;
 type J = IsLiteral<true>;
 //=> true
 
-type K = IsLiteral<boolean>;
+type K = IsLiteral<false>;
+//=> true
+
+type L = IsLiteral<boolean>;
 //=> false
+
+type M = IsLiteral<1 | 'foo' | false>;
+//=> true
+
+type N = IsLiteral<string | number | symbol>;
+//=> false
+
+type O = IsLiteral<1000n | string | true>;
+//=> boolean
 ```
 
 @category Type Guard
 @category Utilities
 */
-export type IsLiteral<T> =
-	IsPrimitive<T> extends true
-		? IsNotFalse<IsLiteralUnion<T>>
-		: false;
+export type IsLiteral<T> = IfNotAnyOrNever<T, {
+	ifNot: _IsLiteral<CollapseLiterals<UnwrapBrand<T>>>;
+	ifAny: false;
+	ifNever: false;
+}>;
+
+type _IsLiteral<T> =
+	| (Extract<T, boolean> extends infer Bools
+		// We can't instantiate `IsBooleanLiteral` with `never`,
+		// because that will add an extraneous `false` to the result if there are no booleans.
+		? IsNever<Bools> extends true
+			? never
+			: IsBooleanLiteral<Bools>
+		: never)
+	| (IsLiteralNonBools<Exclude<T, boolean>>);
+
+type IsLiteralNonBools<T> =
+	T extends number | bigint
+		? IsNumericLiteral<T>
+		: T extends string
+			? IsStringLiteral<T>
+			: T extends symbol
+				? IsSymbolLiteral<T>
+				: false;
 
 export {};

package/source/is-numeric-literal.d.ts

@@ -0,0 +1,50 @@
+import type {CollapseLiterals, UnwrapBrand} from './internal/object.d.ts';
+import type {IfNotAnyOrNever} from './internal/type.d.ts';
+
+/**
+Returns a boolean for whether the given type is a `number` or `bigint` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+
+@example
+```
+import type {IsNumericLiteral} from 'type-fest';
+
+type A = IsNumericLiteral<0>;
+//=> true
+
+type B = IsNumericLiteral<number>;
+//=> false
+
+type C = IsNumericLiteral<100n>;
+//=> true
+
+type D = IsNumericLiteral<bigint>;
+//=> false
+
+type E = IsNumericLiteral<1 | 2 | 10n | 20n>;
+//=> true
+
+type F = IsNumericLiteral<number | bigint>;
+//=> false
+
+type G = IsNumericLiteral<1 | bigint>;
+//=> boolean
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsNumericLiteral<T> = IfNotAnyOrNever<T, {
+	ifNot: _IsNumericLiteral<CollapseLiterals<UnwrapBrand<T>>>;
+	ifAny: false;
+	ifNever: false;
+}>;
+
+type _IsNumericLiteral<T> = T extends number | bigint
+	? number extends T
+		? false
+		: bigint extends T
+			? false
+			: true
+	: false;
+
+export {};

package/source/is-string-literal.d.ts

@@ -0,0 +1,72 @@
+import type {CollapseLiterals, UnwrapBrand} from './internal/object.d.ts';
+import type {IfNotAnyOrNever} from './internal/type.d.ts';
+
+/**
+Returns a boolean for whether the given type is a `string` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+
+The implementation of this type is inspired by the trick mentioned in this [StackOverflow answer](https://stackoverflow.com/a/68261113/420747).
+
+@example
+```
+import type {IsStringLiteral} from 'type-fest';
+
+type A = IsStringLiteral<'foo'>;
+//=> true
+
+type B = IsStringLiteral<string>;
+//=> false
+
+// String types with infinite set of possible values return `false`
+type C = IsStringLiteral<`on${string}`>;
+//=> false
+
+type D = IsStringLiteral<Uppercase<string>>;
+//=> false
+
+type E = IsStringLiteral<'foo' | 'bar' | 'baz'>;
+//=> true
+
+type F = IsStringLiteral<'sm' | 'md' | 'lg' | `${number}px`>;
+//=> boolean
+```
+
+@example
+```
+import type {IsStringLiteral} from 'type-fest';
+
+type StringLength<S extends string, Counter extends never[] = []> =
+	IsStringLiteral<S> extends true
+		? S extends `${string}${infer Tail}`
+			? StringLength<Tail, [...Counter, never]>
+			: Counter['length']
+		: number; // return `number` for non-literal string types
+
+type L1 = StringLength<'foobar'>;
+//=> 6
+
+type L2 = StringLength<Lowercase<string>>;
+//=> number
+
+type L3 = StringLength<`${number}`>;
+//=> number
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsStringLiteral<S> = IfNotAnyOrNever<S, {
+	ifNot: _IsStringLiteral<CollapseLiterals<UnwrapBrand<S>>>;
+	ifAny: false;
+	ifNever: false;
+}>;
+
+type _IsStringLiteral<S> =
+	// If `S` is an infinite string type (e.g., `on${string}`), `Record<S, never>` produces an index signature,
+	// and since `{}` extends index signatures, the result becomes `false`.
+	S extends string
+		? {} extends Record<S, never>
+			? false
+			: true
+		: false;
+
+export {};

package/source/is-symbol-literal.d.ts

@@ -0,0 +1,39 @@
+import type {CollapseLiterals, UnwrapBrand} from './internal/object.d.ts';
+import type {IfNotAnyOrNever} from './internal/type.d.ts';
+
+/**
+Returns a boolean for whether the given type is a `symbol` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+
+@example
+```
+import type {IsSymbolLiteral} from 'type-fest';
+
+declare const symbolLiteral1: unique symbol;
+declare const symbolLiteral2: unique symbol;
+
+type A = IsSymbolLiteral<typeof symbolLiteral1>;
+//=> true
+
+type B = IsSymbolLiteral<symbol>;
+//=> false
+
+type C = IsSymbolLiteral<typeof symbolLiteral1 | typeof symbolLiteral2>;
+//=> true
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsSymbolLiteral<T> = IfNotAnyOrNever<T, {
+	ifNot: _IsSymbolLiteral<CollapseLiterals<UnwrapBrand<T>>>;
+	ifAny: false;
+	ifNever: false;
+}>;
+
+type _IsSymbolLiteral<T> = T extends symbol
+	? symbol extends T
+		? false
+		: true
+	: false;
+
+export {};

package/source/is-union.d.ts

@@ -21,20 +21,20 @@ 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
+	(
+		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
+		? boolean extends Result ? true
+			: Result
+		: never; // Should never happen
 
 export {};

package/source/iterable-element.d.ts

@@ -57,10 +57,10 @@ type Fruit = IterableElement<typeof fruits>;
 @category Iterable
 */
 export type IterableElement<TargetIterable> =
-	TargetIterable extends Iterable<infer ElementType> ?
-		ElementType :
-		TargetIterable extends AsyncIterable<infer ElementType> ?
-			ElementType :
-			never;
+	TargetIterable extends Iterable<infer ElementType>
+		? ElementType
+		: TargetIterable extends AsyncIterable<infer ElementType>
+			? ElementType
+			: never;
 
 export {};

package/source/jsonify.d.ts

@@ -25,15 +25,11 @@ type JsonifyList<T extends UnknownArray> = T extends readonly []
 			? 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]>;
+	[Key in keyof T as T[Key] extends NotJsonable ? never : Key]: Jsonify<T[Key]>;
 };
 
 /**
@@ -98,13 +94,13 @@ export type Jsonify<T> = IsAny<T> extends true
 		? null
 		: T extends JsonPrimitive
 			? T
-			: // Any object with toJSON is special case
-			T extends {toJSON(): infer J}
+			// 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
+				// Instanced primitives are objects
+				: T extends Number
 					? number
 					: T extends String
 						? string

package/source/kebab-case.d.ts

@@ -15,6 +15,7 @@ import type {KebabCase} from 'type-fest';
 
 const someVariable: KebabCase<'fooBar'> = 'foo-bar';
 const someVariableNoSplitOnNumbers: KebabCase<'p2pNetwork', {splitOnNumbers: false}> = 'p2p-network';
+const someVariableWithPunctuation: KebabCase<'div.card::after', {splitOnPunctuation: true}> = 'div-card-after';
 
 // Advanced
 

package/source/kebab-cased-properties-deep.d.ts

@@ -51,6 +51,13 @@ const splitOnNumbers: KebabCasedPropertiesDeep<{line1: {line2: [{line3: string}]
 		],
 	},
 };
+
+const splitOnPunctuation: KebabCasedPropertiesDeep<{'user@info': {'user::id': number; 'user::name': string}}, {splitOnPunctuation: true}> = {
+	'user-info': {
+		'user-id': 1,
+		'user-name': 'Tom',
+	},
+};
 ```
 
 @category Change case

package/source/kebab-cased-properties.d.ts

@@ -4,7 +4,7 @@ import type {ApplyDefaultOptions} from './internal/index.d.ts';
 import type {WordsOptions} from './words.d.ts';
 
 /**
-Convert object properties to kebab case but not recursively.
+Convert top-level object properties to kebab case.
 
 This can be useful when, for example, converting some API types from a different style.
 
@@ -28,6 +28,10 @@ const result: KebabCasedProperties<User> = {
 const splitOnNumbers: KebabCasedProperties<{line1: string}, {splitOnNumbers: true}> = {
 	'line-1': 'string',
 };
+
+const splitOnPunctuation: KebabCasedProperties<{'foo::bar': string}, {splitOnPunctuation: true}> = {
+	'foo-bar': 'string',
+};
 ```
 
 @category Change case

package/source/keys-of-union.d.ts

@@ -38,7 +38,7 @@ type AllKeys = KeysOfUnion<Union>;
 @category Object
 */
 export type KeysOfUnion<ObjectType> =
-  // Hack to fix https://github.com/sindresorhus/type-fest/issues/1008
-  keyof UnionToIntersection<ObjectType extends unknown ? Record<keyof ObjectType, never> : never>;
+	// Hack to fix https://github.com/sindresorhus/type-fest/issues/1008
+	keyof UnionToIntersection<ObjectType extends unknown ? Record<keyof ObjectType, never> : never>;
 
 export {};