@schafevormfenster/rest-commons 0.1.1

package/src/index.ts

@@ -0,0 +1,46 @@
+// Schemas
+export * from "./api-schemas/error.schema";
+export * from "./api-schemas/health.schema";
+export * from "./api-schemas/okay.schema";
+export * from "./api-schemas/result.schema";
+export * from "./api-schemas/results.schema";
+
+// Primitive schemas
+export * from "./primitives/location.schema";
+export * from "./primitives/slug.schema";
+export * from "./primitives/numeric-id.schema";
+export * from "./primitives/uuid.schema";
+export * from "./primitives/geoname-id.schema";
+export * from "./primitives/wikidata-id.schema";
+export * from "./primitives/international-zip.schema";
+
+// Time utilities
+export * from "./time/timezone.types";
+export * from "./time/iso8601.schema"; // ISO8601 schemas
+export * from "./time/relative-time.schema"; // Relative time schemas
+export * from "./time/flexible-time.schema"; // Flexible time schemas
+export * from "./time/bounded-time.schema"; // Bounded time schemas
+export * from "./time/time-helpers"; // Helper functions
+export * from "./time/is-relative-time";
+export { parseFlexibleTime as parseFlexibleTimeAdvanced } from "./time/flexible-time-parser";
+export * from "./time/boundary-enforcement";
+
+// Deprecated exports (for backward compatibility)
+/** @deprecated Use flexible-time.schema exports instead */
+export { FlexibleTimeSchema as FlexibleTimeSchemaOld, FlexibleTime as FlexibleTimeOld, TimeUnit, RelativeTimeConfig } from "./time/time-schemas";
+
+// Helpers
+export * from "./helpers/correlation/get-correlation-id";
+export * from "./helpers/correlation/get-header";
+export * from "./helpers/detect-mime-type";
+export * from "./helpers/detect-suspicious-patterns";
+export * from "./helpers/hash-binary";
+export * from "./helpers/parameter-validation";
+export * from "./helpers/slugify";
+export * from "./helpers/response-headers/build-api-unauthorized-headers";
+export * from "./helpers/response-headers/environment.types";
+export * from "./helpers/response-headers/resolve-environment";
+
+// Utilities
+export * from "./normalization/normalize-list";
+export * from "./normalization/normalize-location";

package/src/normalization/normalize-list.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+
+import { normalizeStringList } from "./normalize-list";
+
+describe("normalizeStringList", () => {
+  it("lowercases, removes duplicates, and sorts values with proper umlaut handling", () => {
+    const input = [
+      "Banana",
+      "apple",
+      "cherry",
+      "Äpfel",
+      " banana ",
+      "Öl",
+      "orange",
+    ];
+    const result = normalizeStringList(input);
+    expect(result).toEqual([
+      "äpfel",
+      "apple",
+      "banana",
+      "cherry",
+      "öl",
+      "orange",
+    ]);
+  });
+
+  it("handles empty and already normalized inputs", () => {
+    expect(normalizeStringList([])).toEqual([]);
+    expect(normalizeStringList(["a", "b"])).toEqual(["a", "b"]);
+  });
+
+  it("removes duplicates correctly", () => {
+    const input = ["apple", "Apple", "APPLE", " apple ", "banana"];
+    const result = normalizeStringList(input);
+    expect(result).toEqual(["apple", "banana"]);
+  });
+
+  it("sorts umlauts near their base letters", () => {
+    const input = ["z", "ä", "a", "ö", "o", "ü", "u", "b"];
+    const result = normalizeStringList(input);
+    expect(result).toEqual(["a", "ä", "b", "o", "ö", "u", "ü", "z"]);
+  });
+});

package/src/normalization/normalize-list.ts

