@revealui/core 0.0.1-pre.0

package/dist/core/router/routeInternal.ts

@@ -0,0 +1,97 @@
+import { PageContextForRoute, PageContextFromRoute } from "../router";
+import { resolveRouteString, resolveRouteFunction } from "./resolveRouteUtils";
+import { assert } from "../utils";
+import type { PageRoutes, RouteType } from "./loadPageRoutes";
+import type { Hook } from "../processing/getters/getHook";
+import { executeOnBeforeRouteHook } from "./executeOnBeforeRouteHook";
+import { objectAssign } from "./utils";
+import { PageContextUrlInternal } from "../processing/getters/getPageContextUrlComputed";
+
+// Core routing logic
+async function routeInternal(
+  pageContext: PageContextForRoute,
+): Promise<PageContextFromRoute> {
+  const pageRoutes: PageRoutes = pageContext._pageRoutes;
+  const urlPathname: string = pageContext.urlPathname;
+  const routeMatches = [];
+
+  // Execute onBeforeRoute hook if defined
+  const pageContextFromHook = await executeOnBeforeRouteHook(pageContext);
+  if (
+    pageContextFromHook &&
+    pageContextFromHook._routingProvidedByOnBeforeRouteHook &&
+    pageContextFromHook.pageId
+  ) {
+    return pageContextFromHook;
+  }
+
+  // Iterate through available routes to find a match
+  for (const pageRoute of pageRoutes) {
+    const { routeType, pageId } = pageRoute;
+
+    if (routeType === "STRING" && pageRoute.routeString) {
+      const match = resolveRouteString(pageRoute.routeString, urlPathname);
+      if (match) {
+        routeMatches.push({
+          pageId,
+          routeParams: match.routeParams,
+          routeType,
+        });
+        continue;
+      }
+    }
+
+    if (
+      routeType === "FUNCTION" &&
+      typeof pageRoute.routeFunction === "function"
+    ) {
+      const match = await resolveRouteFunction(
+        pageRoute.routeFunction as (
+          pageContext: PageContextUrlInternal,
+        ) => unknown,
+        pageContext,
+      );
+      if (match) {
+        routeMatches.push({
+          pageId,
+          routeParams: match.routeParams,
+          routeType,
+        });
+        continue;
+      }
+    }
+
+    if (routeType === "FILESYSTEM" && pageRoute.routeFilesystemDefinedBy) {
+      const match = resolveRouteString(pageRoute.routeString, urlPathname);
+      if (match) {
+        routeMatches.push({
+          pageId,
+          routeParams: match.routeParams,
+          routeType,
+        });
+        continue;
+      }
+    }
+  }
+
+  // Sort routes by precedence if multiple matches
+  routeMatches.sort((a, b) => {
+    if ("precedence" in a && "precedence" in b) {
+      return (a.precedence as number) - (b.precedence as number);
+    }
+    return 0;
+  });
+
+  const bestMatch = routeMatches[0] ?? null;
+
+  // Assign matched route context to pageContextFromRoute
+  const pageContextFromRoute: PageContextFromRoute = {
+    pageId: bestMatch ? bestMatch.pageId : null,
+    routeParams: bestMatch ? bestMatch.routeParams : {},
+    _debugRouteMatches: routeMatches,
+  };
+
+  return pageContextFromRoute;
+}
+
+export { routeInternal };

package/dist/core/router/utils.ts

