es-toolkit 1.51.0-dev.2080 → 1.51.0-dev.2082

package/dist/types/EmptyObject.d.mts

@@ -0,0 +1,21 @@
+//#region src/types/EmptyObject.d.ts
+/**
+ * An object with no properties.
+ *
+ * Pairs with the `isEmptyObject` guard. Assigning an object that has any property
+ * fails, because every value would have to be `never`.
+ *
+ * @example
+ * const a: EmptyObject = {}; // ok
+ * const b: EmptyObject = { a: 1 }; // error
+ *
+ * @example
+ * // Useful for a step that carries no data.
+ * interface StepContext {
+ *   intro: EmptyObject;
+ *   form: { amount: number };
+ * }
+ */
+type EmptyObject = Record<PropertyKey, never>;
+//#endregion
+export { EmptyObject };

package/dist/types/EmptyObject.d.ts

@@ -0,0 +1,21 @@
+//#region src/types/EmptyObject.d.ts
+/**
+ * An object with no properties.
+ *
+ * Pairs with the `isEmptyObject` guard. Assigning an object that has any property
+ * fails, because every value would have to be `never`.
+ *
+ * @example
+ * const a: EmptyObject = {}; // ok
+ * const b: EmptyObject = { a: 1 }; // error
+ *
+ * @example
+ * // Useful for a step that carries no data.
+ * interface StepContext {
+ *   intro: EmptyObject;
+ *   form: { amount: number };
+ * }
+ */
+type EmptyObject = Record<PropertyKey, never>;
+//#endregion
+export { EmptyObject };

package/dist/types/IsEqual.d.mts

@@ -0,0 +1,18 @@
+//#region src/types/IsEqual.d.ts
+/**
+ * Resolves to `true` when `A` and `B` are exactly the same type, `false` otherwise.
+ *
+ * Unlike a plain conditional type, this tells `any` apart from every other type,
+ * which makes it useful for catching an accidental `any` in type-level tests.
+ *
+ * @template A - The first type to compare.
+ * @template B - The second type to compare.
+ *
+ * @example
+ * type A = IsEqual<{ a: string }, { a: string }>; // true
+ * type B = IsEqual<string, 'literal'>;            // false
+ * type C = IsEqual<unknown, any>;                 // false
+ */
+type IsEqual<A, B> = (<G>() => G extends A ? 1 : 2) extends (<G>() => G extends B ? 1 : 2) ? true : false;
+//#endregion
+export { IsEqual };

package/dist/types/IsEqual.d.ts

@@ -0,0 +1,18 @@
+//#region src/types/IsEqual.d.ts
+/**
+ * Resolves to `true` when `A` and `B` are exactly the same type, `false` otherwise.
+ *
+ * Unlike a plain conditional type, this tells `any` apart from every other type,
+ * which makes it useful for catching an accidental `any` in type-level tests.
+ *
+ * @template A - The first type to compare.
+ * @template B - The second type to compare.
+ *
+ * @example
+ * type A = IsEqual<{ a: string }, { a: string }>; // true
+ * type B = IsEqual<string, 'literal'>;            // false
+ * type C = IsEqual<unknown, any>;                 // false
+ */
+type IsEqual<A, B> = (<G>() => G extends A ? 1 : 2) extends (<G>() => G extends B ? 1 : 2) ? true : false;
+//#endregion
+export { IsEqual };

package/dist/types/JsonValue.d.mts