@@ -0,0 +1,21 @@
+import { MAX_TAGS_COUNT, sanitizeTag } from "@schafevormfenster/security";
+
+/**
+ * Normalize an array of strings by:
+ * - sanitizing with whitelist rules (preserving umlauts, removing injections)
+ * - trimming whitespace
+ * - lowercasing using locale-insensitive toLowerCase
+ * - removing duplicates
+ * - sorting alphabetically with proper German locale support (umlauts near base letters)
+ * - enforcing a maximum count
+ */
+export function normalizeStringList(values: string[] = []): string[] {
+  const sanitized = values.map((v) => sanitizeTag(v));
+  const normalized = sanitized
+    .map((v) => v.trim().toLowerCase())
+    .filter((v) => v.length > 0);
+
+  const unique = [...new Set(normalized)].slice(0, MAX_TAGS_COUNT);
+  unique.sort((a, b) => a.localeCompare(b, "de-DE"));
+  return unique;
+}

package/src/normalization/normalize-location.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+
+import { normalizeLocation } from './normalize-location';
+
+describe('normalizeLocation', () => {
+  describe('space normalization', () => {
+    it('should collapse multiple spaces to single space', () => {
+      expect(normalizeLocation('Schlatkow   17390  Schmatzin')).toBe('Schlatkow 17390 Schmatzin');
+      expect(normalizeLocation('Berlin     Germany')).toBe('Berlin Germany');
+      expect(normalizeLocation('Am   Markt    5')).toBe('Am Markt 5');
+    });
+
+    it('should handle tabs and newlines as spaces', () => {
+      expect(normalizeLocation('Schlatkow\t17390\nSchmatzin')).toBe('Schlatkow 17390 Schmatzin');
+      expect(normalizeLocation('Berlin\t\tGermany\n')).toBe('Berlin Germany');
+    });
+
+    it('should trim leading and trailing spaces', () => {
+      expect(normalizeLocation('  Schlatkow 17390 Schmatzin  ')).toBe('Schlatkow 17390 Schmatzin');
+      expect(normalizeLocation('\tBerlin Germany\n')).toBe('Berlin Germany');
+    });
+  });
+
+  describe('comma normalization', () => {
+    it('should ensure no space before comma and one space after', () => {
+      expect(normalizeLocation('Schlatkow ,17390 Schmatzin')).toBe('Schlatkow, 17390 Schmatzin');
+      expect(normalizeLocation('Schlatkow  ,  17390 Schmatzin')).toBe('Schlatkow, 17390 Schmatzin');
+      expect(normalizeLocation('Schlatkow,17390 Schmatzin')).toBe('Schlatkow, 17390 Schmatzin');
+    });
+
+    it('should handle multiple commas correctly', () => {
+      expect(normalizeLocation('Schlatkow , 17390 , Schmatzin')).toBe('Schlatkow, 17390, Schmatzin');
+      expect(normalizeLocation('A,B,C,D')).toBe('A, B, C, D');
+    });
+
+    it('should handle comma at the end correctly', () => {
+      expect(normalizeLocation('Schlatkow, 17390 Schmatzin ,')).toBe('Schlatkow, 17390 Schmatzin,');
+      expect(normalizeLocation('Berlin , ')).toBe('Berlin,');
+    });
+  });
+
+  describe('idempotent behavior', () => {
+    it('should handle already normalized strings (idempotent)', () => {
+      const normalized = 'Schlatkow, 17390 Schmatzin';
+      expect(normalizeLocation(normalized)).toBe(normalized);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty string', () => {
+      expect(normalizeLocation('')).toBe('');
+    });
+
+    it('should handle string with only spaces', () => {
+      expect(normalizeLocation('   ')).toBe('');
+      expect(normalizeLocation('\t\n')).toBe('');
+    });
+
+    it('should handle string with only comma', () => {
+      expect(normalizeLocation(',')).toBe(',');
+      expect(normalizeLocation(' , ')).toBe(',');
+    });
+
+    it('should handle single character', () => {
+      expect(normalizeLocation('A')).toBe('A');
+      expect(normalizeLocation(' A ')).toBe('A');
+    });
+
+    it('should handle special characters and numbers', () => {
+      expect(normalizeLocation('Str. 123  ,  12345   City')).toBe('Str. 123, 12345 City');
+      expect(normalizeLocation('Ä-Ö-Ü  ,   Test')).toBe('Ä-Ö-Ü, Test');
+    });
+  });
+
+  describe('cache optimization scenarios', () => {
+    it('should normalize different variations to the same string', () => {
+      const variations = [
+        'Schlatkow, 17390 Schmatzin',
+        'Schlatkow   ,   17390  Schmatzin',
+        'Schlatkow ,17390 Schmatzin',
+        '  Schlatkow  ,  17390   Schmatzin  ',
+        'Schlatkow\t,\t17390\tSchmatzin',
+      ];
+
+      const expected = 'Schlatkow, 17390 Schmatzin';
+      for (const variation of variations) {
+        expect(normalizeLocation(variation)).toBe(expected);
+      }
+    });
+  });
+});

