@oscarpalmer/atoms 0.212.0 → 0.214.0

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

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

@@ -0,0 +1,13 @@
+//#region src/models/string/string.misc.model.ts
+const STRING_DELIMITER_UUID_DEFAULT = "-";
+const STRING_DELIMITER_UUID_HTML = "_";
+const STRING_EXPRESSION_IGNORED = /(^|\.)(__proto__|constructor|prototype)(\.|$)/i;
+const STRING_EXPRESSION_WORDS = /[^\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\x7f]+/g;
+const STRING_EXPRESSION_WHITESPACE_PREFIX = /^(\s+)/;
+const STRING_MATCH_ENDS_WITH = "endsWith";
+const STRING_MATCH_INCLUDES = "includes";
+const STRING_MATCH_STARTS_WITH = "startsWith";
+const STRING_NEWLINE = "\n";
+const STRING_ZERO = "0";
+//#endregion
+export { STRING_DELIMITER_UUID_DEFAULT, STRING_DELIMITER_UUID_HTML, STRING_EXPRESSION_IGNORED, STRING_EXPRESSION_WHITESPACE_PREFIX, STRING_EXPRESSION_WORDS, STRING_MATCH_ENDS_WITH, STRING_MATCH_INCLUDES, STRING_MATCH_STARTS_WITH, STRING_NEWLINE, STRING_ZERO };

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

@@ -0,0 +1,85 @@
+//#region src/models/string/string.normalize.model.d.ts
+export type InternalNormalizer = {
+  [NORMALIZE_SYMBOL]: Required<NormalizeOptions>;
+} & Normalizer;
+/**
+ * Options for normalizing a string
+ */
+export type NormalizeOptions = {
+  /**
+   * Remove diacritical marks from the string? _(defaults to `true`)_
+   */
+  deburr?: boolean;
+  /**
+   * Convert the string to lower case? _(defaults to `true`)_
+   */
+  lowerCase?: boolean;
+  /**
+   * Remove special characters from the string? _(defaults to `false`)_
+   *
+   * _(Punctuation and symbol characters are considered special)_
+   */
+  special?: boolean;
+  /**
+   * Trim the string? _(defaults to `true`)_
+   */
+  trim?: boolean;
+  /**
+   * Shorten consecutive whitespace characters to a single space? _(defaults to `true`)_
+   */
+  whitespace?: boolean;
+};
+/**
+ * String normalizer function
+ */
+export type Normalizer = {
+  /**
+   * Normalize a string
+   *
+   * @param value String to normalize
+   * @returns Normalized string
+   */
+  normalize(value: string): string;
+};
+export type NormalizerOptions = Required<NormalizeOptions>;
+export declare const NORMALIZE_DEBURR_CHARACTERS: {
+  Æ: string;
+  æ: string;
+  Ð: string;
+  ð: string;
+  Đ: string;
+  đ: string;
+  Ħ: string;
+  ħ: string;
+  IJ: string;
+  ij: string;
+  İ: string;
+  ı: string;
+  ĸ: string;
+  Ŀ: string;
+  ŀ: string;
+  Ł: string;
+  ł: string;
+  Ŋ: string;
+  ŋ: string;
+  ʼn: string;
+  Œ: string;
+  œ: string;
+  Ø: string;
+  ø: string;
+  ſ: string;
+  ß: string;
+  Þ: string;
+  þ: string;
+  Ŧ: string;
+  ŧ: string;
+};
+export declare const NORMALIZE_DEBURR_NORMALIZATION = "NFD";
+export declare const NORMALIZE_DEBURR_PATTERN_CHARACTERS: RegExp;
+export declare const NORMALIZE_DEBURR_PATTERN_SIMPLE: RegExp;
+export declare const NORMALIZE_NORMALIZATION_NORMALIZATION: string;
+export declare const NORMALIZE_SPECIAL_PATTERN: RegExp;
+export declare const NORMALIZE_SPECIAL_REPLACEMENT = "";
+export declare const NORMALIZE_SYMBOL: unique symbol;
+export declare const NORMALIZE_WHITESPACE_REPLACEMENT = " ";
+//#endregion

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

