@tstdl/base 0.93.36 → 0.93.37

package/source/utils/array/array.ts

@@ -1,114 +0,0 @@
-import { distinct as iterableDistinct } from '../iterable-helpers/distinct.js';
-import type { IteratorFunction } from '../iterable-helpers/types.js';
-import { randomInt } from '../math.js';
-import { isArray, isDefined } from '../type-guards.js';
-
-/**
- * Returns value as is, if it is an array, otherwise puts the single value into an array.
- */
-export function toArray<T>(value: T | T[]): T[];
-export function toArray<T>(value: T | readonly T[]): readonly T[];
-export function toArray<T>(value: T | T[] | readonly T[]): readonly T[] {
-  return isArray(value) ? value : [value] as T[];
-}
-
-/**
- * Return copy of value, if it is an array, otherwise puts the single value into an array.
- */
-export function toArrayCopy<T>(value: T | T[] | readonly T[]): T[] {
-  return isArray(value) ? [...value] : [value] as T[];
-}
-
-/**
- * Returns element of value at index 0, if it is an array and has exactly one element, otherweise returns value as is.
- */
-export function extractValueOfArrayIfSingleElement<T>(value: T | T[]): T | T[];
-export function extractValueOfArrayIfSingleElement<T>(value: T | readonly T[]): T | readonly T[];
-export function extractValueOfArrayIfSingleElement<T>(value: T | T[] | readonly T[]): T | readonly T[] {
-  if (isArray(value) && (value.length == 1)) {
-    return value[0]!;
-  }
-
-  return value;
-}
-
-export function distinct<T>(values: Iterable<T>, selector?: IteratorFunction<T, any>): T[] {
-  return [...(isDefined(selector) ? iterableDistinct(values, selector) : new Set(values))];
-}
-
-/**
- * creates a new array of specified length and fills it with values from the specified value provider function
- * @param length length of the new array
- * @param valueProvider provider function for the array values
- * @returns created array
- */
-export function createArray<T>(length: number, valueProvider: (index: number) => T): T[] {
-  const arr: T[] = [];
-  arr.length = length;
-
-  return arr.fill(undefined as T).map((_, index) => valueProvider(index));
-}
-
-/**
- * shuffles items using "The modern version of the Fisher–Yates shuffle"
- * @param items items to shuffle
- * @returns shuffled items
- */
-export function shuffle<T>(items: readonly T[]): T[] {
-  const cloned = [...items];
-
-  for (let i = 0; i < cloned.length; i++) {
-    const j = randomInt(i, cloned.length - 1);
-    [cloned[i], cloned[j]] = [cloned[j]!, cloned[i]!];
-  }
-
-  return cloned;
-}
-
-/**
- * picks a random item from specified array
- * @param array array to pick random item from
- * @param options options
- * @returns random item
- */
-export function randomItem<T>(array: readonly T[], { min, max }: { min?: number, max?: number } = {}): T {
-  const _min = isDefined(min) ? Math.max(min, 0) : 0;
-  const _max = isDefined(max) ? Math.min(max, array.length - 1) : array.length - 1;
-  const index = randomInt(_min, _max);
-
-  return array[index]!;
-}
-
-/**
- * picks random items from specified array
- * @param array array to pick random items from
- * @param count count of items to pick
- * @param allowDuplicates allow picking an item multiple times - required when count is larger than array length
- * @returns random items
- */
-export function randomItems<T>(array: readonly T[], count: number, allowDuplicates: boolean = false): T[] {
-  if (allowDuplicates) {
-    return createArray(count, () => array[randomInt(0, array.length - 1)]!);
-  }
-
-  if (count > array.length) {
-    throw new Error('count larger than length of array without allowing duplicates');
-  }
-
-  if (count >= (array.length / 2)) {
-    return shuffle(array).slice(0, count);
-  }
-
-  const taken = new Set<number>();
-
-  return createArray<T>(count, () => {
-    while (true) {
-      const index = randomInt(0, array.length - 1);
-
-      if (!taken.has(index)) {
-        taken.add(index);
-        return array[index]!;
-      }
-    }
-  });
-}

