@schafevormfenster/rest-commons 0.1.1

package/src/api-schemas/error.schema.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+export const ApiErrorSchema = z
+  .object({
+    status: z.number().min(400).max(599),
+    error: z.string(),
+    trace: z.any().optional(),
+  })
+  .strict();
+
+// Type export matching schema name (for @schafevormfenster/enforce-schema-type rule)
+export type ApiError = z.infer<typeof ApiErrorSchema>;
+
+// Class for error handling with instanceof checks and throwing
+export class ApiErrorConstructor extends Error {
+  readonly status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.status = status;
+    this.name = "ApiError";
+  }
+}

package/src/api-schemas/health.schema.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  ApiInfoSchema,
+  ApiStatusSchema,
+  HealthyApiStatusSchema,
+  HealthyServiceInfoSchema,
+  ServiceStatusSchema,
+  UnhealthyApiStatusSchema,
+  UnhealthyServiceInfoSchema,
+} from "./health.schema";
+
+describe("health.schema", () => {
+  it("parses healthy service info", () => {
+    const service = HealthyServiceInfoSchema.parse({
+      name: "Example",
+      status: 200,
+      message: "healthy",
+      version: "1.0.0",
+    });
+    expect(service.name).toBe("Example");
+    expect(service.status).toBe(200);
+    expect(service.message).toMatch(/healthy/i);
+  });
+
+  it("parses unhealthy service info", () => {
+    const service = UnhealthyServiceInfoSchema.parse({
+      name: "Example",
+      status: 503,
+      error: "Service unavailable",
+      version: "1.0.0",
+    });
+    expect(service.status).toBe(503);
+    expect(service.error).toMatch(/service unavailable/i);
+  });
+
+  it("parses healthy API status", () => {
+    const status = HealthyApiStatusSchema.parse({
+      status: 200,
+      name: "api",
+      version: "1.0.0",
+      description: "ok",
+      services: [
+        { name: "svc", status: 200, message: "healthy" },
+        { name: "svc2", status: 500, error: "fail" },
+      ],
+    });
+    expect(status.status).toBe(200);
+    expect(status.services).toHaveLength(2);
+  });
+
+  it("parses unhealthy API status", () => {
+    const status = UnhealthyApiStatusSchema.parse({
+      status: 500,
+      error: "bad",
+      name: "api",
+      version: "1.0.0",
+      services: [{ name: "svc", status: 500, error: "boom" }],
+    });
+    expect(status.error).toMatch(/bad/i);
+  });
+
+  it("ApiInfoSchema validates basic api info", () => {
+    const info = ApiInfoSchema.parse({
+      name: "api",
+      version: "1.2.3",
+      description: "desc",
+      services: [{ name: "svc", status: 200, message: "healthy" }],
+    });
+    expect(info.name).toBe("api");
+  });
+
+  it("ApiStatusSchema accepts both healthy and unhealthy variants", () => {
+    const healthy = ApiStatusSchema.parse({
+      status: 200,
+      name: "api",
+      version: "1.0.0",
+      services: [{ name: "svc", status: 200, message: "healthy" }],
+    });
+    expect(healthy.status).toBe(200);
+
+    const unhealthy = ApiStatusSchema.parse({
+      status: 503,
+      error: "down",
+      name: "api",
+      version: "1.0.0",
+      services: [{ name: "svc", status: 503, error: "down" }],
+    });
+    expect(unhealthy.status).toBe(503);
+  });
+
+  it("ServiceStatusSchema union validates both variants", () => {
+    expect(
+      ServiceStatusSchema.parse({
+        name: "svc",
+        status: 200,
+        message: "healthy",
+      })
+    ).toBeTruthy();
+    expect(
+      ServiceStatusSchema.parse({ name: "svc", status: 500, error: "err" })
+    ).toBeTruthy();
+  });
+});

package/src/api-schemas/health.schema.ts

