@sylphx/flow 1.0.1 → 1.0.3

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

@@ -0,0 +1,311 @@
+/**
+ * Standard error types for the application
+ * Typed errors enable better error handling and recovery
+ *
+ * DESIGN RATIONALE:
+ * - Discriminated union for all error types
+ * - Each error type has specific context
+ * - Enables type-safe error handling
+ * - Clear error categories for recovery strategies
+ */
+
+/**
+ * Base error type with common fields
+ */
+export interface BaseError {
+  readonly kind: string;
+  readonly message: string;
+  readonly context?: Record<string, unknown>;
+  readonly cause?: Error;
+}
+
+/**
+ * Configuration error - invalid configuration or missing required config
+ */
+export interface ConfigError extends BaseError {
+  readonly kind: 'ConfigError';
+  readonly configKey?: string;
+  readonly configPath?: string;
+}
+
+/**
+ * File system error - file not found, permission denied, etc.
+ */
+export interface FileSystemError extends BaseError {
+  readonly kind: 'FileSystemError';
+  readonly path: string;
+  readonly operation: 'read' | 'write' | 'delete' | 'create' | 'stat';
+}
+
+/**
+ * Database error - query failure, connection error, etc.
+ */
+export interface DatabaseError extends BaseError {
+  readonly kind: 'DatabaseError';
+  readonly operation: string;
+  readonly table?: string;
+}
+
+/**
+ * Validation error - input validation failure
+ */
+export interface ValidationError extends BaseError {
+  readonly kind: 'ValidationError';
+  readonly field?: string;
+  readonly errors: string[];
+}
+
+/**
+ * Network error - HTTP error, timeout, connection refused, etc.
+ */
+export interface NetworkError extends BaseError {
+  readonly kind: 'NetworkError';
+  readonly url?: string;
+  readonly statusCode?: number;
+}
+
+/**
+ * CLI error - command line interface specific errors
+ */
+export interface CLIError extends BaseError {
+  readonly kind: 'CLIError';
+  readonly command?: string;
+  readonly exitCode?: number;
+}
+
+/**
+ * Not found error - resource not found
+ */
+export interface NotFoundError extends BaseError {
+  readonly kind: 'NotFoundError';
+  readonly resourceType: string;
+  readonly resourceId: string;
+}
+
+/**
+ * Permission error - insufficient permissions
+ */
+export interface PermissionError extends BaseError {
+  readonly kind: 'PermissionError';
+  readonly resource: string;
+  readonly requiredPermission: string;
+}
+
+/**
+ * Unknown error - catch-all for unexpected errors
+ */
+export interface UnknownError extends BaseError {
+  readonly kind: 'UnknownError';
+}
+
+/**
+ * Union of all error types
+ */
+export type AppError =
+  | ConfigError
+  | FileSystemError
+  | DatabaseError
+  | ValidationError
+  | NetworkError
+  | CLIError
+  | NotFoundError
+  | PermissionError
+  | UnknownError;
+
+/**
+ * Error constructors
+ */
+
+export const configError = (
+  message: string,
+  options?: {
+    configKey?: string;
+    configPath?: string;
+    context?: Record<string, unknown>;
+    cause?: Error;
+  }
+): ConfigError => ({
+  kind: 'ConfigError',
+  message,
+  configKey: options?.configKey,
+  configPath: options?.configPath,
+  context: options?.context,
+  cause: options?.cause,
+});
+
+export const fileSystemError = (
+  message: string,
+  path: string,
+  operation: 'read' | 'write' | 'delete' | 'create' | 'stat',
+  options?: { context?: Record<string, unknown>; cause?: Error }
+): FileSystemError => ({
+  kind: 'FileSystemError',
+  message,
+  path,
+  operation,
+  context: options?.context,
+  cause: options?.cause,
+});
+
+export const databaseError = (
+  message: string,
+  operation: string,
+  options?: { table?: string; context?: Record<string, unknown>; cause?: Error }
+): DatabaseError => ({
+  kind: 'DatabaseError',
+  message,
+  operation,
+  table: options?.table,
+  context: options?.context,
+  cause: options?.cause,
+});
+
+export const validationError = (
+  message: string,
+  errors: string[],
+  options?: { field?: string; context?: Record<string, unknown> }
+): ValidationError => ({
+  kind: 'ValidationError',
+  message,
+  field: options?.field,
+  errors,
+  context: options?.context,
+});
+
+export const networkError = (
+  message: string,
+  options?: { url?: string; statusCode?: number; context?: Record<string, unknown>; cause?: Error }
+): NetworkError => ({
+  kind: 'NetworkError',
+  message,
+  url: options?.url,
+  statusCode: options?.statusCode,
+  context: options?.context,
+  cause: options?.cause,
+});
+
+export const cliError = (
+  message: string,
+  options?: {
+    command?: string;
+    exitCode?: number;
+    context?: Record<string, unknown>;
+    cause?: Error;
+  }
+): CLIError => ({
+  kind: 'CLIError',
+  message,
+  command: options?.command,
+  exitCode: options?.exitCode,
+  context: options?.context,
+  cause: options?.cause,
+});
+
+export const notFoundError = (
+  message: string,
+  resourceType: string,
+  resourceId: string,
+  options?: { context?: Record<string, unknown>; cause?: Error }
+): NotFoundError => ({
+  kind: 'NotFoundError',
+  message,
+  resourceType,
+  resourceId,
+  context: options?.context,
+  cause: options?.cause,
+});
+
+export const permissionError = (
+  message: string,
+  resource: string,
+  requiredPermission: string,
+  options?: { context?: Record<string, unknown>; cause?: Error }
+): PermissionError => ({
+  kind: 'PermissionError',
+  message,
+  resource,
+  requiredPermission,
+  context: options?.context,
+  cause: options?.cause,
+});
+
+export const unknownError = (
+  message: string,
+  options?: { context?: Record<string, unknown>; cause?: Error }
+): UnknownError => ({
+  kind: 'UnknownError',
+  message,
+  context: options?.context,
+  cause: options?.cause,
+});
+
+/**
+ * Convert unknown error to AppError
+ */
+export const toAppError = (error: unknown): AppError => {
+  if (isAppError(error)) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return unknownError(error.message, { cause: error });
+  }
+
+  return unknownError(String(error));
+};
+
+/**
+ * Type guard for AppError
+ */
+export const isAppError = (error: unknown): error is AppError => {
+  return typeof error === 'object' && error !== null && 'kind' in error && 'message' in error;
+};
+
+/**
+ * Format error for display
+ */
+export const formatError = (error: AppError): string => {
+  let formatted = `[${error.kind}] ${error.message}`;
+
+  if (error.kind === 'ConfigError' && error.configKey) {
+    formatted += `\n  Config key: ${error.configKey}`;
+  }
+
+  if (error.kind === 'FileSystemError') {
+    formatted += `\n  Path: ${error.path}`;
+    formatted += `\n  Operation: ${error.operation}`;
+  }
+
+  if (error.kind === 'DatabaseError') {
+    formatted += `\n  Operation: ${error.operation}`;
+    if (error.table) {
+      formatted += `\n  Table: ${error.table}`;
+    }
+  }
+
+  if (error.kind === 'ValidationError') {
+    formatted += `\n  Errors:`;
+    for (const err of error.errors) {
+      formatted += `\n    - ${err}`;
+    }
+  }
+
+  if (error.kind === 'NetworkError') {
+    if (error.url) {
+      formatted += `\n  URL: ${error.url}`;
+    }
+    if (error.statusCode) {
+      formatted += `\n  Status: ${error.statusCode}`;
+    }
+  }
+
+  if (error.context) {
+    formatted += `\n  Context: ${JSON.stringify(error.context, null, 2)}`;
+  }
+
+  if (error.cause) {
+    formatted += `\n  Caused by: ${error.cause.message}`;
+  }
+
+  return formatted;
+};

