@tstdl/base 0.93.139 → 0.93.141

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();

package/image-service/README.md

@@ -0,0 +1,137 @@
+# Image Service
+
+A robust module for generating signed, manipulated image URLs, providing an abstract interface for image processing services with a concrete implementation for [imgproxy](https://imgproxy.net/).
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Image Options](#image-options)
+  - [Manual Instantiation](#manual-instantiation)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Abstract Interface**: `ImageService` base class allows for dependency injection and easy swapping of image providers.
+- **Imgproxy Support**: Full implementation for generating signed imgproxy URLs.
+- **Secure Signing**: Automatically handles HMAC-SHA256 signature generation using your key and salt.
+- **Rich Manipulations**: Supports resizing, cropping (gravity/origin), formatting, quality adjustment, and cache busting.
+- **Type-Safe Options**: Fully typed configuration and options using TypeScript enums and classes.
+
+## Core Concepts
+
+The module revolves around the `ImageService` abstract class. By depending on this abstraction in your application, you decouple your code from the specific image processing backend.
+
+The primary implementation provided is `ImgproxyImageService`. It generates URLs that point to an imgproxy server. These URLs include:
+
+1.  **Processing Options**: Instructions for resizing, formatting, etc.
+2.  **Encoded Source URL**: The original image URL, Base64 encoded.
+3.  **Signature**: A cryptographic signature ensuring the URL parameters haven't been tampered with, preventing denial-of-service attacks via image processing.
+
+## 🚀 Basic Usage
+
+### 1. Configuration
+
+First, configure the service during your application bootstrap. This registers `ImgproxyImageService` as the implementation for `ImageService` in the dependency injection container.
+
+```ts
+import { configureImgproxyImageService } from '@tstdl/base/image-service';
+
+// In your bootstrap or configuration file
+configureImgproxyImageService({
+  endpoint: 'https://images.yourdomain.com',
+  key: 'your-hex-encoded-key',
+  salt: 'your-hex-encoded-salt',
+  signatureSize: 32,
+});
+```
+
+### 2. Generating URLs
+
+Inject the `ImageService` and use `getUrl` to generate signed URLs for your images.
+
+```ts
+import { ImageService, ImageResizeMode } from '@tstdl/base/image-service';
+import { inject } from '@tstdl/base/injector';
+
+class UserProfileController {
+  // Inject the abstract service
+  readonly #imageService = inject(ImageService);
+
+  async getAvatarUrl(originalUrl: string): Promise<string> {
+    // Generate a signed URL
+    const signedUrl = await this.#imageService.getUrl(originalUrl, {
+      width: 150,
+      height: 150,
+      resizeMode: ImageResizeMode.Fill,
+    });
+
+    return signedUrl;
+    // Output example:
+    // https://images.yourdomain.com/SIGNATURE/rs:fill:150:150/aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS5qcGc
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Image Options
+
+The `ImageOptions` class provides granular control over the output image.
+
+```ts
+import { ImageService, ImageResizeMode, ImageOrigin, ImageFormat } from '@tstdl/base/image-service';
+import { inject } from '@tstdl/base/injector';
+
+const imageService = inject(ImageService);
+
+const url = await imageService.getUrl('https://example.com/banner.png', {
+  // Resize strategy
+  resizeMode: ImageResizeMode.Fit, // 'fit' or 'fill'
+  width: 800,
+  height: 400,
+
+  // Gravity / Origin (where to focus when cropping)
+  origin: ImageOrigin.Smart, // Uses smart detection if supported, or center
+
+  // Output format and quality
+  format: ImageFormat.Webp,
+  quality: 80,
+
+  // Cache busting string (appended to processing options)
+  cacheBuster: 'v1.2.3',
+});
+```
+
+### Manual Instantiation
+
+If you need to instantiate `ImgproxyImageService` directly (outside of the DI container) or manage multiple instances with different configurations:
+
+```ts
+import { ImgproxyImageService } from '@tstdl/base/image-service';
+
+const imgproxy = new ImgproxyImageService(
+  'https://img.example.com', // endpoint
+  'aabbcc...', // key (hex)
+  '112233...', // salt (hex)
+  32, // signature size
+);
+
+const url = await imgproxy.getUrl('http://source.com/img.jpg', { width: 100 });
+```
+
+## 📚 API
+
+| Export                          | Type             | Description                                                                                |
+| :------------------------------ | :--------------- | :----------------------------------------------------------------------------------------- |
+| `ImageService`                  | `abstract class` | The base contract for image services. Defines `getUrl`.                                    |
+| `ImgproxyImageService`          | `class`          | Concrete implementation for imgproxy.                                                      |
+| `configureImgproxyImageService` | `function`       | Helper to register the imgproxy service and config in the injector.                        |
+| `ImageOptions`                  | `class`          | Configuration object for image manipulation (width, height, etc.).                         |
+| `ImageResizeMode`               | `enum`           | Resize strategies: `Fit`, `Fill`.                                                          |
+| `ImageFormat`                   | `enum`           | Output formats: `Png`, `Jpg`, `Webp`, `Avif`, etc.                                         |
+| `ImageOrigin`                   | `enum`           | Gravity/Origin for cropping: `Center`, `Smart`, `Top`, `TopLeft`, etc.                     |
+| `IMGPROXY_IMAGE_SERVICE_CONFIG` | `InjectionToken` | Token used to inject the configuration object.                                             |
+| `ImgproxyImageServiceConfig`    | `type`           | Type definition for the configuration object (`endpoint`, `key`, `salt`, `signatureSize`). |