@hkdigital/lib-core 0.3.1

package/dist/util/time/index.js

@@ -0,0 +1,323 @@
+/**
+ * time.js
+ *
+ * @description
+ * This file contains time related functionality
+ *
+ * @example
+ *
+ *   import { delay, now } from './time.js';
+ *
+ *   async function test()
+ *   {
+ *     console.log( `Current timestamp [${now()}]` );
+ *
+ *     await delay( 1000 );
+ *
+ *     console.log( `Current timestamp [${now()}]` );
+ *   }
+ */
+
+/**
+ * FIXME: use Intl.DateTimeFormat instead of custom conversions
+ *
+ *  e.g.
+ *   return new Intl.DateTimeFormat('nl-NL', {
+ *     month: "long",
+ *    timeZone: 'Europe/Amsterdam'
+ *   }).format(d);
+ */
+
+import {
+	SECOND_MS,
+	MINUTE_MS,
+	HOUR_MS,
+	DAY_MS,
+	TIME_2025_01_01 } from '../../constants/time.js';
+
+import * as expect from '../expect';
+import { HkPromise } from '../../classes/promise/index.js';
+
+/**
+ * Returns a promise that resolves after a specified timeout
+ * - If the returned promise is rejected, the timeout is cancelled
+ *
+ * @param  {number} delayOrMinDelayMs
+ *   Number of milliseconds to wait before promise resolves
+ *
+ * @param  {number} [maxDelayMs=delayOrMinDelayMs]
+ *   Maximum number of milliseconds to wait before the returned promise
+ *   resolves. If this parameter is set, the delay will be chosen randomly
+ *   between the values [delayOrMinDelayMs, maxDelayMs]
+ *
+ * @returns {HkPromise} promise that resolves after a specified timeout
+ */
+export function delay(delayOrMinDelayMs, maxDelayMs) {
+	expect.number(delayOrMinDelayMs);
+
+	if (maxDelayMs) {
+		//
+		// maxDelayMs was set -> generate random delay
+		//
+		if (maxDelayMs > delayOrMinDelayMs) {
+			delayOrMinDelayMs = Math.floor(
+				delayOrMinDelayMs + Math.random() * (maxDelayMs - delayOrMinDelayMs)
+			);
+		}
+	}
+
+	const promise = new HkPromise();
+
+	let timer = setTimeout(() => {
+		timer = null;
+		promise.resolve();
+	}, delayOrMinDelayMs);
+
+	// Register catch method to cancel timer when promise is rejected
+	promise.catch(() => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = null;
+		}
+	});
+
+	return promise;
+}
+
+/**
+ * Get the number of milliseconds since the specified time stamp of the default
+ * reference time stamp TIME_2025_01_01
+ *
+ * @param {number} [sinceMs=TIME_2025_01_01]
+ *
+ * @returns {number} number of milliseconds since the specified time
+ */
+export function sinceMs(sinceMs = TIME_2025_01_01) {
+	return Date.now() - sinceMs;
+}
+
+/**
+ * Get a string that represents the time in a readable
+ * string format: [DD:][HH:]MM:SS.mmm
+ *
+ * @param {number} timeMs [description]
+ *
+ * @returns {string} time in human readable format
+ */
+export function timeToString(timeMs) {
+	const days = Math.floor(timeMs / DAY_MS);
+
+	let restMs = timeMs - days * DAY_MS;
+
+	const hours = Math.floor(restMs / HOUR_MS);
+
+	restMs = restMs - hours * HOUR_MS;
+
+	const minutes = Math.floor(restMs / MINUTE_MS);
+
+	restMs = restMs - minutes * MINUTE_MS;
+
+	const seconds = Math.floor(restMs / SECOND_MS);
+
+	restMs = restMs - seconds * SECOND_MS;
+
+	let str = '';
+
+	if (days) {
+		str += `${days.toString().padStart(2, '0')}:`;
+		str += `${hours.toString().padStart(2, '0')}:`;
+	} else if (hours) {
+		str += `${hours.toString().padStart(2, '0')}:`;
+	}
+
+	str += `${minutes.toString().padStart(2, '0')}:`;
+	str += `${seconds.toString().padStart(2, '0')}.`;
+	str += `${restMs.toString().padStart(3, '0')}`;
+
+	return str;
+}
+
+/**
+ * Returns a Date object
+ * - The input can be a Date object or a numeric timestamp
+ *
+ * @param {Date|number} dateOrTimestamp
+ *
+ * @returns {Date} date object
+ */
+export function toDate(dateOrTimestamp) {
+	if (dateOrTimestamp instanceof Date) {
+		return dateOrTimestamp;
+	}
+
+	if (typeof dateOrTimestamp === 'number') {
+		return new Date(dateOrTimestamp);
+	}
+
+	throw new Error('Missing or invalid parameter [dateOrTimestamp]');
+}
+
+/**
+ * Get the ISO 8601 week number of the specified date
+ *
+ * @see https://stackoverflow.com
+ *      /questions/6117814/get-week-of-year-in-javascript-like-in-php
+ *
+ * @param {Date|number} dateOrTimestamp
+ *
+ * @returns {number} week number
+ */
+export function getWeekNumber(dateOrTimestamp) {
+	const date = toDate(dateOrTimestamp);
+
+	//
+	// Create a copy of this date object
+	//
+	const target = new Date(date.valueOf());
+
+	//
+	// ISO week date weeks start on Monday, so correct the day number
+	//
+	const dayNumber = (date.getDay() + 6) % 7;
+
+	//
+	// ISO 8601 states that week 1 is the week with the first Thursday
+	// of that year.
+	//
+	// Set the target date to the Thursday in the target week
+	//
+	target.setDate(target.getDate() - dayNumber + 3);
+
+	//
+	// Store the millisecond value of the target date
+	//
+	const firstThursday = target.valueOf();
+
+	// Set the target to the first Thursday of the year
+	// First, set the target to January 1st
+	target.setMonth(0, 1);
+
+	//
+	// Not a Thursday? Correct the date to the next Thursday
+	//
+	if (target.getDay() !== 4) {
+		target.setMonth(0, 1 + ((4 - target.getDay() + 7) % 7));
+	}
+
+	//
+	// The week number is the number of weeks between the first Thursday
+	// of the year and the Thursday in the target week
+	// (604800000 = 7 * 24 * 3600 * 1000)
+	//
+	return 1 + Math.ceil((firstThursday - target.getTime()) / 604800000);
+}
+
+/**
+ * Get the name of the month
+ * - Returns the month name using Intl.DateTimeFormat
+ * - By default uses English locale, but locale can be specified
+ *
+ * @param {Date|number} dateOrTimestamp - Date object or timestamp
+ * @param {string} [locale='nl-NL'] - The locale to use for the month name
+ *
+ * @param {Object} [options]
+ * @param {'numeric'|'2-digit'|'narrow'|'short'|'long'} [options.month='long']
+ * @param {string} [options.timeZone] - Optional timezone
+ *
+ * @returns {string} name of the month in the specified locale
+ */
+export function getMonthName(dateOrTimestamp, locale = 'nl-NL',
+    options = { month: 'long' }) {
+
+  const date = toDate(dateOrTimestamp);
+
+  // Create formatter with provided locale and options
+  // @ts-ignore - TypeScript kan hier strikter zijn dan nodig met de options
+  const formatter = new Intl.DateTimeFormat(locale, {
+    month: options?.month || 'long',
+    ...(options?.timeZone ? { timeZone: options.timeZone } : {})
+  });
+
+  return formatter.format(date);
+}
+
+/**
+ * Get the name of the day of the week
+ * - Returns the day name using Intl.DateTimeFormat
+ * - By default uses English locale, but locale can be specified
+ *
+ * @param {Date|number} dateOrTimestamp - Date object or timestamp
+ * @param {string} [locale='nl-NL'] - The locale to use for the day name
+ *
+ * @param {Object} [options]
+ * @param {'narrow'|'short'|'long'} [options.weekday='long']
+ * @param {string} [options.timeZone] - Optional timezone
+ *
+ * @returns {string} name of the day in the specified locale
+ */
+export function getDayName(dateOrTimestamp, locale = 'nl-NL',
+    options = { weekday: 'long' }) {
+
+  const date = toDate(dateOrTimestamp);
+
+  // Create formatter with provided locale and options
+  // @ts-ignore - TypeScript kan hier strikter zijn dan nodig met de options
+  const formatter = new Intl.DateTimeFormat(locale, {
+    weekday: options?.weekday || 'long',
+    ...(options?.timeZone ? { timeZone: options.timeZone } : {})
+  });
+
+  return formatter.format(date);
+}
+
+/**
+ * Return the timestamp of the start of the day
+ * - Midnight
+ *
+ * @param {Date|number} [dateOrTimestamp]
+ *
+ * @returns {number} timestamp of start of the day (00:00:00:0000)
+ */
+export function getTimeAtStartOfDay(dateOrTimestamp) {
+	let d;
+
+	if (dateOrTimestamp) {
+		d = toDate(dateOrTimestamp);
+	} else {
+		// today, now
+		d = new Date();
+	}
+
+	d.setHours(0);
+	d.setMinutes(0);
+	d.setSeconds(0);
+	d.setMilliseconds(0);
+
+	return d.getTime();
+}
+
+/**
+ * Return the timestamp of the end of the day
+ * - Midnight - 1 millisecond
+ *
+ * @param {Date|number} [dateOrTimestamp]
+ *
+ * @returns {number} timestamp of start of the day
+ */
+export function getTimeAtEndOfDay(dateOrTimestamp) {
+	let d;
+
+	if (dateOrTimestamp) {
+		d = toDate(dateOrTimestamp);
+	} else {
+		// today, now
+		d = new Date();
+	}
+
+	d.setHours(23);
+	d.setMinutes(59);
+	d.setSeconds(59);
+	d.setMilliseconds(999);
+
+	return d.getTime();
+}

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

