@sylphx/flow 1.7.0 → 1.8.1

package/src/services/memory.service.ts

@@ -1,476 +0,0 @@
-/**
- * Memory Service Layer
- *
- * Business logic layer for memory operations
- * Handles memory management with validation, caching, and business rules
- * Uses functional Result type for error handling
- */
-
-import { type Result, tryCatchAsync } from '../core/functional/result.js';
-import type { ILogger } from '../core/interfaces.js';
-import {
-  MemoryError,
-  type MemoryErrorType,
-  MemoryNotFoundError,
-  MemorySizeError,
-  MemoryValidationError,
-} from '../errors/memory-errors.js';
-import type {
-  CreateMemoryData,
-  MemoryEntry,
-  MemoryRepository,
-  MemorySearchParams,
-} from '../repositories/memory.repository.js';
-import type { MemoryStatsResult, MemoryValue } from '../types/memory-types.js';
-import {
-  type CacheState,
-  cacheDelete,
-  cacheDeleteWhere,
-  cacheEnforceLimit,
-  cacheGet,
-  cacheSet,
-  createCache,
-} from '../utils/immutable-cache.js';
-
-export interface MemoryServiceConfig {
-  defaultNamespace?: string;
-  maxEntrySize?: number;
-  enableCaching?: boolean;
-  cacheMaxSize?: number;
-  retentionPolicy?: {
-    enabled: boolean;
-    maxAge: number; // milliseconds
-    cleanupInterval?: number; // milliseconds
-  };
-}
-
-/**
- * Dependencies for MemoryService
- */
-export interface MemoryServiceDeps {
-  readonly repository: MemoryRepository;
-  readonly logger: ILogger;
-}
-
-/**
- * Internal state for MemoryService
- */
-interface MemoryServiceState {
-  readonly cache: CacheState<string, MemoryEntry>;
-  readonly cleanupTimer?: NodeJS.Timeout;
-}
-
-/**
- * MemoryService Interface
- * Business logic layer for memory operations
- */
-export interface MemoryService {
-  readonly get: (key: string, namespace?: string) => Promise<Result<MemoryValue, MemoryErrorType>>;
-  readonly set: (
-    key: string,
-    value: string,
-    namespace?: string
-  ) => Promise<Result<MemoryEntry, MemoryErrorType>>;
-  readonly delete: (key: string, namespace?: string) => Promise<Result<boolean, MemoryError>>;
-  readonly list: (namespace?: string) => Promise<Result<string[], MemoryError>>;
-  readonly search: (params: MemorySearchParams) => Promise<Result<MemoryEntry[], MemoryError>>;
-  readonly clear: (namespace?: string) => Promise<Result<number, MemoryError>>;
-  readonly getStats: () => Promise<Result<MemoryStatsResult, MemoryError>>;
-  readonly bulkSet: (
-    entries: Array<{ key: string; value: string; namespace?: string }>,
-    namespace?: string
-  ) => Promise<Result<MemoryEntry[], MemoryError>>;
-  readonly dispose: () => Promise<void>;
-}
-
-/**
- * Create Memory Service (Factory Function)
- * Handles memory management with validation, caching, and business rules
- */
-export const createMemoryService = (
-  deps: MemoryServiceDeps,
-  config: MemoryServiceConfig = {}
-): MemoryService => {
-  // Service configuration in closure
-  const serviceConfig: MemoryServiceConfig = {
-    defaultNamespace: 'default',
-    enableCaching: true,
-    cacheMaxSize: 1000,
-    ...config,
-  };
-
-  // Mutable state in closure (will be updated immutably)
-  let state: MemoryServiceState = {
-    cache: createCache(),
-    cleanupTimer: undefined,
-  };
-
-  // Helper: Update state immutably
-  const updateState = (updates: Partial<MemoryServiceState>): void => {
-    state = { ...state, ...updates };
-  };
-
-  /**
-   * Get a memory value
-   */
-  const get = async (
-    key: string,
-    namespace: string = serviceConfig.defaultNamespace || 'default'
-  ): Promise<Result<MemoryValue, MemoryErrorType>> => {
-    return await tryCatchAsync(
-      async () => {
-        // Check cache first if enabled
-        if (serviceConfig.enableCaching) {
-          const cacheKey = `${namespace}:${key}`;
-          // FUNCTIONAL: Use immutable cache get
-          const cached = cacheGet(state.cache, cacheKey);
-          if (cached) {
-            return {
-              value: cached.value,
-              metadata: {
-                namespace,
-                timestamp: cached.timestamp,
-                size: cached.value.length,
-              },
-            };
-          }
-        }
-
-        // Fetch from repository
-        const entry = await deps.repository.getByKey(key, namespace);
-
-        if (!entry) {
-          throw new MemoryNotFoundError(key, namespace);
-        }
-
-        // Cache the result if enabled
-        if (serviceConfig.enableCaching) {
-          updateCache(entry);
-        }
-
-        return {
-          value: entry.value,
-          metadata: {
-            namespace,
-            timestamp: entry.timestamp,
-            size: entry.value.length,
-          },
-        };
-      },
-      (error) => {
-        if (error instanceof MemoryNotFoundError) {
-          return error;
-        }
-        deps.logger.error(`Failed to get memory entry: ${key}`, error);
-        return new MemoryError(`Failed to get memory entry: ${key}`, error);
-      }
-    );
-  };
-
-  /**
-   * Set a memory value
-   */
-  const set = async (
-    key: string,
-    value: string,
-    namespace: string = serviceConfig.defaultNamespace || 'default'
-  ): Promise<Result<MemoryEntry, MemoryErrorType>> => {
-    return await tryCatchAsync(
-      async () => {
-        // Validate inputs
-        const validationError = validateMemoryEntry(key, value);
-        if (validationError) {
-          throw validationError;
-        }
-
-        const timestamp = Date.now();
-        const data: CreateMemoryData = {
-          key,
-          namespace,
-          value,
-          timestamp,
-        };
-
-        // Store in repository
-        const entry = await deps.repository.setMemory(data);
-
-        // Update cache if enabled
-        if (serviceConfig.enableCaching) {
-          updateCache(entry);
-          enforceCacheLimit();
-        }
-
-        deps.logger.debug(`Memory entry set: ${key} in namespace: ${namespace}`);
-
-        return entry;
-      },
-      (error) => {
-        if (error instanceof MemoryValidationError || error instanceof MemorySizeError) {
-          return error;
-        }
-        deps.logger.error(`Failed to set memory entry: ${key}`, error);
-        return new MemoryError(`Failed to set memory entry: ${key}`, error);
-      }
-    );
-  };
-
-  /**
-   * Delete a memory entry
-   */
-  const deleteEntry = async (
-    key: string,
-    namespace: string = serviceConfig.defaultNamespace || 'default'
-  ): Promise<Result<boolean, MemoryError>> => {
-    return await tryCatchAsync(
-      async () => {
-        const deleted = await deps.repository.deleteMemory(key, namespace);
-
-        // Remove from cache if present
-        if (serviceConfig.enableCaching) {
-          const cacheKey = `${namespace}:${key}`;
-          // FUNCTIONAL: Use immutable cache delete, returns new state
-          updateState({ cache: cacheDelete(state.cache, cacheKey) });
-        }
-
-        deps.logger.debug(`Memory entry deleted: ${key} in namespace: ${namespace}`);
-
-        return deleted;
-      },
-      (error) => {
-        deps.logger.error(`Failed to delete memory entry: ${key}`, error);
-        return new MemoryError(`Failed to delete memory entry: ${key}`, error);
-      }
-    );
-  };
-
-  /**
-   * List all keys in a namespace
-   */
-  const list = async (
-    namespace: string = serviceConfig.defaultNamespace || 'default'
-  ): Promise<Result<string[], MemoryError>> => {
-    return await tryCatchAsync(
-      async () => {
-        const keys = await deps.repository.listKeys(namespace);
-        return keys;
-      },
-      (error) => {
-        deps.logger.error(`Failed to list keys in namespace: ${namespace}`, error);
-        return new MemoryError(`Failed to list keys in namespace: ${namespace}`, error);
-      }
-    );
-  };
-
-  /**
-   * Search memory entries
-   */
-  const search = async (
-    params: MemorySearchParams
-  ): Promise<Result<MemoryEntry[], MemoryError>> => {
-    return await tryCatchAsync(
-      async () => {
-        const entries = await deps.repository.searchMemory(params);
-        return entries;
-      },
-      (error) => {
-        deps.logger.error('Failed to search memory entries', error);
-        return new MemoryError('Failed to search memory entries', error);
-      }
-    );
-  };
-
-  /**
-   * Clear all entries in a namespace
-   */
-  const clear = async (
-    namespace: string = serviceConfig.defaultNamespace || 'default'
-  ): Promise<Result<number, MemoryError>> => {
-    return await tryCatchAsync(
-      async () => {
-        const deletedCount = await deps.repository.clearNamespace(namespace);
-
-        // Clear cache entries for this namespace
-        if (serviceConfig.enableCaching) {
-          // FUNCTIONAL: Use immutable cache deleteWhere, returns new state
-          updateState({
-            cache: cacheDeleteWhere(state.cache, (key) => key.startsWith(`${namespace}:`)),
-          });
-        }
-
-        deps.logger.info(`Cleared ${deletedCount} entries from namespace: ${namespace}`);
-
-        return deletedCount;
-      },
-      (error) => {
-        deps.logger.error(`Failed to clear namespace: ${namespace}`, error);
-        return new MemoryError(`Failed to clear namespace: ${namespace}`, error);
-      }
-    );
-  };
-
-  /**
-   * Get memory statistics
-   */
-  const getStats = async (): Promise<Result<MemoryStatsResult, MemoryError>> => {
-    return await tryCatchAsync(
-      async () => {
-        const stats = await deps.repository.getStats();
-
-        return {
-          totalEntries: stats.totalEntries,
-          totalSize: stats.totalSize,
-          namespaces: stats.namespaces,
-          oldestEntry: stats.oldestEntry,
-          newestEntry: stats.newestEntry,
-        };
-      },
-      (error) => {
-        deps.logger.error('Failed to get memory statistics', error);
-        return new MemoryError('Failed to get memory statistics', error);
-      }
-    );
-  };
-
-  /**
-   * Perform bulk operations
-   */
-  const bulkSet = async (
-    entries: Array<{ key: string; value: string; namespace?: string }>,
-    namespace: string = serviceConfig.defaultNamespace || 'default'
-  ): Promise<Result<MemoryEntry[], MemoryError>> => {
-    return await tryCatchAsync(
-      async () => {
-        const results: MemoryEntry[] = [];
-        const errors: string[] = [];
-
-        for (const entry of entries) {
-          const result = await set(entry.key, entry.value, entry.namespace || namespace);
-          if (result._tag === 'Success') {
-            results.push(result.value);
-          } else {
-            errors.push(`${entry.key}: ${result.error.message}`);
-          }
-        }
-
-        if (errors.length > 0) {
-          deps.logger.warn(`Bulk set completed with ${errors.length} errors`, { errors });
-          throw new MemoryError(`Bulk set completed with errors: ${errors.join('; ')}`);
-        }
-
-        return results;
-      },
-      (error) => {
-        if (error instanceof MemoryError) {
-          return error;
-        }
-        deps.logger.error('Failed to perform bulk set', error);
-        return new MemoryError('Failed to perform bulk set', error);
-      }
-    );
-  };
-
-  /**
-   * Validate memory entry data
-   */
-  const validateMemoryEntry = (
-    key: string,
-    value: string
-  ): MemoryValidationError | MemorySizeError | null => {
-    if (!key || key.trim().length === 0) {
-      return new MemoryValidationError('Key cannot be empty', 'key', key);
-    }
-
-    if (key.length > 255) {
-      return new MemoryValidationError('Key cannot exceed 255 characters', 'key', key);
-    }
-
-    if (serviceConfig.maxEntrySize && value.length > serviceConfig.maxEntrySize) {
-      return new MemorySizeError(value.length, serviceConfig.maxEntrySize);
-    }
-
-    // Validate key format (no special characters that could cause issues)
-    if (!/^[a-zA-Z0-9._-]+$/.test(key)) {
-      return new MemoryValidationError(
-        'Key can only contain alphanumeric characters, dots, hyphens, and underscores',
-        'key',
-        key
-      );
-    }
-
-    return null;
-  };
-
-  /**
-   * Update cache with new entry
-   * FUNCTIONAL: Returns new cache state instead of mutating
-   */
-  const updateCache = (entry: MemoryEntry): void => {
-    const cacheKey = `${entry.namespace}:${entry.key}`;
-    // FUNCTIONAL: Use immutable cache set, returns new state
-    updateState({ cache: cacheSet(state.cache, cacheKey, entry) });
-  };
-
-  /**
-   * Enforce cache size limit
-   * FUNCTIONAL: Uses immutable cache operations
-   */
-  const enforceCacheLimit = (): void => {
-    if (serviceConfig.cacheMaxSize && state.cache.size > serviceConfig.cacheMaxSize) {
-      // FUNCTIONAL: Use immutable cache enforceLimit, returns new state
-      const entriesToRemove = state.cache.size - serviceConfig.cacheMaxSize;
-      updateState({ cache: cacheEnforceLimit(state.cache, serviceConfig.cacheMaxSize) });
-      deps.logger.debug(`Cache eviction: removed ${entriesToRemove} entries`);
-    }
-  };
-
-  /**
-   * Setup cleanup timer for retention policy
-   */
-  const setupCleanupTimer = (): void => {
-    if (serviceConfig.retentionPolicy?.enabled && serviceConfig.retentionPolicy.cleanupInterval) {
-      const timer = setInterval(async () => {
-        try {
-          const deletedCount = await deps.repository.cleanupOldEntries(
-            serviceConfig.retentionPolicy?.maxAge
-          );
-          if (deletedCount > 0) {
-            deps.logger.info(`Automatic cleanup: removed ${deletedCount} old entries`);
-          }
-        } catch (error) {
-          deps.logger.error('Automatic cleanup failed', error);
-        }
-      }, serviceConfig.retentionPolicy.cleanupInterval);
-      updateState({ cleanupTimer: timer });
-    }
-  };
-
-  /**
-   * Cleanup resources
-   */
-  const dispose = async (): Promise<void> => {
-    if (state.cleanupTimer) {
-      clearInterval(state.cleanupTimer);
-      updateState({ cleanupTimer: undefined });
-    }
-
-    // FUNCTIONAL: Replace cache with new empty cache instead of clearing
-    updateState({ cache: createCache() });
-    deps.logger.info('Memory service disposed');
-  };
-
-  // Initialize cleanup timer
-  setupCleanupTimer();
-
-  // Return service interface
-  return {
-    get,
-    set,
-    delete: deleteEntry,
-    list,
-    search,
-    clear,
-    getStats,
-    bulkSet,
-    dispose,
-  };
-};