@@ -0,0 +1,24 @@
+//#region src/types/JsonValue.d.ts
+/**
+ * Any value that `JSON.parse` can produce.
+ *
+ * Functions, `Date`, `undefined`, and class instances are excluded, because they
+ * do not survive a JSON round trip.
+ *
+ * @example
+ * declare function parse(text: string): JsonValue;
+ *
+ * const value = parse('{"a":[1,null]}');
+ * if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+ *   const a = value.a; // JsonValue
+ * }
+ *
+ * @example
+ * // Use `Record` when you want to accept a JSON object specifically.
+ * declare function send(body: Record<string, JsonValue>): void;
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+//#endregion
+export { JsonValue };

package/dist/types/JsonValue.d.ts

@@ -0,0 +1,24 @@
+//#region src/types/JsonValue.d.ts
+/**
+ * Any value that `JSON.parse` can produce.
+ *
+ * Functions, `Date`, `undefined`, and class instances are excluded, because they
+ * do not survive a JSON round trip.
+ *
+ * @example
+ * declare function parse(text: string): JsonValue;
+ *
+ * const value = parse('{"a":[1,null]}');
+ * if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+ *   const a = value.a; // JsonValue
+ * }
+ *
+ * @example
+ * // Use `Record` when you want to accept a JSON object specifically.
+ * declare function send(body: Record<string, JsonValue>): void;
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+//#endregion
+export { JsonValue };

package/dist/types/Primitive.d.mts

@@ -0,0 +1,14 @@
+//#region src/types/Primitive.d.ts
+/**
+ * Every primitive value in JavaScript. Anything that is not a primitive is an object.
+ *
+ * Writing this union by hand usually misses `bigint` or `symbol`.
+ *
+ * @example
+ * function isPrimitive(value: unknown): value is Primitive {
+ *   return value === null || (typeof value !== 'object' && typeof value !== 'function');
+ * }
+ */
+type Primitive = string | number | bigint | boolean | symbol | null | undefined;
+//#endregion
+export { Primitive };

package/dist/types/Primitive.d.ts

@@ -0,0 +1,14 @@
+//#region src/types/Primitive.d.ts
+/**
+ * Every primitive value in JavaScript. Anything that is not a primitive is an object.
+ *
+ * Writing this union by hand usually misses `bigint` or `symbol`.
+ *
+ * @example
+ * function isPrimitive(value: unknown): value is Primitive {
+ *   return value === null || (typeof value !== 'object' && typeof value !== 'function');
+ * }
+ */
+type Primitive = string | number | bigint | boolean | symbol | null | undefined;
+//#endregion
+export { Primitive };

package/dist/types/SetOptional.d.mts

@@ -0,0 +1,20 @@
+import { Simplify } from "./Simplify.mjs";
+
+//#region src/types/SetOptional.d.ts
+/**
+ * Makes the given keys `K` of `T` optional, leaving the rest unchanged.
+ * Like the built-in `Partial`, but scoped to specific keys.
+ *
+ * Distributes over unions, so a union stays a union.
+ *
+ * @template T - The object type to transform.
+ * @template K - The keys to make optional.
+ *
+ * @example
+ * type User = { id: number; name: string; email: string };
+ * type UserDraft = SetOptional<User, 'email'>;
+ * // => { id: number; name: string; email?: string }
+ */
+type SetOptional<T, K extends keyof T> = T extends unknown ? Simplify<Omit<T, K> & Partial<Pick<T, K>>> : never;
+//#endregion
+export { SetOptional };

package/dist/types/SetOptional.d.ts

@@ -0,0 +1,20 @@
+import { Simplify } from "./Simplify.js";
+
+//#region src/types/SetOptional.d.ts
+/**
+ * Makes the given keys `K` of `T` optional, leaving the rest unchanged.
+ * Like the built-in `Partial`, but scoped to specific keys.
+ *
+ * Distributes over unions, so a union stays a union.
+ *
+ * @template T - The object type to transform.
+ * @template K - The keys to make optional.
+ *
+ * @example
+ * type User = { id: number; name: string; email: string };
+ * type UserDraft = SetOptional<User, 'email'>;
+ * // => { id: number; name: string; email?: string }
+ */
+type SetOptional<T, K extends keyof T> = T extends unknown ? Simplify<Omit<T, K> & Partial<Pick<T, K>>> : never;
+//#endregion
+export { SetOptional };

package/dist/types/SetRequired.d.mts

@@ -0,0 +1,20 @@
+import { Simplify } from "./Simplify.mjs";
+
+//#region src/types/SetRequired.d.ts
+/**
+ * Makes the given keys `K` of `T` required, leaving the rest unchanged.
+ * Like the built-in `Required`, but scoped to specific keys.
+ *
+ * Distributes over unions, so a union stays a union.
+ *
+ * @template T - The object type to transform.
+ * @template K - The keys to make required.
+ *
+ * @example
+ * type User = { id: number; name: string; avatar?: string };
+ * type ProfileUser = SetRequired<User, 'avatar'>;
+ * // => { id: number; name: string; avatar: string }
+ */
+type SetRequired<T, K extends keyof T> = T extends unknown ? Simplify<T & Required<Pick<T, K>>> : never;
+//#endregion
+export { SetRequired };

