@oscarpalmer/atoms 0.186.2 → 0.187.0

package/src/string/normalize.ts

@@ -38,6 +38,7 @@ export type NormalizeOptions = {
 export type Normalizer = {
 	/**
 	 * Normalize a string
+	 *
 	 * @param value String to normalize
 	 * @returns Normalized string
 	 */
@@ -52,6 +53,7 @@ type Options = Required<NormalizeOptions>;
 
 /**
  * Deburr a string, removing diacritical marks
+ *
  * @param value String to deburr
  * @returns Deburred string
  */
@@ -89,7 +91,8 @@ function getNormalizeOptions(input?: NormalizeOptions): Options {
 /**
  * Initialize a string normalizer
  *
- * Available as `initializeNormalizer` and `normalize.initialize`
+ * _Available as `initializeNormalizer` and `normalize.initialize`_
+ *
  * @param options Normalization options
  * @returns Normalizer function
  */
@@ -102,7 +105,8 @@ export 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/src/string/template.ts

@@ -1,10 +1,19 @@
-import {isPlainObject} from '../internal/is';
-import {getString} from '../internal/string';
+import {isPlainObject, isTemplateStringsArray} from '../internal/is';
+import {getString, interpolate} from '../internal/string';
 import {getValue} from '../internal/value/get';
 import type {PlainObject} from '../models';
 
 // #region Types
 
+/**
+ * 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
  */
@@ -19,18 +28,39 @@ export 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;
 
 // #endregion
 
 // #region Functions
 
+function getRenderer(strings: TemplateStringsArray, values: unknown[]): Renderer {
+	return (variables?: PlainObject, options?: Partial<TemplateOptions>) => {
+		return template(interpolate(strings, values), variables, options);
+	};
+}
+
 function getTemplateOptions(input?: Partial<TemplateOptions>): Required<TemplateOptions> {
 	const options = isPlainObject(input) ? (input as TemplateOptions) : {};
 
@@ -50,7 +80,7 @@ function handleTemplate(
 		return '';
 	}
 
-	if (typeof variables !== 'object' || variables === null) {
+	if (typeof variables !== 'object' || variables === null || Object.keys(variables).length === 0) {
 		return value;
 	}
 
@@ -68,22 +98,34 @@ function handleTemplate(
 }
 
 /**
- * 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
  */
 export function initializeTemplater(options?: Partial<TemplateOptions>): Templater {
 	const {ignoreCase, pattern} = getTemplateOptions(options);
 
-	return (value: string, variables?: PlainObject): string => {
-		return handleTemplate(value, pattern, ignoreCase, variables);
-	};
+	return ((value: string | TemplateStringsArray, ...parameters: unknown[]) => {
+		return isTemplateStringsArray(value)
+			? (variables?: PlainObject) =>
+					handleTemplate(interpolate(value, parameters), pattern, ignoreCase, variables)
+			: handleTemplate(value, pattern, ignoreCase, parameters[0] as PlainObject);
+	}) as Templater;
 }
 
+/**
+ * Get a _Renderer_ for a string template
+ *
+ * @returns _Renderer_ function
+ */
+export 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
@@ -91,12 +133,21 @@ export function initializeTemplater(options?: Partial<TemplateOptions>): Templat
  */
 export function template(
 	value: string,
-	variables: PlainObject,
+	variables?: PlainObject,
 	options?: Partial<TemplateOptions>,
-): string {
-	const {ignoreCase, pattern} = getTemplateOptions(options);
+): string;
+
+export function template(
+	value: string | TemplateStringsArray,
+	...parameters: unknown[]
+): string | Renderer {
+	if (isTemplateStringsArray(value)) {
+		return getRenderer(value, parameters);
+	}
+
+	const {ignoreCase, pattern} = getTemplateOptions(parameters[1] as Partial<TemplateOptions>);
 
-	return handleTemplate(value, pattern, ignoreCase, variables);
+	return handleTemplate(value, pattern, ignoreCase, parameters[0] as PlainObject);
 }
 
 template.initialize = initializeTemplater;

package/src/value/clone.ts

@@ -10,15 +10,25 @@ const CLONE_NAME = 'clone';
 
 // #region Functions
 
+/**
+ * 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
+ */
+export function clone<Value>(value: Value, flat: true): Value;
+
 /**
  * Clone any kind of value _(deeply, if needed)_
+ *
  * @param value Value to clone
  * @returns Cloned value
  */
 export function clone<Value>(value: Value): Value;
 
-export function clone(value: unknown): unknown {
-	return cloneValue(value, 0, new WeakMap());
+export function clone(value: unknown, flat?: boolean): unknown {
+	return flat === true ? copy(value) : cloneValue(value, 0, new WeakMap(), false);
 }
 
 clone.handlers = getSelfHandlers(clone, {
@@ -69,6 +79,7 @@ function cloneMap(
 	map: Map<unknown, unknown>,
 	depth: number,
 	references: WeakMap<WeakKey, unknown>,
+	flat: boolean,
 ): Map<unknown, unknown> {
 	if (depth >= MAX_CLONE_DEPTH) {
 		return map;
@@ -79,8 +90,8 @@ function cloneMap(
 
 	for (const entry of entries) {
 		cloned.set(
-			cloneValue(entry[0], depth + 1, references),
-			cloneValue(entry[1], depth + 1, references),
+			flat ? entry[0] : cloneValue(entry[0], depth + 1, references, false),
+			flat ? entry[1] : cloneValue(entry[1], depth + 1, references, false),
 		);
 	}
 
@@ -101,12 +112,13 @@ function cloneNode(node: Node, depth: number, references: WeakMap<WeakKey, unkno
 	return cloned;
 }
 
-function clonePlainObject(
+function cloneObject(
 	value: ArrayOrPlainObject,
 	depth: number,
 	references: WeakMap<WeakKey, unknown>,
+	flat: boolean,
 ): ArrayOrPlainObject {
-	if (depth >= MAX_CLONE_DEPTH) {
+	if (flat || depth >= MAX_CLONE_DEPTH) {
 		return Array.isArray(value) ? value.slice() : {...value};
 	}
 
@@ -117,7 +129,7 @@ function clonePlainObject(
 	for (let index = 0; index < length; index += 1) {
 		const key = keys[index];
 
-		cloned[key] = cloneValue((value as PlainObject)[key], depth + 1, references);
+		cloned[key] = cloneValue((value as PlainObject)[key], depth + 1, references, false);
 	}
 
 	references.set(value, cloned);
@@ -147,6 +159,7 @@ function cloneSet(
 	set: Set<unknown>,
 	depth: number,
 	references: WeakMap<WeakKey, unknown>,
+	flat: boolean,
 ): Set<unknown> {
 	if (depth >= MAX_CLONE_DEPTH) {
 		return set;
@@ -157,7 +170,7 @@ function cloneSet(
 	const {length} = values;
 
 	for (let index = 0; index < length; index += 1) {
-		cloned.add(cloneValue(values[index], depth + 1, references));
+		cloned.add(flat ? values[index] : cloneValue(values[index], depth + 1, references, false));
 	}
 
 	references.set(set, cloned);
@@ -181,26 +194,23 @@ function cloneTypedArray(
 	return cloned as TypedArray;
 }
 
-function cloneValue(value: unknown, depth: number, references: WeakMap<WeakKey, unknown>): unknown {
+function cloneValue(
+	value: unknown,
+	depth: number,
+	references: WeakMap<WeakKey, unknown>,
+	flat: boolean,
+): unknown {
 	switch (true) {
 		case value == null:
-			return value;
-
 		case typeof value === 'bigint':
-			return BigInt(value);
-
 		case typeof value === 'boolean':
-			return Boolean(value);
+		case typeof value === 'number':
+		case typeof value === 'string':
+			return value;
 
 		case typeof value === 'function':
 			return;
 
-		case typeof value === 'number':
-			return Number(value);
-
-		case typeof value === 'string':
-			return String(value);
-
 		case typeof value === 'symbol':
 			return Symbol(value.description);
 
@@ -220,16 +230,16 @@ function cloneValue(value: unknown, depth: number, references: WeakMap<WeakKey,
 			return cloneRegularExpression(value, depth, references);
 
 		case value instanceof Map:
-			return cloneMap(value, depth, references);
+			return cloneMap(value, depth, references, flat);
 
 		case typeof Node !== 'undefined' && value instanceof Node:
 			return cloneNode(value, depth, references);
 
 		case value instanceof Set:
-			return cloneSet(value, depth, references);
+			return cloneSet(value, depth, references, flat);
 
 		case isArrayOrPlainObject(value):
-			return clonePlainObject(value, depth, references);
+			return cloneObject(value, depth, references, flat);
 
 		case isTypedArray(value):
 			return cloneTypedArray(value, depth, references);
@@ -239,10 +249,24 @@ function cloneValue(value: unknown, depth: number, references: WeakMap<WeakKey,
 	}
 }
 
+/**
+ * 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
+ */
+export function copy<Value>(value: Value): Value {
+	return cloneValue(value, 0, new WeakMap(), true) as 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
  */
 export function deregisterCloner<Instance>(constructor: Constructor<Instance>): void {
@@ -252,9 +276,10 @@ export function deregisterCloner<Instance>(constructor: Constructor<Instance>):
 /**
  * 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`)_
  */
 export function registerCloner<Instance>(
 	constructor: Constructor<Instance>,

package/src/value/collection.ts

@@ -1,16 +1,18 @@
 import {equal} from '../internal/value/equal';
 
 /**
- * Does the value exist for a key in a map?
- * @param map Map to check in
+ * Does the value exist for a key in a _Map_?
+ *
+ * @param map _Map_ to check in
  * @param value Value to check for
  * @returns `true` if the value exists, otherwise `false`
  */
 export function inMap<Value>(map: Map<unknown, Value>, value: Value): boolean;
 
 /**
- * Does the value exist for a key in a map?
- * @param map Map to check in
+ * Does the value exist for a key in a _Map_?
+ *
+ * @param map _Map_ to check in
  * @param value Value to check for
  * @param key To return the key for the value
  * @returns The key for the value if it exists, otherwise `undefined`
@@ -36,8 +38,9 @@ export function inMap<Key, Value>(map: Map<Key, Value>, value: Value, key?: unkn
 }
 
 /**
- * Does the value exist in a set?
- * @param set Set to check in
+ * Does the value exist in a _Set_?
+ *
+ * @param set _Set_ to check in
  * @param value Value to check for
  * @returns `true` if the value exists, otherwise `false`
  */

package/src/value/diff.ts

@@ -27,7 +27,8 @@ export type DiffResult<First, Second = First> = {
 	 */
 	type: DiffType;
 	/**
-	 * - The differences between the two values
+	 * The differences between the two values
+	 *
 	 * - Keys are in dot notation
 	 * - Values are objects with `from` and `to` properties
 	 */
@@ -68,6 +69,7 @@ type Parameters = {
 
 /**
  * Find the differences between two values
+ *
  * @param first First value
  * @param second Second value
  * @param options Comparison options