@oscarpalmer/atoms 0.82.0 → 0.83.0

package/dist/color/hex.js

@@ -1,7 +1,7 @@
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-import { anyPattern, getNormalisedHex, hexToRgb } from "./functions.js";
+import { getNormalisedHex, anyPattern, hexToRgb } from "./functions.js";
 class HexColor {
   constructor(value) {
     __publicField(this, "state");

package/dist/i18n.cjs

@@ -0,0 +1,106 @@
+"use strict";
+var _a, _b, _c;
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const defaults = {
+  delimiter: "",
+  languages: {
+    fallback: null,
+    preferred: null
+  }
+};
+function getKey(value, languages) {
+  if ((languages == null ? void 0 : languages.fallback) == null && (languages == null ? void 0 : languages.preferred) == null) {
+    return;
+  }
+  const { fallback, preferred } = languages;
+  switch (true) {
+    case (preferred != null && preferred.full in value):
+      return preferred.full;
+    case (preferred != null && preferred.region != null && preferred.base in value):
+      return preferred.base;
+    case (fallback != null && fallback.full in value):
+      return fallback.full;
+    case (fallback != null && fallback.region != null && fallback.base in value):
+      return fallback.base;
+  }
+}
+function getLanguage(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const [full, base, region] = /^([a-z]{2,3})(?:-([A-Z]{2}))?$/.exec(value) ?? [];
+  if (full != null) {
+    return { base, full, region };
+  }
+}
+function getTranslation(value, key) {
+  if (typeof value !== "object" || value == null || key == null) {
+    return "";
+  }
+  const translation = value[key];
+  return typeof translation === "string" ? translation : String(translation);
+}
+function setLanguage(key, value) {
+  const language = getLanguage(value);
+  if (language != null) {
+    defaults.languages[key] = language;
+  }
+}
+function translate(value, options) {
+  return translateValue(value, null, null, options);
+}
+translate.configure = (configuration) => {
+  if (typeof configuration.delimiter === "string") {
+    defaults.delimiter = configuration.delimiter;
+  }
+  if (typeof configuration.fallback === "string") {
+    setLanguage("fallback", configuration.fallback);
+  }
+  if (typeof configuration.language === "string") {
+    setLanguage("preferred", configuration.language);
+  }
+};
+translate.configuration = () => {
+  return {
+    delimiter: String(defaults.delimiter),
+    fallback: String(defaults.languages.fallback.full),
+    language: String(defaults.languages.preferred.full)
+  };
+};
+function translatePrimitive(value) {
+  let actual = value;
+  if (typeof value === "function") {
+    actual = value();
+  }
+  return actual == null ? "" : typeof actual === "string" ? actual : String(actual);
+}
+function translateTranslatable(value, delimiter, languages, options) {
+  let actualDelimiter = delimiter ?? defaults.delimiter;
+  let actualLanguages = languages;
+  if (options != null) {
+    actualDelimiter = typeof options.delimiter === "string" ? options.delimiter : defaults.delimiter;
+    actualLanguages = {
+      fallback: getLanguage(options.fallback),
+      preferred: getLanguage(options.language)
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => translateValue(item, actualDelimiter, actualLanguages)).filter((translated) => translated.trim().length > 0).join(actualDelimiter);
+  }
+  return getTranslation(
+    value,
+    getKey(value, actualLanguages) ?? getKey(value, defaults.languages)
+  );
+}
+function translateValue(value, delimiter, language, options) {
+  return typeof value !== "object" || value == null ? translatePrimitive(value) : translateTranslatable(
+    value,
+    delimiter,
+    language,
+    options
+  );
+}
+const defaultLanguage = (((_c = (_b = (_a = document == null ? void 0 : document.documentElement) == null ? void 0 : _a.lang) == null ? void 0 : _b.trim()) == null ? void 0 : _c.length) ?? 0) > 0 ? document.documentElement.lang : (navigator == null ? void 0 : navigator.language) ?? "en";
+setLanguage("fallback", defaultLanguage);
+setLanguage("preferred", defaultLanguage);
+exports.translate = translate;

package/dist/i18n.js

@@ -0,0 +1,106 @@
+var _a, _b, _c;
+const defaults = {
+  delimiter: "",
+  languages: {
+    fallback: null,
+    preferred: null
+  }
+};
+function getKey(value, languages) {
+  if ((languages == null ? void 0 : languages.fallback) == null && (languages == null ? void 0 : languages.preferred) == null) {
+    return;
+  }
+  const { fallback, preferred } = languages;
+  switch (true) {
+    case (preferred != null && preferred.full in value):
+      return preferred.full;
+    case (preferred != null && preferred.region != null && preferred.base in value):
+      return preferred.base;
+    case (fallback != null && fallback.full in value):
+      return fallback.full;
+    case (fallback != null && fallback.region != null && fallback.base in value):
+      return fallback.base;
+  }
+}
+function getLanguage(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const [full, base, region] = /^([a-z]{2,3})(?:-([A-Z]{2}))?$/.exec(value) ?? [];
+  if (full != null) {
+    return { base, full, region };
+  }
+}
+function getTranslation(value, key) {
+  if (typeof value !== "object" || value == null || key == null) {
+    return "";
+  }
+  const translation = value[key];
+  return typeof translation === "string" ? translation : String(translation);
+}
+function setLanguage(key, value) {
+  const language = getLanguage(value);
+  if (language != null) {
+    defaults.languages[key] = language;
+  }
+}
+function translate(value, options) {
+  return translateValue(value, null, null, options);
+}
+translate.configure = (configuration) => {
+  if (typeof configuration.delimiter === "string") {
+    defaults.delimiter = configuration.delimiter;
+  }
+  if (typeof configuration.fallback === "string") {
+    setLanguage("fallback", configuration.fallback);
+  }
+  if (typeof configuration.language === "string") {
+    setLanguage("preferred", configuration.language);
+  }
+};
+translate.configuration = () => {
+  return {
+    delimiter: String(defaults.delimiter),
+    fallback: String(defaults.languages.fallback.full),
+    language: String(defaults.languages.preferred.full)
+  };
+};
+function translatePrimitive(value) {
+  let actual = value;
+  if (typeof value === "function") {
+    actual = value();
+  }
+  return actual == null ? "" : typeof actual === "string" ? actual : String(actual);
+}
+function translateTranslatable(value, delimiter, languages, options) {
+  let actualDelimiter = delimiter ?? defaults.delimiter;
+  let actualLanguages = languages;
+  if (options != null) {
+    actualDelimiter = typeof options.delimiter === "string" ? options.delimiter : defaults.delimiter;
+    actualLanguages = {
+      fallback: getLanguage(options.fallback),
+      preferred: getLanguage(options.language)
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => translateValue(item, actualDelimiter, actualLanguages)).filter((translated) => translated.trim().length > 0).join(actualDelimiter);
+  }
+  return getTranslation(
+    value,
+    getKey(value, actualLanguages) ?? getKey(value, defaults.languages)
+  );
+}
+function translateValue(value, delimiter, language, options) {
+  return typeof value !== "object" || value == null ? translatePrimitive(value) : translateTranslatable(
+    value,
+    delimiter,
+    language,
+    options
+  );
+}
+const defaultLanguage = (((_c = (_b = (_a = document == null ? void 0 : document.documentElement) == null ? void 0 : _a.lang) == null ? void 0 : _b.trim()) == null ? void 0 : _c.length) ?? 0) > 0 ? document.documentElement.lang : (navigator == null ? void 0 : navigator.language) ?? "en";
+setLanguage("fallback", defaultLanguage);
+setLanguage("preferred", defaultLanguage);
+export {
+  translate
+};

package/dist/index.cjs

@@ -4,6 +4,7 @@ const array_index = require("./array/index.cjs");
 const color_index = require("./color/index.cjs");
 const emitter = require("./emitter.cjs");
 const _function = require("./function.cjs");
+const i18n = require("./i18n.cjs");
 const is = require("./is.cjs");
 const logger = require("./logger.cjs");
 const math = require("./math.cjs");
@@ -54,6 +55,7 @@ exports.debounce = _function.debounce;
 exports.memoise = _function.memoise;
 exports.noop = _function.noop;
 exports.throttle = _function.throttle;
+exports.translate = i18n.translate;
 exports.isArrayOrPlainObject = is.isArrayOrPlainObject;
 exports.isEmpty = is.isEmpty;
 exports.isKey = is.isKey;
@@ -79,7 +81,7 @@ exports.toQuery = query.toQuery;
 exports.queue = queue.queue;
 exports.getRandomBoolean = random.getRandomBoolean;
 exports.getRandomCharacters = random.getRandomCharacters;
-exports.getRandomColour = random.getRandomColour;
+exports.getRandomColor = random.getRandomColor;
 exports.getRandomFloat = random.getRandomFloat;
 exports.getRandomHex = random.getRandomHex;
 exports.getRandomInteger = random.getRandomInteger;

package/dist/index.js

@@ -2,13 +2,14 @@ import { flatten, push } from "./array/index.js";
 import { getForegroundColor } from "./color/index.js";
 import { emitter } from "./emitter.js";
 import { debounce, memoise, noop, throttle } from "./function.js";
+import { translate } from "./i18n.js";
 import { isArrayOrPlainObject, isEmpty, isKey, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isPlainObject, isPrimitive } from "./is.js";
 import { logger } from "./logger.js";
 import { average, max, min, round, sum } from "./math.js";
 import { between, clamp, getNumber } from "./number.js";
 import { fromQuery, toQuery } from "./query.js";
 import { queue } from "./queue.js";
-import { getRandomBoolean, getRandomCharacters, getRandomColour, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems } from "./random.js";
+import { getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems } from "./random.js";
 import { SizedMap, SizedSet } from "./sized.js";
 import { createUuid, getString, join, parse, truncate, words } from "./string/index.js";
 import "./touch.js";
@@ -77,7 +78,7 @@ export {
   getRGBColor,
   getRandomBoolean,
   getRandomCharacters,
-  getRandomColour,
+  getRandomColor,
   getRandomFloat,
   getRandomHex,
   getRandomInteger,
@@ -134,6 +135,7 @@ export {
   toMap,
   toQuery,
   toRecord,
+  translate,
   truncate,
   unique,
   unsmush,

package/dist/random.cjs

@@ -15,7 +15,7 @@ function getRandomCharacters(length, selection) {
   }
   return characters;
 }
-function getRandomColour() {
+function getRandomColor() {
   return `#${Array.from({ length: 6 }, getRandomHex).join("")}`;
 }
 function getRandomFloat(min, max) {
@@ -39,7 +39,7 @@ function getRandomItems(array, amount) {
 }
 exports.getRandomBoolean = getRandomBoolean;
 exports.getRandomCharacters = getRandomCharacters;
-exports.getRandomColour = getRandomColour;
+exports.getRandomColor = getRandomColor;
 exports.getRandomFloat = getRandomFloat;
 exports.getRandomHex = getRandomHex;
 exports.getRandomInteger = getRandomInteger;

package/dist/random.js

@@ -13,7 +13,7 @@ function getRandomCharacters(length, selection) {
   }
   return characters;
 }
-function getRandomColour() {
+function getRandomColor() {
   return `#${Array.from({ length: 6 }, getRandomHex).join("")}`;
 }
 function getRandomFloat(min, max) {
@@ -38,7 +38,7 @@ function getRandomItems(array, amount) {
 export {
   getRandomBoolean,
   getRandomCharacters,
-  getRandomColour,
+  getRandomColor,
   getRandomFloat,
   getRandomHex,
   getRandomInteger,

package/package.json

@@ -9,13 +9,13 @@
 	"description": "Atomic utilities for making your JavaScript better.",
 	"devDependencies": {
 		"@biomejs/biome": "^1.9",
-		"@types/node": "^22.12",
+		"@types/node": "^22.13",
 		"@vitest/coverage-istanbul": "^3",
 		"dts-bundle-generator": "^9.5",
 		"glob": "^11",
-		"happy-dom": "^16.7",
+		"happy-dom": "^17",
 		"typescript": "^5.7",
-		"vite": "^6",
+		"vite": "^6.1",
 		"vitest": "^3"
 	},
 	"exports": {
@@ -70,6 +70,16 @@
 				"default": "./dist/function.cjs"
 			}
 		},
+		"./i18n": {
+			"import": {
+				"types": "./types/i18n.d.ts",
+				"default": "./dist/i18n.js"
+			},
+			"require": {
+				"types": "./types/i18n.d.cts",
+				"default": "./dist/i18n.cjs"
+			}
+		},
 		"./is": {
 			"import": {
 				"types": "./types/is.d.ts",
@@ -179,15 +189,8 @@
 			}
 		}
 	},
-	"files": [
-		"dist",
-		"src",
-		"types"
-	],
-	"keywords": [
-		"helper",
-		"utility"
-	],
+	"files": ["dist", "src", "types"],
+	"keywords": ["helper", "utility"],
 	"license": "MIT",
 	"main": "./dist/index.cjs",
 	"module": "./dist/index.js",
@@ -205,5 +208,5 @@
 	},
 	"type": "module",
 	"types": "./types/index.d.cts",
-	"version": "0.82.0"
+	"version": "0.83.0"
 }

package/src/i18n.ts

@@ -0,0 +1,272 @@
+import type {PlainObject} from './models';
+
+type Defaults = {
+	/**
+	 * Delimiter to use when translating an array of translatable values
+	 */
+	delimiter: string;
+	/**
+	 * Languages to use when translating
+	 */
+	languages: Languages;
+};
+
+type Language = {
+	/**
+	 * Language code _(e.g. `en`, `es`, `fr`, `ja`, `zh`)_
+	 */
+	readonly base: string;
+	/**
+	 * Language code with region _(e.g. `en-US`, `es-ES`, `fr-FR`, `ja-JP`, `zh-CN`)_
+	 */
+	readonly full: string;
+	/**
+	 * Region code _(e.g. `US`, `ES`, `FR`, `JP`, `CN`)_
+	 */
+	readonly region?: string;
+};
+
+type Languages = {
+	/**
+	 * Language to use when no translation is found
+	 */
+	fallback: Language;
+	/**
+	 * Language to use when translating
+	 */
+	preferred: Language;
+};
+
+type TranslateConfiguration = TranslateOptions;
+
+export type TranslateOptions = {
+	/**
+	 * Delimiter to use when translating an array of translatable values
+	 */
+	delimiter: string;
+	/**
+	 * Language to use when no translation is found
+	 */
+	fallback: string;
+	/**
+	 * Language to use when translating
+	 */
+	language: string;
+};
+
+/**
+ * A translatable object
+ */
+export type Translatable = Record<string, unknown>;
+
+const defaults: Defaults = {
+	delimiter: '',
+	languages: {
+		fallback: null as never,
+		preferred: null as never,
+	},
+};
+
+/**
+ * Get translation key for a translatable object
+ */
+function getKey(
+	value: PlainObject,
+	languages: Partial<Languages>,
+): string | undefined {
+	if (languages?.fallback == null && languages?.preferred == null) {
+		return;
+	}
+
+	const {fallback, preferred} = languages;
+
+	switch (true) {
+		case preferred != null && preferred.full in value:
+			return preferred.full;
+
+		case preferred != null &&
+			preferred.region != null &&
+			preferred.base in value:
+			return preferred.base;
+
+		case fallback != null && fallback.full in value:
+			return fallback.full;
+
+		case fallback != null && fallback.region != null && fallback.base in value:
+			return fallback.base;
+	}
+}
+
+/**
+ * Get a _Language_ from a value
+ */
+function getLanguage(value: unknown): Language | undefined {
+	if (typeof value !== 'string') {
+		return;
+	}
+
+	const [full, base, region] =
+		/^([a-z]{2,3})(?:-([A-Z]{2}))?$/.exec(value) ?? [];
+
+	if (full != null) {
+		return {base, full, region};
+	}
+}
+
+/**
+ * Get translation for a key from a translatable object
+ */
+function getTranslation(value: unknown, key?: string): string {
+	if (typeof value !== 'object' || value == null || key == null) {
+		return '';
+	}
+
+	const translation = (value as PlainObject)[key];
+
+	return typeof translation === 'string' ? translation : String(translation);
+}
+
+/**
+ * Set a _Language_ for a key
+ */
+function setLanguage(key: keyof Languages, value: string): void {
+	const language = getLanguage(value);
+
+	if (language != null) {
+		defaults.languages[key] = language;
+	}
+}
+
+/**
+ * Translates a value _(with optional options, but defaulting to configuration)_
+ */
+export function translate(
+	value: unknown,
+	options?: Partial<TranslateOptions>,
+): string;
+
+/**
+ * Translates an array of values _(with optional options, but defaulting to configuration)_
+ */
+export function translate(
+	value: unknown[],
+	options?: Partial<TranslateOptions>,
+): string;
+
+export function translate(
+	value: unknown | unknown[],
+	options?: Partial<TranslateOptions>,
+): string {
+	return translateValue(value, null as never, null as never, options);
+}
+
+/**
+ * Configures the translation options _(used as defaults when translating)_
+ */
+translate.configure = (
+	configuration: Partial<TranslateConfiguration>,
+): void => {
+	if (typeof configuration.delimiter === 'string') {
+		defaults.delimiter = configuration.delimiter;
+	}
+
+	if (typeof configuration.fallback === 'string') {
+		setLanguage('fallback', configuration.fallback);
+	}
+
+	if (typeof configuration.language === 'string') {
+		setLanguage('preferred', configuration.language);
+	}
+};
+
+/**
+ * Gets the current translation configuration
+ */
+translate.configuration = (): TranslateConfiguration => {
+	return {
+		delimiter: String(defaults.delimiter),
+		fallback: String(defaults.languages.fallback.full),
+		language: String(defaults.languages.preferred.full),
+	};
+};
+
+/**
+ * Translates a primitive value _(into a string)_
+ */
+function translatePrimitive(value: unknown): string {
+	let actual = value;
+
+	if (typeof value === 'function') {
+		actual = value();
+	}
+
+	return actual == null
+		? ''
+		: typeof actual === 'string'
+			? actual
+			: String(actual);
+}
+
+/**
+ * Translates a translatable object _(or array of translatable objects)_ into a string
+ */
+function translateTranslatable(
+	value: PlainObject | PlainObject[],
+	delimiter: string,
+	languages: Partial<Languages>,
+	options?: Partial<TranslateOptions>,
+): string {
+	let actualDelimiter = delimiter ?? defaults.delimiter;
+	let actualLanguages = languages;
+
+	if (options != null) {
+		actualDelimiter =
+			typeof options.delimiter === 'string'
+				? options.delimiter
+				: defaults.delimiter;
+
+		actualLanguages = {
+			fallback: getLanguage(options.fallback),
+			preferred: getLanguage(options.language),
+		};
+	}
+
+	if (Array.isArray(value)) {
+		return value
+			.map(item => translateValue(item, actualDelimiter, actualLanguages))
+			.filter(translated => translated.trim().length > 0)
+			.join(actualDelimiter);
+	}
+
+	return getTranslation(
+		value,
+		getKey(value, actualLanguages) ?? getKey(value, defaults.languages),
+	);
+}
+
+/**
+ * Translates a value _(into a string)_
+ */
+function translateValue(
+	value: unknown,
+	delimiter: string,
+	language: Partial<Languages>,
+	options?: Partial<TranslateOptions>,
+): string {
+	return typeof value !== 'object' || value == null
+		? translatePrimitive(value)
+		: translateTranslatable(
+				value as PlainObject | PlainObject[],
+				delimiter,
+				language,
+				options,
+			);
+}
+
+const defaultLanguage =
+	(document?.documentElement?.lang?.trim()?.length ?? 0) > 0
+		? document.documentElement.lang
+		: (navigator?.language ?? 'en');
+
+setLanguage('fallback', defaultLanguage);
+setLanguage('preferred', defaultLanguage);

package/src/index.ts

@@ -2,6 +2,7 @@ export * from './array/index';
 export * from './color/index';
 export * from './emitter';
 export * from './function';
+export * from './i18n';
 export * from './is';
 export * from './logger';
 export * from './math';

package/src/random.ts

@@ -34,9 +34,9 @@ export function getRandomCharacters(
 }
 
 /**
- * Get a random hexadecimal colour
+ * Get a random hexadecimal color
  */
-export function getRandomColour(): string {
+export function getRandomColor(): string {
 	return `#${Array.from({length: 6}, getRandomHex).join('')}`;
 }