package/source/utils/array/index.ts

@@ -1,2 +0,0 @@
-export * from './array.js';
-export * from './array-backtracker.js';

package/source/utils/async-hook/async-hook.ts

@@ -1,153 +0,0 @@
-/**
- * Represents the public interface for an asynchronous hook.
- *
- * @template T The type of the value that the hook is triggered with.
- * @template C The type of the optional context object passed to the hook's trigger and handlers. Defaults to `never`.
- * @template R The return type of an individual handler. Defaults to `unknown`.
- */
-export type AsyncHook<T, C = never, R = unknown> = {
-  /**
-   * Registers a handler function to be called when the hook is triggered.
-   * @param handler The async handler function to register.
-   * @returns A registration object with an `unregister` method to remove the handler.
-   */
-  register: (handler: AsyncHookHandler<T, C, R>) => AsyncHookHandlerRegistration,
-
-  /**
-   * Triggers the hook, executing all registered handlers in sequence.
-   *
-   * The signature of this function is conditional:
-   * - If the context type `C` is `never` (the default), it accepts only the `value` argument.
-   * - If `C` is any other type, it requires both `value` and `context` arguments.
-   *
-   * @param value The value to pass to all handlers.
-   * @param context The context object to pass to all handlers (only required if `C` is not `never`).
-   * @returns A promise that resolves to an array of results from all handlers.
-   */
-  trigger: [C] extends [never] ? ((value: T) => Promise<R[]>) : ((value: T, context: C) => Promise<R[]>),
-};
-
-/**
- * Defines the signature for a handler function that can be registered with an `AsyncHook`.
- * The function can be synchronous (returning `R`) or asynchronous (returning `Promise<R>`).
- *
- * The signature is conditional based on the context type `C`:
- * - If `C` is `never`, the handler receives only the `value` argument.
- * - If `C` is any other type, the handler receives both `value` and `context`.
- *
- * @template T The type of the value passed to the handler.
- * @template C The type of the optional context object.
- * @template R The expected return type of the handler.
- */
-export type AsyncHookHandler<T, C, R> = [C] extends [never] ? ((value: T) => R | Promise<R>) : ((value: T, context: C) => R | Promise<R>);
-
-/**
- * Represents the object returned when a handler is registered,
- * allowing for its subsequent unregistration.
- */
-export type AsyncHookHandlerRegistration = {
-  /**
-   * Unregisters the handler, preventing it from being called in future triggers.
-   */
-  unregister: () => void,
-};
-
-/**
- * Creates a new asynchronous hook.
- *
- * An async hook is a system that allows you to register multiple "handler" functions
- * that will be executed in sequence when a "trigger" event occurs. This is useful
- * for creating extensible, plugin-like architectures. Handlers can be synchronous
- * or asynchronous.
- *
- * @template T The type of the primary value that the hook is triggered with.
- * @template C The type of the optional context object passed to the hook's trigger and handlers. Defaults to `never`.
- * @template R The return type of an individual handler. The `trigger` method will resolve with an array of these values (`R[]`). Defaults to `unknown`.
- * @returns {AsyncHook<T, C, R>} An object with `register` and `trigger` methods.
- *
- * @example
- * ```ts
- * // Simple hook without context
- * async function runSimpleExample() {
- *   const onTaskStart = asyncHook<string>();
- *
- *   onTaskStart.register(taskName => {
- *     console.log(`[Logger] Task started: ${taskName}`);
- *   });
- *
- *   const registration = onTaskStart.register(async taskName => {
- *     await new Promise(resolve => setTimeout(resolve, 50));
- *     console.log(`[Notifier] Notifying that task started: ${taskName}`);
- *   });
- *
- *   await onTaskStart.trigger('Process Data');
- *   // [Logger] Task started: Process Data
- *   // [Notifier] Notifying that task started: Process Data
- *
- *   registration.unregister();
- *   console.log('Notifier unregistered.');
- *
- *   await onTaskStart.trigger('Finalize Report');
- *   // [Logger] Task started: Finalize Report
- * }
- * ```
- *
- * @example
- * ```ts
- * // Hook with a context object
- * async function runContextExample() {
- *   type TaskContext = { userId: number; transactionId: string };
- *
- *   const onTaskComplete = asyncHook<string, TaskContext, boolean>();
- *
- *   onTaskComplete.register((taskName, context) => {
- *     console.log(`[Audit] Task '${taskName}' completed by user ${context.userId}.`);
- *     return true; // Audit successful
- *   });
- *
- *   onTaskComplete.register(async (taskName, context) => {
- *     console.log(`[DB] Logging completion of '${taskName}' for transaction ${context.transactionId}.`);
- *     return true; // DB update successful
- *   });
- *
- *   const results = await onTaskComplete.trigger(
- *     'SubmitOrder',
- *     { userId: 123, transactionId: 'abc-456' }
- *   );
- *
- *   console.log('Handler results:', results); // [true, true]
- * }
- * ```
- */
-export function asyncHook<T, C = never, R = unknown>(): AsyncHook<T, C, R> {
-  const handlers: AsyncHookHandler<T, C, R>[] = [];
-
-  return {
-    register: (handler: AsyncHookHandler<T, C, R>): AsyncHookHandlerRegistration => {
-      handlers.push(handler);
-
-      return {
-        unregister() {
-          const index = handlers.indexOf(handler);
-          if (index > -1) {
-            handlers.splice(index, 1);
-          }
-        },
-      };
-    },
-    // The implementation uses a single function body, but the public type signature
-    // is conditional, ensuring type safety for callers.
-    trigger: async (value: T, context?: C) => {
-      const returnValues: R[] = [];
-
-      // Create a snapshot of handlers in case one of them unregisters another during its execution.
-      for (const handler of [...handlers]) {
-        // The non-null assertion `context!` is safe due to the conditional public type of `trigger`.
-        const returnValue = await handler(value, context!);
-        returnValues.push(returnValue);
-      }
-
-      return returnValues;
-    },
-  };
-}

