@hkdigital/lib-sveltekit 0.1.58 → 0.1.60

package/dist/constants/bases.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Characters selected for their visually distinct shapes to improve
+ * human readability and reduce confusion.
+ */
+export const ALPHABET_BASE_HUMAN: "3456789abcdefghjkmnpqrstuvwxy";
+/**
+ * Base58 character set: alphanumeric characters excluding similar-looking
+ * ones (0, O, I, l) to prevent visual ambiguity.
+ */
+export const ALPHABET_BASE_58: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";

package/dist/constants/bases.js

@@ -0,0 +1,13 @@
+
+/**
+ * Characters selected for their visually distinct shapes to improve
+ * human readability and reduce confusion.
+ */
+ export const ALPHABET_BASE_HUMAN = '3456789abcdefghjkmnpqrstuvwxy';
+
+/**
+ * Base58 character set: alphanumeric characters excluding similar-looking
+ * ones (0, O, I, l) to prevent visual ambiguity.
+ */
+export const ALPHABET_BASE_58 =
+  '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';

package/dist/constants/time.d.ts

@@ -15,5 +15,4 @@ export const INTERVALS_MS: {
     "two-weekly": number;
     "four-weekly": number;
 };
-export const TIME_2020_01_01: 1577836800000;
-export const TIME_2100_01_01: 4102444800000;
+export const TIME_2025_01_01: 1577836800000;

package/dist/constants/time.js

