npm - @tstdl/base - Versions diffs - 0.93.138 → 0.93.140 - Mend

@tstdl/base 0.93.138 → 0.93.140

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (138) hide show

package/README.md +166 -0
package/ai/genkit/multi-region.plugin.js +5 -3
package/ai/genkit/tests/multi-region.test.d.ts +1 -0
package/ai/genkit/tests/multi-region.test.js +5 -2
package/ai/parser/parser.js +2 -2
package/ai/prompts/build.js +1 -0
package/ai/prompts/instructions-formatter.d.ts +15 -2
package/ai/prompts/instructions-formatter.js +36 -31
package/ai/prompts/prompt-builder.js +5 -5
package/ai/prompts/steering.d.ts +3 -2
package/ai/prompts/steering.js +3 -1
package/ai/tests/instructions-formatter.test.js +1 -0
package/api/README.md +403 -0
package/api/client/client.js +7 -13
package/api/client/tests/api-client.test.js +10 -10
package/api/default-error-handlers.js +1 -1
package/api/response.d.ts +2 -2
package/api/response.js +22 -33
package/api/server/api-controller.d.ts +1 -1
package/api/server/api-controller.js +3 -3
package/api/server/api-request-token.provider.d.ts +1 -0
package/api/server/api-request-token.provider.js +1 -0
package/api/server/middlewares/allowed-methods.middleware.js +2 -1
package/api/server/middlewares/content-type.middleware.js +2 -1
package/api/types.d.ts +3 -2
package/application/README.md +240 -0
package/application/application.js +2 -2
package/audit/README.md +267 -0
package/authentication/README.md +288 -0
package/authentication/client/authentication.service.d.ts +12 -11
package/authentication/client/authentication.service.js +21 -21
package/authentication/client/http-client.middleware.js +2 -2
package/authentication/tests/authentication.client-error-handling.test.js +2 -1
package/authentication/tests/authentication.client-service-refresh.test.js +5 -3
package/browser/README.md +401 -0
package/cancellation/README.md +156 -0
package/cancellation/tests/coverage.test.d.ts +1 -0
package/cancellation/tests/coverage.test.js +49 -0
package/cancellation/tests/leak.test.d.ts +1 -0
package/cancellation/tests/leak.test.js +35 -0
package/cancellation/tests/token.test.d.ts +1 -0
package/cancellation/tests/token.test.js +136 -0
package/cancellation/token.d.ts +53 -177
package/cancellation/token.js +132 -201
package/context/README.md +174 -0
package/cookie/README.md +161 -0
package/css/README.md +157 -0
package/data-structures/README.md +320 -0
package/decorators/README.md +140 -0
package/distributed-loop/README.md +231 -0
package/distributed-loop/distributed-loop.js +1 -1
package/document-management/README.md +403 -0
package/document-management/server/services/document-management.service.js +9 -7
package/document-management/tests/document-management-core.test.js +2 -7
package/document-management/tests/document-management.api.test.js +6 -7
package/document-management/tests/document-statistics.service.test.js +11 -12
package/document-management/tests/document.service.test.js +3 -3
package/document-management/tests/enum-helpers.test.js +2 -3
package/dom/README.md +213 -0
package/enumerable/README.md +259 -0
package/enumeration/README.md +121 -0
package/errors/README.md +267 -0
package/file/README.md +191 -0
package/formats/README.md +210 -0
package/function/README.md +144 -0
package/http/README.md +318 -0
package/http/client/adapters/undici.adapter.js +1 -1
package/http/client/http-client-request.d.ts +6 -5
package/http/client/http-client-request.js +8 -9
package/http/server/node/node-http-server.js +1 -2
package/image-service/README.md +137 -0
package/injector/README.md +491 -0
package/injector/injector.d.ts +1 -0
package/injector/injector.js +17 -5
package/injector/tests/leak.test.d.ts +1 -0
package/injector/tests/leak.test.js +45 -0
package/intl/README.md +113 -0
package/json-path/README.md +182 -0
package/jsx/README.md +154 -0
package/key-value-store/README.md +191 -0
package/lock/README.md +249 -0
package/lock/web/web-lock.js +119 -47
package/logger/README.md +287 -0
package/mail/README.md +256 -0
package/memory/README.md +144 -0
package/message-bus/README.md +244 -0
package/message-bus/message-bus-base.js +1 -1
package/module/README.md +182 -0
package/module/module.d.ts +1 -1
package/module/module.js +77 -17
package/module/modules/web-server.module.js +1 -1
package/notification/tests/notification-type.service.test.js +24 -15
package/object-storage/README.md +300 -0
package/openid-connect/README.md +274 -0
package/orm/README.md +423 -0
package/package.json +8 -6
package/password/README.md +164 -0
package/pdf/README.md +246 -0
package/polyfills.js +1 -0
package/pool/README.md +198 -0
package/process/README.md +237 -0
package/promise/README.md +252 -0
package/promise/cancelable-promise.js +1 -1
package/random/README.md +193 -0
package/reflection/README.md +305 -0
package/rpc/README.md +386 -0
package/rxjs-utils/README.md +262 -0
package/schema/README.md +342 -0
package/serializer/README.md +342 -0
package/signals/implementation/README.md +134 -0
package/sse/README.md +278 -0
package/task-queue/README.md +300 -0
package/task-queue/postgres/task-queue.d.ts +2 -1
package/task-queue/postgres/task-queue.js +32 -2
package/task-queue/task-context.js +1 -1
package/task-queue/task-queue.d.ts +17 -0
package/task-queue/task-queue.js +103 -44
package/task-queue/tests/complex.test.js +4 -4
package/task-queue/tests/dependencies.test.js +4 -2
package/task-queue/tests/queue.test.js +111 -0
package/task-queue/tests/worker.test.js +21 -13
package/templates/README.md +287 -0
package/testing/README.md +157 -0
package/text/README.md +346 -0
package/threading/README.md +238 -0
package/types/README.md +311 -0
package/utils/README.md +322 -0
package/utils/async-iterable-helpers/observable-iterable.d.ts +1 -1
package/utils/async-iterable-helpers/observable-iterable.js +4 -8
package/utils/async-iterable-helpers/take-until.js +4 -4
package/utils/backoff.js +89 -30
package/utils/retry-with-backoff.js +1 -1
package/utils/timer.d.ts +1 -1
package/utils/timer.js +5 -7
package/utils/timing.d.ts +1 -1
package/utils/timing.js +2 -4
package/utils/z-base32.d.ts +1 -0
package/utils/z-base32.js +1 -0

