@hkdigital/lib-core 0.3.1

package/dist/util/exceptions/index.js

@@ -0,0 +1,23 @@
+
+import { DetailedError } from "../../constants/errors/generic.js";
+
+/**
+ * Creates a new Error from the error message and throws it with a reference
+ * to the originating Error
+ * - The originating Error is set as `cause` property
+ *
+ * @param {string} message - Additional message to prepend
+ * @param {Error|string} error - Original error
+ * @param {string|Object.<string, any>} details
+ *
+ * @throws {DetailedError}
+ * @returns {never} This function never returns
+ */
+export function rethrow(message, error, details ) {
+  if (!(error instanceof Error)) {
+    // Convert non-Error values to Error objects
+    error = new Error(String(error));
+  }
+
+  throw new DetailedError(message, details, error );
+}

package/dist/util/expect/arrays.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Throws a validation error if value is not an array of strings
+ *
+ * @param {any} value
+ */
+export function stringArray(value: any): void;
+/**
+ * Throws a validation error if value is not an array of objects
+ *
+ * @param {any} value
+ */
+export function objectArray(value: any): void;
+/**
+ * Throws an exception if the value is not an Array or the array is empty
+ */
+export function notEmptyArray(value: any): void;
+/**
+ * Throws a validation error if value is not array like
+ * - Checks if the value is an object and has a property `length`
+ *
+ * @param {any} value
+ */
+export function arrayLike(value: any): void;
+export { array_ as array };
+/**
+ * Throws a validation error if value is not an array
+ *
+ * @param {any} value
+ */
+declare function array_(value: any): void;

package/dist/util/expect/arrays.js

@@ -0,0 +1,47 @@
+import * as v from 'valibot';
+
+/**
+ * Throws a validation error if value is not an array
+ *
+ * @param {any} value
+ */
+function array_(value) {
+	v.parse(v.instance(Array), value);
+}
+
+export { array_ as array };
+
+/**
+ * Throws a validation error if value is not an array of strings
+ *
+ * @param {any} value
+ */
+export function stringArray(value) {
+	v.parse(v.array(v.string()), value);
+}
+
+/**
+ * Throws a validation error if value is not an array of objects
+ *
+ * @param {any} value
+ */
+export function objectArray(value) {
+	v.parse(v.array(v.looseObject({})), value);
+}
+
+/**
+ * Throws an exception if the value is not an Array or the array is empty
+ */
+export function notEmptyArray(value) {
+	v.parse(v.pipe(v.instance(Array), v.nonEmpty()), value);
+}
+
+/**
+ * Throws a validation error if value is not array like
+ * - Checks if the value is an object and has a property `length`
+ *
+ * @param {any} value
+ */
+export function arrayLike(value) {
+	v.parse(v.object({ length: v.number() }), value);
+}

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