package/source/utils/async-hook/index.ts

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

package/source/utils/async-iterable-helpers/all.ts

@@ -1,45 +0,0 @@
-import type { AnyIterable } from '../any-iterable-iterator.js';
-import { isAsyncIterable } from './is-async-iterable.js';
-import type { AsyncPredicate } from './types.js';
-
-export async function allAsync<T>(iterable: AnyIterable<T>, predicate: AsyncPredicate<T> = () => true): Promise<boolean> {
-  return isAsyncIterable(iterable)
-    ? async(iterable, predicate)
-    : sync(iterable, predicate);
-}
-
-async function sync<T>(iterable: Iterable<T>, predicate: AsyncPredicate<T>): Promise<boolean> {
-  let index = 0;
-
-  for (const item of iterable) {
-    let matches = predicate(item, index++);
-
-    if (matches instanceof Promise) {
-      matches = await matches;
-    }
-
-    if (!matches) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
-async function async<T>(iterable: AsyncIterable<T>, predicate: AsyncPredicate<T>): Promise<boolean> {
-  let index = 0;
-
-  for await (const item of iterable) {
-    let matches = predicate(item, index++);
-
-    if (matches instanceof Promise) {
-      matches = await matches;
-    }
-
-    if (!matches) {
-      return false;
-    }
-  }
-
-  return true;
-}

package/source/utils/async-iterable-helpers/any.ts

@@ -1,45 +0,0 @@
-import type { AnyIterable } from '../any-iterable-iterator.js';
-import { isAsyncIterable } from './is-async-iterable.js';
-import type { AsyncPredicate } from './types.js';
-
-export async function anyAsync<T>(iterable: AnyIterable<T>, predicate: AsyncPredicate<T> = () => true): Promise<boolean> {
-  return isAsyncIterable(iterable)
-    ? async(iterable, predicate)
-    : sync(iterable, predicate);
-}
-
-async function sync<T>(iterable: Iterable<T>, predicate: AsyncPredicate<T>): Promise<boolean> {
-  let index = 0;
-
-  for (const item of iterable) {
-    let matches = predicate(item, index++);
-
-    if (matches instanceof Promise) {
-      matches = await matches;
-    }
-
-    if (matches) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-async function async<T>(iterable: AsyncIterable<T>, predicate: AsyncPredicate<T>): Promise<boolean> {
-  let index = 0;
-
-  for await (const item of iterable) {
-    let matches = predicate(item, index++);
-
-    if (matches instanceof Promise) {
-      matches = await matches;
-    }
-
-    if (matches) {
-      return true;
-    }
-  }
-
-  return false;
-}

package/source/utils/async-iterable-helpers/assert.ts

@@ -1,40 +0,0 @@
-import type { AnyIterable } from '../any-iterable-iterator.js';
-import { assert as assertHelper } from '../type-guards.js';
-import { isAsyncIterable } from './is-async-iterable.js';
-import type { AsyncPredicate } from './types.js';
-
-export function assertAsync<T, TPredicate extends T = T>(iterable: AnyIterable<T>, predicate: AsyncPredicate<T>): AsyncIterableIterator<TPredicate> {
-  return isAsyncIterable(iterable)
-    ? async(iterable, predicate)
-    : sync(iterable, predicate);
-}
-
-async function* sync<T, TPredicate extends T = T>(iterable: Iterable<T>, predicate: AsyncPredicate<T>): AsyncIterableIterator<TPredicate> {
-  let index = 0;
-
-  for (const item of iterable) {
-    let returnValue = predicate(item, index++);
-
-    if (returnValue instanceof Promise) {
-      returnValue = await returnValue;
-    }
-
-    assertHelper(returnValue);
-    yield item as TPredicate;
-  }
-}
-
-async function* async<T, TPredicate extends T = T>(iterable: AsyncIterable<T>, predicate: AsyncPredicate<T>): AsyncIterableIterator<TPredicate> {
-  let index = 0;
-
-  for await (const item of iterable) {
-    let returnValue = predicate(item, index++);
-
-    if (returnValue instanceof Promise) {
-      returnValue = await returnValue;
-    }
-
-    assertHelper(returnValue);
-    yield item as Awaited<TPredicate>;
-  }
-}

package/source/utils/async-iterable-helpers/batch.ts

@@ -1,43 +0,0 @@
-import type { AnyIterable } from '../any-iterable-iterator.js';
-import { isAsyncIterable } from './is-async-iterable.js';
-
-export function batchAsync<T>(iterable: AnyIterable<T>, size: number): AsyncIterableIterator<T[]> {
-  return isAsyncIterable(iterable)
-    ? async(iterable, size)
-    : sync(iterable, size);
-}
-
-// eslint-disable-next-line @typescript-eslint/require-await
-async function* sync<T>(iterable: Iterable<T>, size: number): AsyncIterableIterator<T[]> {
-  let buffer: T[] = [];
-
-  for (const item of iterable) {
-    buffer.push(item);
-
-    if (buffer.length >= size) {
-      yield buffer;
-      buffer = [];
-    }
-  }
-
-  if (buffer.length > 0) {
-    yield buffer;
-  }
-}
-
-async function* async<T>(iterable: AsyncIterable<T>, size: number): AsyncIterableIterator<T[]> {
-  let buffer: T[] = [];
-
-  for await (const item of iterable) {
-    buffer.push(item);
-
-    if (buffer.length >= size) {
-      yield buffer;
-      buffer = [];
-    }
-  }
-
-  if (buffer.length > 0) {
-    yield buffer;
-  }
-}

package/source/utils/async-iterable-helpers/buffer.ts

@@ -1,68 +0,0 @@
-import { CancellationToken } from '#/cancellation/token.js';
-import { CircularBuffer } from '#/data-structures/circular-buffer.js';
-import type { AnyIterable } from '../any-iterable-iterator.js';
-import { hasOwnProperty } from '../object/object.js';
-import { takeUntilAsync } from './take-until.js';
-
-type BufferItem<T> =
-  | { end: false, value: T }
-  | { end: true, error?: Error };
-
-// eslint-disable-next-line max-lines-per-function, max-statements
-export async function* bufferAsync<T>(iterable: AnyIterable<T>, size: number): AsyncIterableIterator<T> {
-  const buffer = new CircularBuffer<BufferItem<T>>(Math.max(1, size));
-
-  const consumerEndedToken = new CancellationToken();
-  let consumerHasError = false;
-  let consumerError: any;
-
-  void (async () => {
-    try {
-      for await (const item of takeUntilAsync(iterable, consumerEndedToken)) {
-        buffer.add({ end: false, value: item });
-
-        if (buffer.isFull) {
-          await buffer.$onFreeSlots;
-        }
-
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        if (consumerHasError) {
-          throw consumerError;
-        }
-
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        if (consumerEndedToken.isSet) {
-          return;
-        }
-      }
-
-      buffer.add({ end: true });
-    }
-    catch (error: unknown) {
-      buffer.add({ end: true, error: error as Error });
-    }
-  })();
-
-  try {
-    for await (const item of buffer.consumeAsync()) {
-      if (item.end) {
-        if (hasOwnProperty(item, 'error')) {
-          throw item.error!;
-        }
-
-        break;
-      }
-
-      yield item.value;
-    }
-  }
-  catch (error: unknown) {
-    consumerHasError = true;
-    consumerError = error as Error;
-    throw error;
-  }
-  finally {
-    consumerEndedToken.set();
-    buffer.clear();
-  }
-}

package/source/utils/async-iterable-helpers/concat.ts

@@ -1,8 +0,0 @@
-import type { AnyIterable } from '../any-iterable-iterator.js';
-
-// eslint-disable-next-line @typescript-eslint/require-await
-export async function* concatAsync<T>(...iterables: AnyIterable<T>[]): AsyncIterableIterator<T> {
-  for (const iterable of iterables) {
-    yield* iterable;
-  }
-}

package/source/utils/async-iterable-helpers/default-if-empty.ts

@@ -1,14 +0,0 @@
-import type { AnyIterable } from '../any-iterable-iterator.js';
-
-export async function* defaultIfEmptyAsync<T, TDefault>(iterable: AnyIterable<T>, defaultValue: TDefault): AsyncIterableIterator<T | TDefault> {
-  let empty = true;
-
-  for await (const item of iterable) {
-    empty = false;
-    yield item;
-  }
-
-  if (empty) {
-    yield defaultValue;
-  }
-}

package/source/utils/async-iterable-helpers/deferred.ts

@@ -1,6 +0,0 @@
-import type { AnyIterable } from '../any-iterable-iterator.js';
-
-export async function* deferredAsyncIterable<T>(source: () => (AnyIterable<T> | Promise<AnyIterable<T>>)): AsyncIterableIterator<T> {
-  const iterable = await source();
-  yield* iterable;
-}

package/source/utils/async-iterable-helpers/difference.ts

@@ -1,36 +0,0 @@
-import type { AnyIterable } from '../any-iterable-iterator.js';
-import { concatAsync } from './concat.js';
-import { mapAsync } from './map.js';
-import { toArrayAsync } from './to-array.js';
-import type { AsyncIteratorFunction } from './types.js';
-
-export async function* differenceAsync<T>(baseIterable: AnyIterable<T>, iterable: AnyIterable<T>, selector: AsyncIteratorFunction<T, any> = (item) => item): AsyncIterableIterator<T> {
-  const diffItems = mapAsync(iterable, selector);
-  const diffItemsArray = await toArrayAsync(diffItems);
-  const diffItemsSet = new Set(diffItemsArray);
-
-  let index = 0;
-  for await (const item of baseIterable) {
-    const selected = await selector(item, index++);
-
-    if (!diffItemsSet.has(selected)) {
-      yield item;
-    }
-  }
-}
-
-export async function* differenceManyAsync<T>(baseIterable: AnyIterable<T>, iterables: AnyIterable<T>[], selector: AsyncIteratorFunction<T, any> = (item) => item): AsyncIterableIterator<T> {
-  const items = concatAsync(...iterables);
-  const diffItems = mapAsync(items, selector);
-  const diffItemsArray = await toArrayAsync(diffItems);
-  const diffItemsSet = new Set(diffItemsArray);
-
-  let index = 0;
-  for await (const item of baseIterable) {
-    const selected = selector(item, index++);
-
-    if (!diffItemsSet.has(selected)) {
-      yield item;
-    }
-  }
-}

package/source/utils/async-iterable-helpers/distinct.ts

@@ -1,39 +0,0 @@
-import type { AnyIterable } from '../any-iterable-iterator.js';
-import { isAsyncIterable } from './is-async-iterable.js';
-import type { AsyncIteratorFunction } from './types.js';
-
-export function distinctAsync<TIn>(iterable: AnyIterable<TIn>, selector: AsyncIteratorFunction<TIn, any> = (item) => item): AsyncIterableIterator<TIn> {
-  return isAsyncIterable(iterable)
-    ? async(iterable, selector)
-    : sync(iterable, selector);
-}
-
-async function* sync<TIn>(iterable: Iterable<TIn>, selector: AsyncIteratorFunction<TIn, any>): AsyncIterableIterator<TIn> {
-  const items = new Set();
-  let index = 0;
-
-  for (const item of iterable) {
-    const returnValue = selector(item, index++);
-    const selection = (returnValue instanceof Promise) ? await returnValue : returnValue;
-
-    if (!items.has(selection)) {
-      items.add(selection);
-      yield item;
-    }
-  }
-}
-
-async function* async<TIn>(iterable: AsyncIterable<TIn>, selector: AsyncIteratorFunction<TIn, any>): AsyncIterableIterator<TIn> {
-  const items = new Set();
-  let index = 0;
-
-  for await (const item of iterable) {
-    const returnValue = selector(item, index++);
-    const selection = (returnValue instanceof Promise) ? await returnValue : returnValue;
-
-    if (!items.has(selection)) {
-      items.add(selection);
-      yield item;
-    }
-  }
-}

package/source/utils/async-iterable-helpers/drain.ts

@@ -1,7 +0,0 @@
-import type { AnyIterable } from '../any-iterable-iterator.js';
-
-export async function drainAsync(iterable: AnyIterable<any>): Promise<void> {
-  for await (const _item of iterable) {
-    // just drain
-  }
-}

package/source/utils/async-iterable-helpers/filter.ts

@@ -1,41 +0,0 @@
-import type { AnyIterable } from '../any-iterable-iterator.js';
-import { isAsyncIterable } from './is-async-iterable.js';
-import type { AsyncPredicate } from './types.js';
-
-export function filterAsync<T, TNew extends T = T>(iterable: AnyIterable<T>, predicate: AsyncPredicate<T>): AsyncIterableIterator<TNew> {
-  return isAsyncIterable(iterable)
-    ? async<T, TNew>(iterable, predicate)
-    : sync<T, TNew>(iterable, predicate);
-}
-
-async function* sync<T, TNew extends T = T>(iterable: Iterable<T>, predicate: AsyncPredicate<T>): AsyncIterableIterator<TNew> {
-  let index = 0;
-
-  for (const item of iterable) {
-    let matches = predicate(item, index++);
-
-    if (matches instanceof Promise) {
-      matches = await matches;
-    }
-
-    if (matches) {
-      yield item as TNew;
-    }
-  }
-}
-
-async function* async<T, TNew extends T = T>(iterable: AsyncIterable<T>, predicate: AsyncPredicate<T>): AsyncIterableIterator<TNew> {
-  let index = 0;
-
-  for await (const item of iterable) {
-    let matches = predicate(item, index++);
-
-    if (matches instanceof Promise) {
-      matches = await matches;
-    }
-
-    if (matches) {
-      yield item as Awaited<TNew>;
-    }
-  }
-}