@tstdl/base 0.92.168 → 0.93.0

package/audit/audit.model.d.ts

@@ -0,0 +1,15 @@
+import { EntityWithoutMetadata, Json, Timestamp, Uuid } from '../orm/index.js';
+import { ActorType, AuditOutcome, AuditSeverity } from './types.js';
+export declare class AuditEvent extends EntityWithoutMetadata {
+    timestamp: Timestamp;
+    correlationId?: Uuid;
+    module: string;
+    action: string;
+    outcome: AuditOutcome;
+    severity: AuditSeverity;
+    actorId: string;
+    actorType: ActorType;
+    targetId: string;
+    targetType: string;
+    details?: Json<unknown>;
+}

package/audit/audit.model.js

@@ -0,0 +1,73 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { EntityWithoutMetadata, Json, Table, Timestamp, Uuid } from '../orm/index.js';
+import { Enumeration, StringProperty } from '../schema/index.js';
+import { ActorType, AuditOutcome, AuditSeverity } from './types.js';
+let AuditEvent = class AuditEvent extends EntityWithoutMetadata {
+    timestamp;
+    correlationId;
+    module;
+    action;
+    outcome;
+    severity;
+    actorId;
+    actorType;
+    targetId;
+    targetType;
+    details;
+};
+__decorate([
+    Timestamp(),
+    __metadata("design:type", Number)
+], AuditEvent.prototype, "timestamp", void 0);
+__decorate([
+    Uuid({ nullable: true }),
+    __metadata("design:type", String)
+], AuditEvent.prototype, "correlationId", void 0);
+__decorate([
+    StringProperty(),
+    __metadata("design:type", String)
+], AuditEvent.prototype, "module", void 0);
+__decorate([
+    StringProperty(),
+    __metadata("design:type", String)
+], AuditEvent.prototype, "action", void 0);
+__decorate([
+    Enumeration(AuditOutcome),
+    __metadata("design:type", String)
+], AuditEvent.prototype, "outcome", void 0);
+__decorate([
+    Enumeration(AuditSeverity),
+    __metadata("design:type", String)
+], AuditEvent.prototype, "severity", void 0);
+__decorate([
+    StringProperty(),
+    __metadata("design:type", String)
+], AuditEvent.prototype, "actorId", void 0);
+__decorate([
+    Enumeration(ActorType),
+    __metadata("design:type", String)
+], AuditEvent.prototype, "actorType", void 0);
+__decorate([
+    StringProperty(),
+    __metadata("design:type", String)
+], AuditEvent.prototype, "targetId", void 0);
+__decorate([
+    StringProperty(),
+    __metadata("design:type", String)
+], AuditEvent.prototype, "targetType", void 0);
+__decorate([
+    Json({ nullable: true }),
+    __metadata("design:type", Object)
+], AuditEvent.prototype, "details", void 0);
+AuditEvent = __decorate([
+    Table({ name: 'event' })
+], AuditEvent);
+export { AuditEvent };

package/audit/auditor.d.ts

@@ -0,0 +1,42 @@
+import { type Resolvable, type resolveArgumentType } from '../injector/index.js';
+import type { UndefinableJsonObject } from '../types/index.js';
+import type { ActorType } from './types.js';
+import { AuditOutcome, AuditSeverity } from './types.js';
+export type AuditPayload = Partial<{
+    correlationId?: string;
+    outcome?: AuditOutcome;
+    severity?: AuditSeverity;
+    actorId?: string;
+    actorType?: ActorType;
+    targetId?: string;
+    targetType?: string;
+    details?: UndefinableJsonObject;
+}>;
+export type AuditorArgument = string | string[] | {
+    module?: string | string[];
+    context?: Partial<AuditPayload>;
+};
+export declare class Auditor implements Resolvable<AuditorArgument> {
+    #private;
+    readonly module: string[];
+    readonly context: Partial<Partial<{
+        correlationId?: string;
+        outcome?: AuditOutcome;
+        severity?: AuditSeverity;
+        actorId?: string;
+        actorType?: ActorType;
+        targetId?: string;
+        targetType?: string;
+        details?: UndefinableJsonObject;
+    }>>;
+    get moduleString(): string;
+    readonly [resolveArgumentType]: AuditorArgument;
+    fork(subModule: string | string[]): Auditor;
+    with(context: Partial<AuditPayload>): Auditor;
+    withCorrelation(): Auditor;
+    log(action: string, data?: AuditPayload): Promise<void>;
+    info(action: string, data: AuditPayload): Promise<void>;
+    warn(action: string, data: AuditPayload): Promise<void>;
+    error(action: string, data: AuditPayload): Promise<void>;
+    critical(action: string, data: AuditPayload): Promise<void>;
+}

