@tstdl/base 0.92.167 → 0.93.0

package/orm/decorators.js

@@ -145,3 +145,11 @@ export function Index(columnsOrOptions, options) {
     }
     return createColumnDecorator({ index: { options: columnsOrOptions } });
 }
+/**
+ * Decorator to mark a column as an expiration field. This will be used to automatically delete records when expired.
+ * @param mode - Whether to delete soft or hard.
+ * @returns A property decorator.
+ */
+export function ExpiresAt(mode = 'soft') {
+    return createColumnDecorator({ expirationField: { mode } });
+}

package/orm/server/repository.d.ts

@@ -1,6 +1,6 @@
 import { SQL } from 'drizzle-orm';
 import type { PgColumn, PgInsertValue, PgUpdateSetSource } from 'drizzle-orm/pg-core';
-import { type Resolvable, resolveArgumentType } from '../../injector/interfaces.js';
+import { afterResolve, type Resolvable, resolveArgumentType } from '../../injector/interfaces.js';
 import type { DeepPartial, OneOrMany, Paths, Type, UntaggedDeep } from '../../types/index.js';
 import { Entity, type EntityMetadataAttributes, type EntityType, type EntityWithoutMetadata } from '../entity.js';
 import type { Query } from '../query.js';
@@ -37,6 +37,8 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
      */
     get table(): PgTableFromType<EntityType<T>>;
     readonly [resolveArgumentType]: EntityType<T>;
