@tstdl/base 0.93.36 → 0.93.38

package/source/utils/feedable-async-iterable.ts

@@ -1,60 +0,0 @@
-import { firstValueFrom, Subject } from 'rxjs';
-
-import { CancellationToken } from '#/cancellation/token.js';
-import { CircularBuffer } from '#/data-structures/circular-buffer.js';
-
-export class FeedableAsyncIterable<T> implements AsyncIterable<T> {
-  private readonly readSubject = new Subject<void>();
-  private readonly closedToken = new CancellationToken();
-  private readonly buffer = new CircularBuffer<{ item: T, error: undefined } | { item: undefined, error: Error }>();
-
-  get $read(): Promise<void> {
-    return firstValueFrom(this.readSubject);
-  }
-
-  get $empty(): Promise<void> {
-    return this.buffer.$onEmpty;
-  }
-
-  get closed(): boolean {
-    return this.closedToken.isSet;
-  }
-
-  get bufferSize(): number {
-    return this.buffer.size;
-  }
-
-  feed(item: T): void {
-    if (this.closed) {
-      throw new Error('Feedable is already closed.');
-    }
-
-    this.buffer.add({ item, error: undefined });
-  }
-
-  end(): void {
-    this.closedToken.set();
-  }
-
-  throw(error: Error): void {
-    if (this.closed) {
-      throw new Error('Feedable is already closed.');
-    }
-
-    this.buffer.add({ item: undefined, error });
-    this.end();
-  }
-
-  async *[Symbol.asyncIterator](): AsyncIterableIterator<T> {
-    const consumer = this.buffer.consumeAsync(this.closedToken, true);
-
-    for await (const entry of consumer) {
-      if (entry.error != undefined) {
-        throw entry.error;
-      }
-
-      yield entry.item;
-      this.readSubject.next();
-    }
-  }
-}

package/source/utils/file-reader.ts

@@ -1,27 +0,0 @@
-import { DetailsError } from '../errors/details.error.js';
-
-export async function readAsText(blob: Blob, encoding?: string): Promise<string> {
-  return setup((reader) => reader.readAsText(blob, encoding));
-}
-
-export async function readAsArrayBuffer(blob: Blob): Promise<ArrayBuffer> {
-  return setup((reader) => reader.readAsArrayBuffer(blob));
-}
-
-export async function readAsBinaryString(blob: Blob): Promise<string> {
-  return setup((reader) => reader.readAsBinaryString(blob));
-}
-
-export async function readAsDataUrl(blob: Blob): Promise<string> {
-  return setup((reader) => reader.readAsDataURL(blob));
-}
-
-async function setup<T extends FileReader['result']>(dispatcher: (reader: FileReader) => void): Promise<T> {
-  return new Promise<T>((resolve, reject) => {
-    const reader = new FileReader();
-    reader.onload = () => resolve(reader.result as T);
-    reader.onerror = () => reject(new DetailsError(reader.error!.message, reader.error));
-
-    dispatcher(reader);
-  });
-}

package/source/utils/format-error.ts

