zibri 2.4.0 → 2.5.0

package/src/utilities/sem-ver.utilities.ts

@@ -0,0 +1,270 @@
+import { isNumeric } from './is-numeric.function';
+import { SemVerMatcher } from '../versioning/supported-versions-options.model';
+
+/**
+ * Definition for a SemVer version.
+ */
+export type SemVerVersion = `${number}.${number}.${number}`;
+
+/**
+ * Semver tuple consisting of major, minor and patch.
+ */
+type SemVerTuple = readonly [number, number, number];
+
+/**
+ * A sem ver range, consisting of a min and max version .
+ */
+type SemVerRangeBounds = {
+    /**
+     * The minimum sem ver version.
+     */
+    min: SemVerTuple,
+    /**
+     * The maximum sem ver version.
+     */
+    max: SemVerTuple
+};
+
+/**
+ * Encapsulates functionalities around handling semver versions.
+ */
+export abstract class SemVerUtilities {
+    /**
+     * Checks whether the given value is a valid SemVer version.
+     * @param value - The value to check.
+     * @returns True if the value is in the format "number.number.number", false otherwise.
+     */
+    static isSemVerVersion(value: string): value is SemVerVersion {
+        const parts: string[] = value.split('.');
+        if (parts.length !== 3) {
+            return false;
+        }
+
+        return parts.every(isNumeric);
+    }
+
+    /**
+     * Compares the given versions and checks if the first one is bigger, equal or smaller than the second one.
+     * @param v1 - The first version.
+     * @param v2 - The second version to compare against.
+     * @returns 'bigger', 'equal' or 'smaller'.
+     */
+    static compare(v1: SemVerVersion, v2: SemVerVersion): 'bigger' | 'equal' | 'smaller' {
+        const result: number = this.compareTuple(this.parseStrict(v1), this.parseStrict(v2));
+        if (result > 0) {
+            return 'bigger';
+        }
+        if (result < 0) {
+            return 'smaller';
+        }
+        return 'equal';
+    }
+
+    /**
+     * Checks if the given semver matcher overlaps with one of the provided matchers.
+     * @param version - The version/matcher to check.
+     * @param matchers - The matchers to check against.
+     * @returns True if the version/matcher overlaps with at least one matcher, false otherwise.
+     */
+    static matches(version: SemVerMatcher, matchers: SemVerMatcher[]): boolean {
+        const versionRange: SemVerRangeBounds = this.toRange(version);
+        return matchers.some((matcher: SemVerMatcher) => this.intersects(versionRange, this.toRange(matcher)));
+    }
+
+    private static toRange(matcher: SemVerMatcher): SemVerRangeBounds {
+        const parts: string[] = matcher.trim().split(/\s+/)
+            .filter(Boolean);
+
+        return parts.reduce<SemVerRangeBounds>(
+            (acc: SemVerRangeBounds, part: string) => this.intersect(acc, this.atomicRange(part)),
+            this.fullRange()
+        );
+    }
+
+    private static atomicRange(matcher: string): SemVerRangeBounds {
+        if (matcher.startsWith('^')) {
+            return this.caretRange(matcher.slice(1));
+        }
+
+        if (matcher.startsWith('~')) {
+            return this.tildeRange(matcher.slice(1));
+        }
+
+        if (matcher.startsWith('>=')) {
+            return {
+                min: this.parseStrict(matcher.slice(2)),
+                max: this.infinity()
+            };
+        }
+
+        if (matcher.startsWith('>')) {
+            return {
+                min: this.increment(this.parseStrict(matcher.slice(1))),
+                max: this.infinity()
+            };
+        }
+
+        if (matcher.startsWith('<=')) {
+            return {
+                min: this.zero(),
+                max: this.increment(this.parseStrict(matcher.slice(2)))
+            };
+        }
+
+        if (matcher.startsWith('<')) {
+            return {
+                min: this.zero(),
+                max: this.parseStrict(matcher.slice(1))
+            };
+        }
+
+        const exact: SemVerTuple = this.parseStrict(matcher);
+        return {
+            min: exact,
+            max: this.increment(exact)
+        };
+    }
+
+    private static caretRange(raw: string): SemVerRangeBounds {
+        const [major, minor, patch] = this.parseLoose(raw);
+        const min: SemVerTuple = [major, minor, patch];
+
+        if (major > 0) {
+            return {
+                min,
+                max: [major + 1, 0, 0]
+            };
+        }
+
+        if (minor > 0) {
+            return {
+                min,
+                max: [0, minor + 1, 0]
+            };
+        }
+
+        return {
+            min,
+            max: [0, 0, patch + 1]
+        };
+    }
+
+    private static tildeRange(raw: string): SemVerRangeBounds {
+        const parts: string[] = raw.split('.');
+
+        if (parts.length < 1 || parts.length > 3) {
+            throw new Error(`Invalid semver matcher: ~${raw}`);
+        }
+
+        const [major, minor, patch] = this.parseLoose(raw);
+        const min: SemVerTuple = [major, minor, patch];
+
+        if (parts.length >= 2) {
+            return {
+                min,
+                max: [major, minor + 1, 0]
+            };
+        }
+
+        return {
+            min,
+            max: [major + 1, 0, 0]
+        };
+    }
+
+    private static parseStrict(version: string): SemVerTuple {
+        if (!this.isSemVerVersion(version)) {
+            throw new Error(`Invalid semver version: ${version}`);
+        }
+
+        const [major, minor, patch] = version.split('.').map(Number);
+        return [major, minor, patch];
+    }
+
+    private static parseLoose(version: string): SemVerTuple {
+        const parts: string[] = version.split('.');
+
+        if (parts.length < 1 || parts.length > 3) {
+            throw new Error(`Invalid semver matcher: ${version}`);
+        }
+
+        const [majorRaw, minorRaw, patchRaw] = parts;
+
+        if (
+            !isNumeric(majorRaw)
+            || (minorRaw !== undefined && !isNumeric(minorRaw))
+            || (patchRaw !== undefined && !isNumeric(patchRaw))
+        ) {
+            throw new Error(`Invalid semver matcher: ${version}`);
+        }
+
+        return [
+            Number(majorRaw),
+            Number(minorRaw ?? 0),
+            Number(patchRaw ?? 0)
+        ];
+    }
+
+    private static compareTuple(a: SemVerTuple, b: SemVerTuple): number {
+        if (a[0] > b[0]) {
+            return 1;
+        }
+        if (a[0] < b[0]) {
+            return -1;
+        }
+
+        if (a[1] > b[1]) {
+            return 1;
+        }
+        if (a[1] < b[1]) {
+            return -1;
+        }
+
+        if (a[2] > b[2]) {
+            return 1;
+        }
+        if (a[2] < b[2]) {
+            return -1;
+        }
+
+        return 0;
+    }
+
+    private static intersect(a: SemVerRangeBounds, b: SemVerRangeBounds): SemVerRangeBounds {
+        return {
+            min: this.maxTuple(a.min, b.min),
+            max: this.minTuple(a.max, b.max)
+        };
+    }
+
+    private static intersects(a: SemVerRangeBounds, b: SemVerRangeBounds): boolean {
+        return this.compareTuple(this.maxTuple(a.min, b.min), this.minTuple(a.max, b.max)) < 0;
+    }
+
+    private static minTuple(a: SemVerTuple, b: SemVerTuple): SemVerTuple {
+        return this.compareTuple(a, b) <= 0 ? a : b;
+    }
+
+    private static maxTuple(a: SemVerTuple, b: SemVerTuple): SemVerTuple {
+        return this.compareTuple(a, b) >= 0 ? a : b;
+    }
+
+    private static increment([major, minor, patch]: SemVerTuple): SemVerTuple {
+        return [major, minor, patch + 1];
+    }
+
+    private static zero(): SemVerTuple {
+        return [0, 0, 0];
+    }
+
+    private static infinity(): SemVerTuple {
+        return [Number.POSITIVE_INFINITY, 0, 0];
+    }
+
+    private static fullRange(): SemVerRangeBounds {
+        return {
+            min: this.zero(),
+            max: this.infinity()
+        };
+    }
+}

