@oscarpalmer/atoms 0.193.0 → 0.194.0

package/src/string/index.ts

@@ -1,199 +0,0 @@
-import {isTemplateStringsArray} from '../internal/is';
-import {interpolate} from '../internal/string';
-
-// #region Functions
-
-/**
- * Dedent a string template, removing common leading whitespace from each line
- *
- * @returns Dedented string
- */
-export 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
- */
-export function dedent(value: string): string;
-
-export function dedent(value: string | TemplateStringsArray, ...values: unknown[]): string {
-	let actual: string;
-
-	if (isTemplateStringsArray(value)) {
-		actual = interpolate(value, values);
-	} else {
-		actual = value;
-	}
-
-	if (typeof actual !== 'string') {
-		return '';
-	}
-
-	const lines = actual.split('\n');
-	const {length} = lines;
-
-	if (length === 1) {
-		return actual.trim();
-	}
-
-	const lastIndex = length - 1;
-
-	const lengths: number[] = [];
-
-	for (let index = 0; index < length; index += 1) {
-		const [, indentation] = /^(\s+)/.exec(lines[index]) ?? [];
-
-		if (indentation != null) {
-			lengths.push(indentation.length);
-		}
-	}
-
-	if (lengths.length === 0) {
-		return actual.trim();
-	}
-
-	const minimum = Math.min(...lengths);
-
-	const pattern = new RegExp(`^\\s{0,${minimum}}`);
-
-	let result = '';
-
-	for (let index = 0; index < length; index += 1) {
-		const line = lines[index];
-
-		result += line.replace(pattern, '') + (index === lastIndex ? '' : '\n');
-	}
-
-	return result.trim();
-}
-
-/**
- * Get a new UUID string _(version 4)_ for use in _HTML_
- *
- * @param html Use _HTML_-friendly format
- * @returns UUID string
- */
-export function getUuid(html: true): string;
-
-/**
- * Get a new UUID string _(version 4)_
- *
- * @returns UUID string
- */
-export function getUuid(): string;
-
-/**
- * Get a new UUID string _(version 4)_
- *
- * @returns UUID string
- */
-export function getUuid(html?: unknown): string {
-	const forHTML = html === true;
-
-	while (true) {
-		const bytes = new Uint8Array(16);
-
-		crypto.getRandomValues(bytes);
-
-		bytes[6] = (bytes[6] & 0x0f) | 0x40;
-
-		bytes[8] = (bytes[8] & 0x3f) | 0x80;
-
-		const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, ZERO)).join('');
-
-		const first = hex.substring(0, 8);
-
-		if (forHTML && NUMERICAL_PREFIX_PATTERN.test(first)) {
-			continue;
-		}
-
-		return [
-			first,
-			hex.substring(8, 12),
-			hex.substring(12, 16),
-			hex.substring(16, 20),
-			hex.substring(20, 32),
-		].join(forHTML ? DELIMITER_UUID_HTML : DELIMITER_UUID_DEFAULT);
-	}
-}
-
-/**
- * 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
- */
-export function parse(
-	value: string,
-	reviver?: (this: unknown, key: string, value: unknown) => unknown,
-): unknown {
-	try {
-		return JSON.parse(value, reviver);
-	} catch {
-		return undefined;
-	}
-}
-
-/**
- * Trim a string _(removing whitespace from both ends)_
- *
- * @param value String to trim
- * @returns Trimmed string
- */
-export function trim(value: string): string {
-	return typeof value === 'string' ? value.trim() : '';
-}
-
-/**
- * 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
- * @returns Truncated string
- */
-export function truncate(value: string, length: number, suffix?: string): string {
-	if (typeof value !== 'string' || typeof length !== 'number' || length === 0) {
-		return '';
-	}
-
-	if (length >= value.length) {
-		return value;
-	}
-
-	const actualSuffix = typeof suffix === 'string' ? suffix : '';
-	const actualSuffixLength = actualSuffix.length;
-
-	if (length <= actualSuffixLength) {
-		return actualSuffix;
-	}
-
-	const truncatedLength = length - actualSuffixLength;
-
-	return `${value.slice(0, truncatedLength)}${actualSuffix}`;
-}
-
-// #endregion
-
-// #region Variables
-
-const DELIMITER_UUID_DEFAULT = '-';
-
-const DELIMITER_UUID_HTML = '_';
-
-const NUMERICAL_PREFIX_PATTERN = /^\d/;
-
-const ZERO = '0';
-
-// #endregion
-
-// #endregion
-
-// #region Exports
-
-export {getString, join, words} from '../internal/string';
-
-// #endregion