@@ -0,0 +1,43 @@
+//#region src/models/string/string.normalize.model.ts
+const NORMALIZE_DEBURR_CHARACTERS = {
+	Æ: "AE",
+	æ: "ae",
+	Ð: "D",
+	ð: "d",
+	Đ: "D",
+	đ: "d",
+	Ħ: "H",
+	ħ: "h",
+	IJ: "IJ",
+	ij: "ij",
+	İ: "I",
+	ı: "i",
+	ĸ: "k",
+	Ŀ: "L",
+	ŀ: "l",
+	Ł: "L",
+	ł: "l",
+	Ŋ: "N",
+	ŋ: "n",
+	ʼn: "'n",
+	Œ: "OE",
+	œ: "oe",
+	Ø: "O",
+	ø: "o",
+	ſ: "s",
+	ß: "ss",
+	Þ: "TH",
+	þ: "th",
+	Ŧ: "T",
+	ŧ: "t"
+};
+const NORMALIZE_DEBURR_NORMALIZATION = "NFD";
+const NORMALIZE_DEBURR_PATTERN_CHARACTERS = new RegExp(`(${Object.keys(NORMALIZE_DEBURR_CHARACTERS).join("|")})`, "g");
+const NORMALIZE_DEBURR_PATTERN_SIMPLE = /[\u0300-\u036f]/g;
+const NORMALIZE_NORMALIZATION_NORMALIZATION = "NFC";
+const NORMALIZE_SPECIAL_PATTERN = /[\p{P}\p{S}]/gu;
+const NORMALIZE_SPECIAL_REPLACEMENT = "";
+const NORMALIZE_SYMBOL = Symbol("normalize");
+const NORMALIZE_WHITESPACE_REPLACEMENT = " ";
+//#endregion
+export { NORMALIZE_DEBURR_CHARACTERS, NORMALIZE_DEBURR_NORMALIZATION, NORMALIZE_DEBURR_PATTERN_CHARACTERS, NORMALIZE_DEBURR_PATTERN_SIMPLE, NORMALIZE_NORMALIZATION_NORMALIZATION, NORMALIZE_SPECIAL_PATTERN, NORMALIZE_SPECIAL_REPLACEMENT, NORMALIZE_SYMBOL, NORMALIZE_WHITESPACE_REPLACEMENT };

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

@@ -0,0 +1,50 @@
+import { PlainObject } from "../index.mjs";
+//#region src/models/string/string.template.model.d.ts
+export type InternalTemplater = {
+  [TEMPLATE_SYMBOL]: Required<TemplateOptions>;
+} & Templater;
+/**
+ * Renderer for a string template with variables
+ *
+ * @param variables Variables to use
+ * @param options Templating options
+ * @returns Templated string
+ */
+export type Renderer = (variables?: PlainObject, options?: Partial<TemplateOptions>) => string;
+/**
+ * Options for templating strings
+ */
+export type TemplateOptions = {
+  /**
+   * Ignore case when searching for variables?
+   */
+  ignoreCase?: boolean;
+  /**
+   * Custom pattern for outputting variables
+   */
+  pattern?: RegExp;
+};
+export type Templater = {
+  /**
+   * Render a string from a template with variables
+   *
+   * @returns Templated string
+   */
+  render(strings: TemplateStringsArray, ...values: unknown[]): TemplaterRenderer;
+  /**
+   * Render a string from a template with variables
+   *
+   * @param value Template string
+   * @param variables Variables to use
+   * @returns Templated string
+   */
+  render(value: string, variables?: PlainObject): string;
+};
+export type TemplaterOptions = Required<TemplateOptions>;
+/**
+ * Render a template string with variables
+ */
+export type TemplaterRenderer = (variables?: PlainObject) => string;
+export declare const TEMPLATE_EXPRESSION_VARIABLE: RegExp;
+export declare const TEMPLATE_SYMBOL: unique symbol;
+//#endregion

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

@@ -0,0 +1,5 @@
+//#region src/models/string/string.template.model.ts
+const TEMPLATE_EXPRESSION_VARIABLE = /{{([\s\S]+?)}}/g;
+const TEMPLATE_SYMBOL = Symbol("template");
+//#endregion
+export { TEMPLATE_EXPRESSION_VARIABLE, TEMPLATE_SYMBOL };

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

