zibri 2.3.0 → 2.4.1

package/src/data-source/hooks/hooks.test.ts

@@ -0,0 +1,268 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from '@jest/globals';
+
+import { createTestDataSource, defaultTestServerEntities } from '../../__testing__/test-server/create-test-data-source.function';
+import { StartedTestServer, startTestServer } from '../../__testing__/test-server/start-test-server.function';
+import { ChangeSetEntity } from '../../change-sets/models/change-set-entity.model';
+import { ChangeSetType } from '../../change-sets/models/change-set-type.enum';
+import { ChangeSet } from '../../change-sets/models/change-set.model';
+import { SoftDeleteEntity } from '../../change-sets/models/soft-delete-entity.model';
+import { SoftDeleteRepository } from '../../change-sets/soft-delete-repository';
+import { repositoryTokenFor } from '../../di/decorators/inject-repository.decorator';
+import { inject } from '../../di/inject.function';
+import { BaseEntity } from '../../entity/base-entity.model';
+import { Entity } from '../../entity/decorators/entity.decorator';
+import { Property } from '../../entity/decorators/property.decorator';
+import { PostgresDataSource } from '../data-sources/postgres-typeorm-data-source.model';
+import { Repository } from '../repository';
+
+// ==================== TEST ENTITIES ====================
+
+// Entity that tests ALL hook-related features
+@Entity()
+class HookTestEntity extends BaseEntity implements ChangeSetEntity, SoftDeleteEntity {
+    @Property.string()
+    name!: string;
+
+    @Property.string({ encryption: true, exclude: true })
+    secretValue!: string; // encrypted on save, decrypted on read, excluded from response
+
+    @Property.string({ hash: true })
+    password!: string; // hashed on save
+
+    @Property.boolean({ default: true })
+    isActive!: boolean; // default value set on create
+
+    @Property.string({ required: false, excludeFromChangeSets: true })
+    internalNote?: string; // excluded from change sets
+
+    @Property.boolean({ default: false })
+    deleted!: boolean; // required by SoftDeleteEntity
+
+    @Property.oneToMany({ target: () => ChangeSet, inverseSide: 'changeSetEntityId' })
+    changeSets!: ChangeSet[]; // required by ChangeSetEntity
+}
+
+let server: StartedTestServer;
+let repo: Repository<HookTestEntity>;
+let changeSetRepo: Repository<ChangeSet>;
+
+beforeAll(async () => {
+    server = await startTestServer({
+        dataSources: [
+            createTestDataSource({
+                entities: [...defaultTestServerEntities, HookTestEntity, ChangeSet]
+            })
+        ]
+    });
+    repo = inject(repositoryTokenFor(HookTestEntity));
+    changeSetRepo = inject(repositoryTokenFor(ChangeSet));
+}, 15000);
+
+afterAll(async () => {
+    await server.shutdown();
+});
+
+beforeEach(async () => {
+    await changeSetRepo.deleteAll({});
+    await repo.deleteAll({});
+});
+
+describe('before‑save hooks', () => {
+    describe('on create', () => {
+        it('encrypts properties marked with encryption', async () => {
+            const entity: HookTestEntity = await repo.create({
+                name: 'Test',
+                secretValue: 'top-secret',
+                password: 'plain'
+            });
+
+            // secretValue should be encrypted (not the plain text)
+            expect(entity.secretValue).toBe('top-secret');
+        });
+
+        it('hashes properties marked with hash', async () => {
+            const entity: HookTestEntity = await repo.create({
+                name: 'Test',
+                secretValue: 'top-secret',
+                password: 'my-password'
+            });
+
+            // password should be hashed (not the plain text)
+            expect(entity.password).not.toBe('my-password');
+            expect(entity.password).toContain('$'); // hash contains algorithm prefix
+        });
+
+        it('sets default values when not provided', async () => {
+            const entity: HookTestEntity = await repo.create({
+                name: 'Test',
+                secretValue: 'top-secret',
+                password: 'plain'
+            });
+
+            // isActive should default to true
+            expect(entity.isActive).toBe(true);
+        });
+
+        it('does NOT override explicitly provided values with defaults', async () => {
+            const entity: HookTestEntity = await repo.create({
+                name: 'Test',
+                secretValue: 'top-secret',
+                password: 'plain',
+                isActive: false
+            });
+
+            expect(entity.isActive).toBe(false);
+        });
+
+        it('encrypts values at rest (raw database access)', async () => {
+            const entity: HookTestEntity = await repo.create({
+                name: 'EncAtRest',
+                secretValue: 'super-secret',
+                password: 'pw'
+            });
+
+            // Use the query builder to read the raw column – no before‑return hook runs
+            const raw: HookTestEntity | null = await (repo.dataSource as PostgresDataSource)
+                .query(HookTestEntity)
+                .select(`${HookTestEntity.name}.secretValue`)
+                .where(`${HookTestEntity.name}.id = :id`, { id: entity.id })
+                .getOne();
+
+            // The stored value must be encrypted (not plain text)
+            expect(raw?.secretValue).not.toBe('super-secret');
+            expect(raw?.secretValue.length).toBeGreaterThan(20);
+        });
+    });
+
+    describe('on update', () => {
+        let entityId: string;
+
+        beforeEach(async () => {
+            const entity: HookTestEntity = await repo.create({
+                name: 'Original',
+                secretValue: 'initial-secret',
+                password: 'initial-password'
+            });
+            entityId = entity.id;
+        });
+
+        it('encrypts updated encrypted properties', async () => {
+            const updated: HookTestEntity = await repo.updateById(entityId, { secretValue: 'new-secret' });
+            expect(updated.secretValue).toBe('new-secret');
+        });
+
+        it('hashes updated hash properties', async () => {
+            const updated: HookTestEntity = await repo.updateById(entityId, { password: 'new-password' });
+            expect(updated.password).not.toBe('new-password');
+            expect(updated.password).toContain('$');
+        });
+
+        it('does NOT re‑set default values (setDefault = false)', async () => {
+            // Update without providing isActive
+            const updated: HookTestEntity = await repo.updateById(entityId, { name: 'Updated' });
+            // isActive should remain its original value (true from create's default)
+            expect(updated.isActive).toBe(true);
+        });
+    });
+});
+
+describe('before‑return hooks', () => {
+    describe('on find', () => {
+        let entityId: string;
+        let originalSecret: string;
+
+        beforeEach(async () => {
+            // We need the entity as stored (with encrypted/hashed values) before the return hook runs.
+            // So we create one and capture what findById returns after decryption.
+            const entity: HookTestEntity = await repo.create({
+                name: 'ReturnTest',
+                secretValue: 'my-secret',
+                password: 'my-password'
+            });
+            entityId = entity.id;
+            // After create, before‑return has already run, so we see decrypted values.
+            originalSecret = entity.secretValue;
+        });
+
+        it('decrypts encrypted properties on findById', async () => {
+            const fetched: HookTestEntity = await repo.findById(entityId);
+            // secretValue should be decrypted (equal to the original plain text after re‑encryption/decryption)
+            expect(fetched.secretValue).toBe(originalSecret);
+        });
+
+        it('decrypts encrypted properties on findAll', async () => {
+            const results: HookTestEntity[] = await repo.findAll();
+            expect(results).toHaveLength(1);
+            expect(results[0].secretValue).toBe(originalSecret);
+        });
+
+        it('decrypts encrypted properties on findOne', async () => {
+            const fetched: HookTestEntity = await repo.findOne({ where: { id: entityId } }, true);
+            expect(fetched.secretValue).toBe(originalSecret);
+        });
+
+        it('removes excluded properties from the returned entity', async () => {
+            const fetched: HookTestEntity = await repo.findById(entityId);
+            expect(fetched.secretValue).toBe(originalSecret);
+            expect(JSON.stringify(fetched)).not.toContain('secretValue');
+        });
+    });
+});
+
+describe('ChangeSetRepository hooks integration', () => {
+    it('excludes properties marked with excludeFromChangeSets from change sets', async () => {
+        const entity: HookTestEntity = await repo.create({
+            name: 'ChangeSetTest',
+            secretValue: 'test-secret',
+            password: 'test-password',
+            internalNote: 'do not track'
+        });
+
+        const changeSets: ChangeSet[] = await changeSetRepo.findAll({ where: { changeSetEntityId: entity.id } });
+        expect(changeSets).toHaveLength(1);
+
+        const cs: ChangeSet = changeSets[0];
+        // internalNote should NOT appear in changes
+        expect(cs.changes.some(c => c.key === 'internalNote')).toBe(false);
+        // other properties should be tracked
+        expect(cs.changes.some(c => c.key === 'name')).toBe(true);
+    });
+
+    it('records change sets for create and update operations', async () => {
+        const entity: HookTestEntity = await repo.create({
+            name: 'TrackingTest',
+            secretValue: 'secret',
+            password: 'pass'
+        });
+
+        // Update name
+        await repo.updateById(entity.id, { name: 'Updated' });
+
+        const changeSets: ChangeSet[] = await changeSetRepo.findAll({
+            where: { changeSetEntityId: entity.id },
+            order: { createdAt: 'ASC' }
+        });
+        expect(changeSets).toHaveLength(2);
+        expect(changeSets[0].type).toBe(ChangeSetType.CREATE);
+        expect(changeSets[1].type).toBe(ChangeSetType.UPDATE);
+    });
+});
+
+describe('SoftDeleteRepository hooks integration', () => {
+    it('excludes "deleted" from change sets', async () => {
+        const entity: HookTestEntity = await repo.create({
+            name: 'SoftDeleteTest',
+            secretValue: 'secret',
+            password: 'pass'
+        });
+
+        // Soft delete
+        await (repo as unknown as SoftDeleteRepository<HookTestEntity>).deleteById(entity.id);
+
+        const changeSets: ChangeSet[] = await changeSetRepo.findAll({ where: { changeSetEntityId: entity.id } });
+        const deleteCs: ChangeSet | undefined = changeSets.find(cs => cs.type === ChangeSetType.DELETE);
+        expect(deleteCs).toBeDefined();
+        // deleted flag should NOT appear in changes
+        expect(deleteCs?.changes.some(c => c.key === 'deleted')).toBe(false);
+    });
+});

