@hkdigital/lib-core 0.3.1

package/dist/util/singleton/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Get a singleton instance
+ * - A class can be supplied to create the singleton instance from
+ * - The singleton is identified by a needle string
+ *
+ * @param {object} _
+ * @param {any} _.class
+ * @param {*[]} [_.args] - Constructor arguments
+ * @param {string} [_.needle]
+ *   If not supplied, a needle will be constructed from the serialized
+ *   constructor arguments (args).
+ */
+export function getInstance({ needle, class: Class, args }: {
+    class: any;
+    args?: any[];
+    needle?: string;
+}): any;
+/**
+ * Creates a proxy that instantiates the singleton class upon it's first usage
+ *
+ * @template T
+ *
+ * @param {object} _
+ * @param {new() => T} _.class
+ * @param {*[]} [_.args] - Constructor arguments
+ *
+ * @returns {T & {init:()=>null}} proxy
+ */
+export function lazySingleton<T>({ class: Class, args }: {
+    class: new () => T;
+    args?: any[];
+}): T & {
+    init: () => null;
+};

package/dist/util/singleton/index.js

@@ -0,0 +1,97 @@
+import { expect } from '../index.js';
+
+const instancesByNeedle = new Map();
+
+/**
+ * Get a singleton instance
+ * - A class can be supplied to create the singleton instance from
+ * - The singleton is identified by a needle string
+ *
+ * @param {object} _
+ * @param {any} _.class
+ * @param {*[]} [_.args] - Constructor arguments
+ * @param {string} [_.needle]
+ *   If not supplied, a needle will be constructed from the serialized
+ *   constructor arguments (args).
+ */
+export function getInstance({ needle, class: Class, args }) {
+	expect.class(Class);
+
+	if (!needle) {
+		// Stringify instance arguments and use it as needle
+		needle = JSON.stringify(args === undefined ? null : args);
+	}
+
+	expect.notEmptyString(needle);
+
+	const className = Class.constructor.name;
+
+	// console.log('getInstance()', { needle, args, className });
+
+	needle = `${className}:${needle}`;
+
+	let instance = instancesByNeedle.get(needle);
+
+	if (!instance) {
+		// console.log('Create new instance');
+		// @ts-ignore
+		instance = new Class(...(args ?? []));
+
+		instancesByNeedle.set(needle, instance);
+	}
+
+	return instance;
+}
+
+/**
+ * Creates a proxy that instantiates the singleton class upon it's first usage
+ *
+ * @template T
+ *
+ * @param {object} _
+ * @param {new() => T} _.class
+ * @param {*[]} [_.args] - Constructor arguments
+ *
+ * @returns {T & {init:()=>null}} proxy
+ */
+export function lazySingleton({ class: Class, args }) {
+	/** @type {T} */
+	let singleton;
+
+	/** @type {T & {init:()=>null}} */
+	// @ts-ignore
+	const proxy = new Proxy(
+		// @ts-ignore
+		{},
+		{
+			/**
+			 * @param {T} target
+			 * @param {string} prop
+			 */
+			// @ts-ignore
+			get(target, prop) {
+				// console.log('lazySingleton: get property', prop);
+
+				if (!singleton) {
+					// @ts-ignore
+					singleton = new Class(...(args ?? []));
+				}
+
+				if (prop === 'init') {
+					// @ts-ignore
+					if (prop in singleton) {
+						// The class has an init method itself, return a reference
+						return singleton[prop];
+					}
+
+					return () => null;
+				}
+
+				// @ts-ignore
+				return singleton[prop];
+			}
+		}
+	);
+
+	return proxy;
+}

package/dist/util/string/array-path.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Convert a path string to an array path
+ * - The path string will be spit at the `pathSeparator` token
+ * - If the supplied path is already an array, the original array will
+ *   be returned
+ *
+ * @param {string|string[]} path
+ *   String or array path (e.g. "some.path.to")
+ *
+ * @param {string} [pathSeparator=PATH_SEPARATOR]
+ *   A custom path separator to use instead of the default "."
+ *
+ * @returns {string} string path (e.g. "some.path.to")
+ */
+export function toStringPath(path: string | string[], pathSeparator?: string): string;

