@revealui/core 0.0.1-pre.0

package/dist/core/renderer/stream/onLoad.ts

@@ -0,0 +1,14 @@
+export { onLoad };
+
+import { installRequireShim } from "@brillout/require-shim";
+import { assertIsNotBrowser } from "../../gaurds/assertions/assertIsNotBrowser/index.js";
+import { assertNodeVersion } from "../../gaurds/assertions/assertNodeVersion/index.js";
+import { isErrorDebug } from "../../gaurds/validators/isErrorDebug.js";
+import { setAlwaysShowStackTrace } from "./utils.js";
+
+function onLoad() {
+  assertIsNotBrowser();
+  assertNodeVersion();
+  installRequireShim();
+  if (isErrorDebug()) setAlwaysShowStackTrace();
+}

package/dist/core/renderer/stream/react-streaming.ts

@@ -0,0 +1,69 @@
+// Zero-config support for https://www.npmjs.com/package/react-streaming
+
+export {
+  getStreamOfReactStreamingPackage,
+  isStreamFromReactStreamingPackage,
+  streamFromReactStreamingPackageToString,
+}
+export type {
+  StreamFromReactStreamingPackage,
+  StreamFromReactStreamingPackagePublic,
+}
+
+import type { renderToStream } from "react-streaming/server"
+
+import {
+  streamPipeNodeToString,
+  StreamReadableWeb,
+  streamReadableWebToString,
+  StreamWritableNode,
+} from "./index.js"
+import { assert, assertUsage, hasProp, isRevealApp } from "./utils.js"
+
+// We use this simplistic public type to avoid type mismatches (when the user installed another version than reveal's devDependency#react-streaming install).
+type StreamFromReactStreamingPackagePublic = { injectToStream: Function }
+type StreamFromReactStreamingPackage = Awaited<
+  ReturnType<typeof renderToStream>
+>
+
+function streamFromReactStreamingPackageToString(
+  stream: StreamFromReactStreamingPackage
+) {
+  if (stream.pipe) {
+    return streamPipeNodeToString(stream.pipe)
+  }
+  if (stream.readable) {
+    return streamReadableWebToString(stream.readable)
+  }
+  assert(false)
+}
+
+function isStreamFromReactStreamingPackage(
+  thing: unknown
+): thing is StreamFromReactStreamingPackage {
+  if (hasProp(thing, "injectToStream", "function")) {
+    assertUsage(
+      hasProp(thing, "hasStreamEnded", "function"),
+      isRevealApp()
+        ? //
+          "Update reveal to its latest version"
+        : "Update react-streaming to its latest version"
+    )
+    return true
+  }
+  return false
+}
+
+type Pipe = { __streamPipeNode: (writable: StreamWritableNode) => void }
+type Readable = StreamReadableWeb
+function getStreamOfReactStreamingPackage(
+  stream: StreamFromReactStreamingPackage
+): Pipe | Readable {
+  if (stream.pipe) {
+    return { __streamPipeNode: stream.pipe }
+  }
+  if (stream.readable) {
+    return stream.readable
+  }
+  assert(false)
+}

package/dist/core/renderer/stream/utils.ts