@@ -0,0 +1,103 @@
+/**
+ * Throws a validation error if value is not an Error instance
+ *
+ * @param {any} value
+ */
+export function error_(value: any): void;
+/**
+ * Expect a value not to be null
+ *
+ * @param {any} value
+ */
+export function notNull(value: any): void;
+/**
+ * Expect a value to be a boolean and true
+ *
+ * @param {any} value
+ */
+export function _true(value: any): void;
+/**
+ * Expect a positive number
+ *
+ * @param {any} value
+ */
+export function positiveNumber(value: any): void;
+/**
+ * Throws a validation error if value is not a string
+ *
+ * @param {any} value
+ */
+export function notEmptyString(value: any): void;
+/**
+ * Throws a validation error if value is not iterable
+ *
+ * @param {any} value
+ */
+export function iterable(value: any): void;
+/**
+ * Throws a validation error if value is not a a store (has not subscribe
+ * method)
+ *
+ * @param {any} value
+ */
+export function store(value: any): void;
+/**
+ * Throws a validation error if value is not an object or the value
+ * is an array
+ *
+ * @param {any} value
+ */
+export function objectNoArray(value: any): void;
+/**
+ * Throws a validation error if value is not an object or the value
+ * is a function
+ *
+ * @param {any} value
+ */
+export function objectNoFunction(value: any): void;
+/**
+ * Throws a validation error if value is not an object or null
+ *
+ * @param {any} value
+ */
+export function objectOrNull(value: any): void;
+/**
+ * Throws a validation error if value is not an array or Set
+ *
+ * @param {any} value
+ */
+export function arrayOrSet(value: any): void;
+export * from "./arrays.js";
+export * from "./primitives.js";
+export * from "./url.js";
+/**
+ * Throws a validation error if value is not an object
+ *
+ * @param {any} value
+ */
+declare function object_(value: any): void;
+/**
+ * Throws a validation error if value is not a function
+ *
+ * @param {any} value
+ */
+declare function function_(value: any): void;
+/**
+ * Throws a validation error if value is not a Promise
+ *
+ * @param {any} value
+ */
+declare function promise_(value: any): void;
+/**
+ * Throws a validation error if value is not a Map
+ *
+ * @param {any} value
+ */
+declare function map_(value: any): void;
+/**
+ * Throws a validation error if value is not a Set
+ *
+ * @param {any} value
+ */
+declare function set_(value: any): void;
+export { object_ as object, function_ as function, _function as function, function_ as class, _class as class, promise_ as promise, map_ as map, set_ as set, error_ as error, _true as true, _true as true };

package/dist/util/expect/index.js

