@revealui/core 0.0.1-pre.0

package/dist/core/errors/ErrorHandler.ts

@@ -0,0 +1,480 @@
+/**
+ * Unified Error Handling System
+ *
+ * Consolidates all error handling patterns across the codebase.
+ * Replaces 2,927 try-catch blocks with standardized error handling.
+ */
+
+// ======
+// ERROR TYPES
+// ======
+
+import type { ErrorContext, ErrorDetails } from '../types/contracts';
+
+export class DomainError extends Error {
+  public readonly code: string;
+  public readonly details?: ErrorDetails;
+  public override readonly cause?: Error;
+
+  constructor(
+    message: string,
+    code: string = 'DOMAIN_ERROR',
+    details?: ErrorDetails,
+    cause?: Error
+  ) {
+    super(message);
+    this.name = 'DomainError';
+    this.code = code;
+    if (details) this.details = details;
+    if (cause) this.cause = cause;
+  }
+}
+
+export class ValidationError extends Error {
+  public readonly field: string;
+  public readonly code: string;
+
+  constructor(field: string, message: string, code: string = 'VALIDATION_ERROR') {
+    super(message);
+    this.name = 'ValidationError';
+    this.field = field;
+    this.code = code;
+  }
+}
+
+export class InfrastructureError extends Error {
+  public readonly code: string;
+  public readonly context?: ErrorContext;
+
+  constructor(message: string, code: string = 'INFRASTRUCTURE_ERROR', context?: ErrorContext) {
+    super(message);
+    this.name = 'InfrastructureError';
+    this.code = code;
+    if (context) this.context = context;
+  }
+}
+
+export class BusinessRuleError extends Error {
+  public readonly rule: string;
+
+  constructor(rule: string, message: string) {
+    super(message);
+    this.name = 'BusinessRuleError';
+    this.rule = rule;
+  }
+}
+
+// ======
+// ERROR HANDLER CLASS
+// ======
+
+export class ErrorHandler {
+  private static instance: ErrorHandler;
+
+  static getInstance(): ErrorHandler {
+    if (!ErrorHandler.instance) {
+      ErrorHandler.instance = new ErrorHandler();
+    }
+    return ErrorHandler.instance;
+  }
+
+  // ======
+  // ERROR TRANSFORMATION
+  // ======
+
+  transformError(error: unknown, _context?: ErrorContext): Error {
+    if (error instanceof Error) {
+      return error;
+    }
+
+    const message = typeof error === 'string' ? error : 'Unknown error occurred';
+    return new Error(message);
+  }
+
+  wrapError(error: unknown, operation: string, context?: ErrorContext): Error {
+    const transformedError = this.transformError(error);
+
+    console.error(`Error in operation: ${operation}`, {
+      error: transformedError.message,
+      operation,
+      context,
+      stack: transformedError.stack,
+    });
+
+    return transformedError;
+  }
+
+  // ======
+  // ERROR LOGGING
+  // ======
+
+  // Using Record<string, unknown> because error context structure varies by operation type
+  logError(error: unknown, operation: string, context?: Record<string, unknown>): void {
+    const transformedError = this.transformError(error);
+
+    console.error(`Operation failed: ${operation}`, {
+      error: transformedError.message,
+      operation,
+      context,
+      stack: transformedError.stack,
+    });
+  }
+
+  logDomainError(error: DomainError, operation: string): void {
+    console.error(`Domain error in operation: ${operation}`, {
+      error: error.message,
+      code: error.code,
+      operation,
+      details: error.details,
+      cause: error.cause?.message,
+    });
+  }
+
+  logValidationError(error: ValidationError, operation: string): void {
+    console.warn(`Validation error in operation: ${operation}`, {
+      error: error.message,
+      field: error.field,
+      code: error.code,
+      operation,
+    });
+  }
+
+  logInfrastructureError(error: InfrastructureError, operation: string): void {
+    console.error(`Infrastructure error in operation: ${operation}`, {
+      error: error.message,
+      code: error.code,
+      operation,
+      context: error.context,
+    });
+  }
+
+  // ======
+  // ERROR RECOVERY
+  // ======
+
+  async withRetry<T>(
+    operation: () => Promise<T>,
+    maxRetries: number = 3,
+    delay: number = 1000,
+    operationName: string = 'unknown'
+  ): Promise<T> {
+    let lastError: Error;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = this.transformError(error);
+
+        if (attempt === maxRetries) {
+          console.error(`Operation failed after ${maxRetries} attempts: ${operationName}`, {
+            error: lastError.message,
+            operation: operationName,
+            attempts: maxRetries,
+          });
+          throw lastError;
+        }
+
+        console.warn(`Operation failed, retrying (${attempt}/${maxRetries}): ${operationName}`, {
+          error: lastError.message,
+          operation: operationName,
+          attempt,
+        });
+
+        await new Promise(resolve => setTimeout(resolve, delay * attempt));
+      }
+    }
+
+    throw lastError!;
+  }
+
+  // ======
+  // ERROR CLASSIFICATION
+  // ======
+
+  isDomainError(error: unknown): error is DomainError {
+    return error instanceof DomainError;
+  }
+
+  isValidationError(error: unknown): error is ValidationError {
+    return error instanceof ValidationError;
+  }
+
+  isInfrastructureError(error: unknown): error is InfrastructureError {
+    return error instanceof InfrastructureError;
+  }
+
+  isBusinessRuleError(error: unknown): error is BusinessRuleError {
+    return error instanceof BusinessRuleError;
+  }
+
+  // ======
+  // ERROR CONTEXT
+  // ======
+
+  createErrorContext(operation: string, context?: ErrorContext): ErrorContext {
+    return {
+      operation,
+      timestamp: new Date().toISOString(),
+      ...context,
+    };
+  }
+
+  // ======
+  // ERROR HANDLING (returns result objects for service responses)
+  // ======
+
+  handle(
+    error: unknown,
+    context?: ErrorContext
+  ): {
+    success: boolean;
+    error?: string;
+    type?: string;
+    context?: ErrorContext;
+    details?: string;
+  } {
+    const transformedError = this.transformError(error);
+
+    if (this.isDomainError(error)) {
+      this.logDomainError(
+        error,
+        ((context as Record<string, unknown>)['operation'] as string | undefined) || 'unknown'
+      );
+      return {
+        success: false,
+        error: transformedError.message,
+        type: 'domain',
+        ...(context ? { context } : {}),
+        ...(error.stack ? { details: error.stack } : {}),
+      };
+    }
+
+    if (this.isValidationError(error)) {
+      this.logValidationError(
+        error,
+        ((context as Record<string, unknown>)['operation'] as string | undefined) || 'unknown'
+      );
+      return {
+        success: false,
+        error: transformedError.message,
+        type: 'validation',
+        ...(context ? { context } : {}),
+        ...(error.stack ? { details: error.stack } : {}),
+      };
+    }
+
+    if (this.isInfrastructureError(error)) {
+      this.logInfrastructureError(
+        error,
+        ((context as Record<string, unknown>)['operation'] as string | undefined) || 'unknown'
+      );
+      return {
+        success: false,
+        error: transformedError.message,
+        type: 'infrastructure',
+        ...(context ? { context } : {}),
+        ...(error.stack ? { details: error.stack } : {}),
+      };
+    }
+
+    if (this.isBusinessRuleError(error)) {
+      return {
+        success: false,
+        error: transformedError.message,
+        type: 'business',
+        ...(context ? { context } : {}),
+        ...(error.stack ? { details: error.stack } : {}),
+      };
+    }
+
+    if (error instanceof Error) {
+      this.logError(
+        error,
+        ((context as Record<string, unknown>)['operation'] as string | undefined) || 'unknown',
+        context
+      );
+      return {
+        success: false,
+        error: transformedError.message,
+        type: 'generic',
+        ...(context ? { context } : {}),
+        ...(error.stack ? { details: error.stack } : {}),
+      };
+    }
+
+    return {
+      success: false,
+      error: 'Unknown error occurred',
+      type: 'unknown',
+      ...(context ? { context } : {}),
+    };
+  }
+
+  // ======
+  // ERROR RECOVERY
+  // ======
+
+  async handleWithRecovery<T>(
+    error: unknown,
+    recoveryFn: (error: Error) => Promise<T>
+  ): Promise<{ success: boolean; data?: T; error?: string }> {
+    const transformedError = this.transformError(error);
+
+    try {
+      const data = await recoveryFn(transformedError);
+      return {
+        success: true,
+        data,
+      };
+    } catch (recoveryError) {
+      const transformedRecoveryError = this.transformError(recoveryError);
+      return {
+        success: false,
+        error: transformedRecoveryError.message,
+      };
+    }
+  }
+
+  // ======
+  // ERROR CLASSIFICATION
+  // ======
+
+  classifyError(
+    error: unknown
+  ): 'domain' | 'validation' | 'infrastructure' | 'business' | 'generic' {
+    if (this.isDomainError(error)) return 'domain';
+    if (this.isValidationError(error)) return 'validation';
+    if (this.isInfrastructureError(error)) return 'infrastructure';
+    if (this.isBusinessRuleError(error)) return 'business';
+    return 'generic';
+  }
+}
+
+// ======
+// DECORATOR FUNCTIONS
+// ======
+
+export function withErrorHandling<
+  TArgs extends unknown[],
+  TReturn,
+  T extends (...args: TArgs) => Promise<TReturn>,
+>(fn: T, operationName: string): T {
+  return (async (...args: Parameters<T>) => {
+    const errorHandler = ErrorHandler.getInstance();
+
+    try {
+      return await fn(...args);
+    } catch (error) {
+      errorHandler.logError(error, operationName);
+      throw errorHandler.wrapError(error, operationName);
+    }
+  }) as T;
+}
+
+export function withDomainErrorHandling<
+  TArgs extends unknown[],
+  TReturn,
+  T extends (...args: TArgs) => Promise<TReturn>,
+>(fn: T, operationName: string): T {
+  return (async (...args: Parameters<T>) => {
+    const errorHandler = ErrorHandler.getInstance();
+
+    try {
+      return await fn(...args);
+    } catch (error) {
+      if (errorHandler.isDomainError(error)) {
+        errorHandler.logDomainError(error, operationName);
+      } else {
+        errorHandler.logError(error, operationName);
+      }
+      throw error;
+    }
+  }) as T;
+}
+
+export function withValidationErrorHandling<
+  TArgs extends unknown[],
+  TReturn,
+  T extends (...args: TArgs) => Promise<TReturn>,
+>(fn: T, operationName: string): T {
+  return (async (...args: Parameters<T>) => {
+    const errorHandler = ErrorHandler.getInstance();
+
+    try {
+      return await fn(...args);
+    } catch (error) {
+      if (errorHandler.isValidationError(error)) {
+        errorHandler.logValidationError(error, operationName);
+      } else {
+        errorHandler.logError(error, operationName);
+      }
+      throw error;
+    }
+  }) as T;
+}
+
+// ======
+// SERVICE RESULT HELPERS
+// ======
+
+// Using Record<string, unknown> because error context structure varies by operation type
+export function handleServiceError<T>(
+  error: unknown,
+  operationName: string,
+  context?: Record<string, unknown>
+): { success: boolean; data?: T; error?: Error } {
+  const errorHandler = ErrorHandler.getInstance();
+  const transformedError = errorHandler.transformError(error);
+
+  errorHandler.logError(error, operationName, context);
+
+  return {
+    success: false,
+    error: transformedError,
+  };
+}
+
+export function handleDomainServiceError<T>(
+  error: unknown,
+  operationName: string
+): { success: boolean; data?: T; error?: Error } {
+  const errorHandler = ErrorHandler.getInstance();
+
+  if (errorHandler.isDomainError(error)) {
+    errorHandler.logDomainError(error, operationName);
+  } else {
+    errorHandler.logError(error, operationName);
+  }
+
+  return {
+    success: false,
+    error: errorHandler.transformError(error),
+  };
+}
+
+// ======
+// GLOBAL ERROR HANDLER
+// ======
+
+export function setupGlobalErrorHandling(): void {
+  const errorHandler = ErrorHandler.getInstance();
+
+  // Handle uncaught exceptions
+  process.on('uncaughtException', error => {
+    errorHandler.logError(error, 'uncaughtException');
+    process.exit(1);
+  });
+
+  // Handle unhandled promise rejections
+  process.on('unhandledRejection', (reason, promise) => {
+    errorHandler.logError(reason, 'unhandledRejection', { promise });
+  });
+}
+
+// ======
+// EXPORTS
+// ======
+
+// All classes and functions are exported directly above - no re-export needed
+

