zibri 2.3.0 → 2.4.1

package/src/change-sets/models/change-set-entity.model.ts

@@ -1,5 +1,6 @@
 import { ChangeSet } from './change-set.model';
 import { BaseEntity } from '../../entity/base-entity.model';
+import { Property } from '../../entity/decorators/property.decorator';
 import { Newable } from '../../types/newable.type';
 import { MetadataUtilities } from '../../utilities/metadata.utilities';
 
@@ -7,12 +8,13 @@ import { MetadataUtilities } from '../../utilities/metadata.utilities';
  * An entity that can be handled by the ChangeSetRepository.
  * Has an uuid id and a relation to all its changeSets.
  */
-export type ChangeSetEntity = BaseEntity & {
+export class ChangeSetEntity extends BaseEntity {
     /**
      * The change sets of the entity.
      */
-    changeSets: ChangeSet[]
-};
+    @Property.oneToMany({ target: () => ChangeSet, inverseSide: 'changeSetEntityId' })
+    changeSets!: ChangeSet[];
+}
 
 /**
  * Checks whether the given class is a ChangeSetEntity class.
@@ -20,5 +22,5 @@ export type ChangeSetEntity = BaseEntity & {
  * @returns True if it has a changeSets property of type array.
  */
 export function isChangeSetEntityNewable(cls: Newable<unknown>): cls is Newable<ChangeSetEntity> {
-    return MetadataUtilities.getModelProperties(cls)['changeSets']?.type === 'array';
+    return MetadataUtilities.getModelProperties(cls)['changeSets'] !== undefined;
 }

package/src/change-sets/models/change-set.model.ts

@@ -10,7 +10,7 @@ import { OmitStrict } from '../../types/omit-strict.type';
  * A single change set.
  * Gets automatically created for configured entities whenever they are changed.
  */
