@did-btcr2/common 2.2.2 → 3.1.0

package/src/logger.ts

@@ -51,18 +51,35 @@ const LEVEL_METHODS: Record<Level, keyof Console> = {
  * - File/line tracing
  * - Timestamps
  * - Colorized output
+ * @class Logger
+ * @type {Logger}
  */
 export class Logger {
   private levels: Level[];
   private namespace?: string;
+  private useColors: boolean;
+  private static shared: Logger;
 
-  constructor(namespace?: string) {
-    this.levels = LOG_LEVELS[NODE_ENV] || [];
-    this.namespace = namespace ?? 'did-btcr2-js';
+  /**
+   * Creates a new Logger instance.
+   * @param {string} namespace - Optional namespace for log messages.
+   * @param {Object} options - Configuration options.
+   * @param {Level[]} options.levels - Log levels to enable.
+   * @param {boolean} options.useColors - Whether to use colored output.
+   */
+  constructor(namespace?: string, options: { levels?: Level[]; useColors?: boolean } = {}) {
+    this.levels = options.levels || LOG_LEVELS[NODE_ENV] || [];
+    this.namespace = namespace || 'did-btcr2-js';
+    const envForce = process.env.LOG_COLORS;
+    this.useColors = options.useColors || (envForce ? envForce !== '0' && envForce.toLowerCase() !== 'false' : Boolean(process.stdout.isTTY));
   }
 
   /**
    * Logs a message with the specified level.
+   * @param {Level} level - The log level.
+   * @param {unknown} message - The message to log.
+   * @param {...unknown[]} args - Additional arguments to log.
+   * @returns {void}
    */
   private _log(level: Level, message?: unknown, ...args: unknown[]): void {
     if (!this.levels.includes(level)) return;
@@ -72,70 +89,85 @@ export class Logger {
 
     const timestamp = new Date().toISOString();
     const namespace = this.namespace ? `[${this.namespace}]` : '';
+    const render = this.useColors ? color : (v: string) => v;
+    const renderGray = this.useColors ? chalk.gray : (v: string) => v;
 
     (console[method] as (...args: any[]) => void)(
-      `${chalk.gray(timestamp)} ${namespace} ${color(level)}: ${chalk.white(message)}`,
+      `${renderGray(timestamp)} ${namespace} ${render(level)}: ${message}`,
       ...args
     );
   }
 
-  // 🔹 Instance-based logging methods
-  public debug(message?: unknown, ...args: unknown[]) {
+  debug(message?: unknown, ...args: unknown[]): Logger {
     this._log('debug', message, ...args); return this;
   }
 
-  public error(message?: unknown, ...args: unknown[]) {
+  error(message?: unknown, ...args: unknown[]): Logger {
     this._log('error', message, ...args); return this;
   }
 
-  public info(message?: unknown, ...args: unknown[]) {
+  info(message?: unknown, ...args: unknown[]): Logger {
     this._log('info', message, ...args); return this;
   }
 
-  public warn(message?: unknown, ...args: unknown[]) {
+  warn(message?: unknown, ...args: unknown[]): Logger {
     this._log('warn', message, ...args); return this;
   }
 
-  public security(message?: unknown, ...args: unknown[]) {
+  security(message?: unknown, ...args: unknown[]): Logger {
     this._log('security', message, ...args); return this;
   }
 
-  public log(message?: unknown, ...args: unknown[]) {
+  log(message?: unknown, ...args: unknown[]): Logger {
     this._log('log', message, ...args); return this;
   }
 
-  public newline() {
+  newline(): Logger {
     console.log(); return this;
   }
 
   /**
    * Static methods for convenience (auto-instantiate).
+   * These use a shared singleton instance.
+   * @param {unknown} message - The message to log.
+   * @param {...unknown[]} args - Additional arguments to log.
+   * @returns {void}
    */
-  public static debug(message?: unknown, ...args: unknown[]) {
-    new Logger().debug(message, ...args);
+  static debug(message?: unknown, ...args: unknown[]): void {
+    Logger.instance().debug(message, ...args);
   }
 
-  public static error(message?: unknown, ...args: unknown[]) {
-    new Logger().error(message, ...args);
+  static error(message?: unknown, ...args: unknown[]): void {
+    Logger.instance().error(message, ...args);
   }
 
-  public static info(message?: unknown, ...args: unknown[]) {
-    new Logger().info(message, ...args);
+  static info(message?: unknown, ...args: unknown[]): void {
+    Logger.instance().info(message, ...args);
   }
 
-  public static warn(message?: unknown, ...args: unknown[]) {
-    new Logger().warn(message, ...args);
+  static warn(message?: unknown, ...args: unknown[]): void {
+    Logger.instance().warn(message, ...args);
   }
 
-  public static security(message?: unknown, ...args: unknown[]) {
-    new Logger().security(message, ...args);
+  static security(message?: unknown, ...args: unknown[]): void {
+    Logger.instance().security(message, ...args);
   }
 
-  public static log(message?: unknown, ...args: unknown[]) {
-    new Logger().log(message, ...args);
+  static log(message?: unknown, ...args: unknown[]): void {
+    Logger.instance().log(message, ...args);
   }
 
-  public static newline() {
-    new Logger().newline();
+  static newline() {
+    Logger.instance().newline();
   }
-}
+
+  private static instance(levels?: Level[], useColors?: boolean): Logger {
+    if (!Logger.shared) {
+      Logger.shared = new Logger(undefined, { levels, useColors });
+    } else {
+      if (levels) Logger.shared.levels = levels;
+      if (useColors !== undefined) Logger.shared.useColors = useColors;
+    }
+    return Logger.shared;
+  }
+}

package/src/types.ts

@@ -3,6 +3,7 @@ import { HDKey } from '@scure/bip32';
 /* Crypto Types */
 export type Bytes = Uint8Array;
 export type Hex = Bytes | string;
+export type HexString = string;
 export type SignatureHex = Hex;
 export type HashHex = Hex;
 
@@ -72,14 +73,18 @@ export type BeaconUri = string;
 export type DidPlaceholder = 'did:btcr2:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
 export type CanonicalizedProofConfig = string;
 export type CryptosuiteName = 'bip340-jcs-2025' | 'bip340-rdfc-2025';
-export type ContextObject = Record<string | number | symbol, any>;
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonArray = JsonValue[];
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+export type JsonObject = { [key: string]: JsonValue };
+export type JSONObject = JsonObject; // JSON object: prototyped or unprototyped
+export type Prototyped = JSONObject;
+export type Unprototyped = JSONObject;
+export type ContextObject = Record<string, JsonValue>;
 export type Context = string | string[] | ContextObject | ContextObject[]
 
 /* General Types */
-export type Maybe<T> = T | any;
-export type JSONObject = Record<string | number | symbol, any>; // JSON object: prototyped or unprototyped
-export type Prototyped = JSONObject;
-export type Unprototyped = JSONObject;
+export type Maybe<T> = T | unknown;
 export type TwoDigits = `${number}${number}`;
 export type ThreeDigits = `${number}${number}${number}`;
 export type Year = `${1 | 2}${ThreeDigits}`;
@@ -93,4 +98,5 @@ export type TzOffset = `${Hours}:${Minutes}`;
 export type DateTimestamp = `${UtcTimestamp}Z` | `${UtcTimestamp}-${TzOffset}`;
 export type CanonicalizableObject = Record<string, any>;
 export type CanonicalizationAlgorithm = 'jcs' | 'rdfc';
-export type UnixTimestamp = number;
+export type CanonicalizationEncoding = 'hex' | 'base58';
+export type UnixTimestamp = number;

package/src/utils/date.ts

@@ -0,0 +1,130 @@
+/**
+ * Utility class for date-related operations.
+ * @name DateUtils
+ * @class DateUtils
+ */
+export class DateUtils {
+  /**
+   * Render an ISO 8601 UTC timestamp without fractional seconds.
+   * @param {Date} [date=new Date()] - The date to format.
+   * @returns {string} The formatted date string.
+   */
+  static toISOStringNonFractional(date: Date = new Date()): string {
+    const time = date.getTime();
+    if (Number.isNaN(time)) {
+      throw new Error(`Invalid date: ${date}`);
+    }
+    return date.toISOString().replace(/\.\d{3}Z$/, 'Z');
+  }
+
+  /**
+   * Unix timestamp in seconds (integer).
+   * @param {Date} [date=new Date()] - The date to convert.
+   * @returns {number} The Unix timestamp in seconds.
+   */
+  static toUnixSeconds(date: Date = new Date()): number {
+    const time = date.getTime();
+    if (Number.isNaN(time)) {
+      throw new Error(`Invalid date: ${date}`);
+    }
+    return Math.floor(date.getTime() / 1000);
+  }
+
+  /**
+   * Validate if a string is a valid UTC date string.
+   * @param {string} dateString - The date string to validate.
+   * @returns {boolean} True if valid, otherwise false.
+   * @throws {Error} If the date string is invalid.
+   */
+  static dateStringToTimestamp(dateString: string): Date {
+    const date = new Date(dateString);
+    if (Number.isNaN(date.getTime())) {
+      return new Date(0);
+    }
+    return date;
+  }
+
+  /**
+   * Convert a blocktime (Unix timestamp in seconds) to a Date object.
+   * @param {number} blocktime - The blocktime in seconds.
+   * @returns {Date} The corresponding Date object.
+   */
+  static blocktimeToTimestamp(blocktime: number): Date {
+    return new Date(blocktime * 1000);
+  }
+
+  /**
+   * Validates an XMLSCHEMA11-2 dateTime string.
+   * Format: [-]YYYY-MM-DDThh:mm:ss[.fractional][Z|(+|-)hh:mm]
+   *
+   * @see https://www.w3.org/TR/xmlschema11-2/#dateTime
+   */
+  static isValidXsdDateTime(value?: string): boolean {
+    // Empty or undefined value is not a valid dateTime
+    if(!value) return false;
+
+    // Regex for XML Schema dateTime:
+    // - Optional leading minus for BCE years
+    // - Year: 4+ digits
+    // - Month: 01-12
+    // - Day: 01-31 (further validated below)
+    // - T separator
+    // - Hour: 00-23 (24:00:00 is valid end-of-day per spec)
+    // - Minute: 00-59
+    // - Second: 00-59 (with optional fractional part)
+    // - Timezone: Z or (+|-)hh:mm
+    const xsdDateTimeRegex =
+        /^-?(\d{4,})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;
+
+    const match = value.match(xsdDateTimeRegex);
+    if (!match) return false;
+
+    const [, y, m, d, H, M, S, , tz] = match;
+
+    const year = parseInt(y, 10);
+    const month = parseInt(m, 10);
+    const day = parseInt(d, 10);
+    const hour = parseInt(H, 10);
+    const minute = parseInt(M, 10);
+    const second = parseInt(S, 10);
+
+    // Year 0000 is not valid in XML Schema (no year zero)
+    if (year === 0) return false;
+
+    // Month: 1-12
+    if (month < 1 || month > 12) return false;
+
+    // Day: validate against month (and leap year for February)
+    const daysInMonth = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    const isLeapYear = (year % 4 === 0 && year % 100 !== 0) || (year % 400 === 0);
+    const maxDay = month === 2 && isLeapYear ? 29 : daysInMonth[month - 1];
+    if (day < 1 || day > maxDay) return false;
+
+    // Hour: 00-23, or 24:00:00 exactly (end-of-day)
+    if (hour === 24) {
+      if (minute !== 0 || second !== 0) return false;
+    } else if (hour > 23) {
+      return false;
+    }
+
+    // Minute: 00-59
+    if (minute > 59) return false;
+
+    // Second: 00-59 (leap second 60 is debatable; XML Schema doesn't explicitly allow it)
+    if (second > 59) return false;
+
+    // Validate timezone offset if present
+    if (tz && tz !== 'Z') {
+      const tzMatch = tz.match(/^[+-](\d{2}):(\d{2})$/);
+      if (tzMatch) {
+        const tzHour = parseInt(tzMatch[1], 10);
+        const tzMin = parseInt(tzMatch[2], 10);
+        if (tzHour > 14 || (tzHour === 14 && tzMin !== 0) || tzMin > 59) {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }
+}

package/src/utils/json.ts

@@ -0,0 +1,315 @@
+import { JSONObject, Prototyped, Unprototyped } from '../types.js';
+
+/**
+ * Options for cloning JSON values.
+ */
+type CloneOptions = {
+  stripPrototypes?: boolean;
+  transform?: (value: any) => any;
+};
+
+/**
+ * Utilities for working with JSON data.
+ * @name JSONUtils
+ * @class JSONUtils
+ */
+export class JSONUtils {
+  /**
+   * Check if a value is a JSON object (not an array, not null, and has Object prototype).
+   * @param {unknown} value - The value to check.
+   * @returns {boolean} True if the value is a JSON object.
+   */
+  static isObject(value: unknown): value is JSONObject {
+    if (value === null || typeof value !== 'object') return false;
+    if (Array.isArray(value)) return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+  }
+
+  /**
+   * Check if a value is a parsable JSON string.
+   * @param {unknown} value - The value to check.
+   * @returns {boolean} True if the value is a parsable JSON string.
+   */
+  static isParsable(value: unknown): value is string {
+    if (typeof value !== 'string') return false;
+    try {
+      JSON.parse(value);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Check if a value is an unprototyped object (i.e., Object.create(null)).
+   * @param {unknown} value - The value to check.
+   * @returns {boolean} True if the value is an unprototyped object.
+   */
+  static isUnprototyped(value: unknown): value is Unprototyped {
+    if (value === null || typeof value !== 'object') return false;
+    return Object.getPrototypeOf(value) === null;
+  }
+
+  /**
+   * Normalize a JSON value by stripping prototypes from all objects within it.
+   * @param {T} value - The JSON value to normalize.
+   * @returns {Prototyped} The normalized JSON value.
+   */
+  static normalize<T extends JSONObject | Array<any>>(value: T): Prototyped {
+    return this.cloneInternal(value, { stripPrototypes: true });
+  }
+
+  /**
+   * Shallow copy of a JSON object.
+   * @param {T extends JSONObject} value - The JSON object to copy.
+   * @returns {T} The copied JSON object.
+   */
+  static copy<T extends JSONObject>(value: T): T {
+    return { ...value };
+  }
+
+  /**
+   * Deep clone a JSON value.
+   * @param {T} value - The JSON value to clone.
+   * @returns {T} The cloned JSON value.
+   */
+  static clone<T>(value: T): T {
+    if (typeof structuredClone === 'function') {
+      return structuredClone(value);
+    }
+    return this.cloneInternal(value);
+  }
+
+  /**
+   * Deep clone a JSON value, replacing strings that match a pattern.
+   * @param {T} value - The JSON value to clone.
+   * @param {RegExp} pattern - The regex pattern to match strings.
+   * @param {string} replacement - The replacement string.
+   * @returns {T} The cloned JSON value with replacements.
+   */
+  static cloneReplace<T>(value: T, pattern: RegExp, replacement: string): T {
+    return this.cloneInternal(value, {
+      transform : (candidate) => typeof candidate === 'string'
+        ? candidate.replace(pattern, replacement)
+        : candidate
+    });
+  }
+
+  /**
+   * Deep equality check between two values.
+   * @param {unknown} a - The first value to compare.
+   * @param {unknown} b - The second value to compare.
+   * @param {WeakMap<object, object>} seen - A WeakMap to track seen object pairs for circular reference detection.
+   * @returns {boolean} True if the values are deeply equal.
+   */
+  static deepEqual(
+    a: unknown,
+    b: unknown,
+    seen: WeakMap<object, object> = new WeakMap<object, object>(),
+    depth: number = 0
+  ): boolean {
+    if (depth > 1024) {
+      throw new Error('Maximum comparison depth exceeded');
+    }
+    if (Object.is(a, b)) return true;
+
+    if (typeof a !== typeof b) return false;
+    if (a === null || b === null) return false;
+    if (typeof a !== 'object') return false;
+
+    if (seen.get(a as object) === b) return true;
+    seen.set(a as object, b as object);
+
+    if (ArrayBuffer.isView(a) && ArrayBuffer.isView(b)) {
+      const viewA = new Uint8Array((a as ArrayBufferView).buffer, (a as ArrayBufferView).byteOffset, (a as ArrayBufferView).byteLength);
+      const viewB = new Uint8Array((b as ArrayBufferView).buffer, (b as ArrayBufferView).byteOffset, (b as ArrayBufferView).byteLength);
+      if (viewA.byteLength !== viewB.byteLength) return false;
+      for (let i = 0; i < viewA.byteLength; i++) {
+        if (viewA[i] !== viewB[i]) return false;
+      }
+      return true;
+    }
+
+    if (a instanceof Date && b instanceof Date) {
+      return a.getTime() === b.getTime();
+    }
+
+    if (a instanceof Set && b instanceof Set) {
+      if (a.size !== b.size) return false;
+      for (const itemA of a) {
+        let matched = false;
+        for (const itemB of b) {
+          if (this.deepEqual(itemA, itemB, seen, depth + 1)) {
+            matched = true;
+            break;
+          }
+        }
+        if (!matched) return false;
+      }
+      return true;
+    }
+
+    if (a instanceof Map && b instanceof Map) {
+      if (a.size !== b.size) return false;
+      for (const [keyA, valueA] of a) {
+        let matched = false;
+        if (b.has(keyA)) {
+          matched = this.deepEqual(valueA, b.get(keyA), seen, depth + 1);
+        } else {
+          for (const [keyB, valueB] of b) {
+            if (
+              this.deepEqual(keyA, keyB, seen, depth + 1)
+              && this.deepEqual(valueA, valueB, seen, depth + 1)
+            ) {
+              matched = true;
+              break;
+            }
+          }
+        }
+        if (!matched) return false;
+      }
+      return true;
+    }
+
+    if (Array.isArray(a) && Array.isArray(b)) {
+      if (a.length !== b.length) return false;
+      for (let i = 0; i < a.length; i++) {
+        if (!this.deepEqual(a[i], b[i], seen, depth + 1)) return false;
+      }
+      return true;
+    }
+
+    const keysA = Object.keys(a as object);
+    const keysB = Object.keys(b as object);
+    if (keysA.length !== keysB.length) return false;
+
+    for (const key of keysA) {
+      if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+      if (!this.deepEqual((a as any)[key], (b as any)[key], seen, depth + 1)) return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Delete specified keys from a JSON value.
+   * @param {T} value - The JSON value to process.
+   * @param {Array<string | number | symbol>} keys - The keys to delete.
+   * @returns {T} The JSON value with specified keys deleted.
+   */
+  static deleteKeys<T>(value: T, keys: Array<string | number | symbol>): T {
+    const keySet = new Set(keys.map(key => typeof key === 'number' ? key.toString() : key));
+
+    const walk = (candidate: any): any => {
+      if (Array.isArray(candidate)) {
+        return candidate.map(item => walk(item));
+      }
+
+      if (candidate && typeof candidate === 'object') {
+        const result: any = Array.isArray(candidate) ? [] : {};
+        for (const key of Object.keys(candidate)) {
+          if (keySet.has(key)) continue;
+          result[key] = walk(candidate[key]);
+        }
+        return result;
+      }
+
+      return candidate;
+    };
+
+    return walk(value);
+  }
+
+  /**
+   * Sanitize a JSON value by removing undefined values from objects and arrays.
+   * @param {T} value - The JSON value to sanitize.
+   * @returns {T} The sanitized JSON value.
+   */
+  static sanitize<T>(value: T): T {
+    const walk = (candidate: any): any => {
+      if (Array.isArray(candidate)) {
+        return candidate.map(item => walk(item));
+      }
+
+      if (candidate && typeof candidate === 'object') {
+        const result: any = {};
+        for (const [key, val] of Object.entries(candidate)) {
+          const sanitized = walk(val);
+          if (sanitized !== undefined) {
+            result[key] = sanitized;
+          }
+        }
+        return result;
+      }
+
+      return candidate;
+    };
+
+    return walk(value);
+  }
+
+  /**
+   * Internal function to clone JSON values with options.
+   * @param {T} value - The value to clone.
+   * @param {CloneOptions} options - The cloning options.
+   * @param {WeakMap<object, any>} seen - A WeakMap to track seen objects for circular reference detection.
+   * @returns {any} The cloned value.
+   */
+  static cloneInternal<T>(
+    value: T,
+    options: CloneOptions = {},
+    seen: WeakMap<object, any> = new WeakMap<object, any>(),
+    depth: number = 0
+  ): any {
+    if (depth > 1024) {
+      throw new Error('Maximum clone depth exceeded');
+    }
+    const transformed = options.transform ? options.transform(value) : value;
+    if (transformed !== value) return transformed;
+
+    if (typeof value !== 'object' || value === null) {
+      return transformed;
+    }
+
+    if (seen.has(value as object)) {
+      throw new Error('Cannot clone circular structure');
+    }
+
+    // Handle arrays and typed arrays
+    if (Array.isArray(value)) {
+      const clone: any[] = [];
+      seen.set(value as object, clone);
+      for (const item of value) {
+        clone.push(this.cloneInternal(item, options, seen, depth + 1));
+      }
+      return clone;
+    }
+
+    // Handle ArrayBuffer views (typed arrays, DataView)
+    if (ArrayBuffer.isView(value)) {
+      if (value instanceof DataView) {
+        return new DataView(
+          value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength)
+        );
+      }
+
+      if (typeof (value as any).slice === 'function') {
+        return (value as any).slice();
+      }
+    }
+
+    if (value instanceof Date) {
+      return new Date(value.getTime());
+    }
+
+    const result: any = options.stripPrototypes ? {} : Object.create(Object.getPrototypeOf(value));
+    seen.set(value as object, result);
+
+    for (const key of Object.keys(value as object)) {
+      result[key] = this.cloneInternal((value as any)[key], options, seen, depth + 1);
+    }
+
+    return result;
+  }
+}

package/src/utils/set.ts

@@ -0,0 +1,23 @@
+/**
+ * Utility class for set operations.
+ * @name SetUtils
+ * @class SetUtils
+ */
+export class SetUtils {
+  /**
+   * Compute the set difference without mutating the inputs.
+   * @param {Set<T>} left - The left set.
+   * @param {Set<T>} right - The right set.
+   * @returns {Set<T>} A new set containing elements in `left` that are not in `right`.
+   */
+  static difference<T>(left: Set<T>, right: Set<T>): Set<T> {
+    const result = new Set<T>();
+    for (const value of left) {
+      if (!right.has(value)) {
+        result.add(value);
+      }
+    }
+    return result;
+  }
+
+}