@oscarpalmer/atoms 0.213.0 → 0.214.0

package/dist/models/promise.model.d.mts

@@ -0,0 +1,119 @@
+import { ArrayOrPlainObject, GenericCallback, Key } from "./index.mjs";
+import { Aborter } from "./aborter.model.mjs";
+import { Result } from "./result.model.mjs";
+//#region src/models/promise.model.d.ts
+/**
+ * A _Promise_ that can be canceled
+ */
+export declare class CancelablePromise<Value = void> extends Promise<Value> {
+  #private;
+  constructor(executor: (resolve: (value: Value) => void, reject: (reason: unknown) => void) => void);
+  /**
+   * Cancel the _Promise_, rejecting it with an optional reason
+   *
+   * @param reason Optional reason for canceling the _Promise_
+   */
+  cancel(reason?: unknown): void;
+}
+/**
+ * A _Promise_ that was fulfilled
+ */
+export type FulfilledPromise<Value> = {
+  /**
+   * Status of the _Promise_
+   */
+  status: typeof PROMISE_TYPE_FULFILLED;
+  /**
+   * Value of the _Promise_
+   */
+  value: Awaited<Value>;
+};
+export type PromiseData = {
+  last: number;
+  result: ArrayOrPlainObject;
+};
+export type PromiseHandlers = {
+  resolve(value: unknown[]): void;
+  reject(reason: unknown): void;
+};
+/**
+ * Options for a _Promise_-handling function
+ */
+export type PromiseOptions = {
+  /**
+   * AbortSignal for aborting the _Promise_; when aborted, the _Promise_ will reject with the reason of the signal
+   */
+  signal?: AbortSignal;
+  /**
+   * How long to wait for _(in milliseconds; defaults to `0`)_
+   */
+  time?: number;
+};
+export type PromiseParameters = {
+  aborter?: Aborter;
+  complete: boolean;
+  data: PromiseData;
+  handlers: PromiseHandlers;
+  index: number;
+  key: Key;
+  value?: unknown;
+};
+/**
+ * _Promise_ handling strategy
+ *
+ * - `complete`: wait for all _Promises_ to settle, then return the results, as an array of fulfilled and/or rejected results
+ * - `first`: rejects on the first rejected _Promise_, and returns an array of values
+ */
+export type PromiseStrategy = "complete" | "first";
+/**
+ * An error thrown when a promise times out
+ */
+export declare class PromiseTimeoutError extends Error {
+  constructor();
+}
+export type PromisesItems<Items extends ArrayOrPlainObject> = { [ItemsKey in keyof Items]: Items[ItemsKey] extends GenericCallback ? ReturnType<Items[ItemsKey]> extends Promise<infer Value> ? Promise<Value> : never : Items[ItemsKey] extends Promise<infer Value> ? Promise<Value> : Promise<Items[ItemsKey]>; };
+/**
+ * Options for handling multiple _Promises_
+ */
+export type PromisesOptions = {
+  /**
+   * AbortSignal for aborting the _Promises_; when aborted, the _Promises_ will reject with the reason of the signal
+   */
+  signal?: AbortSignal;
+  /**
+   * Strategy for handling the _Promises_; defaults to `complete`
+   */
+  strategy?: PromiseStrategy;
+};
+export type PromisesResult<Items extends ArrayOrPlainObject> = { [ItemsKey in keyof Items]: Items[ItemsKey] extends Promise<infer Value> ? Result<Awaited<Value>> : never; };
+export type PromisesUnwrapped<Items extends ArrayOrPlainObject> = { [ItemsKey in keyof Items]: Items[ItemsKey] extends GenericCallback ? ReturnType<Items[ItemsKey]> extends Promise<infer Value> ? Awaited<Value> : never : Items[ItemsKey] extends Promise<infer Value> ? Awaited<Value> : never; } extends (infer Result) ? Result : never;
+export type PromisesValue<Value> = FulfilledPromise<Value> | RejectedPromise;
+export type PromisesValues<Items extends ArrayOrPlainObject> = { [ItemsKey in keyof Items]: Items[ItemsKey] extends Promise<infer Value> ? PromisesValue<Awaited<Value>> : never; } extends (infer Result) ? Result : never;
+/**
+ * A _Promise_ that was rejected
+ */
+export type RejectedPromise = {
+  /**
+   * Status of the _Promise_
+   */
+  status: typeof PROMISE_TYPE_REJECTED;
+  /**
+   * Reason for the rejection
+   */
+  reason: unknown;
+};
+export declare const PROMISE_ABORT_EVENT = "abort";
+export declare const PROMISE_ABORT_OPTIONS: {
+  once: boolean;
+};
+export declare const PROMISE_ERROR_NAME = "PromiseTimeoutError";
+export declare const PROMISE_MESSAGE_EXPECTATION_ATTEMPT = "Attempt expected a function or a promise";
+export declare const PROMISE_MESSAGE_EXPECTATION_ITEMS_TYPE = "promises expected an array or object holding promise-functions or promises";
+export declare const PROMISE_MESSAGE_EXPECTATION_RESULT = "toResult expected a Promise";
+export declare const PROMISE_MESSAGE_EXPECTATION_TIMED = "Timed function expected a Promise";
+export declare const PROMISE_MESSAGE_TIMEOUT = "Promise timed out";
+export declare const PROMISE_STRATEGY_ALL: Set<PromiseStrategy>;
+export declare const PROMISE_STRATEGY_DEFAULT: PromiseStrategy;
+export declare const PROMISE_TYPE_FULFILLED = "fulfilled";
+export declare const PROMISE_TYPE_REJECTED = "rejected";
+//#endregion

