zibri 2.4.0 → 2.5.0

package/src/data-source/data-sources/where-converter/typeorm-where-filter.converter.ts

@@ -0,0 +1,389 @@
+import { And, ArrayContainedBy, ArrayContains, Equal, FindOperator, ILike, In, IsNull, LessThan, LessThanOrEqual, Like, MoreThan, MoreThanOrEqual, Not, Or, Raw, FindOptionsWhere as ToFindOptionsWhere, FindOptionsWhereProperty as ToFindOptionsWhereProperty, DataSource as ToDataSource } from 'typeorm';
+
+import { BaseEntity } from '../../../entity/base-entity.model';
+import { PropertyMetadata, RelationMetadata } from '../../../entity/decorators/property.decorator';
+import { Relation } from '../../../entity/models/relation.enum';
+import { ExcludeStrict } from '../../../types/exclude-strict.type';
+import { Newable } from '../../../types/newable.type';
+import { MetadataUtilities } from '../../../utilities/metadata.utilities';
+import { ObjectUtilities } from '../../../utilities/object.utilities';
+import { ArrayWhereFilter } from '../../models/where/array-where-filter.model';
+import { isWhereFilterKey, WhereFilterKeys } from '../../models/where/where-filter-keys.model';
+import { Where, WhereFilter, WhereFilterProperty } from '../../models/where/where-filter.model';
+
+// eslint-disable-next-line typescript/typedef
+const lengthWhereFilterKeys = [
+    'length',
+    'lengthGreaterThan',
+    'lengthGreaterThanEquals',
+    'lengthLesserThan',
+    'lengthLesserThanEquals'
+] as const satisfies (keyof ExcludeStrict<ArrayWhereFilter<object>, null | object[]>)[];
+
+/**
+ * Handler function for a single where-filter key.
+ */
+export type WhereFilterHandler = (
+    value: unknown,
+    metadata: PropertyMetadata,
+    nestedProperties: Record<string, PropertyMetadata> | undefined,
+    entityClass: Newable<unknown>
+) => FindOperator<unknown>;
+
+/**
+ * Abstract base converter that transforms a Zibri WhereFilter into a TypeORM FindOptionsWhere.
+ */
+export abstract class TypeOrmWhereFilterConverter {
+
+    /**
+     * Handler for a fuzzyLike filter.
+     */
+    protected abstract fuzzyLikeWhereFilterHandler: WhereFilterHandler;
+
+    /**
+     * A map that defines how Zibri's where filter properties are mapped to their typeorm counterpart.
+     */
+    protected handleFilterKeyMap: Record<WhereFilterKeys, WhereFilterHandler> = {
+        not: (value) => Not(value),
+        like: (value) => Like(value),
+        oneOf: (value) => {
+            if (!Array.isArray(value)) {
+                throw new Error('The "oneOf" property of the where filter needs to be an array.');
+            }
+            return In(value);
+        },
+        notOneOf: (value) => {
+            if (!Array.isArray(value)) {
+                throw new Error('The "notOneOf" property of the where filter needs to be an array.');
+            }
+            return Not(In(value));
+        },
+        after: (value) => MoreThan(value),
+        before: (value) => LessThan(value),
+        afterOrOn: (value) => MoreThanOrEqual(value),
+        beforeOrOn: (value) => LessThanOrEqual(value),
+        greaterThan: (value) => MoreThan(value),
+        greaterThanEquals: (value) => MoreThanOrEqual(value),
+        lesserThan: (value) => LessThan(value),
+        lesserThanEquals: (value) => LessThanOrEqual(value),
+        iLike: (value) => ILike(value),
+        fuzzyLike: (value, metadata, nestedProperties, entityClass) => this.fuzzyLikeWhereFilterHandler(
+            value,
+            metadata,
+            nestedProperties,
+            entityClass
+        ),
+        is: (value, metadata) => {
+            if (value === null) {
+                return IsNull();
+            }
+            // Unwrap a full entity for MANY_TO_ONE / BELONGS_TO_ONE
+            if (
+                (metadata.type === Relation.MANY_TO_ONE
+                    || metadata.type === Relation.BELONGS_TO_ONE)
+                && typeof value === 'object'
+                && !Array.isArray(value)
+                && 'id' in value
+            ) {
+                return Equal(value.id);
+            }
+            return Equal(value);
+        },
+        where: (value, metadata, nestedProperties, entityClass) => this.whereHandler(value, metadata, nestedProperties, entityClass),
+        includes: (value) => {
+            if (!Array.isArray(value)) {
+                throw new Error('The "includes" property of the where filter needs to be an array.');
+            }
+            return ArrayContains(value);
+        },
+        isIncludedIn: (value) => {
+            if (!Array.isArray(value)) {
+                throw new Error('The "isIncludedIn" property of the where filter needs to be an array.');
+            }
+            return ArrayContainedBy(value);
+        },
+        length: (value) => Raw(alias => `array_length(${alias}, 1) = ${value}`),
+        lengthGreaterThan: (value) => Raw(alias => `array_length(${alias}, 1) > ${value}`),
+        lengthGreaterThanEquals: (value) => Raw(alias => `array_length(${alias}, 1) >= ${value}`),
+        lengthLesserThan: (value) => Raw(alias => `array_length(${alias}, 1) < ${value}`),
+        lengthLesserThanEquals: (value) => Raw(alias => `array_length(${alias}, 1) <= ${value}`)
+    };
+
+    constructor(protected readonly typeOrmDataSource: ToDataSource) {}
+
+    // ── Public entry point (concrete) ──────────────────────────
+    /**
+     * Converts the given zibri filter to a typeorm filter.
+     * @param filter - The zibri filter to convert.
+     * @param entityClass - The entity class to search for by this filter.
+     * @returns The typeorm filter.
+     */
+    convert<T extends object>(
+        filter: Where<T>,
+        entityClass: Newable<T>
+    ): ToFindOptionsWhere<T> | ToFindOptionsWhere<T>[] {
+        const properties: Record<string, PropertyMetadata> = MetadataUtilities.getModelProperties(entityClass);
+        if (Array.isArray(filter)) {
+            return filter.map(f => this.singleWhereFilterToFindOptionsWhere(f, properties, entityClass));
+        }
+        return this.singleWhereFilterToFindOptionsWhere(filter, properties, entityClass);
+    }
+
+    /**
+     * Handles converting a where filter to a typeorm FindOperator.
+     * @param value - The value of the where filter.
+     * @param metadata - The metadata of the property for which the where filter has been specified.
+     * @param nestedProperties - Nested properties on the where filter. Need to exist.
+     * @param entityClass - The entity class that the where filter belongs to.
+     * @returns A typeorm FindOperator.
+     * @throws Wheen now nested properties have been found.
+     */
+    protected whereHandler(
+        value: unknown,
+        metadata: PropertyMetadata,
+        nestedProperties: Record<string, PropertyMetadata> | undefined,
+        entityClass: Newable<unknown>
+    ): FindOperator<unknown> {
+        if (nestedProperties == undefined) {
+            throw new Error('The "where" operator is not supported on this property without nested metadata.');
+        }
+        let targetClass: Newable<unknown> = entityClass;
+        if (metadata.type === 'object') {
+            targetClass = metadata.cls();
+        }
+        else if (
+            metadata.type === Relation.HAS_ONE || metadata.type === Relation.BELONGS_TO_ONE
+            || metadata.type === Relation.MANY_TO_ONE || metadata.type === Relation.ONE_TO_MANY
+            || metadata.type === Relation.MANY_TO_MANY
+        ) {
+            targetClass = metadata.target();
+        }
+        return this.singleWhereFilterToFindOptionsWhere(
+            value as WhereFilter<Record<string, unknown>>,
+            nestedProperties,
+            targetClass as Newable<Record<string, unknown>>
+        ) as unknown as FindOperator<unknown>;
+    }
+
+    // ── Pipeline stages (concrete, overridable) ─────────────────
+
+    /**
+     * Converts a single where filter to a typeorm FindOptionsWhere property.
+     * @param filter - The filter to convert.
+     * @param properties - The property metadata of the model that the filter is for.
+     * @param entityClass - The entity class to search for by this filter.
+     * @returns A typeorm FindOptionsWhere property.
+     */
+    protected singleWhereFilterToFindOptionsWhere<T extends Object>(
+        filter: WhereFilter<T>,
+        properties: Record<string, PropertyMetadata>,
+        entityClass: Newable<T>
+    ): ToFindOptionsWhere<T> {
+        const res: ToFindOptionsWhere<T> = {};
+        const extraRawConditions: FindOperator<unknown>[] = [];
+
+        for (const key of ObjectUtilities.keys(filter)) {
+            const prop: WhereFilterProperty<T[typeof key]> | WhereFilterProperty<T[typeof key]>[] | undefined = filter[key];
+            if (prop === undefined) {
+                continue;
+            }
+
+            const propertyMetadata: PropertyMetadata = properties[key];
+            let nestedProperties: Record<string, PropertyMetadata> | undefined;
+
+            if (propertyMetadata.type === Relation.ONE_TO_MANY || propertyMetadata.type === Relation.MANY_TO_MANY) {
+                this.processRelationFilter(key, prop, propertyMetadata, entityClass, res, extraRawConditions);
+                continue;
+            }
+
+            if (propertyMetadata.type === 'object') {
+                nestedProperties = MetadataUtilities.getModelProperties(propertyMetadata.cls());
+            }
+            else if (
+                propertyMetadata.type === Relation.HAS_ONE
+                || propertyMetadata.type === Relation.BELONGS_TO_ONE
+                || propertyMetadata.type === Relation.MANY_TO_ONE
+            ) {
+                nestedProperties = MetadataUtilities.getModelProperties(propertyMetadata.target());
+            }
+
+            res[key] = this.propertyToFindOperator(
+                prop,
+                propertyMetadata,
+                nestedProperties,
+                entityClass as Newable<T[Extract<keyof T, string>]>
+            ) as typeof key extends 'toString' ? unknown : ToFindOptionsWhereProperty<NonNullable<T[typeof key]>>;
+        }
+
+        if (extraRawConditions.length) {
+            const existingIdFilter: FindOperator<unknown> | undefined = res['id' as keyof T] as FindOperator<unknown> | undefined;
+            const combined: FindOperator<unknown> = existingIdFilter
+                ? And(existingIdFilter, ...extraRawConditions)
+                : And(...extraRawConditions);
+            (res as Record<string, FindOperator<unknown>>)['id'] = combined;
+        }
+
+        return res;
+    }
+
+    private processRelationFilter<T extends Object>(
+        key: string,
+        prop: WhereFilterProperty<T[Extract<keyof T, string>]> | WhereFilterProperty<T[Extract<keyof T, string>]>[],
+        propertyMetadata: RelationMetadata<BaseEntity>,
+        entityClass: Newable<T>,
+        res: ToFindOptionsWhere<T>,
+        extraRawConditions: FindOperator<unknown>[]
+    ): void {
+        const filterObj: Record<string, unknown> = prop as Record<string, unknown>;
+
+        for (const lengthKey of lengthWhereFilterKeys) {
+            if (lengthKey in filterObj && typeof filterObj[lengthKey] === 'number') {
+                extraRawConditions.push(
+                    this.buildRelationLengthRawOperator(
+                        entityClass, key, propertyMetadata, lengthKey, filterObj[lengthKey]
+                    )
+                );
+                // eslint-disable-next-line typescript/no-dynamic-delete
+                delete filterObj[lengthKey];
+            }
+        }
+
+        // 2) includes / isIncludedIn
+        if ('includes' in filterObj && Array.isArray(filterObj.includes)) {
+            extraRawConditions.push(
+                this.buildRelationIncludesOperator(
+                    entityClass, key, propertyMetadata, filterObj.includes as BaseEntity[]
+                )
+            );
+            delete filterObj.includes;
+        }
+        if ('isIncludedIn' in filterObj && Array.isArray(filterObj.isIncludedIn)) {
+            extraRawConditions.push(
+                this.buildRelationIsIncludedInOperator(
+                    entityClass, key, propertyMetadata, filterObj.isIncludedIn as BaseEntity[]
+                )
+            );
+            delete filterObj.isIncludedIn;
+        }
+
+        // 3) Remaining element filters (e.g. where)
+        if (Object.keys(filterObj).length > 0) {
+            const targetEntity: Newable<BaseEntity> = propertyMetadata.target();
+            const nestedProps: Record<string, PropertyMetadata> = MetadataUtilities.getModelProperties(targetEntity);
+            (res as Record<string, unknown>)[key] = this.propertyToFindOperator(
+                filterObj as WhereFilterProperty<T> | WhereFilterProperty<T>[],
+                propertyMetadata,
+                nestedProps,
+                entityClass
+            );
+        }
+    }
+
+    /**
+     * Converts a where filter property to a typeorm FindOperator property.
+     * @param property - The property to convert.
+     * @param propertyMetadata - The property metadata of the property.
+     * @param nestedProperties - Nested properties, if any.
+     * @param entityClass - The entity class that the property is on.
+     * @returns A typeorm FindOperator property.
+     */
+    protected propertyToFindOperator<T>(
+        property: WhereFilterProperty<T> | WhereFilterProperty<T>[],
+        propertyMetadata: PropertyMetadata,
+        nestedProperties: Record<string, PropertyMetadata> | undefined,
+        entityClass: Newable<T>
+    ): FindOperator<T> {
+        if (Array.isArray(property)) {
+            return propertyMetadata.type === 'array'
+                ? this.singlePropertyToFindOperator(property as WhereFilterProperty<T>, propertyMetadata, nestedProperties, entityClass)
+                : Or(
+                    ...property.map(
+                        p => this.singlePropertyToFindOperator<T>(
+                            p as WhereFilterProperty<T>,
+                            propertyMetadata,
+                            nestedProperties,
+                            entityClass
+                        )
+                    )
+                );
+        }
+        return this.singlePropertyToFindOperator(property, propertyMetadata, nestedProperties, entityClass);
+    }
+
+    /**
+     * Transforms a single where filter property to a typeorm FindOperator.
+     * @param property - The where filter property to transform.
+     * @param propertyMetadata - The metadata of the where filter property.
+     * @param nestedProperties - Any nested properties of the where filter.
+     * @param entityClass - The entity class that the property is on.
+     * @returns A typeorm FindOperator.
+     * @throws When the where filter property is invalid.
+     */
+    protected singlePropertyToFindOperator<T>(
+        property: WhereFilterProperty<T>,
+        propertyMetadata: PropertyMetadata,
+        nestedProperties: Record<string, PropertyMetadata> | undefined,
+        entityClass: Newable<T>
+    ): FindOperator<T> {
+        if (property === null) {
+            // eslint-disable-next-line typescript/no-unsafe-return
+            return IsNull();
+        }
+        if (
+            typeof property === 'string'
+            || typeof property === 'bigint'
+            || typeof property === 'number'
+            || typeof property === 'boolean'
+            || property instanceof Date
+            || (Array.isArray(property) && propertyMetadata.type === 'array')
+        ) {
+            return Equal(property as T);
+        }
+
+        const operators: FindOperator<T>[] = [];
+        const filterKeys: unknown[] = ObjectUtilities.keys(property);
+        if (!filterKeys.length) {
+            throw new Error('Empty where filter');
+        }
+
+        for (const key of filterKeys) {
+            if (!isWhereFilterKey(key)) {
+                throw new Error(`Unknown key "${key}" on where filter ${property}`);
+            }
+            const handler: WhereFilterHandler = this.handleFilterKeyMap[key];
+            const value: unknown = (property as Record<string, unknown>)[key];
+            const op: FindOperator<unknown> = handler(value, propertyMetadata, nestedProperties, entityClass);
+            if (op !== undefined) {
+                operators.push(op as FindOperator<T>);
+            }
+        }
+
+        return operators.length === 1
+            ? operators[0]
+            : And(...operators);
+    }
+
+    // ── Abstract – DB‑specific building blocks ───────────────────
+
+    protected abstract buildRelationLengthRawOperator<T>(
+        entityClass: Newable<T>,
+        propertyName: string,
+        metadata: RelationMetadata<BaseEntity>,
+        lengthKey: string,
+        value: number
+    ): FindOperator<unknown>;
+
+    protected abstract buildRelationIncludesOperator<T>(
+        entityClass: Newable<T>,
+        propertyName: string,
+        metadata: RelationMetadata<BaseEntity>,
+        entities: BaseEntity[]
+    ): FindOperator<unknown>;
+
+    protected abstract buildRelationIsIncludedInOperator<T>(
+        entityClass: Newable<T>,
+        propertyName: string,
+        metadata: RelationMetadata<BaseEntity>,
+        entities: BaseEntity[]
+    ): FindOperator<unknown>;
+}

package/src/data-source/exclude-property.test.ts

@@ -26,8 +26,11 @@ class Order {
     @Property.string({ exclude: true })
     internalNote!: string;
 
-    @Property.manyToOne({ target: () => User, inverseSide: 'orders' })
+    @Property.manyToOne({ target: () => User, joinColumn: 'userId', inverseSide: 'orders' })
     user!: unknown;
+
+    @Property.string({ format: 'uuid' })
+    userId!: string;
 }
 
 class User extends BaseEntity {

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 | null; // 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-entity.model.ts

@@ -1,7 +1,7 @@
 import { BaseEntity } from '../../entity/base-entity.model';
 import { Entity } from '../../entity/decorators/entity.decorator';
 import { Property } from '../../entity/decorators/property.decorator';
-import { type Version } from '../../types/version.type';
+import { type SemVerVersion } from '../../utilities/sem-ver.utilities';
 
 /**
  * The migration entity that is stored in the db.
@@ -18,7 +18,7 @@ export class MigrationEntity extends BaseEntity {
      * The version at which this migration should run.
      */
     @Property.string({ unique: true })
-    version!: Version;
+    version!: SemVerVersion;
 
     /**
      * The timestamp at which the migration ran.