+    [afterResolve](): void;
+    private expirationLoop;
     protected getTransactionalContextData(): EntityRepositoryContext;
     /**
      * Loads a single entity by its ID.

package/orm/server/repository.js

@@ -4,20 +4,24 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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;
 };
-import { and, asc, count, desc, eq, inArray, isNull, isSQLWrapper, SQL, sql } from 'drizzle-orm';
+import { and, asc, count, desc, eq, inArray, isNull, isSQLWrapper, lte, or, SQL, sql } from 'drizzle-orm';
 import { match } from 'ts-pattern';
+import { CancellationSignal } from '../../cancellation/token.js';
 import { NotFoundError } from '../../errors/not-found.error.js';
 import { Singleton } from '../../injector/decorators.js';
 import { inject, injectArgument } from '../../injector/inject.js';
-import { resolveArgumentType } from '../../injector/interfaces.js';
+import { afterResolve, resolveArgumentType } from '../../injector/interfaces.js';
 import { Schema } from '../../schema/schema.js';
 import { distinct, toArray } from '../../utils/array/array.js';
 import { mapAsync } from '../../utils/async-iterable-helpers/map.js';
 import { toArrayAsync } from '../../utils/async-iterable-helpers/to-array.js';
 import { importSymmetricKey } from '../../utils/cryptography.js';
 import { fromDeepObjectEntries, fromEntries, objectEntries } from '../../utils/object/object.js';
-import { assertDefinedPass, isArray, isDefined, isString, isUndefined } from '../../utils/type-guards.js';
+import { cancelableTimeout } from '../../utils/timing.js';
+import { tryIgnoreAsync } from '../../utils/try-ignore.js';
+import { assertDefined, assertDefinedPass, isArray, isDefined, isString, isUndefined } from '../../utils/type-guards.js';
 import { typeExtends } from '../../utils/type/index.js';
+import { millisecondsPerSecond } from '../../utils/units.js';
 import { Entity } from '../entity.js';
 import { TRANSACTION_TIMESTAMP } from '../sqls.js';
 import { getColumnDefinitions, getColumnDefinitionsMap, getDrizzleTableFromType } from './drizzle/schema-converter.js';
@@ -37,6 +41,7 @@ const entityTypeToken = Symbol('EntityType');
 let EntityRepository = class EntityRepository extends Transactional {
     #context = isInTransactionalContext() ? getTransactionalContextData(this) : {};
     #encryptionSecret = isInTransactionalContext() ? this.#context.encryptionSecret : inject(ENCRYPTION_SECRET, undefined, { optional: true });
+    #cancellationSignal = isInTransactionalContext() ? undefined : inject(CancellationSignal);
     #transformContext = this.#context.transformContext;
     type = this.#context.type ?? injectArgument(this, { optional: true }) ?? assertDefinedPass(this.constructor[entityTypeToken], 'Missing entity type.');
     typeName = this.type.entityName ?? this.type.name;
@@ -51,6 +56,30 @@ let EntityRepository = class EntityRepository extends Transactional {
     get table() {
         return this.#table;
     }
+    [afterResolve]() {
+        if (!this.isInTransaction) {
+            void this.expirationLoop();
+        }
+    }
+    async expirationLoop() {
+        const softExpirationColumns = this.#columnDefinitions.filter((column) => column.reflectionData?.expirationField?.mode == 'soft');
+        const hardExpirationColumns = this.#columnDefinitions.filter((column) => column.reflectionData?.expirationField?.mode == 'hard');
+        if ((softExpirationColumns.length + hardExpirationColumns.length) == 0) {
+            return;
+        }
+        const softDeletionQuery = or(...softExpirationColumns.map((column) => lte(this.getColumn(column), TRANSACTION_TIMESTAMP)));
+        const hardDeletionQuery = or(...hardExpirationColumns.map((column) => lte(this.getColumn(column), TRANSACTION_TIMESTAMP)));
+        assertDefined(this.#cancellationSignal);
+        while (this.#cancellationSignal.isUnset) {
+            if (isDefined(softDeletionQuery)) {
+                await tryIgnoreAsync(async () => await this.deleteManyByQuery(softDeletionQuery));
+            }
+            if (isDefined(hardDeletionQuery)) {
+                await tryIgnoreAsync(async () => await this.hardDeleteManyByQuery(hardDeletionQuery));
+            }
+            await cancelableTimeout(30 * millisecondsPerSecond, this.#cancellationSignal);
+        }
+    }
     getTransactionalContextData() {
         const context = {
             type: this.type,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.92.167",
+  "version": "0.93.0",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -11,27 +11,32 @@
     "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": "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/",
-    "pub": "npm run build:production && rm -vf dist/test* && rm -vrf dist/tools/ && npm publish dist/",
+    "pub": "npm run build:production && npm run cleanup:dist && npm publish dist/",
     "tsc:watch": "tsc --watch",
     "tsc-alias:watch": "tsc-alias --watch",
-    "generate:migration": "npm run generate:migration:document-management && npm run generate:migration:authentication && npm run generate:migration:mail && npm run generate:migration:queue && npm run generate:migration:key-value-store",
+    "cleanup:dist": "rm -vf dist/test* && rm -vrf dist/tools/",
+    "generate:migration": "npm run generate:migration:document-management && npm run generate:migration:authentication && npm run generate:migration:mail && npm run generate:migration:queue && npm run generate:migration:key-value-store && npm run generate:migration:lock",
     "generate:migration:document-management": "drizzle-kit generate --config dist/document-management/server/drizzle.config.js",
     "generate:migration:authentication": "drizzle-kit generate --config dist/authentication/server/drizzle.config.js",
     "generate:migration:mail": "drizzle-kit generate --config dist/mail/drizzle.config.js",
     "generate:migration:queue": "drizzle-kit generate --config dist/queue/postgres/drizzle.config.js",
     "generate:migration:key-value-store": "drizzle-kit generate --config dist/key-value-store/postgres/drizzle.config.js",
-    "generate:readmes": "deno run --allow-run=repomix --allow-read=source --allow-write=source --allow-net=generativelanguage.googleapis.com --allow-env=GEMINI_API_KEY generate-readmes.ts",
+    "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",
-    "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",
+    "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/",
     "copy:orm:authentication": "rm -rf ./dist/authentication/server/drizzle && cp -r ./source/authentication/server/drizzle ./dist/authentication/server/",
     "copy:orm:mail": "rm -rf ./dist/mail/drizzle && cp -r ./source/mail/drizzle ./dist/mail/",
     "copy:orm:queue": "rm -rf ./dist/queue/postgres/drizzle && cp -r ./source/queue/postgres/drizzle ./dist/queue/postgres/",
-    "copy:orm:key-value-store": "rm -rf ./dist/key-value-store/postgres/drizzle && cp -r ./source/key-value-store/postgres/drizzle ./dist/key-value-store/postgres/"
+    "copy:orm:key-value-store": "rm -rf ./dist/key-value-store/postgres/drizzle && cp -r ./source/key-value-store/postgres/drizzle ./dist/key-value-store/postgres/",
+    "copy:orm:lock": "rm -rf ./dist/lock/postgres/drizzle && cp -r ./source/lock/postgres/drizzle ./dist/lock/postgres/"
   },
   "exports": {
     "./tsconfig.json": "./tsconfig.json",
@@ -40,7 +45,6 @@
     "./environment": "./environment.js",
     "./interfaces": "./interfaces.js",
     "./polyfills": "./polyfills.js",
-    "./process-shutdown": "./process-shutdown.js",
     "./supports": "./supports.js",
     "./tokens": "./tokens.js",
     "./ai": "./ai/index.js",
@@ -55,8 +59,6 @@
     "./cookie": "./cookie/index.js",
     "./css": "./css/index.js",
     "./data-structures": "./data-structures/index.js",
-    "./database": "./database/index.js",
-    "./database/mongo": "./database/mongo/index.js",
     "./decorators": "./decorators/index.js",
     "./disposable": "./disposable/index.js",
     "./distributed-loop": "./distributed-loop/index.js",
@@ -79,10 +81,9 @@
     "./json-path": "./json-path/index.js",
     "./jsx": "./jsx/index.js",
     "./key-value-store": "./key-value-store/index.js",
-    "./key-value-store/mongo": "./key-value-store/mongo/index.js",
     "./key-value-store/postgres": "./key-value-store/postgres/index.js",
     "./lock": "./lock/index.js",
-    "./lock/mongo": "./lock/mongo/index.js",
+    "./lock/postgres": "./lock/postgres/index.js",
     "./lock/web": "./lock/web/index.js",
     "./logger": "./logger/index.js",
     "./mail": "./mail/index.js",
@@ -100,7 +101,6 @@
     "./process": "./process/index.js",
     "./promise": "./promise/index.js",
     "./queue": "./queue/index.js",
-    "./queue/mongo": "./queue/mongo/index.js",
     "./queue/postgres": "./queue/postgres/index.js",
     "./random": "./random/index.js",
     "./reflection": "./reflection/index.js",
@@ -109,9 +109,6 @@
     "./rxjs-utils": "./rxjs-utils/index.js",
     "./schema": "./schema/index.js",
     "./schema/converters": "./schema/converters/index.js",
-    "./search-index": "./search-index/index.js",
-    "./search-index/elastic": "./search-index/elastic/index.js",
-    "./search-index/memory": "./search-index/memory/index.js",
     "./serializer": "./serializer/index.js",
     "./serializer/handlers": "./serializer/handlers/index.js",
     "./signals": "./signals/index.js",
@@ -123,8 +120,6 @@
     "./templates/resolvers": "./templates/resolvers/index.js",
     "./templates/types": "./templates/types/index.js",
     "./text": "./text/index.js",
-    "./theme": "./theme/index.js",
-    "./theme/adapters": "./theme/adapters/index.js",
     "./threading": "./threading/index.js",
     "./types": "./types/index.js",
     "./utils": "./utils/index.js",
@@ -148,28 +143,25 @@
     "type-fest": "4.37"
   },
   "peerDependencies": {
-    "@elastic/elasticsearch": "^9.1",
     "@google-cloud/storage": "^7.17",
-    "@google/genai": "^1.15",
+    "@google/genai": "^1.19",
     "@tstdl/angular": "^0.92",
     "@zxcvbn-ts/core": "^3.0",
     "@zxcvbn-ts/language-common": "^3.0",
     "@zxcvbn-ts/language-de": "^3.0",
     "@zxcvbn-ts/language-en": "^3.0",
-    "chroma-js": "^2.6",
     "drizzle-orm": "^0.44",
     "file-type": "^21.0",
     "handlebars": "^4.7",
     "minio": "^8.0",
     "mjml": "^4.15",
-    "mongodb": "^6.18",
     "nodemailer": "^7.0",
     "pg": "^8.16",
     "playwright": "^1.55",
     "preact": "^10.27",
     "preact-render-to-string": "^6.6",
     "sharp": "^0.34",
-    "undici": "^7.14",
+    "undici": "^7.16",
     "urlpattern-polyfill": "^10.1"
   },
   "peerDependenciesMeta": {
@@ -178,8 +170,7 @@
     }
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin": "5.2",
-    "@types/chroma-js": "2.4",
+    "@stylistic/eslint-plugin": "5.3",
     "@types/koa__router": "12.0",
     "@types/luxon": "3.7",
     "@types/minio": "7.1",
@@ -189,15 +180,14 @@
     "@types/pg": "8.15",
     "concurrently": "9.2",
     "drizzle-kit": "0.31",
-    "eslint": "9.33",
-    "globals": "16.3",
-    "repomix": "1.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.40"
+    "typescript-eslint": "8.43"
   },
   "overrides": {
     "drizzle-kit": {

package/pdf/pdf.service.js

@@ -24,7 +24,7 @@ import { finalizeStream } from '../utils/stream/finalize-stream.js';
 import { readableStreamFromPromise } from '../utils/stream/from-promise.js';
 import { readBinaryStream } from '../utils/stream/stream-reader.js';
 import { timeout } from '../utils/timing.js';
-import { isDefined } from '../utils/type-guards.js';
+import { isDefined, isNumber } from '../utils/type-guards.js';
 export class PdfServiceRenderOptions extends PdfRenderOptions {
     browserContext;
     locale;
@@ -81,7 +81,7 @@ let PdfService = class PdfService {
      * @returns pdf stream
      */
     renderHtmlStream(html, options) {
-        return this.renderStream(async (page) => page.setContent(html), options);
+        return this.renderStream(async (page) => await page.setContent(html), options);
     }
     /**
      * Renders HTML to pdf
@@ -91,7 +91,7 @@ let PdfService = class PdfService {
      */
     async renderHtml(html, options) {
         const stream = this.renderHtmlStream(html, options);
-        return readBinaryStream(stream);
+        return await readBinaryStream(stream);
     }
     /**
      * Renders an url to pdf stream
@@ -112,7 +112,7 @@ let PdfService = class PdfService {
      */
     async renderUrl(url, options) {
         const stream = this.renderUrlStream(url, options);
-        return readBinaryStream(stream);
+        return await readBinaryStream(stream);
     }
     /**
      * Renders a template to pdf
@@ -137,15 +137,15 @@ let PdfService = class PdfService {
      */
     async renderTemplate(keyOrTemplate, templateContext, options) {
         const stream = this.renderTemplateStream(keyOrTemplate, templateContext, options);
-        return readBinaryStream(stream);
+        return await readBinaryStream(stream);
     }
     renderStream(handler, options = {}) {
         return readableStreamFromPromise(async () => {
             const context = options.browserContext ?? await this.browserController.newContext({ locale: options.locale ?? this.defaultLocale });
             const page = await context.newPage();
             if (isDefined(options.log) && (options.log != false)) {
-                const level = (options.log == true) ? LogLevel.Trace : options.log;
-                const logger = this.logger.fork({ level, subModule: 'PAGE' });
+                const level = isNumber(options.log) ? options.log : LogLevel.Trace;
+                const logger = this.logger.fork('PAGE', { level });
                 page.attachLogger(logger);
             }
             const optionsFromHandler = await handler(page);
@@ -165,7 +165,7 @@ let PdfService = class PdfService {
             return finalizeStream(pdfStream, {
                 beforeDone: close,
                 beforeCancel: close,
-                error: close
+                error: close,
             });
         });
     }
@@ -178,6 +178,6 @@ export function pdfTemplate(name, fields, options) {
     return {
         name,
         fields,
-        options
+        options,
     };
 }

package/pool/pool.d.ts

@@ -1,5 +1,3 @@
-import type { AsyncDisposable } from '../disposable/disposable.js';
-import { disposeAsync } from '../disposable/disposable.js';
 import type { Logger } from '../logger/index.js';
 export type PoolOptions = {
     /**
@@ -45,5 +43,5 @@ export declare class Pool<T extends object> implements AsyncDisposable {
     use<R>(handler: (instance: T) => R | Promise<R>, options?: PoolUseOptions): Promise<R>;
     disposeInstance(instance: T): Promise<void>;
     dispose(): Promise<void>;
-    [disposeAsync](): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/pool/pool.js

@@ -1,6 +1,5 @@
 import { ArrayList } from '../data-structures/array-list.js';
 import { SetCollection } from '../data-structures/set-collection.js';
-import { disposeAsync } from '../disposable/disposable.js';
 import { hardwareConcurrency } from '../environment.js';
 import { isDefined } from '../utils/type-guards.js';
 export class Pool {
@@ -57,7 +56,7 @@ export class Pool {
         while (!this.freeInstances.hasItems) {
             await this.freeInstances.$onItems;
         }
-        return this.get();
+        return await this.get();
     }
     async release(instance) {
         if (this.freeInstances.includes(instance)) {
@@ -110,9 +109,9 @@ export class Pool {
         await this.disposer(instance);
     }
     async dispose() {
-        return this[disposeAsync]();
+        await this[Symbol.asyncDispose]();
     }
-    async [disposeAsync]() {
+    async [Symbol.asyncDispose]() {
         this.disposed = true;
         if (this.length == 0) {
             return;

package/queue/postgres/job.model.d.ts

@@ -1,5 +1,4 @@
-import { EntityWithoutMetadata } from '../../orm/entity.js';
-import { Integer, Json, Timestamp } from '../../orm/index.js';
+import { EntityWithoutMetadata, Integer, Json, Timestamp } from '../../orm/index.js';
 import type { ObjectLiteral } from '../../types/index.js';
 import type { Job } from '../queue.js';
 export declare class PostgresJob<T extends ObjectLiteral = ObjectLiteral> extends EntityWithoutMetadata implements Job<T> {

package/queue/postgres/job.model.js

@@ -8,8 +8,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 import { Index, Table } from '../../orm/decorators.js';
-import { EntityWithoutMetadata } from '../../orm/entity.js';
-import { Integer, Json, Timestamp } from '../../orm/index.js';
+import { EntityWithoutMetadata, Integer, Json, Timestamp } from '../../orm/index.js';
 import { StringProperty } from '../../schema/index.js';
 let PostgresJob = class PostgresJob extends EntityWithoutMetadata {
     queue;

package/queue/postgres/module.js

@@ -24,6 +24,6 @@ export async function migratePostgresQueueSchema() {
     await migrate(database, {
         migrationsSchema: 'queue',
         migrationsTable: '_migrations',
-        migrationsFolder: import.meta.resolve('./drizzle').replace('file://', '')
+        migrationsFolder: import.meta.resolve('./drizzle').replace('file://', ''),
     });
 }

package/threading/thread-pool.d.ts

@@ -1,7 +1,5 @@
 import type * as NodeWorkerThreads from 'node:worker_threads';
 import type { LiteralUnion } from 'type-fest';
-import type { AsyncDisposable } from '../disposable/index.js';
-import { disposeAsync } from '../disposable/index.js';
 import type { Logger } from '../logger/index.js';
 import type { ThreadWorker } from './thread-worker.js';
 export type ThreadOptions = (WorkerOptions | NodeWorkerThreads.WorkerOptions) & {
@@ -13,7 +11,7 @@ export declare class ThreadPool implements AsyncDisposable {
     readonly options: ThreadOptions | undefined;
     constructor(url: string | URL, logger: Logger, options?: ThreadOptions);
     dispose(): Promise<void>;
-    [disposeAsync](): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     getProcessor<T extends ThreadWorker>(name?: string): (...args: Parameters<T>) => Promise<ReturnType<T>>;
     process<T extends ThreadWorker>(name: LiteralUnion<'default', string>, ...args: Parameters<T>): Promise<ReturnType<T>>;
     private spawn;

package/threading/thread-pool.js

@@ -1,4 +1,3 @@
-import { disposeAsync } from '../disposable/index.js';
 import { isNode } from '../environment.js';
 import { dynamicImport } from '../import.js';
 import { Pool } from '../pool/index.js';
@@ -9,7 +8,7 @@ if (isNode) {
     spawnWorker = async (url, options) => {
         const workerThreads = await dynamicImport('node:worker_threads');
         spawnWorker = () => new workerThreads.Worker(url, options);
-        return spawnWorker(url, options);
+        return await spawnWorker(url, options);
     };
 }
 else {
@@ -22,26 +21,26 @@ export class ThreadPool {
     constructor(url, logger, options) {
         this.url = url;
         this.options = options;
-        this.pool = new Pool(async () => this.spawn(), async ({ worker }) => worker.terminate(), logger, { size: options?.threadCount });
+        this.pool = new Pool(async () => await this.spawn(), async ({ worker }) => await worker.terminate(), logger, { size: options?.threadCount });
     }
     async dispose() {
-        return this[disposeAsync]();
+        await this[Symbol.asyncDispose]();
     }
-    async [disposeAsync]() {
+    async [Symbol.asyncDispose]() {
         await this.pool.dispose();
     }
     getProcessor(name = 'default') {
-        const processor = async (...args) => this.process(name, ...args);
+        const processor = async (...args) => await this.process(name, ...args);
         return processor;
     }
     async process(name, ...args) {
-        return this.pool.use(async (entry) => {
+        return await this.pool.use(async (entry) => {
             if (!entry.remotes.has(name)) {
                 const rpcEndpoint = MessagePortRpcEndpoint.from(entry.worker);
                 const remote = await Rpc.connect(rpcEndpoint, `thread-worker:${name}`);
                 entry.remotes.set(name, remote);
             }
-            return entry.remotes.get(name)(...args);
+            return await entry.remotes.get(name)(...args);
         });
     }
     async spawn() {

package/utils/format-error.d.ts

@@ -16,9 +16,16 @@ export type FormatErrorOptions = {
      * Include stack trace
      */
     includeStack?: boolean;
+    /**
+     * Maximum recursion depth for nested causes and aggregate errors (default: 5)
+     */
+    depth?: number;
 };
 export interface ErrorExtraInfo {
     /** Format extra data (without message and stack) as JSON */
     getExtraInfo(): UndefinableJson | undefined;
 }
+/**
+ * Enhanced error formatting
+ */
 export declare function formatError(error: any, options?: FormatErrorOptions): string;

package/utils/format-error.js

@@ -1,35 +1,77 @@
 import { unwrapError } from '../errors/utils.js';
 import { decycle } from './object/decycle.js';
 import { objectKeys } from './object/object.js';
-import { isDefined, isFunction, isUndefined } from './type-guards.js';
+import { tryChain } from './try-chain.js';
+import { isDefined, isFunction, isObject, isUndefined } from './type-guards.js';
+/**
+ * Enhanced error formatting
+ */
 export function formatError(error, options = {}) {
-    const { includeRest = 'if-no-extra-info', includeExtraInfo = true, includeStack = true } = options;
+    const { includeName = true, includeRest = 'if-no-extra-info', includeExtraInfo = true, includeStack = true, depth = 5, } = options;
+    if (depth <= 0) {
+        return '[Max recursion depth reached]';
+    }
+    const actualError = unwrapError(error);
     let name;
     let message;
     let stack;
     let rest;
     let extraInfo;
-    const actualError = unwrapError(error);
-    if ((actualError instanceof Error)) {
-        ({ name, message, stack, ...rest } = actualError);
-        // eslint-disable-next-line @typescript-eslint/unbound-method
-        if (includeExtraInfo && isFunction(actualError.getExtraInfo)) {
+    let cause;
+    let aggregateErrors;
+    if (isObject(actualError)) {
+        if (actualError instanceof Error) {
+            ({ name, message, stack, cause, ...rest } = actualError);
+            if (actualError instanceof AggregateError) {
+                aggregateErrors = actualError.errors;
+            }
+        }
+        else {
+            // Handle plain objects that might have error-like properties
+            ({ name, message, stack, cause, ...rest } = actualError);
+        }
+        // Check for extra info (duck-typing)
+        if (includeExtraInfo && isFunction(actualError.getExtraInfo)) { // eslint-disable-line @typescript-eslint/unbound-method
             extraInfo = actualError.getExtraInfo();
         }
     }
-    if (isUndefined(name) && (isUndefined(message) || message.trim().length == 0)) {
-        try {
-            const decycledError = decycle(actualError);
-            message = JSON.stringify(decycledError, null, 2);
+    // If no message, serialize the whole object as a fallback
+    if (isUndefined(message) || String(message).trim().length === 0) { // eslint-disable-line @typescript-eslint/no-unnecessary-type-conversion
+        // Handle primitives directly
+        if (!isObject(actualError)) {
+            message = String(actualError);
         }
-        catch {
-            throw actualError;
+        else {
+            message = tryChain([
+                () => JSON.stringify(actualError, null, 2), // Try normal serialization first
+                () => {
+                    // Fallback with decycle for objects with circular references
+                    const decycledError = decycle(actualError);
+                    return JSON.stringify(decycledError, null, 2);
+                },
+                // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                () => `[Unstringifiable object: ${String(actualError)}]`, // Safe fallback if JSON.stringify still fails
+            ]);
         }
     }
-    const nameString = (options.includeName ?? true) ? `${name ?? 'Error'}: ` : '';
-    const decycledRest = isDefined(rest) ? decycle(rest) : undefined;
-    const restString = (((includeRest == true) || ((includeRest == 'if-no-extra-info') && isUndefined(extraInfo))) && isDefined(decycledRest) && (objectKeys(rest ?? {}).length > 0)) ? `\n${JSON.stringify(decycledRest, null, 2)}` : '';
+    // --- String Assembly ---
+    const nameString = includeName ? `${name ?? 'Error'}: ` : '';
+    let restString = '';
+    const shouldIncludeRest = (includeRest == true) || (includeRest == 'if-no-extra-info' && isUndefined(extraInfo));
+    if (shouldIncludeRest && isDefined(rest) && objectKeys(rest).length > 0) {
+        restString = `\n${JSON.stringify(decycle(rest), null, 2)}`;
+    }
     const extraInfoString = isDefined(extraInfo) ? `\n${JSON.stringify(extraInfo, null, 2)}` : '';
     const stackString = (includeStack && isDefined(stack)) ? `\n${stack}` : '';
-    return `${nameString}${message}${restString}${extraInfoString}${stackString}`;
+    const causeString = includeStack && cause
+        ? formatNestedError('Caused by:', cause, { ...options, depth: depth - 1 })
+        : '';
+    const aggregateErrorsString = Array.isArray(aggregateErrors)
+        ? aggregateErrors.map((err, i) => formatNestedError(`Sub-error #${i + 1}:`, err, { ...options, depth: depth - 1 })).join('')
+        : '';
+    return `${nameString}${message}${restString}${extraInfoString}${stackString}${causeString}${aggregateErrorsString}`;
+}
+function formatNestedError(prefix, error, options) {
+    const formatted = formatError(error, options).replace(/\n/g, '\n  ');
+    return `\n\n${prefix}\n  ${formatted}`;
 }

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;