package/dist/util/string/array-path.js

@@ -0,0 +1,75 @@
+import { PATH_SEPARATOR } from '../object/index.js';
+
+/**
+ * Convert a path string to an array path
+ * - The path string will be spit at the `pathSeparator` token
+ * - If the supplied path is already an array, the original array will
+ *   be returned
+ *
+ * @param {string|string[]} path
+ *   String or array path (e.g. "some.path.to")
+ *
+ * @param {string} [pathSeparator=PATH_SEPARATOR]
+ *   A custom path separator to use instead of the default "."
+ *
+ * @returns {string} string path (e.g. "some.path.to")
+ */
+export function toStringPath(path, pathSeparator = PATH_SEPARATOR) {
+  if (Array.isArray(path)) {
+    return path.join(pathSeparator);
+  } else if (typeof path === 'string') {
+    // path is already a string
+    return path;
+  } else {
+    throw new Error(
+      'Missing or invalid parameter [path] (expected string or array)'
+    );
+  }
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Make sure that the outputted path is an array path
+ * - The input value may be a array path
+ * - The input value may be a string path (no conversion needed)
+ *
+ * @param {string|string[]} path
+ *
+ * @returns {string[]} array path (list of strings)
+ */
+// export function fromPath( path )
+// {
+//   if( typeof path === "string" )
+//   {
+//     return path;
+//   }
+//   else {
+//     expect.array( path,
+//       "Missing or invalid parameter [path] (expected string or string[])" );
+
+//     let strPath = proc.arrayToStringPathWeakMap.get( path );
+
+//     if( strPath )
+//     {
+//       // std.debug( "Using cached value", path );
+//       return strPath;
+//     }
+
+//     // Check array path
+//     for( let j = 0, n = path.length; j < n; j = j + 1 )
+//     {
+//       if( typeof path[j] !== "string" )
+//       {
+//         throw new Error("Invalid array path. Expected array of strings");
+//       }
+//     }
+
+//     strPath = path.join("/");
+
+//     proc.safeArrayPathsWeakMap.set( path, true );
+//     proc.arrayToStringPathWeakMap.set( path, strPath );
+
+//     return strPath;
+//   }
+// }

package/dist/util/string/convert.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Remove strange characters from a string and replace whitespace by
+ * dashes.
+ *
+ * @returns {string} string that can be used as uri
+ */
+export function toUriName(str: any): string;
+/**
+ * Captizalize the first character of a string
+ *
+ * @param {string} str - Input string
+ *
+ * @returns {string} string with first letter capitalized
+ */
+export function capitalizeFirst(str: string): string;
+/**
+ * Converts a kebab-case string to Title Case.
+ *
+ * @param {string} kebabString - The kebab-case string to convert
+ * @return {string} The converted Title Case string
+ */
+export function kebabToTitleCase(kebabString: string): string;

package/dist/util/string/convert.js

@@ -0,0 +1,54 @@
+import * as expect from '../expect/index.js';
+
+/**
+ * Remove strange characters from a string and replace whitespace by
+ * dashes.
+ *
+ * @returns {string} string that can be used as uri
+ */
+export function toUriName(str) {
+  expect.string(str);
+
+  str = str.toLowerCase().replace(/[^a-z0-9]+/gi, '-');
+
+  // TODO: remove duplicate dashes
+
+  return str;
+}
+
+/**
+ * Captizalize the first character of a string
+ *
+ * @param {string} str - Input string
+ *
+ * @returns {string} string with first letter capitalized
+ */
+export function capitalizeFirst(str) {
+  if (!str.length) {
+    return str;
+  }
+
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Converts a kebab-case string to Title Case.
+ *
+ * @param {string} kebabString - The kebab-case string to convert
+ * @return {string} The converted Title Case string
+ */
+export function kebabToTitleCase(kebabString) {
+  // Check if input is a string
+  if (typeof kebabString !== 'string') {
+    throw new Error('Input must be a string');
+  }
+
+  // Split the string by hyphens
+  return kebabString
+    .split('-')
+    .map((word) => {
+      // Capitalize the first letter of each word
+      return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+    })
+    .join(' ');
+}

package/dist/util/string/fs.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Path utilities for working with file and directory paths.
+ * Provides functions similar to Node.js path module but for browser and SvelteKit use.
+ */
+/**
+ * Extracts the filename from a path, with or without extension.
+ *
+ * @param {string} path - The path to extract the filename from
+ * @param {boolean} [includeExtension=true] - Whether to include the extension
+ * @return {string} The extracted filename
+ */
+export function basename(path: string, includeExtension?: boolean): string;
+/**
+ * Extracts the extension from a filename.
+ *
+ * @param {string} path - The path to extract the extension from
+ * @param {boolean} [includeDot=false] - Whether to include the dot in the extension
+ * @return {string} The extracted extension
+ */
+export function extname(path: string, includeDot?: boolean): string;
+/**
+ * Extracts the directory name from a path.
+ *
+ * @param {string} path - The path to extract the directory name from
+ * @return {string} The extracted directory name
+ */
+export function dirname(path: string): string;
+/**
+ * Joins path segments with the appropriate separator.
+ *
+ * @param {...string} paths - The path segments to join
+ * @return {string} The joined path
+ */
+export function join(...paths: string[]): string;
+/**
+ * Normalizes a path by resolving '..' and '.' segments.
+ *
+ * @param {string} path - The path to normalize
+ * @return {string} The normalized path
+ */
+export function normalize(path: string): string;
+/**
+ * Checks if a path is absolute.
+ *
+ * @param {string} path - The path to check
+ * @return {boolean} Whether the path is absolute
+ */
+export function isAbsolute(path: string): boolean;
+/**
+ * Returns the path segments as an array.
+ *
+ * @param {string} path - The path to split
+ * @return {string[]} The path segments
+ */
+export function segments(path: string): string[];

package/dist/util/string/fs.js

@@ -0,0 +1,226 @@
+/**
+ * Path utilities for working with file and directory paths.
+ * Provides functions similar to Node.js path module but for browser and SvelteKit use.
+ */
+
+/**
+ * Extracts the filename from a path, with or without extension.
+ *
+ * @param {string} path - The path to extract the filename from
+ * @param {boolean} [includeExtension=true] - Whether to include the extension
+ * @return {string} The extracted filename
+ */
+export function basename(path, includeExtension = true) {
+  if (typeof path !== 'string') {
+    throw new Error('Path must be a string');
+  }
+
+  // Handle empty string
+  if (path === '') {
+    return '';
+  }
+
+  // Remove trailing slashes
+  path = path.replace(/\/+$/, '');
+
+  // Find the last occurrence of '/'
+  const lastSlashIndex = path.lastIndexOf('/');
+
+  // Get the full filename
+  const filename =
+    lastSlashIndex === -1 ? path : path.substring(lastSlashIndex + 1);
+
+  // Return the full filename if extension should be included
+  if (includeExtension) {
+    return filename;
+  }
+
+  // Otherwise, remove the extension
+  const lastDotIndex = filename.lastIndexOf('.');
+
+  // If no dot is found or dot is the first character (hidden file), return the filename
+  if (lastDotIndex <= 0) {
+    return filename;
+  }
+
+  // Return everything before the last dot
+  return filename.substring(0, lastDotIndex);
+}
+
+/**
+ * Extracts the extension from a filename.
+ *
+ * @param {string} path - The path to extract the extension from
+ * @param {boolean} [includeDot=false] - Whether to include the dot in the extension
+ * @return {string} The extracted extension
+ */
+export function extname(path, includeDot = false) {
+  if (typeof path !== 'string') {
+    throw new Error('Path must be a string');
+  }
+
+  const filename = basename(path);
+  const lastDotIndex = filename.lastIndexOf('.');
+
+  // If no dot is found or dot is the first character (hidden file), return empty string
+  if (lastDotIndex <= 0) {
+    return '';
+  }
+
+  // Return the extension with or without the dot
+  return includeDot
+    ? filename.substring(lastDotIndex)
+    : filename.substring(lastDotIndex + 1);
+}
+
+/**
+ * Extracts the directory name from a path.
+ *
+ * @param {string} path - The path to extract the directory name from
+ * @return {string} The extracted directory name
+ */
+export function dirname(path) {
+  if (typeof path !== 'string') {
+    throw new Error('Path must be a string');
+  }
+
+  // Handle empty string
+  if (path === '') {
+    return '.';
+  }
+
+  // Remove trailing slashes
+  path = path.replace(/\/+$/, '');
+
+  // Find the last occurrence of '/'
+  const lastSlashIndex = path.lastIndexOf('/');
+
+  // If no slash is found, return '.'
+  if (lastSlashIndex === -1) {
+    return '.';
+  }
+
+  // If slash is at the beginning, return '/'
+  if (lastSlashIndex === 0) {
+    return '/';
+  }
+
+  // Return everything before the last slash
+  return path.substring(0, lastSlashIndex);
+}
+
+/**
+ * Joins path segments with the appropriate separator.
+ *
+ * @param {...string} paths - The path segments to join
+ * @return {string} The joined path
+ */
+export function join(...paths) {
+  if (paths.length === 0) {
+    return '.';
+  }
+
+  return paths
+    .filter((segment) => typeof segment === 'string' && segment !== '')
+    .join('/')
+    .replace(/\/+/g, '/'); // Replace multiple consecutive slashes with a single one
+}
+
+/**
+ * Normalizes a path by resolving '..' and '.' segments.
+ *
+ * @param {string} path - The path to normalize
+ * @return {string} The normalized path
+ */
+export function normalize(path) {
+  if (typeof path !== 'string') {
+    throw new Error('Path must be a string');
+  }
+
+  // Replace backslashes with forward slashes
+  path = path.replace(/\\/g, '/');
+
+  // Handle empty string
+  if (path === '') {
+    return '.';
+  }
+
+  const isAbsolute = path.startsWith('/');
+  const trailingSlash = path.endsWith('/');
+
+  // Split path into segments
+  const segments = path.split('/').filter(Boolean);
+  const resultSegments = [];
+
+  for (const segment of segments) {
+    if (segment === '.') {
+      // Ignore current directory marker
+      continue;
+    } else if (segment === '..') {
+      // Go up one directory
+      if (
+        resultSegments.length > 0 &&
+        resultSegments[resultSegments.length - 1] !== '..'
+      ) {
+        resultSegments.pop();
+      } else if (!isAbsolute) {
+        resultSegments.push('..');
+      }
+    } else {
+      // Add segment to result
+      resultSegments.push(segment);
+    }
+  }
+
+  // Handle empty result
+  if (resultSegments.length === 0) {
+    return isAbsolute ? '/' : '.';
+  }
+
+  // Join segments
+  let result = resultSegments.join('/');
+
+  // Add leading slash for absolute paths
+  if (isAbsolute) {
+    result = '/' + result;
+  }
+
+  // Add trailing slash if original path had one
+  if (trailingSlash && !result.endsWith('/')) {
+    result += '/';
+  }
+
+  return result;
+}
+
+/**
+ * Checks if a path is absolute.
+ *
+ * @param {string} path - The path to check
+ * @return {boolean} Whether the path is absolute
+ */
+export function isAbsolute(path) {
+  if (typeof path !== 'string') {
+    throw new Error('Path must be a string');
+  }
+
+  return path.startsWith('/');
+}
+
+/**
+ * Returns the path segments as an array.
+ *
+ * @param {string} path - The path to split
+ * @return {string[]} The path segments
+ */
+export function segments(path) {
+  if (typeof path !== 'string') {
+    throw new Error('Path must be a string');
+  }
+
+  // Normalize path first
+  const normalizedPath = normalize(path);
+
+  // Split path into segments
+  return normalizedPath.split('/').filter(Boolean);
+}

package/dist/util/string/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./array-path.js";
+export * from "./convert.js";
+export * from "./fs.js";
+export * from "./interpolate.js";
+export * from "./pad.js";

package/dist/util/string/index.js

@@ -0,0 +1,5 @@
+export * from './array-path.js';
+export * from './convert.js';
+export * from './fs.js';
+export * from './interpolate.js';
+export * from './pad.js';

package/dist/util/string/interpolate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Interpolate: substitute variables in a string
+ *
+ * - Uses mustache template style expression substitution:
+ *   Variables and expressions are surrounded by {{...}}
+ *
+ *  TODO: full mustache support, see https://github.com/janl/mustache.js
+ *
+ * --
+ *
+ * @eg const template = `Hello {{name}}`;
+ *
+ * --
+ *
+ * @param {string} template - Template string to interpolate
+ * @param {object} templateData - Template data to use for interpolation
+ *
+ * @returns {string} interpolated string
+ */
+export function interpolate(template: string, templateData: object, expressionRegexp?: RegExp): string;
+export const RE_JS_EXPRESSION: RegExp;
+export const RE_MUSTACHE: RegExp;

package/dist/util/string/interpolate.js

@@ -0,0 +1,61 @@
+import * as expect from '../expect/index.js';
+
+import { toArrayPath } from '../array/index.js';
+
+import { objectGet, PATH_SEPARATOR } from '../object/index.js';
+
+export const RE_JS_EXPRESSION = /\$\{([^${}]*)\}/g;
+export const RE_MUSTACHE = /\{\{([^{}]*)\}\}/g;
+
+/**
+ * Interpolate: substitute variables in a string
+ *
+ * - Uses mustache template style expression substitution:
+ *   Variables and expressions are surrounded by {{...}}
+ *
+ *  TODO: full mustache support, see https://github.com/janl/mustache.js
+ *
+ * --
+ *
+ * @eg const template = `Hello {{name}}`;
+ *
+ * --
+ *
+ * @param {string} template - Template string to interpolate
+ * @param {object} templateData - Template data to use for interpolation
+ *
+ * @returns {string} interpolated string
+ */
+export function interpolate(
+  template,
+  templateData,
+  expressionRegexp = RE_MUSTACHE
+) {
+  expect.string(template);
+
+  expect.object(templateData);
+
+  return template.replace(
+    expressionRegexp,
+
+    (match, expression) => {
+      const path = toArrayPath(expression);
+
+      /** @type {string} */
+      const replacement = objectGet(templateData, path, undefined);
+
+      if (
+        typeof replacement !== 'string' &&
+        typeof replacement !== 'number' &&
+        typeof replacement !== 'boolean'
+      ) {
+        throw new Error(
+          'Failed to interpolate template: Missing or invalid value for ' +
+            `expression [${expression}] (expected string, number or boolean)`
+        );
+      }
+
+      return replacement;
+    }
+  );
+}

package/dist/util/string/pad.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Prefix a numeric string with 0's
+ *
+ * @param {string|number} input
+ *
+ * @returns {string}
+ */
+export function padDigits(input: string | number, targetLength?: number, padString?: string): string;

package/dist/util/string/pad.js

@@ -0,0 +1,10 @@
+/**
+ * Prefix a numeric string with 0's
+ *
+ * @param {string|number} input
+ *
+ * @returns {string}
+ */
+export function padDigits(input, targetLength = 2, padString = '0') {
+  return ('' + input).padStart(targetLength, padString);
+}