@@ -0,0 +1,30 @@
+// Utils needed by:
+//  - runtime of server
+//  - runtime of client (Client Routing)
+
+// Ensure we don't bloat runtime of Server Routing with the utils down below
+import { assertClientRouting } from "../gaurds/assertions/assertRoutingType/index.js";
+import { isBrowser } from "../gaurds/validators/isBrowser.js";
+
+if (isBrowser()) {
+  assertClientRouting();
+}
+
+export * from "../targets/url/parseUrl.js";
+export * from "../gaurds/assertions/checkType.js";
+export * from "../gaurds/validators/hasProp.js";
+export * from "../gaurds/validators/isBrowser.js";
+export * from "../gaurds/validators/isObjectWithKeys.js";
+export * from "../gaurds/validators/isPlainObject.js";
+export * from "../gaurds/validators/isPromise.js";
+export * from "../utils/array/slice.js";
+export * from "../utils/array/sorter.js";
+export * from "../utils/array/unique.js";
+export * from "../gaurds/assertions/assertUsage/index.js";
+export * from "../gaurds/assertions/assertInfo/index.js";
+export * from "../gaurds/assertions/assertWarning/index.js";
+export * from "../gaurds/assertions/assert/index.js";
+export * from "../gaurds/validators/isCallable.js";
+export * from "../utils/object/objectAssign.js";
+export * from "../utils/string/joinEnglish.js";
+export * from "../utils/string/truncateString.js";

package/dist/core/services/BaseService.ts