package/audit/auditor.js

@@ -0,0 +1,111 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var Auditor_1;
+import { createContextProvider } from '../context/index.js';
+import { Injectable, injectArgument } from '../injector/index.js';
+import { injectRepository } from '../orm/server/index.js';
+import { TRANSACTION_TIMESTAMP } from '../orm/sqls.js';
+import { toArray } from '../utils/array/index.js';
+import { Memoize } from '../utils/function/memoize.js';
+import { filterUndefinedFromRecord, objectKeys } from '../utils/object/object.js';
+import { assertDefinedPass, isArray, isNotArray, isObject, isString } from '../utils/type-guards.js';
+import { AuditEvent } from './audit.model.js';
+import { AuditOutcome, AuditSeverity } from './types.js';
+const { runInAuditorCreationContext, getCurrentAuditorCreationContext, isInAuditorCreationContext } = createContextProvider('AuditorCreation');
+let Auditor = Auditor_1 = class Auditor {
+    #repository = injectRepository(AuditEvent);
+    #argument = isInAuditorCreationContext() ? injectArgument(this, { optional: true }) : undefined;
+    #creationContext = getCurrentAuditorCreationContext();
+    module = this.#creationContext?.module ?? moduleFromArgument(this.#argument);
+    context = this.#creationContext?.context ?? ((isObject(this.#argument) && isNotArray(this.#argument)) ? (this.#argument.context ?? {}) : {});
+    get moduleString() {
+        return this.module.join('.');
+    }
+    fork(subModule) {
+        return runInAuditorCreationContext({
+            module: [...this.module, ...toArray(subModule)],
+            context: this.context,
+        }, () => new Auditor_1());
+    }
+    with(context) {
+        return runInAuditorCreationContext({
+            module: this.module,
+            context: { ...this.context, ...context, details: { ...this.context.details, ...context.details } },
+        }, () => new Auditor_1());
+    }
+    withCorrelation() {
+        return this.with({ correlationId: this.context.correlationId ?? crypto.randomUUID() });
+    }
+    async log(action, data) {
+        const mergedData = { ...this.context, ...data, details: filterUndefinedFromRecord({ ...this.context.details, ...data?.details }) };
+        await this.#repository.insert({
+            timestamp: TRANSACTION_TIMESTAMP,
+            correlationId: mergedData.correlationId,
+            module: this.moduleString,
+            action: action,
+            outcome: assertDefinedPass(mergedData.outcome, 'Audit outcome is required'),
+            severity: assertDefinedPass(mergedData.severity, 'Audit severity is required'),
+            actorId: assertDefinedPass(mergedData.actorId, 'Audit actorId is required'),
+            actorType: assertDefinedPass(mergedData.actorType, 'Audit actorType is required'),
+            targetId: assertDefinedPass(mergedData.targetId, 'Audit targetId is required'),
+            targetType: assertDefinedPass(mergedData.targetType, 'Audit targetType is required'),
+            details: (objectKeys(mergedData.details).length > 0) ? mergedData.details : undefined,
+        });
+    }
+    async info(action, data) {
+        await this.log(action, {
+            ...data,
+            severity: AuditSeverity.Info,
+            outcome: data.outcome ?? AuditOutcome.Success,
+        });
+    }
+    async warn(action, data) {
+        await this.log(action, {
+            ...data,
+            severity: AuditSeverity.Warn,
+            outcome: data.outcome ?? AuditOutcome.Failure,
+        });
+    }
+    async error(action, data) {
+        await this.log(action, {
+            ...data,
+            severity: AuditSeverity.Error,
+            outcome: data.outcome ?? AuditOutcome.Failure,
+        });
+    }
+    async critical(action, data) {
+        await this.log(action, {
+            ...data,
+            severity: AuditSeverity.Critical,
+            outcome: data.outcome ?? AuditOutcome.Failure,
+        });
+    }
+};
+__decorate([
+    Memoize(),
+    __metadata("design:type", String),
+    __metadata("design:paramtypes", [])
+], Auditor.prototype, "moduleString", null);
+Auditor = Auditor_1 = __decorate([
+    Injectable()
+], Auditor);
+export { Auditor };
+function moduleFromArgument(argument) {
+    if (isString(argument)) {
+        return [argument];
+    }
+    if (isArray(argument)) {
+        return argument;
+    }
+    if (isObject(argument)) {
+        return moduleFromArgument(argument.module);
+    }
+    return [];
+}