package/dist/models/promise.model.mjs

@@ -0,0 +1,47 @@
+//#region src/models/promise.model.ts
+/**
+* A _Promise_ that can be canceled
+*/
+var CancelablePromise = class extends Promise {
+	#rejector;
+	constructor(executor) {
+		let rejector;
+		super((resolve, reject) => {
+			rejector = reject;
+			executor(resolve, reject);
+		});
+		this.#rejector = rejector;
+	}
+	/**
+	* Cancel the _Promise_, rejecting it with an optional reason
+	*
+	* @param reason Optional reason for canceling the _Promise_
+	*/
+	cancel(reason) {
+		this.#rejector?.(reason);
+		this.#rejector = void 0;
+	}
+};
+/**
+* An error thrown when a promise times out
+*/
+var PromiseTimeoutError = class extends Error {
+	constructor() {
+		super(PROMISE_MESSAGE_TIMEOUT);
+		this.name = PROMISE_ERROR_NAME;
+	}
+};
+const PROMISE_ABORT_EVENT = "abort";
+const PROMISE_ABORT_OPTIONS = { once: true };
+const PROMISE_ERROR_NAME = "PromiseTimeoutError";
+const PROMISE_MESSAGE_EXPECTATION_ATTEMPT = "Attempt expected a function or a promise";
+const PROMISE_MESSAGE_EXPECTATION_ITEMS_TYPE = "promises expected an array or object holding promise-functions or promises";
+const PROMISE_MESSAGE_EXPECTATION_RESULT = "toResult expected a Promise";
+const PROMISE_MESSAGE_EXPECTATION_TIMED = "Timed function expected a Promise";
+const PROMISE_MESSAGE_TIMEOUT = "Promise timed out";
+const PROMISE_STRATEGY_ALL = /* @__PURE__ */ new Set(["complete", "first"]);
+const PROMISE_STRATEGY_DEFAULT = "complete";
+const PROMISE_TYPE_FULFILLED = "fulfilled";
+const PROMISE_TYPE_REJECTED = "rejected";
+//#endregion
+export { CancelablePromise, PROMISE_ABORT_EVENT, PROMISE_ABORT_OPTIONS, PROMISE_ERROR_NAME, PROMISE_MESSAGE_EXPECTATION_ATTEMPT, PROMISE_MESSAGE_EXPECTATION_ITEMS_TYPE, PROMISE_MESSAGE_EXPECTATION_RESULT, PROMISE_MESSAGE_EXPECTATION_TIMED, PROMISE_MESSAGE_TIMEOUT, PROMISE_STRATEGY_ALL, PROMISE_STRATEGY_DEFAULT, PROMISE_TYPE_FULFILLED, PROMISE_TYPE_REJECTED, PromiseTimeoutError };

package/dist/models/query.model.d.mts

@@ -0,0 +1,9 @@
+//#region src/models/query.model.d.ts
+export declare const QUERY_AMPERSAND = "&";
+export declare const QUERY_DOT = ".";
+export declare const QUERY_EQUAL = "=";
+export declare const QUERY_EXPRESSION_ARRAY_SUFFIX: RegExp;
+export declare const QUERY_EXPRESSION_BOOLEAN: RegExp;
+export declare const QUERY_TRUE = "true";
+export declare const QUERY_TYPES: Set<string>;
+//#endregion

