@hkdigital/lib-core 0.3.9 → 0.3.11

package/dist/util/unique/index.js

@@ -1,249 +1,231 @@
-/**
- * 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/index.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 );
-  }
-}
+/**
+ * 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/index.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/README.md

@@ -0,0 +1,50 @@
+# Valibot Parsers
+
+Collection of Valibot validation parsers for common data types and formats.
+
+## Overview
+
+This module provides pre-configured Valibot parsers for validating and transforming common data types like URLs and user information.
+
+## Parsers
+
+### URL Parsers
+
+- `UrlOrEmptyString` - Validates URL or allows empty string
+- `HumanUrl` - Validates URL with automatic `https://` prefix for protocol-less URLs
+- `UrlPath` - Extracts and validates URL pathname
+- `RelativeUrl` - Validates relative URLs with path, search, and hash
+- `AbsOrRelUrl` - Validates absolute or relative URLs
+
+### User Parsers
+
+- `Name` - Validates user names
+- `Fullname` - Validates full names
+- `Username` - Validates usernames
+- `Surname` - Validates surnames
+- `PhoneNumber` - Validates phone numbers
+
+## Usage
+
+```js
+import { v, HumanUrl, Name } from '$lib/valibot/index.js';
+
+// Validates and transforms URL (throws error if invalid)
+const result = v.parse(HumanUrl, 'example.com'); // Returns 'https://example.com'
+
+// Validates name (throws error if invalid)
+const nameResult = v.parse(Name, 'John');
+
+// Use safeParse to avoid exceptions
+const safeResult = v.safeParse(HumanUrl, 'invalid-url');
+if (safeResult.success) {
+  console.log(safeResult.output);
+} else {
+  console.log(safeResult.issues); // Array of issue objects
+}
+```
+
+## References
+
+- [SafeParseResult API](https://valibot.dev/api/SafeParseResult/)
+- [BaseIssue API](https://valibot.dev/api/BaseIssue/)

package/dist/valibot/index.d.ts

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

package/dist/valibot/index.js

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

package/dist/valibot/{url.d.ts → parsers/url.d.ts}

@@ -1,26 +1,34 @@
 /**
- * Schema to validate an URL or empty string.
+ * Parser for 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
+ * Parser for 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
+ * Parser for 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
+ * Parser for 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
+ * Parser for 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>;
+/**
+ * Parser for URL slug (e.g., "my-blog-post", "user-123")
+ *
+ * @note Must start and end with Latin characters or numbers
+ * @note Hyphens are allowed between character groups
+ * @note Automatically converts to lowercase
+ */
+export const Slug: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.ToLowerCaseAction, v.RegexAction<string, "Must be a valid URL slug">]>;
 import * as v from 'valibot';