zibri 2.4.1 → 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/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/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[]
+}