package/dist/models/query.model.mjs

@@ -0,0 +1,14 @@
+//#region src/models/query.model.ts
+const QUERY_AMPERSAND = "&";
+const QUERY_DOT = ".";
+const QUERY_EQUAL = "=";
+const QUERY_EXPRESSION_ARRAY_SUFFIX = /\[\]$/;
+const QUERY_EXPRESSION_BOOLEAN = /^(false|true)$/;
+const QUERY_TRUE = "true";
+const QUERY_TYPES = /* @__PURE__ */ new Set([
+	"boolean",
+	"number",
+	"string"
+]);
+//#endregion
+export { QUERY_AMPERSAND, QUERY_DOT, QUERY_EQUAL, QUERY_EXPRESSION_ARRAY_SUFFIX, QUERY_EXPRESSION_BOOLEAN, QUERY_TRUE, QUERY_TYPES };

package/dist/models/queue.model.d.mts

@@ -0,0 +1,251 @@
+import { GenericAsyncCallback, GenericCallback } from "./index.mjs";
+import { Aborter } from "./aborter.model.mjs";
+//#region src/models/queue.model.d.ts
+export type InternalKeyedQueue = {
+  [QUEUE_SYMBOL]: KeyedQueueState;
+} & KeyedQueue<GenericAsyncCallback, unknown[]>;
+export type InternalQueue = {
+  [QUEUE_SYMBOL]: QueueState;
+} & Queue<GenericAsyncCallback, unknown[]>;
+/**
+ * A queue that can be used to manage (a)synchronous tasks with a specific key
+ */
+export type KeyedQueue<Callback extends GenericCallback | GenericAsyncCallback, CallbackParameters extends unknown[] = Parameters<Callback>> = {
+  /**
+   * Get keys of all active queues
+   */
+  get active(): string[];
+  /**
+   * Does the queue automatically start when the first item is added?
+   */
+  get autostart(): boolean;
+  /**
+   * Maximum number of runners to process the queue concurrently
+   */
+  get concurrency(): number;
+  /**
+   * Get keys of all empty queues
+   */
+  get empty(): string[];
+  /**
+   * Get keys of all full queues
+   */
+  get full(): string[];
+  /**
+   * Number of items in all queues
+   */
+  get items(): Record<string, number>;
+  /**
+   * Keys of all queues
+   */
+  get keys(): string[];
+  /**
+   * Maximum number of items allowed in the queue
+   */
+  get maximum(): number;
+  /**
+   * Are all queues paused?
+   */
+  get paused(): string[];
+  /**
+   * Number of queues
+   */
+  get queues(): number;
+  /**
+   * Queue an item for a specific key
+   *
+   * @param key Key to queue the item for
+   * @param parameters Parameters to use when item runs
+   * @param signal Optional signal to abort the item
+   * @returns Queued item
+   */
+  add(key: string, parameters: Tail<CallbackParameters>, signal?: AbortSignal): Queued<ReturnType<Callback>>;
+  /**
+   * Clear all items for a specific key _(or all items for all keys, if no key is provided)_
+   *
+   * @param key Optional key to clear the queue for
+   */
+  clear(key?: string): void;
+  /**
+   * Get the queue for a specific key
+   *
+   * @param key Key to get the queue for
+   * @returns Queue for the key, or `undefined` if it doesn't exist
+   */
+  get(key: string): Queue<Callback, Tail<CallbackParameters>> | undefined;
+  /**
+   * Pause the queue for a specific key _(or all queues, if no key is provided)_
+   *
+   * @param key Optional key to pause the queue for
+   */
+  pause(key?: string): void;
+  /**
+   * Remove a specific item for a specific key
+   *
+   * @param key Key to remove the item for
+   * @param id ID of the item to remove
+   */
+  remove(key: string, id: number): void;
+  /**
+   * Remove a queue and its items for a specific key
+   *
+   * _(To remove all items for a specific key, use `clear()` instead)_
+   *
+   * @param key Key to remove the queue for
+   */
+  remove(key: string): void;
+  /**
+   * Remove all queues and their items
+   */
+  remove(): void;
+  /**
+   * Resume the queue for a specific key _(or all queues, if no key is provided)_
+   *
+   * @param key Optional key to resume the queue for
+   */
+  resume(key?: string): void;
+};
+export type KeyedQueueState = {
+  callback: GenericCallback | GenericAsyncCallback;
+  options: Required<QueueOptions>;
+  queues: Map<string, Queue<GenericAsyncCallback, Tail<unknown[]>>>;
+};
+/**
+ * A queue that can be used to manage (a)synchronous tasks
+ */
+export type Queue<Callback extends GenericCallback | GenericAsyncCallback, CallbackParameters extends unknown[] = Parameters<Callback>> = {
+  /**
+   * Is the queue active?
+   */
+  get active(): boolean;
+  /**
+   * Does the queue automatically start when the first item is added?
+   */
+  get autostart(): boolean;
+  /**
+   * Maximum number of runners to process the queue concurrently
+   */
+  get concurrency(): number;
+  /**
+   * Is the queue empty?
+   */
+  get empty(): boolean;
+  /**
+   * Is the queue full?
+   */
+  get full(): boolean;
+  /**
+   * Maximum number of items allowed in the queue
+   */
+  get maximum(): number;
+  /**
+   * Is the queue paused?
+   */
+  get paused(): boolean;
+  /**
+   * Number of items in the queue
+   */
+  get size(): number;
+  /**
+   * Add an item to the queue
+   *
+   * @param parameters Parameters to use when item runs
+   * @param signal Optional signal to abort the item
+   * @returns Queued item
+   */
+  add(parameters: CallbackParameters, signal?: AbortSignal): Queued<ReturnType<Callback>>;
+  /**
+   * Remove and reject all items in the queue
+   */
+  clear(): void;
+  /**
+   * Pause the queue
+   *
+   * - Currently running items will not be stopped
+   * - New added items will not run until the queue is resumed
+   */
+  pause(): void;
+  /**
+   * Remove and reject a specific item in the queue
+   *
+   * @param id ID of queued item
+   */
+  remove(id: number): void;
+  /**
+   * Resume the queue
+   */
+  resume(): void;
+};
+export type QueueHandleType = "clear" | "pause" | "resume";
+export type QueueState = {
+  callback: GenericCallback | GenericAsyncCallback;
+  handled: GenericCallback[];
+  id: number;
+  items: Array<QueuedItem>;
+  key: string | undefined;
+  options: Required<QueueOptions>;
+  paused: boolean;
+  runners: number;
+};
+/**
+ * An error thrown by the Queue when an operation fails
+ */
+export declare class QueueError extends Error {
+  constructor(message: string);
+}
+export type QueueOptions = {
+  /**
+   * Automatically start processing the queue when the first item is added _(defaults to `true`)_
+   */
+  autostart?: boolean;
+  /**
+   * Number of runners to process the queue concurrently _(defaults to `1`)_
+   */
+  concurrency?: number;
+  /**
+   * Maximum number of items allowed in the queue _(defaults to `0`, which means no limit)_
+   */
+  maximum?: number;
+};
+/**
+ * A queued item
+ */
+export type Queued<Value> = {
+  /**
+   * ID of the queued item _(can be used to remove it from the queue)_
+   */
+  readonly id: number;
+  /**
+   * Queued promise
+   */
+  readonly promise: Promise<Value extends Promise<infer Result> ? Result : Value>;
+};
+export type QueuedItem = {
+  aborter?: Aborter;
+  id: number;
+  key?: string;
+  parameters: unknown[];
+  promise: Promise<unknown>;
+  reject(reason?: unknown): void;
+  resolve(value: unknown): void;
+};
+export type QueueStatusKey = "active" | "empty" | "full" | "paused";
+type Tail<Values extends any[]> = Values extends [infer _, ...infer Rest] ? Rest : never;
+export declare const QUEUE_ERROR_NAME = "QueueError";
+export declare const QUEUE_HANDLE_CLEAR: QueueHandleType;
+export declare const QUEUE_HANDLE_PAUSE: QueueHandleType;
+export declare const QUEUE_HANDLE_RESUME: QueueHandleType;
+export declare const QUEUE_MESSAGE_CALLBACK = "A Queue requires a callback function";
+export declare const QUEUE_MESSAGE_CLEAR = "Queue was cleared";
+export declare const QUEUE_MESSAGE_KEY = "Key must be a non-empty string";
+export declare const QUEUE_MESSAGE_MAXIMUM = "Queue has reached its maximum size";
+export declare const QUEUE_MESSAGE_REMOVE = "Item removed from queue";
+export declare const QUEUE_NAME_KEYED = "keyedQueue";
+export declare const QUEUE_NAME_QUEUE = "queue";
+export declare const QUEUE_PROPERTY = "$queue";
+export declare const QUEUE_STATUS_ACTIVE: QueueStatusKey;
+export declare const QUEUE_STATUS_EMPTY: QueueStatusKey;
+export declare const QUEUE_STATUS_FULL: QueueStatusKey;
+export declare const QUEUE_STATUS_PAUSED: QueueStatusKey;
+export declare const QUEUE_SYMBOL: unique symbol;
+//#endregion

