@ts-utilities/core 1.0.12 → 1.2.0

package/dist/index.d.ts

@@ -142,1231 +142,1212 @@ type Hydrate<T> = T extends null ? undefined : T extends (infer U)[] ? Hydrate<U
  */
 declare function hydrate<T>(data: T): Hydrate<T>;
 //#endregion
-//#region src/functions/object.d.ts
-/**
- * Type representing a path split into segments
- * @template S - The original path string type
- */
-type SplitPath<S$1 extends string> = S$1 extends `${infer First}.${infer Rest}` ? [First, ...SplitPath<Rest>] : [S$1];
-/**
- * Recursive type to resolve nested object types based on path
- * @template T - Current object type
- * @template K - Array of path segments
- */
-type GetValue<T, K$1 extends Array<string | number>> = K$1 extends [infer First, ...infer Rest] ? First extends keyof T ? GetValue<T[First], Rest extends Array<string | number> ? Rest : []> : First extends `${number}` ? T extends any[] ? GetValue<T[number], Rest extends Array<string | number> ? Rest : []> : undefined : undefined : T;
+//#region src/types/utilities.d.ts
 /**
- * Get a nested value from an object using array path segments
- * @template T - Object type
- * @template K - Path segments array type
- * @template D - Default value type
- * @param obj - Source object
- * @param path - Array of path segments
- * @param defaultValue - Fallback value if path not found
- * @returns Value at path or default value
+ * 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
- * getObjectValue({a: [{b: 1}]}, ['a', 0, 'b']) // 1
+ * ```ts
+ * type User = { name: string; age: number };
+ * type UserKeys = Keys<User>; // 'name' | 'age'
+ * ```
  */
-declare function getObjectValue<T, K$1 extends Array<string | number>, D>(obj: T, path: K$1, defaultValue: D): Exclude<GetValue<T, K$1>, undefined> | D;
+type Keys<T extends object> = keyof T;
 /**
- * Get a nested value from an object using array path segments
- * @template T - Object type
- * @template K - Path segments array type
- * @param obj - Source object
- * @param path - Array of path segments
- * @returns Value at path or undefined
+ * 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
- * getObjectValue({a: [{b: 1}]}, ['a', 0, 'b']) // 1
+ * ```ts
+ * type User = { name: string; age: number };
+ * type UserValues = Values<User>; // string | number
+ * ```
  */
-declare function getObjectValue<T, K$1 extends Array<string | number>>(obj: T, path: K$1): GetValue<T, K$1> | undefined;
+type Values<T extends object> = T[keyof T];
 /**
- * Get a nested value from an object using dot notation path
- * @template T - Object type
- * @template S - Path string literal type
- * @template D - Default value type
- * @param obj - Source object
- * @param path - Dot-separated path string
- * @param defaultValue - Fallback value if path not found
- * @returns Value at path or default value
+ * 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
- * getObjectValue({a: [{b: 1}]}, 'a.0.b', 2) // 1
+ * ```ts
+ * type Config = {
+ *   server: { host: string; port: number };
+ *   features: string[];
+ * };
+ *
+ * type PartialConfig = DeepPartial<Config>;
+ * // {
+ * //   server?: { host?: string; port?: number };
+ * //   features?: string[];
+ * // }
+ * ```
  */
-declare function getObjectValue<T, S$1 extends string, D>(obj: T, path: S$1, defaultValue: D): Exclude<GetValue<T, SplitPath<S$1>>, undefined> | D;
+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;
 /**
- * Get a nested value from an object using dot notation path
- * @template T - Object type
- * @template S - Path string literal type
- * @param obj - Source object
- * @param path - Dot-separated path string
- * @returns Value at path or undefined
+ * 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
- * getObjectValue({a: [{b: 1}]}, 'a.0.b') // 1
+ * ```ts
+ * type User = { name: string; age: number; email: string };
+ * type PartialUser = SelectivePartial<User, 'age' | 'email'>;
+ * // { name: string; age?: number; email?: string }
+ * ```
  */
-declare function getObjectValue<T, S$1 extends string>(obj: T, path: S$1): GetValue<T, SplitPath<S$1>> | undefined;
+type SelectivePartial<T, K$1 extends keyof T> = Omit<T, K$1> & Partial<Pick<T, K$1>>;
 /**
- * Extend an object or function with additional properties while
- * preserving the original type information.
- *
- * Works with both plain objects and callable functions since
- * functions in JavaScript are objects too. Also handles nullable types.
- *
- * @template T The base object or function type (can be null/undefined)
- * @template P The additional properties type
+ * Makes all properties of an object type required recursively.
  *
- * @param base - The object or function to extend (can be null/undefined)
- * @param props - An object containing properties to attach
+ * This type traverses through nested objects and arrays, making all properties required.
+ * Functions and primitives are left unchanged.
  *
- * @returns The same object/function, augmented with the given properties, or the original value if null/undefined
+ * @template T - The type to make deeply required
+ * @returns A type with all properties required recursively
  *
  * @example
  * ```ts
- * // Extend a plain object
- * const config = extendProps({ apiUrl: '/api' }, { timeout: 5000 });
- * // config has both apiUrl and timeout properties
- *
- * // Extend a function with metadata
- * const fetchData = (url: string) => fetch(url).then(r => r.json());
- * const enhancedFetch = extendProps(fetchData, {
- *   description: 'Data fetching utility',
- *   version: '1.0'
- * });
- * // enhancedFetch is callable and has description/version properties
+ * type PartialConfig = {
+ *   server?: { host?: string; port?: number };
+ * };
  *
- * // Create plugin system
- * const basePlugin = { name: 'base', enabled: true };
- * const authPlugin = extendProps(basePlugin, {
- *   authenticate: (token: string) => validateToken(token)
- * });
+ * 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.
  *
- * // Build configuration objects
- * const defaultSettings = { theme: 'light', lang: 'en' };
- * const userSettings = extendProps(defaultSettings, {
- *   theme: 'dark',
- *   notifications: true
- * });
+ * @template T - The base object type
+ * @template K - The keys to make required
+ * @returns An object type with specified properties required
  *
- * // Handle nullable types (e.g., Supabase Session | null)
- * const session: Session | null = getSession();
- * const extendedSession = extendProps(session, { customProp: 'value' });
- * // extendedSession is (Session & { customProp: string }) | null
+ * @example
+ * ```ts
+ * type PartialUser = { name?: string; age?: number; email?: string };
+ * type RequiredUser = SelectiveRequired<PartialUser, 'name'>;
+ * // { name: string; age?: number; email?: string }
  * ```
  */
-declare function extendProps<T, P$1 extends object>(base: T, props: P$1): T extends null | undefined ? T : T & P$1;
-//#endregion
-//#region src/functions/poll.d.ts
+type SelectiveRequired<T, K$1 extends keyof T> = Omit<T, K$1> & Required<Pick<T, K$1>>;
 /**
- * Repeatedly polls an async `cond` function UNTIL it returns a TRUTHY value,
- * or until the operation times out or is aborted.
- *
- * Designed for waiting on async jobs, external state, or delayed availability.
+ * Creates a type where all properties are never (useful for excluding types).
  *
- * @template T The type of the successful result.
+ * This can be used to create mutually exclusive types or to exclude certain properties.
  *
- * @param cond
- * A function returning a Promise that resolves to:
- *   - a truthy value `T` → stop polling and return it
- *   - falsy/null/undefined → continue polling
+ * @template T - The object type to transform
+ * @returns An object type with all properties set to never
  *
- * @param options
- * Configuration options:
- * - `interval` (number) — Time between polls in ms (default: 5000 ms)
- * - `timeout` (number) — Max total duration before failing (default: 5 min)
- * - `jitter` (boolean) — Add small random offset (±10%) to intervals to avoid sync bursts (default: true)
- * - `signal` (AbortSignal) — Optional abort signal to cancel polling
+ * @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.
  *
- * @returns
- * Resolves with the truthy value `T` when successful.
- * Throws `AbortError` if aborted
+ * @template T - The type to make nullable
+ * @returns A type where all properties can be null
  *
  * @example
  * ```ts
- * // Poll for job completion
- * const job = await poll(async () => {
- *   const status = await getJobStatus();
- *   return status === 'done' ? status : null;
- * }, { interval: 3000, timeout: 60000 });
+ * 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
- * // Wait for API endpoint to be ready
- * const apiReady = await poll(async () => {
- *   try {
- *     await fetch('/api/health');
- *     return true;
- *   } catch {
- *     return null;
- *   }
- * }, { interval: 1000, timeout: 30000 });
+ * 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
- * // Poll with abort signal for cancellation
- * const controller = new AbortController();
- * setTimeout(() => controller.abort(), 10000); // Cancel after 10s
- *
- * try {
- *   const result = await poll(
- *     () => checkExternalService(),
- *     { interval: 2000, signal: controller.signal }
- *   );
- * } catch (err) {
- *   if (err.name === 'AbortError') {
- *     console.log('Polling was cancelled');
- *   }
- * }
+ * 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
- * // Poll for user action completion
- * const userConfirmed = await poll(async () => {
- *   const confirmations = await getPendingConfirmations();
- *   return confirmations.length > 0 ? confirmations[0] : null;
- * }, { interval: 5000, timeout: 300000 }); // 5 min timeout
+ * type User = { name: string; profile: { age: number } };
+ * type MaybeUser = Maybe<User>;
+ * // { name?: string | null | undefined; profile?: { age?: number | null | undefined } | null | undefined }
  * ```
  */