package/src/data-source/migration/migration.test.ts

@@ -1,3 +1,5 @@
+import { randomBytes } from 'node:crypto';
+
 import { beforeAll, afterAll, describe, it, expect } from '@jest/globals';
 import { PostgreSqlContainer, StartedPostgreSqlContainer } from '@testcontainers/postgresql';
 import { Table, TableColumn } from 'typeorm';
@@ -5,16 +7,21 @@ import { Table, TableColumn } from 'typeorm';
 import { MigrationEntity } from './migration-entity.model';
 import { Migration } from './migration.model';
 import { POSTGRES_TEST_IMAGE } from '../../__testing__/constants';
+import { defaultTestServerEntities } from '../../__testing__/test-server/create-test-data-source.function';
+import { AesGcmEncryptionStrategy } from '../../auth/encryption/strategies/aes-gcm.encryption-strategy';
 import { InjectRepository } from '../../di/decorators/inject-repository.decorator';
 import { Injectable } from '../../di/decorators/injectable.decorator';
+import { ZIBRI_DI_TOKENS } from '../../di/default/zibri-di-tokens.default';
 import { inject } from '../../di/inject.function';
+import { register } from '../../di/register.function';
 import { BaseEntity } from '../../entity/base-entity.model';
 import { Entity } from '../../entity/decorators/entity.decorator';
 import { Property } from '../../entity/decorators/property.decorator';
 import { GlobalRegistry } from '../../global/global-registry';
 import { Newable } from '../../types/newable.type';
