@next-vibe/checker 1.0.11 → 1.0.12

package/src/app/api/[locale]/shared/utils/i18n/pl/index.ts

@@ -0,0 +1,21 @@
+import type { translations as enTranslations } from "../en";
+
+export const translations: typeof enTranslations = {
+  parseJsonWithComments: {
+    errors: {
+      invalid_json: "Nieprawidłowy format JSON",
+    },
+  },
+  time: {
+    errors: {
+      invalid_time_format: {
+        title: "Nieprawidłowy format czasu",
+        description: "Czas musi być w formacie HH:MM",
+      },
+      invalid_time_range: {
+        title: "Nieprawidłowy zakres czasu",
+        description: "Czas musi być między 00:00 a 23:59",
+      },
+    },
+  },
+};

package/src/app/api/[locale]/shared/utils/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared utilities that can be used in both client and server environments
+ */
+
+// Export all utility functions
+export * from "./base64";
+export * from "./env-util";
+export * from "./object";
+export * from "./parse-error";
+export * from "./time";
+export * from "./validation";

package/src/app/api/[locale]/shared/utils/object-path.ts

@@ -0,0 +1,41 @@
+/**
+ * Utility functions for safely setting nested object paths
+ */
+
+// Interface for objects that can contain nested structures
+interface NestedObject<TValue> {
+  [key: string]: NestedObject<TValue> | TValue;
+}
+
+/**
+ * Safely sets a value at a nested object path, creating intermediate objects as needed
+ * @param obj - The target object
+ * @param path - Array of path segments
+ * @param value - The value to set
+ */
+export function setNestedPath<TValue, TObject>(
+  obj: TObject,
+  path: readonly string[],
+  value: TValue,
+): void {
+  let current = obj as NestedObject<TValue>;
+
+  // Create intermediate path segments
+  for (let i = 0; i < path.length - 1; i++) {
+    const segment = path[i];
+    if (!segment) {
+      continue;
+    }
+
+    if (!current[segment] || typeof current[segment] !== "object") {
+      current[segment] = {};
+    }
+    current = current[segment] as NestedObject<TValue>;
+  }
+
+  // Set the final value
+  const lastSegment = path.at(-1);
+  if (lastSegment) {
+    current[lastSegment] = value;
+  }
+}

package/src/app/api/[locale]/shared/utils/object.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Tests for object utilities to verify type preservation
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { objectEntries, objectEntriesNumericEnum } from "./object";
+
+// Test enum definitions to match the ones used in cron stats
+enum TestPriority {
+  LOW = "low",
+  NORMAL = "normal",
+  HIGH = "high",
+  CRITICAL = "critical",
+}
+
+enum TestWeekday {
+  SUNDAY = 0,
+  MONDAY = 1,
+  TUESDAY = 2,
+  WEDNESDAY = 3,
+  THURSDAY = 4,
+  FRIDAY = 5,
+  SATURDAY = 6,
+}
+
+// Test data structures
+const priorityRecord: Partial<Record<TestPriority, number>> = {
+  [TestPriority.LOW]: 5,
+  [TestPriority.HIGH]: 10,
+  // NORMAL and CRITICAL are missing to test partial records
+};
+
+const weekdayRecord: Partial<Record<TestWeekday, number>> = {
+  [TestWeekday.MONDAY]: 100,
+  [TestWeekday.FRIDAY]: 80,
+  // Other days are missing
+};
+
+// Test type preservation
+describe("Object utilities type preservation", () => {
+  test("objectEntries preserves enum types for priority", () => {
+    const entries = objectEntries(priorityRecord);
+
+    // This should compile without type errors and preserve enum types
+    entries.forEach(([priority, count]) => {
+      // priority should be of type TestPriority
+      // count should be of type number
+      expect(Object.values(TestPriority)).toContain(priority);
+      expect(typeof count).toBe("number");
+    });
+
+    expect(entries.length).toBe(2); // Only LOW and HIGH are defined
+  });
+
+  test("objectEntriesNumericEnum preserves enum types for weekday", () => {
+    const entries = objectEntriesNumericEnum(weekdayRecord);
+
+    // This should compile without type errors and preserve enum types
+    entries.forEach(([weekday, count]) => {
+      // weekday should be of type TestWeekday (number enum)
+      // count should be of type number
+      expect(typeof weekday).toBe("number");
+      expect(Object.values(TestWeekday)).toContain(weekday);
+      expect(typeof count).toBe("number");
+    });
+
+    expect(entries.length).toBe(2); // Only MONDAY and FRIDAY are defined
+  });
+
+  test("filtered entries only include defined values", () => {
+    const partialRecord: Partial<Record<TestPriority, number>> = {
+      [TestPriority.LOW]: 5,
+      [TestPriority.NORMAL]: undefined, // This should be filtered out
+      [TestPriority.HIGH]: 10,
+    };
+
+    const entries = objectEntries(partialRecord);
+    expect(entries.length).toBe(2); // undefined values should be filtered
+    expect(entries.every(([, value]) => value !== undefined)).toBe(true);
+  });
+});