package/audit/index.d.ts

@@ -0,0 +1,3 @@
+export * from './auditor.js';
+export * from './audit.model.js';
+export * from './types.js';

package/audit/index.js

@@ -0,0 +1,3 @@
+export * from './auditor.js';
+export * from './audit.model.js';
+export * from './types.js';

package/audit/types.d.ts

@@ -0,0 +1,22 @@
+import { type EnumType } from '../enumeration/index.js';
+export declare const AuditSeverity: {
+    readonly Info: "info";
+    readonly Warn: "warn";
+    readonly Error: "error";
+    readonly Critical: "critical";
+};
+export type AuditSeverity = EnumType<typeof AuditSeverity>;
+export declare const AuditOutcome: {
+    readonly Pending: "pending";
+    readonly Success: "success";
+    readonly Cancelled: "cancelled";
+    readonly Failure: "failure";
+    readonly Denied: "denied";
+};
+export type AuditOutcome = EnumType<typeof AuditOutcome>;
+export declare const ActorType: {
+    readonly User: "user";
+    readonly System: "system";
+    readonly ApiKey: "api-key";
+};
+export type ActorType = EnumType<typeof ActorType>;

package/audit/types.js

@@ -0,0 +1,19 @@
+import { defineEnum } from '../enumeration/index.js';
+export const AuditSeverity = defineEnum('AuditSeverity', {
+    Info: 'info',
+    Warn: 'warn',
+    Error: 'error',
+    Critical: 'critical',
+});
+export const AuditOutcome = defineEnum('AuditOutcome', {
+    Pending: 'pending',
+    Success: 'success',
+    Cancelled: 'cancelled',
+    Failure: 'failure',
+    Denied: 'denied',
+});
+export const ActorType = defineEnum('ActorType', {
+    User: 'user',
+    System: 'system',
+    ApiKey: 'api-key',
+});

package/logger/logger.js