package/dist/types/SetRequired.d.ts

@@ -0,0 +1,20 @@
+import { Simplify } from "./Simplify.js";
+
+//#region src/types/SetRequired.d.ts
+/**
+ * Makes the given keys `K` of `T` required, leaving the rest unchanged.
+ * Like the built-in `Required`, but scoped to specific keys.
+ *
+ * Distributes over unions, so a union stays a union.
+ *
+ * @template T - The object type to transform.
+ * @template K - The keys to make required.
+ *
+ * @example
+ * type User = { id: number; name: string; avatar?: string };
+ * type ProfileUser = SetRequired<User, 'avatar'>;
+ * // => { id: number; name: string; avatar: string }
+ */
+type SetRequired<T, K extends keyof T> = T extends unknown ? Simplify<T & Required<Pick<T, K>>> : never;
+//#endregion
+export { SetRequired };

package/dist/types/UnknownRecord.d.mts

@@ -0,0 +1,24 @@
+//#region src/types/UnknownRecord.d.ts
+/**
+ * An object with unknown keys and unknown values.
+ *
+ * Use it instead of `{}`, which accepts every non-nullish value including numbers
+ * and strings. Values are `unknown`, so reading one forces a check first.
+ *
+ * Only types with an index signature are assignable. An `interface` declares its
+ * keys one by one and is rejected, so accept `object` when the caller may pass
+ * one, or spread it at the call site.
+ *
+ * @example
+ * function log(data: UnknownRecord) {
+ *   if (typeof data.id === 'string') {
+ *     console.log(data.id);
+ *   }
+ * }
+ *
+ * log({ id: '1' }); // ok
+ * log(42); // error, while `{}` would have allowed it
+ */
+type UnknownRecord = Record<PropertyKey, unknown>;
+//#endregion
+export { UnknownRecord };

package/dist/types/UnknownRecord.d.ts

@@ -0,0 +1,24 @@
+//#region src/types/UnknownRecord.d.ts
+/**
+ * An object with unknown keys and unknown values.
+ *
+ * Use it instead of `{}`, which accepts every non-nullish value including numbers
+ * and strings. Values are `unknown`, so reading one forces a check first.
+ *
+ * Only types with an index signature are assignable. An `interface` declares its
+ * keys one by one and is rejected, so accept `object` when the caller may pass
+ * one, or spread it at the call site.
+ *
+ * @example
+ * function log(data: UnknownRecord) {
+ *   if (typeof data.id === 'string') {
+ *     console.log(data.id);
+ *   }
+ * }
+ *
+ * log({ id: '1' }); // ok
+ * log(42); // error, while `{}` would have allowed it
+ */
+type UnknownRecord = Record<PropertyKey, unknown>;
+//#endregion
+export { UnknownRecord };

package/dist/types/index.d.mts

@@ -8,7 +8,14 @@ import { ToPascalCaseKeys } from "./ToPascalCaseKeys.mjs";
 import { ToSnakeCaseKeys } from "./ToSnakeCaseKeys.mjs";
 import { DeepPartial } from "./DeepPartial.mjs";
 import { DeepReadonly } from "./DeepReadonly.mjs";
+import { EmptyObject } from "./EmptyObject.mjs";
+import { IsEqual } from "./IsEqual.mjs";
+import { JsonValue } from "./JsonValue.mjs";
 import { NonEmptyArray } from "./NonEmptyArray.mjs";
+import { Primitive } from "./Primitive.mjs";
+import { SetOptional } from "./SetOptional.mjs";
+import { SetRequired } from "./SetRequired.mjs";
+import { UnknownRecord } from "./UnknownRecord.mjs";
 import { ValueOf } from "./ValueOf.mjs";
 import { Writable } from "./Writable.mjs";