-declare function poll<T>(cond: () => Promise<T | null | false | undefined>, {
-  interval,
-  timeout,
-  jitter,
-  signal
-}?: Partial<{
-  interval: number;
-  timeout: number;
-  signal: AbortSignal;
-  jitter: boolean;
-}>): Promise<T>;
-//#endregion
-//#region src/functions/promise.d.ts
-type AwaitedTuple<T extends readonly (() => Promise<any>)[] | []> = { -readonly [P in keyof T]: Awaited<ReturnType<T[P]>> };
-type ObjectValues<T extends Record<string, () => Promise<any>>> = { [K in keyof T]: Awaited<ReturnType<T[K]>> };
-type ConcurrenceResult<T> = {
-  results: T;
-  errors: Error[];
-  succeeded: number;
-  failed: number;
-  duration: number;
-};
-type ConcurrenceOptions = {
-  concurrency?: number;
-  timeout?: number;
-  signal?: AbortSignal;
-  retry?: number;
-  retryDelay?: number;
-  throwOnFirstError?: boolean;
-  ignoreErrors?: boolean;
-};
-declare function withConcurrency<T extends readonly (() => Promise<any>)[] | []>(tasks: T, options?: ConcurrenceOptions): Promise<ConcurrenceResult<AwaitedTuple<T>>>;
-declare function withConcurrency<T extends Record<string, () => Promise<any>>>(tasks: T, options?: ConcurrenceOptions): Promise<ConcurrenceResult<ObjectValues<T>>>;
-//#endregion
-//#region src/functions/schedule.d.ts
-/**
- * A task function that can be synchronous or asynchronous.
- */
-type Task = () => Promise<void> | void;
-/**
- * Options for configuring the schedule function.
- */
-interface ScheduleOpts {
-  /** Number of retry attempts on failure. Defaults to 0. */
-  retry?: number;
-  /** Delay in milliseconds between retries. Defaults to 0. */
-  delay?: number;
-  /** Maximum time in milliseconds to wait for the task to complete. */
-  timeout?: number;
-}
+type Maybe<T> = T extends object ? { [P in keyof T]?: Nullish<T[P]> } : T | null | undefined;
 /**
- * Runs a function asynchronously in the background without blocking the main thread.
+ * Makes all properties of an object type readonly recursively.
  *
- * Executes the task immediately using setTimeout, with optional retry logic on failure.
- * Useful for non-critical operations like analytics, logging, or background processing.
- * Logs execution time and retry attempts to the console.
+ * This type traverses through nested objects and arrays, making all properties readonly.
+ * Functions and primitives are left unchanged.
  *
- * @param task - The function to execute asynchronously
- * @param options - Configuration options for retries and timing
+ * @template T - The type to make deeply readonly
+ * @returns A type with all properties readonly recursively
  *
  * @example
  * ```ts
- * // Simple background task
- * schedule(() => {
- *   console.log('Background work done');
- * });
+ * type Config = {
+ *   server: { host: string; port: number };
+ *   features: string[];
+ * };
  *
- * // Task with retry on failure
- * schedule(
- *   () => sendAnalytics(),
- *   { retry: 3, delay: 1000 }
- * );
+ * type ReadonlyConfig = DeepReadonly<Config>;
+ * // {
+ * //   readonly server: { readonly host: string; readonly port: number };
+ * //   readonly features: readonly string[];
+ * // }
  * ```
  */
-declare function schedule(task: Task, options?: ScheduleOpts): void;
-//#endregion
-//#region src/functions/shield.d.ts
+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;
 /**
- * A helper to run sync or async operations safely without try/catch.
+ * Removes readonly modifier from all properties of an object type recursively.
  *
- * Returns a tuple `[error, data]`:
- * - `error`: the thrown error (if any), otherwise `null`
- * - `data`: the resolved value (if successful), otherwise `null`
+ * @template T - The readonly type to make mutable
+ * @returns A type with all readonly modifiers removed
  *
  * @example
  * ```ts
- * // Synchronous error handling
- * const [err, value] = shield(() => {
- *   if (Math.random() > 0.5) throw new Error('Random failure');
- *   return 'success';
- * });
- * if (err) {
- *   console.error('Operation failed:', err);
- * } else {
- *   console.log('Result:', value);
- * }
- *
- * // Asynchronous error handling
- * const [asyncErr, result] = await shield(async () => {
- *   const response = await fetch('/api/data');
- *   if (!response.ok) throw new Error('API error');
- *   return response.json();
- * });
- * if (asyncErr) {
- *   console.error('API call failed:', asyncErr);
- * } else {
- *   processData(result);
- * }
+ * 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.
  *
- * // API calls with fallbacks
- * const [fetchErr, data] = await shield(fetchUserData(userId));
- * const userData = fetchErr ? getCachedUserData(userId) : data;
+ * @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
  *
- * // File operations
- * const [fileErr, content] = shield(() => readFileSync('config.json'));
- * if (fileErr) {
- *   console.warn('Could not read config, using defaults');
- *   return defaultConfig;
- * }
+ * @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
- * // In async functions
- * async function safeApiCall() {
- *   const [err, result] = await shield(callExternalAPI());
- *   if (err) {
- *     await logError(err);
- *     return null;
- *   }
- *   return result;
- * }
+ * 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.
  *
- * // In event handlers
- * function handleSubmit(formData) {
- *   const [validationErr, validatedData] = shield(() => validateForm(formData));
- *   if (validationErr) {
- *     showValidationError(validationErr);
- *     return;
- *   }
- *   submitData(validatedData);
- * }
+ * @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 }
  * ```
  */
-declare function shield<T, E = Error>(operation: Promise<T>): Promise<[E | null, T | null]>;
-declare function shield<T, E = Error>(operation: () => T): [E | null, T | null];
-//#endregion
-//#region src/functions/utils-core.d.ts
+type RequiredKeys<T, K$1 extends keyof T> = Omit<T, K$1> & Required<Pick<T, K$1>>;
 /**
- * Converts various case styles (camelCase, PascalCase, kebab-case, snake_case) into readable normal case.
+ * Computes the symmetric difference between two object types.
  *
- * Transforms technical naming conventions into human-readable titles by:
- * - Adding spaces between words
- * - Capitalizing the first letter of each word
- * - Handling common separators (-, _, camelCase boundaries)
+ * Properties that exist in either T or U but not in both.
  *
- * @param inputString - The string to convert (supports camelCase, PascalCase, kebab-case, snake_case).
- * @returns The converted string in normal case (title case).
+ * @template T - First object type
+ * @template U - Second object type
+ * @returns Properties unique to T or U
  *
  * @example
  * ```ts
- * convertToNormalCase('camelCase') // 'Camel Case'
- * convertToNormalCase('kebab-case') // 'Kebab Case'
- * convertToNormalCase('snake_case') // 'Snake Case'
- * convertToNormalCase('PascalCase') // 'Pascal Case'
+ * type A = { x: number; y: string };
+ * type B = { y: string; z: boolean };
+ * type DiffAB = Diff<A, B>; // { x: number; z: boolean }
  * ```
  */