@@ -0,0 +1,259 @@
+/**
+ * Validation functions that can be used as safe guards in your code
+ *
+ * @example
+ *
+ * import * as expect from '<path>/expect.js';
+ *
+ * function logText( text )
+ * {
+ *   expect.string( text );
+ *   expect.true( 1 > 0 );
+ *
+ *   console.log( text );
+ * }
+ *
+ * logText( 'Hello' );
+ * logText( 123 );      // <- Will throw an exception
+ */
+
+import * as v from 'valibot';
+
+import { isObject } from '../is/index.js';
+
+/** Internals */
+
+const ObjectSchema = v.custom(isObject, `Invalid type: Expected object`);
+
+/** Exports */
+
+export * from './arrays.js';
+export * from './primitives.js';
+export * from './url.js';
+
+// > Base objects
+
+/**
+ * Throws a validation error if value is not an object
+ *
+ * @param {any} value
+ */
+function object_(value) {
+	v.parse(ObjectSchema, value);
+	// v.parse(v.looseObject({}), value);
+}
+
+export { object_ as object };
+
+/**
+ * Throws a validation error if value is not a function
+ *
+ * @param {any} value
+ */
+function function_(value) {
+	v.parse(v.function(), value);
+}
+
+export { function_ as function };
+
+export { function_ as class };
+
+/**
+ * Throws a validation error if value is not a Promise
+ *
+ * @param {any} value
+ */
+function promise_(value) {
+	v.parse(v.instance(Promise), value);
+}
+
+export { promise_ as promise };
+
+/**
+ * Throws a validation error if value is not a Map
+ *
+ * @param {any} value
+ */
+function map_(value) {
+	v.parse(v.instance(Map), value);
+}
+
+export { map_ as map };
+
+/**
+ * Throws a validation error if value is not a Set
+ *
+ * @param {any} value
+ */
+function set_(value) {
+	v.parse(v.instance(Set), value);
+}
+
+export { set_ as set };
+
+/**
+ * Throws a validation error if value is not an Error instance
+ *
+ * @param {any} value
+ */
+export function error_(value) {
+	v.parse(v.instance(Map), value);
+}
+
+export { error_ as error };
+
+// > Common values
+
+/**
+ * Expect a value not to be null
+ *
+ * @param {any} value
+ */
+export function notNull(value) {
+	v.notValue(null, value);
+}
+
+/**
+ * Expect a value to be a boolean and true
+ *
+ * @param {any} value
+ */
+export function _true(value) {
+	v.value(true, value);
+}
+
+export { _true as true };
+
+// > Compounds
+
+/**
+ * Expect a positive number
+ *
+ * @param {any} value
+ */
+export function positiveNumber(value) {
+	const schema = v.pipe(v.number(), v.minValue(0));
+	v.parse(schema, value);
+}
+
+// notNegativeNumber
+// positiveInteger
+// notNegativeInteger
+
+// stringOrNull
+// stringOrUndefined
+
+/**
+ * Throws a validation error if value is not a string
+ *
+ * @param {any} value
+ */
+export function notEmptyString(value) {
+	const schema = v.pipe(v.string(), v.minLength(1));
+
+	v.parse(schema, value);
+}
+
+// notEmptyStringOrNull
+
+// asyncIterator
+// iterable
+
+/**
+ * Throws a validation error if value is not iterable
+ *
+ * @param {any} value
+ */
+export function iterable(value) {
+	const schema = v.pipe(v.looseObject({ [Symbol.iterator]: v.function() }));
+
+	v.parse(schema, value);
+}
+
+// iterator
+
+/**
+ * Throws a validation error if value is not a a store (has not subscribe
+ * method)
+ *
+ * @param {any} value
+ */
+export function store(value) {
+	v.parse(
+		v.custom((value) => {
+			if (!isObject(value) || typeof value.subscribe !== 'function') {
+				return false;
+			}
+
+			return true;
+		}),
+		value
+	);
+}
+
+// ArrayBuffer
+// arrayOrUndefined
+// arangoCollectionId
+// uriComponent
+
+/**
+ * Throws a validation error if value is not an object or the value
+ * is an array
+ *
+ * @param {any} value
+ */
+export function objectNoArray(value) {
+	v.parse(
+		v.custom((value) => {
+			if (!isObject(value) || value instanceof Array) {
+				return false;
+			}
+
+			return true;
+		}),
+		value
+	);
+}
+
+/**
+ * Throws a validation error if value is not an object or the value
+ * is a function
+ *
+ * @param {any} value
+ */
+export function objectNoFunction(value) {
+	v.parse(
+		v.custom((value) => {
+			if (!isObject(value) || typeof value === 'function') {
+				return false;
+			}
+
+			return true;
+		}),
+		value
+	);
+}
+
+/**
+ * Throws a validation error if value is not an object or null
+ *
+ * @param {any} value
+ */
+export function objectOrNull(value) {
+	v.parse(v.union([v.value(null), v.looseObject({})]), value);
+}
+
+// objectOrUndefined
+// objectPath
+
+/**
+ * Throws a validation error if value is not an array or Set
+ *
+ * @param {any} value
+ */
+export function arrayOrSet(value) {
+	v.parse(v.union([v.instance(Array), v.instance(Set)]), value);
+}
+
+// setOfStrings
+// emptyStringOrSymbol

package/dist/util/expect/primitives.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Throws a validation error if value is not a string
+ *
+ * @param {any} value
+ */
+export function string(value: any): void;
+/**
+ * Throws a validation error if value is not a boolean
+ *
+ * @param {any} value
+ */
+export function boolean(value: any): void;
+/**
+ * Throws a validation error if value is not a number
+ *
+ * @param {any} value
+ */
+export function number(value: any): void;
+/**
+ * Throws a validation error if value is not a Symbol
+ *
+ * @param {any} value
+ */
+export function symbol(value: any): void;
+/**
+ * Throws a validation error if value is not defined
+ *
+ * @param {any} value
+ */
+export function defined(value: any): void;

package/dist/util/expect/primitives.js

