@sylphx/flow 3.19.0 → 3.20.0

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

@@ -1,135 +0,0 @@
-/**
- * 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 = { type: 'unknown', message: 'Unknown error', code: 'UNKNOWN' };
-  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);
-    }
-  };

package/src/core/functional/pipe.ts

@@ -1,189 +0,0 @@
-/**
- * Function composition utilities
- * Enable declarative data transformation pipelines
- *
- * DESIGN RATIONALE:
- * - Left-to-right composition (more readable than f(g(h(x))))
- * - Type-safe (TypeScript infers types through the pipeline)
- * - Point-free style support
- * - Declarative over imperative
- */
-
-/**
- * Compose functions left-to-right
- * pipe(value, fn1, fn2, fn3) === fn3(fn2(fn1(value)))
- */
-export function pipe<A>(value: A): A;
-export function pipe<A, B>(value: A, fn1: (a: A) => B): B;
-export function pipe<A, B, C>(value: A, fn1: (a: A) => B, fn2: (b: B) => C): C;
-export function pipe<A, B, C, D>(value: A, fn1: (a: A) => B, fn2: (b: B) => C, fn3: (c: C) => D): D;
-export function pipe<A, B, C, D, E>(
-  value: A,
-  fn1: (a: A) => B,
-  fn2: (b: B) => C,
-  fn3: (c: C) => D,
-  fn4: (d: D) => E
-): E;
-export function pipe<A, B, C, D, E, F>(
-  value: A,
-  fn1: (a: A) => B,
-  fn2: (b: B) => C,
-  fn3: (c: C) => D,
-  fn4: (d: D) => E,
-  fn5: (e: E) => F
-): F;
-export function pipe<A, B, C, D, E, F, G>(
-  value: A,
-  fn1: (a: A) => B,
-  fn2: (b: B) => C,
-  fn3: (c: C) => D,
-  fn4: (d: D) => E,
-  fn5: (e: E) => F,
-  fn6: (f: F) => G
-): G;
-export function pipe<A, B, C, D, E, F, G, H>(
-  value: A,
-  fn1: (a: A) => B,
-  fn2: (b: B) => C,
-  fn3: (c: C) => D,
-  fn4: (d: D) => E,
-  fn5: (e: E) => F,
-  fn6: (f: F) => G,
-  fn7: (g: G) => H
-): H;
-export function pipe<A, B, C, D, E, F, G, H, I>(
-  value: A,
-  fn1: (a: A) => B,
-  fn2: (b: B) => C,
-  fn3: (c: C) => D,
-  fn4: (d: D) => E,
-  fn5: (e: E) => F,
-  fn6: (f: F) => G,
-  fn7: (g: G) => H,
-  fn8: (h: H) => I
-): I;
-export function pipe<A, B, C, D, E, F, G, H, I, J>(
-  value: A,
-  fn1: (a: A) => B,
-  fn2: (b: B) => C,
-  fn3: (c: C) => D,
-  fn4: (d: D) => E,
-  fn5: (e: E) => F,
-  fn6: (f: F) => G,
-  fn7: (g: G) => H,
-  fn8: (h: H) => I,
-  fn9: (i: I) => J
-): J;
-export function pipe(value: any, ...fns: Array<(arg: any) => any>): any {
-  return fns.reduce((acc, fn) => fn(acc), value);
-}
-
-/**
- * Create a composed function from multiple functions
- * flow(fn1, fn2, fn3) creates a new function that applies fn1, then fn2, then fn3
- */
-export function flow<A, B>(fn1: (a: A) => B): (a: A) => B;
-export function flow<A, B, C>(fn1: (a: A) => B, fn2: (b: B) => C): (a: A) => C;
-export function flow<A, B, C, D>(fn1: (a: A) => B, fn2: (b: B) => C, fn3: (c: C) => D): (a: A) => D;
-export function flow<A, B, C, D, E>(
-  fn1: (a: A) => B,
-  fn2: (b: B) => C,
-  fn3: (c: C) => D,
-  fn4: (d: D) => E
-): (a: A) => E;
-export function flow<A, B, C, D, E, F>(
-  fn1: (a: A) => B,
-  fn2: (b: B) => C,
-  fn3: (c: C) => D,
-  fn4: (d: D) => E,
-  fn5: (e: E) => F
-): (a: A) => F;
-export function flow<A, B, C, D, E, F, G>(
-  fn1: (a: A) => B,
-  fn2: (b: B) => C,
-  fn3: (c: C) => D,
-  fn4: (d: D) => E,
-  fn5: (e: E) => F,
-  fn6: (f: F) => G
-): (a: A) => G;
-export function flow<A, B, C, D, E, F, G, H>(
-  fn1: (a: A) => B,
-  fn2: (b: B) => C,
-  fn3: (c: C) => D,
-  fn4: (d: D) => E,
-  fn5: (e: E) => F,
-  fn6: (f: F) => G,
-  fn7: (g: G) => H
-): (a: A) => H;
-export function flow<A, B, C, D, E, F, G, H, I>(
-  fn1: (a: A) => B,
-  fn2: (b: B) => C,
-  fn3: (c: C) => D,
-  fn4: (d: D) => E,
-  fn5: (e: E) => F,
-  fn6: (f: F) => G,
-  fn7: (g: G) => H,
-  fn8: (h: H) => I
-): (a: A) => I;
-export function flow<A, B, C, D, E, F, G, H, I, J>(
-  fn1: (a: A) => B,
-  fn2: (b: B) => C,
-  fn3: (c: C) => D,
-  fn4: (d: D) => E,
-  fn5: (e: E) => F,
-  fn6: (f: F) => G,
-  fn7: (g: G) => H,
-  fn8: (h: H) => I,
-  fn9: (i: I) => J
-): (a: A) => J;
-export function flow(...fns: Array<(arg: any) => any>): (arg: any) => any {
-  return (value: any) => pipe(value, ...fns);
-}
-
-/**
- * Identity function - returns input unchanged
- * Useful as a no-op transformation or default
- */
-export const identity = <T>(value: T): T => value;
-
-/**
- * Constant function - returns a function that always returns the same value
- * Useful for providing defaults
- */
-export const constant =
-  <T>(value: T) =>
-  (): T =>
-    value;
-
-/**
- * Tap - run a side effect and return the original value
- * Useful for debugging or logging in a pipeline
- */
-export const tap =
-  <T>(fn: (value: T) => void) =>
-  (value: T): T => {
-    fn(value);
-    return value;
-  };
-
-/**
- * Memoize - cache function results
- * Only for pure functions with string/number arguments
- */
-export const memoize = <Args extends Array<string | number>, R>(
-  fn: (...args: Args) => R
-): ((...args: Args) => R) => {
-  const cache = new Map<string, R>();
-
-  return (...args: Args): R => {
-    const key = JSON.stringify(args);
-
-    if (cache.has(key)) {
-      return cache.get(key)!;
-    }
-
-    const result = fn(...args);
-    cache.set(key, result);
-    return result;
-  };
-};