@@ -1,133 +0,0 @@
-import { unwrapError } from '#/errors/utils.js';
-import type { Record, UndefinableJson } from '#/types/index.js';
-import { decycle } from './object/decycle.js';
-import { objectKeys } from './object/object.js';
-import { tryChain } from './try-chain.js';
-import { isArray, isDefined, isFunction, isObject, isUndefined } from './type-guards.js';
-
-export type FormatErrorOptions = {
-  /**
-   * Include error name in message
-   */
-  includeName?: boolean,
-
-  /**
-   * Include all error properties beside name and message
-   */
-  includeRest?: boolean | 'if-no-extra-info',
-
-  /**
-   * Include extraInfo from errors implementing {@link ErrorExtraInfo}
-   */
-  includeExtraInfo?: boolean,
-
-  /**
-   * Include stack trace
-   */
-  includeStack?: boolean,
-
-  /**
-   * Maximum recursion depth for nested causes and aggregate errors (default: 5)
-   */
-  depth?: number,
-};
-
-export interface ErrorExtraInfo {
-  /** Format extra data (without message and stack) as JSON */
-  getExtraInfo(): UndefinableJson | undefined;
-}
-
-/**
- * Enhanced error formatting
- */
-export function formatError(error: any, options: FormatErrorOptions = {}): string {
-  const {
-    includeName = true,
-    includeRest = 'if-no-extra-info',
-    includeExtraInfo = true,
-    includeStack = true,
-    depth = 5,
-  } = options;
-
-  if (depth <= 0) {
-    return '[Max recursion depth reached]';
-  }
-
-  const actualError = unwrapError(error);
-
-  let name: string | undefined;
-  let message: string | undefined;
-  let stack: string | undefined;
-  let rest: Record | undefined;
-  let extraInfo: UndefinableJson | undefined;
-  let cause: unknown;
-  let aggregateErrors: unknown[] | undefined;
-
-  if (isObject(actualError)) {
-    if (actualError instanceof Error) {
-      ({ name, message, stack, cause, ...rest } = actualError);
-
-      if (actualError instanceof AggregateError) {
-        aggregateErrors = actualError.errors;
-      }
-    }
-    else {
-      // Handle plain objects that might have error-like properties
-      ({ name, message, stack, cause, ...rest } = actualError as any);
-    }
-
-    // Check for extra info (duck-typing)
-    if (includeExtraInfo && isFunction((actualError as ErrorExtraInfo).getExtraInfo)) { // eslint-disable-line @typescript-eslint/unbound-method
-      extraInfo = (actualError as ErrorExtraInfo).getExtraInfo();
-    }
-  }
-
-  // If no message, serialize the whole object as a fallback
-  if (isUndefined(message) || String(message).trim().length === 0) { // eslint-disable-line @typescript-eslint/no-unnecessary-type-conversion
-    // Handle primitives directly
-    if (!isObject(actualError)) {
-      message = String(actualError);
-    }
-    else {
-      message = tryChain([
-        () => JSON.stringify(actualError, null, 2), // Try normal serialization first
-        () => {
-          // Fallback with decycle for objects with circular references
-          const decycledError = decycle(actualError);
-          return JSON.stringify(decycledError, null, 2);
-        },
-        // eslint-disable-next-line @typescript-eslint/no-base-to-string
-        () => `[Unstringifiable object: ${String(actualError)}]`, // Safe fallback if JSON.stringify still fails
-      ]);
-    }
-  }
-
-  // --- String Assembly ---
-
-  const nameString = includeName ? `${name ?? 'Error'}: ` : '';
-
-  let restString = '';
-  const shouldIncludeRest = (includeRest == true) || (includeRest == 'if-no-extra-info' && isUndefined(extraInfo));
-
-  if (shouldIncludeRest && isDefined(rest) && objectKeys(rest).length > 0) {
-    restString = `\n${JSON.stringify(decycle(rest), null, 2)}`;
-  }
-
-  const extraInfoString = isDefined(extraInfo) ? `\n${JSON.stringify(extraInfo, null, 2)}` : '';
-  const stackString = (includeStack && isDefined(stack)) ? `\n${stack}` : '';
-
-  const causeString = includeStack && cause
-    ? formatNestedError('Caused by:', cause, { ...options, depth: depth - 1 })
-    : '';
-
-  const aggregateErrorsString = isArray(aggregateErrors)
-    ? aggregateErrors.map((err, i) => formatNestedError(`Sub-error #${i + 1}:`, err, { ...options, depth: depth - 1 })).join('')
-    : '';
-
-  return `${nameString}${message}${restString}${extraInfoString}${stackString}${causeString}${aggregateErrorsString}`;
-}
-
-function formatNestedError(prefix: string, error: any, options: FormatErrorOptions): string {
-  const formatted = formatError(error, options).replace(/\n/g, '\n  ');
-  return `\n\n${prefix}\n  ${formatted}`;
-}

package/source/utils/format.ts

