@tstdl/base 0.93.1 → 0.93.3

package/api/server/api-request-token.provider.d.ts

@@ -1,10 +1,12 @@
+import type { Token } from '../../authentication/index.js';
 import type { ApiRequestData } from '../types.js';
 export declare abstract class ApiRequestTokenProvider {
-    abstract getToken<T>(requestData: ApiRequestData): T | Promise<T>;
+    getToken<T extends Token>(data: ApiRequestData): Promise<T>;
+    abstract tryGetToken<T extends Token>(requestData: ApiRequestData): T | null | Promise<T | null>;
 }
 export declare class NoopApiRequestTokenProvider extends ApiRequestTokenProvider {
-    getToken<T>(): T;
+    tryGetToken<T extends Token>(_requestData: ApiRequestData): T | null | Promise<T | null>;
 }
 export declare class MockApiRequestTokenProvider extends ApiRequestTokenProvider {
-    getToken<T>(): T;
+    tryGetToken<T extends Token>(_requestData: ApiRequestData): T | null | Promise<T | null>;
 }

package/api/server/api-request-token.provider.js

@@ -5,11 +5,19 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Singleton } from '../../injector/decorators.js';
+import { isNull } from '../../utils/type-guards.js';
 export class ApiRequestTokenProvider {
+    async getToken(data) {
+        const token = await this.tryGetToken(data);
+        if (isNull(token)) {
+            throw new Error('No token available for request');
+        }
+        return token;
+    }
 }
 let NoopApiRequestTokenProvider = class NoopApiRequestTokenProvider extends ApiRequestTokenProvider {
-    getToken() {
-        throw new Error('No RequestTokenProvider registered');
+    tryGetToken(_requestData) {
+        throw new Error('No RequestInfoProvider registered');
     }
 };
 NoopApiRequestTokenProvider = __decorate([
@@ -17,11 +25,11 @@ NoopApiRequestTokenProvider = __decorate([
 ], NoopApiRequestTokenProvider);
 export { NoopApiRequestTokenProvider };
 let MockApiRequestTokenProvider = class MockApiRequestTokenProvider extends ApiRequestTokenProvider {
-    getToken() {
+    tryGetToken(_requestData) {
         return {};
     }
 };
 MockApiRequestTokenProvider = __decorate([
-    Singleton({ alias: ApiRequestTokenProvider })
+    Singleton()
 ], MockApiRequestTokenProvider);
 export { MockApiRequestTokenProvider };

package/api/server/gateway.d.ts

@@ -50,15 +50,7 @@ export type ApiMetadata = {
     patternResult: URLPatternResult;
 };
 export declare class ApiGateway implements Resolvable<ApiGatewayOptions> {
-    private readonly requestTokenProvider;
-    private readonly logger;
-    private readonly prefix;
-    private readonly apis;
-    private readonly middlewares;
-    private readonly supressedErrors;
-    private readonly catchErrorMiddleware;
-    private readonly options;
-    private composedMiddleware;
+    #private;
     readonly [resolveArgumentType]: ApiGatewayOptions;
     constructor();
     addMiddleware(middleware: ApiGatewayMiddleware): void;

package/api/server/gateway.js

@@ -7,13 +7,18 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var _a;
 var ApiGateway_1;
+import { match } from 'ts-pattern';
 import 'urlpattern-polyfill';
+import { Auditor } from '../../audit/auditor.js';
+import { ActorType } from '../../audit/types.js';
+import { NIL_UUID } from '../../constants.js';
 import { BadRequestError } from '../../errors/bad-request.error.js';
 import { NotFoundError } from '../../errors/not-found.error.js';
 import { NotImplementedError } from '../../errors/not-implemented.error.js';
 import { HttpServerResponse } from '../../http/server/index.js';
-import { Singleton, inject, injectArgument, resolveArgumentType } from '../../injector/index.js';
+import { inject, injectArgument, resolveArgumentType, Singleton } from '../../injector/index.js';
 import { Logger } from '../../logger/index.js';
 import { Schema } from '../../schema/index.js';
 import { DataStreamSource } from '../../sse/data-stream-source.js';
@@ -23,7 +28,7 @@ import { toArray } from '../../utils/array/array.js';
 import { composeAsyncMiddleware } from '../../utils/middleware.js';
 import { mapObjectValues } from '../../utils/object/object.js';
 import { deferThrow } from '../../utils/throw.js';
-import { isArray, isBlob, isDefined, isNull, isNullOrUndefined, isObject, isReadableStream, isUint8Array, isUndefined } from '../../utils/type-guards.js';
+import { isArray, isBlob, isDefined, isNotNull, isNotNullOrUndefined, isNull, isNullOrUndefined, isObject, isReadableStream, isUint8Array, isUndefined } from '../../utils/type-guards.js';
 import { mebibyte } from '../../utils/units.js';
 import { normalizedApiDefinitionEndpointsEntries } from '../types.js';
 import { getFullApiEndpointResource } from '../utils.js';
@@ -51,42 +56,43 @@ export class ApiGatewayOptions {
     defaultMaxBytes;
 }
 let ApiGateway = ApiGateway_1 = class ApiGateway {
-    requestTokenProvider = inject(ApiRequestTokenProvider);
-    logger = inject(Logger, ApiGateway_1.name);
-    prefix;
-    apis;
-    middlewares;
-    supressedErrors;
-    catchErrorMiddleware;
-    options = injectArgument(this, { optional: true }) ?? {};
-    composedMiddleware;
+    #requestTokenProvider = inject(ApiRequestTokenProvider);
+    #auditor = inject(Auditor, 'Api');
+    #logger = inject(Logger, ApiGateway_1.name);
+    #prefix;
+    #apis;
+    #middlewares;
+    #supressedErrors;
+    #catchErrorMiddleware;
+    #options = injectArgument(this, { optional: true }) ?? {};
+    #composedMiddleware;
     constructor() {
-        this.prefix = isNull(this.options.prefix) ? null : (this.options.prefix ?? 'api');
-        this.apis = new Map();
-        this.middlewares = this.options.middlewares ?? [];
-        this.supressedErrors = new Set(this.options.supressedErrors);
-        this.catchErrorMiddleware = getCatchErrorMiddleware(this.supressedErrors, this.logger);
+        this.#prefix = isNull(this.#options.prefix) ? null : (this.#options.prefix ?? 'api');
+        this.#apis = new Map();
+        this.#middlewares = this.#options.middlewares ?? [];
+        this.#supressedErrors = new Set(this.#options.supressedErrors);
+        this.#catchErrorMiddleware = getCatchErrorMiddleware(this.#supressedErrors, this.#logger);
         this.updateMiddleware();
     }
     addMiddleware(middleware) {
-        this.middlewares.push(middleware);
+        this.#middlewares.push(middleware);
         this.updateMiddleware();
     }
     supressErrors(...errorTypes) {
         for (const type of errorTypes) {
-            this.supressedErrors.add(type);
+            this.#supressedErrors.add(type);
         }
     }
     registerApi(definition, implementation) {
         for (const [name, endpointDefinition] of normalizedApiDefinitionEndpointsEntries(definition.endpoints)) {
             const versionArray = isUndefined(endpointDefinition.version) ? [1] : toArray(endpointDefinition.version);
             for (const version of versionArray) {
-                const resource = getFullApiEndpointResource({ api: definition, endpoint: endpointDefinition, defaultPrefix: this.prefix, explicitVersion: version });
+                const resource = getFullApiEndpointResource({ api: definition, endpoint: endpointDefinition, defaultPrefix: this.#prefix, explicitVersion: version });
                 const methods = isArray(endpointDefinition.method) ? endpointDefinition.method : [endpointDefinition.method ?? 'GET'];
                 if (methods.length == 0) {
                     throw new Error(`No method provided for resource ${resource}.`);
                 }
-                let resourceApis = this.apis.get(resource);
+                let resourceApis = this.#apis.get(resource);
                 if (isUndefined(resourceApis)) {
                     resourceApis = {
                         resource,
@@ -103,7 +109,7 @@ let ApiGateway = ApiGateway_1 = class ApiGateway {
                         }),
                         endpoints: new Map(),
                     };
-                    this.apis.set(resource, resourceApis);
+                    this.#apis.set(resource, resourceApis);
                 }
                 const endpointImplementation = implementation[name]?.bind(implementation) ?? deferThrow(() => new NotImplementedError(`Endpoint ${name} for resource ${resource} not implemented.`));
                 for (const method of methods) {
@@ -119,13 +125,13 @@ let ApiGateway = ApiGateway_1 = class ApiGateway {
             const { api, patternResult } = this.getApiMetadata(request.url);
             const endpoint = api.endpoints.get(request.method);
             const context = { api, resourcePatternResult: patternResult, endpoint, request, response };
-            await this.composedMiddleware(context);
+            await this.#composedMiddleware(context);
             responded = true;
             await respond(context.response);
         }
         catch (error) {
             try {
-                handleApiError(error, response, this.supressedErrors, this.logger);
+                handleApiError(error, response, this.#supressedErrors, this.#logger);
                 if (responded) {
                     await close();
                 }
@@ -134,7 +140,7 @@ let ApiGateway = ApiGateway_1 = class ApiGateway {
                         await respond(response);
                     }
                     catch (errorRespondError) {
-                        this.logger.error(errorRespondError);
+                        this.#logger.error(errorRespondError);
                         await close();
                     }
                 }
@@ -145,7 +151,7 @@ let ApiGateway = ApiGateway_1 = class ApiGateway {
     getApiMetadata(resource) {
         const urlWithoutPort = new URL(resource);
         urlWithoutPort.port = '';
-        for (const api of this.apis.values()) {
+        for (const api of this.#apis.values()) {
             const result = api.pattern.exec(urlWithoutPort);
             if (isNullOrUndefined(result)) {
                 continue;
@@ -155,11 +161,11 @@ let ApiGateway = ApiGateway_1 = class ApiGateway {
         throw new NotFoundError(`Resource ${resource.pathname} not available.`);
     }
     updateMiddleware() {
-        const middlewares = [responseTimeMiddleware, contentTypeMiddleware, this.catchErrorMiddleware, corsMiddleware(this.options.cors), allowedMethodsMiddleware, ...this.middlewares, async (context, next) => this.endpointMiddleware(context, next)];
-        this.composedMiddleware = composeAsyncMiddleware(middlewares);
+        const middlewares = [responseTimeMiddleware, contentTypeMiddleware, this.#catchErrorMiddleware, corsMiddleware(this.#options.cors), allowedMethodsMiddleware, ...this.#middlewares, async (context, next) => await this.endpointMiddleware(context, next)];
+        this.#composedMiddleware = composeAsyncMiddleware(middlewares);
     }
     async endpointMiddleware(context, next) {
-        const readBodyOptions = { maxBytes: context.endpoint.definition.maxBytes ?? this.options.defaultMaxBytes ?? defaultMaxBytes };
+        const readBodyOptions = { maxBytes: context.endpoint.definition.maxBytes ?? this.#options.defaultMaxBytes ?? defaultMaxBytes };
         const body = isDefined(context.endpoint.definition.body)
             ? await getBody(context.request, readBodyOptions, context.endpoint.definition.body)
             : undefined;
@@ -174,24 +180,49 @@ let ApiGateway = ApiGateway_1 = class ApiGateway {
         const validatedParameters = isDefined(context.endpoint.definition.parameters)
             ? Schema.parse(context.endpoint.definition.parameters, parameters)
             : parameters;
+        const requestTokenProvider = this.#requestTokenProvider;
+        const auditor = this.#auditor;
         const requestContext = {
             parameters: validatedParameters,
             body,
             request: context.request,
-            getToken: async () => this.requestTokenProvider.getToken(requestContext),
+            async tryGetToken() {
+                return await requestTokenProvider.tryGetToken(requestContext);
+            },
+            async getToken() {
+                return await requestTokenProvider.getToken(requestContext);
+            },
+            async getAuditor() {
+                const token = await this.tryGetToken();
+                return auditor.fork(context.api.resource)
+                    .withCorrelation()
+                    .with({
+                    actorType: isNotNull(token) ? ActorType.User : ActorType.Anonymous,
+                    actor: token?.payload.subject ?? NIL_UUID,
+                    impersonatorType: isNotNullOrUndefined(token?.payload.impersonator) ? ActorType.User : null,
+                    impersonator: token?.payload.impersonator ?? null,
+                    network: {
+                        path: context.request.url.pathname,
+                        ipAddress: context.request.ip,
+                        userAgent: context.request.headers.tryGetSingle('User-Agent') ?? null,
+                        sessionId: token?.payload.sessionId ?? null,
+                    },
+                });
+            },
         };
         const result = await context.endpoint.implementation(requestContext);
         if (result instanceof HttpServerResponse) {
             context.response.update(result);
         }
         else {
-            context.response.body = isUint8Array(result) ? { buffer: result }
-                : isBlob(result) ? { stream: result.stream() }
-                    : isReadableStream(result) ? { stream: result }
-                        : (result instanceof ServerSentEventsSource) ? { events: result }
-                            : (context.endpoint.definition.result == DataStream) ? { events: DataStreamSource.fromIterable(result).eventSource }
-                                : (context.endpoint.definition.result == String) ? { text: result }
-                                    : { json: result };
+            context.response.body = match(result)
+                .when(isUint8Array, (buffer) => ({ buffer }))
+                .when(isBlob, (value) => ({ stream: value.stream() }))
+                .when((isReadableStream), (stream) => ({ stream }))
+                .when((value) => value instanceof ServerSentEventsSource, (events) => ({ events }))
+                .when(() => (context.endpoint.definition.result == DataStream), (value) => ({ events: DataStreamSource.fromIterable(value).eventSource }))
+                .when(() => (context.endpoint.definition.result == String), (text) => ({ text: text }))
+                .otherwise((json) => ({ json }));
         }
         await next();
     }

package/api/types.d.ts

@@ -1,4 +1,6 @@
 import type { Observable } from 'rxjs';
+import type { Auditor } from '../audit/index.js';
+import type { Token } from '../authentication/index.js';
 import type { HttpServerRequest, HttpServerResponse } from '../http/server/index.js';
 import type { HttpMethod } from '../http/types.js';
 import type { SchemaOutput, SchemaTestable } from '../schema/index.js';
@@ -106,7 +108,9 @@ export type ApiRequestData<T extends ApiDefinition = ApiDefinition, K extends Ap
     request: HttpServerRequest;
 };
 export type ApiRequestContext<T extends ApiDefinition = ApiDefinition, K extends ApiEndpointKeys<T> = ApiEndpointKeys<T>> = ApiRequestData<T, K> & {
-    getToken<Token>(): Promise<Token>;
+    tryGetToken<T extends Token>(): Promise<T | null>;
+    getToken<T extends Token>(): Promise<T>;
+    getAuditor(): Promise<Auditor>;
 };
 export type ApiEndpointServerImplementation<T extends ApiDefinition = ApiDefinition, K extends ApiEndpointKeys<T> = ApiEndpointKeys<T>> = (context: ApiRequestContext<T, K>) => ApiServerResult<T, K> | Promise<ApiServerResult<T, K>>;
 export type ApiEndpointClientImplementation<T extends ApiDefinition = ApiDefinition, K extends ApiEndpointKeys<T> = ApiEndpointKeys<T>> = ApiClientBody<T, K> extends never ? ApiParameters<T, K> extends never ? () => Promise<ApiClientResult<T, K>> : (parameters: ApiParameters<T, K>) => Promise<ApiClientResult<T, K>> : (parameters: ApiParameters<T, K> extends never ? undefined | Record<never, never> : ApiParameters<T, K>, body: ApiClientBody<T, K>) => Promise<ApiClientResult<T, K>>;

package/application/application.d.ts

@@ -7,6 +7,8 @@ export type DestructorFn = () => void | Promise<void>;
 export declare const APPLICATION_MODULE: import("../injector/token.js").InjectionToken<Module, never>;
 export declare const APPLICATION_INITIALIZER: import("../injector/token.js").InjectionToken<InitializerFn, never>;
 export declare const APPLICATION_DESTRUCTOR: import("../injector/token.js").InjectionToken<DestructorFn, never>;
+export declare const APPLICATION_INSTANCE_ID: import("../injector/token.js").InjectionToken<string, never>;
+export declare const APPLICATION_NAME: import("../injector/token.js").InjectionToken<string, never>;
 export declare class Application {
     #private;
     static create(name: string, providers?: OneOrMany<ProvidersItem>[]): Application;

package/application/application.js

@@ -19,7 +19,8 @@ import { isDefined, isFunction } from '../utils/type-guards.js';
 export const APPLICATION_MODULE = injectionToken('ApplicationModule');
 export const APPLICATION_INITIALIZER = injectionToken('ApplicationInitializer');
 export const APPLICATION_DESTRUCTOR = injectionToken('ApplicationDestructor');
-const APPLICATION_NAME = injectionToken('ApplicationName');
+export const APPLICATION_INSTANCE_ID = injectionToken('ApplicationInstanceId');
+export const APPLICATION_NAME = injectionToken('ApplicationName');
 let Application = Application_1 = class Application {
     #name = inject(APPLICATION_NAME);
     #injector = inject(Injector);
@@ -29,6 +30,7 @@ let Application = Application_1 = class Application {
     #shutdownToken = inject(CancellationSignal, undefined, { optional: true })?.createChild() ?? new CancellationToken();
     static create(name, providers = []) {
         const injector = new Injector(`${name}Injector`);
+        injector.register(APPLICATION_INSTANCE_ID, { useValue: crypto.randomUUID() });
         injector.register(APPLICATION_NAME, { useValue: name });
         for (const providersItem of providers.flat()) {
             injector.register(providersItem.provide, providersItem, { multi: providersItem.multi });

package/application/providers.d.ts

@@ -3,7 +3,7 @@ import { type ProvidersItem } from '../injector/index.js';
 import { Module, type FunctionModuleFunction } from '../module/index.js';
 import type { OneOrMany, Type } from '../types/index.js';
 import { type DestructorFn, type InitializerFn } from './application.js';
-export declare function provideModules(...functionsAndModules: OneOrMany<FunctionModuleFunction | Type<Module>>[]): ProvidersItem[];
+export declare function provideModule(...functionsAndModules: OneOrMany<FunctionModuleFunction | Type<Module>>[]): ProvidersItem[];
 export declare function provideInitializer(fn: InitializerFn): ProvidersItem;
 export declare function provideDestructor(fn: DestructorFn): ProvidersItem;
 export declare function provideShutdownSignal(signal: CancellationSignal): ProvidersItem;

package/application/providers.js

@@ -7,7 +7,7 @@ import { typeExtends } from '../utils/type/index.js';
 import { Application, APPLICATION_DESTRUCTOR, APPLICATION_INITIALIZER, APPLICATION_MODULE } from './application.js';
 const quitSignals = ['SIGTERM', 'SIGINT', 'SIGHUP', 'SIGBREAK'];
 const quitEvents = ['uncaughtException', 'unhandledRejection', 'rejectionHandled'];
-export function provideModules(...functionsAndModules) {
+export function provideModule(...functionsAndModules) {
     return functionsAndModules.flat().map((fnOrModule) => {
         if (typeExtends(fnOrModule, Module)) {
             return { provide: APPLICATION_MODULE, useValue: fnOrModule, multi: true };

package/audit/audit.model.d.ts

@@ -1,15 +1,115 @@
-import { EntityWithoutMetadata, Json, Timestamp, Uuid } from '../orm/index.js';
+import { type Embedded, EntityWithoutMetadata, type Json, type Timestamp, type Uuid } from '../orm/index.js';
+import type { UndefinableJsonObject } from '../types/index.js';
 import { ActorType, AuditOutcome, AuditSeverity } from './types.js';
-export declare class AuditEvent extends EntityWithoutMetadata {
+/**
+ * Represents the network details of the request that triggered the audit event.
+ */
+export declare class RequestDetails {
+    /**
+     * The path of the request.
+     * @example '/api/v1/users/xyz'
+     */
+    path: string | null;
+    /**
+     * The IP address of the client.
+     * @example '192.168.1.100'
+     */
+    ipAddress: string | null;
+    /**
+     * The user agent string of the client.
+     * @example 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...'
+     */
+    userAgent: string | null;
+    /**
+     * The session ID associated with the request, if any.
+     */
+    sessionId: Uuid | null;
+}
+/**
+ * Represents the state of data before and after a change.
+ */
+export declare class ChangeDetails {
+    /**
+     * The state of the data before the change occurred.
+     */
+    before: Json<unknown> | null;
+    /**
+     * The state of the data after the change occurred.
+     */
+    after: Json<unknown> | null;
+}
+/**
+ * Represents a single audit event record in the database.
+ * This entity captures who did what, when, and to what, along with other contextual information.
+ *
+ * @template Details The type of the `details` JSON object, allowing for custom, action-specific data.
+ */
+export declare class AuditEvent<Details extends UndefinableJsonObject = UndefinableJsonObject> extends EntityWithoutMetadata {
+    /**
+     * The timestamp when the event occurred.
+     */
     timestamp: Timestamp;
-    correlationId?: Uuid;
+    /**
+     * The ID of the tenant in which the event occurred. Can be null for system-level events.
+     */
+    tenantId: Uuid | null;
+    /**
+     * A unique identifier to correlate multiple related audit events.
+     */
+    correlationId: Uuid | null;
+    /**
+     * The module or feature area where the event originated, in dot-separated format.
+     * @example 'user.authentication'
+     */
     module: string;
+    /**
+     * The specific action that was performed.
+     * @example 'login'
+     */
     action: string;
+    /**
+     * The outcome of the action.
+     */
     outcome: AuditOutcome;
+    /**
+     * The severity level of the event.
+     */
     severity: AuditSeverity;
-    actorId: string;
+    /**
+     * The type of the actor.
+     */
     actorType: ActorType;
-    targetId: string;
+    /**
+     * The (if possible unique) identifier of the actor who performed the action.
+     */
+    actor: string | null;
+    /**
+     * The type of the impersonator, if applicable.
+     */
+    impersonatorType: ActorType | null;
+    /**
+     * The (if possible unique) identifier of the user who is impersonating the actor, if applicable.
+     */
+    impersonator: string | null;
+    /**
+     * The type of the target entity.
+     * @example 'User'
+     */
     targetType: string;
-    details?: Json<unknown>;
+    /**
+     * The unique identifier of the primary resource or entity that was the target of the action.
+     */
+    targetId: Uuid;
+    /**
+     * Network-related details for the request that triggered the event.
+     */
+    network: Embedded<RequestDetails> | null;
+    /**
+     * Details about data changes.
+     */
+    changes: Embedded<ChangeDetails> | null;
+    /**
+     * A flexible JSON object for storing additional, action-specific details.
+     */
+    details: Json<Details> | null;
 }