@@ -0,0 +1,127 @@
+import { Key } from "./index.mjs";
+import { Aborter } from "./aborter.model.mjs";
+//#region src/models/subscription.model.d.ts
+export type InternalSubscription = {
+  [SUBSCRIPTION_SYMBOL]: SubscriptionState;
+} & Subscription;
+export type InternalSubscriptions = {
+  [SUBSCRIPTION_SYMBOL]: SubscriptionsState;
+} & Subscriptions;
+export type Subscription = {
+  /**
+   * Is the subscription active?
+   */
+  get active(): boolean;
+  /**
+   * Unsubscribe from changes
+   */
+  unsubscribe(): void;
+};
+/**
+ * Parameters for creating a subscription
+ */
+export type SubscriptionParameters = {
+  /**
+   * Is the owner of the subscription alive? _(defaults to `true`)_
+   */
+  isActive?: () => boolean;
+  /**
+   * Key used to identify a subscription _(defaults to `undefined`)_
+   */
+  key?: unknown;
+  /**
+   * Signal used to abort the subscription _(defaults to `undefined`)_
+   */
+  signal?: AbortSignal;
+  /**
+   * Value used to identify a subscription
+   */
+  value: unknown;
+};
+/**
+ * Property information for subscription identification
+ */
+export type SubscriptionProperty = {
+  /**
+   * Name of the property used to identify a subscription
+   */
+  key: string;
+  /**
+   * Value of the property used to identify a subscription
+   */
+  value: unknown;
+};
+export type SubscriptionState = {
+  aborter?: Aborter;
+  active: boolean;
+  parameters: SubscriptionParameters;
+  subscriptions: SubscriptionsState;
+};
+export type Subscriptions<Value = unknown> = {
+  /**
+   * Items of the subscriptions store
+   *
+   * - `any` - Set of subscriptions _(for unkeyed subscriptions)_
+   * - `keyed` - Map of keys to sets of subscriptions _(for keyed subscriptions)_
+   */
+  readonly items: Readonly<SubscriptionsItems>;
+  /**
+   * Values of the subscriptions store
+   *
+   * - `from.any` - Map of values to subscriptions _(for unkeyed subscriptions)_
+   * - `from.keyed` - Map of keys to maps of values to subscriptions _(for keyed subscriptions)_
+   * - `to.any` - Map of subscriptions to values _(for unkeyed subscriptions)_
+   * - `to.keyed` - Map of keys to maps of subscriptions to values _(for keyed subscriptions)_
+   */
+  readonly values: Readonly<SubscriptionsValues<Value>>;
+  /**
+   * Clear all subscriptions
+   */
+  clear(): void;
+  /**
+   * Create _(or retrieve)_ a subscription
+   *
+   * @param parameters Subscription parameters
+   * @returns Tuple holding subsccription and existing boolean
+   */
+  create(parameters: SubscriptionParameters): [Subscription, boolean];
+};
+/**
+ * Parameters for creating a subscription store
+ */
+export type SubscriptionsParameters = {
+  /**
+   * Allow any or specific keys for subscriptions? _(defaults to `false`, which prevents keyed subscriptions)_
+   */
+  keys?: boolean | Set<Key>;
+  /**
+   * Property information for subscription identification
+   */
+  property?: SubscriptionProperty;
+};
+export type SubscriptionsState = {
+  items: SubscriptionsItems;
+  keys: boolean | Set<Key>;
+  property: SubscriptionProperty;
+  values: SubscriptionsValues;
+};
+export type SubscriptionsItems = {
+  any: Set<Subscription>;
+  keyed?: Map<Key, Set<Subscription>>;
+};
+export type SubscriptionsValues<Value = unknown> = {
+  from: SubscriptionsValuesItem<Value, Subscription>;
+  to: SubscriptionsValuesItem<Subscription, Value>;
+};
+export type SubscriptionsValuesItem<MapKey, MapValue> = {
+  any: Map<MapKey, MapValue>;
+  keyed?: Map<Key, Map<MapKey, MapValue>>;
+};
+export declare const SUBSCRIPTION_DISALLOWED_KEY = "Disallowed key for subscription";
+export declare const SUBSCRIPTION_INVALID_KEY = "Invalid key for subscription";
+export declare const SUBSCRIPTION_INVALID_VALUE = "A subscription requires a non-null value to identify it";
+export declare const SUBSCRIPTION_NAME = "subscription";
+export declare const SUBSCRIPTION_PROPERTY = "$subscription";
+export declare const SUBSCRIPTION_STORE = "subscriptions";
+export declare const SUBSCRIPTION_SYMBOL: unique symbol;
+//#endregion

package/dist/models/subscription.model.mjs

@@ -0,0 +1,10 @@
+//#region src/models/subscription.model.ts
+const SUBSCRIPTION_DISALLOWED_KEY = "Disallowed key for subscription";
+const SUBSCRIPTION_INVALID_KEY = "Invalid key for subscription";
+const SUBSCRIPTION_INVALID_VALUE = "A subscription requires a non-null value to identify it";
+const SUBSCRIPTION_NAME = "subscription";
+const SUBSCRIPTION_PROPERTY = "$subscription";
+const SUBSCRIPTION_STORE = "subscriptions";
+const SUBSCRIPTION_SYMBOL = Symbol(SUBSCRIPTION_PROPERTY);
+//#endregion
+export { SUBSCRIPTION_DISALLOWED_KEY, SUBSCRIPTION_INVALID_KEY, SUBSCRIPTION_INVALID_VALUE, SUBSCRIPTION_NAME, SUBSCRIPTION_PROPERTY, SUBSCRIPTION_STORE, SUBSCRIPTION_SYMBOL };

package/dist/models/value/value.clone.model.d.mts