package/src/string/match.ts

@@ -1,80 +0,0 @@
-import {memoize, type Memoized} from '../function/memoize';
-
-// #region Types
-
-type Match = 'endsWith' | 'includes' | 'startsWith';
-
-// #endregion
-
-// #region Functions
-
-/**
- * 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`)_
- * @returns `true` if the string ends with the given substring, otherwise `false`
- */
-export function endsWith(haystack: string, needle: string, ignoreCase?: boolean): boolean {
-	return match(MATCH_ENDS_WITH, haystack, needle, ignoreCase === true);
-}
-
-/**
- * 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`)_
- * @returns `true` if the string includes the given substring, otherwise `false`
- */
-export function includes(haystack: string, needle: string, ignoreCase?: boolean): boolean {
-	return match(MATCH_INCLUDES, haystack, needle, ignoreCase === true);
-}
-
-function match(type: Match, haystack: string, needle: string, ignoreCase: boolean): boolean {
-	if (typeof haystack !== 'string' || typeof needle !== 'string') {
-		return false;
-	}
-
-	matchMemoizers[type] ??= memoize(matchCallback.bind(type));
-
-	return matchMemoizers[type].run(haystack, needle, ignoreCase);
-}
-
-function matchCallback(
-	this: Match,
-	haystack: string,
-	needle: string,
-	ignoreCase: boolean,
-): boolean {
-	return (ignoreCase ? haystack.toLocaleLowerCase() : haystack)[this](
-		ignoreCase ? needle.toLocaleLowerCase() : needle,
-	);
-}
-
-/**
- * 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`)_
- * @returns `true` if the string starts with the given substring, otherwise `false`
- */
-export function startsWith(haystack: string, needle: string, ignoreCase?: boolean): boolean {
-	return match(MATCH_STARTS_WITH, haystack, needle, ignoreCase === true);
-}
-
-// #endregion
-
-// #region Variables
-
-const MATCH_ENDS_WITH: Match = 'endsWith';
-
-const MATCH_INCLUDES: Match = 'includes';
-
-const MATCH_STARTS_WITH: Match = 'startsWith';
-
-const matchMemoizers: Partial<Record<Match, Memoized<typeof matchCallback>>> = {};
-
-// #endregion

package/src/string/normalize.ts