@@ -0,0 +1,66 @@
+import "../../gaurds/logger/trackLogs.js";
+
+// We assume all runtime entries will load this utils.ts file
+import { onLoad } from "./onLoad.js";
+onLoad();
+export * from "../../files/file-system/pathShim.js";
+export * from "../../files/file-system/removeFileExtention.js";
+export * from "../../files/virtual-files/index.js";
+export * from "../../gaurds/assertions/assert/index.js";
+export * from "../../gaurds/assertions/assertCast.js";
+export * from "../../gaurds/assertions/assertIsNotProductionRuntime/index.js";
+export * from "../../gaurds/assertions/assertNodeEnv/index.js";
+export * from "../../gaurds/assertions/assertUsage/index.js";
+export * from "../../gaurds/assertions/assertWarning/index.js";
+export * from "../../gaurds/assertions/checkType.js";
+export * from "../../gaurds/debugger/index.js";
+export * from "../../gaurds/logger/formatHintLog.js";
+export * from "../../gaurds/logger/warnIfErrorIsNotObject.js";
+export * from "../../gaurds/normalization/freezePartial.js";
+export * from "../../gaurds/normalization/normalizeHeaders.js";
+export * from "../../gaurds/validators/hasProp.js";
+export * from "../../gaurds/validators/isArray.js";
+export * from "../../gaurds/validators/isArrayOfStrings.js";
+export * from "../../gaurds/validators/isBrowser.js";
+export * from "../../gaurds/validators/isBug.js";
+export * from "../../gaurds/validators/isCallable.js";
+export * from "../../gaurds/validators/isHtml.js";
+export * from "../../gaurds/validators/isNotNullish.js";
+export * from "../../gaurds/validators/isNpmPackage.js";
+export * from "../../gaurds/validators/isObject.js";
+export * from "../../gaurds/validators/isObjectWithKeys.js";
+export * from "../../gaurds/validators/isPlainObject.js";
+export * from "../../gaurds/validators/isPromise.js";
+export * from "../../gaurds/validators/isPropertyGetter.js";
+export * from "../../gaurds/validators/isRevealApp.js";
+export * from "../../gaurds/validators/isSameErrorMessage.js";
+export * from "../../gaurds/validators/isScriptFile.js";
+export * from "../../globals/patterns/styleFileRE.js";
+export * from "../../globals/versions/PROJECT_VERSION.js";
+export * from "../../globals/versions/projectInfo.js";
+export * from "../../processing/getters/getFileExtension.js";
+export * from "../../processing/getters/getGlobalObject.js";
+export * from "../../processing/getters/getOutDirs.js";
+export * from "../../processing/getters/getPropAccessNotation.js";
+export * from "../../processing/getters/getTerminWidth.js";
+export * from "../../processing/iterators/objectKeys.js";
+export * from "../../targets/url/parseUrl.js";
+export * from "../../processing/setters/setAlwaysShowStackTrace.js";
+export * from "../../targets/url/parseUrlExtras.js";
+export * from "../../targets/url/urlToFile.js";
+export * from "../../utils/array/slice.js";
+export * from "../../utils/array/sorter.js";
+export * from "../../utils/array/stringifyStringArray.js";
+export * from "../../utils/array/unique.js";
+export * from "../../utils/async/genPromise.js";
+export * from "../../files/file-system/filesystemPath.js";
+export * from "../../utils/object/objectAssign.js";
+export * from "../../utils/object/objectEntries.js";
+export * from "../../utils/object/objectFromEntries.js";
+// export * from "../../utils/PromiseType.js";
+export * from "../../utils/string/capitalizeFirstLetter.js";
+export * from "../../utils/string/compareString.js";
+export * from "../../utils/string/escapeHtml.js";
+export * from "../../utils/string/joinEnglish.js";
+export * from "../../utils/string/stripAnsi.js";
+export * from "../../utils/string/truncateString.js";

package/dist/core/resilience/circuit-breaker.ts