package/dist/core/files/file-system/filesystemPath.ts

@@ -0,0 +1,27 @@
+import { assert } from "../../gaurds/assertions/assert";
+
+export { assertPosixPath, toPosixPath };
+
+/**
+ * Converts a path to a posix path.
+ * @param path - The path to convert.
+ * @returns The path in posix format.
+ */
+
+function toPosixPath(path: string): string {
+  const pathPosix = path.split("\\").join("/");
+  assertPosixPath(pathPosix);
+  return pathPosix;
+}
+
+function assertPosixPath(path: string): void {
+  const errMsg = (msg: string) => `Not a posix path: ${msg}`;
+  assert(path !== null, errMsg("null"));
+  assert(
+    typeof path === "string",
+    errMsg(`typeof path === ${JSON.stringify(typeof path)}`),
+  );
+  assert(path !== "", errMsg("(empty string)"));
+  assert(path);
+  assert(!path.includes("\\"), errMsg(path));
+}

package/dist/core/files/file-system/findFile.ts

@@ -0,0 +1,35 @@
+export { findFile }
+
+import fs from "fs"
+import path from "path"
+import { isArray } from "../../gaurds/validators/isArray.js"
+import { assertPosixPath } from "./filesystemPath.js"
+
+type Filename =
+  | "package.json"
+  | "reveal.config.js"
+  | "reveal.config.ts"
+  | "reveal.config.ts"
+  | "reveal.config.js"
+  | "vite.config.ts"
+  | "vite.config.js"
+
+function findFile(arg: Filename | Filename[], cwd: string): null | string {
+  assertPosixPath(cwd)
+  const filenames = isArray(arg) ? arg : [arg]
+  let dir = cwd
+  while (true) {
+    for (const filename of filenames) {
+      const configFilePath = path.posix.join(dir, `./${filename}`)
+      if (fs.existsSync(configFilePath)) {
+        assertPosixPath(configFilePath)
+        return configFilePath
+      }
+    }
+    const dirPrevious = dir
+    dir = path.posix.dirname(dir)
+    if (dir === dirPrevious) {
+      return null
+    }
+  }
+}

