@oscarpalmer/atoms 0.202.0 → 0.204.0

package/dist/index.d.mts

@@ -3,30 +3,12 @@
  * A generic array or object
  */
 export type ArrayOrPlainObject = unknown[] | Record<PropertyKey, unknown>;
-/**
- * An asynchronous callback that can be canceled
- */
-export type AsyncCancelableCallback<Callback extends GenericAsyncCallback | GenericCallback> = (ReturnType<Callback> extends Promise<any> ? (...args: Parameters<Callback>) => Promise<Awaited<ReturnType<Callback>>> : (...args: Parameters<Callback>) => Promise<ReturnType<Callback>>) & {
-  /**
-   * Cancel the callback
-   */
-  cancel: () => void;
-};
 /**
  * For matching any `void`, `Date`, primitive, or `RegExp` values
  *
  * _(Thanks, type-fest!)_
  */
 export type BuiltIns = void | Date | Primitive | RegExp;
-/**
- * A synchronous callback that can be canceled
- */
-export type CancelableCallback<Callback extends GenericCallback> = Callback & {
-  /**
-   * Cancel the callback
-   */
-  cancel: () => void;
-};
 /**
  * A generic class constructor
  */
@@ -93,7 +75,7 @@ export type NumericalValues<Item extends PlainObject> = { [ItemKey in keyof Item
 /**
  * An asynchronous function that can only be called once, returning the same value on subsequent calls
  */
-export type OnceAsyncCallback<Callback extends GenericAsyncCallback> = {
+type OnceAsync<Callback extends GenericAsyncCallback> = {
   /**
    * Did the callback's promise reject?
    */
@@ -102,12 +84,27 @@ export type OnceAsyncCallback<Callback extends GenericAsyncCallback> = {
    * Has the callback finished?
    */
   readonly finished: boolean;
-} & Callback & OnceCallbackProperties;
+  /**
+   * Run the callback
+   *
+   * @param parameters Callback parameters
+   * @returns Call result
+   */
+  run: (...parameters: Parameters<Callback>) => ReturnType<Callback>;
+} & OnceProperties;
 /**
  * A callback function that can only be called once, returning the same value on subsequent calls
  */
-export type OnceCallback<Callback extends GenericCallback> = Callback & OnceCallbackProperties;
-type OnceCallbackProperties = {
+type Once<Callback extends GenericCallback> = {
+  /**
+   * Run the callback
+   *
+   * @param parameters Callback parameters
+   * @returns Call result
+   */
+  run: (...parameters: Parameters<Callback>) => ReturnType<Callback>;
+} & OnceProperties;
+type OnceProperties = {
   /**
    * Has the callback been called?
    */
@@ -2774,13 +2771,6 @@ export type SortDirection = 'ascending' | 'descending';
  * Can be used to sort an array, get the predicted index for an item, and check if an array is sorted
  */
 export type Sorter<Item> = {
-  /**
-   * Sort an array of items
-   *
-   * @param array Array to sort
-   * @returns Sorted array
-   */
-  (array: Item[]): Item[];
   /**
    * Get the index for an item _(to be inserted into an array of items)_
    *
@@ -2798,6 +2788,13 @@ export type Sorter<Item> = {
    * @returns `true` if sorted, otherwise `false`
    */
   is(array: Item[]): boolean;
+  /**
+   * Sort an array of items
+   *
+   * @param array Array to sort
+   * @returns Sorted array
+   */
+  sort(array: Item[]): Item[];
 };
 /**
  * Get the index for an item _(to be inserted into an array of items)_ based on sorters _(and an optional default direction)_
@@ -3332,6 +3329,40 @@ export declare function toRecordArrays<Item, KeyArg extends KeyOrCallback<Item,
  */
 export declare function noop(): void;
 //#endregion
+//#region src/internal/function/limit.d.ts
+/**
+ * An asynchronous function that can be cancelled
+ */
+type AsyncLimiter<Callback extends GenericAsyncCallback> = {
+  /**
+   * Cancel the function
+   */
+  cancel(): void;
+  /**
+   * Call the function
+   *
+   * @param parameters Function parameters
+   * @returns Function result
+   */
+  run(...parameters: Parameters<Callback>): Promise<ReturnType<Callback>>;
+};
+/**
+ * A function that can be cancelled
+ */
+type Limiter<Callback extends GenericCallback> = {
+  /**
+   * Cancel the function
+   */
+  cancel(): void;
+  /**
+   * Call the function
+   *
+   * @param parameters Function parameters
+   * @returns Function result
+   */
+  run(...parameters: Parameters<Callback>): ReturnType<Callback>;
+};
+//#endregion
 //#region src/function/limit.d.ts
 /**
  * Debounce a function, ensuring it is only called after `time` milliseconds have passed
@@ -3345,7 +3376,7 @@ export declare function noop(): void;
  * @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
  * @returns Debounced callback handler with a `cancel` method
  */
-export declare function asyncDebounce<Callback extends GenericAsyncCallback | GenericCallback>(callback: Callback, time?: number): AsyncCancelableCallback<Callback>;
+export declare function asyncDebounce<Callback extends GenericAsyncCallback | GenericCallback>(callback: Callback, time?: number): AsyncLimiter<Callback>;
 /**
  * Throttle a function, ensuring it is only called once every `time` milliseconds
  *
@@ -3358,7 +3389,7 @@ export declare function asyncDebounce<Callback extends GenericAsyncCallback | Ge
  * @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
  * @returns Throttled callback handler with a `cancel` method
  */
-export declare function asyncThrottle<Callback extends GenericAsyncCallback | GenericCallback>(callback: Callback, time?: number): AsyncCancelableCallback<Callback>;
+export declare function asyncThrottle<Callback extends GenericAsyncCallback | GenericCallback>(callback: Callback, time?: number): AsyncLimiter<Callback>;
 /**
  * Debounce a function, ensuring it is only called after `time` milliseconds have passed
  *
@@ -3368,7 +3399,7 @@ export declare function asyncThrottle<Callback extends GenericAsyncCallback | Ge
  * @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
  * @returns Debounced callback handler with a `cancel` method
  */
-export declare function debounce<Callback extends GenericCallback>(callback: Callback, time?: number): CancelableCallback<Callback>;
+export declare function debounce<Callback extends GenericCallback>(callback: Callback, time?: number): Limiter<Callback>;
 export declare namespace debounce {
   var async: typeof asyncDebounce;
 }
@@ -3379,12 +3410,14 @@ export declare namespace debounce {
  * @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
  * @returns Throttled callback handler with a `cancel` method
  */
-export declare function throttle<Callback extends GenericCallback>(callback: Callback, time?: number): CancelableCallback<Callback>;
+export declare function throttle<Callback extends GenericCallback>(callback: Callback, time?: number): Limiter<Callback>;
 export declare namespace throttle {
   var async: typeof asyncThrottle;
 }
 //#endregion
 //#region src/function/once.d.ts
+declare function OnceAsync(this: any, callback: GenericAsyncCallback): void;
+declare function Once(this: any, callback: GenericCallback): void;
 /**
  * Create an asynchronous function that can only be called once, rejecting or resolving the same result on subsequent calls
  *
@@ -3393,16 +3426,35 @@ export declare namespace throttle {
  * @param callback Callback to use once
  * @returns _Once_ callback
  */
-export declare function asyncOnce<Callback extends GenericAsyncCallback>(callback: Callback): OnceAsyncCallback<Callback>;
+export declare function asyncOnce<Callback extends GenericAsyncCallback>(callback: Callback): OnceAsync<Callback>;
+export declare namespace asyncOnce {
+  var is: typeof isAsyncOnce;
+}
+/**
+ * Is the value an asynchronous once callback?
+ *
+ * @param value Value to check
+ * @returns `true` if the value is an asynchronous once callback, otherwise `false`
+ */
+export declare function isAsyncOnce(value: unknown): boolean;
+/**
+ * Is the value a once callback?
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a once callback, otherwise `false`
+ */
+export declare function isOnce(value: unknown): boolean;
 /**
  * Create a function that can only be called once, returning the same value on subsequent calls
  *
  * @param callback Callback to use once
  * @returns _Once_ callback
  */
-export declare function once<Callback extends GenericCallback>(callback: Callback): OnceCallback<Callback>;
+export declare function once<Callback extends GenericCallback>(callback: Callback): Once<Callback>;
 export declare namespace once {
   var async: typeof asyncOnce;
+  var is: typeof isOnce;
+  var isAsync: typeof isAsyncOnce;
 }
 //#endregion
 //#region src/function/retry.d.ts
@@ -3967,7 +4019,7 @@ export declare function assertIs<Value>(condition: (value: unknown) => value is
  * @param error Error constructor _(defaults to `Error`)_
  * @returns _Asserter_
  */
-export declare function assertProperty<Value extends PlainObject, Path extends NestedKeys<Value>, Asserted = NestedPick<Value, Path>>(path: Path, condition: (value: NestedValue<Value, Path>) => boolean, message: string, error?: ErrorConstructor): Asserter<Asserted>;
+export declare function assertProperty<Value extends PlainObject, Path extends NestedKeys<Value>>(path: Path, condition: (value: NestedValue<Value, Path>) => boolean, message: string, error?: ErrorConstructor): Asserter<NestedPick<Value, Path>>;
 //#endregion
 //#region src/internal/function/memoize.d.ts
 /**
@@ -4206,10 +4258,19 @@ type Comparator<Value = any> = (first: Value, second: Value) => number;
 export declare function compare(first: unknown, second: unknown): number;
 export declare namespace compare {
   var deregister: typeof deregisterComparator;
-  var handlers: {
-    deregister(constructor: Constructor): void;
+  var handler: {
+    base: {
+      handlers: WeakMap<WeakKey, string | GenericCallback>;
+      options: {
+        callback: GenericCallback;
+        method?: string;
+      };
+      owner: GenericCallback;
+      deregister: (constructor: Constructor) => void;
+      get: (first: unknown, second: unknown) => string | GenericCallback | undefined;
+      register: (constructor: Constructor, handler?: string | GenericCallback) => void;
+    };
     handle(first: unknown, second: unknown, ...parameters: unknown[]): number;
-    register(constructor: Constructor, handler?: string | GenericCallback): void;
   };
   var register: typeof registerComparator;
 }
@@ -4263,7 +4324,7 @@ type Equalizer = {
    * @param ignoreCase If `true`, comparison will be case-insensitive
    * @returns `true` if the strings are equal, otherwise `false`
    */
-  (first: string, second: string, ignoreCase?: boolean): boolean;
+  compare(first: string, second: string, ignoreCase?: boolean): boolean;
   /**
    * Are two values equal?
    *
@@ -4271,7 +4332,7 @@ type Equalizer = {
    * @param second Second value
    * @returns `true` if the values are equal, otherwise `false`
    */
-  (first: unknown, second: unknown): boolean;
+  compare(first: unknown, second: unknown): boolean;
   /**
    * Deregister a equality comparison handler for a specific class
    *
@@ -4286,6 +4347,17 @@ type Equalizer = {
    */
   register: <Instance>(constructor: Constructor<Instance>, handler: (first: Instance, second: Instance) => boolean) => void;
 };
+type Options = {
+  ignoreCase: boolean;
+  ignoreExpressions: OptionsKeys<RegExp[]>;
+  ignoreKeys: OptionsKeys<Set<string>>;
+  relaxedNullish: boolean;
+};
+type OptionsKeys<Values> = {
+  enabled: boolean;
+  values: Values;
+};
+declare function Equalizer(this: any, options: Options): void;
 /**
  * Deregister a equality comparison handler for a specific class
  *
@@ -4313,12 +4385,21 @@ export declare function equal(first: string, second: string, ignoreCase?: boolea
  */
 export declare function equal(first: unknown, second: unknown, options?: EqualOptions): boolean;
 export declare namespace equal {
-  var handlers: {
-    deregister(constructor: Constructor): void;
+  var deregister: typeof deregisterEqualizer;
+  var handler: {
+    base: {
+      handlers: WeakMap<WeakKey, string | GenericCallback>;
+      options: {
+        callback: GenericCallback;
+        method?: string;
+      };
+      owner: GenericCallback;
+      deregister: (constructor: Constructor) => void;
+      get: (first: unknown, second: unknown) => string | GenericCallback | undefined;
+      register: (constructor: Constructor, handler?: string | GenericCallback) => void;
+    };
     handle(first: unknown, second: unknown, ...parameters: unknown[]): boolean;
-    register(constructor: Constructor, handler?: string | GenericCallback): void;
   };
-  var deregister: typeof deregisterEqualizer;
   var initialize: typeof initializeEqualizer;
   var register: typeof registerEqualizer;
 }
@@ -4515,7 +4596,7 @@ export declare function setValue<Data extends PlainObject, Path extends NestedKe
  */
 export declare function setValue<Data extends PlainObject>(data: Data, path: string, value: unknown, ignoreCase?: boolean): Data;
 //#endregion
-//#region src/internal/abort.d.ts
+//#region src/internal/aborter.d.ts
 type Aborter = {
   callback: GenericCallback;
   signal: AbortSignal;
@@ -4767,9 +4848,14 @@ export declare function error<E>(value: E, original: Error): ExtendedErr<E>;
  * @returns Error result
  */
 export declare function error<E>(value: E): Err<E>;
+export declare namespace error {
+  var is: typeof isError;
+}
 /**
  * Is the _Result_ an extended error?
  *
+ * _Available as `isError` and `error.is`_
+ *
  * @param result _Result_ to check
  * @returns `true` if the _Result_ is an extended error, otherwise `false`
  */
@@ -4777,6 +4863,8 @@ export declare function isError<Value, E = Error>(result: ExtendedErr<E> | Resul
 /**
  * Is the _Result_ an error?
  *
+ * _Available as `isError` and `error.is`_
+ *
  * @param result _Result_ to check
  * @returns `true` if the _Result_ is an error, otherwise `false`
  */
@@ -4784,6 +4872,8 @@ export declare function isError<Value, E = Error>(result: Result<Value, E>): res
 /**
  * Is the value an error?
  *
+ * _Available as `isError` and `error.is`_
+ *
  * @param value Value to check
  * @returns `true` if the value is an error, otherwise `false`
  */
@@ -4791,6 +4881,8 @@ export declare function isError(value: unknown): value is Err<unknown> | Extende
 /**
  * Is the _Result_ ok?
  *
+ * _Available as `isOk` and `ok.is`_
+ *
  * @param value _Result_ to check
  * @returns `true` if the _Result_ is ok, otherwise `false`
  */
@@ -4798,6 +4890,8 @@ export declare function isOk<Value, E = Error>(value: Result<Value, E>): value i
 /**
  * Is the value ok?
  *
+ * _Available as `isOk` and `ok.is`_
+ *
  * @param value Value to check
  * @returns `true` if the value is ok, otherwise `false`
  */
@@ -4816,6 +4910,9 @@ export declare function isResult(value: unknown): value is ExtendedErr<unknown>
  * @returns Ok result
  */
 export declare function ok<Value>(value: Value): Ok<Value>;
+export declare namespace ok {
+  var is: typeof isOk;
+}
 /**
  * Gets the value of an ok result _(or a default value)_
  *
@@ -5488,6 +5585,7 @@ export declare function fuzzy<Item>(items: Item[], handler?: (item: Item) => str
  */
 export declare function fuzzy<Item>(items: Item[], configuration?: FuzzyConfiguration<Item>): Fuzzy<Item>;
 export declare namespace fuzzy {
+  var is: typeof isFuzzy;
   var match: typeof fuzzyMatch;
 }
 /**
@@ -5500,6 +5598,15 @@ export declare namespace fuzzy {
  * @returns `true` if the needle matches the haystack in a fuzzy way, otherwise `false`
  */
 export declare function fuzzyMatch(haystack: string, needle: string): boolean;
+/**
+ * Is the value a fuzzy searcher?
+ *
+ * _Available as `isFuzzy` and `fuzzy.is`_
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a fuzzy searcher, otherwise `false`
+ */
+export declare function isFuzzy<Item = unknown>(value: unknown): value is Fuzzy<Item>;
 //#endregion
 //#region src/string/index.d.ts
 /**
@@ -5620,7 +5727,7 @@ export type Normalizer = {
    * @param value String to normalize
    * @returns Normalized string
    */
-  (value: string): string;
+  normalize(value: string): string;
 };
 /**
  * Deburr a string, removing diacritical marks
@@ -5680,7 +5787,7 @@ type Templater = {
    *
    * @returns Templated string
    */
-  (strings: TemplateStringsArray, ...values: unknown[]): TemplaterRenderer;
+  render(strings: TemplateStringsArray, ...values: unknown[]): TemplaterRenderer;
   /**
    * Render a string from a template with variables
    *
@@ -5688,12 +5795,13 @@ type Templater = {
    * @param variables Variables to use
    * @returns Templated string
    */
-  (value: string, variables?: PlainObject): string;
+  render(value: string, variables?: PlainObject): string;
 };
 /**
  * Render a template string with variables
  */
 type TemplaterRenderer = (variables?: PlainObject) => string;
+declare function Templater(this: any, options: Required<TemplateOptions>): void;
 /**
  * Create a _Templater_ with predefined options
  *
@@ -5743,7 +5851,7 @@ export type Cloner = {
    * @param value Value to clone
    * @returns Cloned value
    */
-  <Value>(value: Value): Value;
+  clone<Value>(value: Value): Value;
   /**
    * Deregister a clone handler for a specific class
    *
@@ -5773,9 +5881,18 @@ export declare function clone<Value>(value: Value, options?: CloneOptions): Valu
 export declare namespace clone {
   var deregister: typeof deregisterCloner;
   var handlers: {
-    deregister(constructor: Constructor): void;
+    base: {
+      handlers: WeakMap<WeakKey, string | GenericCallback>;
+      options: {
+        callback: GenericCallback;
+        method?: string;
+      };
+      owner: GenericCallback;
+      deregister: (constructor: Constructor) => void;
+      get: (first: unknown, second: unknown) => string | GenericCallback | undefined;
+      register: (constructor: Constructor, handler?: string | GenericCallback) => void;
+    };
     handle(value: unknown, ...parameters: unknown[]): unknown;
-    register(constructor: Constructor, handler?: string | GenericCallback): void;
   };
   var initialize: typeof initializeCloner;
   var register: typeof registerCloner;
@@ -6120,7 +6237,7 @@ export type Assigner = {
    * @param from Values to assign
    * @returns Assigned value
    */
-  <To extends PlainObject, From extends PlainObject[]>(to: To, from: [...From]): To & UnionToIntersection<From[number]>;
+  assign<To extends PlainObject, From extends PlainObject[]>(to: To, from: [...From]): To & UnionToIntersection<From[number]>;
 };
 /**
  * Options for merging values
@@ -6165,7 +6282,7 @@ export type Merger = {
    * @param values Values to merge
    * @returns Merged value
    */
-  <Values extends ArrayOrPlainObject[]>(values: Array<NestedPartial<Values[number]>>): UnionToIntersection<Values[number]>;
+  merge<Values extends ArrayOrPlainObject[]>(values: Array<NestedPartial<Values[number]>>): UnionToIntersection<Values[number]>;
 };
 /**
  * Assign values from one or more objects to the first one
@@ -6219,10 +6336,16 @@ type TransformCallback<Value extends PlainObject, Key extends keyof Value> = (ke
  */
 type TransformCallbacks<Value extends PlainObject> = Partial<{ [Key in keyof Value]: (value: Value[Key]) => Value[Key]; }>;
 /**
- * A transformer function for an object, with predefined callbacks for transforming its properties
+ * A transformer for an object, with predefined callbacks for transforming its properties
  */
 export type Transformer<Value extends PlainObject> = {
-  (value: Value): Value;
+  /**
+   * Transform an object's properties
+   *
+   * @param value Object to transform
+   * @returns Transformed object
+   */
+  transform(value: Value): Value;
 };
 /**
  * Initialize a transformer for an object with a transformer function
@@ -7498,12 +7621,12 @@ type Logger = {
    * @param label Label for the logger
    * @returns _TimedLogger_ instance
    */
-  time(label: string): TimedLogger;
+  time(label: string): TimeLogger;
 };
 /**
  * A named timer that can be used to log durations to the console
  */
-type TimedLogger = {
+type TimeLogger = {
   /**
    * Is the timer active? _(i.e. has it been started and not stopped, and is logging enabled?)_
    */
@@ -7519,8 +7642,9 @@ type TimedLogger = {
    */
   get stop(): () => void;
 };
+declare function TimeLogger(this: any, label: string): void;
 declare function isLogger(value: unknown): value is Logger;
-declare function isTimedLogger(value: unknown): value is TimedLogger;
+declare function isTimeLogger(value: unknown): value is TimeLogger;
 /**
  * A logger that can be used to log messages to the console
  *
@@ -8202,4 +8326,4 @@ export declare class SizedSet<Value = unknown> extends Set<Value> {
   get(value: Value, update?: boolean): Value | undefined;
 }
 //#endregion
-export { type Color, type ColorType, type ColorTypeExtended, type ColorValue, type ColorValueExtended, type HSLAColor, type HSLColor, type HWBAColor, type HWBColor, Key$1 as Key, Logger, type RGBAColor, type RGBColor, type Shaken, type Smushed, type Subscription, type SubscriptionParameters, type SubscriptionProperty, type Subscriptions, type SubscriptionsParameters, type TimedLogger, type Unsmushed, toPromise as fromResult, getRandomFloatingNumber as getRandomFloat, isLogger, isTimedLogger };
+export { type AsyncLimiter, type Color, type ColorType, type ColorTypeExtended, type ColorValue, type ColorValueExtended, type HSLAColor, type HSLColor, type HWBAColor, type HWBColor, Key$1 as Key, type Limiter, Logger, Once, OnceAsync, type RGBAColor, type RGBColor, type Shaken, type Smushed, type Subscription, type SubscriptionParameters, type SubscriptionProperty, type Subscriptions, type SubscriptionsParameters, type TimeLogger, type Unsmushed, toPromise as fromResult, getRandomFloatingNumber as getRandomFloat, isLogger, isTimeLogger };