-declare function convertToNormalCase(inputString: string): string;
+type Diff<T, U$1> = Omit<T, keyof U$1> & Omit<U$1, keyof T>;
 /**
- * Converts a string to a URL-friendly slug by trimming, converting to lowercase,
- * replacing diacritics, removing invalid characters, and replacing spaces with hyphens.
- * @param {string} [str] - The input string to convert.
- * @returns {string} The generated slug.
+ * 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
- * convertToSlug("Hello World!"); // "hello-world"
- * convertToSlug("Déjà Vu"); // "deja-vu"
+ * ```ts
+ * type A = { x: number; y: string };
+ * type B = { y: string; z: boolean };
+ * type IntersectionAB = Intersection<A, B>; // { y: string }
+ * ```
  */
-declare const convertToSlug: (str: string) => string;
+type Intersection<T extends object, U$1 extends object> = Pick<T, Extract<keyof T, keyof U$1> & Extract<keyof U$1, keyof T>>;
 /**
- * Pauses execution for the specified time.
+ * Merges two object types, combining their properties.
  *
- * `signal` allows cancelling the sleep via AbortSignal.
+ * @template T - First object type
+ * @template U - Second object type
+ * @returns A merged object type with properties from both
  *
- * @param time - Time in milliseconds to sleep (default is 1000ms)
- * @param signal - Optional AbortSignal to cancel the sleep early
- * @returns - A Promise that resolves after the specified time or when aborted
+ * @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 }
+ * ```
  */
-declare const sleep: (time?: number, signal?: AbortSignal) => Promise<void>;
-type DebouncedFunction<F$1 extends (...args: any[]) => any> = {
-  (...args: Parameters<F$1>): ReturnType<F$1> | undefined;
-  readonly isPending: boolean;
-};
+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>;
 /**
- * Creates a debounced function that delays invoking the provided function until
- * after the specified `wait` time has elapsed since the last invocation.
+ * Subtracts properties of one object type from another.
  *
- * If the `immediate` option is set to `true`, the function will be invoked immediately
- * on the leading edge of the wait interval. Subsequent calls during the wait interval
- * will reset the timer but not invoke the function until the interval elapses again.
+ * @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
  *
- * The returned function includes the `isPending` property to check if the debounce
- * timer is currently active.
+ * @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.
  *
- * @typeParam F - The type of the function to debounce.
- *
- * @param function_ - The function to debounce.
- * @param wait - The number of milliseconds to delay (default is 100ms).
- * @param options - An optional object with the following properties:
- *   - `immediate` (boolean): If `true`, invokes the function on the leading edge
- *     of the wait interval instead of the trailing edge.
- *
- * @returns A debounced version of the provided function, enhanced with the `isPending` property.
+ * Useful for creating mutually exclusive configurations.
  *
- * @throws {TypeError} If the first parameter is not a function.
- * @throws {RangeError} If the `wait` parameter is negative.
+ * @template T - The object type
+ * @returns Either the full object or an empty object with optional properties
  *
  * @example
  * ```ts
- * // Basic debouncing
- * const log = debounce((message: string) => console.log(message), 200);
- * log('Hello'); // Logs "Hello" after 200ms if no other call is made.
- * console.log(log.isPending); // true if the timer is active.
- *
- * // Immediate execution
- * const save = debounce(() => saveToServer(), 500, { immediate: true });
- * save(); // Executes immediately, then waits 500ms for subsequent calls
- *
- * // Check pending state
- * const debouncedSearch = debounce(searchAPI, 300);
- * debouncedSearch('query');
- * if (debouncedSearch.isPending) {
- *   showLoadingIndicator();
- * }
+ * type Config = { host: string; port: number };
+ * type AllOrNoneConfig = AllOrNone<Config>;
+ * // { host: string; port: number } | {}
  * ```
  */
-declare function debounce<F$1 extends (...args: any[]) => any>(function_: F$1, wait?: number, options?: {
-  immediate: boolean;
-}): DebouncedFunction<F$1>;
-type ThrottledFunction<F$1 extends (...args: any[]) => any> = {
-  (...args: Parameters<F$1>): ReturnType<F$1> | undefined;
-  readonly isPending: boolean;
-};
+type AllOrNone<T> = T | { [P in keyof T]?: never };
 /**
- * Creates a throttled function that invokes the provided function at most once
- * every `wait` milliseconds.
- *
- * If the `leading` option is set to `true`, the function will be invoked immediately
- * on the leading edge of the throttle interval. If the `trailing` option is set to `true`,
- * the function will also be invoked at the end of the throttle interval if additional
- * calls were made during the interval.
- *
- * The returned function includes the `isPending` property to check if the throttle
- * timer is currently active.
- *
- * @typeParam F - The type of the function to throttle.
- *
- * @param function_ - The function to throttle.
- * @param wait - The number of milliseconds to wait between invocations (default is 100ms).
- * @param options - An optional object with the following properties:
- *   - `leading` (boolean): If `true`, invokes the function on the leading edge of the interval.
- *   - `trailing` (boolean): If `true`, invokes the function on the trailing edge of the interval.
+ * Represents exactly one property from an object type being present.
  *
- * @returns A throttled version of the provided function, enhanced with the `isPending` property.
+ * Useful for creating discriminated unions or mutually exclusive options.
  *
- * @throws {TypeError} If the first parameter is not a function.
- * @throws {RangeError} If the `wait` parameter is negative.
+ * @template T - The object type
+ * @returns A union where only one property is present at a time
  *
  * @example
  * ```ts
- * // Basic throttling (leading edge by default)
- * const log = throttle((message: string) => console.log(message), 200);
- * log('Hello'); // Logs "Hello" immediately
- * log('World'); // Ignored for 200ms
- * console.log(log.isPending); // true if within throttle window
- *
- * // Trailing edge only
- * const trailingLog = throttle(() => console.log('trailing'), 200, {
- *   leading: false,
- *   trailing: true
- * });
- * trailingLog(); // No immediate execution
- * // After 200ms: logs "trailing"
- *
- * // Both edges
- * const bothLog = throttle(() => console.log('both'), 200, {
- *   leading: true,
- *   trailing: true
- * });
- * bothLog(); // Immediate execution
- * // After 200ms: executes again if called during window
+ * type Action = { type: 'create'; payload: string } | { type: 'update'; id: number };
+ * type OneAction = OneOf<Action>;
+ * // { type: 'create'; payload: string } | { type: 'update'; id: number }
  * ```
  */
-declare function throttle<F$1 extends (...args: any[]) => any>(function_: F$1, wait?: number, options?: {
-  leading?: boolean;
-  trailing?: boolean;
-}): ThrottledFunction<F$1>;
+type OneOf<T> = { [K in keyof T]: Pick<T, K> }[keyof T];
 /**
- * Formats a string by replacing each '%s' placeholder with the corresponding argument.
- *
- * Mimics the basic behavior of C's printf for %s substitution. Supports both
- * variadic arguments and array-based argument passing. Extra placeholders
- * are left as-is, missing arguments result in empty strings.
+ * Represents exactly two properties from an object type being present.
  *
- * @param format - The format string containing '%s' placeholders.
- * @param args - The values to substitute, either as separate arguments or a single array.
- * @returns The formatted string with placeholders replaced by arguments.
+ * @template T - The object type
+ * @returns A union where exactly two properties are present at a time
  *
  * @example
  * ```ts
- * // Basic usage with separate arguments
- * printf("%s love %s", "I", "Bangladesh") // "I love Bangladesh"
- *
- * // Using array of arguments
- * printf("%s love %s", ["I", "Bangladesh"]) // "I love Bangladesh"
- *
- * // Extra placeholders remain unchanged
- * printf("%s %s %s", "Hello", "World") // "Hello World %s"
- *
- * // Missing arguments become empty strings
- * printf("%s and %s", "this") // "this and "
- *
- * // Multiple occurrences
- * printf("%s %s %s", "repeat", "repeat", "repeat") // "repeat repeat repeat"
+ * type Config = { a: number; b: string; c: boolean };
+ * type TwoConfig = TwoOf<Config>;
+ * // { a: number; b: string } | { a: number; c: boolean } | { b: string; c: boolean }
  * ```
  */