package/dist/models/queue.model.mjs

@@ -0,0 +1,29 @@
+//#region src/models/queue.model.ts
+/**
+* An error thrown by the Queue when an operation fails
+*/
+var QueueError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = QUEUE_ERROR_NAME;
+	}
+};
+const QUEUE_ERROR_NAME = "QueueError";
+const QUEUE_HANDLE_CLEAR = "clear";
+const QUEUE_HANDLE_PAUSE = "pause";
+const QUEUE_HANDLE_RESUME = "resume";
+const QUEUE_MESSAGE_CALLBACK = "A Queue requires a callback function";
+const QUEUE_MESSAGE_CLEAR = "Queue was cleared";
+const QUEUE_MESSAGE_KEY = "Key must be a non-empty string";
+const QUEUE_MESSAGE_MAXIMUM = "Queue has reached its maximum size";
+const QUEUE_MESSAGE_REMOVE = "Item removed from queue";
+const QUEUE_NAME_KEYED = "keyedQueue";
+const QUEUE_NAME_QUEUE = "queue";
+const QUEUE_PROPERTY = "$queue";
+const QUEUE_STATUS_ACTIVE = "active";
+const QUEUE_STATUS_EMPTY = "empty";
+const QUEUE_STATUS_FULL = "full";
+const QUEUE_STATUS_PAUSED = "paused";
+const QUEUE_SYMBOL = Symbol(QUEUE_PROPERTY);
+//#endregion
+export { QUEUE_ERROR_NAME, QUEUE_HANDLE_CLEAR, QUEUE_HANDLE_PAUSE, QUEUE_HANDLE_RESUME, QUEUE_MESSAGE_CALLBACK, QUEUE_MESSAGE_CLEAR, QUEUE_MESSAGE_KEY, QUEUE_MESSAGE_MAXIMUM, QUEUE_MESSAGE_REMOVE, QUEUE_NAME_KEYED, QUEUE_NAME_QUEUE, QUEUE_PROPERTY, QUEUE_STATUS_ACTIVE, QUEUE_STATUS_EMPTY, QUEUE_STATUS_FULL, QUEUE_STATUS_PAUSED, QUEUE_SYMBOL, QueueError };

