@veducio/keja 0.0.0-stage → 0.2.3

package/src/versioning/define.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { defineRoute, response } from "../route/define.ts";
+import {
+  defineVersions,
+  parseReleasedAt,
+  resolveVersionToken,
+} from "./define.ts";
+
+const versions = defineVersions({
+  v1: { releasedAt: "2020-01-15" },
+  v2: { releasedAt: "01-06-2024" },
+}).versions;
+
+describe("parseReleasedAt", () => {
+  it("accepts calendar dates and unix timestamps", () => {
+    expect(parseReleasedAt("2020-09-20")).toBe(Date.UTC(2020, 8, 20));
+    expect(parseReleasedAt("20-09-2020")).toBe(Date.UTC(2020, 8, 20));
+    expect(parseReleasedAt(1_600_560_000)).toBe(1_600_560_000_000);
+    expect(parseReleasedAt(1_600_560_000_000)).toBe(1_600_560_000_000);
+    expect(parseReleasedAt("2020-13-40")).toBeNull();
+  });
+});
+
+describe("defineVersions", () => {
+  it("accepts v followed by a whole number", () => {
+    expect(
+      defineVersions({
+        v0: { releasedAt: "2020-01-15" },
+        v10: { releasedAt: "2024-06-01" },
+      }).versions.map((version) => version.number),
+    ).toEqual([0, 10]);
+  });
+
+  it("rejects a version that is not v followed by a whole number", () => {
+    expect(() =>
+      defineVersions({
+        "v1.2": { releasedAt: "2020-01-15" },
+      } as never),
+    ).toThrow("Version v1.2 must use the form v1, v2, v3");
+    expect(() =>
+      defineVersions({
+        v01: { releasedAt: "2020-01-15" },
+      } as never),
+    ).toThrow("Version v01 must use the form v1, v2, v3");
+  });
+});
+
+describe("defineRoute version", () => {
+  it("rejects a version that is not v followed by a whole number", () => {
+    expect(() =>
+      defineRoute({
+        method: "get",
+        path: "/users",
+        version: "v1.2",
+        responses: {
+          Ok: response({ code: 200, json: z.object({}) }),
+        },
+        handler: () => new Response(),
+      } as never),
+    ).toThrow("Version v1.2 must use the form v1, v2, v3");
+  });
+});
+
+describe("resolveVersionToken", () => {
+  it("selects the newest version that is not after the requested date", () => {
+    expect(resolveVersionToken("2020-09-20", versions)?.id).toBe("v1");
+    expect(resolveVersionToken("2024-06-01", versions)?.id).toBe("v2");
+    expect(resolveVersionToken("15-01-2020", versions)?.id).toBe("v1");
+    expect(resolveVersionToken("2019-01-01", versions)).toBeNull();
+  });
+
+  it("selects named versions and the latest keyword", () => {
+    expect(resolveVersionToken("v1", versions)?.id).toBe("v1");
+    expect(resolveVersionToken("v9", versions)).toBeNull();
+    expect(resolveVersionToken("latest", versions)?.id).toBe("v2");
+    expect(resolveVersionToken("CURRENT", versions)?.id).toBe("v2");
+  });
+});

package/src/versioning/define.ts