package/src/app/api/[locale]/shared/utils/object.ts

@@ -0,0 +1,75 @@
+/**
+ * Object utilities with type preservation
+ */
+
+/**
+ * Type-safe Object.entries that preserves enum and key types
+ *
+ * @param obj - The object to get entries from
+ * @returns Array of [key, value] tuples with preserved types
+ *
+ * @example
+ * ```typescript
+ * enum Color { RED = "red", BLUE = "blue" }
+ * const colorCounts: Record<Color, number> = { [Color.RED]: 5, [Color.BLUE]: 3 };
+ * const entries = objectEntries(colorCounts); // [Color, number][]
+ * ```
+ */
+export function objectEntries<K extends string | number | symbol, V>(
+  obj: Record<K, V>,
+): Array<[K, V]>;
+
+/**
+ * Type-safe Object.entries for partial records (handles undefined values)
+ *
+ * @param obj - The partial object to get entries from
+ * @returns Array of [key, value] tuples with preserved types, filtered for defined values
+ */
+export function objectEntries<K extends string | number | symbol, V>(
+  obj: Partial<Record<K, V>>,
+): Array<[K, V]>;
+
+export function objectEntries<K extends string | number | symbol, V>(
+  obj: Record<K, V> | Partial<Record<K, V>>,
+): Array<[K, V]> {
+  return Object.entries(obj).filter(
+    ([, value]) => value !== undefined,
+  ) as Array<[K, V]>;
+}
+
+/**
+ * Type-safe Object.keys that preserves key types
+ *
+ * @param obj - The object to get keys from
+ * @returns Array of keys with preserved types
+ */
+export function objectKeys<K extends string | number | symbol, V>(
+  obj: Record<K, V> | Partial<Record<K, V>>,
+): K[] {
+  return Object.keys(obj) as K[];
+}
+
+/**
+ * Type-safe Object.values that preserves value types
+ *
+ * @param obj - The object to get values from
+ * @returns Array of values with preserved types
+ */
+export function objectValues<V>(obj: Record<string | number | symbol, V>): V[] {
+  return Object.values(obj);
+}
+
+/**
+ * Special handling for enum-based records where keys might be numeric
+ * This is useful for JSWeekday and other numeric enums
+ *
+ * @param obj - The object with potentially numeric enum keys
+ * @returns Array of [enum, value] tuples with proper enum type conversion
+ */
+export function objectEntriesNumericEnum<E extends number, V>(
+  obj: Partial<Record<E, V>>,
+): Array<[E, V]> {
+  return Object.entries(obj)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => [parseInt(key, 10) as E, value as V]);
+}

package/src/app/api/[locale]/shared/utils/parse-error.ts