@@ -0,0 +1,63 @@
+
+import { z } from "zod";
+
+import { ApiErrorSchema } from "./error.schema";
+import { OkaySchema } from "./okay.schema";
+
+/**
+ * Services
+ */
+
+export const ServiceInfoSchema = z.object({
+  name: z.string(),
+  version: z.string().optional(),
+}).strict();
+
+export type ServiceInfo = z.infer<typeof ServiceInfoSchema>;
+
+export const HealthyServiceInfoSchema = OkaySchema.merge(
+  ServiceInfoSchema
+).extend({
+  message: z.literal("healthy"),
+});
+
+export type HealthyServiceInfo = z.infer<typeof HealthyServiceInfoSchema>;
+
+export const UnhealthyServiceInfoSchema =
+  ApiErrorSchema.merge(ServiceInfoSchema);
+
+export type UnhealthyServiceInfo = z.infer<
+  typeof UnhealthyServiceInfoSchema
+>;
+
+export const ServiceStatusSchema = z.union([
+  HealthyServiceInfoSchema,
+  UnhealthyServiceInfoSchema,
+]);
+
+export type ServiceStatus = z.infer<typeof ServiceStatusSchema>;
+
+/**
+ * API
+ */
+export const ApiInfoSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  description: z.string().optional(),
+  services: ServiceStatusSchema.array(),
+}).strict();
+
+export type ApiInfo = z.infer<typeof ApiInfoSchema>;
+
+export const HealthyApiStatusSchema = OkaySchema.merge(ApiInfoSchema);
+export type HealthyApiStatus = z.infer<typeof HealthyApiStatusSchema>;
+
+export const UnhealthyApiStatusSchema = ApiErrorSchema.merge(ApiInfoSchema);
+export type UnhealthyApiStatus = z.infer<typeof UnhealthyApiStatusSchema>;
+
+export const ApiStatusSchema = z.union([
+  HealthyApiStatusSchema,
+  UnhealthyApiStatusSchema,
+]);
+
+export type ApiStatus = z.infer<typeof ApiStatusSchema>;

package/src/api-schemas/okay.schema.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from "vitest";
+
+import { OkaySchema } from "./okay.schema";
+
+describe("OkaySchema", () => {
+  it("accepts 2xx status codes", () => {
+    expect(OkaySchema.parse({ status: 200 })).toEqual({ status: 200 });
+    expect(OkaySchema.parse({ status: 299 })).toEqual({ status: 299 });
+  });
+
+  it("rejects non-2xx status codes", () => {
+    expect(() => OkaySchema.parse({ status: 199 })).toThrow();
+    expect(() => OkaySchema.parse({ status: 300 })).toThrow();
+  });
+});

package/src/api-schemas/okay.schema.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+export const OkaySchema = z.object({
+  status: z.number().min(200).max(299),
+  message: z.string().optional(),
+}).strict();
+
+export type Okay = z.infer<typeof OkaySchema>;

package/src/api-schemas/paginated-results.schema.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+import { ResultsSchema } from "./results.schema";
+
+export const PaginationSchema = z.object({
+  page: z.number().describe("Current page number"),
+  limit: z.number().describe("Maximum results per page"),
+  totalPages: z.number().describe("Total number of pages"),
+}).strict();
+
+export type Pagination = z.infer<typeof PaginationSchema>;
+
+export const PaginatedResultsSchema = ResultsSchema.extend({
+  pagination: PaginationSchema,
+});
+
+export type PaginatedResults = z.infer<typeof PaginatedResultsSchema>;

package/src/api-schemas/partial-results.schema.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+import { ResultsSchema } from "./results.schema";
+
+/**
+ * Schema for partial success responses where some items succeeded and others failed.
+ * Extends ResultsSchema with an errors count field.
+ * Useful for batch operations that can have mixed results (e.g., 422 responses).
+ */
+export const PartialResultsSchema = ResultsSchema.extend({
+  errors: z.number(), // Count of failed items
+});
+export type PartialResults = z.infer<typeof PartialResultsSchema>;