@@ -0,0 +1,173 @@
+import { projectError } from "../errors/framework-errors.ts";
+
+export type VersionDefinition = {
+  id: string;
+  number: number;
+  releasedAt: number;
+};
+
+const versionKey = /^v(0|[1-9]\d*)$/;
+const isoDate = /^(\d{4})-(\d{2})-(\d{2})$/;
+const dayMonthYear = /^(\d{2})-(\d{2})-(\d{4})$/;
+
+export function parseReleasedAt(value: string | number): number | null {
+  if (typeof value === "number") {
+    return unixMilliseconds(value);
+  }
+  const text = value.trim();
+  if (/^\d+$/.test(text)) {
+    return unixMilliseconds(Number(text));
+  }
+  const iso = isoDate.exec(text);
+  if (iso) {
+    return calendarUtc(Number(iso[1]), Number(iso[2]), Number(iso[3]));
+  }
+  const dmy = dayMonthYear.exec(text);
+  if (dmy) {
+    return calendarUtc(Number(dmy[3]), Number(dmy[2]), Number(dmy[1]));
+  }
+  return null;
+}
+
+type WholeNumber<Value extends string> = Value extends `${bigint}`
+  ? Value extends `-${string}` | `0${string}`
+    ? Value extends "0"
+      ? Value
+      : never
+    : Value
+  : never;
+
+export type VersionId<Value extends string> = Value extends `v${infer Rest}`
+  ? WholeNumber<Rest> extends never
+    ? never
+    : Value
+  : never;
+
+type VersionRecord = Record<string, { releasedAt: string | number }>;
+
+type CheckedVersions<Versions extends VersionRecord> = {
+  [Key in keyof Versions]: Key extends string
+    ? VersionId<Key> extends never
+      ? "Version must use the form v1, v2, v3"
+      : Versions[Key]
+    : never;
+};
+
+export function readVersionNumber(id: string): number | null {
+  const match = versionKey.exec(id);
+  if (!match) {
+    return null;
+  }
+  const number = Number(match[1]);
+  if (!Number.isSafeInteger(number) || String(number) !== match[1]) {
+    return null;
+  }
+  return number;
+}
+
+export function defineVersions<const Versions extends VersionRecord>(
+  versions: Versions & CheckedVersions<Versions>,
+) {
+  const parsed = Object.entries(versions).map(([id, version]) => {
+    const number = readVersionNumber(id);
+    if (number === null) {
+      throw projectError(
+        "invalidVersionId",
+        `Version ${id} must use the form v1, v2, v3`,
+      );
+    }
+    const releasedAt = parseReleasedAt(version.releasedAt);
+    if (releasedAt === null) {
+      throw projectError(
+        "invalidReleaseDate",
+        `Version ${id} has an invalid release date`,
+      );
+    }
+    return {
+      id,
+      number,
+      releasedAt,
+    };
+  });
+  return {
+    versions: parsed.sort(compareVersions),
+  };
+}
+
+export function isVersions(
+  value: unknown,
+): value is { versions: VersionDefinition[] } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "versions" in value &&
+    Array.isArray(value.versions)
+  );
+}
+
+export function newestVersion(versions: readonly VersionDefinition[]) {
+  return [...versions].sort(compareVersions).at(-1) ?? null;
+}
+
+export function resolveVersionToken(
+  token: string,
+  versions: readonly VersionDefinition[],
+) {
+  if (versions.length === 0) {
+    return null;
+  }
+  const keyword = token.toLowerCase();
+  if (keyword === "latest" || keyword === "current") {
+    return newestVersion(versions);
+  }
+  if (versionKey.test(token)) {
+    return versions.find((version) => version.id === token) ?? null;
+  }
+  const releasedAt = parseReleasedAt(token);
+  if (releasedAt === null) {
+    return null;
+  }
+  const eligible = versions.filter(
+    (version) => version.releasedAt <= releasedAt,
+  );
+  return newestVersion(eligible);
+}
+
+export function isAfterVersion(
+  candidate: VersionDefinition,
+  requested: VersionDefinition,
+) {
+  if (candidate.releasedAt !== requested.releasedAt) {
+    return candidate.releasedAt > requested.releasedAt;
+  }
+  return candidate.number > requested.number;
+}
+
+function unixMilliseconds(value: number) {
+  if (!Number.isFinite(value) || value < 0) {
+    return null;
+  }
+  return value >= 1_000_000_000_000 ? value : value * 1000;
+}
+
+function calendarUtc(year: number, month: number, day: number) {
+  if (month < 1 || month > 12 || day < 1 || day > 31) {
+    return null;
+  }
+  const date = new Date(Date.UTC(year, month - 1, day));
+  if (
+    date.getUTCFullYear() !== year ||
+    date.getUTCMonth() !== month - 1 ||
+    date.getUTCDate() !== day
+  ) {
+    return null;
+  }
+  return date.getTime();
+}
+
+function compareVersions(left: VersionDefinition, right: VersionDefinition) {
+  if (left.releasedAt !== right.releasedAt) {
+    return left.releasedAt - right.releasedAt;
+  }
+  return left.number - right.number;
+}