@@ -0,0 +1,212 @@
+/**
+ * Circuit Breaker Pattern Implementation
+ * Prevents cascading failures by stopping requests to failing services
+ */
+
+export type CircuitState = "closed" | "open" | "half-open"
+
+export interface CircuitBreakerOptions {
+  failureThreshold: number // Number of failures before opening circuit
+  resetTimeout: number // Time in ms before attempting to close circuit
+  monitoringPeriod: number // Time window for tracking failures
+}
+
+export interface CircuitBreakerStats {
+  state: CircuitState
+  failures: number
+  successes: number
+  lastFailureTime?: number
+  lastSuccessTime?: number
+}
+
+class CircuitBreaker {
+  private state: CircuitState = "closed"
+  private failures: number = 0
+  private successes: number = 0
+  private lastFailureTime?: number
+  private lastSuccessTime?: number
+  private failureTimestamps: number[] = []
+
+  constructor(
+    private name: string,
+    private options: CircuitBreakerOptions = {
+      failureThreshold: 5,
+      resetTimeout: 60000, // 1 minute
+      monitoringPeriod: 60000, // 1 minute
+    }
+  ) {}
+
+  /**
+   * Execute a function with circuit breaker protection
+   */
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    // Check if circuit should transition from open to half-open
+    if (this.state === "open") {
+      if (this.shouldAttemptReset()) {
+        this.state = "half-open"
+      } else {
+        throw new Error(`Circuit breaker "${this.name}" is open`)
+      }
+    }
+
+    try {
+      const result = await fn()
+      this.onSuccess()
+      return result
+    } catch (error) {
+      this.onFailure()
+      throw error
+    }
+  }
+
+  /**
+   * Record a successful execution
+   */
+  private onSuccess(): void {
+    this.lastSuccessTime = Date.now()
+
+    if (this.state === "half-open") {
+      // Success in half-open state, close the circuit
+      this.state = "closed"
+      this.failures = 0
+      this.successes = 0
+    } else {
+      this.successes++
+    }
+
+    // Clean up old failure timestamps
+    this.cleanupFailureTimestamps()
+  }
+
+  /**
+   * Record a failed execution
+   */
+  private onFailure(): void {
+    this.lastFailureTime = Date.now()
+    this.failures++
+    this.failureTimestamps.push(Date.now())
+
+    // Clean up old failure timestamps
+    this.cleanupFailureTimestamps()
+
+    // Check if we should open the circuit
+    if (this.shouldOpenCircuit()) {
+      this.state = "open"
+    }
+  }
+
+  /**
+   * Check if circuit should be opened
+   */
+  private shouldOpenCircuit(): boolean {
+    // Count failures in the monitoring period
+    const recentFailures = this.failureTimestamps.filter(
+      (timestamp) => Date.now() - timestamp < this.options.monitoringPeriod
+    ).length
+
+    return recentFailures >= this.options.failureThreshold
+  }
+
+  /**
+   * Check if circuit should attempt reset
+   */
+  private shouldAttemptReset(): boolean {
+    if (!this.lastFailureTime) return false
+    return Date.now() - this.lastFailureTime >= this.options.resetTimeout
+  }
+
+  /**
+   * Clean up old failure timestamps outside monitoring period
+   */
+  private cleanupFailureTimestamps(): void {
+    const cutoff = Date.now() - this.options.monitoringPeriod
+    this.failureTimestamps = this.failureTimestamps.filter(
+      (timestamp) => timestamp > cutoff
+    )
+  }
+
+  /**
+   * Get current circuit breaker statistics
+   */
+  getStats(): CircuitBreakerStats {
+    return {
+      state: this.state,
+      failures: this.failures,
+      successes: this.successes,
+      lastFailureTime: this.lastFailureTime,
+      lastSuccessTime: this.lastSuccessTime,
+    }
+  }
+
+  /**
+   * Reset circuit breaker to closed state
+   */
+  reset(): void {
+    this.state = "closed"
+    this.failures = 0
+    this.successes = 0
+    this.failureTimestamps = []
+    this.lastFailureTime = undefined
+    this.lastSuccessTime = undefined
+  }
+}
+
+/**
+ * Circuit breaker registry
+ */
+class CircuitBreakerRegistry {
+  private breakers: Map<string, CircuitBreaker> = new Map()
+
+  /**
+   * Get or create a circuit breaker
+   */
+  get(name: string, options?: CircuitBreakerOptions): CircuitBreaker {
+    if (!this.breakers.has(name)) {
+      this.breakers.set(name, new CircuitBreaker(name, options))
+    }
+    return this.breakers.get(name)!
+  }
+
+  /**
+   * Get all circuit breakers
+   */
+  getAll(): Map<string, CircuitBreaker> {
+    return new Map(this.breakers)
+  }
+
+  /**
+   * Reset a circuit breaker
+   */
+  reset(name: string): void {
+    const breaker = this.breakers.get(name)
+    if (breaker) {
+      breaker.reset()
+    }
+  }
+
+  /**
+   * Reset all circuit breakers
+   */
+  resetAll(): void {
+    this.breakers.forEach((breaker) => breaker.reset())
+  }
+}
+
+// Export singleton instance
+export const circuitBreakers = new CircuitBreakerRegistry()
+
+/**
+ * Create a circuit breaker wrapper for async functions
+ */
+export function withCircuitBreaker<T extends (...args: any[]) => Promise<any>>(
+  name: string,
+  fn: T,
+  options?: CircuitBreakerOptions
+): T {
+  const breaker = circuitBreakers.get(name, options)
+
+  return (async (...args: Parameters<T>) => {
+    return breaker.execute(() => fn(...args))
+  }) as T
+}
+