package/src/core/functional/validation.ts

@@ -1,138 +0,0 @@
-/**
- * Validation utilities for accumulating errors
- * Unlike Result which short-circuits on first error,
- * Validation accumulates all errors
- *
- * DESIGN RATIONALE:
- * - Form validation needs all errors, not just first
- * - Applicative functor for combining validations
- * - Errors accumulated in array
- * - Success only if all validations pass
- */
-
-import type { Result } from './result.js';
-import { failure, isSuccess, success } from './result.js';
-
-/**
- * Validation result with accumulated errors
- */
-export type Validation<T, E = string> = Result<T, E[]>;
-
-/**
- * Create a successful validation
- */
-export const valid = <T, E = string>(value: T): Validation<T, E> => success(value);
-
-/**
- * Create a failed validation with one or more errors
- */
-export const invalid = <T, E = string>(...errors: E[]): Validation<T, E> => failure(errors);
-
-/**
- * Combine multiple validations
- * Collects all errors if any validation fails
- */
-export const combine = <T, E = string>(validations: Validation<T, E>[]): Validation<T[], E> => {
-  const values: T[] = [];
-  const errors: E[] = [];
-
-  for (const validation of validations) {
-    if (isSuccess(validation)) {
-      values.push(validation.value);
-    } else {
-      errors.push(...validation.error);
-    }
-  }
-
-  if (errors.length > 0) {
-    return invalid(...errors);
-  }
-
-  return valid(values);
-};
-
-/**
- * Validate a value against multiple validators
- * Returns first error or success
- */
-export const validateAll =
-  <T, E = string>(...validators: Array<(value: T) => Validation<T, E>>) =>
-  (value: T): Validation<T, E> => {
-    const errors: E[] = [];
-
-    for (const validator of validators) {
-      const result = validator(value);
-      if (!isSuccess(result)) {
-        errors.push(...result.error);
-      }
-    }
-
-    if (errors.length > 0) {
-      return invalid(...errors);
-    }
-
-    return valid(value);
-  };
-
-/**
- * Common validators
- */
-
-export const nonEmpty =
-  (message: string) =>
-  (value: string): Validation<string, string> => {
-    if (value.trim().length === 0) {
-      return invalid(message);
-    }
-    return valid(value);
-  };
-
-export const minLength =
-  (min: number, message: string) =>
-  (value: string): Validation<string, string> => {
-    if (value.length < min) {
-      return invalid(message);
-    }
-    return valid(value);
-  };
-
-export const maxLength =
-  (max: number, message: string) =>
-  (value: string): Validation<string, string> => {
-    if (value.length > max) {
-      return invalid(message);
-    }
-    return valid(value);
-  };
-
-export const matches =
-  (pattern: RegExp, message: string) =>
-  (value: string): Validation<string, string> => {
-    if (!pattern.test(value)) {
-      return invalid(message);
-    }
-    return valid(value);
-  };
-
-export const isEmail = (message: string) => matches(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, message);
-
-export const isUrl = (message: string) => matches(/^https?:\/\/.+/, message);
-
-export const isNumber =
-  (message: string) =>
-  (value: string): Validation<number, string> => {
-    const num = Number(value);
-    if (Number.isNaN(num)) {
-      return invalid(message);
-    }
-    return valid(num);
-  };
-
-export const range =
-  (min: number, max: number, message: string) =>
-  (value: number): Validation<number, string> => {
-    if (value < min || value > max) {
-      return invalid(message);
-    }
-    return valid(value);
-  };