package/src/versioning/select.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { defineRoute, response } from "../route/define.ts";
+import { defineVersions } from "./define.ts";
+import { selectRoute } from "./select.ts";
+
+const versions = defineVersions({
+  v1: { releasedAt: "2020-01-15" },
+  v2: { releasedAt: "2024-06-01" },
+}).versions;
+
+const user = z.object({ id: z.string() });
+
+const routes = [
+  defineRoute({
+    method: "get",
+    path: "/users/:id",
+    version: "v1",
+    request: { params: user },
+    responses: {
+      User: response({ code: 200, json: user }),
+    },
+    handler: ({ params, respond }) => respond.User(params),
+  }),
+  defineRoute({
+    method: "get",
+    path: "/reports",
+    version: "v2",
+    responses: {
+      Ready: response({ code: 200, json: z.object({ ok: z.literal(true) }) }),
+    },
+    handler: ({ respond }) => respond.Ready({ ok: true }),
+  }),
+];
+
+describe("selectRoute", () => {
+  it("uses the newest handler that is not after the requested version", () => {
+    const v2 = versions.find((version) => version.id === "v2");
+    const v1 = versions.find((version) => version.id === "v1");
+    if (!v2 || !v1) {
+      throw new Error("missing versions");
+    }
+    expect(
+      selectRoute(routes, versions, "GET", "/users/1", v2)?.route.version,
+    ).toBe("v1");
+    expect(selectRoute(routes, versions, "GET", "/reports", v1)).toBeNull();
+    expect(
+      selectRoute(routes, versions, "GET", "/reports", v2)?.route.version,
+    ).toBe("v2");
+  });
+
+  it("matches a route nested several segments deep", () => {
+    const v1 = versions.find((version) => version.id === "v1");
+    if (!v1) {
+      throw new Error("missing versions");
+    }
+    const deep = defineRoute({
+      method: "get",
+      path: "/orgs/:orgId/teams/:teamId/members/:memberId",
+      version: "v1",
+      responses: {
+        Member: response({ code: 200, json: z.object({ id: z.string() }) }),
+      },
+      handler: ({ respond }) => respond.Member({ id: "ada" }),
+    });
+    const selected = selectRoute(
+      [deep],
+      versions,
+      "GET",
+      "/orgs/acme/teams/core/members/ada",
+      v1,
+    );
+    expect(selected?.params).toEqual({
+      orgId: "acme",
+      teamId: "core",
+      memberId: "ada",
+    });
+  });
+});

package/src/versioning/select.ts

@@ -0,0 +1,62 @@
+import type { RouteDefinition } from "../route/define.ts";
+import {
+  isAfterVersion,
+  type VersionDefinition,
+} from "../versioning/define.ts";
+
+export function matchPath(pattern: string, pathname: string) {
+  const expected = segments(pattern);
+  const actual = segments(pathname);
+  if (expected.length !== actual.length) {
+    return null;
+  }
+  const params: Record<string, string> = {};
+  for (const [index, part] of expected.entries()) {
+    const value = actual[index] ?? "";
+    if (part.startsWith(":")) {
+      params[part.slice(1)] = decodeURIComponent(value);
+      continue;
+    }
+    if (part !== value) {
+      return null;
+    }
+  }
+  return params;
+}
+
+export function selectRoute(
+  routes: readonly RouteDefinition[],
+  versions: readonly VersionDefinition[],
+  method: string,
+  pathname: string,
+  requested: VersionDefinition,
+) {
+  const matches = [];
+  for (const route of routes) {
+    if (route.method !== method.toLowerCase()) {
+      continue;
+    }
+    const params = matchPath(route.path, pathname);
+    if (!params) {
+      continue;
+    }
+    const version = versions.find((item) => item.id === route.version);
+    if (!version || isAfterVersion(version, requested)) {
+      continue;
+    }
+    matches.push({ route, params, version });
+  }
+  matches.sort((left, right) => {
+    if (left.version.releasedAt !== right.version.releasedAt) {
+      return right.version.releasedAt - left.version.releasedAt;
+    }
+    return right.version.number - left.version.number;
+  });
+  return matches[0] ?? null;
+}
+
+function segments(value: string) {
+  const normalized =
+    value.length > 1 && value.endsWith("/") ? value.slice(0, -1) : value;
+  return normalized.split("/").filter((part) => part.length > 0);
+}