@hkdigital/lib-sveltekit 0.0.46 → 0.0.48

package/README.md

@@ -29,9 +29,25 @@ pnpm add @hkdigital/lib-sveltekit
 
 ### Update
 
+We use a global installion of the `ncu` package to upgrade our `package.json`. Install `ncu` first if you don't have it yet
+
+```bash
+npm install -g npm-check-updates
+```
+
+Upgrading works as follows:
+
 ```bash
 ncu "@hkdigital/*" -u && pnpm install
 ```
+We use a wildcard to upgrade all installed `node_modules` in the scope `@hkdigital`.
+
+You can also add this command to your project. To do so, add the lines to the bottom of the `scripts` section of your `package.json`.
+
+```bash
+"upgrade:hklib": "ncu '@hkdigital/*' -u && pnpm install",
+"upgrade:all": "ncu -u && pnpm install"
+```
 
 ### Import JS & Svelte
 
@@ -107,5 +123,5 @@ npm publish --access public
 pnpm run publish:npm
 ```
 
-### Contribute
+## Contribute
 If your wish to contribute to this library, please contact us [HKdigital](https://hkdigital.nl/contact). Alternatively, the license permits you to fork the library and publish under an alternative name. Change the package name in [package.json](./package.json) to do so.

package/dist/classes/data/Selector.d.ts

@@ -11,18 +11,20 @@ export default class Selector {
     /**
      * Returns the first item from the list of items that matches the selector
      *
-     * @param {object[]|null} items
+     * @template {object} T
+     * @param {T[]|null} items
      *
-     * @returns {object|null} item or null if not found
+     * @returns {T|null} item or null if not found
      */
-    findFirst(items: object[] | null): object | null;
+    findFirst<T extends unknown>(items: T[] | null): T | null;
     /**
      * Returns all items from the list of items that match the selector
      *
-     * @param {object[]|null} items
+     * @template {object} T
+     * @param {T[]|null} items
      *
-     * @returns {object|null} item or null if not found
+     * @returns {T|null} item or null if not found
      */
-    findAll(items: object[] | null): object | null;
+    findAll<T extends unknown>(items: T[] | null): T | null;
     #private;
 }

package/dist/classes/data/Selector.js

@@ -53,9 +53,10 @@ export default class Selector {
 	/**
 	 * Returns the first item from the list of items that matches the selector
 	 *
-	 * @param {object[]|null} items
+	 * @template {object} T
+	 * @param {T[]|null} items
 	 *
-	 * @returns {object|null} item or null if not found
+	 * @returns {T|null} item or null if not found
 	 */
 	findFirst(items) {
 		if (!items) {
@@ -76,9 +77,10 @@ export default class Selector {
 	/**
 	 * Returns all items from the list of items that match the selector
 	 *
-	 * @param {object[]|null} items
+	 * @template {object} T
+	 * @param {T[]|null} items
 	 *
-	 * @returns {object|null} item or null if not found
+	 * @returns {T|null} item or null if not found
 	 */
 	findAll(items) {
 		const result = [];

package/dist/classes/promise/HkPromise.d.ts

@@ -0,0 +1,116 @@
+/**
+ * HkPromise extends the default javascript Promise class
+ */
+export default class HkPromise extends Promise<any> {
+    constructor(initFn: any);
+    /**
+     * Get value of property [resolved]
+     *
+     * @returns {boolean} true if the promise has been resolved
+     */
+    get resolved(): boolean;
+    /**
+     * Get value of property [rejected]
+     *
+     * @returns {boolean} true if the promise was rejected
+     */
+    get rejected(): boolean;
+    /**
+     * Get value of property [pending]
+     *
+     * @returns {boolean} true if the promise is still pending
+     */
+    get pending(): boolean;
+    /**
+     * Get value of property [cancelled]
+     *
+     * @returns {boolean} true if the promise was cancelled
+     */
+    get cancelled(): boolean;
+    /**
+     * Get value of property [timeout]
+     *
+     * @returns {boolean} true if the promise was cancelled due to a timeout
+     */
+    get timeout(): boolean;
+    /**
+     * Resolve the promise
+     *
+     * @param {mixed} [value] - Value to pass to the "then" callbacks
+     *
+     * @returns {object} this
+     */
+    resolve(...args: any[]): object;
+    /**
+     * Resolve the promise if the promise is still pending
+     *
+     * @param {mixed} [value] - Value to pass to the "catch" callbacks
+     *
+     * @returns {object} this
+     */
+    tryResolve(...args: any[]): object;
+    /**
+     * Reject the promise
+     *
+     * @param {Object} [errorOrInfo]
+     *   Object to pass to the "catch" callbacks, usually an Error object
+     *
+     * @returns {object} this
+     */
+    reject(...args: any[]): object;
+    /**
+     * Reject the promise if the promise is still pending
+     *
+     * @param {Object} [errorOrInfo]
+     *   Object to pass to the "catch" callbacks, usually an Error object
+     *
+     * @returns {object} this
+     */
+    tryReject(...args: any[]): object;
+    /**
+     * Reject the promise and set this.cancelled=true
+     *
+     * @param {Object} [errorOrInfo]
+     *   Object to pass to the "catch" callbacks, usually an Error object
+     *
+     * @returns {object} this
+     */
+    cancel(errorOrInfo?: any, ...args: any[]): object;
+    /**
+     * Reject the promise and set this.cancelled=true
+     *
+     * @param {Object} [errorOrInfo]
+     *   Object to pass to the "catch" callbacks, usually an Error object
+     *
+     * @returns {object} this
+     */
+    tryCancel(...args: any[]): object;
+    /**
+     * Specify the number of milliseconds until the promise should time out.
+     * - When a timeout occurs: the promise is cancelled and the following
+     *   properties are both set
+     *
+     *      this.timeout=true
+     *      this.cancelled=true
+     *
+     * @param {number} ms
+     *   Number of milliseconds after which the promise should time out
+     *
+     * @param {string} [message="Timeout"]
+     *   Message of the error that will be thrown when the timeout occurs
+     */
+    setTimeout(ms: number, message?: string): this;
+    /**
+     * Register a callback that is called when the promise resolves
+     *
+     * @param {function} callback
+     */
+    then(...args: any[]): Promise<any>;
+    /**
+     * Register a callback that is called when the promise rejects, is
+     * cancelled or times out
+     *
+     * @param {function} callback
+     */
+    catch(...args: any[]): Promise<any>;
+}

package/dist/classes/promise/HkPromise.js

@@ -0,0 +1,387 @@
+/**
+ * Hkpromise.js
+ *
+ * @description
+ * HkPromise extends the default Promise class. A HkPromise offers some
+ * additional methods, e.g. resolve, reject and setTimeout, which makes it
+ * easier to use than the build in Promise class in some code constructions.
+ *
+ * @example
+ *
+ *   import HkPromise from "./HkPromise.js";
+ *
+ *   function() {
+ *     const promise = new HkPromise();
+ *
+ *     setTimeout( promise.resolve, 1000 );
+ *
+ *     return promise;
+ *   }
+ */
+
+/* ------------------------------------------------------------------ Imports */
+
+import * as expect from '../../util/expect/index.js';
+
+import { noop } from '../../util/function/index.js';
+
+/* ---------------------------------------------------------------- Internals */
+
+const resolved$ = Symbol('resolved');
+const rejected$ = Symbol('rejected');
+const pending$ = Symbol('pending');
+
+const timeout$ = Symbol('timeout');
+const cancelled$ = Symbol('cancelled');
+
+const resolveFn$ = Symbol('resolveFn');
+const rejectFn$ = Symbol('rejectFn');
+
+const timeoutTimer$ = Symbol('timeoutTimer');
+
+const hasThen$ = Symbol('hasThen');
+
+/* ------------------------------------------------------------------- Export */
+
+/**
+ * HkPromise extends the default javascript Promise class
+ */
+export default class HkPromise extends Promise {
+	constructor(initFn) {
+		let _resolveFn;
+		let _rejectFn;
+
+		super((resolveFn, rejectFn) => {
+			//
+			// @note if initFn cannot be called an exception will be thrown:
+			// TypeError: Promise resolve or reject function is not callable
+			//
+			if (initFn) {
+				initFn(resolveFn, rejectFn);
+			}
+
+			_resolveFn = resolveFn;
+			_rejectFn = rejectFn;
+		});
+
+		// @note some values are not initialized on purpose,
+		//       to save time during promise creation
+
+		this[resolveFn$] = _resolveFn;
+		this[rejectFn$] = _rejectFn;
+
+		// this[ resolved$ ] = false;
+		// this[ rejected$ ] = false;
+
+		this[pending$] = true;
+
+		// this[ cancelled$ ] = false;
+		// this[ timeout$ ] = false;
+
+		// this[ timeoutTimer$ ] = undefined;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Get value of property [resolved]
+	 *
+	 * @returns {boolean} true if the promise has been resolved
+	 */
+	get resolved() {
+		return this[resolved$] ? true : false;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Get value of property [rejected]
+	 *
+	 * @returns {boolean} true if the promise was rejected
+	 */
+	get rejected() {
+		return this[rejected$] ? true : false;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Get value of property [pending]
+	 *
+	 * @returns {boolean} true if the promise is still pending
+	 */
+	get pending() {
+		return this[pending$];
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Get value of property [cancelled]
+	 *
+	 * @returns {boolean} true if the promise was cancelled
+	 */
+	get cancelled() {
+		return this[cancelled$] ? true : false;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Get value of property [timeout]
+	 *
+	 * @returns {boolean} true if the promise was cancelled due to a timeout
+	 */
+	get timeout() {
+		return this[timeout$] ? true : false;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Resolve the promise
+	 *
+	 * @param {mixed} [value] - Value to pass to the "then" callbacks
+	 *
+	 * @returns {object} this
+	 */
+	resolve(/* value */) {
+		// -- Check current Promise state
+
+		if (!this[pending$]) {
+			if (this[resolved$]) {
+				throw new Error('Cannot resolve Promise. Promise has already resolved');
+			} else {
+				throw new Error('Cannot resolve Promise. Promise has already been rejected');
+			}
+		}
+
+		// -- Clear timeout timer (if any)
+
+		if (undefined !== this[timeoutTimer$]) {
+			clearTimeout(this[timeoutTimer$]);
+
+			this[timeoutTimer$] = undefined;
+		}
+
+		// -- Set flags and call resolve function
+
+		this[resolved$] = true;
+		this[pending$] = false;
+
+		this[resolveFn$](...arguments);
+
+		return this;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Resolve the promise if the promise is still pending
+	 *
+	 * @param {mixed} [value] - Value to pass to the "catch" callbacks
+	 *
+	 * @returns {object} this
+	 */
+	tryResolve(/* value */) {
+		if (this[pending$]) {
+			this.resolve(...arguments);
+		}
+
+		return this;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Reject the promise
+	 *
+	 * @param {Object} [errorOrInfo]
+	 *   Object to pass to the "catch" callbacks, usually an Error object
+	 *
+	 * @returns {object} this
+	 */
+	reject(/* errorOrInfo */) {
+		if (!this[hasThen$]) {
+			//
+			// No then (or await) has been used
+			// add catch to prevent useless unhandled promise rejection
+			//
+			this.catch(noop);
+		}
+
+		// -- Check current Promise state
+
+		if (!this[pending$]) {
+			if (this[resolved$]) {
+				throw new Error('Cannot reject Promise. Promise has already resolved');
+			} else {
+				throw new Error('Cannot reject Promise. Promise has already been rejected');
+			}
+		}
+
+		// -- Clear timeout timer (if any)
+
+		if (undefined !== this[timeoutTimer$]) {
+			clearTimeout(this[timeoutTimer$]);
+
+			this[timeoutTimer$] = undefined;
+		}
+
+		// -- Set flags and call reject function
+
+		this[rejected$] = true;
+		this[pending$] = false;
+
+		this[rejectFn$](...arguments);
+
+		return this;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Reject the promise if the promise is still pending
+	 *
+	 * @param {Object} [errorOrInfo]
+	 *   Object to pass to the "catch" callbacks, usually an Error object
+	 *
+	 * @returns {object} this
+	 */
+	tryReject(/* errorOrInfo */) {
+		if (this[pending$]) {
+			this.reject(...arguments);
+		}
+
+		return this;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Reject the promise and set this.cancelled=true
+	 *
+	 * @param {Object} [errorOrInfo]
+	 *   Object to pass to the "catch" callbacks, usually an Error object
+	 *
+	 * @returns {object} this
+	 */
+	cancel(errorOrInfo) {
+		if (errorOrInfo) {
+			if (!(errorOrInfo instanceof Object)) {
+				throw new Error('Invalid parameter [errorOrInfo] (expected (error) object');
+			}
+		} else {
+			errorOrInfo = new Error('Cancelled');
+		}
+
+		errorOrInfo.cancelled = true;
+
+		this[cancelled$] = true;
+		this.reject(...arguments);
+
+		return this;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Reject the promise and set this.cancelled=true
+	 *
+	 * @param {Object} [errorOrInfo]
+	 *   Object to pass to the "catch" callbacks, usually an Error object
+	 *
+	 * @returns {object} this
+	 */
+	tryCancel(/*errorOrInfo*/) {
+		if (this[pending$]) {
+			this.cancel(...arguments);
+		}
+
+		return this;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Specify the number of milliseconds until the promise should time out.
+	 * - When a timeout occurs: the promise is cancelled and the following
+	 *   properties are both set
+	 *
+	 *      this.timeout=true
+	 *      this.cancelled=true
+	 *
+	 * @param {number} ms
+	 *   Number of milliseconds after which the promise should time out
+	 *
+	 * @param {string} [message="Timeout"]
+	 *   Message of the error that will be thrown when the timeout occurs
+	 */
+	setTimeout(ms, message = 'Timeout') {
+		expect.number(ms);
+		expect.string(message);
+
+		// -- Check current Promise state
+
+		if (!this[pending$]) {
+			if (this[resolved$]) {
+				throw new Error('Cannot set timeout. Promise has already resolved');
+			} else {
+				throw new Error('Cannot set timeout. Promise has already been rejected');
+			}
+		}
+
+		// -- Clear existing timeout (if any)
+
+		if (undefined !== this[timeoutTimer$]) {
+			clearTimeout(this[timeoutTimer$]);
+		}
+
+		// -- Set timeout
+
+		const err = new Error(message);
+
+		this[timeoutTimer$] = setTimeout(() => {
+			if (!this[pending$]) {
+				// Promise has already been resolved (should not happen)
+				return;
+			}
+
+			this[timeout$] = true;
+			this[cancelled$] = true;
+
+			err.timeout = true;
+			err.cancelled = true;
+
+			this.reject(err);
+		}, ms);
+
+		// return this -> chainable method
+		return this;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Register a callback that is called when the promise resolves
+	 *
+	 * @param {function} callback
+	 */
+	then(/* callback */) {
+		this[hasThen$] = true;
+
+		return super.then(...arguments);
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Register a callback that is called when the promise rejects, is
+	 * cancelled or times out
+	 *
+	 * @param {function} callback
+	 */
+	catch(/* callback */) {
+		return super.catch(...arguments);
+	}
+} // end class

package/dist/classes/promise/index.d.ts

@@ -0,0 +1 @@
+export { default as HkPromise } from "./HkPromise.js";

package/dist/classes/promise/index.js

@@ -0,0 +1 @@
+export { default as HkPromise } from './HkPromise.js';

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

@@ -135,22 +135,24 @@ export function sortByPathValue(items: any[], path: string[] | string, compareFn
  * Find the first item in the list of objects that matches the selector
  * - All items in the supplied array must be objects
  *
- * @param {object[]} arr
+ * @template {object} T
+ * @param {T[]} arr
  * @param {object|null} selector
  *
- * @returns {object|null} first matched item
+ * @returns {T|null} first matched item
  */
-export function findFirst(arr: object[], selector: object | null): object | null;
+export function findFirst<T extends unknown>(arr: T[], selector: object | null): T | null;
 /**
  * Returns all items from the list of items that match the selector
  * - All items in the supplied array must be objects
  *
- * @param {object[]} arr
+ * @template {object} T
+ * @param {T[]} arr
  * @param {object|null} selector
  *
- * @returns {object[]} matching items
+ * @returns {T[]} matching items
  */
-export function findAll(arr: object[], selector: object | null): object[];
+export function findAll<T extends unknown>(arr: T[], selector: object | null): T[];
 /**
  * Convert array to an object using a list of keys for each index
  *

package/dist/util/array/index.js

@@ -378,10 +378,11 @@ export function sortByPathValue(items, path, compareFn = smallestFirst) {
  * Find the first item in the list of objects that matches the selector
  * - All items in the supplied array must be objects
  *
- * @param {object[]} arr
+ * @template {object} T
+ * @param {T[]} arr
  * @param {object|null} selector
  *
- * @returns {object|null} first matched item
+ * @returns {T|null} first matched item
  */
 export function findFirst(arr, selector) {
 	const selectorObj = new Selector(selector);
@@ -395,10 +396,11 @@ export function findFirst(arr, selector) {
  * Returns all items from the list of items that match the selector
  * - All items in the supplied array must be objects
  *
- * @param {object[]} arr
+ * @template {object} T
+ * @param {T[]} arr
  * @param {object|null} selector
  *
- * @returns {object[]} matching items
+ * @returns {T[]} matching items
  */
 export function findAll(arr, selector) {
 	const selectorObj = new Selector(selector);

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

@@ -0,0 +1,20 @@
+/**
+ * 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;

package/dist/util/{function.js__ → function/index.js}

@@ -16,7 +16,7 @@
 
 /* ------------------------------------------------------------------ Imports */
 
-import * as Types from '$lib/typedef/base.js';
+import * as expect from '../expect/index.js';
 
 /* ------------------------------------------------------------------ Exports */
 
@@ -36,18 +36,16 @@ export const noop = () => {};
  * @returns {function} callback wrapped in `once` function
  */
 export function once(callback) {
-  Types.Number(callback);
+	expect.function(callback);
 
-  expectFunction(callback, 'Missing or invalid parameter [callback]');
+	let ignore = false;
 
-  let ignore = false;
-
-  return function () {
-    if (!ignore) {
-      ignore = true;
-      callback(...arguments);
-    }
-  };
+	return function () {
+		if (!ignore) {
+			ignore = true;
+			callback(...arguments);
+		}
+	};
 }
 
 // -----------------------------------------------------------------------------
@@ -63,40 +61,40 @@ export function once(callback) {
  * @returns {function} debounced function
  */
 export function debounce(fn, intervalMs = 200) {
-  let idleTimer;
-  let lastArguments;
+	let idleTimer;
+	let lastArguments;
 
-  // console.log("debounce");
+	// console.log("debounce");
 
-  return function debounced() {
-    // console.log("debounced");
+	return function debounced() {
+		// console.log("debounced");
 
-    if (idleTimer) {
-      // console.log("idleTimer running");
+		if (idleTimer) {
+			// console.log("idleTimer running");
 
-      // The function has been called recently
-      lastArguments = arguments;
-      return;
-    }
+			// The function has been called recently
+			lastArguments = arguments;
+			return;
+		}
 
-    idleTimer = setTimeout(() => {
-      // console.log("idleTimer finished", lastArguments);
+		idleTimer = setTimeout(() => {
+			// console.log("idleTimer finished", lastArguments);
 
-      idleTimer = null;
+			idleTimer = null;
 
-      if (lastArguments) {
-        //
-        // At least one call has been "debounced"
-        // -> make call with last arguments, so function always receives
-        //    the arguments of the last call to the function
-        //
-        fn(...lastArguments);
-        lastArguments = undefined;
-      }
-    }, intervalMs);
+			if (lastArguments) {
+				//
+				// At least one call has been "debounced"
+				// -> make call with last arguments, so function always receives
+				//    the arguments of the last call to the function
+				//
+				fn(...lastArguments);
+				lastArguments = undefined;
+			}
+		}, intervalMs);
 
-    fn(...arguments);
-  };
+		fn(...arguments);
+	};
 }
 
 // -----------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-sveltekit",
-	"version": "0.0.46",
+	"version": "0.0.48",
 	"author": "Jens Kleinhout, HKdigital (https://hkdigital.nl)",
 	"license": "ISC",
 	"repository": {
@@ -54,6 +54,10 @@
 			"types": "./dist/classes/data/index.d.ts",
 			"svelte": "./dist/classes/data/index.js"
 		},
+		"./classes/promise": {
+			"types": "./dist/classes/promise/index.d.ts",
+			"svelte": "./dist/classes/promise/index.js"
+		},
 		"./classes/streams": {
 			"types": "./dist/classes/streams/index.d.ts",
 			"svelte": "./dist/classes/streams/index.js"
@@ -122,6 +126,10 @@
 			"types": "./dist/util/expect/index.d.ts",
 			"svelte": "./dist/util/expect/index.js"
 		},
+		"./util/function": {
+			"types": "./dist/util/function/index.d.ts",
+			"svelte": "./dist/util/function/index.js"
+		},
 		"./util/is": {
 			"types": "./dist/util/is/index.d.ts",
 			"svelte": "./dist/util/is/index.js"