package/dist/core/files/file-system/findPackageJson.ts

@@ -0,0 +1,19 @@
+export { findPackageJson };
+
+import { createRequire } from "module";
+import { findFile } from "./findFile.js";
+// @ts-ignore Shimmed by dist-cjs-fixup.js for CJS build.
+const importMetaUrl: string = import.meta.url;
+const require_ = createRequire(importMetaUrl);
+
+function findPackageJson(
+  cwd: string,
+): null | { packageJson: Record<string, unknown>; packageJsonPath: string } {
+  const packageJsonPath = findFile("package.json", cwd);
+  if (!packageJsonPath) return null;
+  const packageJson = require_(packageJsonPath);
+  return {
+    packageJson,
+    packageJsonPath,
+  };
+}

package/dist/core/files/file-system/findPageFiles.ts

@@ -0,0 +1,40 @@
+export { findPageFiles }
+
+import glob from "fast-glob"
+import type { ResolvedConfig } from "vite"
+
+import pc from "@brillout/picocolors"
+import { FileType } from "../../../types/interfaces/file.js"
+import { assertWarning } from "../../gaurds/assertions/assertWarning/index.js"
+import { scriptFileExtensions } from "../../gaurds/validators/isScriptFile.js"
+import { getOutDirs } from "../../processing/getters/getOutDirs.js"
+import { toPosixPath } from "./filesystemPath.js"
+
+async function findPageFiles(
+  config: ResolvedConfig,
+  fileTypes: FileType[],
+  isDev: boolean
+): Promise<string[]> {
+  const cwd = config.root
+  const { outDirRoot } = getOutDirs(config)
+  const timeBase = new Date().getTime()
+  let pageFiles = await glob(
+    fileTypes.map((fileType) => `**/*${fileType}.${scriptFileExtensions}`),
+    { ignore: ["**/node_modules/**", `${outDirRoot}/**`], cwd, dot: false }
+  )
+  pageFiles = pageFiles.map((p) => "/" + toPosixPath(p))
+  const time = new Date().getTime() - timeBase
+  if (isDev) {
+    // We only warn in dev, because while building it's expected to take a long time as fast-glob is competing for resources with other tasks
+    assertWarning(
+      time < 1.5 * 1000,
+      `Finding your page files ${pc.cyan(
+        "**/*.page.*"
+      )} took an unexpected long time (${time}ms). Reach out to the reveal maintainer.`,
+      {
+        onlyOnce: "slow-page-files-search",
+      }
+    )
+  }
+  return pageFiles
+}