@@ -0,0 +1,55 @@
+import * as v from 'valibot';
+
+/**
+ * Throws a validation error if value is not a string
+ *
+ * @param {any} value
+ */
+export function string(value) {
+	v.parse(v.string(), value);
+}
+
+/**
+ * Throws a validation error if value is not a boolean
+ *
+ * @param {any} value
+ */
+export function boolean(value) {
+	v.parse(v.boolean(), value);
+}
+
+/**
+ * Throws a validation error if value is not a number
+ *
+ * @param {any} value
+ */
+export function number(value) {
+	v.parse(v.number(), value);
+}
+
+/**
+ * Throws a validation error if value is not a Symbol
+ *
+ * @param {any} value
+ */
+export function symbol(value) {
+	v.parse(v.symbol(), value);
+}
+
+/**
+ * Throws a validation error if value is not defined
+ *
+ * @param {any} value
+ */
+export function defined(value) {
+	v.parse(
+		v.custom((value) => {
+			if (value === undefined) {
+				return false;
+			}
+
+			return true;
+		}, 'Invalid type: Expected any value, but received undefined'),
+		value
+	);
+}

package/dist/util/expect/url.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Throws a validation error if value is not an url
+ *
+ * @param {any} value
+ */
+export function url(value: any): void;
+/**
+ * Throws a validation error if value is not an url or
+ * an empty string
+ *
+ * @param {any} value
+ */
+export function urlOrEmptyString(value: any): void;
+/**
+ * Throws a validation error if value is not a relative url
+ *
+ * @param {any} value
+ */
+export function urlPath(value: any): void;
+/**
+ * Throws a validation error if value is not a relative url
+ *
+ * @param {any} value
+ */
+export function relativeUrl(value: any): void;
+/**
+ * Throws a validation error if value is not an absolute
+ * or relative url
+ *
+ * @param {any} value
+ */
+export function absOrRelUrl(value: any): void;

package/dist/util/expect/url.js

@@ -0,0 +1,60 @@
+// > Imports
+
+import * as v from 'valibot';
+
+import {
+	ValidateUrl,
+	ValidateUrlOrEmptyString,
+	ValidateUrlPath,
+	ValidateRelativeUrl,
+	ValidateAbsOrRelUrl
+} from '../../schemas/validate-url.js';
+
+// > Exports
+
+/**
+ * Throws a validation error if value is not an url
+ *
+ * @param {any} value
+ */
+export function url(value) {
+	v.parse(ValidateUrl, value);
+}
+
+/**
+ * Throws a validation error if value is not an url or
+ * an empty string
+ *
+ * @param {any} value
+ */
+export function urlOrEmptyString(value) {
+	v.parse(ValidateUrlOrEmptyString, value);
+}
+
+/**
+ * Throws a validation error if value is not a relative url
+ *
+ * @param {any} value
+ */
+export function urlPath(value) {
+	v.parse(ValidateUrlPath, value);
+}
+
+/**
+ * Throws a validation error if value is not a relative url
+ *
+ * @param {any} value
+ */
+export function relativeUrl(value) {
+	v.parse(ValidateRelativeUrl, value);
+}
+
+/**
+ * Throws a validation error if value is not an absolute
+ * or relative url
+ *
+ * @param {any} value
+ */
+export function absOrRelUrl(value) {
+	v.parse(ValidateAbsOrRelUrl, value);
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Wraps a function so that the callback function will be called only once
+ *
+ * @param {function} callback
+ *
+ * @returns {function} callback wrapped in `once` function
+ */
+export function once(callback: Function): Function;
+/**
+ * Returns a debounced function
+ * - The original function is not called more than once during the
+ *   specified interval
+ *
+ * @param {function} fn
+ * @param {number} [intervalMs=200]
+ *
+ * @returns {function} debounced function
+ */
+export function debounce(fn: Function, intervalMs?: number): Function;
+export function noop(): void;
+/**
+ * Defer the execution of a function
+ *  - Uses the best 'setImmediate' implementation supported by the current
+ *    runtime environment
+ *
+ * @param {function} fn - Function to execute
+ *
+ * --
+ *
+ * @note setImmediate is preferred over nextTick
+ *
+ * @see https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/
+ */
+export const defer: any;