-declare function printf(format: string, ...args: unknown[]): string;
+type TwoOf<T> = { [K in keyof T]: { [L in Exclude<keyof T, K>]: Pick<T, K | L> }[Exclude<keyof T, K>] }[keyof T];
 /**
- * Escapes a string for use in a regular expression.
+ * Prettifies a complex type by expanding it for better readability in tooltips.
  *
- * @param str - The string to escape
- * @returns - The escaped string safe for use in RegExp constructor
+ * 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
- * const escapedString = escapeRegExp('Hello, world!');
- * // escapedString === 'Hello\\, world!'
- *
- * const regex = new RegExp(escapeRegExp(userInput));
+ * type Complex = { a: string } & { b: number };
+ * type PrettyComplex = Prettify<Complex>; // Shows as { a: string; b: number }
  * ```
  */
-declare function escapeRegExp(str: string): string;
+type Prettify<T> = T extends infer U ? U extends object ? { [K in keyof U]: U[K] } & {} : U : never;
 /**
- * Normalizes a string by:
- * - Applying Unicode normalization (NFC)
- * - Optionally removing diacritic marks (accents)
- * - Optionally trimming leading/trailing non-alphanumeric characters
- * - Optionally converting to lowercase
+ * Extracts all nested keys of an object type as dot-separated strings.
  *
- * @param str - The string to normalize
- * @param options - Normalization options
- * @param options.lowercase - Whether to convert the result to lowercase (default: true)
- * @param options.removeAccents - Whether to remove diacritic marks like accents (default: true)
- * @param options.removeNonAlphanumeric - Whether to trim non-alphanumeric characters from the edges (default: true)
- * @returns The normalized string
+ * @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
- * normalizeText('Café') // 'cafe'
- * normalizeText('  Hello!  ') // 'hello'
- * normalizeText('José', { removeAccents: false }) // 'josé'
+ * interface 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'
+ *
+ * // For literal arrays with objects (assumes const context):
+ * const obj = { items: [{ id: 1 }, { id: 2 }] };
+ * type ObjPaths = NestedKeyOf<typeof obj>;
+ * // 'items' | `items.${number}` | `items.${number}.id`
  * ```
  */
-declare function normalizeText(str?: string | null, options?: {
-  lowercase?: boolean;
-  removeAccents?: boolean;
-  removeNonAlphanumeric?: boolean;
-}): string;
-//#endregion
-//#region src/types/utilities.d.ts
+type NestedKeyOf<ObjectType extends object, IgnoreKeys extends string = never> = { [Key in keyof ObjectType & string]: Key extends IgnoreKeys ? never : ObjectType[Key] extends readonly (infer U)[] ? U extends object ? ObjectType[Key] extends readonly [any, ...any[]] ? Key | `${Key}.${keyof ObjectType[Key] & `${number}`}` | `${Key}.${keyof ObjectType[Key] & `${number}`}.${NestedKeyOf<U, IgnoreKeys>}` : Key | `${Key}.${number}` | `${Key}.${number}.${NestedKeyOf<U, IgnoreKeys>}` : Key : ObjectType[Key] extends object ? `${Key}` | `${Key}.${NestedKeyOf<ObjectType[Key], IgnoreKeys>}` : `${Key}` }[keyof ObjectType & string];
 /**
- * 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
+ * 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 User = { name: string; age: number };
- * type UserKeys = Keys<User>; // 'name' | 'age'
+ * type A = { x: number; y: string };
+ * type B = { y: string };
+ * type Result = Without<A, B>; // { x?: never }
  * ```
  */
-type Keys<T extends object> = keyof T;
+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>);
 /**
- * Extracts the values of an object type as a union type.
+ * Computes a type-level AND (all must true) for a tuple of types.
  *
- * @template T - The object type to extract values from
- * @returns A union of all values in the object type
+ * Truth table for 3 arguments:
  *
- * @example
- * ```ts
- * type User = { name: string; age: number };
- * type UserValues = Values<User>; // string | number
- * ```
+ * 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 Values<T extends object> = T[keyof T];
+type AND<T extends any[]> = T extends [infer F, ...infer R] ? R extends any[] ? F & AND<R> : F : unknown;
 /**
- * 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.
+ * Computes a type-level OR (At least one) for a tuple of types.
  *
- * @template T - The type to make deeply partial
- * @returns A type with all properties optional recursively
+ * Truth table for 3 arguments:
  *
- * @example
- * ```ts
- * type Config = {
- *   server: { host: string; port: number };
- *   features: string[];
- * };
+ * 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
  *
- * type PartialConfig = DeepPartial<Config>;
- * // {
- * //   server?: { host?: string; port?: number };
- * //   features?: string[];
- * // }
- * ```
+ * @template T - Tuple of boolean-like types (1/0)
  */
-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;
+type OR<T extends any[]> = T extends [infer F, ...infer R] ? R extends any[] ? F | OR<R> : F : never;
 /**
- * Makes only specified properties of an object type optional.
+ * Computes a type-level XOR (only one/odd) for a tuple of types.
  *
- * @template T - The base object type
- * @template K - The keys to make optional
- * @returns An object type with specified properties optional
+ * Truth table for 3 arguments:
  *
- * @example
- * ```ts
- * type User = { name: string; age: number; email: string };
- * type PartialUser = SelectivePartial<User, 'age' | 'email'>;
- * // { name: string; age?: number; email?: string }
- * ```
+ * 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 SelectivePartial<T, K$1 extends keyof T> = Omit<T, K$1> & Partial<Pick<T, K$1>>;
+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;
 /**
- * Makes all properties of an object type required recursively.
+ * Computes a type-level XNOR (All or None true) for a tuple of types.
  *
- * This type traverses through nested objects and arrays, making all properties required.
- * Functions and primitives are left unchanged.
+ * Truth table for 3 arguments:
  *
- * @template T - The type to make deeply required
- * @returns A type with all properties required recursively
+ * 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
  *
- * @example
- * ```ts
- * type PartialConfig = {
- *   server?: { host?: string; port?: number };
- * };
+ * @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.
  *
- * type RequiredConfig = DeepRequired<PartialConfig>;
- * // {
- * //   server: { host: string; port: number };
- * // }
- * ```
+ * 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 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;
+type NOT<T> = { [P in keyof T]?: never };
 /**
- * Makes only specified properties of an object type required.
+ * Computes a type-level NAND for a tuple of types.
  *
- * @template T - The base object type
- * @template K - The keys to make required
- * @returns An object type with specified properties required
+ * Truth table for 3 arguments:
  *
- * @example
- * ```ts
- * type PartialUser = { name?: string; age?: number; email?: string };
- * type RequiredUser = SelectiveRequired<PartialUser, 'name'>;
- * // { name: string; age?: number; email?: string }
- * ```
+ * 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 SelectiveRequired<T, K$1 extends keyof T> = Omit<T, K$1> & Required<Pick<T, K$1>>;
+type NAND<T extends any[]> = NOT<AND<T>>;
 /**
- * Creates a type where all properties are never (useful for excluding types).
+ * Computes a type-level NOR for a tuple of types.
  *
- * This can be used to create mutually exclusive types or to exclude certain properties.
+ * Truth table for 3 arguments:
  *
- * @template T - The object type to transform
- * @returns An object type with all properties set to never
+ * 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
  *
- * @example
- * ```ts
- * type User = { name: string; age: number };
- * type ExcludedUser = Never<User>; // { name: never; age: never }
- * ```
+ * @template T - Tuple of boolean-like types (1/0)
  */
-type Never<T> = { [K in keyof T]: never };
+type NOR<T extends any[]> = NOT<OR<T>>;
+//#endregion
+//#region src/types/guards.d.ts
 /**
- * Makes all properties of an object type nullable recursively.
+ * 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.
  *
- * @template T - The type to make nullable
- * @returns A type where all properties can be null
+ * @param val - The value to check
+ * @returns True if the value is falsy, false otherwise
  *
  * @example
- * ```ts
- * type User = { name: string; profile: { age: number } };
- * type NullableUser = Nullable<User>;
- * // { name: string | null; profile: { age: number | null } | null }
- * ```
+ * if (isFalsy(value)) {
+ *   console.log('Value is falsy');
+ * }
  */
