@oscarpalmer/atoms 0.186.2 → 0.187.0

package/dist/sized/set.mjs

@@ -1,17 +1,17 @@
 import { getSizedMaximum } from "../internal/sized.mjs";
 //#region src/sized/set.ts
 /**
-* A Set with a maximum size
+* A _Set_ with a maximum size
 *
-* Behavior is similar to a _LRU_-cache, where the oldest values are removed
+* Behavior is similar to a _LRU_ cache, where the oldest values are removed
 */
 var SizedSet = class extends Set {
 	/**
-	* The maximum size of the Set
+	* The maximum size of the _Set_
 	*/
 	#maximumSize;
 	/**
-	* Is the Set full?
+	* Is the _Set_ full?
 	*/
 	get full() {
 		return this.size >= this.#maximumSize;
@@ -38,9 +38,10 @@ var SizedSet = class extends Set {
 		return super.add(value);
 	}
 	/**
-	* Get a value from the SizedSet, if it exists _(and move it to the end)_
-	* @param value Value to get from the SizedSet
-	* @param update Update the value's position in the SizedSet? _(defaults to `false`)_
+	* Get a value from the _SizedSet_, if it exists _(and optionally move it to the end)_
+	*
+	* @param value Value to get from the _SizedSet_
+	* @param update Update the value's position in the _SizedSet_? _(defaults to `false`)_
 	* @returns Found value if it exists, otherwise `undefined`
 	*/
 	get(value, update) {

package/dist/string/case.d.mts

@@ -1,48 +1,56 @@
 //#region src/string/case.d.ts
 /**
  * Convert a string to camel case _(thisIsCamelCase)_
+ *
  * @param value String to convert
  * @returns Camel-cased string
  */
 declare function camelCase(value: string): string;
 /**
  * Capitalize the first letter of a string _(and lowercase the rest)_
+ *
  * @param value String to capitalize
  * @returns Capitalized string
  */
 declare function capitalize(value: string): string;
 /**
  * Convert a string to kebab case _(this-is-kebab-case)_
+ *
  * @param value String to convert
  * @returns Kebab-cased string
  */
 declare function kebabCase(value: string): string;
 /**
  * Convert a string to lower case
+ *
  * @param value String to convert
  * @returns Lower-cased string
  */
 declare function lowerCase(value: string): string;
 /**
  * Convert a string to pascal case _(ThisIsPascalCase)_
+ *
  * @param value String to convert
  * @returns Pascal-cased string
  */
 declare function pascalCase(value: string): string;
 /**
  * Convert a string to snake case _(this_is_snake_case)_
+ *
  * @param value String to convert
  * @returns Snake-cased string
  */
 declare function snakeCase(value: string): string;
 /**
  * Convert a string to title case _(Capitalizing Every Word)_
+ *
  * @param value String to convert
  * @returns Title-cased string
  */
 declare function titleCase(value: string): string;
 /**
  * Convert a string to upper case
+ *
  * @param value String to convert
  * @returns Upper-cased string
  */

package/dist/string/case.mjs

@@ -3,6 +3,7 @@ import { memoize } from "../function/memoize.mjs";
 //#region src/string/case.ts
 /**
 * Convert a string to camel case _(thisIsCamelCase)_
+*
 * @param value String to convert
 * @returns Camel-cased string
 */
@@ -11,6 +12,7 @@ function camelCase(value) {
 }
 /**
 * Capitalize the first letter of a string _(and lowercase the rest)_
+*
 * @param value String to capitalize
 * @returns Capitalized string
 */
@@ -21,6 +23,7 @@ function capitalize(value) {
 }
 /**
 * Convert a string to kebab case _(this-is-kebab-case)_
+*
 * @param value String to convert
 * @returns Kebab-cased string
 */
@@ -29,6 +32,7 @@ function kebabCase(value) {
 }
 /**
 * Convert a string to lower case
+*
 * @param value String to convert
 * @returns Lower-cased string
 */
@@ -39,6 +43,7 @@ function lowerCase(value) {
 }
 /**
 * Convert a string to pascal case _(ThisIsPascalCase)_
+*
 * @param value String to convert
 * @returns Pascal-cased string
 */
@@ -47,6 +52,7 @@ function pascalCase(value) {
 }
 /**
 * Convert a string to snake case _(this_is_snake_case)_
+*
 * @param value String to convert
 * @returns Snake-cased string
 */
@@ -55,6 +61,7 @@ function snakeCase(value) {
 }
 /**
 * Convert a string to title case _(Capitalizing Every Word)_
+*
 * @param value String to convert
 * @returns Title-cased string
 */
@@ -96,6 +103,7 @@ function toCaseCallback(value) {
 }
 /**
 * Convert a string to upper case
+*
 * @param value String to convert
 * @returns Upper-cased string
 */

package/dist/string/fuzzy.d.mts

@@ -8,19 +8,26 @@ declare class Fuzzy<Item> {
   #private;
   /**
    * 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[];
   constructor(state: FuzzyState<Item>);
   /**
    * 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)_
@@ -28,6 +35,7 @@ declare class Fuzzy<Item> {
   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)_
@@ -38,16 +46,15 @@ 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`
+   * - 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`
+   * _Prioritized over `handler`_
    */
   key?: keyof Item;
 } : {}) & FuzzyOptions;
@@ -57,7 +64,10 @@ type FuzzyOptions = {
    */
   limit?: number;
   /**
-   * Maximum score difference between the best and worst similar matches included in results; higher values cast a wider net _(defaults to 5)_
+   * Maximum score difference between the best and worst similar matches included in results
+   *
+   * - Higher values cast a wider net
+   * - Defaults to `5`
    */
   tolerance?: number;
 };
@@ -87,6 +97,7 @@ type FuzzyState<Item> = {
 };
 /**
  * Create a fuzzy searcher for an array of items
+ *
  * @param items Items to search through
  * @param key Key to use to stringify items
  * @returns Fuzzy searcher
@@ -94,6 +105,7 @@ type FuzzyState<Item> = {
 declare function fuzzy<Item extends PlainObject, ItemKey extends keyof Item>(items: Item[], key?: ItemKey): Fuzzy<Item>;
 /**
  * Create a fuzzy searcher for an array of items
+ *
  * @param items Items to search through
  * @param handler Handler to stringify items
  * @returns Fuzzy searcher
@@ -101,6 +113,7 @@ declare function fuzzy<Item extends PlainObject, ItemKey extends keyof Item>(ite
 declare function fuzzy<Item>(items: Item[], handler?: (item: Item) => string): Fuzzy<Item>;
 /**
  * Create a fuzzy searcher for an array of items
+ *
  * @param items Items to search through
  * @param configuration Fuzzy configuration
  * @returns Fuzzy searcher
@@ -111,6 +124,7 @@ declare namespace fuzzy {
 }
 /**
  * Does the needle match the haystack in a fuzzy way?
+ *
  * @param haystack Haystack to search through
  * @param needle Needle to search for
  * @returns `true` if the needle matches the haystack in a fuzzy way, `false` otherwise

package/dist/string/fuzzy.mjs

@@ -10,12 +10,16 @@ var Fuzzy = class {
 	#state;
 	/**
 	* Get items currently being searched through
+	*
+	* @returns Original items
 	*/
 	get items() {
 		return this.#state.items.slice();
 	}
 	/**
 	* Set new items to search through
+	*
+	* @param items New items to search through
 	*/
 	set items(items) {
 		if (Array.isArray(items)) {
@@ -25,6 +29,8 @@ var Fuzzy = class {
 	}
 	/**
 	* Get strings currently being searched through _(the stringified version of `items`)_
+	*
+	* @returns Stringified items
 	*/
 	get strings() {
 		return this.#state.strings.slice();
@@ -79,6 +85,7 @@ function fuzzy(items, configuration) {
 fuzzy.match = fuzzyMatch;
 /**
 * Does the needle match the haystack in a fuzzy way?
+*
 * @param haystack Haystack to search through
 * @param needle Needle to search for
 * @returns `true` if the needle matches the haystack in a fuzzy way, `false` otherwise

package/dist/string/index.d.mts

@@ -1,15 +1,28 @@
 import { getString, join, words } from "../internal/string.mjs";
 
 //#region src/string/index.d.ts
+/**
+ * Dedent a string template, removing common leading whitespace from each line
+ *
+ * @returns Dedented string
+ */
 declare function dedent(strings: TemplateStringsArray, ...values: unknown[]): string;
+/**
+ * Dedent a string, removing common leading whitespace from each line
+ *
+ * @param value String to dedent
+ * @returns Dedented string
+ */
 declare function dedent(value: string): string;
 /**
- * Get a new UUID-string _(version 4)_
+ * Get a new UUID string _(version 4)_
+ *
  * @returns UUID string
  */
 declare function getUuid(): string;
 /**
  * Parse a JSON string into its proper value _(or `undefined` if it fails)_
+ *
  * @param value JSON string to parse
  * @param reviver Reviver function to transform the parsed values
  * @returns Parsed value or `undefined` if parsing fails
@@ -17,12 +30,14 @@ declare function getUuid(): string;
 declare function parse(value: string, reviver?: (this: unknown, key: string, value: unknown) => unknown): unknown;
 /**
  * Trim a string _(removing whitespace from both ends)_
+ *
  * @param value String to trim
  * @returns Trimmed string
  */
 declare function trim(value: string): string;
 /**
- * Truncate a string to a specified length, when possible
+ * Truncate a string to a specified length
+ *
  * @param value String to truncate
  * @param length Maximum length of the string after truncation
  * @param suffix Suffix to append to the truncated string

package/dist/string/index.mjs

@@ -1,5 +1,5 @@
 import { isTemplateStringsArray } from "../internal/is.mjs";
-import { getString, join, words } from "../internal/string.mjs";
+import { getString, interpolate, join, words } from "../internal/string.mjs";
 //#region src/string/index.ts
 function dedent(value, ...values) {
 	let actual;
@@ -26,7 +26,8 @@ function dedent(value, ...values) {
 	return result.trim();
 }
 /**
-* Get a new UUID-string _(version 4)_
+* Get a new UUID string _(version 4)_
+*
 * @returns UUID string
 */
 function getUuid() {
@@ -43,14 +44,9 @@ function getUuid() {
 		hex.substring(20, 32)
 	].join("-");
 }
-function interpolate(strings, values) {
-	const { length } = strings;
-	let interpolated = "";
-	for (let index = 0; index < length; index += 1) interpolated += `${strings[index]}${getString(values[index])}`;
-	return interpolated;
-}
 /**
 * Parse a JSON string into its proper value _(or `undefined` if it fails)_
+*
 * @param value JSON string to parse
 * @param reviver Reviver function to transform the parsed values
 * @returns Parsed value or `undefined` if parsing fails
@@ -64,6 +60,7 @@ function parse(value, reviver) {
 }
 /**
 * Trim a string _(removing whitespace from both ends)_
+*
 * @param value String to trim
 * @returns Trimmed string
 */
@@ -71,7 +68,8 @@ function trim(value) {
 	return typeof value === "string" ? value.trim() : "";
 }
 /**
-* Truncate a string to a specified length, when possible
+* Truncate a string to a specified length
+*
 * @param value String to truncate
 * @param length Maximum length of the string after truncation
 * @param suffix Suffix to append to the truncated string

package/dist/string/match.d.mts

@@ -1,6 +1,7 @@
 //#region src/string/match.d.ts
 /**
  * Check if a string ends with a specified substring
+ *
  * @param haystack String to look in
  * @param needle String to look for
  * @param ignoreCase Ignore case when matching? _(defaults to `false`)_
@@ -9,6 +10,7 @@
 declare function endsWith(haystack: string, needle: string, ignoreCase?: boolean): boolean;
 /**
  * Check if a string includes a specified substring
+ *
  * @param haystack String to look in
  * @param needle String to look for
  * @param ignoreCase Ignore case when matching? _(defaults to `false`)_
@@ -17,6 +19,7 @@ declare function endsWith(haystack: string, needle: string, ignoreCase?: boolean
 declare function includes(haystack: string, needle: string, ignoreCase?: boolean): boolean;
 /**
  * Check if a string starts with a specified substring
+ *
  * @param haystack String to look in
  * @param needle String to look for
  * @param ignoreCase Ignore case when matching? _(defaults to `false`)_

package/dist/string/match.mjs

@@ -2,6 +2,7 @@ import { memoize } from "../function/memoize.mjs";
 //#region src/string/match.ts
 /**
 * Check if a string ends with a specified substring
+*
 * @param haystack String to look in
 * @param needle String to look for
 * @param ignoreCase Ignore case when matching? _(defaults to `false`)_
@@ -12,6 +13,7 @@ function endsWith(haystack, needle, ignoreCase) {
 }
 /**
 * Check if a string includes a specified substring
+*
 * @param haystack String to look in
 * @param needle String to look for
 * @param ignoreCase Ignore case when matching? _(defaults to `false`)_
@@ -30,6 +32,7 @@ function matchCallback(haystack, needle, ignoreCase) {
 }
 /**
 * Check if a string starts with a specified substring
+*
 * @param haystack String to look in
 * @param needle String to look for
 * @param ignoreCase Ignore case when matching? _(defaults to `false`)_

package/dist/string/normalize.d.mts

@@ -32,6 +32,7 @@ type NormalizeOptions = {
 type Normalizer = {
   /**
    * Normalize a string
+   *
    * @param value String to normalize
    * @returns Normalized string
    */
@@ -39,6 +40,7 @@ type Normalizer = {
 };
 /**
  * Deburr a string, removing diacritical marks
+ *
  * @param value String to deburr
  * @returns Deburred string
  */
@@ -46,7 +48,8 @@ declare function deburr(value: string): string;
 /**
  * Initialize a string normalizer
  *
- * Available as `initializeNormalizer` and `normalize.initialize`
+ * _Available as `initializeNormalizer` and `normalize.initialize`_
+ *
  * @param options Normalization options
  * @returns Normalizer function
  */
@@ -54,7 +57,8 @@ declare function initializeNormalizer(options?: NormalizeOptions): Normalizer;
 /**
  * Normalize a string
  *
- * By default, the string will be trimmed, deburred, and then lowercased
+ * _By default, the string will be trimmed, deburred, and then lowercased_
+ *
  * @param value String to normalize
  * @param options Normalization options
  * @returns Normalized string

package/dist/string/normalize.mjs

@@ -4,6 +4,7 @@ import { lowerCase } from "./case.mjs";
 //#region src/string/normalize.ts
 /**
 * Deburr a string, removing diacritical marks
+*
 * @param value String to deburr
 * @returns Deburred string
 */
@@ -29,7 +30,8 @@ function getNormalizeOptions(input) {
 /**
 * Initialize a string normalizer
 *
-* Available as `initializeNormalizer` and `normalize.initialize`
+* _Available as `initializeNormalizer` and `normalize.initialize`_
+*
 * @param options Normalization options
 * @returns Normalizer function
 */
@@ -40,7 +42,8 @@ function initializeNormalizer(options) {
 /**
 * Normalize a string
 *
-* By default, the string will be trimmed, deburred, and then lowercased
+* _By default, the string will be trimmed, deburred, and then lowercased_
+*
 * @param value String to normalize
 * @param options Normalization options
 * @returns Normalized string

package/dist/string/template.d.mts

@@ -1,6 +1,14 @@
 import { PlainObject } from "../models.mjs";
 
 //#region src/string/template.d.ts
+/**
+ * Renderer for a string template with variables
+ *
+ * @param variables Variables to use
+ * @param options Templating options
+ * @returns Templated string
+ */
+type Renderer = (variables?: PlainObject, options?: Partial<TemplateOptions>) => string;
 /**
  * Options for templating strings
  */
@@ -14,29 +22,50 @@ type TemplateOptions = {
    */
   pattern?: RegExp;
 };
+type Templater = {
+  /**
+   * Render a string from a template with variables
+   *
+   * @returns Templated string
+   */
+  (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
+   */
+  (value: string, variables?: PlainObject): string;
+};
 /**
- * Render a string from a template with variables
- * @param value Template string
- * @param variables Variables to use
- * @returns Templated string
+ * Render a template string with variables
  */
-type Templater = (value: string, variables?: PlainObject) => string;
+type TemplaterRenderer = (variables?: PlainObject) => string;
 /**
- * Create a templater with predefined options
+ * Create a _Templater_ with predefined options
+ *
+ * _Available as `initializeTemplater` and `template.initialize`_
  *
- * Available as `initializeTemplater` and `template.initialize`
  * @param options Templating options
- * @returns Templater function
+ * @returns _Templater_ function
  */
 declare function initializeTemplater(options?: Partial<TemplateOptions>): Templater;
+/**
+ * Get a _Renderer_ for a string template
+ *
+ * @returns _Renderer_ function
+ */
+declare function template(strings: TemplateStringsArray, ...values: unknown[]): Renderer;
 /**
  * Render a string from a template with variables
+ *
  * @param value Template string
  * @param variables Variables to use
  * @param options Templating options
  * @returns Templated string
  */
-declare function template(value: string, variables: PlainObject, options?: Partial<TemplateOptions>): string;
+declare function template(value: string, variables?: PlainObject, options?: Partial<TemplateOptions>): string;
 declare namespace template {
   var initialize: typeof initializeTemplater;
 }

package/dist/string/template.mjs

@@ -1,7 +1,12 @@
-import { isPlainObject } from "../internal/is.mjs";
-import { getString } from "../internal/string.mjs";
+import { isPlainObject, isTemplateStringsArray } from "../internal/is.mjs";
+import { getString, interpolate } from "../internal/string.mjs";
 import { getValue } from "../internal/value/get.mjs";
 //#region src/string/template.ts
+function getRenderer(strings, values) {
+	return (variables, options) => {
+		return template(interpolate(strings, values), variables, options);
+	};
+}
 function getTemplateOptions(input) {
 	const options = isPlainObject(input) ? input : {};
 	return {
@@ -11,7 +16,7 @@ function getTemplateOptions(input) {
 }
 function handleTemplate(value, pattern, ignoreCase, variables) {
 	if (typeof value !== "string") return "";
-	if (typeof variables !== "object" || variables === null) return value;
+	if (typeof variables !== "object" || variables === null || Object.keys(variables).length === 0) return value;
 	const values = {};
 	return value.replace(pattern, (_, key) => {
 		if (values[key] == null) {
@@ -22,28 +27,23 @@ function handleTemplate(value, pattern, ignoreCase, variables) {
 	});
 }
 /**
-* Create a templater with predefined options
+* Create a _Templater_ with predefined options
+*
+* _Available as `initializeTemplater` and `template.initialize`_
 *
-* Available as `initializeTemplater` and `template.initialize`
 * @param options Templating options
-* @returns Templater function
+* @returns _Templater_ function
 */
 function initializeTemplater(options) {
 	const { ignoreCase, pattern } = getTemplateOptions(options);
-	return (value, variables) => {
-		return handleTemplate(value, pattern, ignoreCase, variables);
-	};
+	return ((value, ...parameters) => {
+		return isTemplateStringsArray(value) ? (variables) => handleTemplate(interpolate(value, parameters), pattern, ignoreCase, variables) : handleTemplate(value, pattern, ignoreCase, parameters[0]);
+	});
 }
-/**
-* Render a string from a template with variables
-* @param value Template string
-* @param variables Variables to use
-* @param options Templating options
-* @returns Templated string
-*/
-function template(value, variables, options) {
-	const { ignoreCase, pattern } = getTemplateOptions(options);
-	return handleTemplate(value, pattern, ignoreCase, variables);
+function template(value, ...parameters) {
+	if (isTemplateStringsArray(value)) return getRenderer(value, parameters);
+	const { ignoreCase, pattern } = getTemplateOptions(parameters[1]);
+	return handleTemplate(value, pattern, ignoreCase, parameters[0]);
 }
 template.initialize = initializeTemplater;
 const EXPRESSION_VARIABLE = /{{([\s\S]+?)}}/g;

package/dist/value/clone.d.mts

@@ -1,8 +1,17 @@
 import { Constructor, GenericCallback } from "../models.mjs";
 
 //#region src/value/clone.d.ts
+/**
+ * Clone any kind of value _(shallowly)_
+ *
+ * @param value Value to clone
+ * @param flat Clone only the value itself, without cloning nested values
+ * @returns Cloned value
+ */
+declare function clone<Value>(value: Value, flat: true): Value;
 /**
  * Clone any kind of value _(deeply, if needed)_
+ *
  * @param value Value to clone
  * @returns Cloned value
  */
@@ -16,20 +25,32 @@ declare namespace clone {
   var deregister: typeof deregisterCloner;
   var register: typeof registerCloner;
 }
+/**
+ * Copy any kind of value
+ *
+ * - Clones the value shallowly, without cloning nested values
+ * - To copy a value deeply, use `clone` instead
+ *
+ * @param value Value to copy
+ * @returns Copied value
+ */
+declare function copy<Value>(value: Value): Value;
 /**
  * Deregister a clone handler for a specific class
  *
- * Available as `deregisterCloner` and `template.deregister`
+ * _Available as `deregisterCloner` and `template.deregister`_
+ *
  * @param constructor Class constructor
  */
 declare function deregisterCloner<Instance>(constructor: Constructor<Instance>): void;
 /**
  * Register a clone handler for a specific class
  *
- * Available as `registerCloner` and `template.register`
+ * _Available as `registerCloner` and `template.register`_
+ *
  * @param constructor Class constructor
- * @param handler Method name or clone function _(defaults to `clone`)_
+ * @param handler Method name or clone function _(defaults to method name `clone`)_
  */
 declare function registerCloner<Instance>(constructor: Constructor<Instance>, handler?: string | ((value: Instance) => Instance)): void;
 //#endregion
-export { clone, deregisterCloner, registerCloner };
+export { clone, copy, deregisterCloner, registerCloner };