simple_flow 0.1.0

data/docs/api/result.md

@@ -0,0 +1,375 @@
+# Result API Reference
+
+The `Result` class is an immutable value object that represents the outcome of a step in a SimpleFlow pipeline. It encapsulates the operation's value, contextual data, and any errors that occurred.
+
+## Class: `SimpleFlow::Result`
+
+**Location**: `/Users/dewayne/sandbox/git_repos/madbomber/simple_flow/lib/simple_flow/result.rb`
+
+### Constructor
+
+#### `new(value, context: {}, errors: {})`
+
+Creates a new Result instance.
+
+**Parameters:**
+- `value` (Object) - The outcome of the operation
+- `context` (Hash, optional) - Contextual data related to the operation (default: `{}`)
+- `errors` (Hash, optional) - Errors organized by category (default: `{}`)
+
+**Returns:** Result instance
+
+**Example:**
+```ruby
+# Basic result
+result = SimpleFlow::Result.new(42)
+
+# Result with context
+result = SimpleFlow::Result.new(
+  { user_id: 123 },
+  context: { timestamp: Time.now }
+)
+
+# Result with errors
+result = SimpleFlow::Result.new(
+  nil,
+  errors: { validation: ["Email is required"] }
+)
+```
+
+### Instance Attributes
+
+#### `value`
+
+The outcome of the operation.
+
+**Type:** Object (read-only)
+
+**Example:**
+```ruby
+result = SimpleFlow::Result.new(42)
+result.value  # => 42
+```
+
+#### `context`
+
+Contextual data related to the operation.
+
+**Type:** Hash (read-only)
+
+**Example:**
+```ruby
+result = SimpleFlow::Result.new(42, context: { user: "John" })
+result.context  # => { user: "John" }
+```
+
+#### `errors`
+
+Errors that occurred during the operation, organized by category.
+
+**Type:** Hash (read-only)
+
+**Example:**
+```ruby
+result = SimpleFlow::Result.new(nil, errors: {
+  validation: ["Email required", "Password too short"],
+  auth: ["Invalid credentials"]
+})
+
+result.errors[:validation]  # => ["Email required", "Password too short"]
+result.errors[:auth]        # => ["Invalid credentials"]
+```
+
+### Instance Methods
+
+#### `with_context(key, value)`
+
+Adds or updates context to the result. Returns a new Result instance with updated context.
+
+**Parameters:**
+- `key` (Symbol) - The key to store the context under
+- `value` (Object) - The value to store
+
+**Returns:** New Result instance
+
+**Immutability:** This method creates a new Result object; the original is unchanged.
+
+**Example:**
+```ruby
+result = SimpleFlow::Result.new(42)
+  .with_context(:user_id, 123)
+  .with_context(:timestamp, Time.now)
+
+result.context  # => { user_id: 123, timestamp: 2025-11-15 12:00:00 }
+```
+
+**Chaining:**
+```ruby
+result = SimpleFlow::Result.new(data)
+  .with_context(:step_name, "process_data")
+  .with_context(:duration, 0.5)
+  .with_context(:source, :api)
+```
+
+#### `with_error(key, message)`
+
+Adds an error message under a specific key. If the key already exists, the message is appended to existing errors. Returns a new Result instance with updated errors.
+
+**Parameters:**
+- `key` (Symbol) - The category under which to store the error
+- `message` (String) - The error message
+
+**Returns:** New Result instance
+
+**Immutability:** Creates a new Result object.
+
+**Example:**
+```ruby
+result = SimpleFlow::Result.new(nil)
+  .with_error(:validation, "Email is required")
+  .with_error(:validation, "Password too short")
+  .with_error(:auth, "Invalid credentials")
+
+result.errors
+# => {
+#      validation: ["Email is required", "Password too short"],
+#      auth: ["Invalid credentials"]
+#    }
+```
+
+**Error Accumulation:**
+```ruby
+result = SimpleFlow::Result.new(data)
+
+# Add first validation error
+result = result.with_error(:validation, "Name is required")
+
+# Add second validation error (accumulates)
+result = result.with_error(:validation, "Email is required")
+
+result.errors[:validation]
+# => ["Name is required", "Email is required"]
+```
+
+#### `halt(new_value = nil)`
+
+Halts the pipeline flow. Optionally updates the result's value. Returns a new Result instance with `continue` set to false.
+
+**Parameters:**
+- `new_value` (Object, optional) - New value to set (default: keep current value)
+
+**Returns:** New Result instance with `@continue = false`
+
+**Example:**
+```ruby
+# Halt without changing value
+result = SimpleFlow::Result.new(42).halt
+result.continue?  # => false
+result.value      # => 42
+
+# Halt with new value
+result = SimpleFlow::Result.new(42).halt(100)
+result.continue?  # => false
+result.value      # => 100
+
+# Halt with error
+result = SimpleFlow::Result.new(data)
+  .halt
+  .with_error(:validation, "Invalid input")
+
+result.continue?  # => false
+result.errors     # => { validation: ["Invalid input"] }
+```
+
+**Usage in Steps:**
+```ruby
+step ->(result) {
+  if invalid?(result.value)
+    result.halt.with_error(:validation, "Invalid data")
+  else
+    result.continue(process(result.value))
+  end
+}
+```
+
+#### `continue(new_value)`
+
+Continues the pipeline flow with an updated value. Returns a new Result instance with the new value.
+
+**Parameters:**
+- `new_value` (Object) - The new value to set
+
+**Returns:** New Result instance with updated value
+
+**Example:**
+```ruby
+result = SimpleFlow::Result.new(5)
+  .continue(10)
+
+result.continue?  # => true
+result.value      # => 10
+```
+
+**Usage in Steps:**
+```ruby
+step ->(result) {
+  transformed = transform(result.value)
+  result.continue(transformed)
+}
+```
+
+#### `continue?`
+
+Checks if the pipeline should continue executing.
+
+**Returns:** Boolean
+- `true` if the pipeline should continue
+- `false` if the pipeline has been halted
+
+**Example:**
+```ruby
+result = SimpleFlow::Result.new(42)
+result.continue?  # => true
+
+result = result.halt
+result.continue?  # => false
+```
+
+**Usage:**
+```ruby
+result = pipeline.call(initial_data)
+
+if result.continue?
+  puts "Success: #{result.value}"
+  process_result(result)
+else
+  puts "Failed: #{result.errors}"
+  handle_errors(result)
+end
+```
+
+## Usage Patterns
+
+### Basic Flow Control
+
+```ruby
+step ->(result) {
+  if valid?(result.value)
+    result.continue(result.value)
+  else
+    result.halt.with_error(:validation, "Invalid")
+  end
+}
+```
+
+### Error Accumulation
+
+```ruby
+step ->(result) {
+  result_obj = result
+
+  if invalid_email?(result.value[:email])
+    result_obj = result_obj.with_error(:email, "Invalid format")
+  end
+
+  if invalid_phone?(result.value[:phone])
+    result_obj = result_obj.with_error(:phone, "Invalid format")
+  end
+
+  # Continue even with errors (check later)
+  result_obj.continue(result.value)
+}
+
+step ->(result) {
+  if result.errors.any?
+    result.halt(result.value)
+  else
+    result.continue(result.value)
+  end
+}
+```
+
+### Context Propagation
+
+```ruby
+pipeline = SimpleFlow::Pipeline.new do
+  step ->(result) {
+    result
+      .with_context(:started_at, Time.now)
+      .with_context(:user_id, 123)
+      .continue(result.value)
+  }
+
+  step ->(result) {
+    # Access context from previous step
+    user_id = result.context[:user_id]
+    data = fetch_user_data(user_id)
+
+    result
+      .with_context(:user_data, data)
+      .continue(result.value)
+  }
+
+  step ->(result) {
+    # All context available
+    duration = Time.now - result.context[:started_at]
+
+    result
+      .with_context(:duration, duration)
+      .continue(process(result.value))
+  }
+end
+```
+
+### Combining Operations
+
+```ruby
+step ->(result) {
+  result
+    .with_context(:timestamp, Time.now)
+    .with_context(:source, :api)
+    .with_error(:warning, "Deprecated API version")
+    .continue(transformed_data)
+}
+```
+
+## Implementation Details
+
+### Immutability
+
+All Result methods return new instances:
+
+```ruby
+original = SimpleFlow::Result.new(42)
+modified = original.with_context(:key, "value")
+
+original.context  # => {}
+modified.context  # => { key: "value" }
+
+# original and modified are different objects
+original.object_id != modified.object_id  # => true
+```
+
+### Internal State
+
+The Result class maintains internal state that is preserved across method calls:
+
+```ruby
+result = SimpleFlow::Result.new(42)
+  .halt
+  .with_context(:key, "value")
+
+# @continue flag is preserved
+result.continue?  # => false
+result.context    # => { key: "value" }
+```
+
+### Thread Safety
+
+Result objects are immutable and thread-safe. Multiple threads can safely read from the same Result instance.
+
+## Related Documentation
+
+- [Pipeline API](pipeline.md) - How pipelines use Result objects
+- [Error Handling Guide](../guides/error-handling.md) - Error handling patterns
+- [Validation Patterns](../guides/validation-patterns.md) - Validation strategies