zibri 2.4.0 → 2.5.0

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

@@ -2,7 +2,7 @@ import { MigrationEntity } from './migration-entity.model';
 import { repositoryTokenFor } from '../../di/decorators/inject-repository.decorator';
 import { inject } from '../../di/inject.function';
 import { Newable } from '../../types/newable.type';
-import { Version } from '../../types/version.type';
+import { SemVerVersion } from '../../utilities/sem-ver.utilities';
 import { DataSourceInterface } from '../data-sources/data-source.interface';
 import { Repository } from '../repository';
 import { Transaction } from '../transaction/transaction.model';
@@ -11,7 +11,7 @@ import { Transaction } from '../transaction/transaction.model';
  * Base class for a data source migration.
  */
 export abstract class Migration {
-    abstract readonly version: Version;
+    abstract readonly version: SemVerVersion;
     /**
      * The data source that the migration is for.
      */

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

@@ -19,8 +19,9 @@ 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 { Version } from '../../types/version.type';
-import { PostgresDataSource, PostgresOptions } from '../data-sources/postgres-data-source.model';
+import { OmitStrict } from '../../types/omit-strict.type';
+import { SemVerVersion } from '../../types/version.type';
+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';
@@ -33,7 +34,7 @@ class LegacyItem {
 
 @DataSource()
 class LegacyDbDataSource extends PostgresDataSource {
-    options: PostgresOptions = {
+    options: OmitStrict<PostgresOptions, 'type'> = {
         host: 'localhost',
         username: 'postgres',
         password: 'password',
@@ -54,7 +55,7 @@ class Item {
 
 @DataSource()
 class DbDataSource extends PostgresDataSource {
-    options: PostgresOptions = {
+    options: OmitStrict<PostgresOptions, 'type'> = {
         host: 'localhost',
         username: 'postgres',
         password: 'password',
@@ -67,7 +68,7 @@ class DbDataSource extends PostgresDataSource {
 
 @Injectable()
 class AddTestValueMigration extends Migration {
-    version: Version = '0.0.1';
+    version: SemVerVersion = '0.0.1';
 
     constructor(
         @InjectRepository(Item)

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'>>;

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

@@ -1,27 +1,28 @@
-import { BaseWhereFilter } from './base-where-filter.model';
+import { BaseWhereFilter, BaseWhereFilterObject } from './base-where-filter.model';
 
 /**
- * A filter for a date where property.
+ * The date where filter object.
  */
-export type DateWhereFilter = BaseWhereFilter<Date> | {
-    /**
-     * The property needs to be not this value.
-     */
-    not?: Date,
+type DateFilterWhereObject = BaseWhereFilterObject<Date> & {
     /**
-     * The property needs to be one of the values in the array.
+     * The property needs to be after the date.
      */
-    oneOf?: Date[],
+    after?: Date,
     /**
-     * The property needs to be NOT one of the values in the array.
+     * The property needs to be before the date.
      */
-    notOneOf?: Date[],
+    before?: Date,
     /**
-     * The property needs to be after the value.
+     * The property needs to be after or on the date.
      */
-    after?: Date,
+    afterOrOn?: Date,
     /**
-     * The property needs to be before the value.
+     * The property needs to be before or on the date.
      */
-    before?: Date
-};
+    beforeOrOn?: Date
+};
+
+/**
+ * A filter for a date where property.
+ */
+export type DateWhereFilter = BaseWhereFilter<Date, DateFilterWhereObject>;

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

@@ -1,21 +1,9 @@
-import { BaseWhereFilter } from './base-where-filter.model';
+import { BaseWhereFilter, BaseWhereFilterObject } from './base-where-filter.model';
 
 /**
- * A filter for a number where property.
+ * The number where filter object.
  */
-export type NumberWhereFilter<T extends number | bigint> = BaseWhereFilter<T> | {
-    /**
-     * The property needs to be not this value.
-     */
-    not?: T,
-    /**
-     * The property needs to be one of the values in the array.
-     */
-    oneOf?: T[],
-    /**
-     * The property needs to be NOT one of the values in the array.
-     */
-    notOneOf?: T[],
+type NumberWhereFilterObject<T extends number | bigint> = BaseWhereFilterObject<T> & {
     /**
      * The property needs to be greater than the provided value.
      */
@@ -32,4 +20,9 @@ export type NumberWhereFilter<T extends number | bigint> = BaseWhereFilter<T> |
      * The property needs to be lesser than or equal to the provided value.
      */
     lesserThanEquals?: T
-};
+};
+
+/**
+ * A filter for a number where property.
+ */
+export type NumberWhereFilter<T extends number | bigint> = BaseWhereFilter<T, NumberWhereFilterObject<T>>;

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

@@ -3,10 +3,69 @@ import { Where } from './where-filter.model';
 /**
  * A filter for a object where property.
  */
-export type ObjectWhereFilter<T extends Object> = null
-    // eslint-disable-next-line jsdoc/require-jsdoc
-    | { equals: T, where?: never, not?: never, oneOf?: never, notOneOf?: never }
-    // eslint-disable-next-line jsdoc/require-jsdoc
-    | { equals?: never, where: Where<T>, not?: never, oneOf?: never, notOneOf?: never }
-    // eslint-disable-next-line jsdoc/require-jsdoc
-    | { equals?: never, where?: never, not?: T, oneOf?: T[], notOneOf?: T[] };
+export type ObjectWhereFilter<T extends Object> = {
+    /**
+     * The property needs to equal the value.
+     */
+    is: T | null,
+    /**
+     * A where condition that the property needs to match.
+     */
+    where?: never,
+    /**
+     * The property needs to be not this value.
+     */
+    not?: never,
+    /**
+     * The property should be one of the provided values.
+     */
+    oneOf?: never,
+    /**
+     * The property should NOT be one of the provided values.
+     */
+    notOneOf?: never
+}
+| {
+    /**
+     * The property needs to equal the value.
+     */
+    is?: never,
+    /**
+     * A where condition that the property needs to match.
+     */
+    where: Where<T>,
+    /**
+     * The property needs to be not this value.
+     */
+    not?: never,
+    /**
+     * The property should be one of the provided values.
+     */
+    oneOf?: never,
+    /**
+     * The property should NOT be one of the provided values.
+     */
+    notOneOf?: never
+}
+| {
+    /**
+     * The property needs to equal the value.
+     */
+    is?: never,
+    /**
+     * A where condition that the property needs to match.
+     */
+    where?: never,
+    /**
+     * The property needs to be not this value.
+     */
+    not?: T | null,
+    /**
+     * The property should be one of the provided values.
+     */
+    oneOf?: (T | null)[],
+    /**
+     * The property should NOT be one of the provided values.
+     */
+    notOneOf?: (T | null)[]
+};

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

@@ -1,21 +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 { Percentage } from '../../../types/percentage.type';
 
 /**
- * A filter for a string where property.
+ * The string where filter object.
  */
-export type StringWhereFilter = BaseWhereFilter<string> | {
-    /**
-     * The property needs to be not this value.
-     */
-    not?: string,
-    /**
-     * The property needs to be one of the values in the array.
-     */
-    oneOf?: string[],
-    /**
-     * The property needs to be NOT one of the values in the array.
-     */
-    notOneOf?: string[],
+type StringWhereFilterObject = BaseWhereFilterObject<string> & {
     /**
      * The property needs to be like the provided string.
      * @example '%.com'
@@ -25,5 +15,25 @@ export type StringWhereFilter = BaseWhereFilter<string> | {
      * The property needs to be like the provided string, ignoring case.
      * @example '%.cOm'
      */
-    iLike?: string
-};
+    iLike?: string,
+    /**
+     * The property needs to fuzzily be like the provided string so that eg. Typos don't matter.
+     */
+    fuzzyLike?: {
+        /**
+         * The search value.
+         */
+        value: string,
+        /**
+         * The minimum similarity that the search term must have as a percentage between 1 and 99.
+         *
+         * 1 matches almost everything while 99 is basically just a strict equal.
+         */
+        minSimilarity?: ExcludeStrict<Percentage, 0 | 100>
+    }
+};
+
+/**
+ * A filter for a string where property.
+ */
+export type StringWhereFilter = BaseWhereFilter<string, StringWhereFilterObject>;

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

@@ -0,0 +1,91 @@
+
+import { ArrayWhereFilter, ObjectArrayWhereFilter } from './array-where-filter.model';
+import { BooleanWhereFilter } from './boolean-where-filter.model';
+import { DateWhereFilter } from './date-where-filter.model';
+import { NumberWhereFilter } from './number-where-filter.model';
+import { ObjectWhereFilter } from './object-where-filter.model';
+import { StringWhereFilter } from './string-where-filter.model';
+import { ExcludeStrict } from '../../../types/exclude-strict.type';
+import { ObjectUtilities } from '../../../utilities/object.utilities';
+
+/**
+ * Where filter keys of object properties.
+ */
+type ObjectWhereFilterKeys = keyof ObjectWhereFilter<object>;
+
+/**
+ * Where filter keys of array properties.
+ */
+type ArrayWhereFilterKeys = keyof ExcludeStrict<ArrayWhereFilter<object>, null | object[]>;
+
+/**
+ * Where filter keys of object array properties.
+ */
+type ObjectArrayWhereFilterKeys = keyof ExcludeStrict<ObjectArrayWhereFilter<object>, null | object[]>;
+
+/**
+ * Where filter keys of boolean properties.
+ */
+type BooleanWhereFilterKeys = keyof BooleanWhereFilter;
+
+/**
+ * Where filter keys of date properties.
+ */
+type DateWhereFilterKeys = keyof ExcludeStrict<DateWhereFilter, null | Date>;
+
+/**
+ * Where filter keys of number properties.
+ */
+type NumberWhereFilterKeys = keyof ExcludeStrict<NumberWhereFilter<number | bigint>, null | (number | bigint)>;
+
+/**
+ * Where filter keys of string properties.
+ */
+type StringWhereFilterKeys = keyof ExcludeStrict<StringWhereFilter, null | string>;
+
+/**
+ * All where filter keys.
+ */
+export type WhereFilterKeys = ArrayWhereFilterKeys
+    | ObjectArrayWhereFilterKeys
+    | BooleanWhereFilterKeys
+    | DateWhereFilterKeys
+    | NumberWhereFilterKeys
+    | ObjectWhereFilterKeys
+    | StringWhereFilterKeys;
+
+const whereFilterKeysRecord: Record<WhereFilterKeys, WhereFilterKeys> = {
+    not: 'not',
+    like: 'like',
+    oneOf: 'oneOf',
+    notOneOf: 'notOneOf',
+    after: 'after',
+    afterOrOn: 'afterOrOn',
+    before: 'before',
+    beforeOrOn: 'beforeOrOn',
+    greaterThan: 'greaterThan',
+    greaterThanEquals: 'greaterThanEquals',
+    lesserThan: 'lesserThan',
+    lesserThanEquals: 'lesserThanEquals',
+    iLike: 'iLike',
+    fuzzyLike: 'fuzzyLike',
+    is: 'is',
+    where: 'where',
+    includes: 'includes',
+    isIncludedIn: 'isIncludedIn',
+    length: 'length',
+    lengthGreaterThan: 'lengthGreaterThan',
+    lengthLesserThanEquals: 'lengthLesserThanEquals',
+    lengthGreaterThanEquals: 'lengthGreaterThanEquals',
+    lengthLesserThan: 'lengthLesserThan'
+};
+const whereFilterKeySet: Set<WhereFilterKeys> = new Set<WhereFilterKeys>(ObjectUtilities.values(whereFilterKeysRecord));
+
+// eslint-disable-next-line jsdoc/require-returns
+/**
+ * Checks if the given key is a where filter key.
+ * @param key - The key to check.
+ */
+export function isWhereFilterKey(key: unknown): key is WhereFilterKeys {
+    return whereFilterKeySet.has(key as WhereFilterKeys);
+}