@sylphx/flow 1.0.1 → 1.0.3

package/src/core/functional/async.ts

@@ -0,0 +1,313 @@
+/**
+ * Async/Promise utilities for functional programming
+ * Handle promises with Result types
+ *
+ * DESIGN RATIONALE:
+ * - Convert Promise rejections to Result types
+ * - Composable async operations
+ * - No unhandled promise rejections
+ * - Type-safe async error handling
+ */
+
+import type { AppError } from './error-types.js';
+import { toAppError } from './error-types.js';
+import type { Result } from './result.js';
+import { failure, isSuccess, success } from './result.js';
+
+/**
+ * Async Result type
+ */
+export type AsyncResult<T, E = AppError> = Promise<Result<T, E>>;
+
+/**
+ * Convert Promise to AsyncResult
+ * Catches rejections and converts to Result
+ */
+export const fromPromise = async <T>(
+  promise: Promise<T>,
+  onError?: (error: unknown) => AppError
+): AsyncResult<T> => {
+  try {
+    const value = await promise;
+    return success(value);
+  } catch (error) {
+    return failure(onError ? onError(error) : toAppError(error));
+  }
+};
+
+/**
+ * Map over async result
+ */
+export const mapAsync =
+  <T, U>(fn: (value: T) => U | Promise<U>) =>
+  async <E>(result: AsyncResult<T, E>): AsyncResult<U, E> => {
+    const resolved = await result;
+    if (isSuccess(resolved)) {
+      const mapped = await fn(resolved.value);
+      return success(mapped);
+    }
+    return resolved;
+  };
+
+/**
+ * FlatMap over async result
+ */
+export const flatMapAsync =
+  <T, U, E>(fn: (value: T) => AsyncResult<U, E>) =>
+  async (result: AsyncResult<T, E>): AsyncResult<U, E> => {
+    const resolved = await result;
+    if (isSuccess(resolved)) {
+      return fn(resolved.value);
+    }
+    return resolved;
+  };
+
+/**
+ * Run async operation with timeout
+ */
+export const withTimeout = <T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  onTimeout?: () => AppError
+): AsyncResult<T> => {
+  return fromPromise(
+    Promise.race([
+      promise,
+      new Promise<T>((_, reject) =>
+        setTimeout(() => reject(new Error('Operation timed out')), timeoutMs)
+      ),
+    ]),
+    onTimeout
+  );
+};
+
+/**
+ * Retry async operation
+ */
+export const retry = async <T>(
+  fn: () => Promise<T>,
+  options: {
+    maxAttempts: number;
+    delayMs?: number;
+    backoff?: number;
+    onRetry?: (attempt: number, error: AppError) => void;
+  }
+): AsyncResult<T> => {
+  const { maxAttempts, delayMs = 1000, backoff = 2, onRetry } = options;
+
+  let lastError: AppError | null = null;
+  let currentDelay = delayMs;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const result = await fromPromise(fn());
+
+    if (isSuccess(result)) {
+      return result;
+    }
+
+    lastError = result.error;
+
+    if (attempt < maxAttempts) {
+      if (onRetry) {
+        onRetry(attempt, lastError);
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, currentDelay));
+      currentDelay *= backoff;
+    }
+  }
+
+  return failure(lastError!);
+};
+
+/**
+ * Run promises in parallel and collect results
+ * Fails if any promise fails
+ */
+export const allAsync = async <T>(promises: AsyncResult<T, AppError>[]): AsyncResult<T[]> => {
+  const results = await Promise.all(promises);
+
+  const values: T[] = [];
+  for (const result of results) {
+    if (isSuccess(result)) {
+      values.push(result.value);
+    } else {
+      return result;
+    }
+  }
+
+  return success(values);
+};
+
+/**
+ * Run promises in parallel and collect all results
+ * Returns both successes and failures
+ */
+export const allSettledAsync = async <T>(
+  promises: AsyncResult<T, AppError>[]
+): Promise<Result<T, AppError>[]> => {
+  return Promise.all(promises);
+};
+
+/**
+ * Run promises sequentially
+ */
+export const sequenceAsync = async <T>(
+  promises: Array<() => AsyncResult<T, AppError>>
+): AsyncResult<T[]> => {
+  const values: T[] = [];
+
+  for (const promiseFn of promises) {
+    const result = await promiseFn();
+    if (isSuccess(result)) {
+      values.push(result.value);
+    } else {
+      return result;
+    }
+  }
+
+  return success(values);
+};
+
+/**
+ * Race promises - return first to complete
+ */
+export const raceAsync = async <T>(promises: AsyncResult<T, AppError>[]): AsyncResult<T> => {
+  return Promise.race(promises);
+};
+
+/**
+ * Delay execution
+ */
+export const delay = (ms: number): Promise<void> => {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+};
+
+/**
+ * Run with concurrency limit
+ */
+export const withConcurrency = async <T>(
+  tasks: Array<() => AsyncResult<T, AppError>>,
+  concurrency: number
+): AsyncResult<T[]> => {
+  const results: T[] = [];
+  const executing: Promise<void>[] = [];
+
+  for (const task of tasks) {
+    const promise = (async () => {
+      const result = await task();
+      if (isSuccess(result)) {
+        results.push(result.value);
+      } else {
+        throw result.error;
+      }
+    })();
+
+    executing.push(promise);
+
+    if (executing.length >= concurrency) {
+      await Promise.race(executing);
+      executing.splice(executing.indexOf(promise), 1);
+    }
+  }
+
+  try {
+    await Promise.all(executing);
+    return success(results);
+  } catch (error) {
+    return failure(toAppError(error));
+  }
+};
+
+/**
+ * Memoize async function
+ */
+export const memoizeAsync = <Args extends any[], T>(
+  fn: (...args: Args) => AsyncResult<T, AppError>,
+  keyFn?: (...args: Args) => string
+): ((...args: Args) => AsyncResult<T, AppError>) => {
+  const cache = new Map<string, AsyncResult<T, AppError>>();
+
+  return (...args: Args): AsyncResult<T, AppError> => {
+    const key = keyFn ? keyFn(...args) : JSON.stringify(args);
+
+    if (cache.has(key)) {
+      return cache.get(key)!;
+    }
+
+    const result = fn(...args);
+    cache.set(key, result);
+    return result;
+  };
+};
+
+/**
+ * Debounce async function
+ */
+export const debounceAsync = <Args extends any[], T>(
+  fn: (...args: Args) => AsyncResult<T, AppError>,
+  delayMs: number
+): ((...args: Args) => AsyncResult<T, AppError>) => {
+  let timeoutId: NodeJS.Timeout | null = null;
+  let latestArgs: Args | null = null;
+  let latestPromise: AsyncResult<T, AppError> | null = null;
+
+  return (...args: Args): AsyncResult<T, AppError> => {
+    latestArgs = args;
+
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+
+    if (!latestPromise) {
+      latestPromise = new Promise((resolve) => {
+        timeoutId = setTimeout(async () => {
+          if (latestArgs) {
+            const result = await fn(...latestArgs);
+            resolve(result);
+            latestPromise = null;
+            timeoutId = null;
+          }
+        }, delayMs);
+      }) as AsyncResult<T, AppError>;
+    }
+
+    return latestPromise;
+  };
+};
+
+/**
+ * Throttle async function
+ */
+export const throttleAsync = <Args extends any[], T>(
+  fn: (...args: Args) => AsyncResult<T, AppError>,
+  limitMs: number
+): ((...args: Args) => AsyncResult<T, AppError>) => {
+  let lastRun = 0;
+  let pending: AsyncResult<T, AppError> | null = null;
+
+  return (...args: Args): AsyncResult<T, AppError> => {
+    const now = Date.now();
+
+    if (now - lastRun >= limitMs) {
+      lastRun = now;
+      return fn(...args);
+    }
+
+    if (!pending) {
+      pending = new Promise((resolve) => {
+        setTimeout(
+          async () => {
+            lastRun = Date.now();
+            const result = await fn(...args);
+            pending = null;
+            resolve(result);
+          },
+          limitMs - (now - lastRun)
+        );
+      }) as AsyncResult<T, AppError>;
+    }
+
+    return pending;
+  };
+};