package/src/utilities/typeorm.utilities.ts

@@ -0,0 +1,75 @@
+import { DataSource, EntityTarget, EntityMetadata as TOEntityMetadata } from 'typeorm';
+import { ColumnMetadata } from 'typeorm/metadata/ColumnMetadata.js';
+
+import { ColumnType } from '../data-source/models/column-type.model';
+import { Transaction } from '../data-source/transaction/transaction.model';
+import { BaseEntity } from '../entity/base-entity.model';
+
+/**
+ * Utilities for dealing with typeorm.
+ */
+export abstract class TypeOrmUtilities {
+    /**
+     * Gets the metadata for a typeorm column.
+     * @param target - The entity.
+     * @param propertyName - The name of the property to get the column metadata for.
+     * @param transaction - The transaction to use to get the column metadata.
+     * @returns The typeorm column metadata.
+     * @throws When the provided propertyName could not be found as a column.
+     */
+    static getColumnMetadata<T extends BaseEntity>(
+        target: EntityTarget<T>,
+        propertyName: keyof T | string & {},
+        transaction: Transaction
+    ): ColumnMetadata {
+        const metadata: TOEntityMetadata = this.getEntityMetadata(target, transaction);
+        const column: ColumnMetadata | undefined = metadata.columns.find(
+            (col) => col.propertyName === propertyName
+        );
+
+        if (!column) {
+            throw new Error(
+                `Column ${propertyName.toString()} not found in model`
+            );
+        }
+
+        return column;
+    }
+
+    /**
+     * Gets the typeorm metadata for a given entity.
+     * @param target - The target entity.
+     * @param transaction - The transaction to run this command with.
+     * @returns The typeorm metadata.
+     */
+    static getEntityMetadata<T extends BaseEntity>(target: EntityTarget<T>, transaction: Transaction): TOEntityMetadata {
+        return transaction.queryRunner.connection.getMetadata(target);
+    }
+
+    // eslint-disable-next-line jsdoc/require-param
+    /**
+     * Normalizes the type of the given column using the provided dataSource.
+     * @returns The normalized column type as a string.
+     * @throws When no dataSource has been provided.
+     */
+    static normalizeColumnType(
+        dataSource: DataSource | undefined,
+        column: {
+            // eslint-disable-next-line jsdoc/require-jsdoc
+            type?: ColumnType | string & {},
+            // eslint-disable-next-line jsdoc/require-jsdoc
+            length?: number | string,
+            // eslint-disable-next-line jsdoc/require-jsdoc
+            precision?: number | null,
+            // eslint-disable-next-line jsdoc/require-jsdoc
+            scale?: number,
+            // eslint-disable-next-line jsdoc/require-jsdoc
+            isArray?: boolean
+        }
+    ): string {
+        if (!dataSource) {
+            throw new Error('The data source needs to be initialized before it can be used.');
+        }
+        return dataSource.driver.normalizeType(column);
+    }
+}