package/dist/models/random.model.d.mts

@@ -0,0 +1,6 @@
+//#region src/models/random.model.d.ts
+export declare const RANDOM_ALPHABET = "abcdefghijklmnopqrstuvwxyz";
+export declare const RANDOM_BOOLEAN_MODIFIER = .5;
+export declare const RANDOM_HEX_CHARACTERS = "0123456789ABCDEF";
+export declare const RANDOM_HEX_MAXIMUM = 15;
+//#endregion

package/dist/models/random.model.mjs

@@ -0,0 +1,7 @@
+//#region src/models/random.model.ts
+const RANDOM_ALPHABET = "abcdefghijklmnopqrstuvwxyz";
+const RANDOM_BOOLEAN_MODIFIER = .5;
+const RANDOM_HEX_CHARACTERS = "0123456789ABCDEF";
+const RANDOM_HEX_MAXIMUM = 15;
+//#endregion
+export { RANDOM_ALPHABET, RANDOM_BOOLEAN_MODIFIER, RANDOM_HEX_CHARACTERS, RANDOM_HEX_MAXIMUM };

package/dist/{internal/models → models}/result.model.d.mts

@@ -1,9 +1,17 @@
-import { GenericCallback } from "../../models.mjs";
-//#region src/internal/models/result.model.d.ts
+import { GenericCallback } from "./index.mjs";
+//#region src/models/result.model.d.ts
 /**
  * An unknown result
  */
 export type AnyResult<Value, E> = Err<E> | ExtendedErr<E> | Ok<Value>;
