docs: document all remaining utils

Author: unrevised6419

src/array.ts

@@ -30,6 +30,7 @@ export function firstOrSelf<T>(value: Maybe<Arrayable<T>>): Optional<T> {
  *
  * ```ts
  * intersperse(['a', 'b', 'c'], '-'); // ['a', '-', 'b', '-', 'c']
+ * ```
  */
 export function intersperse<T>(array: ReadonlyArray<T>, separator: T): T[] {
 	return [...Array(2 * array.length - 1)].map((_, i) =>

src/date.ts

@@ -1,18 +1,44 @@
 import type { Tagged } from 'type-fest';
 import type { Maybe, Optional } from './types.js';
 
+/**
+ * Represents a valid Date object.
+ * This type is used to ensure that the date is a valid instance of Date and not an invalid date.
+ */
 export type ValidDate = Tagged<Date, 'valid'>;
 
+/**
+ * Checks if a value is a valid Date object.
+ *
+ * ```ts
+ * isValidDate(new Date()); // true
+ * isValidDate(new Date('2023-10-01')); // true
+ * isValidDate(new Date('invalid-date')); // false
+ * isValidDate('2023-10-01'); // false
+ * ```
+ */
 export function isValidDate(date: Date): date is ValidDate {
 	return date instanceof Date && !Number.isNaN(date.getTime());
 }
 
+/**
+ * Gets the date string in ISO format (YYYY-MM-DD) from a Date object or a date-like value.
+ *
+ * ```ts
+ * getDateString(new Date('2023-10-01')); // '2023-10-01'
+ * getDateString('2023-10-01'); // '2023-10-01'
+ * getDateString(1738358400000); // '2023-10-01'
+ * getDateString(new Date('invalid-date')); // undefined
+ * getDateString(null); // undefined
+ * getDateString(undefined); // undefined
+ * ```
+ */
 export function getDateString(date: ValidDate): string;
 export function getDateString(
-	date?: Maybe<Date | string | number>,
+	date: Maybe<Date | string | number>,
 ): Optional<string>;
 export function getDateString(
-	date?: Maybe<Date | string | number>,
+	date: Maybe<Date | string | number>,
 ): Optional<string> {
 	if (date == null) return undefined;
 
@@ -25,12 +51,24 @@ export function getDateString(
 	return date.toISOString().split('T')[0];
 }
 
+/**
+ * Gets the date and time string in ISO format (YYYY-MM-DDTHH:mm:ss) from a Date object or a date-like value.
+ *
+ * ```ts
+ * getDateTimeString(new Date('2023-10-01T12:34:56')); // '2023-10-01T12:34:56'
+ * getDateTimeString('2023-10-01T12:34:56'); // '2023-10-01T12:34:56'
+ * getDateTimeString(1738358400000); // '2023-10-01T00:00:00'
+ * getDateTimeString(new Date('invalid-date')); // undefined
+ * getDateTimeString(null); // undefined
+ * getDateTimeString(undefined); // undefined
+ * ```
+ */
 export function getDateTimeString(date: ValidDate): string;
 export function getDateTimeString(
-	date?: Maybe<Date | string | number>,
+	date: Maybe<Date | string | number>,
 ): Optional<string>;
 export function getDateTimeString(
-	date?: Maybe<Date | string | number>,
+	date: Maybe<Date | string | number>,
 ): Optional<string> {
 	if (date == null) return undefined;
 
@@ -43,12 +81,34 @@ export function getDateTimeString(
 	return date.toISOString().split('.')[0];
 }
 
-export function toDate(value: Maybe<string | number | Date>) {
+/**
+ * Converts a value to a Date object.
+ *
+ * ```ts
+ * toDate('2023-10-01'); // Date object for October 1, 2023
+ * toDate(1738358400000); // Date object for October 1, 2023
+ * toDate(new Date('2023-10-01')); // Date object for October 1, 2023
+ * toDate('invalid-date'); // undefined
+ * toDate(null); // undefined
+ * toDate(undefined); // undefined
+ * ```
+ */
+export function toDate(value: Maybe<string | number | Date>): Date | undefined {
 	if (value == null) return undefined;
 	const date = new Date(value);
 	return Number.isNaN(date.getTime()) ? undefined : date;
 }
 
+/**
+ * Checks if a date is between two other dates (inclusive).
+ *
+ * ```ts
+ * isBetween(new Date('2023-10-01'), new Date('2023-09-01'), new Date('2023-11-01')); // true
+ * isBetween(new Date('2023-10-01'), new Date('2023-10-01'), new Date('2023-10-01')); // true
+ * isBetween(new Date('2023-10-01'), new Date('2023-11-01'), new Date('2023-09-01')); // false
+ * isBetween(new Date('2023-10-01'), new Date('2023-10-02'), new Date('2023-10-02')); // false
+ * ```
+ */
 export function isBetween(date: Date, min: Date, max: Date): boolean {
 	return min <= date && date <= max;
 }
@@ -58,6 +118,18 @@ const defaultOptions: Intl.DateTimeFormatOptions = {
 	timeStyle: 'short',
 };
 
+/**
+ * Formats a date into a string using the specified locales and options.
+ *
+ * ```ts
+ * formatDate(new Date('2023-10-01'), { locales: 'en-US', options: { dateStyle: 'full' } }); // "Sunday, October 1, 2023"
+ * formatDate('2023-10-01', { locales: 'fr-FR', options: { dateStyle: 'long' } }); // "1 octobre 2023"
+ * formatDate(1738358400000, { locales: 'de-DE', options: { timeStyle: 'short' } }); // "01.10.2023, 00:00"
+ * formatDate(new Date('invalid-date')); // "Invalid Date"
+ * formatDate(null); // undefined
+ * formatDate(undefined); // undefined
+ * ```
+ */
 export function formatDate(
 	date: Maybe<string | number | Date>,
 	params?: {

src/function.ts

@@ -1,21 +1,85 @@
+/**
+ * No operation function.
+ * This is a utility function that does nothing when called. It can be used as a placeholder
+ * or default callback when no action is needed.
+ *
+ * ```ts
+ * noop(); // Does nothing
+ * ```
+ *
+ * @deprecated Use `noop` from `es-toolkit` instead.
+ */
 export function noop() {}
 
+/**
+ * Returns the input value.
+ * This is a utility function that can be used as a default callback or placeholder
+ * when no transformation is needed. It simply returns the value passed to it.
+ *
+ * ```ts
+ * const value = 42;
+ * const result = identity(value);
+ * console.log(result); // 42
+ * ```
+ *
+ * @deprecated Use `identity` from `es-toolkit` instead.
+ */
 export function identity<T>(value: T): T {
 	return value;
 }
 
+/**
+ * Returns false.
+ * This is a utility function that can be used as a default callback or placeholder
+ * when a false value is needed. It simply returns `false`.
+ *
+ * ```ts
+ * const result = falseFn();
+ * console.log(result); // false
+ * ```
+ */
 export function falseFn() {
 	return false;
 }
 
+/**
+ * Returns true.
+ * This is a utility function that can be used as a default callback or placeholder
+ * when a true value is needed. It simply returns `true`.
+ *
+ * ```ts
+ * const result = trueFn();
+ * console.log(result); // true
+ * ```
+ */
 export function trueFn() {
 	return true;
 }
 
+/**
+ * Returns null.
+ * This is a utility function that can be used as a default callback or placeholder
+ * when a null value is needed. It simply returns `null`.
+ *
+ * ```ts
+ * const result = nullFn();
+ * console.log(result); // null
+ * ```
+ */
 export function nullFn() {
 	return null;
 }
 
+/**
+ * Returns undefined.
+ * This is a utility function that can be used as a default callback or placeholder
+ * when an undefined value is needed. It simply returns `undefined`.
+ *
+ * ```ts
+ * const result = undefinedFn();
+ * console.log(result); // undefined
+ * ```
+ */
 export function undefinedFn() {
 	return undefined;
 }

src/promise.ts

@@ -1,15 +1,62 @@
+/**
+ * Checks if a promise result is rejected.
+ * Can be used as a type guard to narrow the type of the result to `PromiseRejectedResult`.
+ *
+ * ```ts
+ * const rejected = new Promise((_, reject) => setTimeout(() => reject(new Error('fail')), 1000));
+ * const result = await settled(rejected);
+ * console.log(isRejected(result)); // true
+ *
+ * const results = await Promise.allSettled([
+ *   Promise.resolve('done'),
+ *   Promise.reject(new Error('fail')),
+ * ]);
+ * console.log(results.filter(isRejected)); // [{ status: 'rejected', reason: Error('fail') }]
+ * console.log(results.filter(isFulfilled)); // [{ status: 'fulfilled', value: 'done' }]
+ * ```
+ */
 export function isRejected<T>(
 	result: PromiseSettledResult<T>,
 ): result is PromiseRejectedResult {
 	return result.status === 'rejected';
 }
 
+/**
+ * Checks if a promise result is fulfilled.
+ * Can be used as a type guard to narrow the type of the result to `PromiseFulfilledResult`.
+ *
+ * ```ts
+ * const fulfilled = new Promise((resolve) => setTimeout(() => resolve('done'), 1000));
+ * const result = await settled(fulfilled);
+ * console.log(isFulfilled(result)); // true
+ *
+ * const results = await Promise.allSettled([
+ *   Promise.resolve('done'),
+ *   Promise.reject(new Error('fail')),
+ * ]);
+ * console.log(results.filter(isFulfilled)); // [{ status: 'fulfilled', value: 'done' }]
+ * console.log(results.filter(isRejected)); // [{ status: 'rejected', reason: Error('fail') }]
+ * ```
+ */
 export function isFulfilled<T>(
 	result: PromiseSettledResult<T>,
 ): result is PromiseFulfilledResult<T> {
 	return result.status === 'fulfilled';
 }
 
+/**
+ * Returns the first settled result of a promise.
+ *
+ * ```ts
+ * const fulfilled = new Promise((resolve) => setTimeout(() => resolve('done'), 1000));
+ * const result = await settled(fulfilled);
+ * console.log(result); // { status: 'fulfilled', value: 'done' }
+ *
+ * const rejected = new Promise((_, reject) => setTimeout(() => reject(new Error('fail')), 1000));
+ * const result = await settled(rejected);
+ * console.log(result); // { status: 'rejected', reason: Error('fail') }
+ * ```
+ */
 export async function settled<T>(
 	promise: Promise<T>,
 ): Promise<PromiseSettledResult<T>> {
@@ -29,6 +76,17 @@ export type Failure<E> = [null, E] & {
 
 export type Result<T, E = Error> = Success<T> | Failure<E>;
 
+/**
+ * Tries to resolve a promise and returns a result tuple.
+ * Similar to {@link settled}, but returns a tuple with the data and error.
+ *
+ * ```ts
+ * const result = await tryCatch(Promise.resolve('success'));
+ * console.log(result); // ['success', null]
+ * const errorResult = await tryCatch(Promise.reject(new Error('fail')));
+ * console.log(errorResult); // [null, Error('fail')]
+ * ```
+ */
 export async function tryCatch<T, E = Error>(
 	promise: Promise<T>,
 ): Promise<Result<T, E>> {

src/types.ts

@@ -1,3 +1,6 @@
+/**
+ * Strictly omits keys from an object type.
+ */
 export type StrictOmit<T, K extends keyof T> = Omit<T, K>;
 
 export type Optional<T> = T | undefined;
@@ -29,6 +32,9 @@ export type Choice<T extends ID = ID> = {
 	children?: ReadonlyArray<Choice<T>>;
 };
 
+/**
+ * A read-only array type that ensures all elements are read-only.
+ */
 export type ReadonlyArrayStrict<T> = ReadonlyArray<Readonly<T>>;
 
 export type DeepWriteable<T> = {

src/utils.ts

@@ -1,10 +1,42 @@
+/**
+ * Utility functions for type checking in JavaScript.
+ * These functions help determine the type of a value at runtime.
+ *
+ * ```ts
+ * isType('hello', 'string'); // true
+ * isType(42, 'number'); // true
+ * isType(true, 'boolean'); // true
+ * isType([], 'array'); // true
+ * isType({}, 'object'); // true
+ * isType(null, 'null'); // true
+ * isType(undefined, 'undefined'); // true
+ */
 export function isType<T extends keyof TypeMap>(
 	value: unknown,
 	type: T,
 ): value is TypeMap[T] {
 	return getType(value) === type;
 }
 
+/**
+ * Returns the type of a value as a string.
+ * This function uses `Object.prototype.toString` to determine the type of the value.
+ * It returns a lowercase string representing the type, such as "string", "number", "boolean", etc.
+ *
+ * ```ts
+ * getType('hello'); // 'string'
+ * getType(42); // 'number'
+ * getType(true); // 'boolean'
+ * getType([]); // 'array'
+ * getType({}); // 'object'
+ * getType(null); // 'null'
+ * getType(undefined); // 'undefined'
+ * getType(new Date()); // 'date'
+ * getType(/regex/); // 'regexp'
+ * getType(new Map()); // 'map'
+ * getType(new Set()); // 'set'
+ * getType(new Promise(() => {})); // 'promise'
+ */
 export function getType(value: unknown): keyof TypeMap | (string & {}) {
 	const s = Object.prototype.toString.call(value);
 	return s.slice(8, -1).toLowerCase();