@@ -0,0 +1,134 @@
+import type { ErrorResponseType } from "next-vibe/shared/types/response.schema";
+
+import type { TParams, TranslationKey } from "@/i18n/core/static-types";
+
+/**
+ * Custom error class that preserves error type and translation parameters
+ */
+class ApiError extends Error {
+  errorType?: string;
+  messageParams?: TParams;
+  translationKey?: TranslationKey;
+
+  constructor(options: {
+    errorType: string;
+    messageParams?: TParams;
+    translationKey: TranslationKey;
+  }) {
+    super(options.translationKey);
+    this.name = "ApiError" as const;
+    this.errorType = options.errorType;
+    this.messageParams = options.messageParams;
+    this.translationKey = options.translationKey;
+  }
+}
+
+/**
+ * Check if an object is an ErrorResponseType
+ */
+export function isErrorResponseType(
+  // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Error parsing utility requires 'unknown' to handle any error input type
+  obj: unknown,
+): obj is ErrorResponseType {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "success" in obj &&
+    obj.success === false &&
+    "message" in obj &&
+    "errorType" in obj
+  );
+}
+
+/**
+ * Possible error input types for error checking and parsing
+ */
+
+/**
+ * Parse a parseable error into a proper Error object
+ * Preserves error type and translation parameters if available
+ *
+ * @param error - The error to parse
+ * @returns A proper Error object
+ */
+// eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Error parsing utility requires 'unknown' to handle any error input type
+export function parseError(error: unknown): Error {
+  // Handle standard Error instances
+  if (error instanceof Error) {
+    return error;
+  }
+
+  // Handle ErrorResponseType objects
+  if (isErrorResponseType(error)) {
+    return new ApiError({
+      errorType: error.errorType.errorKey,
+      messageParams: error.messageParams,
+      translationKey: error.message,
+    });
+  }
+
+  // Handle other objects
+  if (typeof error === "object" && error !== null) {
+    // Extract meaningful error info from objects without console.error pollution
+    // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Error parsing requires type assertion for object property access
+    const errorObj = error as Record<string, unknown>;
+    const errorMessage =
+      errorObj.error || errorObj.message || "An unknown error occurred";
+    return new Error(String(errorMessage));
+  }
+
+  // Handle string errors
+  if (typeof error === "string") {
+    return new Error(error);
+  }
+
+  // Handle objects with message property
+  if (typeof error === "object" && error !== null && "message" in error) {
+    // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Error parsing requires type assertion for object property access
+    const errorObj = error as Record<string, unknown>;
+    const message = errorObj.message;
+    if (typeof message === "string") {
+      return new Error(message);
+    }
+  }
+
+  // Handle objects with error property
+  if (typeof error === "object" && error !== null && "error" in error) {
+    // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Error parsing requires type assertion for object property access
+    const errorObj = error as Record<string, unknown>;
+    const errorMessage = errorObj.error;
+    if (typeof errorMessage === "string") {
+      return new Error(errorMessage);
+    }
+  }
+
+  // Handle null/undefined
+  if (error === null || error === undefined) {
+    return new Error("errors.noDetails");
+  }
+
+  // Default case
+  return new Error("An unknown error occurred");
+}
+
+/**
+ * Format strings with values using a template pattern
+ *
+ * @param strings - The strings to format
+ * @param values - The values to insert into the strings
+ * @returns The formatted strings
+ */
+export function format<
+  T extends Record<string, string | number | boolean | null | undefined>,
+>(strings: string[], values: T): string[] {
+  return strings.map((part) =>
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Required by replace() API
+    part.replaceAll(/{(\w+)}/g, (match, key: string) => {
+      const value = values[key];
+      if (value === null || value === undefined) {
+        return "";
+      }
+      return String(value);
+    }),
+  );
+}

package/src/app/api/[locale]/shared/utils/parse-json.ts