package/src/types/api/batch.ts

@@ -1,108 +0,0 @@
-import { z } from 'zod';
-import type { ApiError } from './errors.js';
-
-// ============================================================================
-// BATCH API INTERFACES
-// ============================================================================
-
-/**
- * Batch API result for processing multiple operations
- */
-export interface BatchApiResult<T = unknown> {
-  /** Batch operation ID */
-  batchId: string;
-  /** Total number of operations */
-  total: number;
-  /** Number of successful operations */
-  successful: number;
-  /** Number of failed operations */
-  failed: number;
-  /** Results for individual operations */
-  results: BatchOperationResult<T>[];
-  /** Batch operation metadata */
-  metadata?: {
-    /** Batch start timestamp */
-    startedAt: string;
-    /** Batch completion timestamp */
-    completedAt?: string;
-    /** Total processing time in milliseconds */
-    duration?: number;
-    /** Processing batch size */
-    batchSize?: number;
-    /** Number of concurrent operations */
-    concurrency?: number;
-  };
-}
-
-/**
- * Individual batch operation result
- */
-export interface BatchOperationResult<T = unknown> {
-  /** Operation index in the batch */
-  index: number;
-  /** Operation ID */
-  id: string;
-  /** Operation success status */
-  success: boolean;
-  /** Operation result data */
-  data?: T;
-  /** Operation error (if failed) */
-  error?: ApiError;
-  /** Operation processing time in milliseconds */
-  processingTime?: number;
-  /** Operation retry attempts */
-  retryCount?: number;
-}
-
-// ============================================================================
-// ZOD SCHEMAS
-// ============================================================================
-
-export const BatchOperationResultSchema = z.object({
-  index: z.number().min(0),
-  id: z.string(),
-  success: z.boolean(),
-  data: z.unknown().optional(),
-  error: z
-    .object({
-      code: z.string(),
-      message: z.string(),
-      statusCode: z.number().optional(),
-      type: z.enum([
-        'validation',
-        'authentication',
-        'authorization',
-        'not_found',
-        'conflict',
-        'rate_limit',
-        'server_error',
-        'network',
-        'timeout',
-      ]),
-      description: z.string().optional(),
-      fieldErrors: z.record(z.array(z.string())).optional(),
-      stack: z.string().optional(),
-      context: z.record(z.unknown()).optional(),
-      suggestions: z.array(z.string()).optional(),
-    })
-    .optional(),
-  processingTime: z.number().min(0).optional(),
-  retryCount: z.number().min(0).optional(),
-});
-
-export const BatchApiResultSchema = z.object({
-  batchId: z.string(),
-  total: z.number().min(0),
-  successful: z.number().min(0),
-  failed: z.number().min(0),
-  results: z.array(BatchOperationResultSchema),
-  metadata: z
-    .object({
-      startedAt: z.string(),
-      completedAt: z.string().optional(),
-      duration: z.number().min(0).optional(),
-      batchSize: z.number().positive().optional(),
-      concurrency: z.number().positive().optional(),
-    })
-    .optional(),
-});

