@tstdl/base 0.93.138 → 0.93.140

package/function/README.md

@@ -0,0 +1,144 @@
+# Function
+
+A utility module providing tools for function manipulation and debugging. It currently focuses on transparently wrapping functions to log execution details, arguments, and return values.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Custom Logger](#custom-logger)
+  - [Enabling Stack Traces](#enabling-stack-traces)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Transparent Logging**: Wrap any function to automatically log when it is called and what it returns.
+- **Argument Formatting**: Automatically formats primitive arguments and arrays for readable log output.
+- **Custom Loggers**: Integrate with the `@tstdl/base/logger` or any compatible logger interface.
+- **Stack Traces**: Optionally print stack traces on every call for deep debugging.
+- **Metadata Control**: Override the function name used in logs for better context.
+
+## Core Concepts
+
+The `function` module provides high-order functions that take an existing function and return a new one with added behavior.
+
+### Function Wrapping
+
+The primary utility, `wrapLog`, acts as a functional decorator. It intercepts calls to the target function, logs the arguments, executes the original function, and then logs the result. This is particularly useful for debugging complex logic flows or inspecting data transformations without modifying the original source code with temporary `console.log` statements.
+
+## 🚀 Basic Usage
+
+The most common use case is wrapping a function to see its inputs and outputs in the console.
+
+```typescript
+import { wrapLog } from '@tstdl/base/function';
+
+function calculateSum(a: number, b: number): number {
+  return a + b;
+}
+
+// Wrap the function. By default, it uses console.log (via console.log.bind(console))
+const loggedCalculateSum = wrapLog(calculateSum);
+
+// Execute the wrapped function
+loggedCalculateSum(5, 10);
+
+// Console Output:
+// [call: calculateSum(5, 10)]
+// [return: calculateSum => 15]
+```
+
+## 🔧 Advanced Topics
+
+### Custom Logger
+
+You can direct the output to a specific logger instance (e.g., from `@tstdl/base/logger`) instead of `console.log`. The wrapper uses the `trace` method of the logger.
+
+```typescript
+import { wrapLog } from '@tstdl/base/function';
+import { Logger } from '@tstdl/base/logger';
+import { inject } from '@tstdl/base/injector';
+
+class MathService {
+  private logger = inject(Logger, 'MathService');
+
+  add(a: number, b: number): number {
+    return a + b;
+  }
+
+  constructor() {
+    // Replace the method with a logged version using the service's logger
+    this.add = wrapLog(this.add.bind(this), {
+      logger: this.logger,
+      fnName: 'MathService.add', // Custom name for clearer logs
+    }) as any;
+  }
+}
+```
+
+### Enabling Stack Traces
+
+For debugging call chains, you can enable the `trace` option. This will output a stack trace every time the function is called.
+
+```typescript
+import { wrapLog } from '@tstdl/base/function';
+
+function criticalOperation() {
+  // ... logic
+}
+
+const debugOperation = wrapLog(criticalOperation, {
+  trace: true,
+  logResult: false, // Only log the call and trace, ignore the return value
+});
+
+debugOperation();
+// Output:
+// [call: criticalOperation()]
+// Trace: ... (stack trace)
+```
+
+## 📚 API
+
+### Functions
+
+| Function                | Description                                                      |
+| :---------------------- | :--------------------------------------------------------------- |
+| `wrapLog(fn, options?)` | Wraps a function to log its calls, arguments, and return values. |
+
+### Types
+
+| Type             | Description                         |
+| :--------------- | :---------------------------------- |
+| `WrapLogOptions` | Configuration object for `wrapLog`. |
+
+#### WrapLogOptions
+
+```typescript
+type WrapLogOptions = {
+  /**
+   * The name to use in log messages. Defaults to fn.name.
+   */
+  fnName?: string;
+
+  /**
+   * Whether to log the return value of the function.
+   * Default: true
+   */
+  logResult?: boolean;
+
+  /**
+   * A Logger instance to use. If not provided, defaults to console.log.
+   * The wrapper calls logger.trace().
+   */
+  logger?: Logger;
+
+  /**
+   * Whether to print a stack trace (console.trace) on execution.
+   * Default: false
+   */
+  trace?: boolean;
+};
+```

package/http/README.md

@@ -0,0 +1,318 @@
+# @tstdl/base/http
+
+A powerful, isomorphic, middleware-based HTTP client and server library for TypeScript. This module provides a comprehensive suite of tools for handling HTTP communication, featuring a flexible client with a middleware pipeline and a modern, async-iterable-based server abstraction.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [HTTP Client](#http-client)
+  - [HTTP Server](#http-server)
+  - [Isomorphic Utilities](#isomorphic-utilities)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Client Setup](#client-setup)
+  - [Making Requests](#making-requests)
+  - [Server Setup](#server-setup)
+  - [Handling Requests](#handling-requests)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Client Middleware](#client-middleware)
+  - [Streaming Data](#streaming-data)
+  - [Error Handling](#error-handling)
+  - [Automatic Parameter Mapping](#automatic-parameter-mapping)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Isomorphic Design:** Shared abstractions for client and server, with specific adapters for different environments (e.g., `undici` for Node.js).
+- **Middleware-Driven Client:** Intercept and modify requests/responses using a flexible async middleware pipeline for concerns like logging, authentication, and caching.
+- **Pluggable Client Adapter:** The `HttpClientAdapter` allows swapping the underlying HTTP engine. `UndiciHttpClientAdapter` is provided for high-performance Node.js applications.
+- **Modern Server Abstraction:** The `HttpServer` uses an async iterator pattern (`for await...of`) for elegant and efficient request handling.
+- **Advanced Body Handling:** Seamlessly works with JSON, text, forms (`x-www-form-urlencoded`), `FormData`, binary (`Uint8Array`, `Blob`), and `ReadableStream`.
+- **Automatic Parameter Mapping:** Intelligently maps request parameters to URL path segments, query strings, or the request body.
+- **Typed API:** Strongly typed interfaces for requests, responses, headers, and query parameters to catch errors at compile time.
+- **Utility Classes:** Helpers like `HttpHeaders`, `HttpQuery`, and `HttpForm` simplify common tasks.
+
+## Core Concepts
+
+### HTTP Client
+
+The client is designed around three main components: `HttpClient`, `HttpClientAdapter`, and `HttpClientMiddleware`.
+
+- **`HttpClient`**: The primary interface for making requests. It manages configuration, default headers, and the middleware pipeline. It offers convenience methods like `getJson()`, `post()`, etc. The flow of a request is: `HttpClient` -> `Middleware Chain` -> `HttpClientAdapter`.
+- **`HttpClientAdapter`**: The "engine" that performs the actual HTTP call. The library is decoupled from any specific implementation. For Node.js, the `UndiciHttpClientAdapter` is provided, which uses the high-performance `undici` library.
+- **`HttpClientMiddleware`**: A function that intercepts a request before it's sent and the response after it's received. Middleware is composed into a pipeline.
+
+### HTTP Server
+
+The server implementation is based on the `HttpServer` abstract class.
+
+- **`HttpServer`**: An async iterable that yields a `HttpServerRequestContext` for each incoming connection. This design promotes a clean, modern loop for processing requests (`for await (const context of server)`).
+- **`HttpServerRequestContext`**: Encapsulates the `request` (incoming) and a `respond` function (outgoing).
+- **`NodeHttpServer`**: The default implementation of `HttpServer` for Node.js, built on top of the native `node:http` module.
+
+### Isomorphic Utilities
+
+- **`HttpHeaders`**: A map-like class for managing HTTP headers with typed getters for common headers (e.g., `contentType`, `contentLength`).
+- **`HttpBody`**: A unified interface for reading request/response bodies. It supports reading as JSON, text, buffer, or stream, regardless of the source (Node stream, Blob, etc.).
+
+## 🚀 Basic Usage
+
+### Client Setup
+
+To use the client in a Node.js environment, you need to configure the `UndiciHttpClientAdapter`.
+
+```typescript
+import { HttpClient, configureHttpClient } from '@tstdl/base/http';
+import { configureUndiciHttpClientAdapter } from '@tstdl/base/http/undici';
+import { Injector } from '@tstdl/base/injector';
+
+// 1. Configure the adapter (Node.js specific)
+configureUndiciHttpClientAdapter({ register: true });
+
+// 2. Configure the client (optional base URL)
+configureHttpClient({
+  baseUrl: 'https://api.example.com',
+});
+
+// 3. Resolve the client
+const httpClient = Injector.resolve(HttpClient);
+```
+
+### Making Requests
+
+The `HttpClient` provides methods for standard HTTP verbs (`get`, `post`, `put`, `patch`, `delete`, `head`).
+
+```typescript
+// GET JSON
+type User = { id: number; name: string };
+const user = await httpClient.getJson<User>('/users/1');
+console.log(user.name);
+
+// POST JSON
+const newUser = { name: 'Alice' };
+const createdUser = await httpClient.postJson<User>('/users', {
+  body: { json: newUser },
+});
+
+// GET with Query Parameters
+// Result: GET /search?q=typescript&limit=10
+const results = await httpClient.getJson('/search', {
+  query: { q: 'typescript', limit: 10 },
+});
+```
+
+### Server Setup
+
+Configure and run the `NodeHttpServer`.
+
+```typescript
+import { HttpServer } from '@tstdl/base/http/server';
+import { configureNodeHttpServer } from '@tstdl/base/http/node';
+import { Injector } from '@tstdl/base/injector';
+
+// 1. Register the Node.js server implementation
+configureNodeHttpServer();
+
+// 2. Resolve the server
+const httpServer = Injector.resolve(HttpServer);
+
+// 3. Start listening
+await httpServer.listen(3000);
+console.log('Server listening on port 3000');
+```
+
+### Handling Requests
+
+Use the async iterator pattern to handle incoming requests sequentially or concurrently.
+
+```typescript
+import { HttpServerResponse } from '@tstdl/base/http/server';
+
+// Loop through incoming requests
+for await (const context of httpServer) {
+  const { request, respond } = context;
+
+  // Handle request asynchronously
+  (async () => {
+    try {
+      if (request.url.pathname === '/hello') {
+        await respond(
+          new HttpServerResponse({
+            statusCode: 200,
+            body: { text: 'Hello World!' },
+          }),
+        );
+      } else {
+        await respond(
+          new HttpServerResponse({
+            statusCode: 404,
+            statusMessage: 'Not Found',
+          }),
+        );
+      }
+    } catch (error) {
+      console.error(error);
+      await respond(new HttpServerResponse({ statusCode: 500 }));
+    } finally {
+      // Ensure the connection is closed if needed (handled by respond usually)
+      await context.close();
+    }
+  })();
+}
+```
+
+## 🔧 Advanced Topics
+
+### Client Middleware
+
+Middleware allows you to intercept requests and responses. This is useful for authentication, logging, or modifying headers.
+
+```typescript
+import { HttpClient, configureHttpClient, type HttpClientMiddleware, type HttpClientMiddlewareContext, type HttpClientMiddlewareNext } from '@tstdl/base/http';
+import { configureUndiciHttpClientAdapter } from '@tstdl/base/http/undici';
+import { Injector } from '@tstdl/base/injector';
+
+const authMiddleware: HttpClientMiddleware = async (context: HttpClientMiddlewareContext, next: HttpClientMiddlewareNext) => {
+  // Pre-request logic
+  context.request.headers.set('Authorization', 'Bearer my-token');
+
+  // Execute next middleware / adapter
+  await next();
+
+  // Post-response logic
+  if (context.response?.statusCode === 401) {
+    console.warn('Unauthorized request!');
+  }
+};
+
+configureUndiciHttpClientAdapter({ register: true });
+configureHttpClient({
+  middleware: [authMiddleware],
+});
+
+const client = Injector.resolve(HttpClient);
+```
+
+### Streaming Data
+
+Both the client and server support streaming, which is essential for large files or real-time data.
+
+**Client Streaming (Download):**
+
+```typescript
+const stream = httpClient.getBinaryStream('/large-file.zip');
+// stream is a ReadableStream<Uint8Array>
+
+for await (const chunk of stream) {
+  console.log(`Received chunk of size: ${chunk.length}`);
+}
+```
+
+**Server Streaming (Response):**
+
+```typescript
+import { HttpServerResponse } from '@tstdl/base/http/server';
+import { readableStreamFromPromise } from '@tstdl/base/utils/stream';
+
+// ... inside request loop
+await respond(
+  new HttpServerResponse({
+    statusCode: 200,
+    headers: { 'Content-Type': 'text/plain' },
+    body: {
+      // Create a stream that yields data
+      stream: readableStreamFromPromise(async function* () {
+        yield new TextEncoder().encode('Chunk 1\n');
+        await new Promise((r) => setTimeout(r, 1000));
+        yield new TextEncoder().encode('Chunk 2\n');
+      }),
+    },
+  }),
+);
+```
+
+### Error Handling
+
+The `HttpClient` automatically throws an `HttpError` for non-2xx responses if `throwOnNon200` is true (default).
+
+```typescript
+import { HttpError, HttpErrorReason } from '@tstdl/base/http';
+
+try {
+  await httpClient.get('/non-existent');
+} catch (error) {
+  if (error instanceof HttpError) {
+    console.log('Reason:', error.reason); // e.g., HttpErrorReason.StatusCode
+    console.log('Status:', error.response?.statusCode); // 404
+
+    // Access the response body if needed
+    const body = await error.responseInstance?.body.readAsText();
+    console.log('Error Body:', body);
+  }
+}
+```
+
+### Automatic Parameter Mapping
+
+The `HttpClientRequest` can automatically map a `parameters` object to the URL path, query string, or body based on the URL pattern and HTTP method.
+
+```typescript
+// URL: /users/:userId
+// Method: GET
+// Result: GET /users/123?details=true
+await httpClient.getJson('/users/:userId', {
+  parameters: {
+    userId: 123, // Mapped to URL path because :userId exists
+    details: true, // Mapped to Query because it's GET and not in URL path
+  },
+});
+
+// URL: /users
+// Method: POST
+// Result: POST /users with JSON body { name: 'Bob' }
+await httpClient.postJson('/users', {
+  parameters: {
+    name: 'Bob', // Mapped to Body because it's POST and no URL params match
+  },
+});
+```
+
+## 📚 API
+
+### Configuration Functions
+
+| Function                                    | Description                                                          |
+| :------------------------------------------ | :------------------------------------------------------------------- |
+| `configureHttpClient(config)`               | Configures the global `HttpClient` options, adapter, and middleware. |
+| `configureUndiciHttpClientAdapter(options)` | Configures and registers the `UndiciHttpClientAdapter` (Node.js).    |
+| `configureNodeHttpServer(config)`           | Registers the `NodeHttpServer` as the default `HttpServer`.          |
+
+### Client
+
+| Class                     | Description                                                                       |
+| :------------------------ | :-------------------------------------------------------------------------------- |
+| `HttpClient`              | Main service for making HTTP requests.                                            |
+| `HttpClientRequest`       | Represents an outgoing request. Handles parameter mapping and body normalization. |
+| `HttpClientResponse`      | Represents an incoming response. Provides access to status, headers, and body.    |
+| `HttpClientAdapter`       | Abstract base class for HTTP adapters.                                            |
+| `UndiciHttpClientAdapter` | Adapter implementation using `undici` (Node.js).                                  |
+
+### Server
+
+| Class                | Description                                                       |
+| :------------------- | :---------------------------------------------------------------- |
+| `HttpServer`         | Abstract base class for HTTP servers. Implements `AsyncIterable`. |
+| `NodeHttpServer`     | Server implementation using `node:http`.                          |
+| `HttpServerRequest`  | Represents an incoming request on the server.                     |
+| `HttpServerResponse` | Represents an outgoing response from the server.                  |
+
+### Shared / Utilities
+
+| Class          | Description                                                              |
+| :------------- | :----------------------------------------------------------------------- |
+| `HttpHeaders`  | Typed wrapper around HTTP headers.                                       |
+| `HttpBody`     | Helper to read request/response bodies as Text, JSON, Buffer, or Stream. |
+| `HttpQuery`    | Helper for managing URL query parameters.                                |
+| `HttpForm`     | Helper for `application/x-www-form-urlencoded` data.                     |
+| `HttpError`    | Error thrown when requests fail or return non-success status codes.      |
+| `CookieParser` | Utility to parse `Cookie` headers.                                       |

package/http/client/adapters/undici.adapter.js

@@ -53,7 +53,7 @@ let UndiciHttpClientAdapter = class UndiciHttpClientAdapter extends HttpClientAd
         try {
             const response = await request(httpClientRequest.url, {
                 method: httpClientRequest.method,
-                signal: httpClientRequest.abortSignal.asAbortSignal(),
+                signal: httpClientRequest.cancellationSignal.abortSignal,
                 headers: httpClientRequest.headers.asNormalizedObject(),
                 body,
                 headersTimeout: httpClientRequest.timeout,

package/http/client/http-client-request.d.ts

@@ -1,4 +1,4 @@
-import { type CancellationSignal } from '../../cancellation/index.js';
+import { type CancellationSignal, type CancellationSource } from '../../cancellation/index.js';
 import type { OneOrMany, Record, TypedOmit, UndefinableJson, UndefinableJsonObject } from '../../types/index.js';
 import { HttpForm, type HttpFormObject } from '../http-form.js';
 import { HttpHeaders, type HttpHeadersObject } from '../http-headers.js';
@@ -23,7 +23,7 @@ export type HttpRequestAuthorization = {
 };
 export type HttpFormDataObjectValue = string | number | boolean | Uint8Array<ArrayBuffer> | Blob;
 export type HttpFormDataObject = Record<string, OneOrMany<HttpFormDataObjectValue>>;
-export type HttpClientRequestOptions = Partial<TypedOmit<HttpClientRequest, 'url' | 'method' | 'abortSignal' | 'abort' | 'headers' | 'query' | 'body'>> & {
+export type HttpClientRequestOptions = Partial<TypedOmit<HttpClientRequest, 'url' | 'method' | 'cancellationSignal' | 'abort' | 'headers' | 'query' | 'body'>> & {
     urlParameter?: HttpUrlParametersObject | HttpUrlParameters;
     headers?: HttpHeadersObject | HttpHeaders;
     query?: HttpQueryObject | HttpQuery;
@@ -33,7 +33,7 @@ export type HttpClientRequestOptions = Partial<TypedOmit<HttpClientRequest, 'url
         form?: HttpFormObject | HttpForm;
         formData?: HttpFormDataObject | FormData;
     };
-    abortSignal?: CancellationSignal;
+    cancellationSignal?: CancellationSource;
     priority?: RequestPriority;
 };
 export type HttpRequestCredentials = 'omit' | 'same-origin' | 'include';
@@ -110,9 +110,10 @@ export declare class HttpClientRequest implements Disposable {
      */
     context: Record;
     /**
-     * Can be used to cancel the request. Throws HttpError
+     * Can be used to cancel the request.
+     * Must throw HttpError.
      */
-    get abortSignal(): CancellationSignal;
+    get cancellationSignal(): CancellationSignal;
     constructor(url: string, method?: HttpMethod, options?: HttpClientRequestOptions);
     constructor(requestObject: HttpClientRequestObject);
     [Symbol.dispose](): void;

package/http/client/http-client-request.js

@@ -7,7 +7,7 @@ import { HttpHeaders } from '../http-headers.js';
 import { HttpQuery } from '../http-query.js';
 import { HttpUrlParameters } from '../http-url-parameters.js';
 export class HttpClientRequest {
-    #abortToken;
+    #cancellationToken;
     url;
     method;
     headers;
@@ -75,10 +75,11 @@ export class HttpClientRequest {
      */
     context;
     /**
-     * Can be used to cancel the request. Throws HttpError
+     * Can be used to cancel the request.
+     * Must throw HttpError.
      */
-    get abortSignal() {
-        return this.#abortToken.signal;
+    get cancellationSignal() {
+        return this.#cancellationToken.signal;
     }
     constructor(urlOrObject, method, options = {}) {
         if (isString(urlOrObject)) {
@@ -106,16 +107,14 @@ export class HttpClientRequest {
         this.timeout = requestOptions.timeout ?? 30000;
         this.throwOnNon200 = requestOptions.throwOnNon200 ?? true;
         this.context = requestOptions.context ?? {};
-        this.#abortToken = requestOptions.abortSignal?.createChild() ?? new CancellationToken();
+        this.#cancellationToken = new CancellationToken(requestOptions.cancellationSignal);
     }
     [Symbol.dispose]() {
-        this.#abortToken.set();
-        this.#abortToken.complete();
+        this.#cancellationToken[Symbol.dispose]();
     }
     /** Abort the request */
     abort() {
-        this.#abortToken.set();
-        this.#abortToken.complete();
+        this.#cancellationToken.set();
     }
     clone() {
         const request = new HttpClientRequest(this);

package/http/server/node/node-http-server.js

@@ -10,7 +10,6 @@ import * as Http from 'node:http';
 import { Writable } from 'node:stream';
 import { bindNodeCallback, share } from 'rxjs';
 import { match, P } from 'ts-pattern';
-import { CancellationToken } from '../../../cancellation/index.js';
 import { HttpHeaders } from '../../../http/http-headers.js';
 import { HttpQuery } from '../../../http/http-query.js';
 import { afterResolve, inject, Singleton } from '../../../injector/index.js';
@@ -88,7 +87,7 @@ let NodeHttpServer = NodeHttpServer_1 = class NodeHttpServer extends HttpServer
             }
             if (connections > 0) {
                 this.#logger.info(`Waiting for ${connections} connections to end`);
-                await cancelableTimeout(250, CancellationToken.from(close$));
+                await cancelableTimeout(250, close$);
             }
         }
         this.#requestIterable.end();