package/src/utilities/uuid.utilities.ts

@@ -1,4 +1,4 @@
-import { v4 } from 'uuid';
+import { randomUUID } from 'node:crypto';
 
 /**
  * Utilities for dealing with uuid.
@@ -9,6 +9,6 @@ export abstract class UUIDUtilities {
      * @returns A v4 uuid string.
      */
     static generate(): string {
-        return v4();
+        return randomUUID();
     }
 }

package/src/validation/validation-problem.model.ts

@@ -1,10 +1,11 @@
 import { BaseEntity } from '../entity/base-entity.model';
 import { RelationMetadata } from '../entity/decorators/property.decorator';
+import { BelongsToOnePropertyMetadata } from '../entity/models/belongs-to-one-property-metadata.model';
 import { FileSize } from '../entity/models/file-property-metadata.model';
+import { HasOnePropertyMetadata } from '../entity/models/has-one-property-metadata.model';
 import { ManyToManyPropertyMetadata } from '../entity/models/many-to-many-property-metadata.model';
 import { ManyToOnePropertyMetadata } from '../entity/models/many-to-one-property-metadata.model';
 import { OneToManyPropertyMetadata } from '../entity/models/one-to-many-property-metadata.model';
-import { OneToOnePropertyMetadata } from '../entity/models/one-to-one-property-metadata.model';
 import { Relation } from '../entity/models/relation.enum';
 import { MimeType } from '../http/mime-type.enum';
 