@@ -0,0 +1,70 @@
+import { parse } from "jsonc-parser";
+import type { ResponseType } from "next-vibe/shared/types/response.schema";
+import {
+  ErrorResponseTypes,
+  fail,
+} from "next-vibe/shared/types/response.schema";
+
+/**
+ * JSON Parser with Comment Support
+ * Handles JSON files with comments (like tsconfig.json)
+ * Uses jsonc-parser which properly handles comments and trailing commas
+ */
+
+export interface JsonWithComments {
+  [key: string]:
+    | string
+    | number
+    | boolean
+    | null
+    | undefined
+    | JsonWithComments
+    | JsonWithComments[];
+}
+
+/**
+ * Parse JSON with support for comments and trailing commas
+ *
+ * @param jsonString - JSON string potentially containing comments
+ * @returns Parsed JSON object or error response
+ */
+export function parseJsonWithComments(
+  jsonString: string,
+): ResponseType<JsonWithComments> {
+  try {
+    const result = parse(jsonString);
+    if (typeof result !== "object" || result === null) {
+      return fail({
+        message:
+          "app.api.shared.utils.parseJsonWithComments.errors.invalid_json",
+        errorType: ErrorResponseTypes.INVALID_FORMAT_ERROR,
+      });
+    }
+    // Type guard: result is an object and matches JsonWithComments structure
+    return {
+      success: true,
+      data: result,
+    };
+  } catch (error) {
+    return fail({
+      message: "app.api.shared.utils.parseJsonWithComments.errors.invalid_json",
+      errorType: ErrorResponseTypes.INVALID_FORMAT_ERROR,
+      messageParams: {
+        error: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+}
+
+/**
+ * Safely parse JSON with comments, returning null on error
+ *
+ * @param jsonString - JSON string potentially containing comments
+ * @returns Parsed JSON object or null if parsing fails
+ */
+export function tryParseJsonWithComments(
+  jsonString: string,
+): JsonWithComments | null {
+  const result = parseJsonWithComments(jsonString);
+  return result.success ? result.data : null;
+}

package/src/app/api/[locale]/shared/utils/time.ts

@@ -0,0 +1,53 @@
+import {
+  ErrorResponseTypes,
+  fail,
+  type ResponseType,
+  success,
+} from "../types/response.schema";
+
+/**
+ * Converts a time string in HH:MM format to seconds since midnight
+ * @param timeStr - Time string in HH:MM format
+ * @returns Success response with seconds or error response
+ */
+export function timeToSeconds(
+  timeStr: `${number}:${number}`,
+): ResponseType<number> {
+  const [hours, minutes] = timeStr.split(":").map(Number);
+  if (hours === undefined || minutes === undefined) {
+    return fail({
+      message: "app.api.shared.utils.time.errors.invalid_time_format.title",
+      errorType: ErrorResponseTypes.VALIDATION_ERROR,
+      messageParams: {
+        inputValue: timeStr,
+      },
+    });
+  }
+  return success(hours * 3600 + minutes * 60);
+}
+
+export type SimpleTimeFormat = `${number}:${number}`;
+
+/**
+ * Converts seconds since midnight to a time string in HH:MM format
+ * @param seconds - Seconds since midnight
+ * @returns Success response with time string or error response
+ */
+export function secondsToTime(seconds: number): ResponseType<string> {
+  if (seconds < 0 || seconds >= 86_400) {
+    return fail({
+      message: "app.api.shared.utils.time.errors.invalid_time_range.title",
+      errorType: ErrorResponseTypes.VALIDATION_ERROR,
+      messageParams: {
+        inputValue: seconds,
+      },
+    });
+  }
+
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+
+  const timeString = `${hours.toString().padStart(2, "0")}:${minutes.toString().padStart(2, "0")}`;
+
+  return success(timeString);
+}

package/src/app/api/[locale]/shared/utils/validation.ts

@@ -0,0 +1,127 @@
+import type { ZodError, ZodIssue } from "zod";
+import { z } from "zod";
+
+import type { EndpointLogger } from "@/app/api/[locale]/system/unified-interface/shared/logger/endpoint";
+
+import type { ResponseType } from "../types/response.schema";
+import { ErrorResponseTypes, fail } from "../types/response.schema";
+import { parseError } from "./parse-error";
+
+/**
+ * Validate data against a schema
+ * Accepts any data (from HTTP, user input, etc.) and validates it
+ * @param data - The data to validate (can be any type from HTTP)
+ * @param schema - The schema to validate against
+ * @returns A response with the validated data or error
+ */
+export function validateData<TSchema extends z.ZodType>(
+  data: Parameters<TSchema["parse"]>[0],
+  schema: TSchema,
+  logger: EndpointLogger,
+): ResponseType<z.infer<TSchema>> {
+  if (isEmptyObjectSchema(schema)) {
+    return { success: true, data: {} as z.infer<TSchema> };
+  }
+  if (isEmptySchema(schema)) {
+    return { success: true, data: undefined as z.infer<TSchema> };
+  }
+  if (isNeverSchema(schema)) {
+    return { success: true, data: undefined as z.infer<TSchema> };
+  }
+
+  try {
+    const result = schema.safeParse(data);
+
+    if (!result.success) {
+      const formattedErrors = formatZodErrors(result.error);
+      const errorCount = result.error.issues?.length || 0;
+      logger.error("Validation error details", {
+        errorCount,
+        errors: result.error.issues?.slice(0, 3).map((e: ZodIssue) => ({
+          path: e.path.join("."),
+          message: e.message,
+          code: e.code,
+        })),
+        allErrors: JSON.stringify(result.error.issues),
+        formattedErrors,
+        errorType: typeof result.error,
+        errorConstructor: result.error?.constructor?.name,
+        hasIssues: "issues" in result.error,
+        fullError: JSON.stringify(result.error, null, 2),
+      });
+      return fail({
+        message: "app.api.shared.errorTypes.validation_error",
+        errorType: ErrorResponseTypes.VALIDATION_ERROR,
+        messageParams: {
+          error: formattedErrors.join(", "),
+          errorCount: errorCount,
+        },
+      });
+    }
+
+    // For API responses, don't wrap the response in a success object, return the data directly
+    return { data: result.data, success: true };
+  } catch (error) {
+    const parsedError = parseError(error);
+    logger.error("Unexpected validation error", parsedError);
+    return fail({
+      message: "app.api.shared.errorTypes.validation_error",
+      errorType: ErrorResponseTypes.VALIDATION_ERROR,
+      messageParams: { error: parsedError.message },
+    });
+  }
+}
+
+/**
+ * Format Zod errors into a readable format
+ * @param zodError - The ZodError object to format
+ * @returns A formatted error string array
+ */
+function formatZodErrors(zodError: ZodError): string[] {
+  if (
+    !zodError?.issues ||
+    !Array.isArray(zodError.issues) ||
+    zodError.issues.length === 0
+  ) {
+    return ["error.general.unknown_validation_error"];
+  }
+  return zodError.issues.map(
+    (err: ZodIssue) => `${err.path.join(".")}: ${err.message}`,
+  );
+}
+
+/**
+ * Check if request schema is an empty object
+ */
+export function isEmptyObjectSchema(schema: z.ZodSchema): boolean {
+  return (
+    schema instanceof z.ZodObject && Object.keys(schema.shape).length === 0
+  );
+}
+
+/**
+ * Check if schema expects no input (undefined or never)
+ */
+export function isEmptySchema(schema: z.ZodSchema): boolean {
+  return (
+    schema instanceof z.ZodUndefined ||
+    schema instanceof z.ZodNever ||
+    schema instanceof z.ZodVoid
+  );
+}
+
+/**
+ * Check if schema expects never type specifically
+ */
+export function isNeverSchema(schema: z.ZodSchema): boolean {
+  try {
+    const testResult = schema.safeParse({});
+    return (
+      !testResult.success &&
+      testResult.error?.issues?.[0]?.code === "invalid_type" &&
+      testResult.error?.issues?.[0]?.expected === "never"
+    );
+  } catch {
+    return false;
+  }
+}