@oscarpalmer/atoms 0.42.0 → 0.43.0

package/dist/js/index.js

@@ -597,6 +597,14 @@ function getString(value) {
 function titleCase(value) {
   return value.split(/\s+/).map((word) => capitalise(word)).join(" ");
 }
+function truncate(value, length, suffix) {
+  const suffixLength = suffix?.length ?? 0;
+  const truncatedLength = length - suffixLength;
+  return value.length <= length ? value : `${value.slice(0, truncatedLength)}${suffix ?? ""}`;
+}
+function words(value) {
+  return [];
+}
 
 // src/js/is.ts
 function isArrayOrPlainObject(value) {
@@ -637,6 +645,79 @@ function isPlainObject(value) {
 function isPrimitive(value) {
   return value == null || /^(bigint|boolean|number|string|symbol)$/.test(typeof value);
 }
+// src/js/log.ts
+var time = function(label) {
+  const started = log.enabled;
+  let stopped = false;
+  if (started) {
+    console.time(label);
+  }
+  return Object.create({
+    log() {
+      if (started && log.enabled) {
+        console.timeLog(label);
+      }
+    },
+    stop() {
+      if (started && !stopped) {
+        stopped = true;
+        console.timeEnd(label);
+      }
+    }
+  });
+};
+var work = function(type, data) {
+  if (log.enabled) {
+    console[type](...data);
+  }
+};
+var types = new Set([
+  "dir",
+  "debug",
+  "error",
+  "info",
+  "table",
+  "trace",
+  "warn"
+]);
+var log = (() => {
+  let enabled = true;
+  function instance(...data) {
+    work("log", data);
+  }
+  Object.defineProperties(instance, {
+    enabled: {
+      get() {
+        return enabled;
+      },
+      set(value) {
+        enabled = value;
+      }
+    },
+    time: {
+      value: time
+    }
+  });
+  for (const type of types) {
+    Object.defineProperty(instance, type, {
+      value: (...data) => work(type, data)
+    });
+  }
+  return instance;
+})();
+// src/js/math.ts
+function average(values) {
+  return values.length > 0 ? sum(values) / values.length : Number.NaN;
+}
+function max(values) {
+  return values.length > 0 ? Math.max(...values) : Number.NaN;
+}
+function min(values) {
+  return values.length > 0 ? Math.min(...values) : Number.NaN;
+}
+function sum(values) {
+  return values.reduce((a, b) => a + b, 0);
+}
 // src/js/queue.ts
 function queue(callback) {
   _atomic_queued.add(callback);
@@ -670,12 +751,12 @@ function getRandomDate(earliest, latest) {
   const latestTime = latest?.getTime() ?? 8640000000000000;
   return new Date(getRandomInteger(earliestTime, latestTime));
 }
-function getRandomFloat(min, max) {
-  const minimum = min ?? Number.MIN_SAFE_INTEGER;
-  return Math.random() * ((max ?? Number.MAX_SAFE_INTEGER) - minimum) + minimum;
+function getRandomFloat(min2, max2) {
+  const minimum = min2 ?? Number.MIN_SAFE_INTEGER;
+  return Math.random() * ((max2 ?? Number.MAX_SAFE_INTEGER) - minimum) + minimum;
 }
-function getRandomInteger(min, max) {
-  return Math.floor(getRandomFloat(min, max));
+function getRandomInteger(min2, max2) {
+  return Math.floor(getRandomFloat(min2, max2));
 }
 function getRandomHex() {
   return "0123456789ABCDEF"[getRandomInteger(0, 16)];
@@ -718,13 +799,13 @@ var timer = function(type, callback, options) {
   };
   const instance = Object.create({
     restart() {
-      return work("restart", this, state, extended);
+      return work2("restart", this, state, extended);
     },
     start() {
-      return work("start", this, state, extended);
+      return work2("start", this, state, extended);
     },
     stop() {
-      return work("stop", this, state, extended);
+      return work2("stop", this, state, extended);
     }
   });
   Object.defineProperties(instance, {
@@ -795,7 +876,7 @@ function when(condition, options) {
   });
   return instance;
 }
-var work = function(type, timer2, state, options) {
+var work2 = function(type, timer2, state, options) {
   if (type === "start" && state.active || type === "stop" && !state.active) {
     return timer2;
   }
@@ -1063,10 +1144,13 @@ function setValue(data, path, value, ignoreCase) {
   return data;
 }
 export {
+  words,
   when,
   wait,
   unique,
+  truncate,
   titleCase,
+  sum,
   splice,
   setValue,
   rgbToHsl,
@@ -1074,7 +1158,10 @@ export {
   repeat,
   queue,
   push,
+  min,
   merge,
+  max,
+  log,
   isWhen,
   isWaited,
   isTimer,
@@ -1126,6 +1213,7 @@ export {
   capitalise as capitalize,
   capitalise,
   between,
+  average,
   findElements as $$,
   findElement as $
 };

package/dist/js/index.mjs

@@ -5,6 +5,8 @@ export * from "./element/index";
 export * from "./element/focusable";
 export * from "./event";
 export * from "./is";
+export * from "./log";
+export * from "./math";
 export * from "./models";
 export * from "./number";
 export * from "./queue";

package/dist/js/log.js

@@ -0,0 +1,63 @@
+// src/js/log.ts
+var time = function(label) {
+  const started = log.enabled;
+  let stopped = false;
+  if (started) {
+    console.time(label);
+  }
+  return Object.create({
+    log() {
+      if (started && log.enabled) {
+        console.timeLog(label);
+      }
+    },
+    stop() {
+      if (started && !stopped) {
+        stopped = true;
+        console.timeEnd(label);
+      }
+    }
+  });
+};
+var work = function(type, data) {
+  if (log.enabled) {
+    console[type](...data);
+  }
+};
+var types = new Set([
+  "dir",
+  "debug",
+  "error",
+  "info",
+  "table",
+  "trace",
+  "warn"
+]);
+var log = (() => {
+  let enabled = true;
+  function instance(...data) {
+    work("log", data);
+  }
+  Object.defineProperties(instance, {
+    enabled: {
+      get() {
+        return enabled;
+      },
+      set(value) {
+        enabled = value;
+      }
+    },
+    time: {
+      value: time
+    }
+  });
+  for (const type of types) {
+    Object.defineProperty(instance, type, {
+      value: (...data) => work(type, data)
+    });
+  }
+  return instance;
+})();
+export {
+  log
+};

package/dist/js/log.mjs

@@ -0,0 +1,63 @@
+// src/js/log.ts
+var time = function(label) {
+  const started = log.enabled;
+  let stopped = false;
+  if (started) {
+    console.time(label);
+  }
+  return Object.create({
+    log() {
+      if (started && log.enabled) {
+        console.timeLog(label);
+      }
+    },
+    stop() {
+      if (started && !stopped) {
+        stopped = true;
+        console.timeEnd(label);
+      }
+    }
+  });
+};
+var work = function(type, data) {
+  if (log.enabled) {
+    console[type](...data);
+  }
+};
+var types = new Set([
+  "dir",
+  "debug",
+  "error",
+  "info",
+  "table",
+  "trace",
+  "warn"
+]);
+var log = (() => {
+  let enabled = true;
+  function instance(...data) {
+    work("log", data);
+  }
+  Object.defineProperties(instance, {
+    enabled: {
+      get() {
+        return enabled;
+      },
+      set(value) {
+        enabled = value;
+      }
+    },
+    time: {
+      value: time
+    }
+  });
+  for (const type of types) {
+    Object.defineProperty(instance, type, {
+      value: (...data) => work(type, data)
+    });
+  }
+  return instance;
+})();
+export {
+  log
+};

package/dist/js/math.js

@@ -0,0 +1,19 @@
+// src/js/math.ts
+function average(values) {
+  return values.length > 0 ? sum(values) / values.length : Number.NaN;
+}
+function max(values) {
+  return values.length > 0 ? Math.max(...values) : Number.NaN;
+}
+function min(values) {
+  return values.length > 0 ? Math.min(...values) : Number.NaN;
+}
+function sum(values) {
+  return values.reduce((a, b) => a + b, 0);
+}
+export {
+  sum,
+  min,
+  max,
+  average
+};

package/dist/js/math.mjs

@@ -0,0 +1,19 @@
+// src/js/math.ts
+function average(values) {
+  return values.length > 0 ? sum(values) / values.length : Number.NaN;
+}
+function max(values) {
+  return values.length > 0 ? Math.max(...values) : Number.NaN;
+}
+function min(values) {
+  return values.length > 0 ? Math.min(...values) : Number.NaN;
+}
+function sum(values) {
+  return values.reduce((a, b) => a + b, 0);
+}
+export {
+  sum,
+  min,
+  max,
+  average
+};

package/dist/js/string.js

@@ -22,7 +22,17 @@ function getString(value) {
 function titleCase(value) {
   return value.split(/\s+/).map((word) => capitalise(word)).join(" ");
 }
+function truncate(value, length, suffix) {
+  const suffixLength = suffix?.length ?? 0;
+  const truncatedLength = length - suffixLength;
+  return value.length <= length ? value : `${value.slice(0, truncatedLength)}${suffix ?? ""}`;
+}
+function words(value) {
+  return [];
+}
 export {
+  words,
+  truncate,
   titleCase,
   getString,
   createUuid,

package/dist/js/string.mjs

@@ -22,7 +22,17 @@ function getString(value) {
 function titleCase(value) {
   return value.split(/\s+/).map((word) => capitalise(word)).join(" ");
 }
+function truncate(value, length, suffix) {
+  const suffixLength = suffix?.length ?? 0;
+  const truncatedLength = length - suffixLength;
+  return value.length <= length ? value : `${value.slice(0, truncatedLength)}${suffix ?? ""}`;
+}
+function words(value) {
+  return [];
+}
 export {
+  words,
+  truncate,
   titleCase,
   getString,
   createUuid,

package/package.json

@@ -130,5 +130,5 @@
 	},
 	"type": "module",
 	"types": "./types/index.d.ts",
-	"version": "0.42.0"
+	"version": "0.43.0"
 }

package/src/js/index.ts

@@ -4,6 +4,8 @@ export * from './element/index';
 export * from './element/focusable';
 export * from './event';
 export * from './is';
+export * from './log';
+export * from './math';
 export * from './models';
 export * from './number';
 export * from './queue';

package/src/js/is.ts

@@ -10,6 +10,9 @@ export function isArrayOrPlainObject(
 	return Array.isArray(value) || isPlainObject(value);
 }
 
+/**
+ * Is the array or object completely empty or only containing `null` or `undefined` values?
+ */
 export function isEmpty(value: ArrayOrPlainObject): boolean {
 	if (Array.isArray(value)) {
 		return (

package/src/js/log.ts

@@ -0,0 +1,140 @@
+/**
+ * Logs any number of values at the "log" log level
+ */
+type LogCallback = (...data: unknown[]) => void;
+
+type LogPrototype = {
+	/**
+	 * Is logging to the console enabled? _(defaults to `true`)_
+	 */
+	enabled: boolean;
+	/**
+	 * Logs the value and shows all its properties
+	 */
+	dir(value: unknown): void;
+	/**
+	 * Logs any number of values at the "debug" log level
+	 */
+	debug(...data: unknown[]): void;
+	/**
+	 * Logs any number of values at the "error" log level
+	 */
+	error(...data: unknown[]): void;
+	/**
+	 * Logs any number of values at the "info" log level
+	 */
+	info(...data: unknown[]): void;
+	/**
+	 * Logs data as a table, with optional properties to use as columns
+	 */
+	table(data: unknown, properties?: string[]): void;
+	/**
+	 * - Starts a logged timer with a label
+	 * - Returns a `Time`-object for logging the current duration of the timer and stopping the timer _(and logging the total duration)_
+	 */
+	time(label: string): Time;
+	/**
+	 * Logs any number of values together with a trace from where it was called
+	 */
+	trace(...data: unknown[]): void;
+	/**
+	 * Logs any number of values at the "warn" log level
+	 */
+	warn(...data: unknown[]): void;
+};
+
+type Time = {
+	/**
+	 * - Logs the current duration of the timer
+	 * - Ignored if logging is disabled
+	 */
+	log(): void;
+	/**
+	 * - Stops the timer and logs the total duration
+	 * - Will always log the total duration, even if logging is disabled
+	 */
+	stop(): void;
+};
+
+type Type =
+	| 'dir'
+	| 'debug'
+	| 'error'
+	| 'info'
+	| 'log'
+	| 'table'
+	| 'trace'
+	| 'warn';
+
+const types = new Set<Type>([
+	'dir',
+	'debug',
+	'error',
+	'info',
+	'table',
+	'trace',
+	'warn',
+]);
+
+const log = (() => {
+	let enabled = true;
+
+	function instance(...data: unknown[]): void {
+		work('log', data);
+	}
+
+	Object.defineProperties(instance, {
+		enabled: {
+			get() {
+				return enabled;
+			},
+			set(value: boolean) {
+				enabled = value;
+			},
+		},
+		time: {
+			value: time,
+		},
+	});
+
+	for (const type of types) {
+		Object.defineProperty(instance, type, {
+			value: (...data: unknown[]) => work(type, data),
+		});
+	}
+
+	return instance;
+})() as LogCallback & LogPrototype;
+
+function time(label: string): Time {
+	const started = log.enabled;
+
+	let stopped = false;
+
+	if (started) {
+		console.time(label);
+	}
+
+	return Object.create({
+		log() {
+			if (started && log.enabled) {
+				console.timeLog(label);
+			}
+		},
+		stop() {
+			if (started && !stopped) {
+				stopped = true;
+
+				console.timeEnd(label);
+			}
+		},
+	});
+}
+
+function work(type: Type, data: unknown[]): void {
+	if (log.enabled) {
+		console[type](...data);
+	}
+}
+
+export {log};

package/src/js/math.ts

@@ -0,0 +1,27 @@
+/**
+ * Get the average value from a list of numbers
+ */
+export function average(values: number[]): number {
+	return values.length > 0 ? sum(values) / values.length : Number.NaN;
+}
+
+/**
+ * Get the maximum value from a list of numbers
+ */
+export function max(values: number[]): number {
+	return values.length > 0 ? Math.max(...values) : Number.NaN;
+}
+
+/**
+ * Get the minimum value from a list of numbers
+ */
+export function min(values: number[]): number {
+	return values.length > 0 ? Math.min(...values) : Number.NaN;
+}
+
+/**
+ * Get the sum of a list of numbers
+ */
+export function sum(values: number[]): number {
+	return values.reduce((a, b) => a + b, 0);
+}

package/src/js/string.ts

@@ -53,4 +53,26 @@ export function titleCase(value: string): string {
 		.join(' ');
 }
 
+/**
+ * Truncates a string to a specified length, when possible
+ * - Returned as-is if the string is already short enough
+ * - A suffix may be appended to the truncated string, e.g., an ellipsis
+ */
+export function truncate(
+	value: string,
+	length: number,
+	suffix?: string,
+): string {
+	const suffixLength = suffix?.length ?? 0;
+	const truncatedLength = length - suffixLength;
+
+	return value.length <= length
+		? value
+		: `${value.slice(0, truncatedLength)}${suffix ?? ''}`;
+}
+
+export function words(value: string): string[] {
+	return [];
+}
+
 export {capitalise as capitalize};

package/src/js/timer.ts

@@ -80,15 +80,22 @@ type TimerOptions = {} & RepeatOptions;
 type WaitOptions = {} & BaseOptions & OptionsWithError;
 
 export type When = {
-	/**
-	 * Stops the timer
-	 */
-	stop(): void;
-	then(
-		resolve?: (() => void) | null,
-		reject?: (() => void) | null,
-	): Promise<void>;
-};
+		/**
+		 * Is the timer running?
+		 */
+		get active(): boolean;
+		/**
+		 * Stops the timer
+		 */
+		stop(): void;
+		/**
+		 * Starts the timer and returns a promise that resolves when the condition is met
+		 */
+		then(
+			resolve?: (() => void) | null,
+			reject?: (() => void) | null,
+		): Promise<void>;
+	};
 
 type WhenOptions = {} & OptionsWithCount;
 

package/types/index.d.ts

@@ -4,6 +4,8 @@ export * from './element/index';
 export * from './element/focusable';
 export * from './event';
 export * from './is';
+export * from './log';
+export * from './math';
 export * from './models';
 export * from './number';
 export * from './queue';

package/types/is.d.ts

@@ -3,6 +3,9 @@ import type { ArrayOrPlainObject, PlainObject, Primitive } from './models';
  * Is the value an array or a record?
  */
 export declare function isArrayOrPlainObject(value: unknown): value is ArrayOrPlainObject;
+/**
+ * Is the array or object completely empty or only containing `null` or `undefined` values?
+ */
 export declare function isEmpty(value: ArrayOrPlainObject): boolean;
 /**
  * Is the value undefined or null?

package/types/log.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Logs any number of values at the "log" log level
+ */
+type LogCallback = (...data: unknown[]) => void;
+type LogPrototype = {
+    /**
+     * Is logging to the console enabled? _(defaults to `true`)_
+     */
+    enabled: boolean;
+    /**
+     * Logs the value and shows all its properties
+     */
+    dir(value: unknown): void;
+    /**
+     * Logs any number of values at the "debug" log level
+     */
+    debug(...data: unknown[]): void;
+    /**
+     * Logs any number of values at the "error" log level
+     */
+    error(...data: unknown[]): void;
+    /**
+     * Logs any number of values at the "info" log level
+     */
+    info(...data: unknown[]): void;
+    /**
+     * Logs data as a table, with optional properties to use as columns
+     */
+    table(data: unknown, properties?: string[]): void;
+    /**
+     * - Starts a logged timer with a label
+     * - Returns a `Time`-object for logging the current duration of the timer and stopping the timer _(and logging the total duration)_
+     */
+    time(label: string): Time;
+    /**
+     * Logs any number of values together with a trace from where it was called
+     */
+    trace(...data: unknown[]): void;
+    /**
+     * Logs any number of values at the "warn" log level
+     */
+    warn(...data: unknown[]): void;
+};
+type Time = {
+    /**
+     * - Logs the current duration of the timer
+     * - Ignored if logging is disabled
+     */
+    log(): void;
+    /**
+     * - Stops the timer and logs the total duration
+     * - Will always log the total duration, even if logging is disabled
+     */
+    stop(): void;
+};
+declare const log: LogCallback & LogPrototype;
+export { log };

package/types/math.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Get the average value from a list of numbers
+ */
+export declare function average(values: number[]): number;
+/**
+ * Get the maximum value from a list of numbers
+ */
+export declare function max(values: number[]): number;
+/**
+ * Get the minimum value from a list of numbers
+ */
+export declare function min(values: number[]): number;
+/**
+ * Get the sum of a list of numbers
+ */
+export declare function sum(values: number[]): number;

package/types/string.d.ts

@@ -14,4 +14,11 @@ export declare function getString(value: unknown): string;
  * Convert a string to title case _(capitalising every word)_
  */
 export declare function titleCase(value: string): string;
+/**
+ * Truncates a string to a specified length, when possible
+ * - Returned as-is if the string is already short enough
+ * - A suffix may be appended to the truncated string, e.g., an ellipsis
+ */
+export declare function truncate(value: string, length: number, suffix?: string): string;
+export declare function words(value: string): string[];
 export { capitalise as capitalize };

package/types/timer.d.ts

@@ -59,10 +59,17 @@ export type Timer = {
 };
 type WaitOptions = {} & BaseOptions & OptionsWithError;
 export type When = {
+    /**
+     * Is the timer running?
+     */
+    get active(): boolean;
     /**
      * Stops the timer
      */
     stop(): void;
+    /**
+     * Starts the timer and returns a promise that resolves when the condition is met
+     */
     then(resolve?: (() => void) | null, reject?: (() => void) | null): Promise<void>;
 };
 type WhenOptions = {} & OptionsWithCount;