@@ -0,0 +1,403 @@
+/**
+ * Unified Base Service
+ *
+ * Consolidates all base service functionality into a single hierarchy.
+ * Replaces 5 duplicate base service implementations.
+ */
+
+import { type UnifiedLoggerV2, createLogger } from '../logging';
+import type { Result } from '../result';
+import { toServiceResult } from '../result/adapters';
+import type { ServiceResult } from '../types/contracts';
+
+// ======
+// CORE INTERFACES
+// ======
+
+export interface ServiceMetrics {
+  count: number;
+  totalTime: number;
+  errors: number;
+}
+
+export interface HealthStatus {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  uptime: number;
+  // Using Record<string, unknown> because service metrics structure varies by service type and cannot be strictly typed
+  metrics: /* Using Record<string, unknown> because service metrics structure varies by service type and cannot be strictly typed */ Record<
+    string,
+    { count: number; averageTime: number; errorRate: number }
+  >;
+}
+
+export interface ServiceMetadata {
+  name: string;
+  type: 'application' | 'domain' | 'infrastructure';
+  startTime: Date;
+  payloadAvailable?: boolean;
+}
+
+// ======
+// BASE SERVICE CLASS
+// ======
+
+export abstract class BaseService {
+  protected readonly logger: UnifiedLoggerV2;
+  protected readonly serviceName: string;
+  protected readonly startTime: Date = new Date();
+  protected readonly metrics: Map<string, ServiceMetrics> = new Map();
+  protected readonly serviceType: 'application' | 'domain' | 'infrastructure';
+
+  constructor(
+    protected readonly payload: unknown | null,
+    serviceName: string,
+    serviceType: 'application' | 'domain' | 'infrastructure' = 'application'
+  ) {
+    this.serviceName = serviceName;
+    this.serviceType = serviceType;
+    this.logger = createLogger(serviceName);
+
+    // Validate PayloadCMS instance for infrastructure and application services (optional)
+    if (serviceType !== 'domain' && !payload) {
+      this.logger.warn(`PayloadCMS instance not provided for ${serviceType} service: ${serviceName}`);
+    }
+
+    this.logger.info(`${serviceName} initialized`);
+  }
+
+  // ======
+  // LIFECYCLE METHODS
+  // ======
+
+  /**
+   * Public initialize method - calls protected onInitialize()
+   * Can be overridden in subclasses via onInitialize()
+   */
+  public async initialize(): Promise<void> {
+    await this.onInitialize();
+  }
+
+  /**
+   * Public cleanup method - calls protected onCleanup()
+   * Can be overridden in subclasses via onCleanup()
+   */
+  public async cleanup(): Promise<void> {
+    await this.onCleanup();
+  }
+
+  /**
+   * Public healthCheck method - calls protected onHealthCheck()
+   * Can be overridden in subclasses via onHealthCheck()
+   */
+  public async healthCheck(): Promise<void> {
+    await this.onHealthCheck();
+  }
+
+  /**
+   * Protected hook for initialization - override in subclasses
+   */
+  protected async onInitialize(): Promise<void> {
+    this.logger.info(`${this.serviceName} initializing`);
+    // Override in subclasses for specific initialization
+  }
+
+  /**
+   * Protected hook for cleanup - override in subclasses
+   */
+  protected async onCleanup(): Promise<void> {
+    this.logger.info(`${this.serviceName} cleaning up`);
+    // Override in subclasses for specific cleanup
+  }
+
+  /**
+   * Protected hook for health checks - override in subclasses
+   */
+  protected async onHealthCheck(): Promise<void> {
+    // Override in subclasses for specific health checks
+    this.logger.debug(`${this.serviceName} health check passed`);
+  }
+
+  // ======
+  // OPERATION EXECUTION
+  // ======
+
+  protected async executeOperation<T>(
+    operation: () => Promise<T>,
+    operationName: string,
+    // Using Record<string, unknown> because operation context structure varies by operation type and cannot be strictly typed
+    context?: /* Using Record<string, unknown> because operation context structure varies by operation type and cannot be strictly typed */ Record<
+      string,
+      unknown
+    >
+  ): Promise<Result<T, Error> | ServiceResult<T>> {
+    const startTime = Date.now();
+
+    try {
+      this.logger.info(`Starting operation: ${operationName}`, {
+        service: this.serviceName,
+        context,
+      });
+
+      const result = await operation();
+      const duration = Date.now() - startTime;
+
+      this.recordSuccess(operationName, duration);
+
+      this.logger.info(`Completed operation: ${operationName}`, {
+        service: this.serviceName,
+        duration,
+        context,
+      });
+
+      // Return UnifiedResult
+      return { _tag: 'Success', value: result, success: true };
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      this.recordError(operationName, duration);
+
+      const errorResult = this.handleError<T>(error, operationName, context);
+
+      // Convert ServiceResult to UnifiedResult
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      return { _tag: 'Failure', error: errorObj, success: false };
+    }
+  }
+
+  // ======
+  // ERROR HANDLING
+  // ======
+
+  protected handleError<T>(
+    error: unknown,
+    operationName: string,
+    // Using Record<string, unknown> because error context structure varies by error type and cannot be strictly typed
+    context?: /* Using Record<string, unknown> because error context structure varies by error type and cannot be strictly typed */ Record<
+      string,
+      unknown
+    >
+  ): ServiceResult<T> {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+
+    this.logger.error(`Operation failed: ${operationName}`, {
+      error: errorMessage,
+      service: this.serviceName,
+      operation: operationName,
+      context,
+    });
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : errorMessage,
+    };
+  }
+
+  // ======
+  // METRICS TRACKING
+  // ======
+
+  protected recordSuccess(operationName: string, duration: number): void {
+    const existing = this.metrics.get(operationName) ?? { count: 0, totalTime: 0, errors: 0 };
+    this.metrics.set(operationName, {
+      count: existing.count + 1,
+      totalTime: existing.totalTime + duration,
+      errors: existing.errors,
+    });
+  }
+
+  protected recordError(operationName: string, duration: number): void {
+    const existing = this.metrics.get(operationName) ?? { count: 0, totalTime: 0, errors: 0 };
+    this.metrics.set(operationName, {
+      count: existing.count + 1,
+      totalTime: existing.totalTime + duration,
+      errors: existing.errors + 1,
+    });
+  }
+
+  // ======
+  // HEALTH MONITORING
+  // ======
+
+  async getHealthStatus(): Promise<ServiceResult<HealthStatus>> {
+    try {
+      await this.onHealthCheck();
+
+      const uptime = Date.now() - this.startTime.getTime();
+      const metrics: Record<string, { count: number; averageTime: number; errorRate: number }> = {};
+
+      for (const [operation, data] of this.metrics.entries()) {
+        metrics[operation] = {
+          count: data.count,
+          averageTime: data.count > 0 ? data.totalTime / data.count : 0,
+          errorRate: data.count > 0 ? data.errors / data.count : 0,
+        };
+      }
+
+      // Determine health status based on error rates
+      const totalErrors = Array.from(this.metrics.values()).reduce(
+        (sum, data) => sum + data.errors,
+        0
+      );
+      const totalOperations = Array.from(this.metrics.values()).reduce(
+        (sum, data) => sum + data.count,
+        0
+      );
+      const errorRate = totalOperations > 0 ? totalErrors / totalOperations : 0;
+
+      let status: 'healthy' | 'degraded' | 'unhealthy';
+      if (errorRate > 0.5) status = 'unhealthy';
+      else if (errorRate > 0.1) status = 'degraded';
+      else status = 'healthy';
+
+      return {
+        success: true,
+        data: { status, uptime, metrics },
+      };
+    } catch (error) {
+      return this.handleError(error, 'getHealthStatus');
+    }
+  }
+
+  // ======
+  // METADATA
+  // ======
+
+  getMetadata(): ServiceMetadata {
+    return {
+      name: this.serviceName,
+      type: this.serviceType,
+      startTime: this.startTime,
+      payloadAvailable: !!this.payload,
+    };
+  }
+
+  // ======
+  // UTILITY METHODS
+  // ======
+
+  protected validateBusinessRule(condition: boolean, errorMessage: string): void {
+    if (!condition) {
+      throw new Error(`Business rule violation: ${errorMessage}`);
+    }
+  }
+
+  protected async executeInTransaction<T>(
+    operation: () => Promise<T>,
+    operationName: string
+  ): Promise<ServiceResult<T>> {
+    const result = await this.executeOperation(async () => {
+      // In a real implementation, this would start a database transaction
+      // For now, we'll just execute the operation
+      return await operation();
+    }, `${operationName}_transaction`);
+    // Convert Result to ServiceResult if needed
+    if ('isSuccess' in result || 'isFailure' in result) {
+      return toServiceResult(result as Result<T, Error>);
+    }
+    return result as ServiceResult<T>;
+  }
+
+  protected async coordinateServices<T>(
+    services: Array<() => Promise<unknown>>,
+    operationName: string
+  ): Promise<ServiceResult<T>> {
+    const result = await this.executeOperation(async () => {
+      const results = await Promise.all(services.map(service => service()));
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return results as any as T;
+    }, `${operationName}_coordination`);
+    // Convert Result to ServiceResult if needed
+    if ('isSuccess' in result || 'isFailure' in result) {
+      return toServiceResult(result as Result<T, Error>);
+    }
+    return result as ServiceResult<T>;
+  }
+}
+
+// ======
+// LAYER-SPECIFIC EXTENSIONS
+// ======
+
+export abstract class ApplicationService extends BaseService {
+  constructor(payload: unknown, serviceName: string) {
+    super(payload, serviceName, 'application');
+  }
+
+  protected async executeApplicationOperation<T>(
+    operation: () => Promise<T>,
+    operationName: string,
+    // Using Record<string, unknown> because operation context structure varies by operation type and cannot be strictly typed
+    context?: /* Using Record<string, unknown> because operation context structure varies by operation type and cannot be strictly typed */ Record<
+      string,
+      unknown
+    >
+  ): Promise<ServiceResult<T>> {
+    const result = await this.executeOperation(operation, operationName, context);
+    // Convert Result to ServiceResult if needed
+    if ('isSuccess' in result || 'isFailure' in result) {
+      return toServiceResult(result as Result<T, Error>);
+    }
+    return result as ServiceResult<T>;
+  }
+
+  protected handleApplicationError<T>(
+    error: unknown,
+    operationName: string,
+    // Using Record<string, unknown> because error context structure varies by error type and cannot be strictly typed
+    context?: /* Using Record<string, unknown> because error context structure varies by error type and cannot be strictly typed */ Record<
+      string,
+      unknown
+    >
+  ): ServiceResult<T> {
+    return this.handleError(error, operationName, context);
+  }
+}
+
+export abstract class DomainService extends BaseService {
+  constructor(serviceName: string) {
+    super(null, serviceName, 'domain');
+  }
+
+  protected async executeDomainOperation<T>(
+    operation: () => Promise<T>,
+    operationName: string
+  ): Promise<ServiceResult<T>> {
+    const result = await this.executeOperation(operation, operationName);
+    // Convert Result to ServiceResult if needed
+    if ('isSuccess' in result || 'isFailure' in result) {
+      return toServiceResult(result as Result<T, Error>);
+    }
+    return result as ServiceResult<T>;
+  }
+
+  protected handleDomainError<T>(error: unknown, _operationName: string): ServiceResult<T> {
+    // Domain services should not log - that's infrastructure concern
+    const errorMessage = error instanceof Error ? error.message : 'Unknown domain error';
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : errorMessage,
+    };
+  }
+}
+
+export abstract class InfrastructureService extends BaseService {
+  constructor(payload: unknown, serviceName: string) {
+    super(payload, serviceName, 'infrastructure');
+  }
+
+  protected async executeInfrastructureOperation<T>(
+    operation: () => Promise<T>,
+    operationName: string
+  ): Promise<ServiceResult<T>> {
+    const result = await this.executeOperation(operation, operationName);
+    // Convert Result to ServiceResult if needed
+    if ('isSuccess' in result || 'isFailure' in result) {
+      return toServiceResult(result as Result<T, Error>);
+    }
+    return result as ServiceResult<T>;
+  }
+
+  protected handleInfrastructureError<T>(error: unknown, operationName: string): ServiceResult<T> {
+    return this.handleError(error, operationName);
+  }
+}
+