@@ -1,42 +0,0 @@
-import { kibibyte, kilobyte, microsecondsPerMillisecond, millisecondsPerSecond, nanosecondsPerMillisecond } from './units.js';
-
-const siByteSizes = ['B', 'kB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
-const iecByteSizes = ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB'];
-
-export function formatDuration(milliseconds: number, precision: number): string {
-  let value: number;
-  let suffix: string;
-
-  if (milliseconds >= millisecondsPerSecond) {
-    value = milliseconds / millisecondsPerSecond;
-    suffix = 's';
-  }
-  else if (milliseconds >= 1) {
-    value = milliseconds;
-    suffix = 'ms';
-  }
-  else if (milliseconds >= 1 / microsecondsPerMillisecond) {
-    value = milliseconds * microsecondsPerMillisecond;
-    suffix = 'us';
-  }
-  else {
-    value = milliseconds * nanosecondsPerMillisecond;
-    suffix = 'ns';
-  }
-
-  const trimmed = parseFloat(value.toFixed(precision));
-  const result = `${trimmed} ${suffix}`;
-
-  return result;
-}
-
-export function formatBytes(bytes: number, { decimals = 2, unit = 'IEC' }: { decimals?: number, unit?: 'SI' | 'IEC' } = {}): string {
-  const iec = unit == 'IEC';
-  const base = iec ? kibibyte : kilobyte;
-  const exponent = Math.floor(Math.log(bytes) / Math.log(base));
-  const prefix = (iec ? iecByteSizes : siByteSizes)[exponent];
-  const result = (bytes / (base ** exponent));
-  const formattedResult = Intl.NumberFormat(undefined, { useGrouping: false, maximumFractionDigits: decimals }).format(result);
-
-  return `${formattedResult} ${prefix}`;
-}

package/source/utils/function/class.ts

@@ -1,14 +0,0 @@
-import type { AbstractConstructor } from '#/types/index.js';
-import { isUndefined } from '../type-guards.js';
-
-declare class EmptyClass { }
-
-export function getClassOfName(name: string): typeof EmptyClass;
-export function getClassOfName<T extends AbstractConstructor>(name: string, extend: T): T;
-export function getClassOfName(name: string, extend?: AbstractConstructor): AbstractConstructor {
-  if (isUndefined(extend)) {
-    return { [name]: class { } }[name]!;
-  }
-
-  return { [name]: class extends extend { } }[name]!;
-}

package/source/utils/function/index.ts

@@ -1,3 +0,0 @@
-export * from './class.js';
-export * from './memoize.js';
-export * from './throttle.js';

package/source/utils/function/memoize.ts

@@ -1,190 +0,0 @@
-import { IterableWeakMap } from '#/data-structures/iterable-weak-map.js';
-import { MultiKeyMap } from '#/data-structures/multi-key-map.js';
-import { createAccessorDecorator } from '#/reflection/index.js';
-import type { Constructor } from '#/types/index.js';
-import { assertDefinedPass, isDefined } from '#/utils/type-guards.js';
-import { hasOwnProperty } from '../object/object.js';
-
-export type MemoizeOptions = {
-  /** Use WeakMap instead of Map for caching. Can be used with object parameters only */
-  weak?: boolean,
-};
-
-/**
- * Memoizes a function with an arbitrary number of parameters. If you only need a single parameter, {@link memoizeSingle} is faster
- * @param fn function memoize
- * @returns memoized function
- */export function memoize<Fn extends (...parameters: any[]) => any>(fn: Fn, options: MemoizeOptions = {}): Fn {
-  const cache = new MultiKeyMap<any, any>((options.weak ?? false) ? () => new IterableWeakMap() : undefined);
-  const name = getMemoizedName(fn);
-
-  return {
-    [name](...parameters: Parameters<Fn>): any {
-      if (cache.has(parameters)) {
-        return cache.get(parameters)!;
-      }
-
-      const result = fn.call(this, ...parameters);
-      cache.set(parameters, result);
-
-      return result;
-    },
-  }[name] as Fn;
-}
-
-/**
- * Memoizes a function with a single parameter. Faster than {@link memoize}
- * @param fn function memoize
- * @returns memoized function
- */
-export function memoizeSingle<Fn extends (parameter: any) => any>(fn: Fn, options: MemoizeOptions = {}): Fn {
-  const cache = (options.weak ?? false) ? new IterableWeakMap() : new Map<any, any>();
-  const name = getMemoizedName(fn);
-
-  return {
-    [name](parameter: any): any {
-      if (cache.has(parameter)) {
-        return cache.get(parameter)!;
-      }
-
-      const result = fn.call(this, parameter);
-      cache.set(parameter, result);
-
-      return result;
-    },
-  }[name] as Fn;
-}
-
-export function memoizeClass<T extends Constructor>(type: T, options: MemoizeOptions = {}): (...parameters: ConstructorParameters<T>) => InstanceType<T> {
-  return memoize((...parameters: ConstructorParameters<T>): any => new type(...parameters), options);
-}
-
-export function memoizeClassSingle<T extends Constructor<any, [any]>>(type: T, options: MemoizeOptions = {}): (...parameters: ConstructorParameters<T>) => InstanceType<T> {
-  return memoizeSingle((parameter: ConstructorParameters<T>[0]): any => new type(parameter), options);
-}
-
-/**
- * Memoizes the result of a class getter, ensuring the getter's logic is
- * executed only once per instance.
- *
- * Subsequent accesses to the getter will return the cached value.
- *
- * @param strategy The memoization strategy to use.
- * - `attach`: (Default) Uses `Symbol` properties to store the cached value directly on the class instance. This is generally faster but adds hidden properties to the instance.
- * - `weak-map`: Uses a `WeakMap` to store the cached value, with the class instance as the key. This avoids adding any properties to the instance, keeping it "clean".
- *
- * @example
- * ```typescript
- * class MyEvaluator {
- *   @Memoize()
- *   get result() {
- *     // This expensive result creation only happens once per instance.
- *     return this.computeExpensiveResult();
- *   }
- * }
- *
- * const service = new MyEvaluator();
- * const s1 = service.result; // Logs "Creating new result..."
- * const s2 = service.result; // Does not log anything, returns cached result.
- * console.log(s1 === s2); // true
- * ```
- *
- * @remarks
- * If the decorated property has a corresponding setter, calling the setter will
- * invalidate the cache. The getter will be re-evaluated on its next access.
- *
- * @returns An accessor decorator function.
- */
-export function Memoize(strategy: 'attach' | 'weak-map' = 'attach') {
-  return createAccessorDecorator({
-    handler: (data) => {
-      const getter = assertDefinedPass(data.descriptor.get, 'Memoize requires an getter for accessors.'); // eslint-disable-line @typescript-eslint/unbound-method
-      const setter = data.descriptor.set; // eslint-disable-line @typescript-eslint/unbound-method
-
-      if (strategy == 'attach') {
-        return createAttachMemoizeHandler(data.propertyKey, getter, setter);
-      }
-      else {
-        return createWeakMapMemoizeHandler(getter, setter);
-      };
-    },
-  });
-}
-
-function createAttachMemoizeHandler(propertyKey: PropertyKey, getter: NonNullable<PropertyDescriptor['get']>, setter?: PropertyDescriptor['set']): PropertyDescriptor {
-  const stateKey = Symbol(`memoization[${String(propertyKey)}]`);
-
-  type Memoization = {
-    hasValue: boolean,
-    value: any,
-  };
-
-  type ThisWithCache = { [stateKey]?: Memoization };
-
-  function getState(instance: ThisWithCache): Memoization {
-    if (!hasOwnProperty(instance, stateKey)) {
-      Object.defineProperty(instance, stateKey, {
-        value: { hasValue: false, value: undefined },
-        writable: false,
-        configurable: true,
-        enumerable: false,
-      });
-    }
-
-    return instance[stateKey]!;
-  }
-
-  function cachedGetter(this: ThisWithCache): any {
-    const state = getState(this);
-
-    if (state.hasValue) {
-      return state.value;
-    }
-
-    const value = getter.call(this);
-    state.hasValue = true;
-    state.value = value;
-
-    return value;
-  }
-
-  function cachedSetter(this: ThisWithCache, value: any) {
-    setter!.call(this, value);
-
-    if (hasOwnProperty(this, stateKey)) {
-      this[stateKey]!.hasValue = false;
-      this[stateKey]!.value = undefined;
-    }
-  }
-
-  return {
-    get: cachedGetter,
-    set: isDefined(setter) ? cachedSetter : undefined,
-  };
-}
-
-function createWeakMapMemoizeHandler(getter: NonNullable<PropertyDescriptor['get']>, setter?: PropertyDescriptor['set']): PropertyDescriptor {
-  const cache = new WeakMap<object>();
-
-  function cachedGetter(this: object): any {
-    if (cache.has(this)) {
-      return cache.get(this);
-    }
-
-    const value = getter.call(this);
-    cache.set(this, value);
-
-    return value;
-  };
-
-  function cachedSetter(this: object, value: any) {
-    setter!.call(this, value);
-    cache.delete(this);
-  };
-
-  return { get: cachedGetter, set: isDefined(setter) ? cachedSetter : undefined };
-}
-
-function getMemoizedName(fn: (...args: any[]) => any): string {
-  return `memoized${fn.name[0]?.toUpperCase() ?? ''}${fn.name.slice(1)}`;
-}

package/source/utils/function/throttle.ts

@@ -1,33 +0,0 @@
-import { currentTimestamp } from '../date-time.js';
-
-export const didNotRun = Symbol('did-not-run');
-
-export function throttleFunction<Args extends any[], ReturnValue>(func: (...args: Args) => ReturnValue, interval: number, queue: boolean = false): (...args: Args) => (ReturnValue | typeof didNotRun) {
-  let lastCall = 0;
-  let pending = false;
-  let nextArgs: Args;
-
-  const throttled = (...args: Args) => {
-    const nextAllowedCall = lastCall + interval;
-    const now = currentTimestamp(); // eslint-disable-line no-shadow
-
-    if (now >= nextAllowedCall) {
-      pending = false;
-      lastCall = now;
-      return func(...args);
-    }
-    else if (queue) {
-      nextArgs = args;
-
-      if (!pending) {
-        const delay = nextAllowedCall - now;
-        setTimeout(() => throttled(...nextArgs), delay);
-        pending = true;
-      }
-    }
-
-    return didNotRun;
-  };
-
-  return throttled;
-}

package/source/utils/helpers.ts

@@ -1,91 +0,0 @@
-import { DetailsError } from '#/errors/details.error.js';
-import { supportsNotification } from '#/supports.js';
-import type { DeepArray, Record } from '#/types/index.js';
-import { decycle } from './object/decycle.js';
-import { isArray } from './type-guards.js';
-
-/**
- * Create an structured clone of an value using Notification if available, otherwise history state (may alters history)
- *
- * may not work in every environment!
- * @param value value to clone
- * @returns clone of value
- */
-export function structuredClone<T>(value: T): T {
-  if (supportsNotification) {
-    return new Notification('', { data: value, silent: true }).data as T;
-  }
-
-  const oldState = history.state;
-  history.replaceState(value, document.title);
-  const copy = history.state as T;
-  history.replaceState(oldState, document.title);
-
-  return copy;
-}
-
-/**
- * Create an structured clone of an value using a MessageChannel
- *
- * should work in all environments
- * @param value value to clone
- * @returns clone of value
- */
-export async function structuredCloneAsync<T>(value: T, options?: { transfer?: any[] }): Promise<T> {
-  const { port1, port2 } = new MessageChannel();
-
-  const promise = new Promise<T>((resolve) => (port2.onmessage = (event) => resolve(event.data as T)));
-  port1.postMessage(value, options);
-
-  return await promise;
-}
-
-export function valueOfType<T>(value: T): T {
-  return value;
-}
-
-export function flatten<T>(array: DeepArray<T>): T[] {
-  return array.reduce<T[]>((acc, item) => (isArray(item) ? [...(acc), ...flatten(item)] : [...(acc), item]), []);
-}
-
-export function toError(obj: any): Error {
-  if (obj instanceof Error) {
-    return obj;
-  }
-
-  let message: string;
-
-  try {
-    message = JSON.stringify(decycle(obj));
-  }
-  catch {
-    message = 'serialization of error reason failed. Take a look at the details property of this error instance.';
-  }
-
-  const error = new DetailsError(message, obj);
-  return error;
-}
-
-export function select<T extends Record, K extends keyof T>(key: K): (item: T) => T[K] {
-  return (item: T): any => item[key];
-}
-
-export function parseFirstAndFamilyName(name: string): { firstName: string | undefined, familyName: string | undefined } {
-  if (name.includes(',')) {
-    const [familyName, firstName] = name.split(',').map((part) => part.trim());
-    return { firstName, familyName };
-  }
-
-  const parts = name.split(' ');
-  const familyName = (parts.length > 1) ? (parts.pop()!).trim() : '';
-  const firstName = parts.map((part) => part.trim()).join(' ');
-
-  return {
-    firstName: firstName.length > 0 ? firstName : undefined,
-    familyName: familyName.length > 0 ? familyName : undefined,
-  };
-}
-
-export function iif<T, F>(condition: boolean, trueFn: () => T, falseFn: () => F): T | F {
-  return condition ? trueFn() : falseFn();
-}

package/source/utils/html-link-utils.ts

@@ -1,20 +0,0 @@
-import { NotFoundError } from '#/errors/not-found.error.js';
-import { isNull } from './type-guards.js';
-
-/**
- * Dynamically set a webmanifest
- * Note: The link-element has to be statically added (href can be empty), otherwise it wont work.
- */
-export function setWebManifest(linkSelector: string, manifest: object): void {
-  const link = document.querySelector(linkSelector);
-
-  if (isNull(link)) {
-    throw new NotFoundError(`Link element "${linkSelector}" not found.`);
-  }
-
-  const manifestString = JSON.stringify(manifest);
-  const blob = new Blob([manifestString], { type: 'application/json' });
-  const manifestURL = URL.createObjectURL(blob);
-
-  link.setAttribute('href', manifestURL);
-}