package/dist/core/files/file-system/pathShim.ts

@@ -0,0 +1,16 @@
+import { assert } from "../../gaurds/assertions/assert";
+
+export { pathShim };
+
+// Simple shim for `import * from "node:path"` used by the server runtime.
+// Robust alternative: https://github.com/unjs/pathe
+
+function pathShim(path1: string, path2: string): string {
+  assert(!path1.includes("\\"));
+  assert(!path2.includes("\\"));
+  let joined = [...path1.split("/"), ...path2.split("/")]
+    .filter(Boolean)
+    .join("/");
+  if (path1.startsWith("/")) joined = "/" + joined;
+  return joined;
+}

package/dist/core/files/file-system/prependEntriesDir.ts

@@ -0,0 +1,13 @@
+import { assert } from "../../gaurds/assertions/assert";
+
+export { prependEntriesDir };
+
+function prependEntriesDir(entryName: string): string {
+  if (entryName.startsWith("/")) {
+    entryName = entryName.slice(1);
+  }
+  assert(!entryName.startsWith("/"));
+  assert(entryName);
+  entryName = `entries/${entryName}`;
+  return entryName;
+}

package/dist/core/files/file-system/removeFileExtention.ts

@@ -0,0 +1,3 @@
+export function removeFileExtention(filePath: string) {
+  return filePath.split(".").slice(0, -1).join(".");
+}