package/src/core/functional/either.ts

@@ -0,0 +1,109 @@
+/**
+ * Either type for representing values that can be one of two types
+ * Commonly used for success/error, but more general than Result
+ *
+ * DESIGN RATIONALE:
+ * - Generic sum type for two possibilities
+ * - Left traditionally represents error/failure
+ * - Right traditionally represents success/value
+ * - Result is a specialized Either<Error, Value>
+ */
+
+export type Either<L, R> = Left<L> | Right<R>;
+
+export interface Left<L> {
+  readonly _tag: 'Left';
+  readonly left: L;
+}
+
+export interface Right<R> {
+  readonly _tag: 'Right';
+  readonly right: R;
+}
+
+/**
+ * Constructors
+ */
+
+export const left = <L>(value: L): Left<L> => ({
+  _tag: 'Left',
+  left: value,
+});
+
+export const right = <R>(value: R): Right<R> => ({
+  _tag: 'Right',
+  right: value,
+});
+
+/**
+ * Type guards
+ */
+
+export const isLeft = <L, R>(either: Either<L, R>): either is Left<L> => either._tag === 'Left';
+
+export const isRight = <L, R>(either: Either<L, R>): either is Right<R> => either._tag === 'Right';
+
+/**
+ * Transformations
+ */
+
+export const map =
+  <L, R, R2>(fn: (value: R) => R2) =>
+  (either: Either<L, R>): Either<L, R2> => {
+    if (isRight(either)) {
+      return right(fn(either.right));
+    }
+    return either;
+  };
+
+export const mapLeft =
+  <L, L2, R>(fn: (value: L) => L2) =>
+  (either: Either<L, R>): Either<L2, R> => {
+    if (isLeft(either)) {
+      return left(fn(either.left));
+    }
+    return either;
+  };
+
+export const flatMap =
+  <L, R, R2>(fn: (value: R) => Either<L, R2>) =>
+  (either: Either<L, R>): Either<L, R2> => {
+    if (isRight(either)) {
+      return fn(either.right);
+    }
+    return either;
+  };
+
+/**
+ * Pattern matching
+ */
+export const match =
+  <L, R, T>(onLeft: (left: L) => T, onRight: (right: R) => T) =>
+  (either: Either<L, R>): T => {
+    if (isLeft(either)) {
+      return onLeft(either.left);
+    }
+    return onRight(either.right);
+  };
+
+/**
+ * Extract value or provide default
+ */
+export const getOrElse =
+  <R>(defaultValue: R) =>
+  <L>(either: Either<L, R>): R => {
+    if (isRight(either)) {
+      return either.right;
+    }
+    return defaultValue;
+  };
+
+/**
+ * Swap Left and Right
+ */
+export const swap = <L, R>(either: Either<L, R>): Either<R, L> => {
+  if (isLeft(either)) {
+    return right(either.left);
+  }
+  return left(either.right);
+};