-type Nullable<T> = T extends object ? { [P in keyof T]: Nullable<T[P]> } : T | null;
+declare const isFalsy: (val: unknown) => val is Falsy;
 /**
- * Makes all properties of an object type optional (undefined) recursively.
+ * Type guard that checks if a value is null or undefined.
  *
- * @template T - The type to make optional
- * @returns A type where all properties can be undefined
+ * @param val - The value to check
+ * @returns True if the value is null or undefined, false otherwise
  *
  * @example
- * ```ts
- * type User = { name: string; profile: { age: number } };
- * type OptionalUser = Optional<User>;
- * // { name: string | undefined; profile: { age: number | undefined } | undefined }
- * ```
+ * if (isNullish(value)) {
+ *   console.log('Value is null or undefined');
+ * }
  */
-type Optional<T> = T extends object ? { [P in keyof T]: Optional<T[P]> } : T | undefined;
+declare const isNullish: (val: unknown) => val is null | undefined;
 /**
- * Makes all properties of an object type nullish (null or undefined) recursively.
+ * Type guard that checks if a value is a boolean.
  *
- * @template T - The type to make nullish
- * @returns A type where all properties can be null or undefined
+ * @param val - The value to check
+ * @returns True if the value is a boolean, false otherwise
  *
  * @example
- * ```ts
- * type User = { name: string; profile: { age: number } };
- * type NullishUser = Nullish<User>;
- * // { name: string | null | undefined; profile: { age: number | null | undefined } | null | undefined }
- * ```
+ * if (isBoolean(value)) {
+ *   console.log('Value is a boolean');
+ * }
  */
-type Nullish<T> = T extends object ? { [P in keyof T]: Nullish<T[P]> } : T | null | undefined;
+declare const isBoolean: (val: unknown) => val is boolean;
 /**
- * Makes all properties of an object type optional and nullish recursively.
- *
- * This combines optional properties with nullish values.
+ * Type guard that checks if a value is a string.
  *
- * @template T - The type to make maybe
- * @returns A type where all properties are optional and can be null or undefined
+ * @param val - The value to check
+ * @returns True if the value is a string, false otherwise
  *
  * @example
- * ```ts
- * type User = { name: string; profile: { age: number } };
- * type MaybeUser = Maybe<User>;
- * // { name?: string | null | undefined; profile?: { age?: number | null | undefined } | null | undefined }
- * ```
+ * if (isString(value)) {
+ *   console.log('Value is a string');
+ * }
  */
-type Maybe<T> = T extends object ? { [P in keyof T]?: Nullish<T[P]> } : T | null | undefined;
+declare const isString: (val: unknown) => val is string;
 /**
- * Makes all properties of an object type readonly recursively.
+ * Type guard that checks whether a value is a finite number.
  *
- * This type traverses through nested objects and arrays, making all properties readonly.
- * Functions and primitives are left unchanged.
+ * This excludes `NaN`, `Infinity`, and `-Infinity`.
  *
- * @template T - The type to make deeply readonly
- * @returns A type with all properties readonly recursively
+ * @param val - The value to check
+ * @returns `true` if the value is a finite number
  *
  * @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[];
- * // }
- * ```
+ * isFiniteNumber(42);        // true
+ * isFiniteNumber(NaN);       // false
+ * isFiniteNumber(Infinity); // false
  */
-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;
+declare const isFiniteNumber: (val: unknown) => val is number;
 /**
- * Removes readonly modifier from all properties of an object type recursively.
+ * Type guard that checks if a value is an array.
  *
- * @template T - The readonly type to make mutable
- * @returns A type with all readonly modifiers removed
+ * @param val - The value to check
+ * @returns True if the value is an array, false otherwise
  *
  * @example
- * ```ts
- * type ReadonlyUser = { readonly name: string; readonly profile: { readonly age: number } };
- * type MutableUser = Mutable<ReadonlyUser>;
- * // { name: string; profile: { age: number } }
- * ```
+ * if (isArray(value)) {
+ *   console.log('Value is an array');
+ * }
  */
-type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+declare const isArray: (val: unknown) => val is unknown[];
 /**
- * Extracts keys of an object type that have values of a specific type.
+ * Type guard that checks if a value is a function.
  *
- * @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
+ * @param val - The value to check
+ * @returns True if the value is a function, false otherwise
  *
  * @example
- * ```ts
- * type User = { name: string; age: number; active: boolean };
- * type StringKeys = KeysOfType<User, string>; // 'name'
- * type NumberKeys = KeysOfType<User, number>; // 'age'
- * ```
+ * if (isFunction(value)) {
+ *   console.log('Value is a function');
+ * }
  */
-type KeysOfType<T, U$1> = { [K in keyof T]: T[K] extends U$1 ? K : never }[keyof T];
+declare const isFunction: (val: unknown) => val is Function;
 /**
- * Omits properties from an object type that have values of a specific type.
+ * Type guard that checks if a value is a primitive 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
+ * @param val - The value to check
+ * @returns True if the value is a primitive, false otherwise
  *
  * @example
- * ```ts
- * type Mixed = { name: string; age: number; active: boolean };
- * type WithoutStrings = OmitByType<Mixed, string>; // { age: number; active: boolean }
- * ```
+ * if (isPrimitive(value)) {
+ *   console.log('Value is a primitive type');
+ * }
  */
-type OmitByType<T, U$1> = { [K in keyof T as T[K] extends U$1 ? never : K]: T[K] };
+declare const isPrimitive: (val: unknown) => val is Primitive;
 /**
- * Makes specified properties required while keeping others as-is.
+ * Type guard that checks if a value is a plain object (not an array, function, etc.).
  *
- * @template T - The base object type
- * @template K - The keys to make required
- * @returns An object type with specified properties required
+ * @param value - The value to check
+ * @returns True if the value is a plain object, false otherwise
  *
  * @example
- * ```ts
- * type PartialUser = { name?: string; age?: number; email?: string };
- * type RequiredNameUser = RequiredKeys<PartialUser, 'name'>;
- * // { name: string; age?: number; email?: string }
- * ```
+ * if (isPlainObject(value)) {
+ *   console.log('Value is a plain object');
+ * }
  */
-type RequiredKeys<T, K$1 extends keyof T> = Omit<T, K$1> & Required<Pick<T, K$1>>;
+declare function isPlainObject(value: unknown): value is Record<string, any>;
+//#endregion
+//#region src/functions/object.d.ts
 /**
- * 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 representing a path split into segments
+ * @template S - The original path string type
  */
-type Diff<T, U$1> = Omit<T, keyof U$1> & Omit<U$1, keyof T>;
+type SplitPath<S$1 extends string> = S$1 extends `${infer First}.${infer Rest}` ? [First, ...SplitPath<Rest>] : [S$1];
 /**
- * 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 }
- * ```
+ * Recursive type to resolve nested object types based on path
+ * @template T - Current object type
+ * @template K - Array of path segments
  */
-type Intersection<T extends object, U$1 extends object> = Pick<T, Extract<keyof T, keyof U$1> & Extract<keyof U$1, keyof T>>;
+type GetValue<T, K$1 extends Array<string | number>> = K$1 extends [infer First, ...infer Rest] ? First extends keyof T ? GetValue<T[First], Rest extends Array<string | number> ? Rest : []> : First extends `${number}` ? T extends any[] ? GetValue<T[number], Rest extends Array<string | number> ? Rest : []> : undefined : undefined : 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
+ * Get a nested value from an object using dot notation path
+ * @template T - Object type
+ * @template S - Valid path string type constrained by object structure
+ * @template D - Default value type
+ * @param obj - Source object
+ * @param path - Dot-separated path string (constrained to valid paths)
+ * @param defaultValue - Fallback value if path not found
+ * @returns Value at path or default value
  *
  * @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 }