package/dist/core/targets/client/abort.ts

@@ -0,0 +1,11 @@
+// TODO/v1-release: Move all universal imports (when using Client Routing) to:
+//   import {
+//     redirect,
+//     render,
+//     resolveRoute,
+//     navigate,
+//     prefetch,
+//   } from 'reveal'
+// Use package.json#exports to make the imports isomorphic.
+// The client-side has no utility when using Server Routing.
+export { redirect, render } from "../../router/abort.js";

package/dist/core/targets/client/createPageContext.ts

@@ -0,0 +1,48 @@
+export { createPageContext };
+
+import { assert } from "../../gaurds/assertions/assert/index.js";
+import { loadPageRoutes } from "../../router/loadPageRoutes.js";
+
+import { getBaseServer } from "../../processing/getters/getBaseServer.js";
+import getGlobalObject from "../../processing/getters/getGlobalObject.js";
+import { getPageContextUrlComputed } from "../../processing/getters/getPageContextUrlComputed.js";
+import { getPageFilesAll } from "../../processing/getters/getPageFiles/index.js";
+import { isBaseServer } from "../../targets/url/parseUrl.js";
+import { objectAssign } from "../../utils/object/objectAssign.js";
+import { PromiseType } from "../../../types/interfaces/logic.js";
+
+const globalObject = getGlobalObject<{
+  pageFilesData?: PromiseType<ReturnType<typeof getPageFilesAll>>;
+}>("createPageContext.ts", {});
+
+async function createPageContext(urlOriginal: string) {
+  if (!globalObject.pageFilesData) {
+    globalObject.pageFilesData = await getPageFilesAll(true);
+  }
+  const { pageFilesAll, allPageIds, pageConfigs, pageConfigGlobal } =
+    globalObject.pageFilesData;
+  const { pageRoutes, onBeforeRouteHook } = await loadPageRoutes(
+    pageConfigs,
+    pageConfigGlobal,
+    allPageIds,
+  );
+  const baseServer = getBaseServer();
+  assert(isBaseServer(baseServer));
+  const pageContext = {
+    urlOriginal,
+    _objectCreatedByReveal: true,
+    _urlHandler: null,
+    _urlRewrite: null,
+    _baseServer: baseServer,
+    _pageFilesAll: pageFilesAll,
+    _pageConfigs: pageConfigs,
+    _pageConfigGlobal: pageConfigGlobal,
+    _allPageIds: allPageIds,
+    _pageRoutes: pageRoutes,
+    _onBeforeRouteHook: onBeforeRouteHook,
+    _isPageContextObject: true,
+  };
+  const pageContextUrlComputed = getPageContextUrlComputed(pageContext);
+  objectAssign(pageContext, pageContextUrlComputed);
+  return pageContext;
+}