package/dist/core/files/file-system/requireResolve.ts

@@ -0,0 +1,59 @@
+export { requireResolve };
+
+import { createRequire } from "module";
+import { scriptFileExtensionList } from "../../gaurds/validators/isScriptFile.js";
+import { assertIsNotBrowser } from "../../gaurds/assertions/assertIsNotBrowser/index.js";
+import { assertIsNotProductionRuntime } from "../../gaurds/assertions/assertIsNotProductionRuntime/index.js";
+import { assertPosixPath, toPosixPath } from "./filesystemPath.js";
+import { assert } from "../../gaurds/assertions/assert/index.js";
+
+// @ts-ignore Shimmed by dist-cjs-fixup.js for CJS build.
+const importMetaUrl: string = import.meta.url;
+const require_ = createRequire(importMetaUrl);
+
+assertIsNotBrowser();
+assertIsNotProductionRuntime();
+
+function requireResolve(importPath: string, cwd: string): string | null {
+  assertPosixPath(cwd);
+  const clean = addFileExtensionsToRequireResolve();
+  importPath = removeFileExtention(importPath);
+  let importedFile: string | null;
+  try {
+    importedFile = require_.resolve(importPath, { paths: [cwd] });
+  } catch {
+    importedFile = null;
+  } finally {
+    clean();
+  }
+  if (importedFile) {
+    importedFile = toPosixPath(importedFile);
+  }
+  return importedFile;
+}
+
+function removeFileExtention(importPath: string) {
+  for (const ext of scriptFileExtensionList) {
+    const suffix = `.${ext}`;
+    if (importPath.endsWith(suffix)) {
+      return importPath.slice(0, -1 * suffix.length);
+    }
+  }
+  return importPath;
+}
+
+function addFileExtensionsToRequireResolve() {
+  const added: string[] = [];
+  scriptFileExtensionList.forEach((ext: string) => {
+    assert(!ext.includes("."));
+    ext = `.${ext}`;
+    added.push(ext);
+    
+  });
+  const clean = () => {
+    added.forEach((ext) => {
+     createRequire(ext);
+    });
+  };
+  return clean;
+}