- * ```
+ * getObjectValue({a: [{b: 1}]}, 'a.0.b', 2) // 1
  */
-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>;
+declare function getObjectValue<const T extends object, S$1 extends NestedKeyOf<T>, D>(obj: T, path: S$1, defaultValue: D): Exclude<GetValue<T, SplitPath<S$1>>, undefined> | D;
 /**
- * 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
+ * Get a nested value from an object using dot notation path
+ * @template T - Object type
+ * @template S - Valid path string type constrained by object structure
+ * @param obj - Source object
+ * @param path - Dot-separated path string (constrained to valid paths)
+ * @returns Value at path or undefined
  *
  * @example
- * ```ts
- * type A = { x: number; y: string; z: boolean };
- * type B = { y: string };
- * type Subtracted = Substract<A, B>; // { x: number; z: boolean }
- * ```
+ * getObjectValue({a: [{b: 1}]}, 'a.0.b') // 1
  */
-type Substract<T extends object, U$1 extends object> = Omit<T, keyof U$1>;
+declare function getObjectValue<const T extends object, S$1 extends NestedKeyOf<T>>(obj: T, path: S$1): GetValue<T, SplitPath<S$1>> | undefined;
 /**
- * Represents either all properties present or none of them.
+ * Extend an object or function with additional properties while
+ * preserving the original type information.
  *
- * Useful for creating mutually exclusive configurations.
+ * Works with both plain objects and callable functions since
+ * functions in JavaScript are objects too. Also handles nullable types.
  *
- * @template T - The object type
- * @returns Either the full object or an empty object with optional properties
+ * @template T The base object or function type (can be null/undefined)
+ * @template P The additional properties type
+ *
+ * @param base - The object or function to extend (can be null/undefined)
+ * @param props - An object containing properties to attach
+ *
+ * @returns The same object/function, augmented with the given properties, or the original value if null/undefined
  *
  * @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.
+ * // Extend a plain object
+ * const config = extendProps({ apiUrl: '/api' }, { timeout: 5000 });
+ * // config has both apiUrl and timeout properties
  *
- * Useful for creating discriminated unions or mutually exclusive options.
+ * // Extend a function with metadata
+ * const fetchData = (url: string) => fetch(url).then(r => r.json());
+ * const enhancedFetch = extendProps(fetchData, {
+ *   description: 'Data fetching utility',
+ *   version: '1.0'
+ * });
+ * // enhancedFetch is callable and has description/version properties
  *
- * @template T - The object type
- * @returns A union where only one property is present at a time
+ * // Create plugin system
+ * const basePlugin = { name: 'base', enabled: true };
+ * const authPlugin = extendProps(basePlugin, {
+ *   authenticate: (token: string) => validateToken(token)
+ * });
  *
- * @example
- * ```ts
- * type Action = { type: 'create'; payload: string } | { type: 'update'; id: number };
- * type OneAction = OneOf<Action>;
- * // { type: 'create'; payload: string } | { type: 'update'; id: number }
+ * // Build configuration objects
+ * const defaultSettings = { theme: 'light', lang: 'en' };
+ * const userSettings = extendProps(defaultSettings, {
+ *   theme: 'dark',
+ *   notifications: true
+ * });
+ *
+ * // Handle nullable types (e.g., Supabase Session | null)
+ * const session: Session | null = getSession();
+ * const extendedSession = extendProps(session, { customProp: 'value' });
+ * // extendedSession is (Session & { customProp: string }) | null
  * ```
  */
-type OneOf<T> = { [K in keyof T]: Pick<T, K> }[keyof T];
+declare function extendProps<T, P$1 extends object>(base: T, props: P$1): T extends null | undefined ? T : T & P$1;
+//#endregion
+//#region src/functions/poll.d.ts
 /**
- * Represents exactly two properties from an object type being present.
+ * Repeatedly polls an async `cond` function UNTIL it returns a TRUTHY value,
+ * or until the operation times out or is aborted.
  *
- * @template T - The object type
- * @returns A union where exactly two properties are present at a time
+ * Designed for waiting on async jobs, external state, or delayed availability.
  *
- * @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.
+ * @template T The type of the successful result.
  *
- * This type doesn't change the runtime type but helps with IntelliSense display.
+ * @param cond
+ * A function returning a Promise that resolves to:
+ *   - a truthy value `T` → stop polling and return it
+ *   - falsy/null/undefined → continue polling
  *
- * @template T - The type to prettify
- * @returns The same type but expanded for better readability
+ * @param options
+ * Configuration options:
+ * - `interval` (number) — Time between polls in ms (default: 5000 ms)
+ * - `timeout` (number) — Max total duration before failing (default: 5 min)
+ * - `jitter` (boolean) — Add small random offset (±10%) to intervals to avoid sync bursts (default: true)
+ * - `signal` (AbortSignal) — Optional abort signal to cancel polling
+ *
+ * @returns
+ * Resolves with the truthy value `T` when successful.
+ * Throws `AbortError` if aborted
  *
  * @example
  * ```ts
- * type Complex = { a: string } & { b: number };
- * type PrettyComplex = Prettify<Complex>; // Shows as { a: string; b: number }
+ * // Poll for job completion
+ * const job = await poll(async () => {
+ *   const status = await getJobStatus();
+ *   return status === 'done' ? status : null;
+ * }, { interval: 3000, timeout: 60000 });
  * ```
- */
-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'
+ * // Wait for API endpoint to be ready
+ * const apiReady = await poll(async () => {
+ *   try {
+ *     await fetch('/api/health');
+ *     return true;
+ *   } catch {
+ *     return null;
+ *   }
+ * }, { interval: 1000, timeout: 30000 });
  * ```
- */
-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.
+ * @example
+ * ```ts
+ * // Poll with abort signal for cancellation
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 10000); // Cancel after 10s
  *
- * @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
+ * try {
+ *   const result = await poll(
+ *     () => checkExternalService(),
+ *     { interval: 2000, signal: controller.signal }
+ *   );
+ * } catch (err) {
+ *   if (err.name === 'AbortError') {
+ *     console.log('Polling was cancelled');
+ *   }
+ * }
+ * ```
  *
  * @example
  * ```ts
- * type A = { x: number; y: string };
- * type B = { y: string };
- * type WithoutB = Without<A, B>; // { x?: never }
+ * // Poll for user action completion
+ * const userConfirmed = await poll(async () => {
+ *   const confirmations = await getPendingConfirmations();
+ *   return confirmations.length > 0 ? confirmations[0] : null;
+ * }, { interval: 5000, timeout: 300000 }); // 5 min timeout
  * ```
  */
-type Without<T, U$1> = { [P in Exclude<keyof T, keyof U$1>]?: never };
+declare function poll<T>(cond: () => Promise<T | null | false | undefined>, {
+  interval,
+  timeout,
+  jitter,
+  signal
+}?: Partial<{
+  interval: number;
+  timeout: number;
+  signal: AbortSignal;
+  jitter: boolean;
+}>): Promise<T>;
 //#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>);
+//#region src/functions/promise.d.ts
+type TaskType<T> = Promise<T> | (() => Promise<T>);
+type AwaitedTuple<T extends readonly TaskType<any>[] | []> = { -readonly [P in keyof T]: Awaited<T[P] extends (() => Promise<infer R>) ? R : T[P]> };
+type ObjectValues<T extends Record<string, TaskType<any>>> = { [K in keyof T]: Awaited<T[K] extends (() => Promise<infer R>) ? R : T[K]> };
+type ConcurrenceResult<T> = {
+  results: T;
+  errors: Error[];
+  succeeded: number;
+  failed: number;
+  duration: number;
+};
+type ConcurrenceOptions = {
+  concurrency?: number;
+  timeout?: number;
+  signal?: AbortSignal;
+  retry?: number;
+  retryDelay?: number;
+  throwOnFirstError?: boolean;
+  ignoreErrors?: boolean;
+};
+declare function withConcurrency<T extends readonly TaskType<any>[] | []>(tasks: T, options?: ConcurrenceOptions): Promise<ConcurrenceResult<AwaitedTuple<T>>>;
+declare function withConcurrency<T extends Record<string, TaskType<any>>>(tasks: T, options?: ConcurrenceOptions): Promise<ConcurrenceResult<ObjectValues<T>>>;
+//#endregion
+//#region src/functions/schedule.d.ts
 /**
- * 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)
+ * A task function that can be synchronous or asynchronous.
  */
-type AND<T extends any[]> = T extends [infer F, ...infer R] ? R extends any[] ? F & AND<R> : F : unknown;
+type Task = () => Promise<void> | void;
 /**
- * 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)
+ * Options for configuring the schedule function.
  */