-export { type DeepPartial, type DeepReadonly, type Merge, type NonEmptyArray, type ObjectKeys, type Simplify, type ToCamelCaseKeys, type ToConstantCaseKeys, type ToKebabCaseKeys, type ToPascalCaseKeys, type ToSnakeCaseKeys, type ValueOf, type Writable };
+export { type DeepPartial, type DeepReadonly, type EmptyObject, type IsEqual, type JsonValue, type Merge, type NonEmptyArray, type ObjectKeys, type Primitive, type SetOptional, type SetRequired, type Simplify, type ToCamelCaseKeys, type ToConstantCaseKeys, type ToKebabCaseKeys, type ToPascalCaseKeys, type ToSnakeCaseKeys, type UnknownRecord, type ValueOf, type Writable };

package/dist/types/index.d.ts

@@ -8,7 +8,14 @@ import { ToPascalCaseKeys } from "./ToPascalCaseKeys.js";
 import { ToSnakeCaseKeys } from "./ToSnakeCaseKeys.js";
 import { DeepPartial } from "./DeepPartial.js";
 import { DeepReadonly } from "./DeepReadonly.js";
+import { EmptyObject } from "./EmptyObject.js";
+import { IsEqual } from "./IsEqual.js";
+import { JsonValue } from "./JsonValue.js";
 import { NonEmptyArray } from "./NonEmptyArray.js";
+import { Primitive } from "./Primitive.js";
+import { SetOptional } from "./SetOptional.js";
+import { SetRequired } from "./SetRequired.js";
+import { UnknownRecord } from "./UnknownRecord.js";
 import { ValueOf } from "./ValueOf.js";
 import { Writable } from "./Writable.js";
-export { type DeepPartial, type DeepReadonly, type Merge, type NonEmptyArray, type ObjectKeys, type Simplify, type ToCamelCaseKeys, type ToConstantCaseKeys, type ToKebabCaseKeys, type ToPascalCaseKeys, type ToSnakeCaseKeys, type ValueOf, type Writable };
+export { type DeepPartial, type DeepReadonly, type EmptyObject, type IsEqual, type JsonValue, type Merge, type NonEmptyArray, type ObjectKeys, type Primitive, type SetOptional, type SetRequired, type Simplify, type ToCamelCaseKeys, type ToConstantCaseKeys, type ToKebabCaseKeys, type ToPascalCaseKeys, type ToSnakeCaseKeys, type UnknownRecord, type ValueOf, type Writable };

package/dist/util/attempt.d.mts

@@ -38,6 +38,6 @@
  * });
  * ```
  */
-declare function attempt<T, E>(func: () => T): [null, T] | [E, null];
+declare function attempt<T, E = unknown>(func: () => T): [null, T] | [E, null];
 //#endregion
 export { attempt };

package/dist/util/attempt.d.ts

@@ -38,6 +38,6 @@
  * });
  * ```
  */
-declare function attempt<T, E>(func: () => T): [null, T] | [E, null];
+declare function attempt<T, E = unknown>(func: () => T): [null, T] | [E, null];
 //#endregion
 export { attempt };

package/dist/util/attemptAsync.d.mts

@@ -31,6 +31,6 @@
  * });
  * // users is typed as User[]
  */
-declare function attemptAsync<T, E>(func: () => Promise<T>): Promise<[null, T] | [E, null]>;
+declare function attemptAsync<T, E = unknown>(func: () => Promise<T>): Promise<[null, T] | [E, null]>;
 //#endregion
 export { attemptAsync };

package/dist/util/attemptAsync.d.ts

@@ -31,6 +31,6 @@
  * });
  * // users is typed as User[]
  */
-declare function attemptAsync<T, E>(func: () => Promise<T>): Promise<[null, T] | [E, null]>;
+declare function attemptAsync<T, E = unknown>(func: () => Promise<T>): Promise<[null, T] | [E, null]>;
 //#endregion
 export { attemptAsync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-toolkit",
-  "version": "1.51.0-dev.2080+f4e08794",
+  "version": "1.51.0-dev.2082+0949c8b5",
   "description": "A state-of-the-art, high-performance JavaScript utility library with a small bundle size and strong type annotations.",
   "homepage": "https://es-toolkit.dev",
   "bugs": "https://github.com/toss/es-toolkit/issues",