@@ -1,205 +0,0 @@
-import {memoize, type Memoized} from '../function/memoize';
-import {isPlainObject} from '../internal/is';
-import {lowerCase} from './case';
-
-// #region Types
-
-/**
- * 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
-	 */
-	(value: string): string;
-};
-
-type Options = Required<NormalizeOptions>;
-
-// #endregion
-
-// #region Functions
-
-/**
- * Deburr a string, removing diacritical marks
- *
- * @param value String to deburr
- * @returns Deburred string
- */
-export function deburr(value: string): string {
-	if (typeof value !== 'string') {
-		return '';
-	}
-
-	deburrMemoizer ??= memoize(value => {
-		let deburred = value.normalize(DEBURR_NORMALIZATION).replace(DEBURR_PATTERN_SIMPLE, '');
-
-		deburred = deburred.replace(
-			DEBURR_PATTERN_CHARACTERS,
-			(_, character) => DEBURR_CHARACTERS[character as keyof typeof DEBURR_CHARACTERS],
-		);
-
-		return deburred;
-	});
-
-	return deburrMemoizer.run(value);
-}
-
-function getNormalizeOptions(input?: NormalizeOptions): Options {
-	const options = isPlainObject(input) ? input : {};
-
-	return {
-		deburr: options.deburr !== false,
-		lowerCase: options.lowerCase !== false,
-		special: options.special === true,
-		trim: options.trim !== false,
-		whitespace: options.whitespace !== false,
-	};
-}
-
-/**
- * Initialize a string normalizer
- *
- * _Available as `initializeNormalizer` and `normalize.initialize`_
- *
- * @param options Normalization options
- * @returns Normalizer function
- */
-export function initializeNormalizer(options?: NormalizeOptions): Normalizer {
-	const normalization = getNormalizeOptions(options);
-
-	return (value: string) => normalizeString(value, normalization);
-}
-
-/**
- * Normalize a string
- *
- * _By default, the string will be trimmed, deburred, and then lowercased_
- *
- * @param value String to normalize
- * @param options Normalization options
- * @returns Normalized string
- */
-export function normalize(value: string, options?: NormalizeOptions): string {
-	return normalizeString(value, getNormalizeOptions(options));
-}
-
-normalize.initialize = initializeNormalizer;
-
-function normalizeString(value: string, options: Options): string {
-	if (typeof value !== 'string') {
-		return '';
-	}
-
-	let result = value;
-
-	if (options.trim) {
-		result = result.trim();
-	}
-
-	if (options.whitespace) {
-		result = result.replace(WHITESPACE_PATTERN, WHITESPACE_REPLACEMENT);
-	}
-
-	if (options.deburr) {
-		result = deburr(result);
-	}
-
-	if (options.lowerCase) {
-		result = lowerCase(result);
-	}
-
-	if (options.special) {
-		result = result.replace(SPECIAL_PATTERN, SPECIAL_REPLACEMENT);
-	}
-
-	return result.normalize(NORMALIZATION_NORMALIZATION);
-}
-
-// #endregion
-
-// #region Variables
-
-const 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 DEBURR_NORMALIZATION = 'NFD';
-
-const DEBURR_PATTERN_CHARACTERS = new RegExp(`(${Object.keys(DEBURR_CHARACTERS).join('|')})`, 'g');
-
-const DEBURR_PATTERN_SIMPLE = /[\u0300-\u036f]/g;
-
-const NORMALIZATION_NORMALIZATION = 'NFC';
-
-const SPECIAL_PATTERN = /[\p{P}\p{S}]/gu;
-
-const SPECIAL_REPLACEMENT = '';
-
-const WHITESPACE_PATTERN = /\s+/g;
-
-const WHITESPACE_REPLACEMENT = ' ';
-
-let deburrMemoizer: Memoized<typeof deburr>;
-
-// #endregion

package/src/string/template.ts

@@ -1,161 +0,0 @@
-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
- */
-export type TemplateOptions = {
-	/**
-	 * Ignore case when searching for variables?
-	 */
-	ignoreCase?: boolean;
-	/**
-	 * Custom pattern for outputting variables
-	 */
-	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 template string with variables
- */
-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) : {};
-
-	return {
-		ignoreCase: options.ignoreCase === true,
-		pattern: options.pattern instanceof RegExp ? options.pattern : EXPRESSION_VARIABLE,
-	};
-}
-
-function handleTemplate(
-	value: string,
-	pattern: RegExp,
-	ignoreCase: boolean,
-	variables?: PlainObject,
-): string {
-	if (typeof value !== 'string') {
-		return '';
-	}
-
-	if (typeof variables !== 'object' || variables === null || Object.keys(variables).length === 0) {
-		return value;
-	}
-
-	const values: Record<string, string> = {};
-
-	return value.replace(pattern, (_, key) => {
-		if (values[key] == null) {
-			const templateValue = getValue(variables, key, ignoreCase);
-
-			values[key] = templateValue == null ? '' : getString(templateValue);
-		}
-
-		return values[key];
-	});
-}
-
-/**
- * Create a _Templater_ with predefined options
- *
- * _Available as `initializeTemplater` and `template.initialize`_
- *
- * @param options Templating options
- * @returns _Templater_ function
- */
-export function initializeTemplater(options?: Partial<TemplateOptions>): Templater {
-	const {ignoreCase, pattern} = getTemplateOptions(options);
-
-	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
- * @returns Templated string
- */
-export function template(
-	value: string,
-	variables?: PlainObject,
-	options?: Partial<TemplateOptions>,
-): 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, parameters[0] as PlainObject);
-}
-
-template.initialize = initializeTemplater;
-
-// #endregion
-
-// #region Variables
-
-const EXPRESSION_VARIABLE = /{{([\s\S]+?)}}/g;
-
-// #endregion