@tstdl/base 0.93.138 → 0.93.140

package/types/README.md

@@ -0,0 +1,311 @@
+# @tstdl/base/types
+
+A comprehensive collection of fundamental, advanced, and specialized TypeScript utility types designed to enhance type safety, improve developer experience, and provide standard definitions for common data structures.
+
+## Table of Contents
+
+- [Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [General Utility Types](#general-utility-types)
+  - [Tagged Types](#tagged-types)
+  - [Enumerations](#enumerations)
+  - [GeoJSON Types](#geojson-types)
+  - [Web Types](#web-types)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Common Utilities](#common-utilities)
+  - [Tagged Types](#tagged-types-usage)
+  - [Enumerations](#enumerations-usage)
+  - [GeoJSON](#geojson)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Deep Selection](#deep-selection)
+  - [Type Paths](#type-paths)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Extensive Utility Belt**: Over 50 utility types for advanced manipulation (`Simplify`, `DeepPartial`, `Writable`, `PickDeep`, `Optionalize`, etc.).
+- **Nominal Typing**: A robust `Tagged` type system to create distinct types from primitives (branding), preventing accidental misuse of semantically different values.
+- **GeoJSON Support**: Complete, RFC 7946 compliant type definitions for geospatial data structures.
+- **Web Standards**: Ready-to-use types for HTML input attributes, modes, and autocomplete values.
+- **JSON & Primitives**: Strict definitions for JSON structures and primitive type mapping.
+
+## Core Concepts
+
+### General Utility Types
+
+TypeScript's built-in utility types (`Partial`, `Pick`, etc.) are excellent, but complex applications often require more granular control. This module provides utilities to:
+
+- **Simplify** complex intersection types into readable object literals (great for IDE tooltips).
+- **Deeply** modify types (make everything writable, optional, or readonly recursively).
+- **Select** or **Omit** nested properties using a structural mask.
+- **Transform** optional properties (`| undefined`) into truly optional keys (`?`).
+
+### Tagged Types
+
+Primitives like `string` are often used for IDs (`UserId`, `OrderId`). However, TypeScript treats all strings as compatible, allowing you to accidentally pass a `UserId` to a function expecting an `OrderId`.
+**Tagged Types** (also known as Branded Types) solve this by attaching a "tag" to the type signature. This makes them structurally unique to the compiler without requiring runtime overhead.
+
+### Enumerations
+
+While TypeScript has native enums, they often suffer from type-safety issues and limited runtime introspection. The library provides a set of types to work with both array-based and object-based enumerations defined via the `#/enumeration` module.
+
+### GeoJSON Types
+
+When working with maps and geospatial data, adhering to the GeoJSON standard is crucial. These types ensure your data structures (`Feature`, `Point`, `Polygon`) match the official specification.
+
+### Web Types
+
+Provides strict typing for HTML `<input>` and `<textarea>` attributes, including comprehensive unions for `autocomplete`, `inputmode`, and `type`.
+
+## 🚀 Basic Usage
+
+### Common Utilities
+
+Use these utilities to clean up and transform your interfaces.
+
+```ts
+import type { Simplify, Writable, Optionalize, OneOrMany } from '@tstdl/base/types';
+
+// 1. Simplify: Flattens intersections for better readability
+type Complex = { a: string } & { b: number };
+type Simple = Simplify<Complex>; // { a: string; b: number; }
+
+// 2. Writable: Removes 'readonly' modifiers
+const config = { endpoint: 'https://api.com', retries: 3 } as const;
+type MutableConfig = Writable<typeof config>;
+// { endpoint: "https://api.com"; retries: 3; } (mutable)
+
+// 3. Optionalize: Converts properties with `undefined` to optional keys `?`
+type RawData = {
+  id: string;
+  description: string | undefined; // Required key, but value can be undefined
+};
+type CleanData = Optionalize<RawData>;
+// { id: string; description?: string; }
+
+// 4. OneOrMany: Handles single items or arrays
+function processItems(items: OneOrMany<string>) {
+  const list = Array.isArray(items) ? items : [items];
+  // ...
+}
+```
+
+### Tagged Types Usage
+
+Create distinct types for different IDs to prevent bugs.
+
+```ts
+import type { Tagged } from '@tstdl/base/types';
+
+// Define distinct types
+type UserId = Tagged<string, 'UserId'>;
+type OrderId = Tagged<string, 'OrderId'>;
+
+function cancelOrder(orderId: OrderId, user: UserId) {
+  console.log(`User ${user} cancelled order ${orderId}`);
+}
+
+// Casting is required to "brand" the primitive
+const myUser = 'user-123' as UserId;
+const myOrder = 'order-abc' as OrderId;
+
+cancelOrder(myOrder, myUser); // ✅ OK
+
+// cancelOrder(myUser, myOrder);
+// ❌ Error: Argument of type 'UserId' is not assignable to parameter of type 'OrderId'.
+```
+
+### Enumerations Usage
+
+Extract types from your enumeration definitions.
+
+```ts
+import type { EnumerationValue, EnumerationKey } from '@tstdl/base/types';
+
+const Colors = {
+  Red: 'red',
+  Green: 'green',
+  Blue: 'blue',
+} as const;
+
+type Color = EnumerationValue<typeof Colors>; // 'red' | 'green' | 'blue'
+type ColorKey = EnumerationKey<typeof Colors>; // 'Red' | 'Green' | 'Blue'
+```
+
+### GeoJSON
+
+Type-safe geospatial data structures.
+
+```ts
+import type { Feature, Point } from '@tstdl/base/types';
+
+type PlaceProperties = {
+  name: string;
+  rating: number;
+};
+
+const cafe: Feature<Point, PlaceProperties> = {
+  type: 'Feature',
+  geometry: {
+    type: 'Point',
+    coordinates: [13.405, 52.52], // [lon, lat]
+  },
+  properties: {
+    name: 'Coffee Shop',
+    rating: 4.5,
+  },
+};
+```
+
+## 🔧 Advanced Topics
+
+### Deep Selection
+
+Use `PickDeep` to select a subset of a deeply nested type structure. This is incredibly useful for defining API responses or GraphQL-like selection sets.
+
+```ts
+import type { PickDeep } from '@tstdl/base/types';
+
+type UserProfile = {
+  id: string;
+  personal: {
+    name: { first: string; last: string };
+    age: number;
+  };
+  settings: {
+    theme: 'dark' | 'light';
+    notifications: boolean;
+  };
+};
+
+// Select only the first name and theme
+type UserPreview = PickDeep<
+  UserProfile,
+  {
+    personal: {
+      name: { first: true };
+    };
+    settings: {
+      theme: true;
+    };
+  }
+>;
+
+// Resulting Type:
+// {
+//   personal: {
+//     name: { first: string };
+//   };
+//   settings: {
+//     theme: 'dark' | 'light';
+//   };
+// }
+```
+
+### Type Paths
+
+Extract valid dot-notation paths from an object, useful for form libraries or property accessors.
+
+```ts
+import type { Path, TypeFromPath } from '@tstdl/base/types';
+
+type Config = {
+  database: {
+    host: string;
+    port: number;
+  };
+  logging: {
+    level: string;
+  };
+};
+
+// Union of all valid paths
+type ConfigPaths = Path<Config>;
+// "database" | "database.host" | "database.port" | "logging" | "logging.level"
+
+// Extract the type at a specific path
+type PortType = TypeFromPath<Config, 'database.port'>; // number
+```
+
+## 📚 API
+
+### General Utility Types
+
+| Type                    | Description                                                                   |
+| :---------------------- | :---------------------------------------------------------------------------- |
+| `Simplify<T>`           | Flattens intersection types into a single object type for better readability. |
+| `SimplifyDeep<T>`       | Recursively simplifies types.                                                 |
+| `Writable<T>`           | Removes `readonly` modifiers from properties.                                 |
+| `DeepWritable<T>`       | Recursively removes `readonly` modifiers.                                     |
+| `DeepReadonly<T>`       | Recursively adds `readonly` modifiers.                                        |
+| `DeepPartial<T>`        | Recursively makes all properties optional.                                    |
+| `DeepNonNullable<T>`    | Recursively removes `null` and `undefined`.                                   |
+| `Optionalize<T>`        | Converts properties that allow `undefined` into optional keys (`?`).          |
+| `OptionalizeDeep<T>`    | Recursively optionalizes properties that allow `undefined`.                   |
+| `OptionalizeNullable<T>`| Converts properties that allow `null` or `undefined` into optional keys (`?`).|
+| `Unoptionalize<T>`      | Converts optional keys (`?`) into required keys that allow `undefined`.       |
+| `PickBy<T, V>`          | Picks properties from `T` whose values are assignable to `V`.                 |
+| `OmitBy<T, V>`          | Omits properties from `T` whose values are assignable to `V`.                 |
+| `PickDeep<T, S>`        | Deeply picks properties based on a selection shape `S`.                       |
+| `OmitDeep<T, S>`        | Deeply omits properties based on a selection shape `S`.                       |
+| `Merge<T1, T2>`         | Merges two types, with `T2` properties overwriting `T1`.                      |
+| `OneOrMany<T>`          | `T | readonly T[]`.                                                          |
+| `Path<T>`               | Union of dot-notation paths for object `T`.                                   |
+| `TypeFromPath<T, P>`    | The type of the property at path `P` within `T`.                              |
+| `Json`                  | Represents any valid JSON value.                                              |
+| `Record<K, V>`          | Shorthand for `Record<K, V>` with default `K=PropertyKey`.                    |
+| `Type<T>`               | Represents a class constructor.                                               |
+| `AbstractType<T>`       | Represents an abstract class constructor.                                     |
+| `ReactiveValue<T>`      | `T | Signal<T> | Observable<T>`.                                            |
+| `PascalCase<V>`         | Converts a string literal to PascalCase.                                      |
+| `Flatten<T>`            | Unwraps a single level of array nesting.                                      |
+| `DeepFlatten<T>`        | Recursively unwraps array nesting.                                            |
+| `ArrayItem<T>`          | Extracts the item type from an array.                                         |
+| `Entries<T>`            | Returns array of `[key, value]` tuples.                                       |
+| `FromEntries<E>`        | Reconstructs an object from entries.                                          |
+
+### Tagged Types
+
+| Type                     | Description                                                |
+| :----------------------- | :--------------------------------------------------------- |
+| `Tagged<Type, TagName>`  | Creates a nominal type by branding `Type` with `TagName`.  |
+| `Untagged<T>`            | Extracts the underlying primitive type from a tagged type. |
+| `UntaggedDeep<T>`        | Recursively extracts underlying primitive types.           |
+| `HasTag<T, Token>`       | Checks if a type has a specific tag.                       |
+| `GetTagMetadata<T, Tag>` | Retrieves metadata associated with a tag.                  |
+
+### Enumerations
+
+| Type                  | Description                                            |
+| :-------------------- | :----------------------------------------------------- |
+| `Enumeration`         | Union of `EnumerationArray` and `EnumerationObject`. |
+| `EnumerationValue<T>` | The union of all values in an enumeration.             |
+| `EnumerationKey<T>`   | The union of all keys (keys for objects, indices for arrays). |
+| `EnumerationMap<T>`   | Maps keys to their normalized values.                  |
+| `EnumerationEntry<T>` | Union of `[key, value]` pairs.                         |
+
+### GeoJSON Types
+
+| Type                 | Description                                             |
+| :------------------- | :------------------------------------------------------ |
+| `Position`           | `[longitude, latitude, elevation?]`                     |
+| `Point`              | GeoJSON Point geometry.                                 |
+| `LineString`         | GeoJSON LineString geometry.                            |
+| `Polygon`            | GeoJSON Polygon geometry.                               |
+| `MultiPoint`         | GeoJSON MultiPoint geometry.                            |
+| `MultiLineString`    | GeoJSON MultiLineString geometry.                       |
+| `MultiPolygon`       | GeoJSON MultiPolygon geometry.                          |
+| `Geometry`           | Union of all geometry types.                            |
+| `GeometryCollection` | A collection of geometries.                             |
+| `Feature<G, P>`      | A GeoJSON Feature with geometry `G` and properties `P`. |
+| `FeatureCollection`  | A collection of Features.                               |
+
+### Web Types
+
+| Type                 | Description                                |
+| :------------------- | :----------------------------------------- |
+| `InputType`          | Union of valid HTML `<input>` type values. |
+| `InputMode`          | Union of valid HTML `inputmode` values.    |
+| `InputAutocomplete`  | Union of valid HTML `autocomplete` values. |
+| `InputAttributes`    | Interface for HTML input attributes.       |
+| `TextAreaAttributes` | Interface for HTML textarea attributes.    |

package/utils/README.md

@@ -0,0 +1,322 @@
+# @tstdl/base/utils
+
+A comprehensive, modular, and tree-shakeable utility library for TypeScript, providing a rich set of tools for common programming tasks. It features extensive support for asynchronous iterables, object manipulation, cryptography, streams, and robust type safety.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Async Iterable Pipelines](#async-iterable-pipelines)
+  - [Parallel Processing](#parallel-processing)
+  - [Deep Object Merging & Decycling](#deep-object-merging--decycling)
+  - [Resilient Operations (Backoff & Retry)](#resilient-operations-backoff--retry)
+  - [Cryptography Wrappers](#cryptography-wrappers)
+  - [Stream Utilities](#stream-utilities)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Async Iterable Helpers**: A complete suite of functional operators (`map`, `filter`, `reduce`, `batch`, etc.) for `AsyncIterable`, enabling powerful streaming data pipelines.
+- **Parallel Processing**: Utilities to process async iterables concurrently (`parallelMap`, `parallelForEach`).
+- **Object Manipulation**: Advanced helpers for deep merging, circular reference handling (`decycle`/`recycle`), and type-safe property path access.
+- **Cryptography**: Simplified, promise-based wrappers around the Web Crypto API for encryption, hashing, and signing.
+- **Resilience Patterns**: Built-in `backoffLoop` and `retryAsync` for handling unstable operations with exponential backoff and jitter.
+- **Stream Utilities**: Tools to convert between Streams, Iterables, and Buffers, including `readBinaryStream` and `toBytesStream`.
+- **Type Safety**: Extensive collection of type guards (`isString`, `isDefined`) and assertion functions (`assertDefinedPass`) to narrow types at runtime.
+- **Zero Dependencies**: Lightweight and self-contained.
+
+## Core Concepts
+
+### Iterable-First Design
+
+The library prioritizes `Iterable` and `AsyncIterable` interfaces. This allows for memory-efficient, lazy evaluation of data sequences. Instead of loading large datasets into arrays, you can process them item-by-item as they flow through a pipeline.
+
+### Tree-Shakeability
+
+Every utility is exported in a way that allows modern bundlers to strip out unused code. You can import everything from the root `@tstdl/base/utils`, and only what you use will end up in your production build.
+
+### Type Guards & Assertions
+
+We provide pairs of functions for type checking:
+
+- **Guards** (`isString`): Return a boolean and narrow the type in TypeScript.
+- **Assertions** (`assertString`): Throw an `AssertionError` if the check fails, asserting the type.
+- **Pass-through Assertions** (`assertStringPass`): Assert the type and return the value, allowing for inline checks.
+
+## 🚀 Basic Usage
+
+Import the utilities you need directly from the package root.
+
+```typescript
+import { isDefined, timeout, mapAsync, toArrayAsync, randomString } from '@tstdl/base/utils';
+
+async function main() {
+  // 1. Simple Type Guard
+  const value: string | undefined = 'Hello';
+  if (isDefined(value)) {
+    console.log(value.toUpperCase()); // value is typed as string here
+  }
+
+  // 2. Async Iterable Helper
+  async function* numberGenerator() {
+    yield 1;
+    yield 2;
+    yield 3;
+  }
+
+  const doubled = await toArrayAsync(
+    mapAsync(numberGenerator(), async (num) => {
+      await timeout(100); // Wait 100ms
+      return num * 2;
+    }),
+  );
+  console.log(doubled); // [2, 4, 6]
+}
+```
+
+## 🔧 Advanced Topics
+
+### Async Iterable Pipelines
+
+Chain multiple operations to process data streams efficiently. This is similar to RxJS or LINQ but built on standard `AsyncIterable`.
+
+```typescript
+import { range, filterAsync, mapAsync, batchAsync, toArrayAsync } from '@tstdl/base/utils';
+
+// Create a pipeline
+const pipeline = batchAsync(
+  mapAsync(
+    filterAsync(
+      // Source: Sync iterable converted to async automatically
+      range(1, 100),
+      (x) => x % 2 === 0, // Keep evens
+    ),
+    async (x) => x * 10, // Multiply by 10
+  ),
+  5, // Batch into arrays of 5 items
+);
+
+// Execute the pipeline
+const batches = await toArrayAsync(pipeline);
+// Result: [[20, 40, 60, 80, 100], [120, ...], ...]
+```
+
+### Parallel Processing
+
+When processing items involves IO (like network requests), processing them sequentially is slow. Use `parallelMap` or `parallelForEach` to control concurrency.
+
+```typescript
+import { parallelMap, toArrayAsync } from '@tstdl/base/utils';
+
+const userIds = [1, 2, 3, 4, 5];
+
+const users = await toArrayAsync(
+  parallelMap(
+    userIds,
+    3, // Concurrency: Process 3 items at a time
+    true, // Keep Order: Ensure output order matches input order
+    async (id) => {
+      const response = await fetch(`/users/${id}`);
+      return response.json();
+    },
+  ),
+);
+```
+
+### Deep Object Merging & Decycling
+
+Handle complex objects with circular references or deep structures.
+
+```typescript
+import { mergeDeep, decycle, recycle } from '@tstdl/base/utils';
+
+// Deep Merge
+const defaultSettings = { theme: { color: 'blue', font: 'arial' } };
+const userSettings = { theme: { color: 'red' } };
+
+const settings = mergeDeep(defaultSettings, userSettings);
+// { theme: { color: 'red', font: 'arial' } }
+
+// Circular References
+const a: any = { name: 'A' };
+const b: any = { name: 'B', parent: a };
+a.child = b;
+
+// JSON.stringify(a) would throw. Use decycle:
+const safe = decycle(a);
+const json = JSON.stringify(safe);
+
+// Restore later
+const restored = recycle(JSON.parse(json));
+```
+
+### Resilient Operations (Backoff & Retry)
+
+Handle transient failures and hanging requests using `backoffLoop` and `retryWithBackoff`.
+
+#### backoffLoop
+
+Manual control over a retry loop.
+
+```typescript
+import { backoffLoop } from '@tstdl/base/utils';
+
+await backoffLoop(
+  async (controller) => {
+    try {
+      await fetch('https://api.example.com/unstable');
+      controller.break(); // Success, exit loop
+    } catch (error) {
+      console.warn('Request failed, retrying...');
+      controller.backoff(); // Wait (exponentially increasing delay) then retry
+    }
+  },
+  {
+    strategy: 'exponential',
+    initialDelay: 500,
+    maximumDelay: 5000,
+    jitter: 0.1,
+  },
+);
+```
+
+#### retryWithBackoff
+
+A higher-order utility that combines retries, exponential backoff, jitter, and timeouts. It also automatically respects `Retry-After` headers for HTTP errors.
+
+```typescript
+import { retryWithBackoff } from '@tstdl/base/utils';
+
+const result = await retryWithBackoff(
+  async (signal) => {
+    // signal is set if the attempt times out or is cancelled
+    return await fetch('https://api.example.com/data', { signal: signal.asAbortSignal() });
+  },
+  {
+    timeout: 5000, // Timeout for EACH attempt
+    retry: {
+      shouldRetry: (error, attempt) => attempt < 3 && isTransientError(error),
+      backoff: { strategy: 'exponential', initialDelay: 1000 },
+    },
+  },
+);
+```
+
+### Cryptography Wrappers
+
+Simplified, promise-based access to modern crypto standards.
+
+```typescript
+import { digest, generatePbkdf2Key, encrypt, decrypt, encodeBase64 } from '@tstdl/base/utils';
+
+// Hashing
+const hash = await digest('SHA-256', 'Hello World');
+console.log(await hash.toHex());
+
+// Encryption
+const key = await generatePbkdf2Key(true);
+const encrypted = encrypt('AES-GCM', key, 'Secret Message');
+console.log(await encrypted.toBase64());
+```
+
+### Stream Utilities
+
+Bridge the gap between Node.js Streams, Web Streams, and Iterables.
+
+```typescript
+import { readBinaryStream, toBytesStream } from '@tstdl/base/utils';
+
+// Read a Web ReadableStream into a single Uint8Array
+const response = await fetch('https://example.com/image.png');
+const buffer = await readBinaryStream(response.body!);
+
+// Convert a stream of arbitrary chunks to a byte stream
+const byteStream = toBytesStream(someObjectStream);
+```
+
+## 📚 API
+
+### Async Iterable Helpers
+
+| Function                            | Description                                               |
+| :---------------------------------- | :-------------------------------------------------------- |
+| `mapAsync`                          | Transform items asynchronously.                           |
+| `filterAsync`                       | Filter items asynchronously.                              |
+| `reduceAsync`                       | Reduce items to a single value.                           |
+| `batchAsync`                        | Group items into arrays of a specific size.               |
+| `bufferAsync`                       | Buffer items to handle backpressure or bursts.            |
+| `takeAsync` / `skipAsync`           | Take or skip a specific number of items.                  |
+| `takeWhileAsync` / `takeUntilAsync` | Take items based on a predicate or signal.                |
+| `distinctAsync`                     | Filter out duplicate items.                               |
+| `groupAsync`                        | Group items by a key selector.                            |
+| `toArrayAsync`                      | Consume the iterable and return an array.                 |
+| `firstAsync` / `lastAsync`          | Get the first or last item.                               |
+| `drainAsync`                        | Consume the iterable completely without returning values. |
+
+### Parallel Processing
+
+| Function          | Description                                        |
+| :---------------- | :------------------------------------------------- |
+| `parallelMap`     | Map items with specified concurrency.              |
+| `parallelFilter`  | Filter items with specified concurrency.           |
+| `parallelForEach` | Execute a function for each item with concurrency. |
+| `parallelGroup`   | Group items with concurrency.                      |
+
+### Object Utilities
+
+| Function                        | Description                                                      |
+| :------------------------------ | :--------------------------------------------------------------- |
+| `mergeDeep`                     | Deeply merge objects with array handling options.                |
+| `decycle` / `recycle`           | Handle circular references for serialization.                    |
+| `pick` / `omit`                 | Create new objects with selected/omitted keys.                   |
+| `mapObject` / `mapObjectValues` | Map keys or values of an object.                                 |
+| `filterObject`                  | Filter object properties by value or key.                        |
+| `getPropertyNameProxy`          | Type-safe way to get property paths (e.g., `user.profile.name`). |
+| `lazyProperty`                  | Define a property that initializes on first access.              |
+
+### Type Guards & Assertions
+
+| Function                      | Description                                             |
+| :---------------------------- | :------------------------------------------------------ |
+| `isDefined` / `assertDefined` | Check for `null` or `undefined`.                        |
+| `isString` / `assertString`   | Check for string type.                                  |
+| `isNumber` / `assertNumber`   | Check for number type (excluding NaN).                  |
+| `isArray` / `assertArray`     | Check for array.                                        |
+| `isObject` / `assertObject`   | Check for non-null object.                              |
+| `assert`                      | Generic assertion function.                             |
+| `assert*Pass`                 | Assert and return the value (e.g., `assertStringPass`). |
+
+### Timing & Async
+
+| Function            | Description                               |
+| :------------------ | :---------------------------------------- |
+| `timeout`           | Promise-based delay.                      |
+| `cancelableTimeout` | Delay that can be cancelled via a signal. |
+| `withTimeout`       | Race a promise against a timeout.         |
+| `backoffLoop`       | Run a loop with backoff logic.            |
+| `retryWithBackoff`  | Higher-order retry utility with backoff.  |
+| `asyncHook`         | Create an async event hook registry.      |
+| `Timer`             | High-resolution timer for benchmarking.   |
+
+### Cryptography & Encoding
+
+| Function                        | Description                             |
+| :------------------------------ | :-------------------------------------- |
+| `encrypt` / `decrypt`           | AES encryption wrappers.                |
+| `digest`                        | SHA hashing wrapper.                    |
+| `sign` / `verify`               | Digital signatures (HMAC, ECDSA, etc.). |
+| `encodeBase64` / `decodeBase64` | Base64 encoding utilities.              |
+| `encodeHex` / `decodeHex`       | Hex encoding utilities.                 |
+| `encodeUtf8` / `decodeText`     | String/Buffer encoding utilities.       |
+
+### Miscellaneous
+
+| Function                         | Description                               |
+| :------------------------------- | :---------------------------------------- |
+| `randomString` / `randomInt`     | Random value generation.                  |
+| `formatDuration` / `formatBytes` | Formatting utilities.                     |
+| `tryIgnore`                      | Try a function, return fallback on error. |
+| `buildUrl`                       | Construct URLs with query parameters.     |
+| `memoize`                        | Function memoization.                     |

package/utils/async-iterable-helpers/observable-iterable.d.ts

@@ -1,2 +1,2 @@
-import type { Observable } from 'rxjs';
+import { type Observable } from 'rxjs';
 export declare function observableAsyncIterable<T>(observable: Observable<T>): AsyncIterableIterator<T>;

package/utils/async-iterable-helpers/observable-iterable.js

@@ -1,30 +1,26 @@
+import { firstValueFrom, merge } from 'rxjs';
 import { CancellationToken } from '../../cancellation/token.js';
-import { merge, take } from 'rxjs';
 import { ObservableArray } from '../../collections/observable/observable-array.js';
 export async function* observableAsyncIterable(observable) {
     const buffer = new ObservableArray();
     const completeToken = new CancellationToken();
     const errorToken = new CancellationToken();
-    let error;
     const subscription = observable.subscribe({
         next: (value) => buffer.add(value),
         complete: () => completeToken.set(),
-        error: (_error) => {
-            error = _error;
-            errorToken.set();
-        }
+        error: (error) => errorToken.set(error),
     });
     try {
         while (buffer.length > 0 || !completeToken.isSet) {
             if (buffer.length == 0) {
-                await merge(buffer.add$, completeToken.set$, errorToken.set$).pipe(take(1)).toPromise();
+                await firstValueFrom(merge(buffer.add$, completeToken, errorToken));
             }
             while (buffer.length > 0) {
                 const item = buffer.removeFirst();
                 yield item;
             }
             if (errorToken.isSet) {
-                throw error;
+                throw errorToken.reason;
             }
         }
     }