@@ -89,7 +89,7 @@ Logger = Logger_1 = __decorate([
 export { Logger };
 function moduleFromArgument(argument) {
     if (isString(argument)) {
-        return toArray(argument);
+        return [argument];
     }
     if (isArray(argument)) {
         return argument;

package/logger/manager.d.ts

@@ -13,8 +13,8 @@ export declare class LogManager {
     /**
      * Gets the effective log level for a given module path.
      * It finds the most specific rule matching the module path.
-     * @param modulePath Array of module names, e.g., ['Api', 'Users']
+     * @param module Array of module names, e.g., ['Api', 'Users']
      * @returns The effective log level
      */
-    getModuleLevel(modulePath?: string | string[]): LogLevel;
+    getModuleLevel(module?: string | string[]): LogLevel;
 }

package/logger/manager.js

@@ -18,7 +18,16 @@ let LogManager = class LogManager {
     log(payload) {
         for (const transport of this.#transports) {
             if (payload.level <= transport.level) {
-                transport.log(payload);
+                try {
+                    transport.log(payload);
+                }
+                catch (err) {
+                    try {
+                        const transportName = transport.constructor?.name ?? 'UnknownTransport';
+                        console.error(`[LogTransport Error] transport=${transportName} error=`, err, 'payload=', payload);
+                    }
+                    catch { /* swallow to avoid cascading failures. */ }
+                }
             }
         }
     }
@@ -42,14 +51,14 @@ let LogManager = class LogManager {
     /**
      * Gets the effective log level for a given module path.
      * It finds the most specific rule matching the module path.
-     * @param modulePath Array of module names, e.g., ['Api', 'Users']
+     * @param module Array of module names, e.g., ['Api', 'Users']
      * @returns The effective log level
      */
-    getModuleLevel(modulePath) {
-        if (!isDefined(modulePath) || (modulePath.length == 0)) {
+    getModuleLevel(module) {
+        if (!isDefined(module) || (module.length == 0)) {
             return this.#defaultLevel;
         }
-        const path = Array.isArray(modulePath) ? modulePath.join('.') : modulePath;
+        const path = Array.isArray(module) ? module.join('.') : module;
         const cachedLevel = this.#moduleLevelCache.get(path);
         if (isDefined(cachedLevel)) {
             return cachedLevel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.92.168",
+  "version": "0.93.0",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -11,7 +11,7 @@
     "build:watch": "concurrently --raw --kill-others npm:tsc:watch npm:tsc-alias:watch",
     "build:production": "rm -rf dist && npm run build && npm run build:production:copy-files",
     "build:production:copy-files": "cp package.json eslint.config.js tsconfig.server.json dist/ && cp tsconfig.base.json dist/tsconfig.json && npm run copy:orm",
-    "build:dts": "rm -rf dist && tsc -p tsconfig.dts.json",
+    "build:dts": "rm -rf dist && tsc -p tsconfig.dts.json && tsc-alias",
     "build:docs": "typedoc",
     "build:docs:watch": "typedoc --watch",
     "lint": "eslint --cache source/",
@@ -28,6 +28,7 @@
     "generate:migration:lock": "drizzle-kit generate --config dist/lock/postgres/drizzle.config.js",
     "generate:readmes": "deno run --allow-run=code2prompt --allow-read --allow-write=source --allow-net=generativelanguage.googleapis.com --allow-env=GEMINI_API_KEY generate-readmes.ts",
     "generate:readmes:new-only": "npm run generate:readmes -- --skip-existing",
+    "generate:llms.md": "npm run build:dts && npm run cleanup:dist && ./scripts/generate-llms-docs.sh",
     "generate:context7-docs": "npm run build:dts && npm run cleanup:dist && ./scripts/generate-context7-docs.sh",
     "copy:orm": "npm run copy:orm:document-management && npm run copy:orm:authentication && npm run copy:orm:mail && npm run copy:orm:queue && npm run copy:orm:key-value-store && npm run copy:orm:lock",
     "copy:orm:document-management": "rm -rf ./dist/document-management/server/drizzle && cp -r ./source/document-management/server/drizzle ./dist/document-management/server/",
@@ -143,7 +144,7 @@
   },
   "peerDependencies": {
     "@google-cloud/storage": "^7.17",
-    "@google/genai": "^1.17",
+    "@google/genai": "^1.19",
     "@tstdl/angular": "^0.92",
     "@zxcvbn-ts/core": "^3.0",
     "@zxcvbn-ts/language-common": "^3.0",
@@ -160,7 +161,7 @@
     "preact": "^10.27",
     "preact-render-to-string": "^6.6",
     "sharp": "^0.34",
-    "undici": "^7.15",
+    "undici": "^7.16",
     "urlpattern-polyfill": "^10.1"
   },
   "peerDependenciesMeta": {
@@ -179,14 +180,14 @@
     "@types/pg": "8.15",
     "concurrently": "9.2",
     "drizzle-kit": "0.31",
-    "eslint": "9.34",
-    "globals": "16.3",
+    "eslint": "9.35",
+    "globals": "16.4",
     "tsc-alias": "1.8",
     "typedoc-github-wiki-theme": "2.1",
     "typedoc-plugin-markdown": "4.8",
     "typedoc-plugin-missing-exports": "4.1",
     "typescript": "5.9",
-    "typescript-eslint": "8.42"
+    "typescript-eslint": "8.43"
   },
   "overrides": {
     "drizzle-kit": {

package/utils/function/memoize.d.ts

@@ -17,20 +17,35 @@ export declare function memoizeSingle<Fn extends (parameter: any) => any>(fn: Fn
 export declare function memoizeClass<T extends Constructor>(type: T, options?: MemoizeOptions): (...parameters: ConstructorParameters<T>) => InstanceType<T>;
 export declare function memoizeClassSingle<T extends Constructor<any, [any]>>(type: T, options?: MemoizeOptions): (...parameters: ConstructorParameters<T>) => InstanceType<T>;
 /**
- * Memoizes an accessor (getter)
+ * Memoizes the result of a class getter, ensuring the getter's logic is
+ * executed only once per instance.
+ *
+ * Subsequent accesses to the getter will return the cached value.
+ *
+ * @param strategy The memoization strategy to use.
+ * - `attach`: (Default) Uses `Symbol` properties to store the cached value directly on the class instance. This is generally faster but adds hidden properties to the instance.
+ * - `weak-map`: Uses a `WeakMap` to store the cached value, with the class instance as the key. This avoids adding any properties to the instance, keeping it "clean".
  *
  * @example
  * ```typescript
- * class MyClass {
+ * class MyEvaluator {
  *   @Memoize()
- *   get myValue() {
- *     // expensive calculation
- *     return 123;
+ *   get result() {
+ *     // This expensive result creation only happens once per instance.
+ *     return this.computeExpensiveResult();
  *   }
  * }
+ *
+ * const service = new MyEvaluator();
+ * const s1 = service.result; // Logs "Creating new result..."
+ * const s2 = service.result; // Does not log anything, returns cached result.
+ * console.log(s1 === s2); // true
  * ```
  *
  * @remarks
- * The getter will be called only once for each instance of the class.
+ * If the decorated property has a corresponding setter, calling the setter will
+ * invalidate the cache. The getter will be re-evaluated on its next access.
+ *
+ * @returns An accessor decorator function.
  */
-export declare function Memoize(): MethodDecorator;
+export declare function Memoize(strategy?: 'attach' | 'weak-map'): MethodDecorator;

package/utils/function/memoize.js

@@ -1,7 +1,8 @@
 import { IterableWeakMap } from '../../data-structures/iterable-weak-map.js';
 import { MultiKeyMap } from '../../data-structures/multi-key-map.js';
 import { createAccessorDecorator } from '../../reflection/index.js';
-import { assertDefinedPass, isDefined } from '../type-guards.js';
+import { assertDefinedPass, isDefined } from '../../utils/type-guards.js';
+import { hasOwnProperty } from '../object/object.js';
 /**
  * Memoizes a function with an arbitrary number of parameters. If you only need a single parameter, {@link memoizeSingle} is faster
  * @param fn function memoize
@@ -46,47 +47,105 @@ export function memoizeClassSingle(type, options = {}) {
     return memoizeSingle((parameter) => new type(parameter), options);
 }
 /**
- * Memoizes an accessor (getter)
+ * Memoizes the result of a class getter, ensuring the getter's logic is
+ * executed only once per instance.
+ *
+ * Subsequent accesses to the getter will return the cached value.
+ *
+ * @param strategy The memoization strategy to use.
+ * - `attach`: (Default) Uses `Symbol` properties to store the cached value directly on the class instance. This is generally faster but adds hidden properties to the instance.
+ * - `weak-map`: Uses a `WeakMap` to store the cached value, with the class instance as the key. This avoids adding any properties to the instance, keeping it "clean".
  *
  * @example
  * ```typescript
- * class MyClass {
+ * class MyEvaluator {
  *   @Memoize()
- *   get myValue() {
- *     // expensive calculation
- *     return 123;
+ *   get result() {
+ *     // This expensive result creation only happens once per instance.
+ *     return this.computeExpensiveResult();
  *   }
  * }
+ *
+ * const service = new MyEvaluator();
+ * const s1 = service.result; // Logs "Creating new result..."
+ * const s2 = service.result; // Does not log anything, returns cached result.
+ * console.log(s1 === s2); // true
  * ```
  *
  * @remarks
- * The getter will be called only once for each instance of the class.
+ * If the decorated property has a corresponding setter, calling the setter will
+ * invalidate the cache. The getter will be re-evaluated on its next access.
+ *
+ * @returns An accessor decorator function.
  */
-export function Memoize() {
-    const cache = new WeakMap();
+export function Memoize(strategy = 'attach') {
     return createAccessorDecorator({
         handler: (data) => {
             const getter = assertDefinedPass(data.descriptor.get, 'Memoize requires an getter for accessors.'); // eslint-disable-line @typescript-eslint/unbound-method
             const setter = data.descriptor.set; // eslint-disable-line @typescript-eslint/unbound-method
-            function cachedGetter() {
-                if (cache.has(this)) {
-                    return cache.get(this); // eslint-disable-line @typescript-eslint/no-unsafe-return
-                }
-                const value = getter.call(this);
-                cache.set(this, value);
-                return value; // eslint-disable-line @typescript-eslint/no-unsafe-return
+            if (strategy == 'attach') {
+                return createAttachMemoizeHandler(data.propertyKey, getter, setter);
             }
-            function cachedSetter(value) {
-                setter?.call(this, value);
-                cache.delete(this);
+            else {
+                return createWeakMapMemoizeHandler(getter, setter);
             }
-            return {
-                get: cachedGetter,
-                set: isDefined(setter) ? cachedSetter : undefined,
-            };
+            ;
         },
     });
 }
+function createAttachMemoizeHandler(propertyKey, getter, setter) {
+    const stateKey = Symbol(`memoization[${String(propertyKey)}]`);
+    function getState(instance) {
+        if (!hasOwnProperty(instance, stateKey)) {
+            Object.defineProperty(instance, stateKey, {
+                value: { hasValue: false, value: undefined },
+                writable: false,
+                configurable: true,
+                enumerable: false,
+            });
+        }
+        return instance[stateKey];
+    }
+    function cachedGetter() {
+        const state = getState(this);
+        if (state.hasValue) {
+            return state.value;
+        }
+        const value = getter.call(this);
+        state.hasValue = true;
+        state.value = value;
+        return value;
+    }
+    function cachedSetter(value) {
+        setter.call(this, value);
+        if (hasOwnProperty(this, stateKey)) {
+            this[stateKey].hasValue = false;
+            this[stateKey].value = undefined;
+        }
+    }
+    return {
+        get: cachedGetter,
+        set: isDefined(setter) ? cachedSetter : undefined,
+    };
+}
+function createWeakMapMemoizeHandler(getter, setter) {
+    const cache = new WeakMap();
+    function cachedGetter() {
+        if (cache.has(this)) {
+            return cache.get(this);
+        }
+        const value = getter.call(this);
+        cache.set(this, value);
+        return value;
+    }
+    ;
+    function cachedSetter(value) {
+        setter.call(this, value);
+        cache.delete(this);
+    }
+    ;
+    return { get: cachedGetter, set: isDefined(setter) ? cachedSetter : undefined };
+}
 function getMemoizedName(fn) {
     return `memoized${fn.name[0]?.toUpperCase() ?? ''}${fn.name.slice(1)}`;
 }