@@ -0,0 +1,81 @@
+/**
+ * Returns a three character prefix that is calculated at boot
+ *
+ * @returns {string} boot time prefix
+ */
+export function bootTimePrefix(): string;
+/**
+ * Create a string that contains random characters from the base58 alphabet
+ *
+ * @param {number} [length=48]
+ *
+ * @returns {string} a base 58 encoded random string
+ */
+export function randomStringBase58(length?: number): string;
+/**
+ * Create a string that contains random characters from a for human's not
+ * ambiguous alphabet
+ *
+ * @param {number} [length=48]
+ *
+ * @returns {string} a human friendly encoded random string
+ */
+export function randomStringBaseHuman(length?: number): string;
+/**
+ * Create a string that contains random characters from the specified alphabet
+ *
+ * @param {number} [length=48]
+ * @param {string} [ALPHABET=ALPHABET_BASE_58]
+ *
+ * @returns {string} a base 58 encoded random string
+ */
+export function randomString(length?: number, ALPHABET?: string): string;
+/**
+ * Create an access code: a string that contains 48 random characters from the
+ * base58 alphabet
+ *
+ * @returns {string} a base 58 encoded random string of length 48
+ */
+export function randomAccessCode(): string;
+/**
+ * Generate client session id
+ *
+ * @returns {string} a base 58 encoded random string of length 48
+ */
+export function generateClientSessionId(): string;
+/**
+ * Generates and returns a new unique local id
+ * - The generated id is garanteed to be unique on the currently running
+ *   local system
+ *
+ * @param {number} [timeMs]
+ *   Custom time value to be used instead of Date.now()
+ *
+ * @returns {string} local id
+ */
+export function generateLocalId(timeMs?: number): string;
+/**
+ * Returns a time based number that changes every 30 seconds
+ *
+ * @param {number} [timeMs=sinceMs()]
+ *   Custom time value to be used instead of sinceMs()
+ *
+ * @returns {number} time based numerical that changes every 30 seconds
+ */
+export function getTimeBasedNumber30s(timeMs?: number): number;
+/**
+ * Returns two character base58 encoded string that changes every 10
+ * milliseconds
+ *
+ * - The function output changes every 9 milliseconds
+ * - Returns a two character string
+ * - The string is base58 encoded
+ * - After 58 * 58 * 10ms = 33,6 seconds, the function output repeats
+ *
+ * @param {number} [timeMs]
+ *   Custom time value to be used instead of Date.now()
+ *
+ * @returns {string} time based value
+ */
+export function getTwoChar10ms(timeMs?: number): string;
+export const BOOT_STAMP: string;