package/src/core/functional/error-handler.ts

@@ -0,0 +1,135 @@
+/**
+ * Functional error handling utilities
+ * Replaces exception-based error handling with Result-based approach
+ *
+ * DESIGN RATIONALE:
+ * - Errors as values, not exceptions
+ * - Explicit error handling in function signatures
+ * - Composable error handling
+ * - Separation of error handling from business logic
+ */
+
+import type { AppError } from './error-types.js';
+import { formatError, toAppError } from './error-types.js';
+import type { Result } from './result.js';
+import { failure, success } from './result.js';
+
+/**
+ * Execute a function and convert exceptions to Result
+ */
+export const execute = <T>(fn: () => T): Result<T, AppError> => {
+  try {
+    return success(fn());
+  } catch (error) {
+    return failure(toAppError(error));
+  }
+};
+
+/**
+ * Execute an async function and convert exceptions to Result
+ */
+export const executeAsync = async <T>(fn: () => Promise<T>): Promise<Result<T, AppError>> => {
+  try {
+    const value = await fn();
+    return success(value);
+  } catch (error) {
+    return failure(toAppError(error));
+  }
+};
+
+/**
+ * Log error to console (side effect)
+ */
+export const logError = (error: AppError): void => {
+  console.error(formatError(error));
+};
+
+/**
+ * Log error and exit process (side effect)
+ * Only use at top-level command handlers
+ */
+export const exitWithError = (error: AppError, exitCode = 1): never => {
+  logError(error);
+  process.exit(exitCode);
+};
+
+/**
+ * Convert Result to exit code
+ * 0 for success, 1 for failure
+ * Use at top-level command handlers
+ */
+export const toExitCode = <T>(result: Result<T, AppError>): number => {
+  if (result._tag === 'Success') {
+    return 0;
+  }
+  logError(result.error);
+  return 1;
+};
+
+/**
+ * Retry logic with exponential backoff
+ * Retries a function that returns a Result
+ */
+export const retry = async <T>(
+  fn: () => Promise<Result<T, AppError>>,
+  options: {
+    maxRetries: number;
+    delayMs: number;
+    backoff?: number;
+    onRetry?: (error: AppError, attempt: number) => void;
+  }
+): Promise<Result<T, AppError>> => {
+  const { maxRetries, delayMs, backoff = 2, onRetry } = options;
+
+  let lastError: AppError | null = null;
+  let currentDelay = delayMs;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const result = await fn();
+
+    if (result._tag === 'Success') {
+      return result;
+    }
+
+    lastError = result.error;
+
+    if (attempt < maxRetries) {
+      if (onRetry) {
+        onRetry(lastError, attempt + 1);
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, currentDelay));
+      currentDelay *= backoff;
+    }
+  }
+
+  return failure(lastError!);
+};
+
+/**
+ * Create an async handler that wraps a function returning Result
+ * Useful for command handlers
+ */
+export const createAsyncHandler =
+  <T extends Record<string, any>>(handler: (options: T) => Promise<Result<void, AppError>>) =>
+  async (options: T): Promise<void> => {
+    const result = await handler(options);
+
+    if (result._tag === 'Failure') {
+      exitWithError(result.error);
+    }
+  };
+
+/**
+ * Create a sync handler that wraps a function returning Result
+ * Useful for command handlers
+ */
+export const createSyncHandler =
+  <T extends Record<string, any>>(handler: (options: T) => Result<void, AppError>) =>
+  (options: T): void => {
+    const result = handler(options);
+
+    if (result._tag === 'Failure') {
+      exitWithError(result.error);
+    }
+  };