package/src/core/functional/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Functional programming utilities
+ * Core abstractions for composable, type-safe error handling
+ *
+ * PRINCIPLES:
+ * - Pure functions (no side effects)
+ * - Explicit error handling (no exceptions in business logic)
+ * - Composable through map/flatMap
+ * - Type-safe (leverages TypeScript's type system)
+ */
+
+export * from './async.js';
+export * from './either.js';
+export * from './error-handler.js';
+export * from './error-types.js';
+export * from './option.js';
+export * from './pipe.js';
+export * from './result.js';
+export * from './validation.js';

package/src/core/functional/option.ts

@@ -0,0 +1,142 @@
+/**
+ * Option type for representing optional values
+ * Eliminates null/undefined and makes optionality explicit
+ *
+ * DESIGN RATIONALE:
+ * - Makes absence of value explicit at type level
+ * - Eliminates null pointer errors
+ * - Composable through map/flatMap
+ * - Forces handling of missing values
+ */
+
+export type Option<T> = Some<T> | None;
+
+export interface Some<T> {
+  readonly _tag: 'Some';
+  readonly value: T;
+}
+
+export interface None {
+  readonly _tag: 'None';
+}
+
+/**
+ * Constructors
+ */
+
+export const some = <T>(value: T): Some<T> => ({
+  _tag: 'Some',
+  value,
+});
+
+export const none: None = {
+  _tag: 'None',
+};
+
+/**
+ * Create Option from nullable value
+ */
+export const fromNullable = <T>(value: T | null | undefined): Option<T> => {
+  if (value === null || value === undefined) {
+    return none;
+  }
+  return some(value);
+};
+
+/**
+ * Type guards
+ */
+
+export const isSome = <T>(option: Option<T>): option is Some<T> => option._tag === 'Some';
+
+export const isNone = <T>(option: Option<T>): option is None => option._tag === 'None';
+
+/**
+ * Transformations
+ */
+
+export const map =
+  <T, U>(fn: (value: T) => U) =>
+  (option: Option<T>): Option<U> => {
+    if (isSome(option)) {
+      return some(fn(option.value));
+    }
+    return none;
+  };
+
+export const flatMap =
+  <T, U>(fn: (value: T) => Option<U>) =>
+  (option: Option<T>): Option<U> => {
+    if (isSome(option)) {
+      return fn(option.value);
+    }
+    return none;
+  };
+
+/**
+ * Extract value or provide default
+ */
+export const getOrElse =
+  <T>(defaultValue: T) =>
+  (option: Option<T>): T => {
+    if (isSome(option)) {
+      return option.value;
+    }
+    return defaultValue;
+  };
+
+/**
+ * Extract value or compute default
+ */
+export const getOrElseLazy =
+  <T>(fn: () => T) =>
+  (option: Option<T>): T => {
+    if (isSome(option)) {
+      return option.value;
+    }
+    return fn();
+  };
+
+/**
+ * Pattern matching
+ */
+export const match =
+  <T, U>(onSome: (value: T) => U, onNone: () => U) =>
+  (option: Option<T>): U => {
+    if (isSome(option)) {
+      return onSome(option.value);
+    }
+    return onNone();
+  };
+
+/**
+ * Filter based on predicate
+ */
+export const filter =
+  <T>(predicate: (value: T) => boolean) =>
+  (option: Option<T>): Option<T> => {
+    if (isSome(option) && predicate(option.value)) {
+      return option;
+    }
+    return none;
+  };
+
+/**
+ * Convert to nullable
+ */
+export const toNullable = <T>(option: Option<T>): T | null => {
+  if (isSome(option)) {
+    return option.value;
+  }
+  return null;
+};
+
+/**
+ * Convert to undefined
+ */
+export const toUndefined = <T>(option: Option<T>): T | undefined => {
+  if (isSome(option)) {
+    return option.value;
+  }
+  return undefined;
+};

package/src/core/functional/pipe.ts

@@ -0,0 +1,189 @@
+/**
+ * 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;
+  };
+};