package/dist/core/targets/client/entry.ts

@@ -0,0 +1,15 @@
+import { assertClientRouting } from "../../gaurds/assertions/assertRoutingType/base.js";
+import { onClientEntryClientRouting } from "../../gaurds/assertions/assertSingleInstance/index.js";
+
+assertClientRouting();
+
+import { initClientRouter } from "./initClientRouter.js";
+import "./pageFiles.js";
+import { removeFoucBuster } from "./removeFoucBuster.js";
+
+const isProd: boolean = import.meta.env.PROD;
+onClientEntryClientRouting(isProd);
+
+if (import.meta.env.DEV) removeFoucBuster();
+
+initClientRouter();

package/dist/core/targets/client/executeOnRenderClientHook.ts

@@ -0,0 +1,94 @@
+export { executeOnRenderClientHook };
+export type { PageContextBeforeRenderClient };
+
+import { getHook, type Hook } from "../../processing/getters/getHook.js";
+import { assert, executeHook } from "../server/utils.js";
+
+import { PageConfigRuntime } from "../../../types/interfaces/page.js";
+import { PageContextExports } from "../../processing/getters/getPageFiles/index.js";
+
+import {
+  type PageContextForUserConsumptionClientSide,
+  preparePageContextForUserConsumptionClientSide,
+} from "./preparePageContextForUserConsumptionClientSide.js";
+import { assertUsage } from "../../gaurds/assertions/assertUsage/index.js";
+import {PageFile} from "../../__internal/index.js";
+
+type PageContextBeforeRenderClient = {
+  _pageFilesLoaded: PageFile[];
+  urlOriginal?: string;
+  urlPathname?: string;
+  pageId: string;
+  _pageConfigs: PageConfigRuntime[];
+} & PageContextExports &
+  PageContextForUserConsumptionClientSide;
+
+async function executeOnRenderClientHook<
+  PC extends PageContextBeforeRenderClient,
+>(pageContext: PC, isClientRouting: boolean): Promise<void> {
+  const pageContextForUserConsumption =
+    preparePageContextForUserConsumptionClientSide(
+      pageContext,
+      isClientRouting,
+    );
+
+  let hook: null | Hook = null;
+  let hookName: "onRenderClient";
+
+  {
+    const renderHook = getHook(pageContext, "onRenderClient");
+    hook = renderHook;
+    hookName = "onRenderClient";
+  }
+  {
+    const renderHook = getHook(pageContext, "onRenderClient");
+    if (renderHook) {
+      hook = renderHook;
+      hookName = "onRenderClient";
+    }
+  }
+
+  if (!hook) {
+    const urlToShowToUser = getUrlToShowToUser(pageContext);
+    assert(urlToShowToUser);
+    if (pageContext._pageConfigs.length > 0) {
+      // V1 design
+      assertUsage(
+        false,
+        `No onRenderClient() hook defined for URL '${urlToShowToUser}', but it's needed.`,
+      );
+    }
+  }
+
+  assert(hook);
+  const renderHook = hook.hookFn;
+  assert(hookName);
+
+  // We don't use a try-catch wrapper because rendering errors are usually handled by the UI framework. (E.g. React's Error Boundaries.)
+  const hookResult = await executeHook(
+    () => renderHook(pageContextForUserConsumption),
+    hook,
+    pageContext,
+  );
+  assertUsage(
+    hookResult === undefined,
+    `The ${hookName}() hook defined by ${hook.hookFilePath} isn't allowed to return a value`,
+  );
+}
+
+function getUrlToShowToUser(pageContext: {
+  urlOriginal?: string;
+  urlPathname?: string;
+}): string {
+  let url: string | undefined;
+  // try/catch to avoid passToClient assertUsage() (although: this may not be needed anymore, since we're now accessing pageContext and not pageContextForUserConsumption)
+  try {
+    url =
+      // Client Routing
+      pageContext.urlPathname ??
+      // Server Routing
+      pageContext.urlOriginal;
+  } catch {}
+  url = url ?? window.location.href;
+  return url;
+}