-type OR<T extends any[]> = T extends [infer F, ...infer R] ? R extends any[] ? F | OR<R> : F : never;
+interface ScheduleOpts {
+  /** Number of retry attempts on failure. Defaults to 0. */
+  retry?: number;
+  /** Delay in milliseconds between retries. Defaults to 0. */
+  delay?: number;
+  /** Maximum time in milliseconds to wait for the task to complete. */
+  timeout?: number;
+}
 /**
- * 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
+ * Runs a function asynchronously in the background without blocking the main thread.
  *
- * @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.
+ * Executes the task immediately using setTimeout, with optional retry logic on failure.
+ * Useful for non-critical operations like analytics, logging, or background processing.
+ * Logs execution time and retry attempts to the console.
  *
- * Truth table for 3 arguments:
+ * @param task - The function to execute asynchronously
+ * @param options - Configuration options for retries and timing
  *
- * 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
+ * @example
+ * ```ts
+ * // Simple background task
+ * schedule(() => {
+ *   console.log('Background work done');
+ * });
  *
- * @template T - Tuple of boolean-like types (1/0)
+ * // Task with retry on failure
+ * schedule(
+ *   () => sendAnalytics(),
+ *   { retry: 3, delay: 1000 }
+ * );
+ * ```
  */
-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;
+declare function schedule(task: Task, options?: ScheduleOpts): void;
+//#endregion
+//#region src/functions/shield.d.ts
 /**
- * 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
+ * A helper to run sync or async operations safely without try/catch.
  *
- * @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.
+ * Returns a tuple `[error, data]`:
+ * - `error`: the thrown error (if any), otherwise `null`
+ * - `data`: the resolved value (if successful), otherwise `null`
  *
- * Truth table for 3 arguments:
+ * @example
+ * ```ts
+ * // Synchronous error handling
+ * const [err, value] = shield(() => {
+ *   if (Math.random() > 0.5) throw new Error('Random failure');
+ *   return 'success';
+ * });
+ * if (err) {
+ *   console.error('Operation failed:', err);
+ * } else {
+ *   console.log('Result:', value);
+ * }
  *
- * 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
+ * // Asynchronous error handling
+ * const [asyncErr, result] = await shield(async () => {
+ *   const response = await fetch('/api/data');
+ *   if (!response.ok) throw new Error('API error');
+ *   return response.json();
+ * });
+ * if (asyncErr) {
+ *   console.error('API call failed:', asyncErr);
+ * } else {
+ *   processData(result);
+ * }
  *
- * @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.
+ * // API calls with fallbacks
+ * const [fetchErr, data] = await shield(fetchUserData(userId));
+ * const userData = fetchErr ? getCachedUserData(userId) : data;
  *
- * Truth table for 3 arguments:
+ * // File operations
+ * const [fileErr, content] = shield(() => readFileSync('config.json'));
+ * if (fileErr) {
+ *   console.warn('Could not read config, using defaults');
+ *   return defaultConfig;
+ * }
+ * ```
  *
- * 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
+ * @example
+ * ```ts
+ * // In async functions
+ * async function safeApiCall() {
+ *   const [err, result] = await shield(callExternalAPI());
+ *   if (err) {
+ *     await logError(err);
+ *     return null;
+ *   }
+ *   return result;
+ * }
  *
- * @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.
+ * // In event handlers
+ * function handleSubmit(formData) {
+ *   const [validationErr, validatedData] = shield(() => validateForm(formData));
+ *   if (validationErr) {
+ *     showValidationError(validationErr);
+ *     return;
+ *   }
+ *   submitData(validatedData);
+ * }
+ * ```
  */
-type Falsy = false | '' | 0 | null | undefined;
+declare function shield<T, E = Error>(operation: Promise<T>): Promise<[E | null, T | null]>;
+declare function shield<T, E = Error>(operation: () => T): [E | null, T | null];
+//#endregion
+//#region src/functions/utils-core.d.ts
 /**
- * Type guard that checks if a value is falsy.
+ * Converts various case styles (camelCase, PascalCase, kebab-case, snake_case) into readable normal case.
  *
- * @param val - The value to check
- * @returns True if the value is falsy, false otherwise
+ * Transforms technical naming conventions into human-readable titles by:
+ * - Adding spaces between words
+ * - Capitalizing the first letter of each word
+ * - Handling common separators (-, _, camelCase boundaries)
+ *
+ * @param inputString - The string to convert (supports camelCase, PascalCase, kebab-case, snake_case).
+ * @returns The converted string in normal case (title case).
  *
  * @example
- * if (isFalsy(value)) {
- *   console.log('Value is falsy');
- * }
+ * ```ts
+ * convertToNormalCase('camelCase') // 'Camel Case'
+ * convertToNormalCase('kebab-case') // 'Kebab Case'
+ * convertToNormalCase('snake_case') // 'Snake Case'
+ * convertToNormalCase('PascalCase') // 'Pascal Case'
+ * ```
  */
-declare const isFalsy: (val: unknown) => val is Falsy;
+declare function convertToNormalCase(inputString: string): string;
 /**
- * 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
- *
+ * Converts a string to a URL-friendly slug by trimming, converting to lowercase,
+ * replacing diacritics, removing invalid characters, and replacing spaces with hyphens.
+ * @param {string} [str] - The input string to convert.
+ * @returns {string} The generated slug.
  * @example
- * if (isNullish(value)) {
- *   console.log('Value is null or undefined');
- * }
+ * convertToSlug("Hello World!"); // "hello-world"
+ * convertToSlug("Déjà Vu"); // "deja-vu"
  */
-declare const isNullish: (val: unknown) => val is null | undefined;
+declare const convertToSlug: (str: string) => string;
 /**
- * Type guard that checks if a value is a boolean.
+ * Pauses execution for the specified time.
  *
- * @param val - The value to check
- * @returns True if the value is a boolean, false otherwise
+ * `signal` allows cancelling the sleep via AbortSignal.
  *
- * @example
- * if (isBoolean(value)) {
- *   console.log('Value is a boolean');
- * }
+ * @param time - Time in milliseconds to sleep (default is 1000ms)
+ * @param signal - Optional AbortSignal to cancel the sleep early
+ * @returns - A Promise that resolves after the specified time or when aborted
  */
-declare const isBoolean: (val: unknown) => val is boolean;
+declare const sleep: (time?: number, signal?: AbortSignal) => Promise<void>;
+type DebouncedFunction<F$1 extends (...args: any[]) => any> = {
+  (...args: Parameters<F$1>): ReturnType<F$1> | undefined;
+  readonly isPending: boolean;
+};
 /**
- * Type guard that checks if a value is a string.
+ * Creates a debounced function that delays invoking the provided function until
+ * after the specified `wait` time has elapsed since the last invocation.
  *
- * @param val - The value to check
- * @returns True if the value is a string, false otherwise
+ * If the `immediate` option is set to `true`, the function will be invoked immediately
+ * on the leading edge of the wait interval. Subsequent calls during the wait interval
+ * will reset the timer but not invoke the function until the interval elapses again.
+ *
+ * The returned function includes the `isPending` property to check if the debounce
+ * timer is currently active.
+ *
+ * @typeParam F - The type of the function to debounce.
+ *
+ * @param function_ - The function to debounce.
+ * @param wait - The number of milliseconds to delay (default is 100ms).
+ * @param options - An optional object with the following properties:
+ *   - `immediate` (boolean): If `true`, invokes the function on the leading edge
+ *     of the wait interval instead of the trailing edge.
+ *
+ * @returns A debounced version of the provided function, enhanced with the `isPending` property.
+ *
+ * @throws {TypeError} If the first parameter is not a function.
+ * @throws {RangeError} If the `wait` parameter is negative.
  *
  * @example
- * if (isString(value)) {
- *   console.log('Value is a string');
+ * ```ts
+ * // Basic debouncing
+ * const log = debounce((message: string) => console.log(message), 200);
+ * log('Hello'); // Logs "Hello" after 200ms if no other call is made.
+ * console.log(log.isPending); // true if the timer is active.
+ *
+ * // Immediate execution
+ * const save = debounce(() => saveToServer(), 500, { immediate: true });
+ * save(); // Executes immediately, then waits 500ms for subsequent calls
+ *
+ * // Check pending state
+ * const debouncedSearch = debounce(searchAPI, 300);
+ * debouncedSearch('query');
+ * if (debouncedSearch.isPending) {
+ *   showLoadingIndicator();
  * }
+ * ```
  */
