@tstdl/base 0.93.139 → 0.93.141

package/module/module.js

@@ -1,3 +1,55 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import { CancellationToken } from '../cancellation/index.js';
 import { defineEnum } from '../enumeration/enumeration.js';
 import { enumValueName } from '../utils/enum.js';
@@ -8,8 +60,8 @@ export const ModuleState = defineEnum('ModuleState', {
     Erroneous: 3,
 });
 export class Module {
-    runPromise;
-    _state;
+    runPromise = Promise.resolve();
+    _state = ModuleState.Stopped;
     cancellationToken;
     name;
     get state() {
@@ -20,27 +72,35 @@ export class Module {
     }
     constructor(name) {
         this.name = name;
-        this.runPromise = Promise.resolve();
-        this._state = ModuleState.Stopped;
-        this.cancellationToken = new CancellationToken();
     }
     async [Symbol.asyncDispose]() {
         await this.stop();
     }
     async run() {
-        if (this._state != ModuleState.Stopped) {
-            throw new Error(`cannot start module, it is ${this.stateString}`);
-        }
-        this.cancellationToken.unset();
+        const env_1 = { stack: [], error: void 0, hasError: false };
         try {
-            this._state = ModuleState.Running;
-            this.runPromise = this._run(this.cancellationToken);
-            await this.runPromise;
-            this._state = ModuleState.Stopped;
-        }
-        catch (error) {
-            this._state = ModuleState.Erroneous;
-            throw error;
+            if (this._state != ModuleState.Stopped) {
+                throw new Error(`cannot start module, it is ${this.stateString}`);
+            }
+            const cancellationToken = __addDisposableResource(env_1, new CancellationToken(), false);
+            this.cancellationToken = cancellationToken;
+            try {
+                this._state = ModuleState.Running;
+                this.runPromise = this._run(cancellationToken);
+                await this.runPromise;
+                this._state = ModuleState.Stopped;
+            }
+            catch (error) {
+                this._state = ModuleState.Erroneous;
+                throw error;
+            }
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
         }
     }
     async stop() {

package/module/modules/web-server.module.js

@@ -18,7 +18,7 @@ export class WebServerModuleConfiguration {
 }
 ;
 let WebServerModule = class WebServerModule extends Module {
-    config = inject(WebServerModuleConfiguration);
+    config = inject(WebServerModuleConfiguration, undefined, { optional: true });
     httpServer = inject(HttpServer);
     apiGateway = inject(ApiGateway);
     apiControllers = inject(API_CONTROLLERS);
@@ -37,8 +37,8 @@ let WebServerModule = class WebServerModule extends Module {
     }
     async _run(cancellationSignal) {
         this.initialize();
-        await this.httpServer.listen(this.config.port ?? 8000);
-        const closePromise = cancellationSignal.$set.then(async () => {
+        await this.httpServer.listen(this.config?.port ?? 8000);
+        const closePromise = cancellationSignal.wait().then(async () => {
             await this.httpServer[Symbol.asyncDispose]();
         });
         for await (const context of this.httpServer) {
@@ -58,5 +58,4 @@ export { WebServerModule };
 export function configureWebServerModule({ injector, ...config } = {}) {
     const targetInjector = injector ?? Injector;
     targetInjector.register(WebServerModuleConfiguration, { useValue: config });
-    targetInjector.registerSingleton(WebServerModule, { useClass: WebServerModule });
 }

package/notification/server/module.d.ts

@@ -11,6 +11,7 @@ export declare class NotificationConfiguration {
      * Defaults to 30 days.
      */
     autoArchiveAfter?: number;
+    autoMigrate?: boolean;
 }
 export declare function configureNotification({ injector, ...config }: NotificationConfiguration & {
     injector?: Injector;

package/notification/server/module.js

@@ -1,5 +1,5 @@
 import { inject, Injector } from '../../injector/index.js';
-import { Database, migrate } from '../../orm/server/index.js';
+import { Database, migrate, registerDatabaseMigration } from '../../orm/server/index.js';
 import { isDefined } from '../../utils/type-guards.js';
 import { NotificationAncillaryService } from './services/notification-ancillary.service.js';
 export class NotificationConfiguration {
@@ -11,6 +11,7 @@ export class NotificationConfiguration {
      * Defaults to 30 days.
      */
     autoArchiveAfter;
+    autoMigrate;
 }
 export function configureNotification({ injector, ...config }) {
     const targetInjector = injector ?? Injector;
@@ -18,6 +19,9 @@ export function configureNotification({ injector, ...config }) {
     if (isDefined(config.ancillaryService)) {
         targetInjector.register(NotificationAncillaryService, { useToken: config.ancillaryService });
     }
+    if (config.autoMigrate != false) {
+        registerDatabaseMigration('Notification', migrateNotificationSchema, { injector });
+    }
 }
 /**
  * Migrates the notification schema.

package/notification/tests/notification-flow.test.js

@@ -10,7 +10,7 @@ import { runInInjectionContext, Singleton } from '../../injector/index.js';
 import { MailService } from '../../mail/mail.service.js';
 import { injectRepository } from '../../orm/server/index.js';
 import { clearTenantData, setupIntegrationTest, truncateTables } from '../../testing/index.js';
-import { InAppNotification, NotificationChannel, NotificationLogEntity, NotificationStatus, WebPushSubscription } from '../models/index.js';
+import { InAppNotification, InAppNotificationArchive, NotificationChannel, NotificationLogEntity, NotificationPreference, NotificationStatus, NotificationType, WebPushSubscription } from '../models/index.js';
 import { configureNotification } from '../server/module.js';
 import { EmailChannelProvider } from '../server/providers/email-channel-provider.js';
 import { NotificationAncillaryService } from '../server/services/notification-ancillary.service.js';
@@ -63,7 +63,7 @@ describe('Notification Flow (Integration)', () => {
         worker.registerProvider(NotificationChannel.InApp, injector.resolve(InAppChannelProvider));
     });
     beforeEach(async () => {
-        await truncateTables(database, schema, ['log', 'in_app', 'in_app_archive', 'type', 'preference', 'web_push_subscription']);
+        await truncateTables(database, schema, [NotificationLogEntity, InAppNotification, InAppNotificationArchive, NotificationType, NotificationPreference, WebPushSubscription]);
         await clearTenantData(database, 'authentication', ['user', 'subject'], tenantId);
         vi.clearAllMocks();
     });

package/notification/tests/notification-type.service.test.js

@@ -1,35 +1,44 @@
-import { describe, expect, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
 import { runInInjectionContext } from '../../injector/index.js';
 import { setupIntegrationTest, truncateTables } from '../../testing/index.js';
 import { NotificationTypeService } from '../server/services/notification-type.service.js';
 describe('NotificationTypeService', () => {
-    test('should initialize types correctly', async () => {
-        const { injector, database } = await setupIntegrationTest({ modules: { notification: true, authentication: true } });
-        // Cleanup
+    let injector;
+    let database;
+    beforeEach(async () => {
+        ({ injector, database } = await setupIntegrationTest({ modules: { notification: true, authentication: true } }));
         await truncateTables(database, 'notification', ['type']);
+    });
+    afterEach(async () => {
+        await injector.dispose();
+    });
+    test('should initialize types correctly', async () => {
         const service = injector.resolve(NotificationTypeService);
+        const prefix = crypto.randomUUID();
+        const type1 = `${prefix}_TYPE1`;
+        const type2 = `${prefix}_TYPE2`;
         const typeData = {
-            TYPE1: { label: 'Type 1' },
-            TYPE2: { label: 'Type 2', throttling: { limit: 1, interval: 1000 } }
+            [type1]: { label: 'Type 1' },
+            [type2]: { label: 'Type 2', throttling: { limit: 1, interval: 1000 } }
         };
         await runInInjectionContext(injector, async () => {
             const result = await service.initializeTypes(typeData);
-            expect(result.TYPE1.label).toBe('Type 1');
-            expect(result.TYPE2.key).toBe('TYPE2');
-            expect(result.TYPE2.throttling?.limit).toBe(1);
+            expect(result[type1]?.label).toBe('Type 1');
+            expect(result[type2]?.key).toBe(type2);
+            expect(result[type2]?.throttling?.limit).toBe(1);
             // Verify persistence
-            const dbTypes = await service.repository.loadAll();
+            const dbTypes = await service.repository.loadManyByQuery({ key: { $in: [type1, type2] } });
             expect(dbTypes).toHaveLength(2);
             // Update
             const updatedData = {
-                TYPE1: { label: 'Type 1 Updated' },
-                TYPE2: { label: 'Type 2', throttling: { limit: 1, interval: 1000 } }
+                [type1]: { label: 'Type 1 Updated' },
+                [type2]: { label: 'Type 2', throttling: { limit: 1, interval: 1000 } }
             };
             const resultUpdated = await service.initializeTypes(updatedData);
-            expect(resultUpdated.TYPE1.label).toBe('Type 1 Updated');
-            const dbTypesUpdated = await service.repository.loadAll();
+            expect(resultUpdated[type1]?.label).toBe('Type 1 Updated');
+            const dbTypesUpdated = await service.repository.loadManyByQuery({ key: { $in: [type1, type2] } });
             expect(dbTypesUpdated).toHaveLength(2);
-            expect(dbTypesUpdated.find((c) => c.key == 'TYPE1')?.label).toBe('Type 1 Updated');
+            expect(dbTypesUpdated.find((c) => c.key == type1)?.label).toBe('Type 1 Updated');
         });
     });
 });

package/object-storage/README.md

@@ -0,0 +1,300 @@
+# @tstdl/base/object-storage
+
+A flexible and extensible module for handling object storage, providing a strong abstraction layer over concrete implementations like S3. It simplifies file management with module-based isolation, automatic lifecycle management, and seamless dependency injection integration.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Configuration](#configuration)
+  - [Injecting and Using ObjectStorage](#injecting-and-using-objectstorage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Lifecycle Management (Expiration)](#lifecycle-management-expiration)
+  - [Pre-signed URLs](#pre-signed-urls)
+  - [Streaming I/O](#streaming-io)
+  - [Listing Objects](#listing-objects)
+  - [Moving and Copying](#moving-and-copying)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Abstract `ObjectStorage` Interface**: Decouples your application logic from specific storage vendors.
+- **S3-Compatible Implementation**: Includes a robust `S3ObjectStorage` implementation working with AWS S3, MinIO, Google Cloud Storage (via S3 interoperability), etc.
+- **Google Cloud Storage Implementation**: Native `GoogleObjectStorage` implementation for direct GCS support.
+- **Module-based Isolation**: Organizes objects into logical "modules". These map to either key prefixes in a shared bucket or separate buckets per module.
+- **Automatic Lifecycle Management**: Configure object expiration policies (e.g., delete temp files after 24h) directly via injection tokens.
+- **Stream Support**: Native support for `ReadableStream` and `Uint8Array` for memory-efficient handling of large files.
+- **Pre-signed URLs**: Generate secure, temporary URLs for direct client-side uploads and downloads.
+- **Dependency Injection**: Designed for `@tstdl/base/injector`, allowing context-aware resolution of storage instances.
+
+## Core Concepts
+
+### ObjectStorage
+
+The central abstract class defining the contract for storage operations (upload, download, delete, exists, etc.). You rarely instantiate this directly; instead, you request it via dependency injection.
+
+### Modules
+
+A **Module** is a logical namespace for a collection of objects (e.g., `user-avatars`, `invoices`, `temp-uploads`).
+
+- **Shared Bucket Mode**: Modules are treated as directory prefixes within a single S3 bucket (e.g., `my-bucket/user-avatars/image.png`).
+- **Bucket-Per-Module Mode**: Each module gets its own dedicated S3 bucket (e.g., bucket `user-avatars` contains `image.png`).
+
+### ObjectStorageProvider
+
+A factory responsible for creating `ObjectStorage` instances for specific modules. The `S3ObjectStorageProvider` handles the creation of S3 clients and ensures buckets exist.
+
+### ObjectStorageObject
+
+Represents a stored file. It provides methods to access metadata, size, content, and resource URIs without loading the entire file into memory immediately.
+
+## 🚀 Basic Usage
+
+### Configuration
+
+#### S3 (AWS, MinIO, etc.)
+
+Configure the S3 provider at your application's entry point (e.g., `bootstrap.ts`).
+
+```typescript
+import { configureS3ObjectStorage } from '@tstdl/base/object-storage';
+
+// Option A: Single Shared Bucket (Recommended for most use cases)
+configureS3ObjectStorage({
+  endpoint: 'http://localhost:9000', // S3 Endpoint
+  accessKey: 'minioadmin',
+  secretKey: 'minioadmin',
+  bucket: 'my-app-storage', // All modules will be subfolders in this bucket
+  forcePathStyle: true, // Required for local s3 server
+});
+
+// Option B: Bucket Per Module
+// configureS3ObjectStorage({
+//   endpoint: '...',
+//   accessKey: '...',
+//   secretKey: '...',
+//   bucketPerModule: true // Each module creates a new bucket
+// });
+```
+
+#### Google Cloud Storage
+
+```typescript
+import { configureGoogleObjectStorage } from '@tstdl/base/object-storage/google';
+
+configureGoogleObjectStorage({
+  projectId: 'my-project-id',
+  keyFilename: '/path/to/keyfile.json',
+  bucket: 'my-app-storage',
+});
+```
+
+### Injecting and Using ObjectStorage
+
+Inject `ObjectStorage` into your services using the module name as the injection argument.
+
+```typescript
+import { inject, Singleton } from '@tstdl/base/injector';
+import { ObjectStorage } from '@tstdl/base/object-storage';
+
+@Singleton()
+export class ProfilePictureService {
+  // Inject storage specifically for the 'profile-pictures' module
+  readonly #storage = inject(ObjectStorage, 'profile-pictures');
+
+  async savePicture(userId: string, content: Uint8Array): Promise<void> {
+    const key = `${userId}.jpg`;
+
+    // Upload content
+    await this.#storage.uploadObject(key, content, {
+      contentType: 'image/jpeg',
+      metadata: { userId },
+    });
+  }
+
+  async getPicture(userId: string): Promise<Uint8Array> {
+    const key = `${userId}.jpg`;
+
+    // Check existence
+    if (!(await this.#storage.exists(key))) {
+      throw new Error('Picture not found');
+    }
+
+    // Download content
+    return this.#storage.getContent(key);
+  }
+
+  async deletePicture(userId: string): Promise<void> {
+    await this.#storage.deleteObject(`${userId}.jpg`);
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Lifecycle Management (Expiration)
+
+You can configure objects to automatically expire (be deleted) after a certain duration. This is configured when injecting the storage instance. The implementation (e.g., S3) will apply lifecycle rules to the bucket.
+
+```typescript
+import { inject, Singleton } from '@tstdl/base/injector';
+import { ObjectStorage } from '@tstdl/base/object-storage';
+import { secondsPerDay } from '@tstdl/base/utils';
+
+@Singleton()
+export class TemporaryUploadService {
+  // Objects in 'temp-files' will be deleted 1 day after creation
+  readonly #tempStorage = inject(ObjectStorage, {
+    module: 'temp-files',
+    configuration: {
+      lifecycle: {
+        expiration: {
+          after: 1 * secondsPerDay,
+        },
+      },
+    },
+  });
+
+  async saveTempFile(filename: string, data: Uint8Array): Promise<void> {
+    await this.#tempStorage.uploadObject(filename, data);
+  }
+}
+```
+
+### Pre-signed URLs
+
+Offload bandwidth from your server by generating pre-signed URLs that allow clients to upload or download directly to/from the storage provider.
+
+```typescript
+import { inject, Singleton } from '@tstdl/base/injector';
+import { ObjectStorage } from '@tstdl/base/object-storage';
+import { millisecondsPerMinute, now } from '@tstdl/base/utils';
+
+@Singleton()
+export class DownloadService {
+  readonly #storage = inject(ObjectStorage, 'reports');
+
+  async getDownloadLink(reportId: string): Promise<string> {
+    const key = `${reportId}.pdf`;
+    const expiration = now().getTime() + 15 * millisecondsPerMinute;
+
+    // Generate a URL valid for 15 minutes
+    return this.#storage.getDownloadUrl(key, expiration, {
+      'response-content-disposition': 'attachment; filename="report.pdf"',
+    });
+  }
+
+  async getUploadLink(reportId: string): Promise<string> {
+    const key = `${reportId}.pdf`;
+    const expiration = now().getTime() + 15 * millisecondsPerMinute;
+
+    // Generate a PUT URL for uploading
+    return this.#storage.getUploadUrl(key, expiration, {
+      contentType: 'application/pdf',
+      contentLength: 1024 * 1024 * 5, // 5MB expected size
+    });
+  }
+}
+```
+
+### Streaming I/O
+
+For large files, use streams to avoid loading the entire file into memory.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { ObjectStorage } from '@tstdl/base/object-storage';
+
+class LargeFileService {
+  readonly #storage = inject(ObjectStorage, 'backups');
+
+  async uploadStream(filename: string, stream: ReadableStream<Uint8Array>, size: number): Promise<void> {
+    await this.#storage.uploadObject(filename, stream, {
+      contentLength: size,
+    });
+  }
+
+  async streamDownload(filename: string): Promise<ReadableStream<Uint8Array>> {
+    return this.#storage.getContentStream(filename);
+  }
+}
+```
+
+### Listing Objects
+
+Use `getObjectsCursor()` to iterate over objects efficiently using an async iterable.
+
+```typescript
+async function listAllFiles(storage: ObjectStorage) {
+  for await (const obj of storage.getObjectsCursor()) {
+    console.log(`Found file: ${obj.key}, Size: ${await obj.getContentLength()}`);
+  }
+}
+```
+
+### Moving and Copying
+
+You can move or copy objects within the same module or across different modules (and buckets).
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { ObjectStorage } from '@tstdl/base/object-storage';
+
+class FileOrganizer {
+  readonly #inbox = inject(ObjectStorage, 'inbox');
+  readonly #archive = inject(ObjectStorage, 'archive');
+
+  async archiveFile(filename: string): Promise<void> {
+    // Move from 'inbox' module to 'archive' module
+    await this.#inbox.moveObject(filename, [this.#archive, `2024/${filename}`]);
+  }
+
+  async duplicateInInbox(filename: string): Promise<void> {
+    // Copy within the same module
+    await this.#inbox.copyObject(filename, `copy_of_${filename}`);
+  }
+}
+```
+
+## 📚 API
+
+### `ObjectStorage` (Abstract Class)
+
+| Method                                         | Description                                             |
+| :--------------------------------------------- | :------------------------------------------------------ |
+| `exists(key: string): Promise<boolean>`        | Checks if an object exists.                             |
+| `uploadObject(key, content, options?)`         | Uploads data (`Uint8Array` or `ReadableStream`).        |
+| `getContent(key): Promise<Uint8Array>`         | Downloads the full object content into memory.          |
+| `getContentStream(key): ReadableStream`        | Gets a stream of the object content.                    |
+| `getDownloadUrl(key, expiration, headers?)`    | Generates a pre-signed download URL.                    |
+| `getUploadUrl(key, expiration, options?)`      | Generates a pre-signed upload URL.                      |
+| `deleteObject(key): Promise<void>`             | Deletes a single object.                                |
+| `deleteObjects(keys): Promise<void>`           | Deletes multiple objects.                               |
+| `copyObject(source, dest, options?)`           | Copies an object (intra- or inter-module).              |
+| `moveObject(source, dest, options?)`           | Moves an object (copy + delete).                        |
+| `getObjects(): Promise<ObjectStorageObject[]>` | Lists all objects in the module.                        |
+| `getObjectsCursor(): AsyncIterable`            | Iterates over objects efficiently.                      |
+| `getObject(key): Promise<ObjectStorageObject>` | Gets a handle to an object without downloading content. |
+
+### `S3ObjectStorageProviderConfig`
+
+| Property          | Type      | Description                                                                    |
+| :---------------- | :-------- | :----------------------------------------------------------------------------- |
+| `endpoint`        | `string`  | S3 API endpoint (e.g., `https://s3.amazonaws.com` or `http://localhost:9000`). |
+| `region`          | `string`  | S3 Region (e.g., `us-east-1`).                                                 |
+| `accessKey`       | `string`  | S3 Access Key ID.                                                              |
+| `secretKey`       | `string`  | S3 Secret Access Key.                                                          |
+| `bucket`          | `string`  | Name of the shared bucket. Mutually exclusive with `bucketPerModule`.          |
+| `bucketPerModule` | `boolean` | If true, creates a separate bucket for each module.                            |
+| `forcePathStyle`  | `boolean` | Whether to use path-style addressing. Useful for local s3 server.              |
+
+### `ObjectStorageObject`
+
+| Method                                   | Description                                |
+| :--------------------------------------- | :----------------------------------------- |
+| `getContentLength(): Promise<number>`    | Returns the size of the object in bytes.   |
+| `getMetadata(): Promise<ObjectMetadata>` | Returns user-defined metadata.             |
+| `getContent(): Promise<Uint8Array>`      | Downloads content.                         |
+| `getContentStream(): ReadableStream`     | Streams content.                           |
+| `getResourceUri(): Promise<string>`      | Returns the URI (e.g., `s3://bucket/key`). |