+/**
+ * A synchronous _Flow_, a function that attempts to pipe values through a series of functions
+ */
+export type AttemptFlow<Callback extends GenericCallback, Value> = (...args: Parameters<Callback>) => Result<UnwrapValue<Value>>;
+/**
+ * An asynchronous _Flow_, a function that attempts to pipe values through a series of functions
+ */
+export type AttemptAsyncFlow<Callback extends GenericCallback, Value> = (...args: Parameters<Callback>) => Promise<Result<UnwrapValue<Value>>>;
 /**
  * An error result
  */

package/dist/models/string/string.case.model.d.mts

@@ -0,0 +1,19 @@
+//#region src/models/string/string.case.model.d.ts
+export type StringCase = "camel" | "kebab" | "pascal" | "snake";
+export type StringCaseOptions = {
+  capitalizeAny: boolean;
+  capitalizeFirst: boolean;
+  type: StringCase;
+};
+export declare const STRING_CASE_CAMEL: StringCase;
+export declare const STRING_CASE_KEBAB: StringCase;
+export declare const STRING_CASE_PASCAL: StringCase;
+export declare const STRING_CASE_SNAKE: StringCase;
+export declare const STRING_DELIMTER_EMPTY = "";
+export declare const STRING_DELIMITER_HYPHEN = "-";
+export declare const STRING_DELIMITER_UNDERSCORE = "_";
+export declare const STRING_EXPRESSION_CAMEL_CASE: RegExp;
+export declare const STRING_EXPRESSION_ACRONYM: RegExp;
+export declare const STRING_REPLACEMENT_CAMEL_CASE = "$1-$2";
+export declare const STRING_S = "s";
+//#endregion

package/dist/models/string/string.case.model.mjs

@@ -0,0 +1,14 @@
+//#region src/models/string/string.case.model.ts
+const STRING_CASE_CAMEL = "camel";
+const STRING_CASE_KEBAB = "kebab";
+const STRING_CASE_PASCAL = "pascal";
+const STRING_CASE_SNAKE = "snake";
+const STRING_DELIMTER_EMPTY = "";
+const STRING_DELIMITER_HYPHEN = "-";
+const STRING_DELIMITER_UNDERSCORE = "_";
+const STRING_EXPRESSION_CAMEL_CASE = /(\p{Ll})(\p{Lu})/gu;
+const STRING_EXPRESSION_ACRONYM = /(\p{Lu}*)(\p{Lu})(\p{Ll}+)/gu;
+const STRING_REPLACEMENT_CAMEL_CASE = "$1-$2";
+const STRING_S = "s";
+//#endregion
+export { STRING_CASE_CAMEL, STRING_CASE_KEBAB, STRING_CASE_PASCAL, STRING_CASE_SNAKE, STRING_DELIMITER_HYPHEN, STRING_DELIMITER_UNDERSCORE, STRING_DELIMTER_EMPTY, STRING_EXPRESSION_ACRONYM, STRING_EXPRESSION_CAMEL_CASE, STRING_REPLACEMENT_CAMEL_CASE, STRING_S };

package/dist/models/string/string.fuzzy.model.d.mts