package/src/api-schemas/result.schema.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from "vitest";
+
+import { ResultSchema } from "./result.schema";
+
+describe("ResultSchema", () => {
+  it("transforms timestamp to ISO string", () => {
+    const result = ResultSchema.parse({
+      status: 200,
+      timestamp: "2024-01-02T03:04:05Z"
+    });
+    expect(result.timestamp).toBe(new Date("2024-01-02T03:04:05Z").toISOString());
+  });
+
+  it("fails when timestamp is invalid", () => {
+    expect(() =>
+      ResultSchema.parse({ status: 200, timestamp: "invalid" })
+    ).toThrow();
+  });
+});

package/src/api-schemas/result.schema.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+import { OkaySchema } from "./okay.schema";
+
+export const ResultSchema = OkaySchema.extend({
+  timestamp: z.string().transform((value) => new Date(value).toISOString()),
+});
+
+export type Result = z.infer<typeof ResultSchema>;

package/src/api-schemas/results.schema.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from "vitest";
+
+import { ResultsSchema } from "./results.schema";
+
+describe("ResultsSchema", () => {
+  it("parses result count and timestamp", () => {
+    const out = ResultsSchema.parse({
+      status: 200,
+      timestamp: "2024-01-02T03:04:05Z",
+      results: 42
+    });
+    expect(out.results).toBe(42);
+    expect(out.timestamp).toBe(new Date("2024-01-02T03:04:05Z").toISOString());
+  });
+});

package/src/api-schemas/results.schema.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+import { ResultSchema } from "./result.schema";
+
+export const ResultsSchema = ResultSchema.extend({
+  results: z.number(),
+});
+
+export type Results = z.infer<typeof ResultsSchema>;

package/src/helpers/correlation/get-correlation-id.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from "vitest";
+
+import { getCorrelationId } from "./get-correlation-id";
+
+describe("getCorrelationId", () => {
+  describe("with existing correlation ID", () => {
+    it("returns existing correlation ID from Headers object", () => {
+      const headers = new Headers();
+      headers.set("x-correlation-id", "existing-id-123");
+
+      const request = { headers };
+      const result = getCorrelationId(request);
+
+      expect(result).toBe("existing-id-123");
+    });
+
+    it("returns existing correlation ID from plain object with get method", () => {
+      const headers = {
+        get: (name: string) => (name === "x-correlation-id" ? "existing-id-456" : undefined),
+      };
+
+      const request = { headers };
+      const result = getCorrelationId(request);
+
+      expect(result).toBe("existing-id-456");
+    });
+
+    it("is case-insensitive when checking for correlation ID", () => {
+      const headers = new Headers();
+      headers.set("X-Correlation-ID", "existing-id-uppercase");
+
+      const request = { headers };
+      const result = getCorrelationId(request);
+
+      expect(result).toBe("existing-id-uppercase");
+    });
+  });
+
+  describe("without existing correlation ID", () => {
+    it("generates new correlation ID when header is missing", () => {
+      const headers = new Headers();
+      const request = { headers };
+
+      const result = getCorrelationId(request);
+
+      // Should be in format: timestamp-randomhex (timestamp in hex, random part is 16 hex chars)
+      expect(result).toMatch(/^[0-9a-f]+-[0-9a-f]{16}$/);
+    });
+
+    it("generates new correlation ID when header is empty string", () => {
+      const headers = new Headers();
+      headers.set("x-correlation-id", "");
+
+      const request = { headers };
+      const result = getCorrelationId(request);
+
+      expect(result).toMatch(/^[0-9a-f]+-[0-9a-f]{16}$/);
+    });
+
+    it("generates new correlation ID when headers is undefined", () => {
+      const request = {};
+      const result = getCorrelationId(request);
+
+      expect(result).toMatch(/^[0-9a-f]+-[0-9a-f]{16}$/);
+    });
+
+    it("generates new correlation ID when headers.get returns undefined", () => {
+      const headers = {
+        get: () => {
+          // Returns nothing (implicitly undefined)
+        },
+      };
+
+      const request = { headers };
+      const result = getCorrelationId(request);
+
+      expect(result).toMatch(/^[0-9a-f]+-[0-9a-f]{16}$/);
+    });
+
+    it("generates unique IDs with different random values", () => {
+      const request = { headers: new Headers() };
+
+      const id1 = getCorrelationId(request);
+      const id2 = getCorrelationId(request);
+
+      expect(id1).not.toBe(id2);
+      expect(id1).toMatch(/^[0-9a-f]+-[0-9a-f]{16}$/);
+      expect(id2).toMatch(/^[0-9a-f]+-[0-9a-f]{16}$/);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles non-string header values by generating new ID", () => {
+      const headers = {
+        get: () => 12_345 as unknown as string,
+      };
+
+      const request = { headers };
+      const result = getCorrelationId(request);
+
+      // Non-string values should be treated as truthy and used if they have length
+      // But numbers don't have .length property, so they won't pass the check
+      // and a new ID will be generated
+      expect(result).toMatch(/^[0-9a-f]+-[0-9a-f]{16}$/);
+    });
+
+    it("handles request with no headers property", () => {
+      const request = {};
+      const result = getCorrelationId(request);
+
+      // Should generate a new ID with proper format
+      expect(result).toMatch(/^[0-9a-f]+-[0-9a-f]{16}$/);
+    });
+
+    it("generates correlation ID with proper format", () => {
+      const request = { headers: new Headers() };
+      const result = getCorrelationId(request);
+
+      // Format: timestamp(hex)-16chars(8 bytes in hex)
+      const parts = result.split("-");
+      expect(parts).toHaveLength(2);
+      expect(parts[0]).toMatch(/^[0-9a-f]+$/);
+      expect(parts[1]).toMatch(/^[0-9a-f]{16}$/);
+    });
+  });
+});

