railway-clj.core — org.clojars.konkon/railway-clj 0.1.0

!> clj macro

(!> & body)

Railway-oriented try/catch. Executes the body and returns a Success with the result. If an exception occurs, returns a Failure with error details.

Example: (!> (/ 10 5)) => (success 2) (!> (/ 10 0)) => (failure {:error "Unexpected error" :details "Divide by zero"})

->error clj

(->error result)

->value clj

(->value result)

<|> clj macro

(<|> value alternative)

Try alternative on failure. If the value is a Failure, evaluates and returns the alternative. Otherwise, returns the original Success unchanged. Similar to the 'or' operation in many languages. Preserves laziness for Success results, but forces evaluation of Failure to determine if the alternative should be used.

Example: (<|> (failure "error") (success 42)) => (success 42) (<|> (success 1) (success 2)) => (success 1) (<|> (lazy-failure #(->error)) (lazy-success #(fallback))) => (lazy-success #(fallback))

>-< clj macro

(>-< value success-fn failure-fn)

Branch processing based on success/failure. Takes a result and two functions - one for handling success, one for handling failure. This is the terminal operation in a railway chain. Forces evaluation of lazy results.

Example: (>-< (success 42) #(str "Success: " %) #(str "Error: " %)) => "Success: 42" (>-< (lazy-success #(expensive-calc)) #(str "Success: " %) #(str "Error: " %)) => "Success: [result of expensive-calc]"

attempt clj macro

(attempt f error-handler)

Creates a function that catches exceptions and handles them with the provided handler. Useful for wrapping functions that might throw exceptions.

Example: (def safe-divide (attempt #(/ 10 %) #(failure {:error "Division error"}))) (safe-divide 2) => 5 (safe-divide 0) => (failure {:error "Division error"})

delay-railway clj macro

(delay-railway & body)

Creates a lazy railway result (Success or Failure) based on the evaluation of the body when forced.

Example: (delay-railway (validate-data data)) => LazySuccess or LazyFailure (|> (delay-railway (db-operation)) process-result) => Preserves laziness

delay-success clj macro

(delay-success & body)

Creates a lazy success that will only execute the body when needed. Useful for expensive operations that might not be needed.

Example: (delay-success (expensive-calculation)) => LazySuccess (|> (delay-success (expensive-calculation)) process-result) => LazySuccess

either clj macro

(either pred then else)

Creates a function that applies one of two functions based on a predicate. Similar to an if-statement, but returns a function that can be composed.

Example: (def process (either even? #(* 2 %) #(+ 1 %))) (process 2) => 4 (process 3) => 4

failure clj

(failure error)

failure? clj

(failure? result)

force-lazy clj

(force-lazy result)

guard clj macro

(guard pred error-msg)

Creates a function that succeeds if a predicate passes, otherwise fails. Useful for validating conditions in a railway chain.

Example: (def check-positive (guard pos? "Value must be positive")) (check-positive 5) => (success 5) (check-positive -1) => (failure {:error "Value must be positive"})

lazy-failure clj

(lazy-failure thunk)

lazy-success clj

(lazy-success thunk)

lazy? clj

(lazy? result)

success clj

(success value)

success? clj

(success? result)

validate clj

(validate spec value)

Validates a value against a spec, returning a railway result. Returns Success with the value if valid, otherwise a Failure with detailed error information.

Example: (s/def ::person (s/keys :req-un [::name ::age])) (validate ::person {:name "John" :age 30}) => (success {:name "John" :age 30}) (validate ::person {}) => (failure {:error "Validation failed" :details "..."})

|+ clj

(|+ & fs)

Chains multiple functions in a railway pattern. Returns a new function that applies each function in sequence, stopping and returning the first Failure encountered. Each function should either return a railway result or a plain value (which will be wrapped in Success).

Example: (def workflow (|+ validate-user check-permissions save-user)) (workflow user-data) => Success or Failure depending on chain results

|-| clj macro

(|-| value & fns)

Thread error value through functions. Only applies functions if the input is a Failure. Otherwise, passes the Success through unchanged. Handles lazy results by preserving laziness.

Example: (|-| (failure {:msg "Error"}) #(assoc % :timestamp "now")) => (failure {:msg "Error" :timestamp "now"}) (|-| (success 42) #(assoc % :info "ignored")) => (success 42) (|-| (lazy-failure #(->error)) add-timestamp) => (lazy-failure #(add-timestamp (->error)))

|> clj macro

(|> value & fns)

Thread success value through functions. Similar to the -> threading macro, but only applies functions if the input is a Success. Otherwise, passes the Failure through unchanged. Handles lazy results by preserving laziness.

Example: (|> (success 5) inc double) => (success 12) (|> (failure :error) inc double) => (failure :error) (|> (lazy-success #(expensive-calc)) inc) => (lazy-success #(inc (expensive-calc)))

|>lazy clj macro

(|>lazy value & fns)

Similar to |> but ensures all operations are done lazily, even if the input is not lazy.

Example: (|>lazy (success 5) expensive-calc format-result) => LazySuccess