@@ -0,0 +1,108 @@
+import { PlainObject } from "../index.mjs";
+//#region src/models/string/string.fuzzy.model.d.ts
+/**
+ * Fuzzy searcher for an array of items
+ */
+export type Fuzzy<Item> = {
+  /**
+   * Get items currently being searched through
+   *
+   * @returns Original items
+   */
+  get items(): Item[];
+  /**
+   * Set new items to search through
+   *
+   * @param items New items to search through
+   */
+  set items(items: Item[]);
+  /**
+   * Get strings currently being searched through _(the stringified version of `items`)_
+   *
+   * @returns Stringified items
+   */
+  get strings(): string[];
+  /**
+   * Search for items matching the given value
+   *
+   * @param value Value to search for
+   * @param options Search options
+   * @returns Search results, with exact matches _(ordered)_ and similar matches _(ordered by relevance)_
+   */
+  search(value: string, options?: FuzzyOptions): FuzzyResult<Item>;
+  /**
+   * Search for items matching the given value
+   *
+   * @param value Value to search for
+   * @param limit Maximum number of combined items to return in `exact` and `similar`
+   * @returns Search results, with exact matches _(ordered)_ and similar matches _(ordered by relevance)_
+   */
+  search(value: string, limit: number): FuzzyResult<Item>;
+};
+export type FuzzyConfiguration<Item> = {
+  /**
+   * Handler to stringify items
+   *
+   * - May be a function that takes an item and returns a string, or if items are plain objects, a key of the item to use to grab a string value from
+   * - Defaults to `getString`
+   */
+  handler?: (item: Item) => string;
+} & (Item extends PlainObject ? {
+  /**
+   * Key to use to stringify items
+   *
+   * _Prioritized over `handler`_
+   */
+  key?: keyof Item;
+} : {}) & FuzzyOptions;
+export type FuzzyItem<Item> = {
+  item: Item;
+  haystack: string;
+};
+export type FuzzyOptions = {
+  /**
+   * Maximum number of combined items to return in `exact` and `similar` _(defaults to all matches)_
+   */
+  limit?: number;
+  /**
+   * Maximum score difference between the best and worst similar matches included in results
+   *
+   * - Higher values cast a wider net
+   * - Defaults to `5`
+   */
+  tolerance?: number;
+};
+/**
+ * Search results from a fuzzy search, with exact and similar matches
+ */
+export type FuzzyResult<Item> = {
+  /**
+   * Ordered items that exactly match the search value
+   */
+  exact: Item[];
+  /**
+   * Ordered items that are similar to the search value, ranked by relevance
+   */
+  similar: Item[];
+};
+/**
+ * Options for fuzzy searching
+ */
+export type FuzzySearchOptions = FuzzyOptions;
+export type FuzzyState<Item> = {
+  handler(item: Item): string;
+  items: Item[];
+  limit?: number;
+  strings: string[];
+  tolerance: number;
+};
+export type InternalFuzzy<Item = unknown> = {
+  [FUZZY_SYMBOL]: FuzzyState<Item>;
+} & Fuzzy<Item>;
+export declare const FUZZY_LENGTH_DIVISOR = 3;
+export declare const FUZZY_MESSAGE_ARRAY = "Fuzzy requires an array of items";
+export declare const FUZZY_MESSAGE_HANDLER = "Fuzzy requires a key or function to stringify items";
+export declare const FUZZY_PROPERTY = "$fuzzy";
+export declare const FUZZY_PROXIMITY_THRESHOLD = 5;
+export declare const FUZZY_SYMBOL: unique symbol;
+//#endregion

package/dist/models/string/string.fuzzy.model.mjs

@@ -0,0 +1,9 @@
+//#region src/models/string/string.fuzzy.model.ts
+const FUZZY_LENGTH_DIVISOR = 3;
+const FUZZY_MESSAGE_ARRAY = "Fuzzy requires an array of items";
+const FUZZY_MESSAGE_HANDLER = "Fuzzy requires a key or function to stringify items";
+const FUZZY_PROPERTY = "$fuzzy";
+const FUZZY_PROXIMITY_THRESHOLD = 5;
+const FUZZY_SYMBOL = Symbol(FUZZY_PROPERTY);
+//#endregion
+export { FUZZY_LENGTH_DIVISOR, FUZZY_MESSAGE_ARRAY, FUZZY_MESSAGE_HANDLER, FUZZY_PROPERTY, FUZZY_PROXIMITY_THRESHOLD, FUZZY_SYMBOL };

package/dist/models/string/string.misc.model.d.mts

@@ -0,0 +1,13 @@
+//#region src/models/string/string.misc.model.d.ts
+export type StringMatch = "endsWith" | "includes" | "startsWith";
+export declare const STRING_DELIMITER_UUID_DEFAULT = "-";
+export declare const STRING_DELIMITER_UUID_HTML = "_";
+export declare const STRING_EXPRESSION_IGNORED: RegExp;
+export declare const STRING_EXPRESSION_WORDS: RegExp;
+export declare const STRING_EXPRESSION_WHITESPACE_PREFIX: RegExp;
+export declare const STRING_MATCH_ENDS_WITH: StringMatch;
+export declare const STRING_MATCH_INCLUDES: StringMatch;
+export declare const STRING_MATCH_STARTS_WITH: StringMatch;
+export declare const STRING_NEWLINE = "\n";
+export declare const STRING_ZERO = "0";
+//#endregion