package/src/normalization/normalize-location.ts

@@ -0,0 +1,29 @@
+/**
+ * Normalizes location strings to optimize cache hits.
+ *
+ * Cleanup operations:
+ * - Remove duplicate or multiple spaces and reduce to at most one space character
+ * - Ensure that a comma has no space before but one space after
+ *
+ * @param location - The location string to normalize
+ * @returns Normalized location string
+ *
+ * @example
+ * normalizeLocation("Schlatkow   ,   17390  Schmatzin")
+ * // Returns: "Schlatkow, 17390 Schmatzin"
+ */
+export function normalizeLocation(location: string): string {
+  return (
+    location
+      // First pass: normalize spaces (collapse multiple spaces/tabs/newlines to single space)
+
+      .replaceAll(/[ \t\n\r]+/gu, " ")
+      // Trim leading and trailing spaces
+      .trim()
+      // Fix comma spacing: remove space before comma, ensure one space after comma (but not at end)
+      // eslint-disable-next-line sonarjs/slow-regex -- Necessary for comma normalization
+      .replaceAll(/ *, */gu, ", ")
+      // Remove trailing space after comma if it's at the end of string
+      .replace(/, $/u, ",")
+  );
+}

package/src/primitives/coordinate-precision.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+
+import { hasValidDecimalPrecision } from "./coordinate-precision";
+
+describe("hasValidDecimalPrecision", () => {
+  it("should accept values with no decimal places", () => {
+    expect(hasValidDecimalPrecision(0)).toBe(true);
+    expect(hasValidDecimalPrecision(90)).toBe(true);
+    expect(hasValidDecimalPrecision(-180)).toBe(true);
+  });
+
+  it("should accept values with up to 8 decimal places", () => {
+    expect(hasValidDecimalPrecision(52.52)).toBe(true); // 2 decimal places
+    expect(hasValidDecimalPrecision(40.7128)).toBe(true); // 4 decimal places
+    expect(hasValidDecimalPrecision(52.520_008)).toBe(true); // 6 decimal places
+    expect(hasValidDecimalPrecision(52.520_008_07)).toBe(true); // 8 decimal places
+  });
+
+  it("should reject values with more than 8 decimal places", () => {
+    expect(hasValidDecimalPrecision(52.520_008_071)).toBe(false); // 9 decimal places
+    expect(hasValidDecimalPrecision(40.712_812_345_678)).toBe(false); // 12 decimal places
+  });
+
+  it("should handle scientific notation correctly", () => {
+    // Small numbers with few actual decimal places should pass
+    expect(hasValidDecimalPrecision(1.23e-4)).toBe(true); // 0.000123 = 6 decimals
+    expect(hasValidDecimalPrecision(1.23e-2)).toBe(true); // 0.0123 = 4 decimals
+    
+    // Numbers with more than 8 decimal places should fail
+    expect(hasValidDecimalPrecision(1.234_567_89e-1)).toBe(false); // 0.123456789 = 9 decimals
+  });
+
+  it("should support custom max decimal places", () => {
+    expect(hasValidDecimalPrecision(1.234, 3)).toBe(true);
+    expect(hasValidDecimalPrecision(1.2345, 3)).toBe(false);
+    expect(hasValidDecimalPrecision(1.234_56, 5)).toBe(true);
+    expect(hasValidDecimalPrecision(1.234_567, 5)).toBe(false);
+  });
+
+  it("should handle edge cases", () => {
+    expect(hasValidDecimalPrecision(0)).toBe(true);
+    expect(hasValidDecimalPrecision(-0)).toBe(true);
+    // Number.EPSILON has many decimal places when converted to standard notation
+    expect(hasValidDecimalPrecision(Number.EPSILON)).toBe(false);
+  });
+});