+import { OmitStrict } from '../../types/omit-strict.type';
 import { Version } from '../../types/version.type';
-import { PostgresDataSource, PostgresOptions } from '../data-sources/postgres-data-source.model';
+import { PostgresDataSource, PostgresOptions } from '../data-sources/postgres-typeorm-data-source.model';
 import { DataSource } from '../decorators/data-source.decorator';
 import { Repository } from '../repository';
 import { Transaction } from '../transaction/transaction.model';
@@ -27,14 +34,14 @@ class LegacyItem {
 
 @DataSource()
 class LegacyDbDataSource extends PostgresDataSource {
-    options: PostgresOptions = {
+    options: OmitStrict<PostgresOptions, 'type'> = {
         host: 'localhost',
         username: 'postgres',
         password: 'password',
         database: 'db',
         synchronize: true
     };
-    entities: Newable<BaseEntity>[] = [MigrationEntity, LegacyItem];
+    entities: Newable<BaseEntity>[] = [...defaultTestServerEntities, LegacyItem];
 }
 
 @Entity({ tableName: 'item' })
@@ -48,14 +55,14 @@ class Item {
 
 @DataSource()
 class DbDataSource extends PostgresDataSource {
-    options: PostgresOptions = {
+    options: OmitStrict<PostgresOptions, 'type'> = {
         host: 'localhost',
         username: 'postgres',
         password: 'password',
         database: 'db',
         synchronize: true
     };
-    entities: Newable<BaseEntity>[] = [MigrationEntity, Item];
+    entities: Newable<BaseEntity>[] = [...defaultTestServerEntities, Item];
     migrations: Newable<Migration>[] = [AddTestValueMigration];
 }
 
@@ -94,6 +101,13 @@ describe('AddTestValueMigration', () => {
             .start();
 
         GlobalRegistry['appData'].version = '0.0.1';
+        register({
+            token: ZIBRI_DI_TOKENS.ENCRYPTION_MASTER_OPTIONS,
+            useValue: {
+                currentMasterStrategy: new AesGcmEncryptionStrategy(),
+                currentMasterKey: { id: 'mk1', value: randomBytes(32) }
+            }
+        });
 
         const legacyDataSource: LegacyDbDataSource = inject(LegacyDbDataSource);
         legacyDataSource.options = {

package/src/data-source/models/options/count-options.model.ts

@@ -1,14 +1,9 @@
 import { BaseRepositoryOptions } from './base-repository-options.model';
+import { FindAllOptions } from './find-all-options.model';
 import { BaseEntity } from '../../../entity/base-entity.model';
-import { Where } from '../where/where-filter.model';
 
 /**
  * Options for counting entities.
  */
 export type CountOptions<T extends BaseEntity> = BaseRepositoryOptions
-    & {
-        /**
-         * The where filter to count the options by.
-         */
-        where?: Where<T>
-    };
+    & Pick<FindAllOptions<T>, 'where'>;

package/src/data-source/models/options/delete-all-options.model.ts

@@ -1,8 +1,6 @@
-import { FindAllOptions } from './find-all-options.model';
-import { BaseEntity } from '../../../entity/base-entity.model';
-import { OmitStrict } from '../../../types/omit-strict.type';
+import { BaseRepositoryOptions } from './base-repository-options.model';
 
 /**
  * Options for deleting multiple entities.
  */
-export type DeleteAllOptions<T extends BaseEntity> = OmitStrict<FindAllOptions<T>, 'where'>;
+export type DeleteAllOptions = BaseRepositoryOptions;

package/src/data-source/models/options/find-all-options.model.ts

@@ -1,4 +1,4 @@
-import { FindManyOptions } from 'typeorm';
+import { FindManyOptions, FindOptionsRelations } from 'typeorm';
 
 import { BaseRepositoryOptions } from './base-repository-options.model';
 import { BaseEntity } from '../../../entity/base-entity.model';
@@ -17,5 +17,5 @@ export type FindAllOptions<T extends BaseEntity> = BaseRepositoryOptions
         /**
          * The relations to include in the found entities.
          */
-        relations?: (keyof T)[]
+        relations?: FindOptionsRelations<T> | (keyof T)[]
     };

package/src/data-source/models/options/find-by-id-options.model.ts

@@ -5,9 +5,4 @@ import { OmitStrict } from '../../../types/omit-strict.type';
 /**
  * Options for finding a single entity by its id.
  */
-export type FindByIdOptions<T extends BaseEntity> = OmitStrict<FindOneOptions<T>, 'where' | 'relations'> & {
-    /**
-     * The relations to include in the found entity.
-     */
-    relations?: (keyof T)[]
-};
+export type FindByIdOptions<T extends BaseEntity> = OmitStrict<FindOneOptions<T>, 'where'>;

package/src/data-source/models/options/find-one-options.model.ts

@@ -1,18 +1,9 @@
 import { BaseRepositoryOptions } from './base-repository-options.model';
+import { FindAllOptions } from './find-all-options.model';
 import { BaseEntity } from '../../../entity/base-entity.model';
-import { Where } from '../where/where-filter.model';
 
 /**
  * Options for finding a single entity.
  */
 export type FindOneOptions<T extends BaseEntity> = BaseRepositoryOptions
-    & {
-        /**
-         * The where filter to find the entity by.
-         */
-        where?: Where<T>,
-        /**
-         * The relations to include in the found entity.
-         */
-        relations?: (keyof T)[]
-    };
+    & Pick<FindAllOptions<T>, 'where' | 'relations'>;

package/src/data-source/models/options/update-all-options.model.ts

@@ -4,9 +4,6 @@ import { BaseRepositoryOptions } from './base-repository-options.model';
  * Options for updating multiple entities at once.
  */
 export type UpdateAllOptions = BaseRepositoryOptions & {
-    /**
-     * Whether or not setting the id property manually is allowed.
-     * @default false.
-     */
-    allowId?: boolean
+    // should never be allowed, as that would cause typeorm's manager.save method to create new entities instead of updating the existing ones.
+    // allowId?: boolean
 };

package/src/data-source/models/options/update-by-id-options.model.ts

@@ -4,9 +4,6 @@ import { BaseRepositoryOptions } from './base-repository-options.model';
  * Options for updating an entity by its id.
  */
 export type UpdateByIdOptions = BaseRepositoryOptions & {
-    /**
-     * Whether or not setting the id property manually is allowed.
-     * @default false.
-     */
-    allowId?: boolean
+    // should never be allowed, as that would cause typeorm's manager.save method to create a new entity instead of updating the existing one.
+    // allowId?: boolean
 };

package/src/data-source/models/where/array-where-filter.model.ts

@@ -1,13 +1,13 @@
+import { Where, WhereFilterProperty } from './where-filter.model';
 
 /**
  * A filter for an array where property.
  */
-export type ArrayWhereFilter<ItemType> = null | {
+export type ArrayWhereFilter<ItemType> = null | ItemType[] | {
     /**
-     * The property needs to equal the value.
+     * The property needs to be not this value.
      */
-    equals: ItemType[]
-} | {
+    not?: null | ItemType[],
     /**
      * The property needs to include the value.
      */
@@ -15,5 +15,147 @@ export type ArrayWhereFilter<ItemType> = null | {
     /**
      * The properties items needs to be included in the value.
      */
-    isIncludedIn?: ItemType[]
+    isIncludedIn?: ItemType[],
+    /**
+     * The length that this array needs to have.
+     */
+    length?: number,
+    /**
+     * The length of this array needs to be greater than the provided value.
+     */
+    lengthGreaterThan?: number,
+    /**
+     * The length of this array needs to be greater than or equal to the provided value.
+     */
+    lengthGreaterThanEquals?: number,
+    /**
+     * The length of this array needs to be lesser than the provided value.
+     */
+    lengthLesserThan?: number,
+    /**
+     * The length of this array needs to be lesser than or equal to the provided value.
+     */
+    lengthLesserThanEquals?: number,
+    /**
+     * A where condition that at least one of the items inside this array needs to match.
+     */
+    where?: never
+}
+| {
+    /**
+     * The property needs to be not this value.
+     */
+    not?: never,
+    /**
+     * The property needs to include the value.
+     */
+    includes?: never,
+    /**
+     * The properties items needs to be included in the value.
+     */
+    isIncludedIn?: never,
+    /**
+     * The length that this array needs to have.
+     */
+    length?: number,
+    /**
+     * The length of this array needs to be greater than the provided value.
+     */
+    lengthGreaterThan?: number,
+    /**
+     * The length of this array needs to be greater than or equal to the provided value.
+     */
+    lengthGreaterThanEquals?: number,
+    /**
+     * The length of this array needs to be lesser than the provided value.
+     */
+    lengthLesserThan?: number,
+    /**
+     * The length of this array needs to be lesser than or equal to the provided value.
+     */
+    lengthLesserThanEquals?: number,
+    /**
+     * A where condition that at least one of the items inside this array needs to match.
+     */
+    where: WhereFilterProperty<ItemType> | WhereFilterProperty<ItemType>[]
+};
+
+/**
+ * A filter for an array of object items where property.
+ */
+export type ObjectArrayWhereFilter<ItemType extends object> = null | ItemType[] | {
+    /**
+     * The property needs to be not this value.
+     */
+    not?: null | ItemType[],
+    /**
+     * The property needs to include the value.
+     */
+    includes?: ItemType[],
+    /**
+     * The properties items needs to be included in the value.
+     */
+    isIncludedIn?: ItemType[],
+    /**
+     * The length that this array needs to have.
+     */
+    length?: number,
+    /**
+     * The length of this array needs to be greater than the provided value.
+     */
+    lengthGreaterThan?: number,
+    /**
+     * The length of this array needs to be greater than or equal to the provided value.
+     */
+    lengthGreaterThanEquals?: number,
+    /**
+     * The length of this array needs to be lesser than the provided value.
+     */
+    lengthLesserThan?: number,
+    /**
+     * The length of this array needs to be lesser than or equal to the provided value.
+     */
+    lengthLesserThanEquals?: number,
+    /**
+     * A where condition that at least one of the items inside this array needs to match.
+     */
+    where?: never
+}
+| {
+    /**
+     * The property needs to be not this value.
+     */
+    not?: never,
+    /**
+     * The property needs to include the value.
+     */
+    includes?: never,
+    /**
+     * The properties items needs to be included in the value.
+     */
+    isIncludedIn?: never,
+    /**
+     * The length that this array needs to have.
+     */
+    length?: number,
+    /**
+     * The length of this array needs to be greater than the provided value.
+     */
+    lengthGreaterThan?: number,
+    /**
+     * The length of this array needs to be greater than or equal to the provided value.
+     */
+    lengthGreaterThanEquals?: number,
+    /**
+     * The length of this array needs to be lesser than the provided value.
+     */
+    lengthLesserThan?: number,
+    /**
+     * The length of this array needs to be lesser than or equal to the provided value.
+     */
+    lengthLesserThanEquals?: number,
+    /**
+     * A where condition that at least one of the items inside this array needs to match.
+     */
+    where: Where<ItemType>
 };

package/src/data-source/models/where/base-where-filter.model.ts

@@ -1,4 +1,22 @@
+/**
+ * The base where filter object.
+ */
+export type BaseWhereFilterObject<T> = {
+    /**
+     * The property needs to be not this value.
+     */
+    not?: T | null,
+    /**
+     * The property needs to be one of the values in the array.
+     */
+    oneOf?: (T | null)[],
+    /**
+     * The property needs to be NOT one of the values in the array.
+     */
+    notOneOf?: (T | null)[]
+};
+
 /**
  * A base where filter, shared by all property types.
  */
-export type BaseWhereFilter<T> = T | null;
+export type BaseWhereFilter<T, FilterObject extends BaseWhereFilterObject<T>> = T | null | FilterObject;

package/src/data-source/models/where/boolean-where-filter.model.ts

@@ -1,6 +1,11 @@
-import { BaseWhereFilter } from './base-where-filter.model';
+import { BaseWhereFilter, BaseWhereFilterObject } from './base-where-filter.model';
+import { ExcludeStrict } from '../../../types/exclude-strict.type';
+import { OmitStrict } from '../../../types/omit-strict.type';
 
 /**
  * A filter for a boolean where property.
  */
-export type BooleanWhereFilter = BaseWhereFilter<boolean>;
+export type BooleanWhereFilter = ExcludeStrict<
+    BaseWhereFilter<boolean, BaseWhereFilterObject<boolean>>,
+    BaseWhereFilterObject<boolean>
+> | Required<OmitStrict<BaseWhereFilterObject<boolean>, 'oneOf' | 'notOneOf'>>;