@@ -24,5 +24,5 @@ export const INTERVALS_MS = {
 
 // > Offsets
 
-export const TIME_2020_01_01 = 1577836800000; // 2020-01-01T00:00:00.000Z
-export const TIME_2100_01_01 = 4102444800000; // 2100-01-01T00:00:00.000Z
+export const TIME_2025_01_01 = 1577836800000; // 2020-01-01T00:00:00.000Z
+// export const TIME_2100_01_01 = 4102444800000; // 2100-01-01T00:00:00.000Z

package/dist/util/bases/base58.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Convert a number to a base 58 encoded string
+ *
+ * @param {number|BigInt} num - Number to encode
+ *
+ * @returns {string} string encoded using base 58
+ */
+export function base58fromNumber(num: number | bigint): string;
+/**
+ * Returns true if the specified string only contains base 58 characters
+ *
+ * @param {string} str [description]
+ *
+ * @returns {boolean} true if the string only contains base 58 characters
+ */
+export function isBase58(str: string): boolean;
+/**
+ * Convert a string encoded as base 58 to a number (BigInt)
+ *
+ * @param {string} str - String to decode
+ *
+ * @param {number} [exceptionValue]
+ *   If specified, the exceptionValue will be returned instead of
+ *   throwing an exception
+ *
+ * @returns {number} decoded decimal numerical representation
+ */
+export function base58toNumber(str: string, exceptionValue?: number, ...args: any[]): number;
+/**
+ * Convert a base58 encoded string to an Uint8Array (bytes)
+ * - A base58 encoded string actually represents a (potentially very big)
+ *   number. This method converts that number into a bytes representation
+ * - A byte can hold 256 values, a base58 character only 58, so there will be
+ *   less bytes needed to encode the value of the base58 encoded string
+ *
+ * @param {string} str - String to convert
+ *
+ * @returns {Uint8Array} bytes that represent the base58 encoded string value
+ */
+export function base58toBytes(str: string): Uint8Array;
+/**
+ * Convert a base58 encoded string to a (base256) byte string
+ *
+ * @param {string} str
+ *
+ * @returns {string} byte string
+ */
+export function base58toByteString(str: string): string;
+/**
+ * Convert bytes to number
+ *
+ * @param {Uint8Array} bytes
+ *
+ * @returns {BigInt} numeric value
+ */
+export function bytesToNumber(bytes: Uint8Array): bigint;
+export const ALPHABET_BASE_58: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+export const ALPHABET_BASE_58_MAP: Map<string, number>;

package/dist/util/bases/base58.js

@@ -0,0 +1,262 @@
+/**
+ * base-58.js
+ *
+ * @description
+ * This file contains code for working with base 58 encoding
+ *
+ * @example
+ *
+ *   import { base58fromNumber } from "./base-58.js";
+ *
+ *   console.log( base58fromNumber( 1234513245 ) ) // base 58 encoded string
+ */
+
+/* ------------------------------------------------------------------ Imports */
+
+import * as expect from '../expect';
+
+/* ------------------------------------------------------------------ Exports */
+
+// Base 58 helper functions
+//
+// Inspired by
+//   https://github.com/jimeh/node-base58/blob/master/src/base58.js
+//
+// @note
+//   Two different commonly used alphabets exist
+//
+//   Bitcoin, IPFS (respects default sort order):
+//     123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
+//
+//   Short URLs for Flickr
+//     123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ
+//
+// @see https://en.wikipedia.org/wiki/StdBase58Helper
+//
+
+export const ALPHABET_BASE_58 =
+  '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+//export
+const BASE_SIZE = BigInt(ALPHABET_BASE_58.length);
+
+// Create a lookup table to fetch character index
+
+export const ALPHABET_BASE_58_MAP =
+  new Map( [...ALPHABET_BASE_58].map( ( char, index ) => [ char, index ] ) );
+
+/**
+ * Convert a number to a base 58 encoded string
+ *
+ * @param {number|BigInt} num - Number to encode
+ *
+ * @returns {string} string encoded using base 58
+ */
+export function base58fromNumber( num )
+{
+  let str = '';
+
+  if( typeof num !== 'bigint' )
+  {
+    if( Number.isNaN( num ) ||
+        num < 0 ||
+        num > Number.MAX_SAFE_INTEGER ||
+        Math.floor( num ) !== num )
+    {
+      throw new Error(
+        'Invalid parameter [num], expected not negative safe integer');
+    }
+
+    num = BigInt(num);
+  }
+
+  while( num >= BASE_SIZE )
+  {
+    const mod = Number(num % BASE_SIZE);
+
+    str = ALPHABET_BASE_58[ mod ] + str;
+
+    // num = Math.floor( num / BASE_SIZE );
+    //
+    num = num / BASE_SIZE; // BigInts are integers, automatically rounded down
+  }
+
+  return ALPHABET_BASE_58[ Number(num) ] + str;
+}
+
+/**
+ * Returns true if the specified string only contains base 58 characters
+ *
+ * @param {string} str [description]
+ *
+ * @returns {boolean} true if the string only contains base 58 characters
+ */
+export function isBase58( str )
+{
+  expect.string( str );
+
+  for( let j = 0, n = str.length; j < n; j = j + 1 )
+  {
+    const char = str.charAt(j);
+    if( !ALPHABET_BASE_58_MAP.has( char ) )
+    {
+      return false;
+    }
+  } // end for
+
+  return true;
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Convert a string encoded as base 58 to a number (BigInt)
+ *
+ * @param {string} str - String to decode
+ *
+ * @param {number} [exceptionValue]
+ *   If specified, the exceptionValue will be returned instead of
+ *   throwing an exception
+ *
+ * @returns {number} decoded decimal numerical representation
+ */
+export function base58toNumber( str, exceptionValue )
+{
+  expect.string( str, 'Missing or invalid parameter [str]' );
+
+  let num = BigInt(0);
+
+  const n = str.length;
+  const n_1 = n - 1;
+
+  for( let j = 0; j < n; j = j + 1 )
+  {
+    const char = str.charAt(j);
+    const value = ALPHABET_BASE_58_MAP.get( char );
+
+    if( value === undefined )
+    {
+      if( 1 === arguments.length )
+      {
+        throw new Error(
+          `Invalid character [${char}] found in string (expected base58`);
+      }
+      else {
+        return exceptionValue;
+      }
+    }
+
+    num = num + BigInt(value) * BigInt(58) ** BigInt( n_1 - j );
+
+    // console.log("num", num );
+
+  } // end for
+
+  return num;
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Convert a base58 encoded string to an Uint8Array (bytes)
+ * - A base58 encoded string actually represents a (potentially very big)
+ *   number. This method converts that number into a bytes representation
+ * - A byte can hold 256 values, a base58 character only 58, so there will be
+ *   less bytes needed to encode the value of the base58 encoded string
+ *
+ * @param {string} str - String to convert
+ *
+ * @returns {Uint8Array} bytes that represent the base58 encoded string value
+ */
+export function base58toBytes( str )
+{
+  const num = base58toNumber( str );
+
+  let numBase16 = num.toString(16);
+
+  if( 1 === numBase16.length % 2 )
+  {
+    //
+    // String contains inpair number of characters -> prefix a "0"
+    //
+    numBase16 = '0' + numBase16;
+  }
+
+  const n = numBase16.length;
+
+  const out = new Uint8Array( numBase16.length >> 1 );
+
+  for( let j = n - 1; j > 0; j = j - 2 )
+  {
+    const low16 = parseInt( numBase16[ j ], 16 );
+    const high16 = parseInt( numBase16[ j - 1 ], 16 );
+
+  //   // const low16 = (j < n_1) ? parseInt(numBase16[ j + 1 ], 10) : 0;
+
+  //   const low16 = (j < n_1) ? parseInt( numBase16[ j + 1 ], 16 ) : 0;
+
+    const value256 = (high16 << 4) + low16;
+
+    out[ j >> 1 ] = value256;
+
+    // console.log(
+    //   {
+    //     numBase16,
+    //     n,
+    //     j,
+    //     high16,
+    //     low16,
+    //     value256,
+    //     out
+    //   } );
+
+  } // end for
+
+  return out;
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Convert a base58 encoded string to a (base256) byte string
+ *
+ * @param {string} str
+ *
+ * @returns {string} byte string
+ */
+export function base58toByteString( str )
+{
+  return new TextDecoder().decode( base58toBytes( str ) );
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Convert bytes to number
+ *
+ * @param {Uint8Array} bytes
+ *
+ * @returns {BigInt} numeric value
+ */
+export function bytesToNumber( bytes )
+{
+  let sum = BigInt(0);
+
+  // console.log( "check", bytes.length );
+
+  for( let j = 0, n = bytes.length; j < n; j = j + 1 )
+  {
+    const base = BigInt(256) ** BigInt( n - 1 - j );
+    const value = bytes[ j ];
+
+    // console.log(
+    //   {
+    //     base,
+    //     value
+    //   } );
+
+    sum = sum + base * BigInt( value );
+  }
+
+  return sum;
+}

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

@@ -0,0 +1 @@
+export * from "./base58.js";

package/dist/util/bases/index.js

@@ -0,0 +1 @@
+export * from './base58.js';

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

@@ -10,14 +10,14 @@
  *   resolves. If this parameter is set, the delay will be chosen randomly
  *   between the values [delayOrMinDelayMs, maxDelayMs]
  *
- * @returns {Promise} promise that resolves after a specified timeout
+ * @returns {HkPromise} promise that resolves after a specified timeout
  */
-export function delay(delayOrMinDelayMs: number, maxDelayMs?: number): Promise<any>;
+export function delay(delayOrMinDelayMs: number, maxDelayMs?: number): HkPromise;
 /**
  * Get the number of milliseconds since the specified time stamp of the default
- * reference time stamp TIME_2020_01_01
+ * reference time stamp TIME_2025_01_01
  *
- * @param {number} [sinceMs=TIME_2020_01_01]
+ * @param {number} [sinceMs=TIME_2025_01_01]
  *
  * @returns {number} number of milliseconds since the specified time
  */
@@ -53,68 +53,56 @@ export function toDate(dateOrTimestamp: Date | number): Date;
 export function getWeekNumber(dateOrTimestamp: Date | number): number;
 /**
  * Get the name of the month
- * - Returns the English name of the month
+ * - Returns the month name using Intl.DateTimeFormat
+ * - By default uses English locale, but locale can be specified
  *
- * - Use the output as label in combination with the functions
- *   text() and translate() for international month names
+ * @param {Date|number} dateOrTimestamp - Date object or timestamp
+ * @param {string} [locale='nl-NL'] - The locale to use for the month name
  *
- * e.g.
+ * @param {Object} [options]
+ * @param {'numeric'|'2-digit'|'narrow'|'short'|'long'} [options.month='long']
+ * @param {string} [options.timeZone] - Optional timezone
  *
- * setTranslations()
- * ...
- *
- * text( getMonthName( new Date() ) );
- *
- * --
- *
- * @param {Date|number} dateOrTimestamp
- *
- * @returns {string} name of the month (English)
+ * @returns {string} name of the month in the specified locale
  */
-export function getMonthName(dateOrTimestamp: Date | number): string;
+export function getMonthName(dateOrTimestamp: Date | number, locale?: string, options?: {
+    month?: "numeric" | "2-digit" | "narrow" | "short" | "long";
+    timeZone?: string;
+}): string;
 /**
- * Get the name of the day
- * - Returns the English name of the day
- *
- * - Use the output as label in combination with the functions
- *   text() and translate() for international day names
+ * 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
  *
- * e.g.
+ * @param {Date|number} dateOrTimestamp - Date object or timestamp
+ * @param {string} [locale='nl-NL'] - The locale to use for the day name
  *
- * setTranslations()
- * ...
+ * @param {Object} [options]
+ * @param {'narrow'|'short'|'long'} [options.weekday='long']
+ * @param {string} [options.timeZone] - Optional timezone
  *
- * text( getDayName( new Date() ) );
- *
- * --
- *
- * @param {Date|number} dateOrTimestamp
- *
- * @returns {string} name of the day (English)
+ * @returns {string} name of the day in the specified locale
  */
-export function getDayName(dateOrTimestamp: Date | number): string;
+export function getDayName(dateOrTimestamp: Date | number, locale?: string, options?: {
+    weekday?: "narrow" | "short" | "long";
+    timeZone?: string;
+}): string;
 /**
  * Return the timestamp of the start of the day
  * - Midnight
  *
- * @param {Date|number} dateOrTimestamp
+ * @param {Date|number} [dateOrTimestamp]
  *
  * @returns {number} timestamp of start of the day (00:00:00:0000)
  */
-export function getTimeAtStartOfDay(dateOrTimestamp: Date | number): number;
+export function getTimeAtStartOfDay(dateOrTimestamp?: Date | number): number;
 /**
  * Return the timestamp of the end of the day
  * - Midnight - 1 millisecond
  *
- * @param {Date|number} dateOrTimestamp
+ * @param {Date|number} [dateOrTimestamp]
  *
  * @returns {number} timestamp of start of the day
  */
-export function getTimeAtEndOfDay(dateOrTimestamp: Date | number): number;
-export const SECOND_MS: 1000;
-export const MINUTE_MS: number;
-export const HOUR_MS: number;
-export const DAY_MS: number;
-export const WEEK_MS: number;
-export const TIME_2020_01_01: 1577836800000;
-export const TIME_2100_01_01: 4102444800000;
+export function getTimeAtEndOfDay(dateOrTimestamp?: Date | number): number;
+import { HkPromise } from '../../classes/promise/index.js';

package/dist/util/time/index.js

@@ -28,24 +28,16 @@
  *   }).format(d);
  */
 
-/* ------------------------------------------------------------------ Imports */
-
-import * as expect from '../expect/index.js';
+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';
 
-/* ---------------------------------------------------------------- Internals */
-
-/* ------------------------------------------------------------------ Exports */
-
-export const SECOND_MS = 1000;
-export const MINUTE_MS = 60 * SECOND_MS;
-export const HOUR_MS = 60 * MINUTE_MS;
-export const DAY_MS = 24 * HOUR_MS;
-export const WEEK_MS = 7 * DAY_MS;
-
-export const TIME_2020_01_01 = 1577836800000; // 2020-01-01T00:00:00.000Z
-export const TIME_2100_01_01 = 4102444800000; // 2100-01-01T00:00:00.000Z
-
 /**
  * Returns a promise that resolves after a specified timeout
  * - If the returned promise is rejected, the timeout is cancelled
@@ -58,7 +50,7 @@ export const TIME_2100_01_01 = 4102444800000; // 2100-01-01T00:00:00.000Z
  *   resolves. If this parameter is set, the delay will be chosen randomly
  *   between the values [delayOrMinDelayMs, maxDelayMs]
  *
- * @returns {Promise} promise that resolves after a specified timeout
+ * @returns {HkPromise} promise that resolves after a specified timeout
  */
 export function delay(delayOrMinDelayMs, maxDelayMs) {
 	expect.number(delayOrMinDelayMs);
@@ -92,22 +84,18 @@ export function delay(delayOrMinDelayMs, maxDelayMs) {
 	return promise;
 }
 
-// -----------------------------------------------------------------------------
-
 /**
  * Get the number of milliseconds since the specified time stamp of the default
- * reference time stamp TIME_2020_01_01
+ * reference time stamp TIME_2025_01_01
  *
- * @param {number} [sinceMs=TIME_2020_01_01]
+ * @param {number} [sinceMs=TIME_2025_01_01]
  *
  * @returns {number} number of milliseconds since the specified time
  */
-export function sinceMs(sinceMs = TIME_2020_01_01) {
+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
@@ -144,13 +132,11 @@ export function timeToString(timeMs) {
 
 	str += `${minutes.toString().padStart(2, '0')}:`;
 	str += `${seconds.toString().padStart(2, '0')}.`;
-	str += `${restMs.toString().padEnd(3, '0')}`;
+	str += `${restMs.toString().padStart(3, '0')}`;
 
 	return str;
 }
 
-// -----------------------------------------------------------------------------
-
 /**
  * Returns a Date object
  * - The input can be a Date object or a numeric timestamp
@@ -171,8 +157,6 @@ export function toDate(dateOrTimestamp) {
 	throw new Error('Missing or invalid parameter [dateOrTimestamp]');
 }
 
-// -----------------------------------------------------------------------------
-
 /**
  * Get the ISO 8601 week number of the specified date
  *
@@ -225,70 +209,72 @@ export function getWeekNumber(dateOrTimestamp) {
 	// of the year and the Thursday in the target week
 	// (604800000 = 7 * 24 * 3600 * 1000)
 	//
-	return 1 + Math.ceil((firstThursday - target) / 604800000);
+	return 1 + Math.ceil((firstThursday - target.getTime()) / 604800000);
 }
 
-// -----------------------------------------------------------------------------
-
 /**
  * Get the name of the month
- * - Returns the English name of the month
- *
- * - Use the output as label in combination with the functions
- *   text() and translate() for international month names
- *
- * e.g.
+ * - Returns the month name using Intl.DateTimeFormat
+ * - By default uses English locale, but locale can be specified
  *
- * setTranslations()
- * ...
+ * @param {Date|number} dateOrTimestamp - Date object or timestamp
+ * @param {string} [locale='nl-NL'] - The locale to use for the month name
  *
- * text( getMonthName( new Date() ) );
+ * @param {Object} [options]
+ * @param {'numeric'|'2-digit'|'narrow'|'short'|'long'} [options.month='long']
+ * @param {string} [options.timeZone] - Optional timezone
  *
- * --
- *
- * @param {Date|number} dateOrTimestamp
- *
- * @returns {string} name of the month (English)
+ * @returns {string} name of the month in the specified locale
  */
-export function getMonthName(dateOrTimestamp) {
-	throw new Error('Not implemented yet');
-	// return MONTH_NAME_LABELS_EN[toDate(dateOrTimestamp).getMonth()];
-}
+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
- * - Returns the English name of the day
- *
- * - Use the output as label in combination with the functions
- *   text() and translate() for international day names
+ * 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
  *
- * e.g.
+ * @param {Date|number} dateOrTimestamp - Date object or timestamp
+ * @param {string} [locale='nl-NL'] - The locale to use for the day name
  *
- * setTranslations()
- * ...
- *
- * text( getDayName( new Date() ) );
- *
- * --
- *
- * @param {Date|number} dateOrTimestamp
+ * @param {Object} [options]
+ * @param {'narrow'|'short'|'long'} [options.weekday='long']
+ * @param {string} [options.timeZone] - Optional timezone
  *
- * @returns {string} name of the day (English)
+ * @returns {string} name of the day in the specified locale
  */
-export function getDayName(dateOrTimestamp) {
-	throw new Error('Not implemented yet');
-	// return DAY_NAME_LABELS_EN[toDate(dateOrTimestamp).getDay()];
-}
+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
+ * @param {Date|number} [dateOrTimestamp]
  *
  * @returns {number} timestamp of start of the day (00:00:00:0000)
  */
@@ -310,13 +296,11 @@ export function getTimeAtStartOfDay(dateOrTimestamp) {
 	return d.getTime();
 }
 
-// -----------------------------------------------------------------------------
-
 /**
  * Return the timestamp of the end of the day
  * - Midnight - 1 millisecond
  *
- * @param {Date|number} dateOrTimestamp
+ * @param {Date|number} [dateOrTimestamp]
  *
  * @returns {number} timestamp of start of the day
  */

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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-sveltekit",
-	"version": "0.1.58",
+	"version": "0.1.60",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"