package/src/primitives/coordinate-precision.ts

@@ -0,0 +1,30 @@
+/**
+ * Validates that a coordinate value has at most the specified number of decimal places.
+ * Handles both standard notation and scientific notation.
+ *
+ * @param value - The numeric coordinate value to validate
+ * @param maxDecimalPlaces - Maximum allowed decimal places (default: 8)
+ * @returns true if the value has at most maxDecimalPlaces decimal places
+ */
+export function hasValidDecimalPrecision(
+  value: number,
+  maxDecimalPlaces = 8
+): boolean {
+  // Convert to string and handle scientific notation
+  const valueString = value.toString();
+  if (valueString.includes("e") || valueString.includes("E")) {
+    // For scientific notation, convert to fixed notation
+    // Use 20 decimal places to ensure we capture all significant digits
+    // without losing precision during the conversion
+    const fixed = value.toFixed(20);
+    const [, decimalPart = ""] = fixed.split(".");
+    // Remove trailing zeros without regex
+    let decimals = decimalPart;
+    while (decimals.endsWith("0")) {
+      decimals = decimals.slice(0, -1);
+    }
+    return decimals.length <= maxDecimalPlaces;
+  }
+  const decimalPlaces = valueString.split(".")[1]?.length || 0;
+  return decimalPlaces <= maxDecimalPlaces;
+}