package/src/helpers/correlation/get-correlation-id.ts

@@ -0,0 +1,22 @@
+import { getHeader } from "./get-header";
+
+export function getCorrelationId(request: {
+  headers?:
+    | Headers
+    | { get?: (name: string) => string | null; [key: string]: unknown };
+}): string {
+  const existingId = getHeader(request, "x-correlation-id");
+  if (existingId && typeof existingId === "string" && existingId.length > 0) {
+    return existingId;
+  }
+
+  // Use crypto for secure random ID generation
+  const bytes = new Uint8Array(8);
+  crypto.getRandomValues(bytes);
+  let randomPart = "";
+  for (const byte of bytes) {
+    randomPart += byte.toString(16).padStart(2, "0");
+  }
+  const timestamp = Date.now().toString(16);
+  return `${timestamp}-${randomPart}`;
+}

package/src/helpers/correlation/get-header.test.ts

@@ -0,0 +1,179 @@
+import { describe, it, expect } from "vitest";
+
+import { getHeader } from "./get-header";
+
+describe("getHeader", () => {
+  describe("with Headers object", () => {
+    it("returns header value when header exists", () => {
+      const headers = new Headers();
+      headers.set("content-type", "application/json");
+
+      const request = { headers };
+      const result = getHeader(request, "content-type");
+
+      expect(result).toBe("application/json");
+    });
+
+    it("returns undefined when header does not exist", () => {
+      const headers = new Headers();
+
+      const request = { headers };
+      const result = getHeader(request, "x-missing-header");
+
+      expect(result).toBeUndefined();
+    });
+
+    it("is case-insensitive for header names", () => {
+      const headers = new Headers();
+      headers.set("Content-Type", "text/html");
+
+      const request = { headers };
+      const result = getHeader(request, "content-type");
+
+      expect(result).toBe("text/html");
+    });
+
+    it("handles multiple headers with same name", () => {
+      const headers = new Headers();
+      headers.append("set-cookie", "cookie1=value1");
+      headers.append("set-cookie", "cookie2=value2");
+
+      const request = { headers };
+      const result = getHeader(request, "set-cookie");
+
+      // Headers.get() returns comma-separated values for duplicate headers
+      expect(result).toContain("cookie1=value1");
+    });
+  });
+
+  describe("with plain object (with get method)", () => {
+    it("returns header value when header exists", () => {
+      const headers = {
+        get: (name: string) => {
+          const headerMap: Record<string, string> = {
+            "content-type": "application/xml",
+            authorization: "Bearer token123",
+          };
+          return headerMap[name] || undefined;
+        },
+      };
+
+      const request = { headers };
+      const result = getHeader(request, "content-type");
+
+      expect(result).toBe("application/xml");
+    });
+
+    it("returns undefined when get method returns undefined", () => {
+      const headers = {
+        get: () => {
+          // Returns nothing (implicitly undefined)
+        },
+      };
+
+      const request = { headers };
+      const result = getHeader(request, "x-custom-header");
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe("with plain object (without get method)", () => {
+    it("returns header value when header exists (case-insensitive)", () => {
+      const headers = {
+        "Content-Type": "application/json",
+        Authorization: "Bearer token456",
+      };
+
+      const request = { headers };
+      const result = getHeader(request, "content-type");
+
+      expect(result).toBe("application/json");
+    });
+
+    it("returns header value with different case", () => {
+      const headers = {
+        "x-custom-header": "custom-value",
+      };
+
+      const request = { headers };
+      const result = getHeader(request, "X-Custom-Header");
+
+      expect(result).toBe("custom-value");
+    });
+
+    it("returns undefined when header does not exist", () => {
+      const headers = {
+        "content-type": "text/plain",
+      };
+
+      const request = { headers };
+      const result = getHeader(request, "x-nonexistent");
+
+      expect(result).toBeUndefined();
+    });
+
+    it("converts non-string header values to strings", () => {
+      const headers = {
+        "x-numeric-header": 12_345,
+        "x-boolean-header": true,
+      };
+
+      const request = { headers };
+
+      expect(getHeader(request, "x-numeric-header")).toBe("12345");
+      expect(getHeader(request, "x-boolean-header")).toBe("true");
+    });
+  });
+
+  describe("edge cases", () => {
+    it("returns undefined when headers is undefined", () => {
+      const request = {};
+      const result = getHeader(request, "any-header");
+
+      expect(result).toBeUndefined();
+    });
+
+    it("returns undefined when headers is undefined in request", () => {
+      const request = { headers: undefined };
+      const result = getHeader(request as { headers: Headers }, "any-header");
+
+      expect(result).toBeUndefined();
+    });
+
+    it("returns undefined when request has no headers property", () => {
+      const request = {};
+      const result = getHeader(request, "content-type");
+
+      expect(result).toBeUndefined();
+    });
+
+    it("handles empty header name edge case", () => {
+      const headers = {
+        "": "empty-name-value",
+        "content-type": "application/json",
+      };
+
+      const request = { headers };
+      
+      // Empty string key can be found but may not be accessible in all environments
+      // Test that it doesn't throw and returns a value (either the value or undefined)
+      const result = getHeader(request, "");
+      expect(result === "empty-name-value" || result === undefined).toBe(true);
+      
+      // Normal keys should still work
+      expect(getHeader(request, "content-type")).toBe("application/json");
+    });
+
+    it("handles headers with special characters in names", () => {
+      const headers = {
+        "x-special-!@#$-header": "special-value",
+      };
+
+      const request = { headers };
+      const result = getHeader(request, "X-Special-!@#$-Header");
+
+      expect(result).toBe("special-value");
+    });
+  });
+});

package/src/helpers/correlation/get-header.ts

@@ -0,0 +1,21 @@
+export function getHeader(
+  request: {
+    headers?:
+      | Headers
+      | { get?: (name: string) => string | null; [key: string]: unknown };
+  },
+  name: string
+): string | undefined {
+  const headers = request?.headers;
+  if (!headers) return undefined;
+
+  if (typeof headers.get === "function") {
+    const v = headers.get(name);
+    return v === null ? undefined : v;
+  }
+
+  const key = Object.keys(headers).find(
+    (k) => k.toLowerCase() === name.toLowerCase()
+  );
+  return key ? String((headers as Record<string, unknown>)[key]) : undefined;
+}