package/dist/core/resilience/retry.ts

@@ -0,0 +1,172 @@
+/**
+ * Retry Logic with Exponential Backoff
+ * Provides configurable retry strategies for resilient API calls
+ */
+
+export interface RetryOptions {
+  maxAttempts?: number
+  initialDelay?: number
+  maxDelay?: number
+  backoffMultiplier?: number
+  jitter?: boolean
+  retryableErrors?: (error: unknown) => boolean
+}
+
+export class RetryError extends Error {
+  constructor(
+    message: string,
+    public readonly attempts: number,
+    public readonly lastError: unknown
+  ) {
+    super(message)
+    this.name = "RetryError"
+  }
+}
+
+/**
+ * Calculate delay with exponential backoff and optional jitter
+ */
+function calculateDelay(
+  attempt: number,
+  initialDelay: number,
+  maxDelay: number,
+  backoffMultiplier: number,
+  jitter: boolean
+): number {
+  const exponentialDelay = initialDelay * Math.pow(backoffMultiplier, attempt - 1)
+  const delay = Math.min(exponentialDelay, maxDelay)
+
+  if (jitter) {
+    // Add random jitter (0-20% of delay) to prevent thundering herd
+    const jitterAmount = delay * 0.2 * Math.random()
+    return delay + jitterAmount
+  }
+
+  return delay
+}
+
+/**
+ * Sleep for specified milliseconds
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Default function to determine if an error is retryable
+ */
+function isRetryableError(error: unknown): boolean {
+  if (error instanceof Error) {
+    // Network errors are retryable
+    if (
+      error.message.includes("ECONNREFUSED") ||
+      error.message.includes("ETIMEDOUT") ||
+      error.message.includes("ENOTFOUND") ||
+      error.message.includes("network")
+    ) {
+      return true
+    }
+
+    // 5xx server errors are retryable
+    if (error.message.includes("500") || error.message.includes("502") || error.message.includes("503")) {
+      return true
+    }
+  }
+
+  // Check if error has status code
+  if (typeof error === "object" && error !== null && "status" in error) {
+    const status = (error as { status: number }).status
+    return status >= 500 && status < 600
+  }
+
+  return false
+}
+
+/**
+ * Retry an async function with exponential backoff
+ */
+export async function retry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const {
+    maxAttempts = 3,
+    initialDelay = 1000,
+    maxDelay = 30000,
+    backoffMultiplier = 2,
+    jitter = true,
+    retryableErrors = isRetryableError,
+  } = options
+
+  let lastError: unknown
+  let attempts = 0
+
+  while (attempts < maxAttempts) {
+    attempts++
+
+    try {
+      return await fn()
+    } catch (error) {
+      lastError = error
+
+      // Check if error is retryable
+      if (!retryableErrors(error)) {
+        throw error
+      }
+
+      // Don't retry on last attempt
+      if (attempts >= maxAttempts) {
+        break
+      }
+
+      // Calculate delay and wait
+      const delay = calculateDelay(
+        attempts,
+        initialDelay,
+        maxDelay,
+        backoffMultiplier,
+        jitter
+      )
+
+      await sleep(delay)
+    }
+  }
+
+  throw new RetryError(
+    `Failed after ${attempts} attempts`,
+    attempts,
+    lastError
+  )
+}
+
+/**
+ * Retry with custom retry condition
+ */
+export async function retryWithCondition<T>(
+  fn: () => Promise<T>,
+  shouldRetry: (error: unknown, attempt: number) => boolean,
+  options: Omit<RetryOptions, "retryableErrors"> = {}
+): Promise<T> {
+  // Track attempt number using closure
+  let attempt = 0
+  return retry(fn, {
+    ...options,
+    retryableErrors: (error: unknown) => {
+      attempt++
+      return shouldRetry(error, attempt)
+    },
+  })
+}
+
+/**
+ * Create a retry wrapper function
+ */
+export function withRetry<T extends (...args: any[]) => Promise<any>>(
+  fn: T,
+  options?: RetryOptions
+): T {
+  return (async (...args: Parameters<T>) => {
+    return retry(() => fn(...args), options)
+  }) as T
+}
+