-@Entity()
+@Entity({ defaultOrder: { createdAt: 'ASC' }, defaultRelations: { changes: true } })
 export class ChangeSet extends BaseEntity {
     /**
      * Whether this change set was initialized on creating, updating or deleting the entity.
@@ -18,10 +18,10 @@ export class ChangeSet extends BaseEntity {
     @Property.string({ enum: ChangeSetType })
     type!: ChangeSetType;
     /**
-     * The time at which the change happened.
+     * The time at which the change happened with nanosecond precision.
      */
-    @Property.date()
-    createdAt!: Date;
+    @Property.number({ format: 'bigint' })
+    createdAt!: bigint;
     /**
      * The id of the user that changed something.
      */

package/src/change-sets/models/change.model.ts

@@ -27,8 +27,13 @@ export class Change<T = unknown> extends BaseEntity {
     /**
      * The change set that this change belongs to.
      */
-    @Property.manyToOne({ target: () => ChangeSet, inverseSide: 'changes', required: false })
+    @Property.manyToOne({ target: () => ChangeSet, inverseSide: 'changes', joinColumn: 'changeSetId' })
     changeSet!: ChangeSet;
+    /**
+     * The id of the change set that this change belongs to.
+     */
+    @Property.string({ format: 'uuid' })
+    changeSetId!: string;
 }
 
 /**
@@ -39,4 +44,4 @@ export type CreateChangeData = OmitStrict<Change, 'id'>;
 /**
  * A new change.
  */
-export type NewChange = OmitStrict<Change, 'id' | 'changeSet'>;
+export type NewChange = OmitStrict<Change, 'id' | 'changeSetId' | 'changeSet'>;

package/src/change-sets/models/soft-delete-entity.model.ts

@@ -1,4 +1,5 @@
 import { ChangeSetEntity, isChangeSetEntityNewable } from './change-set-entity.model';
+import { Property } from '../../entity/decorators/property.decorator';
 import { Newable } from '../../types/newable.type';
 import { MetadataUtilities } from '../../utilities/metadata.utilities';
 
@@ -6,12 +7,13 @@ import { MetadataUtilities } from '../../utilities/metadata.utilities';
  * An entity that can be handled by the SoftDeleteRepository.
  * Has an uuid id, a relation to all its changeSets and a flag that determines whether it is "soft deleted" or not.
  */
-export type SoftDeleteEntity = ChangeSetEntity & {
+export class SoftDeleteEntity extends ChangeSetEntity {
     /**
      * Whether or not the entity is soft deleted.
      */
-    deleted: boolean
-};
+    @Property.boolean({ default: false })
+    deleted!: boolean;
+}
 
 /**
  * Checks whether the given class is a SoftDeleteEntity class.

package/src/change-sets/soft-delete-repository.test.ts

@@ -0,0 +1,326 @@
+import assert from 'node:assert';
+
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from '@jest/globals';
+
+import { ChangeSetType } from './models/change-set-type.enum';
+import { ChangeSet, CreateChangeSetData } from './models/change-set.model';
+import { Change } from './models/change.model';
+import { SoftDeleteEntity } from './models/soft-delete-entity.model';
+import { SoftDeleteWhere } from './models/soft-delete-where.model';
+import { SoftDeleteRepository } from './soft-delete-repository';
+import { Roles } from '../__testing__/mocks/entities/roles.enum';
+import { createTestDataSource, defaultTestServerEntities } from '../__testing__/test-server/create-test-data-source.function';
+import { startTestServer, StartedTestServer } from '../__testing__/test-server/start-test-server.function';
+import { DefaultTestServerUserRepository } from '../__testing__/test-server/user-repository';
+import { AuthServiceInterface } from '../auth/auth-service.interface';
+import { Auth } from '../auth/decorators/auth.decorator';
+import { BaseUserEntity } from '../auth/models/base-user.model';
+import { JwtAuthData } from '../auth/strategies/jwt/jwt-auth-data.model';
+import { JwtCredentials } from '../auth/strategies/jwt/jwt-credentials.model';
+import { JwtAuthStrategy } from '../auth/strategies/jwt/jwt.auth-strategy';
+import { Repository } from '../data-source/repository';
+import { InjectRepository, repositoryTokenFor } from '../di/decorators/inject-repository.decorator';
+import { ZIBRI_DI_TOKENS } from '../di/default/zibri-di-tokens.default';
+import { inject } from '../di/inject.function';
+import { Entity } from '../entity/decorators/entity.decorator';
+import { Property } from '../entity/decorators/property.decorator';
+import { OmitClass } from '../entity/omit-class.model';
+import { PartialClass } from '../entity/partial-class.model';
+import { Body } from '../routing/decorators/body.decorator';
+import { Controller } from '../routing/decorators/controller.decorator';
+import { Delete } from '../routing/decorators/delete.decorator';
+import { Get } from '../routing/decorators/get.decorator';
+import { Param } from '../routing/decorators/param.decorator';
+import { Patch } from '../routing/decorators/patch.decorator';
+import { Post } from '../routing/decorators/post.decorator';
+import { JsonUtilities } from '../utilities/json.utilities';
+
+// ---------- Test entity ----------
+@Entity()
+class Task extends SoftDeleteEntity {
+    @Property.string()
+    title!: string;
+}
+
+class CreateTaskDto extends OmitClass(Task, ['changeSets', 'id', 'deleted']) {}
+class UpdateTaskDto extends PartialClass(OmitClass(Task, ['changeSets', 'id', 'deleted'])) {}
+
+@Entity()
+class TestUser extends BaseUserEntity(Roles) {
+    @Property.string({ hash: true })
+    password!: string;
+}
+
+// ---------- Controller ----------
+@Controller('/tasks')
+class TaskController {
+    constructor(
+        @InjectRepository(Task)
+        private readonly repo: SoftDeleteRepository<Task>
+    ) {}
+
+    @Post('/')
+    @Auth.isLoggedIn([JwtAuthStrategy])
+    async create(@Body(CreateTaskDto) body: CreateTaskDto): Promise<Task> {
+        return this.repo.create(body);
+    }
+
+    @Patch('/:id')
+    @Auth.isLoggedIn([JwtAuthStrategy])
+    async update(
+        @Param.path('id')
+        id: string,
+        @Body(UpdateTaskDto)
+        body: UpdateTaskDto,
+        @Param.query('withDeleted', { type: 'boolean', required: false })
+        withDeleted: boolean = false
+    ): Promise<Task> {
+        return this.repo.updateById(id, body, { withDeleted });
+    }
+
+    @Delete('/:id')
+    @Auth.isLoggedIn([JwtAuthStrategy])
+    async softDelete(@Param.path('id') id: string): Promise<Task> {
+        return this.repo.deleteById(id);
+    }
+
+    @Delete('/:id/hard')
+    @Auth.isLoggedIn([JwtAuthStrategy])
+    async hardDelete(@Param.path('id') id: string): Promise<Task> {
+        return this.repo.deleteById(id, { hardDelete: true });
+    }
+
+    @Get('/')
+    @Auth.isLoggedIn([JwtAuthStrategy])
+    async getAll(): Promise<Task[]> {
+        return this.repo.findAll();
+    }
+
+    @Get('/with-deleted')
+    @Auth.isLoggedIn([JwtAuthStrategy])
+    async getAllWithDeleted(): Promise<Task[]> {
+        return this.repo.findAll({ withDeleted: true });
+    }
+
+    @Get('/:id')
+    @Auth.isLoggedIn([JwtAuthStrategy])
+    async getById(@Param.path('id') id: string): Promise<Task> {
+        return this.repo.findById(id);
+    }
+}
+
+// ---------- Test setup ----------
+let server: StartedTestServer;
+let baseUrl: string;
+let accessToken: string;
+
+let changeSetRepo: Repository<ChangeSet, CreateChangeSetData>;
+let changeRepo: Repository<Change>;
+let taskRepo: SoftDeleteRepository<Task>;
+
+beforeAll(async () => {
+    server = await startTestServer({
+        dataSources: [
+            createTestDataSource({
+                entities: [...defaultTestServerEntities, Task, TestUser]
+            })
+        ],
+        controllers: [TaskController]
+    });
+    baseUrl = await server.start();
+
+    changeSetRepo = inject(repositoryTokenFor(ChangeSet));
+    changeRepo = inject(repositoryTokenFor(Change));
+    taskRepo = inject(repositoryTokenFor(Task)) as SoftDeleteRepository<Task>;
+
+    const userRepo: DefaultTestServerUserRepository = inject(DefaultTestServerUserRepository);
+    const credentialsRepo: Repository<JwtCredentials> = inject(repositoryTokenFor(JwtCredentials));
+
+    const testEmail: string = 'task-test@example.com';
+    const testPassword: string = 'test123';
+    await userRepo.create({ email: testEmail, roles: [Roles.USER] });
+    await credentialsRepo.create({
+        email: testEmail,
+        password: testPassword,
+        userId: (await userRepo.findOne({ where: { email: testEmail } }, true)).id
+    });
+
+    const authService: AuthServiceInterface = inject(ZIBRI_DI_TOKENS.AUTH_SERVICE);
+    const authData: JwtAuthData<Roles> = await authService.login(JwtAuthStrategy<Roles>, {
+        email: testEmail,
+        password: testPassword
+    });
+    accessToken = authData.accessToken.value;
+}, 15000);
+
+afterAll(async () => {
+    await server.shutdown();
+});
+
+beforeEach(async () => {
+    await changeSetRepo.deleteAll({});
+    await changeRepo.deleteAll({});
+    await taskRepo.deleteAll({}, { hardDelete: true });
+});
+
+async function authFetch(path: string, options: RequestInit = {}): Promise<Response> {
+    const res: Response = await fetch(`${baseUrl}${path}`, {
+        ...options,
+        headers: {
+            ...options.headers,
+            Authorization: `Bearer ${accessToken}`,
+            'Content-Type': 'application/json'
+        }
+    });
+    if (!res.ok) {
+        const body: unknown = await res.json();
+        throw new Error(`Request "${options.method ?? 'GET'} ${path}" failed:\n${JsonUtilities.stringify(body, undefined, 4)}`);
+    }
+    return res;
+}
+
+// ---------- Tests ----------
+describe('SoftDeleteRepository behavior', () => {
+    it('created task is not deleted', async () => {
+        const res: Response = await authFetch('/tasks', {
+            method: 'POST',
+            body: JSON.stringify({ title: 'Buy milk' })
+        });
+        const task: Task = await res.json() as Task;
+        expect(task.deleted).toBe(false);
+    });
+
+    describe('soft delete', () => {
+        let taskId: string;
+
+        beforeEach(async () => {
+            const res: Response = await authFetch('/tasks', {
+                method: 'POST',
+                body: JSON.stringify({ title: 'Temporary' })
+            });
+            const task: Task = await res.json() as Task;
+            taskId = task.id;
+        });
+
+        it('marks the entity as deleted and creates a DELETE change set', async () => {
+            await authFetch(`/tasks/${taskId}`, { method: 'DELETE' });
+
+            const tasks: Task[] = await taskRepo.findAll({ withDeleted: true });
+            const task: Task | undefined = tasks.find(t => t.id === taskId);
+            assert(task);
+            expect(task.deleted).toBe(true);
+
+            const changeSets: ChangeSet[] = await changeSetRepo.findAll({ where: { changeSetEntityId: taskId } });
+            expect(changeSets.some(cs => cs.type === ChangeSetType.DELETE)).toBe(true);
+        });
+
+        it('findById throws NotFoundError for soft-deleted task', async () => {
+            await authFetch(`/tasks/${taskId}`, { method: 'DELETE' });
+            await expect(taskRepo.findById(taskId)).rejects.toThrow('Could not find');
+        });
+
+        it('findById with withDeleted=true returns the task', async () => {
+            await authFetch(`/tasks/${taskId}`, { method: 'DELETE' });
+            const task: Task = await taskRepo.findById(taskId, { withDeleted: true });
+            expect(task.deleted).toBe(true);
+        });
+
+        it('soft-deleted task can be updated if withDeleted is passed', async () => {
+            await authFetch(`/tasks/${taskId}`, { method: 'DELETE' });
+            const params: URLSearchParams = new URLSearchParams({ withDeleted: 'true' });
+            // Update using the controller, which uses updateById with options that allow withDeleted
+            await authFetch(`/tasks/${taskId}?${params.toString()}`, {
+                method: 'PATCH',
+                body: JSON.stringify({ title: 'Still here' })
+            });
+        });
+    });
+
+    describe('hard delete', () => {
+        let taskId: string;
+
+        beforeEach(async () => {
+            const res: Response = await authFetch('/tasks', {
+                method: 'POST',
+                body: JSON.stringify({ title: 'To be removed' })
+            });
+            const task: Task = await res.json() as Task;
+            taskId = task.id;
+        });
+
+        it('removes the entity from the database', async () => {
+            await authFetch(`/tasks/${taskId}/hard`, { method: 'DELETE' });
+            await expect(taskRepo.findById(taskId)).rejects.toThrow('Could not find');
+        });
+    });
+
+    describe('findAll queries', () => {
+        let activeId: string;
+        let deletedId: string;
+
+        beforeEach(async () => {
+            const res1: Response = await authFetch('/tasks', {
+                method: 'POST',
+                body: JSON.stringify({ title: 'Active' })
+            });
+            activeId = (await res1.json() as Task).id;
+
+            const res2: Response = await authFetch('/tasks', {
+                method: 'POST',
+                body: JSON.stringify({ title: 'Removed' })
+            });
+            deletedId = (await res2.json() as Task).id;
+            await authFetch(`/tasks/${deletedId}`, { method: 'DELETE' });
+        });
+
+        it('default findAll returns only non-deleted entities', async () => {
+            const res: Response = await authFetch('/tasks');
+            const tasks: Task[] = await res.json() as Task[];
+            expect(tasks.map(t => t.id)).toEqual([activeId]);
+        });
+
+        it('findAll with withDeleted returns all entities', async () => {
+            const res: Response = await authFetch('/tasks/with-deleted');
+            const tasks: Task[] = await res.json() as Task[];
+            expect(tasks.map(t => t.id).sort()).toEqual([activeId, deletedId].sort());
+        });
+    });
+
+    describe('deleteAll', () => {
+        let id1: string, id2: string;
+
+        beforeEach(async () => {
+            const res1: Response = await authFetch('/tasks', {
+                method: 'POST',
+                body: JSON.stringify({ title: 'Task 1' })
+            });
+            id1 = (await res1.json() as Task).id;
+
+            const res2: Response = await authFetch('/tasks', {
+                method: 'POST',
+                body: JSON.stringify({ title: 'Task 2' })
+            });
+            id2 = (await res2.json() as Task).id;
+        });
+
+        it('soft deletes all matching entities', async () => {
+            const where: SoftDeleteWhere<Task> = { title: 'Task 1' };
+            await taskRepo.deleteAll(where); // soft delete by default
+
+            const allTasks: Task[] = await taskRepo.findAll({ withDeleted: true });
+            const task1: Task | undefined = allTasks.find(t => t.id === id1);
+            const task2: Task | undefined = allTasks.find(t => t.id === id2);
+            assert(task1 && task2);
+            expect(task1.deleted).toBe(true);
+            expect(task2.deleted).toBe(false);
+        });
+
+        it('hard deletes all matching entities', async () => {
+            const where: SoftDeleteWhere<Task> = { title: 'Task 2' };
+            await taskRepo.deleteAll(where, { hardDelete: true });
+
+            const allTasks: Task[] = await taskRepo.findAll({ withDeleted: true });
+            expect(allTasks.find(t => t.id === id2)).toBeUndefined();
+        });
+    });
+});

package/src/change-sets/soft-delete-repository.ts

@@ -16,9 +16,14 @@ import { SoftDeleteFindOneOptions } from './models/soft-delete-find-one-options.
 import { SoftDeleteUpdateAllOptions } from './models/soft-delete-update-all-options.model';
 import { SoftDeleteUpdateByIdOptions } from './models/soft-delete-update-by-id-options.model';
 import { SoftDeleteWhere } from './models/soft-delete-where.model';
+import { BeforeReturnHook } from '../data-source/hooks/before-return';
+import { BeforeSaveHook } from '../data-source/hooks/before-save';
 import { Where } from '../data-source/models/where/where-filter.model';
 import { NotFoundError } from '../error-handling/errors/not-found.error';
 import { LoggerInterface } from '../logging/logger.interface';
+import { ChangeSet, CreateChangeSetData } from './models/change-set.model';
+import { AuthServiceInterface } from '../auth/auth-service.interface';
+import { DataSourceInterface } from '../data-source/data-sources/data-source.interface';
 
 /**
  * Options for deleting a soft delete entity by its id.
@@ -33,7 +38,7 @@ export type SoftDeleteByIdOptions = DeleteByIdOptions & {
 /**
  * Options for deleting multiple soft delete entities.
  */
-export type SoftDeleteAllOptions<T extends SoftDeleteEntity> = DeleteAllOptions<T> & {
+export type SoftDeleteAllOptions = DeleteAllOptions & {
     /**
      * Whether or not to "actual" delete entities, rather than marking them as deleted.
      */
@@ -51,10 +56,18 @@ export class SoftDeleteRepository<
 >
     extends ChangeSetRepository<T, CreateData, UpdateData> {
 
-    protected override readonly keysToExcludeFromChangeSets: (keyof T)[] = ['changeSets', 'deleted'];
-
-    constructor(entityClass: Newable<T>, repo: TORepository<T> | Repository<T>, logger: LoggerInterface) {
-        super(entityClass, repo, logger);
+    constructor(
+        entityClass: Newable<T>,
+        repo: TORepository<T> | Repository<T>,
+        logger: LoggerInterface,
+        dataSource: DataSourceInterface,
+        beforeSave: BeforeSaveHook<T, CreateData, UpdateData>,
+        beforeReturn: BeforeReturnHook<T>,
+        authService: AuthServiceInterface,
+        changeSetRepository: Repository<ChangeSet, CreateChangeSetData>
+    ) {
+        super(entityClass, repo, logger, dataSource, beforeSave, beforeReturn, authService, changeSetRepository);
+        this.keysToExcludeFromChangeSets.add('deleted');
     }
 
     // eslint-disable-next-line jsdoc/require-jsdoc
@@ -119,7 +132,19 @@ export class SoftDeleteRepository<
     // eslint-disable-next-line jsdoc/require-jsdoc
     async updateById(id: T['id'], data: UpdateData, options?: SoftDeleteUpdateByIdOptions): Promise<T> {
         await this.findById(id, options);
-        return await super.updateById(id, data, options);
+        try {
+            // The base updateById saves and then calls this.findById again.
+            // If the update set deleted = true, that final findById will throw NotFoundError
+            // because the soft‑delete guard now sees the entity as deleted.
+            return await super.updateById(id, data, options);
+        }
+        catch (error) {
+            // Only catch the case where the update itself caused the soft‑delete
+            if (error instanceof NotFoundError && data.deleted === true) {
+                return this.findById(id, { ...options, withDeleted: true });
+            }
+            throw error;
+        }
     }
 
     // eslint-disable-next-line jsdoc/require-jsdoc
@@ -129,23 +154,28 @@ export class SoftDeleteRepository<
     }
 
     // eslint-disable-next-line jsdoc/require-jsdoc
-    async deleteById(id: T['id'], options?: SoftDeleteByIdOptions): Promise<void> {
+    async deleteById(id: T['id'], options?: SoftDeleteByIdOptions): Promise<T> {
         if (options?.hardDelete === true) {
-            await super.deleteById(id, options);
-            return;
+            return await super.deleteById(id, options);
         }
         const entity: T = await this.findById(id, options);
         if (entity.deleted) {
             throw new NotFoundError(`Could not find ${this.entityClass.name} with id "${id}".`);
         }
-        await this.updateById(id, { deleted: true } as UpdateData, options);
+        const res: T = await this.updateById(id, { deleted: true } as UpdateData, options);
         await this.createChangeSet(entity, { deleted: true } as UpdateData, ChangeSetType.DELETE, options, true);
+        return res;
     }
 
     // eslint-disable-next-line jsdoc/require-jsdoc
-    async deleteAll(where: SoftDeleteWhere<T>, options?: SoftDeleteAllOptions<T> | undefined): Promise<T[]> {
+    async deleteAll(where: SoftDeleteWhere<T>, options?: SoftDeleteAllOptions | undefined): Promise<T[]> {
         if (options?.hardDelete === true) {
-            return await super.deleteAll(this.softDeleteWhereToWhere(true, where), options);
+            // eslint-disable-next-line jsdoc/require-jsdoc
+            const finalOptions: DeleteAllOptions & { withDeleted?: boolean } = {
+                ...options,
+                withDeleted: true
+            };
+            return await super.deleteAll(this.softDeleteWhereToWhere(true, where), finalOptions);
         }
         const res: T[] = await this.updateAllWithoutChangeSet(
             this.softDeleteWhereToWhere(false, where),
@@ -158,7 +188,7 @@ export class SoftDeleteRepository<
 
     private softDeleteWhereToWhere(withDeleted: boolean = false, where?: SoftDeleteWhere<T>): Where<T> {
         if (where == undefined) {
-            return { deleted: false } as Where<T>;
+            return { deleted: withDeleted ? undefined : false } as Where<T>;
         }
         if (Array.isArray(where)) {
             return where.map(f => ({ ...f, deleted: withDeleted ? undefined : false }));

package/src/context/als.utilities.ts

@@ -0,0 +1,84 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import { CacheContext } from './cache/cache.context';
+import { HttpRequestContext } from './request/http-request.context';
+import { WebsocketRequestContext } from './request/websocket-request.context';
+
+/**
+ * Encapsulates functionality around async local storage.
+ */
+export abstract class AlsUtilities {
+    private static readonly httpRequest: AsyncLocalStorage<HttpRequestContext> = new AsyncLocalStorage<HttpRequestContext>();
+    private static readonly websocketRequest: AsyncLocalStorage<WebsocketRequestContext> = new AsyncLocalStorage<WebsocketRequestContext>();
+    private static readonly cacheContext: AsyncLocalStorage<CacheContext[]> = new AsyncLocalStorage<CacheContext[]>();
+
+    /**
+     * Resolves the currently active request context from the async local storage.
+     * @returns The currently active request context.
+     * @throws When the async local storage store has not been initialized yet.
+     */
+    static getCurrentRequestContext(): HttpRequestContext | WebsocketRequestContext | undefined {
+        return this.getCurrentHttpRequestContext() ?? this.getCurrentWebsocketRequestContext();
+    }
+
+    /**
+     * Runs the given function with the request context saved in async local storage.
+     * @param context - The request context.
+     * @param fn - The function to run.
+     * @returns The result of the function.
+     */
+    static runWithHttpRequestContext<T>(context: HttpRequestContext, fn: () => T): T {
+        return this.httpRequest.run(context, fn);
+    }
+
+    /**
+     * Resolves the currently active request context from the async local storage.
+     * @returns The currently active http request context.
+     * @throws When the async local storage store has not been initialized yet.
+     */
+    protected static getCurrentHttpRequestContext(): HttpRequestContext | undefined {
+        const store: HttpRequestContext | undefined = this.httpRequest.getStore();
+        return store;
+    }
+
+    /**
+     * Runs the given function with the request context saved in async local storage.
+     * @param context - The request context.
+     * @param fn - The function to run.
+     * @returns The result of the function.
+     */
+    static runWithWebsocketRequestContext<T>(context: WebsocketRequestContext, fn: () => T): T {
+        return this.websocketRequest.run(context, fn);
+    }
+
+    /**
+     * Resolves the currently active request context from the async local storage.
+     * @returns The currently active websocket request context.
+     * @throws When the async local storage store has not been initialized yet.
+     */
+    protected static getCurrentWebsocketRequestContext(): WebsocketRequestContext | undefined {
+        const store: WebsocketRequestContext | undefined = this.websocketRequest.getStore();
+        return store;
+    }
+
+    /**
+     * Runs the given function with the cache context saved in async local storage.
+     * @param context - The cache context.
+     * @param fn - The function to run.
+     * @returns The result of the function.
+     */
+    static runWithCacheContext<T>(context: CacheContext, fn: () => T): T {
+        const existing: CacheContext[] = this.getCurrentCacheContext() ?? [];
+        // New array — doesn't mutate the parent scope's array
+        return this.cacheContext.run([...existing, context], fn);
+    }
+
+    /**
+     * Resolves the currently active cache context from the async local storage.
+     * @returns The currently active cache context.
+     * @throws When the async local storage store has not been initialized yet.
+     */
+    static getCurrentCacheContext(): CacheContext[] | undefined {
+        return this.cacheContext.getStore();
+    }
+}

package/src/context/base-context.ts

@@ -0,0 +1,12 @@
+/**
+ * The base context that any context needs to extend from.
+ */
+export abstract class BaseContext<T> {
+    abstract readonly type: T;
+    /**
+     * The cached token values.
+     */
+    protected readonly tokenValues: Map<string, unknown> = new Map();
+
+    constructor() {}
+}

package/src/context/cache/cache.context.ts

@@ -0,0 +1,33 @@
+import { CacheOperation } from '../../caching/cache/cache-operation.enum';
+import { Property } from '../../entity/decorators/property.decorator';
+
+/**
+ * Context information about a cache that the program is currently using.
+ */
+export class CacheContext {
+    /**
+     * The name of the cache.
+     */
+    @Property.string()
+    cache!: string;
+    /**
+     * The cache operation currently running.
+     */
+    @Property.string({ enum: CacheOperation })
+    operation!: CacheOperation;
+    /**
+     * The key of the value in the cache.
+     */
+    @Property.unknown({ required: false })
+    key?: unknown;
+    /**
+     * Whether or not the cache has been hit.
+     */
+    @Property.boolean({ required: false })
+    hit?: boolean;
+    /**
+     * The duration that the original function took.
+     */
+    @Property.number({ required: false })
+    durationInMs?: number;
+}