package/pdf/README.md ADDED Viewed

@@ -0,0 +1,246 @@
+# @tstdl/base/pdf
+A comprehensive module for generating high-fidelity PDFs from HTML, URLs, and templates using a headless browser, along with utilities for merging, inspecting, and converting PDF files.
+## Table of Contents
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Prerequisites](#prerequisites)
+  - [Rendering HTML to PDF](#rendering-html-to-pdf)
+  - [Rendering a URL to PDF](#rendering-a-url-to-pdf)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Template-Based Generation](#template-based-generation)
+  - [Streaming Support](#streaming-support)
+  - [Merging PDFs](#merging-pdfs)
+  - [PDF Utilities (Page Count & Image Conversion)](#pdf-utilities-page-count--image-conversion)
+  - [Configuration & Options](#configuration--options)
+- [📚 API](#-api)
+## ✨ Features
+- **Headless Browser Rendering**: Utilizes a managed browser instance to render modern HTML, CSS, and JavaScript into PDFs with pixel-perfect accuracy.
+- **Multiple Sources**: Generate PDFs from raw HTML strings, live URLs, or structured templates.
+- **Template Integration**: Seamlessly integrates with `@tstdl/base/templates` for dynamic, data-driven document generation.
+- **Stream-First Architecture**: All rendering methods offer streaming counterparts for efficient memory usage with large documents.
+- **Manipulation Utilities**: Includes tools to merge PDFs, count pages, and rasterize PDF pages into images (PNG, JPEG, etc.).
+- **Customizable**: Extensive options for page formats, margins, locales, and network idle behaviors.
+## Core Concepts
+### PdfService
+The `PdfService` is the main entry point for generation. It orchestrates a `BrowserController` to manage headless browser contexts and pages. When you request a PDF render, the service handles the lifecycle of opening a page, setting content, waiting for the network to settle, printing to PDF, and cleaning up resources.
+### External Tools
+While the core rendering logic uses a browser, the manipulation utilities (`mergePdfs`, `getPdfPageCount`, `pdfToImage`) rely on efficient external command-line tools (`qpdf`, `poppler-utils`) to perform operations without the overhead of a browser engine.
+## 🚀 Basic Usage
+### Prerequisites
+To use the **utility functions** (`mergePdfs`, `getPdfPageCount`, `pdfToImage`), you must have the following tools installed on your system. The core `PdfService` rendering does **not** require these, but it does require a valid browser environment (managed by `@tstdl/base/browser`).
+- **`qpdf`**: Required for `getPdfPageCount`.
+- **`poppler-utils`**: Required for `mergePdfs` (uses `pdfunite`) and `pdfToImage` (uses `pdftocairo`).
+**Debian/Ubuntu:**
+```bash
+sudo apt-get update && sudo apt-get install -y qpdf poppler-utils
+```
+### Rendering HTML to PDF
+Inject the `PdfService` and use `renderHtml` to convert an HTML string directly into a PDF `Uint8Array`.
+```typescript
+import { PdfService } from '@tstdl/base/pdf';
+import { inject } from '@tstdl/base/injector';
+import { writeFile } from 'node:fs/promises';
+const pdfService = inject(PdfService);
+const html = `
+  <html>
+    <body>
+      <h1>Hello World</h1>
+      <p>This is a PDF generated from HTML.</p>
+    </body>
+  </html>
+`;
+const pdfBytes = await pdfService.renderHtml(html, {
+  format: 'A4',
+  margin: { top: '2cm', right: '2cm', bottom: '2cm', left: '2cm' },
+});
+await writeFile('output.pdf', pdfBytes);
+```
+### Rendering a URL to PDF
+Capture a live webpage as a PDF.
+```typescript
+import { PdfService } from '@tstdl/base/pdf';
+import { inject } from '@tstdl/base/injector';
+import { writeFile } from 'node:fs/promises';
+const pdfService = inject(PdfService);
+// Renders the target URL
+const pdfBytes = await pdfService.renderUrl('https://example.com', {
+  format: 'Letter',
+  renderBackground: true,
+});
+await writeFile('website.pdf', pdfBytes);
+```
+## 🔧 Advanced Topics
+### Template-Based Generation
+For complex reports, use `pdfTemplate` to define the structure and `@tstdl/base/templates` to handle data injection.
+```typescript
+import { PdfService, pdfTemplate } from '@tstdl/base/pdf';
+import { stringTemplateField } from '@tstdl/base/templates';
+import { inject } from '@tstdl/base/injector';
+import { writeFile } from 'node:fs/promises';
+const pdfService = inject(PdfService);
+// Define the template structure
+const invoiceTemplate = pdfTemplate(
+  'invoice',
+  {
+    header: stringTemplateField({
+      template: '<div style="font-size: 10px; text-align: center;">Invoice #{{ invoiceId }}</div>',
+    }),
+    body: stringTemplateField({
+      template: '<h1>Total Due: {{ amount }} {{ currency }}</h1><p>Customer: {{ customer }}</p>',
+    }),
+    footer: stringTemplateField({
+      template: '<div style="font-size: 10px;">Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>',
+    }),
+  },
+  {
+    displayHeaderFooter: true,
+    margin: { top: '2cm', bottom: '2cm' },
+  },
+);
+// Render with context data
+const context = {
+  invoiceId: 'INV-2024-001',
+  amount: 150.0,
+  currency: 'USD',
+  customer: 'Acme Corp',
+};
+const pdfBytes = await pdfService.renderTemplate(invoiceTemplate, context);
+await writeFile('invoice.pdf', pdfBytes);
+```
+### Streaming Support
+For large documents or high-throughput scenarios, use the `*Stream` methods to handle data as it is generated, reducing memory footprint.
+```typescript
+import { PdfService } from '@tstdl/base/pdf';
+import { inject } from '@tstdl/base/injector';
+import { createWriteStream } from 'node:fs';
+import { Writable } from 'node:stream';
+const pdfService = inject(PdfService);
+// Get a ReadableStream<Uint8Array>
+const pdfStream = pdfService.renderHtmlStream('<h1>Large Document</h1>...');
+// Pipe to a file (Node.js stream adapter required for direct piping in some envs,
+// or simply iterate the web stream)
+const fileStream = createWriteStream('streamed-output.pdf');
+const writer = Writable.toWeb(fileStream);
+await pdfStream.pipeTo(writer);
+```
+### Merging PDFs
+Combine multiple PDF sources (file paths, buffers, or streams) into a single document.
+```typescript
+import { mergePdfs } from '@tstdl/base/pdf';
+import { readFile, writeFile } from 'node:fs/promises';
+const coverPage = await readFile('cover.pdf');
+const contentPath = '/tmp/content.pdf';
+// Merge a buffer and a file path
+const mergedBytes = await mergePdfs([coverPage, contentPath]);
+await writeFile('full-report.pdf', mergedBytes);
+```
+### PDF Utilities (Page Count & Image Conversion)
+Inspect and convert existing PDFs.
+```typescript
+import { getPdfPageCount, pdfToImage } from '@tstdl/base/pdf';
+import { writeFile } from 'node:fs/promises';
+// 1. Get Page Count
+const pages = await getPdfPageCount('report.pdf');
+console.log(`Document has ${pages} pages.`);
+// 2. Convert Page 1 to a JPEG image
+const imageBytes = await pdfToImage('report.pdf', 1, 1024, 'jpeg');
+await writeFile('page-1-preview.jpg', imageBytes);
+```
+### Configuration & Options
+The `PdfServiceRenderOptions` interface allows fine-grained control over the output. You can also configure the `PdfService` globally by providing `PdfServiceArgument` during injection (e.g., setting a default `locale` or custom `browserArguments`).
+```typescript
+const options = {
+  format: 'A4',
+  landscape: true,
+  scale: 0.8,
+  margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' },
+  renderBackground: true,
+  waitForNetworkIdle: true, // Wait for network requests to finish
+  delay: 100, // Additional delay in ms before printing
+  locale: 'de-DE', // Set browser locale for date/currency formatting
+  log: true, // Enable logging for the browser page (Trace level by default)
+  browserContext: existingContext, // Optional: reuse an existing browser context
+};
+await pdfService.renderHtml(html, options);
+```
+## 📚 API
+| Export                            | Type       | Description                                                             |
+| :-------------------------------- | :--------- | :---------------------------------------------------------------------- |
+| **`PdfService`**                  | `class`    | Singleton service for generating PDFs via headless browser.             |
+| `PdfService.renderHtml`           | `method`   | Renders HTML string to `Promise<Uint8Array>`.                           |
+| `PdfService.renderHtmlStream`     | `method`   | Renders HTML string to `ReadableStream<Uint8Array>`.                    |
+| `PdfService.renderUrl`            | `method`   | Renders a URL to `Promise<Uint8Array>`.                                 |
+| `PdfService.renderUrlStream`      | `method`   | Renders a URL to `ReadableStream<Uint8Array>`.                          |
+| `PdfService.renderTemplate`       | `method`   | Renders a `PdfTemplate` to `Promise<Uint8Array>`.                       |
+| `PdfService.renderTemplateStream` | `method`   | Renders a `PdfTemplate` to `ReadableStream<Uint8Array>`.                |
+| **`pdfTemplate`**                 | `function` | Factory to create a `PdfTemplate` definition.                           |
+| **`getPdfPageCount`**             | `function` | Returns the number of pages in a PDF. Requires `qpdf`.                  |
+| **`mergePdfs`**                   | `function` | Merges multiple PDFs into one `Uint8Array`. Requires `pdfunite`.        |
+| **`mergePdfsStream`**             | `function` | Merges multiple PDFs into a `ReadableStream`. Requires `pdfunite`.      |
+| **`pdfToImage`**                  | `function` | Converts a specific PDF page to an image buffer. Requires `pdftocairo`. |
+| `PdfServiceRenderOptions`         | `class`    | Configuration object for rendering (extends browser PDF options).       |
+| `PdfTemplate`                     | `class`    | Class representing a PDF template structure.                            |
+| `PdfServiceOptions`               | `type`     | Global configuration options for `PdfService`.                          |
+| `PdfServiceArgument`              | `type`     | Full argument type for `PdfService` injection.                          |

package/polyfills.js CHANGED Viewed

	@@ -1 +1,2 @@
1 1	import 'disposablestack/auto';
2	+ globalThis.Symbol.observable ??= Symbol('observable');

package/pool/README.md ADDED Viewed

@@ -0,0 +1,198 @@
+# Pool
+A robust, asynchronous object pooling implementation for managing reusable resources. It handles instantiation, lifecycle management, and concurrency limits to optimize performance and resource usage.
+## Table of Contents
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Manual Resource Management](#manual-resource-management)
+  - [Error Handling Strategies](#error-handling-strategies)
+  - [Pool Lifecycle](#pool-lifecycle)
+  - [Resource Verification & Ownership](#resource-verification--ownership)
+- [📚 API](#-api)
+## ✨ Features
+- **Async Lifecycle**: Supports asynchronous factory and disposer functions for complex resource initialization.
+- **Concurrency Control**: Automatically limits the number of active instances. Defaults to half of CPU cores (or 4 if unknown).
+- **Queueing**: Waits for available instances when the pool is exhausted.
+- **Scoped Usage**: Provides a `use()` method that automatically handles acquisition and release (RAII-style).
+- **Error Handling**: Configurable options to dispose of instances that encounter errors instead of returning them to the pool.
+- **Modern Standards**: Implements `AsyncDisposable` for integration with the `using` keyword.
+- **Resource Ownership**: Track which resources belong to the pool to prevent accidental double-releases or cross-pool contamination.
+## Core Concepts
+Object pooling is a design pattern used to improve performance and efficiency when the cost of initializing a class instance is high, or when the number of instances in use at any one time needs to be limited (e.g., database connections, worker threads).
+The `Pool` class manages a collection of objects:
+1.  **Factory**: Creates new instances when the pool is not full and no free instances are available.
+2.  **Disposer**: Cleans up instances when they are removed from the pool or when the pool is destroyed.
+3.  **Acquisition**: Clients `get` an instance, removing it from the available set.
+4.  **Release**: Clients `release` an instance, returning it to the available set for reuse.
+## 🚀 Basic Usage
+The most common and recommended way to use the pool is via the `use()` method. This ensures that resources are always released back to the pool, even if an error occurs.
+```ts
+import { Pool } from '@tstdl/base/pool';
+import { ConsoleLogger } from '@tstdl/base/logger'; // Assuming a logger implementation
+// 1. Define the resource you want to pool
+class Worker {
+  readonly id = Math.random().toString(36).slice(2);
+  async process(data: string): Promise<string> {
+    return `Worker ${this.id} processed ${data}`;
+  }
+}
+// 2. Create the pool
+const logger = new ConsoleLogger();
+const workerPool = new Pool<Worker>(
+  // Factory: Creates a new instance
+  () => new Worker(),
+  // Disposer: Cleans up the instance (optional logic here)
+  (worker) => console.log(`Disposing worker ${worker.id}`),
+  logger,
+  { size: 2 }, // Limit to 2 concurrent workers
+);
+async function main() {
+  // 3. Use the pool
+  // The 'use' method acquires a worker, runs the callback, and releases the worker.
+  const result = await workerPool.use(async (worker) => {
+    console.log(`Acquired worker ${worker.id}`);
+    return await worker.process('Hello World');
+  });
+  console.log(result);
+  // Clean up the pool when done
+  await workerPool.dispose();
+}
+main();
+```
+## 🔧 Advanced Topics
+### Manual Resource Management
+If you need fine-grained control over when a resource is acquired and released, you can use `get()` and `release()` directly. **Note:** You must ensure `release()` is called, usually within a `finally` block.
+```ts
+import { Pool } from '@tstdl/base/pool';
+import { ConsoleLogger } from '@tstdl/base/logger';
+const pool = new Pool<object>(
+  () => ({}),
+  () => {},
+  new ConsoleLogger(),
+);
+async function manualFlow() {
+  // Acquire
+  const instance = await pool.get();
+  try {
+    // Do work
+    console.log('Using instance manually');
+  } catch (error) {
+    // Handle error
+  } finally {
+    // Release back to pool
+    await pool.release(instance);
+  }
+}
+```
+### Error Handling Strategies
+By default, if an error occurs inside `use()`, the instance is released back to the pool for reuse. However, for some resources (like network sockets), an error might indicate the instance is corrupt. You can configure the pool to dispose of instances on error.
+**Global Configuration:**
+```ts
+const pool = new Pool<object>(
+  factory,
+  disposer,
+  logger,
+  { disposeOnError: true }, // Always dispose if use() throws
+);
+```
+**Per-Call Configuration:**
+```ts
+await pool.use(
+  async (conn) => {
+    throw new Error('Connection lost');
+  },
+  { disposeOnError: true }, // Override for this specific call
+);
+// The instance used above will be disposed, not released.
+```
+### Pool Lifecycle
+The pool implements `AsyncDisposable`. When disposed, it clears all free instances and marks itself as disposed. Any currently used instances will be disposed when they are returned.
+```ts
+await using pool = new Pool<object>(...);
+// ... use pool ...
+// End of scope: pool.dispose() is called automatically.
+// All idle resources are destroyed.
+```
+### Resource Verification & Ownership
+The pool provides methods to track and manage instances explicitly. This is useful for debugging or when integrating with external systems that might attempt to return objects to the wrong pool.
+```ts
+const isOwned = workerPool.owns(manualWorker);
+const currentPoolSize = workerPool.length;
+if (manualWorker.isCorrupt) {
+  // Removes from pool and calls the disposer
+  await workerPool.disposeInstance(manualWorker);
+}
+```
+## 📚 API
+### Classes
+| Class     | Description                                                |
+| :-------- | :--------------------------------------------------------- |
+| `Pool<T>` | The main class for managing a pool of objects of type `T`. |
+### Types & Interfaces
+| Type                      | Description                                                                    |
+| :------------------------ | :----------------------------------------------------------------------------- |
+| `PoolOptions`             | Configuration options for the pool (size, error handling).                     |
+| `PoolUseOptions`          | Options for the `use` method (override error handling).                        |
+| `PoolInstanceFactory<T>`  | Function type for creating new instances: `() => T \| Promise<T>`.             |
+| `PoolInstanceDisposer<T>` | Function type for disposing instances: `(instance: T) => any \| Promise<any>`. |
+### Pool Properties & Methods
+| Member            | Signature                                                                              | Description                                                                 |
+| :---------------- | :------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- |
+| `length`          | `number` (getter)                                                                      | The total number of instances (free + used + being created).                |
+| `get`             | `(): Promise<T>`                                                                       | Acquires an instance from the pool. Waits if none are available.            |
+| `release`         | `(instance: T): Promise<void>`                                                         | Returns an instance to the pool.                                            |
+| `use`             | `<R>(handler: (instance: T) => R \| Promise<R>, options?: PoolUseOptions): Promise<R>` | Acquires an instance, executes the handler, and releases the instance.      |
+| `disposeInstance` | `(instance: T): Promise<void>`                                                         | Removes a specific instance from the pool and disposes of it.               |
+| `owns`            | `(instance: T): boolean`                                                               | Checks if an instance belongs to this pool (either in-use or idle).         |
+| `dispose`         | `(): Promise<void>`                                                                    | Shuts down the pool and disposes of all idle instances.                     |
+| `[asyncDispose]`  | `(): Promise<void>`                                                                    | Implementation of `AsyncDisposable` for use with the `using` keyword.       |

package/process/README.md ADDED Viewed

@@ -0,0 +1,237 @@
+# Process (`@tstdl/base/process`)
+A modern, promise- and stream-based wrapper for spawning child processes in Node.js, built on the Web Streams API. It simplifies process interaction by treating processes as transform streams and providing ergonomic async/await helpers.
+## Table of Contents
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Spawn and Stay Connected](#spawn-and-stay-connected)
+  - [Spawn and Wait](#spawn-and-wait)
+  - [Spawn, Wait and Read](#spawn-wait-and-read)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Writing to Standard Input](#writing-to-standard-input)
+  - [Piping Processes](#piping-processes)
+  - [Handling Errors and Exit Codes](#handling-errors-and-exit-codes)
+  - [Binary Output](#binary-output)
+- [📚 API](#-api)
+## ✨ Features
+- **Web Streams Interface**: Exposes the child process as a `TransformStream`, where the writable side is `stdin` and the readable side is `stdout`.
+- **Promise-based API**: Fully async/await compatible for spawning and waiting for termination.
+- **Convenience Helpers**: Built-in methods to read `stdout` and `stderr` as strings or byte arrays, and to write strings, buffers, or streams to `stdin`.
+- **One-liner Helpers**: `spawnWaitCommand` and `spawnWaitReadCommand` for common tasks without manual process management.
+- **Error Management**: Configurable handling of non-zero exit codes via the `wait()` method.
+- **Type Safety**: Fully typed with TypeScript.
+## Core Concepts
+The primary entry point is the `spawnCommand` function. Unlike the standard Node.js `spawn`, this function returns a `SpawnCommandResult` object which implements the `TransformStream` interface.
+- **Writable Side (`stdin`)**: You can write to the process's standard input via the `writable` property or the `write()` helper.
+- **Readable Side (`stdout`)**: You can read from the process's standard output via the `readable` property or `readOutput()` helpers.
+- **`stderr`**: Available as a separate `ReadableStream` or via `readError()` helpers.
+This design allows you to seamlessly pipe data through processes using standard Web Streams API methods like `pipeThrough` and `pipeTo`.
+## 🚀 Basic Usage
+### Spawn and Stay Connected
+Spawn a command and interact with it while it's running.
+```typescript
+import { spawnCommand } from '@tstdl/base/process';
+async function listFiles() {
+  // Spawn 'ls -la'
+  const command = await spawnCommand('ls', ['-la']);
+  // Helper to read the entire stdout as a UTF-8 string
+  const output = await command.readOutput();
+  console.log('Output:\n', output);
+  // Wait for the process to exit.
+  // This will throw an error if the exit code is not 0.
+  const { code } = await command.wait();
+  console.log(`Process finished with code ${code}`);
+}
+```
+### Spawn and Wait
+If you only care about the exit code and signal, use `spawnWaitCommand`.
+```typescript
+import { spawnWaitCommand } from '@tstdl/base/process';
+async function checkFile() {
+  const { code } = await spawnWaitCommand('test', ['-f', 'config.json']);
+  console.log(code === 0 ? 'File exists' : 'File missing');
+}
+```
+### Spawn, Wait and Read
+Use `spawnWaitReadCommand` to run a command and get its full output in one go.
+```typescript
+import { spawnWaitReadCommand } from '@tstdl/base/process';
+async function getUptime() {
+  const result = await spawnWaitReadCommand('string', 'uptime');
+  console.log('System uptime:', result.output.trim());
+}
+```
+## 🔧 Advanced Topics
+### Writing to Standard Input
+You can write data to the process using the `write` helper, which accepts strings, `Uint8Array`s, or `ReadableStream`s. It handles encoding and stream closing automatically.
+```typescript
+import { spawnCommand } from '@tstdl/base/process';
+async function grepText() {
+  const grep = await spawnCommand('grep', ['world']);
+  // Write text to stdin. The promise resolves when writing is complete.
+  await grep.write('hello\nworld\nfoo\nbar');
+  // Read the filtered output
+  const result = await grep.readOutput();
+  console.log('Grep Result:', result.trim()); // Output: "world"
+  await grep.wait();
+}
+```
+### Piping Processes
+Because `SpawnCommandResult` is a `TransformStream`, you can pipe the output of one command directly into the input of another.
+```typescript
+import { spawnCommand } from '@tstdl/base/process';
+async function pipeExample() {
+  const ls = await spawnCommand('ls', ['-la']);
+  const grep = await spawnCommand('grep', ['.ts']);
+  // Pipe ls stdout -> grep stdin
+  await ls.readable.pipeTo(grep.writable);
+  // Read the final output from grep
+  const output = await grep.readOutput();
+  console.log('TypeScript files:\n', output);
+  // Wait for both to finish
+  await Promise.all([ls.wait(), grep.wait()]);
+}
+```
+### Handling Errors and Exit Codes
+By default, `wait()` throws an error if the process exits with a non-zero code. The error message attempts to capture the content of `stderr`.
+```typescript
+import { spawnCommand } from '@tstdl/base/process';
+async function errorHandling() {
+  const cat = await spawnCommand('cat', ['non-existent-file.txt']);
+  try {
+    await cat.wait();
+  } catch (error) {
+    console.error('Command failed!');
+    console.error((error as Error).message);
+    // Output: "cat: non-existent-file.txt: No such file or directory"
+  }
+}
+// Disable automatic throwing
+async function manualErrorHandling() {
+  const cat = await spawnCommand('cat', ['non-existent-file.txt']);
+  const { code } = await cat.wait({ throwOnNonZeroExitCode: false });
+  if (code !== 0) {
+    const errorOutput = await cat.readError();
+    console.error(`Exited with ${code}. Error: ${errorOutput}`);
+  }
+}
+```
+### Binary Output
+For commands that produce binary data (like images or compressed files), use `readOutputBytes` or `spawnWaitReadCommand` with the `'binary'` format.
+```typescript
+import { spawnCommand, spawnWaitReadCommand } from '@tstdl/base/process';
+async function getBinary() {
+  const result = await spawnWaitReadCommand('binary', 'gzip', ['-c', 'file.txt']);
+  console.log(`Compressed size: ${result.output.length} bytes`);
+}
+```
+## 📚 API
+### Functions
+| Function               | Description                                                                              |
+| :--------------------- | :--------------------------------------------------------------------------------------- |
+| `spawnCommand`         | Spawns a command and returns an interactive `SpawnCommandResult`.                        |
+| `spawnWaitCommand`     | Spawns a command and waits for its termination. Returns `WaitResult`.                    |
+| `spawnWaitReadCommand` | Spawns a command, waits for termination, and returns `WaitReadResult` with full output. |
+### `SpawnCommandResult`
+The object returned by `spawnCommand`. It implements `TransformStream<Uint8Array, Uint8Array>` and provides additional helpers:
+| Property / Method             | Type                                                                                        | Description                                                                                   |
+| :---------------------------- | :------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- |
+| `process`                     | `ChildProcess`                                                                              | The underlying Node.js `ChildProcess` instance.                                               |
+| `stderr`                      | `ReadableStream<Uint8Array>`                                                                | Stream for the process's standard error.                                                      |
+| `write(data, options?)`       | `Promise<void>`                                                                             | Writes `string`, `Uint8Array`, or `ReadableStream` to `stdin`. Resolves when writing is done. |
+| `writeInBackground(data, opts)`| `void`                                                                                      | Fire-and-forget version of `write`. Errors are handled by closing streams.                    |
+| `readOutput()`                | `Promise<string>`                                                                           | Reads all data from `stdout` as a UTF-8 string.                                               |
+| `readOutputBytes()`           | `Promise<Uint8Array>`                                                                       | Reads all data from `stdout` as a byte array.                                                 |
+| `readError()`                 | `Promise<string>`                                                                           | Reads all data from `stderr` as a UTF-8 string.                                               |
+| `readErrorBytes()`            | `Promise<Uint8Array>`                                                                       | Reads all data from `stderr` as a byte array.                                                 |
+| `wait(options?)`              | `Promise<WaitResult>`                                                                       | Waits for the process to exit. Throws if exit code is non-zero unless configured otherwise.   |
+| `waitRead(format, options?)`  | `Promise<WaitReadResult>`                                                                   | Waits for the process to exit and returns all output/error data.                              |
+| `handleNonZeroExitCode()`     | `void`                                                                                      | Manually triggers the internal error handling logic (aborting streams) if the process failed. |
+### Types
+#### `SpawnOptions`
+| Property           | Type                     | Description                                |
+| :----------------- | :----------------------- | :----------------------------------------- |
+| `arguments`        | `string[]`               | Arguments for the command.                 |
+| `workingDirectory` | `string`                 | Current working directory for the process. |
+| `environment`      | `Record<string, string>` | Environment variables for the process.     |
+#### `WaitOptions`
+| Property                 | Type      | Default | Description                                                                                   |
+| :----------------------- | :-------- | :------ | :-------------------------------------------------------------------------------------------- |
+| `throwOnNonZeroExitCode` | `boolean` | `true`  | If true, `wait()` rejects with an error containing `stderr` output if the exit code is not 0. |
+#### `WaitResult`
+| Property | Type             | Description                                           |
+| :------- | :--------------- | :---------------------------------------------------- |
+| `code`   | `number \| null` | The exit code if the child exited on its own.         |
+| `signal` | `string \| null` | The signal by which the child process was terminated. |
+#### `WaitReadResult`
+Extends `WaitResult` with:
+| Property | Type                    | Description                                |
+| :------- | :---------------------- | :----------------------------------------- |
+| `output` | `string \| Uint8Array` | The full content of `stdout`.              |
+| `error`  | `string \| Uint8Array` | The full content of `stderr`.              |