package/src/primitives/geo-point.schema.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from "vitest";
+
+import { GeoPointSchema } from "./geo-point.schema";
+
+describe("GeoPointSchema", () => {
+  it("should accept valid geo points", () => {
+    expect(GeoPointSchema.parse([0, 0])).toEqual([0, 0]);
+    expect(GeoPointSchema.parse([52.52, 13.405])).toEqual([52.52, 13.405]); // Berlin
+    expect(GeoPointSchema.parse([40.7128, -74.006])).toEqual([40.7128, -74.006]); // New York
+    expect(GeoPointSchema.parse([-33.8688, 151.2093])).toEqual([-33.8688, 151.2093]); // Sydney
+  });
+
+  it("should accept boundary values", () => {
+    expect(GeoPointSchema.parse([90, 180])).toEqual([90, 180]); // North Pole, Date Line
+    expect(GeoPointSchema.parse([-90, -180])).toEqual([-90, -180]); // South Pole, Date Line
+    expect(GeoPointSchema.parse([90, -180])).toEqual([90, -180]);
+    expect(GeoPointSchema.parse([-90, 180])).toEqual([-90, 180]);
+  });
+
+  it("should reject invalid latitude", () => {
+    expect(() => GeoPointSchema.parse([91, 0])).toThrow(
+      "Latitude must be less than or equal to 90"
+    );
+    expect(() => GeoPointSchema.parse([-91, 0])).toThrow(
+      "Latitude must be greater than or equal to -90"
+    );
+    expect(() => GeoPointSchema.parse([100, 0])).toThrow(
+      "Latitude must be less than or equal to 90"
+    );
+  });
+
+  it("should reject invalid longitude", () => {
+    expect(() => GeoPointSchema.parse([0, 181])).toThrow(
+      "Longitude must be less than or equal to 180"
+    );
+    expect(() => GeoPointSchema.parse([0, -181])).toThrow(
+      "Longitude must be greater than or equal to -180"
+    );
+    expect(() => GeoPointSchema.parse([0, 360])).toThrow(
+      "Longitude must be less than or equal to 180"
+    );
+  });
+
+  it("should reject tuples with wrong length", () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => GeoPointSchema.parse([0] as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => GeoPointSchema.parse([0, 0, 0] as any)).toThrow();
+  });
+
+  it("should reject non-tuple values", () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => GeoPointSchema.parse("0,0" as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => GeoPointSchema.parse({ lat: 0, lng: 0 } as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, unicorn/no-null
+    expect(() => GeoPointSchema.parse(null as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => GeoPointSchema.parse(undefined as any)).toThrow();
+  });
+
+  it("should reject non-numeric coordinates", () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => GeoPointSchema.parse(["0", "0"] as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => GeoPointSchema.parse([0, "0"] as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => GeoPointSchema.parse(["0", 0] as any)).toThrow();
+  });
+});

package/src/primitives/geo-point.schema.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+import { LatitudeSchema } from "./latitude.schema";
+import { LongitudeSchema } from "./longitude.schema";
+
+/**
+ * Zod schema for validating geographic coordinates as a tuple.
+ * Geographic coordinates as [latitude, longitude].
+ */
+export const GeoPointSchema = z
+  .tuple([LatitudeSchema, LongitudeSchema])
+  .describe("Geographic coordinates as [latitude, longitude]");
+
+export type GeoPoint = z.infer<typeof GeoPointSchema>;

package/src/primitives/geoname-id.schema.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from "vitest";
+
+import { GeonameIdSchema } from "./geoname-id.schema";
+
+describe("GeonameIdSchema", () => {
+  it("should accept valid Geoname IDs", () => {
+    expect(GeonameIdSchema.parse("1")).toBe("1");
+    expect(GeonameIdSchema.parse("2950159")).toBe("2950159"); // Berlin
+    expect(GeonameIdSchema.parse("5128581")).toBe("5128581"); // New York
+    expect(GeonameIdSchema.parse("1234567890")).toBe("1234567890"); // 10 digits max
+  });
+
+  it("should reject IDs starting with zero", () => {
+    expect(() => GeonameIdSchema.parse("0")).toThrow(
+      "Must be a valid Geoname ID (positive integer, max 10 digits)"
+    );
+    expect(() => GeonameIdSchema.parse("01234")).toThrow(
+      "Must be a valid Geoname ID (positive integer, max 10 digits)"
+    );
+  });
+
+  it("should reject IDs longer than 10 digits", () => {
+    expect(() => GeonameIdSchema.parse("12345678901")).toThrow(
+      "Must be a valid Geoname ID (positive integer, max 10 digits)"
+    );
+  });
+
+  it("should reject non-numeric strings", () => {
+    expect(() => GeonameIdSchema.parse("abc")).toThrow(
+      "Must be a valid Geoname ID (positive integer, max 10 digits)"
+    );
+    expect(() => GeonameIdSchema.parse("123abc")).toThrow(
+      "Must be a valid Geoname ID (positive integer, max 10 digits)"
+    );
+    expect(() => GeonameIdSchema.parse("12-34")).toThrow(
+      "Must be a valid Geoname ID (positive integer, max 10 digits)"
+    );
+  });
+
+  it("should reject empty strings", () => {
+    expect(() => GeonameIdSchema.parse("")).toThrow(
+      "Must be a valid Geoname ID (positive integer, max 10 digits)"
+    );
+  });
+
+  it("should reject negative numbers", () => {
+    expect(() => GeonameIdSchema.parse("-123")).toThrow(
+      "Must be a valid Geoname ID (positive integer, max 10 digits)"
+    );
+  });
+
+  it("should reject non-string values", () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => GeonameIdSchema.parse(123 as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, unicorn/no-null
+    expect(() => GeonameIdSchema.parse(null as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => GeonameIdSchema.parse(undefined as any)).toThrow();
+  });
+});

package/src/primitives/geoname-id.schema.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+/**
+ * Zod schema for validating Geonames.org numeric IDs.
+ * Geoname IDs are positive integers, typically 1-10 digits.
+ */
+export const GeonameIdSchema = z
+  .string()
+  .regex(/^[1-9]\d{0,9}$/, "Must be a valid Geoname ID (positive integer, max 10 digits)")
+  .describe("Geonames.org location identifier");
+
+export type GeonameId = z.infer<typeof GeonameIdSchema>;