@@ -0,0 +1,56 @@
+import { Constructor } from "../index.mjs";
+//#region src/models/value/value.clone.model.d.ts
+export type CloneOptions = {
+  /**
+   * Copy functions instead of returning `undefined`? _(defaults to `false`)_
+   */
+  copyFunctions?: boolean;
+  /**
+   * Copy symbols instead of returning `Symbol(description)`? _(defaults to `false`)_
+   */
+  copySymbols?: boolean;
+};
+export type CloneParameters = {
+  copy: boolean;
+  options: Required<CloneOptions>;
+  references: WeakMap<WeakKey, unknown>;
+};
+/**
+ * A cloning function with predefined options
+ */
+export type Cloner = {
+  /**
+   * Clone any kind of value
+   *
+   * @param value Value to clone
+   * @returns Cloned value
+   */
+  clone<Value>(value: Value): Value;
+  /**
+   * Deregister a clone handler for a specific class
+   *
+   * _Available as `deregisterCloner` and `template.deregister`_
+   *
+   * @param constructor Class constructor
+   */
+  deregister<Instance>(constructor: Constructor<Instance>): void;
+  /**
+   * Register a clone handler for a specific class
+   *
+   * _Available as `registerCloner` and `template.register`_
+   *
+   * @param constructor Class constructor
+   * @param handler Method name or clone function _(defaults to method name `clone`)_
+   */
+  register<Instance>(constructor: Constructor<Instance>, handler?: string | ((value: Instance) => Instance)): void;
+};
+export type InternalCloner = {
+  [CLONE_SYMBOL]: Required<CloneOptions>;
+} & Cloner;
+export declare const CLONE_NAME = "clone";
+export declare const CLONE_COPY_OPTIONS: Required<CloneOptions>;
+export declare const CLONE_DEFAULT_OPTIONS: Required<CloneOptions>;
+export declare const CLONE_MAX_DEPTH = 100;
+export declare const CLONE_PRIMITIVES: Record<string, boolean>;
+export declare const CLONE_SYMBOL: unique symbol;
+//#endregion

package/dist/models/value/value.clone.model.mjs

@@ -0,0 +1,24 @@
+//#region src/models/value/value.clone.model.ts
+const CLONE_NAME = "clone";
+const CLONE_COPY_OPTIONS = {
+	copyFunctions: true,
+	copySymbols: true
+};
+const CLONE_DEFAULT_OPTIONS = {
+	copyFunctions: false,
+	copySymbols: false
+};
+const CLONE_MAX_DEPTH = 100;
+const CLONE_PRIMITIVES = {
+	bigint: true,
+	boolean: true,
+	function: false,
+	number: true,
+	object: false,
+	string: true,
+	symbol: false,
+	undefined: true
+};
+const CLONE_SYMBOL = Symbol(CLONE_NAME);
+//#endregion
+export { CLONE_COPY_OPTIONS, CLONE_DEFAULT_OPTIONS, CLONE_MAX_DEPTH, CLONE_NAME, CLONE_PRIMITIVES, CLONE_SYMBOL };

package/dist/models/value/value.diff.model.d.mts

@@ -0,0 +1,61 @@
+//#region src/models/value/value.diff.model.d.ts
+/**
+ * Options for value comparison
+ */
+export type DiffOptions = {
+  /**
+   * Should `null` and `undefined` be considered equal and ignored in results?
+   */
+  relaxedNullish?: boolean;
+};
+/**
+ * The result of a comparison beteen two values
+ */
+export type DiffResult<First, Second = First> = {
+  /**
+   * The original values that were compared
+   */
+  original: DiffValue<First, Second>;
+  /**
+   * The type of difference between the two values
+   */
+  type: DiffType;
+  /**
+   * The differences between the two values
+   *
+   * - Keys are in dot notation
+   * - Values are objects with `from` and `to` properties
+   */
+  values: Record<string, DiffValue>;
+};
+export type DiffType = "full" | "none" | "partial";
+/**
+ * The difference between two values
+ */
+export type DiffValue<First = unknown, Second = First> = {
+  /**
+   * The value from the first value
+   */
+  from: First;
+  /**
+   * The value from the second value
+   */
+  to: Second;
+};
+export type DiffKeyedValue = {
+  key: string;
+} & DiffValue;
+export type DiffParameters = {
+  changes: DiffKeyedValue[];
+  key: PropertyKey;
+  options: Required<DiffOptions>;
+  values: {
+    first: unknown;
+    second: unknown;
+  };
+  prefix?: string;
+};
+export declare const DIFF_FULL: DiffType;
+export declare const DIFF_NONE: DiffType;
+export declare const DIFF_PARTIAL: DiffType;
+//#endregion

package/dist/models/value/value.diff.model.mjs

@@ -0,0 +1,6 @@
+//#region src/models/value/value.diff.model.ts
+const DIFF_FULL = "full";
+const DIFF_NONE = "none";
+const DIFF_PARTIAL = "partial";
+//#endregion
+export { DIFF_FULL, DIFF_NONE, DIFF_PARTIAL };