package/src/types/api/errors.ts

@@ -1,118 +0,0 @@
-import { z } from 'zod';
-
-// ============================================================================
-// API ERROR INTERFACES
-// ============================================================================
-
-/**
- * API error information
- */
-export interface ApiError {
-  /** Error code */
-  code: string;
-  /** Error message */
-  message: string;
-  /** HTTP status code */
-  statusCode?: number;
-  /** Error type for categorization */
-  type:
-    | 'validation'
-    | 'authentication'
-    | 'authorization'
-    | 'not_found'
-    | 'conflict'
-    | 'rate_limit'
-    | 'server_error'
-    | 'network'
-    | 'timeout';
-  /** Detailed error description */
-  description?: string;
-  /** Field-specific errors (for validation errors) */
-  fieldErrors?: Record<string, string[]>;
-  /** Stack trace (development only) */
-  stack?: string;
-  /** Error context information */
-  context?: Record<string, unknown>;
-  /** Suggestions for resolution */
-  suggestions?: string[];
-}
-
-/**
- * Enhanced error with additional context
- */
-export interface EnhancedError extends Error {
-  /** Error code */
-  code: string;
-  /** HTTP status code */
-  statusCode?: number;
-  /** Error type */
-  type: ApiError['type'];
-  /** Error context */
-  context?: ErrorContext;
-  /** Suggestions for resolution */
-  suggestions?: string[];
-  /** Original error that caused this error */
-  originalError?: Error;
-  /** Timestamp when error occurred */
-  timestamp: string;
-  /** Request ID for tracing */
-  requestId?: string;
-}
-
-/**
- * Error context information
- */
-export interface ErrorContext {
-  /** User ID if available */
-  userId?: string;
-  /** Session ID if available */
-  sessionId?: string;
-  /** IP address if available */
-  ipAddress?: string;
-  /** User agent if available */
-  userAgent?: string;
-  /** Request path */
-  path?: string;
-  /** HTTP method */
-  method?: string;
-  /** Additional context data */
-  data?: Record<string, unknown>;
-}
-
-// ============================================================================
-// ZOD SCHEMAS
-// ============================================================================
-
-export const ErrorContextSchema = z.object({
-  userId: z.string().optional(),
-  sessionId: z.string().optional(),
-  ipAddress: z.string().optional(),
-  userAgent: z.string().optional(),
-  path: z.string().optional(),
-  method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']).optional(),
-  data: z.record(z.unknown()).optional(),
-});
-
-export const EnhancedErrorSchema = z.object({
-  name: z.string(),
-  message: z.string(),
-  code: z.string(),
-  statusCode: z.number().optional(),
-  type: z.enum([
-    'validation',
-    'authentication',
-    'authorization',
-    'not_found',
-    'conflict',
-    'rate_limit',
-    'server_error',
-    'network',
-    'timeout',
-  ]),
-  context: ErrorContextSchema.optional(),
-  suggestions: z.array(z.string()).optional(),
-  originalError: z.instanceof(Error).optional(),
-  timestamp: z.string(),
-  requestId: z.string().optional(),
-  stack: z.string().optional(),
-});