-declare const isString: (val: unknown) => val is string;
+declare function debounce<F$1 extends (...args: any[]) => any>(function_: F$1, wait?: number, options?: {
+  immediate: boolean;
+}): DebouncedFunction<F$1>;
+type ThrottledFunction<F$1 extends (...args: any[]) => any> = {
+  (...args: Parameters<F$1>): ReturnType<F$1> | undefined;
+  readonly isPending: boolean;
+};
 /**
- * Type guard that checks whether a value is a finite number.
+ * Creates a throttled function that invokes the provided function at most once
+ * every `wait` milliseconds.
  *
- * This excludes `NaN`, `Infinity`, and `-Infinity`.
+ * If the `leading` option is set to `true`, the function will be invoked immediately
+ * on the leading edge of the throttle interval. If the `trailing` option is set to `true`,
+ * the function will also be invoked at the end of the throttle interval if additional
+ * calls were made during the interval.
  *
- * @param val - The value to check
- * @returns `true` if the value is a finite number
+ * The returned function includes the `isPending` property to check if the throttle
+ * timer is currently active.
  *
- * @example
- * isFiniteNumber(42);        // true
- * isFiniteNumber(NaN);       // false
- * isFiniteNumber(Infinity); // false
- */
-declare const isFiniteNumber: (val: unknown) => val is number;
-/**
- * Type guard that checks if a value is an array.
+ * @typeParam F - The type of the function to throttle.
  *
- * @param val - The value to check
- * @returns True if the value is an array, false otherwise
+ * @param function_ - The function to throttle.
+ * @param wait - The number of milliseconds to wait between invocations (default is 100ms).
+ * @param options - An optional object with the following properties:
+ *   - `leading` (boolean): If `true`, invokes the function on the leading edge of the interval.
+ *   - `trailing` (boolean): If `true`, invokes the function on the trailing edge of the interval.
+ *
+ * @returns A throttled version of the provided function, enhanced with the `isPending` property.
+ *
+ * @throws {TypeError} If the first parameter is not a function.
+ * @throws {RangeError} If the `wait` parameter is negative.
  *
  * @example
- * if (isArray(value)) {
- *   console.log('Value is an array');
- * }
+ * ```ts
+ * // Basic throttling (leading edge by default)
+ * const log = throttle((message: string) => console.log(message), 200);
+ * log('Hello'); // Logs "Hello" immediately
+ * log('World'); // Ignored for 200ms
+ * console.log(log.isPending); // true if within throttle window
+ *
+ * // Trailing edge only
+ * const trailingLog = throttle(() => console.log('trailing'), 200, {
+ *   leading: false,
+ *   trailing: true
+ * });
+ * trailingLog(); // No immediate execution
+ * // After 200ms: logs "trailing"
+ *
+ * // Both edges
+ * const bothLog = throttle(() => console.log('both'), 200, {
+ *   leading: true,
+ *   trailing: true
+ * });
+ * bothLog(); // Immediate execution
+ * // After 200ms: executes again if called during window
+ * ```
  */
-declare const isArray: (val: unknown) => val is unknown[];
+declare function throttle<F$1 extends (...args: any[]) => any>(function_: F$1, wait?: number, options?: {
+  leading?: boolean;
+  trailing?: boolean;
+}): ThrottledFunction<F$1>;
 /**
- * Type guard that checks if a value is a function.
+ * Formats a string by replacing each '%s' placeholder with the corresponding argument.
  *
- * @param val - The value to check
- * @returns True if the value is a function, false otherwise
+ * Mimics the basic behavior of C's printf for %s substitution. Supports both
+ * variadic arguments and array-based argument passing. Extra placeholders
+ * are left as-is, missing arguments result in empty strings.
+ *
+ * @param format - The format string containing '%s' placeholders.
+ * @param args - The values to substitute, either as separate arguments or a single array.
+ * @returns The formatted string with placeholders replaced by arguments.
  *
  * @example
- * if (isFunction(value)) {
- *   console.log('Value is a function');
- * }
+ * ```ts
+ * // Basic usage with separate arguments
+ * printf("%s love %s", "I", "Bangladesh") // "I love Bangladesh"
+ *
+ * // Using array of arguments
+ * printf("%s love %s", ["I", "Bangladesh"]) // "I love Bangladesh"
+ *
+ * // Extra placeholders remain unchanged
+ * printf("%s %s %s", "Hello", "World") // "Hello World %s"
+ *
+ * // Missing arguments become empty strings
+ * printf("%s and %s", "this") // "this and "
+ *
+ * // Multiple occurrences
+ * printf("%s %s %s", "repeat", "repeat", "repeat") // "repeat repeat repeat"
+ * ```
  */
-declare const isFunction: (val: unknown) => val is Function;
+declare function printf(format: string, ...args: unknown[]): string;
 /**
- * Type guard that checks if a value is a primitive type.
+ * Escapes a string for use in a regular expression.
  *
- * @param val - The value to check
- * @returns True if the value is a primitive, false otherwise
+ * @param str - The string to escape
+ * @returns - The escaped string safe for use in RegExp constructor
  *
  * @example
- * if (isPrimitive(value)) {
- *   console.log('Value is a primitive type');
- * }
+ * ```ts
+ * const escapedString = escapeRegExp('Hello, world!');
+ * // escapedString === 'Hello\\, world!'
+ *
+ * const regex = new RegExp(escapeRegExp(userInput));
+ * ```
  */
-declare const isPrimitive: (val: unknown) => val is Primitive;
+declare function escapeRegExp(str: string): string;
 /**
- * Type guard that checks if a value is a plain object (not an array, function, etc.).
+ * Normalizes a string by:
+ * - Applying Unicode normalization (NFC)
+ * - Optionally removing diacritic marks (accents)
+ * - Optionally trimming leading/trailing non-alphanumeric characters
+ * - Optionally converting to lowercase
  *
- * @param value - The value to check
- * @returns True if the value is a plain object, false otherwise
+ * @param str - The string to normalize
+ * @param options - Normalization options
+ * @param options.lowercase - Whether to convert the result to lowercase (default: true)
+ * @param options.removeAccents - Whether to remove diacritic marks like accents (default: true)
+ * @param options.removeNonAlphanumeric - Whether to trim non-alphanumeric characters from the edges (default: true)
+ * @returns The normalized string
  *
  * @example
- * if (isPlainObject(value)) {
- *   console.log('Value is a plain object');
- * }
+ * ```ts
+ * normalizeText('Café') // 'cafe'
+ * normalizeText('  Hello!  ') // 'hello'
+ * normalizeText('José', { removeAccents: false }) // 'josé'
+ * ```
  */
-declare function isPlainObject(value: unknown): value is Record<string, any>;
+declare function normalizeText(str?: string | null, options?: {
+  lowercase?: boolean;
+  removeAccents?: boolean;
+  removeNonAlphanumeric?: boolean;
+}): string;
 //#endregion
 export { AND, AllOrNone, BUFFER, ConcurrenceOptions, ConcurrenceResult, DeepMergeOptions, DeepPartial, DeepReadonly, DeepRequired, Diff, Falsy, IMPLIES, Intersection, Keys, KeysOfType, Maybe, Merge, Mutable, NAND, NOR, NOT, NestedKeyOf, Never, Nullable, Nullish, OR, OmitByType, OneOf, Optional, Prettify, Primitive, RequiredKeys, ScheduleOpts, SelectivePartial, SelectiveRequired, Substract, Task, TwoOf, Values, Without, XNOR, XNOR_Binary, XOR, XOR_Binary, convertToNormalCase, convertToSlug, debounce, deepmerge, escapeRegExp, extendProps, getObjectValue, hydrate, isArray, isBoolean, isFalsy, isFiniteNumber, isFunction, isNullish, isPlainObject, isPrimitive, isString, normalizeText, poll, printf, schedule, shield, sleep, throttle, withConcurrency };