package/dist/util/unique/index.js

@@ -0,0 +1,249 @@
+/**
+ * unique.js
+ *
+ * @description
+ * This file contains functionality to generate unique data
+ *
+ * @example
+ *
+ *   import { generateLocalId } from './unqiue.js';
+ *
+ *   async function test()
+ *   {
+ *     console.log( `Id 1 [${generateLocalId()}]` );
+ *     console.log( `Id 2 [${generateLocalId()}]` );
+ *   }
+ */
+
+/* ------------------------------------------------------------------ Imports */
+
+import { ALPHABET_BASE_HUMAN, ALPHABET_BASE_58 } from '../../constants/bases.js';
+
+import { base58fromNumber } from '../bases';
+
+import { TIME_2025_01_01 } from '../../constants/time';
+
+import { sinceMs } from '../time';
+
+/**
+ * @type {{
+ *   bootTimePrefix?:string,
+ *   lastTimeBasedNumber?: number,
+ *   lastTimeBasedValue58?: string,
+ *   lastCountBasedNumber?: number
+ * }}
+ */
+var vars = {}; /* @note use 'var declaration' for hoisting */
+
+export const BOOT_STAMP = ( Date.now() - TIME_2025_01_01 ).toString(36);
+
+/* ------------------------------------------------------------------ Exports */
+
+/**
+ * Returns a three character prefix that is calculated at boot
+ *
+ * @returns {string} boot time prefix
+ */
+export function bootTimePrefix()
+{
+  if( !vars.bootTimePrefix )
+  {
+    vars.bootTimePrefix = '3' + getTwoChar10ms();
+  }
+
+  return vars.bootTimePrefix;
+}
+
+/**
+ * Create a string that contains random characters from the base58 alphabet
+ *
+ * @param {number} [length=48]
+ *
+ * @returns {string} a base 58 encoded random string
+ */
+export function randomStringBase58( length=48 )
+{
+  return randomString( length, ALPHABET_BASE_58 );
+}
+
+/**
+ * Create a string that contains random characters from a for human's not
+ * ambiguous alphabet
+ *
+ * @param {number} [length=48]
+ *
+ * @returns {string} a human friendly encoded random string
+ */
+export function randomStringBaseHuman( length=48 )
+{
+  return randomString( length, ALPHABET_BASE_HUMAN );
+}
+
+/**
+ * Create a string that contains random characters from the specified alphabet
+ *
+ * @param {number} [length=48]
+ * @param {string} [ALPHABET=ALPHABET_BASE_58]
+ *
+ * @returns {string} a base 58 encoded random string
+ */
+export function randomString( length=48, ALPHABET=ALPHABET_BASE_58 )
+{
+  if( typeof length !== 'number' || length < 1 )
+  {
+    throw new Error('Invalid parameter [length]');
+  }
+
+  if( typeof ALPHABET !== 'string' || !ALPHABET.length )
+  {
+    throw new Error('Invalid parameter [ALPHABET]');
+  }
+
+  let str = '';
+
+  const n = ALPHABET.length;
+
+  for( let j = length; j > 0; j = j - 1 )
+  {
+    const num = n * Math.random() & -1;  // number [0...n-1]
+    str += ALPHABET[ num ];
+  }
+
+  return str;
+}
+
+/**
+ * Create an access code: a string that contains 48 random characters from the
+ * base58 alphabet
+ *
+ * @returns {string} a base 58 encoded random string of length 48
+ */
+export function randomAccessCode()
+{
+  return randomStringBase58( 48 );
+}
+
+/**
+ * Generate client session id
+ *
+ * @returns {string} a base 58 encoded random string of length 48
+ */
+export function generateClientSessionId()
+{
+  return randomStringBase58( 48 );
+}
+
+/**
+ * Generates and returns a new unique local id
+ * - The generated id is garanteed to be unique on the currently running
+ *   local system
+ *
+ * @param {number} [timeMs]
+ *   Custom time value to be used instead of Date.now()
+ *
+ * @returns {string} local id
+ */
+export function generateLocalId( timeMs )
+{
+  const timeBasedNumber = getTimeBasedNumber30s( timeMs );
+
+  let timeBasedValue58;
+
+  let countBasedNumber;
+
+  if( vars.lastTimeBasedNumber !== timeBasedNumber )
+  {
+    // -- Time stamp based number changed -> reset counter to zero
+
+    countBasedNumber =
+      vars.lastCountBasedNumber = 0;
+
+    // -- Calculate timeBasedValue58 and update cache
+
+    vars.lastTimeBasedNumber = timeBasedNumber;
+
+    // cache string representation
+    timeBasedValue58 =
+      vars.lastTimeBasedValue58 = base58fromNumber( timeBasedNumber );
+  }
+  else {
+    // -- Same time stamp based number -> increment counter
+
+    countBasedNumber =
+      vars.lastCountBasedNumber = vars.lastCountBasedNumber + 1;
+
+    // -- Use cached lastTimeBasedNumber
+
+    timeBasedValue58 = vars.lastTimeBasedValue58;
+  }
+
+  const countBasedValue58 = base58fromNumber( countBasedNumber );
+
+  // Combine parts into single identifier string
+  //
+  // @note ALPHABET_BASE_58 is used because it is faster than
+  //       base58fromNumber for single character encoding
+  //
+  const id =
+    // idFormatPrefix
+    bootTimePrefix() +
+    ALPHABET_BASE_58[ timeBasedValue58.length ] +
+    timeBasedValue58 +
+    countBasedValue58;
+
+  // std.debug( id );
+
+  return id;
+}
+
+
+/**
+ * Returns a time based number that changes every 30 seconds
+ *
+ * @param {number} [timeMs=sinceMs()]
+ *   Custom time value to be used instead of sinceMs()
+ *
+ * @returns {number} time based numerical that changes every 30 seconds
+ */
+export function getTimeBasedNumber30s( timeMs )
+{
+  if( !timeMs )
+  {
+    timeMs = sinceMs();
+  }
+
+  // @note do not use bitwise shift since it only works on 32 bit numbers!
+  return Math.floor( timeMs / 30000 );
+}
+
+
+/**
+ * Returns two character base58 encoded string that changes every 10
+ * milliseconds
+ *
+ * - The function output changes every 9 milliseconds
+ * - Returns a two character string
+ * - The string is base58 encoded
+ * - After 58 * 58 * 10ms = 33,6 seconds, the function output repeats
+ *
+ * @param {number} [timeMs]
+ *   Custom time value to be used instead of Date.now()
+ *
+ * @returns {string} time based value
+ */
+export function getTwoChar10ms( timeMs )
+{
+  const now = timeMs || Date.now();
+
+  // @note
+  // do not use bitwise shift since it only works on 32 bit numbers
+  const num = Math.floor( now / 10 ) % 3364;
+
+  if( num >= 58 )
+  {
+    return base58fromNumber( num );
+  }
+  else {
+    return '1' + base58fromNumber( num );
+  }
+}