@@ -82,15 +83,12 @@ export class RelationsNotAllowedValidationProblem implements ValidationProblem {
 
     private getExample(metadata: RelationMetadata<BaseEntity>, relationKey: string): string {
         switch (metadata.type) {
-            case Relation.MANY_TO_ONE: {
-                return this.getObjectExample(metadata, relationKey);
-            }
-            case Relation.ONE_TO_MANY: {
-                return this.getArrayExample(metadata, relationKey);
-            }
-            case Relation.ONE_TO_ONE: {
+            case Relation.MANY_TO_ONE:
+            case Relation.HAS_ONE:
+            case Relation.BELONGS_TO_ONE: {
                 return this.getObjectExample(metadata, relationKey);
             }
+            case Relation.ONE_TO_MANY:
             case Relation.MANY_TO_MANY: {
                 return this.getArrayExample(metadata, relationKey);
             }
@@ -110,7 +108,7 @@ export class RelationsNotAllowedValidationProblem implements ValidationProblem {
     }
 
     private getObjectExample(
-        metadata: OneToOnePropertyMetadata<BaseEntity> | ManyToOnePropertyMetadata<BaseEntity>,
+        metadata: BelongsToOnePropertyMetadata<BaseEntity> | HasOnePropertyMetadata<BaseEntity> | ManyToOnePropertyMetadata<BaseEntity>,
         relationKey: string
     ): string {
         return [

package/src/validation/validation.service.ts

@@ -10,6 +10,7 @@ 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 { PropertyMetadata, Property, RelationMetadata } from '../entity/decorators/property.decorator';
+import { Relation } from '../entity/models/relation.enum';
 import { ValidationError } from '../error-handling/errors/validation.error';
 import { MimeType } from '../http/mime-type.enum';
 import { FormData } from '../parsing/form-data/form-data.model';
@@ -224,10 +225,11 @@ export class ValidationService implements ValidationServiceInterface {
         const fullKey: string = parentKey ? `${parentKey}.${key}` : key;
 
         if (
-            metadata.type === 'many-to-one'
-            || metadata.type === 'one-to-many'
-            || metadata.type === 'one-to-one'
-            || metadata.type === 'many-to-many'
+            metadata.type === Relation.MANY_TO_ONE
+            || metadata.type === Relation.ONE_TO_MANY
+            || metadata.type === Relation.HAS_ONE
+            || metadata.type === Relation.BELONGS_TO_ONE
+            || metadata.type === Relation.MANY_TO_MANY
         ) {
             return [new RelationsNotAllowedValidationProblem(fullKey, metadata, key)];
         }

package/src/versioning/route-with-version-data.model.ts

@@ -0,0 +1,15 @@
+import { SupportedVersionsOptions } from './supported-versions-options.model';
+
+/**
+ * Defines a route identified by a key with their respective versions.
+ */
+export type RouteWithVersionData = {
+    /**
+     * The supported versions of the route.
+     */
+    versions: SupportedVersionsOptions,
+    /**
+     * The key that identifies the route.
+     */
+    key: string
+};

package/src/versioning/supported-versions-options.model.ts

@@ -0,0 +1,25 @@
+import { ExcludeStrict } from '../types/exclude-strict.type';
+import { SemVerVersion } from '../utilities/sem-ver.utilities';
+
+// eslint-disable-next-line jsdoc/require-jsdoc
+type SemVerRange = `^${number}` | `^${number}.${number}` | `^${SemVerVersion}`
+    | `~${number}` | `~${number}.${number}` | `~${SemVerVersion}`
+    | `>=${SemVerVersion}`
+    | `>${SemVerVersion}`
+    | `<=${SemVerVersion}`
+    | `<${SemVerVersion}`;
+
+/**
+ * Matcher for a version.
+ */
+export type VersionMatcher = 'latest' | '^latest' | '~latest' | SemVerVersion | SemVerRange | `${SemVerRange} ${SemVerRange}`;
+
+/**
+ * Matcher for a semver version.
+ */
+export type SemVerMatcher = ExcludeStrict<VersionMatcher, 'latest' | '^latest' | '~latest'>;
+
+/**
+ * The options available to define what versions are supported by eg. A route.
+ */
+export type SupportedVersionsOptions = 'all' | (VersionMatcher)[];

package/src/versioning/version.model.ts

@@ -0,0 +1,30 @@
+import { RouteWithVersionData } from './route-with-version-data.model';
+import { SemVerVersion } from '../utilities/sem-ver.utilities';
+
+/**
+ * A version, consisting of the actual version value and a starts end end date.
+ */
+export type Version = {
+    /**
+     * The actual version value in the SemVer format.
+     */
+    value: SemVerVersion,
+    /**
+     * The date after which this should be the active version. Used for date based version resolution.
+     */
+    startsAt: Date,
+    /**
+     * The end date of this version. Can be left open if the version is the current latest.
+     */
+    endsAt?: Date | null
+};
+
+/**
+ * Data stored inside of a version file.
+ */
+export type VersionFile = Version & {
+    /**
+     * The routes at the time of the version bump.
+     */
+    routes: RouteWithVersionData[]
+};

package/src/versioning/versioning-service.interface.ts

@@ -0,0 +1,39 @@
+import { SupportedVersionsOptions } from './supported-versions-options.model';
+import { Version, VersionFile } from './version.model';
+import { HttpRequestContext } from '../context/request/http-request.context';
+import { WebsocketRequestContext } from '../context/request/websocket-request.context';
+import { SemVerVersion } from '../utilities/sem-ver.utilities';
+
+/**
+ * Interface for a versioning service.
+ */
+export interface VersioningServiceInterface {
+    /**
+     * Resolves the version from the given request context.
+     */
+    resolveVersion: (context: HttpRequestContext | WebsocketRequestContext) => Version | Promise<Version>,
+    /**
+     * Checks if any of the given version options matches the resolved version.
+     */
+    matchesVersion: (versions: SupportedVersionsOptions, resolvedVersion: Version) => boolean,
+    /**
+     * Finds overlapping versions between two options.
+     */
+    findOverlappingVersions: (
+        a: SupportedVersionsOptions,
+        b: SupportedVersionsOptions,
+        currentLatest: SemVerVersion
+    ) => SupportedVersionsOptions,
+    /**
+     * Checks whether or not the given options have some overlap.
+     */
+    hasOverlappingVersions: (
+        a: SupportedVersionsOptions,
+        b: SupportedVersionsOptions,
+        currentLatest: SemVerVersion
+    ) => boolean,
+    /**
+     * Returns all versions created in the file system.
+     */
+    getVersions: () => VersionFile[]
+}