package/dist/valibot/date.js__

@@ -0,0 +1,10 @@
+// > Imports
+
+import * as v from 'valibot';
+
+// > Exports
+
+/**
+ * Schema to validate a Date or ISO timestamp.
+ */
+export const DateOrIsoTimeStamp = v.union([v.date(), v.pipe(v.string(), v.isoTimestamp())]);

package/dist/valibot/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./user.js";
+export * from "./url.js";
+export default v;
+import * as v from 'valibot';

package/dist/valibot/index.js

@@ -0,0 +1,9 @@
+import * as v from 'valibot';
+
+// export * from './date.js';
+
+export * from './user.js';
+
+export * from './url.js';
+
+export default v;

package/dist/valibot/url.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Schema to validate an URL or empty string.
+ */
+export const UrlOrEmptyString: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction]>, v.UnionSchema<[v.LiteralSchema<"", undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>], undefined>]>;
+/**
+ * Schema to validate an url that may miss the protocol part
+ *
+ * @note an empty string is not allowed!
+ */
+export const HumanUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.TransformAction<string, string>, v.UrlAction<string, undefined>]>;
+/**
+ * Schema to validate url path, without a search and hash part
+ */
+export const UrlPath: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TransformAction<string, URL>, v.CustomSchema<URL, "Invalid URL pathname">, v.TransformAction<URL, string>]>;
+/**
+ * Schema to validate a url path, which consists of
+ * a path and optionally search and hash parts
+ */
+export const RelativeUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TransformAction<string, URL>, v.CustomSchema<URL, "Invalid URL pathname or search part">, v.TransformAction<URL, string>]>;
+/**
+ * Schema to validate an absolute or relative url
+ *
+ * @note an empty string is not allowed!
+ */
+export const AbsOrRelUrl: v.UnionSchema<[v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.UrlAction<string, undefined>]>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TransformAction<string, URL>, v.CustomSchema<URL, "Invalid URL pathname or search part">, v.TransformAction<URL, string>]>]>], undefined>;
+import * as v from 'valibot';