bracket

Source: /nix/store/mls72plk3raskl1r5afh3cl9ik3rn969-source/nix/bracket.nix

Module Description

Resource management with acquire/release patterns.

Ensures cleanup code runs even when errors occur. Essential for managing resources like file handles, connections, or locks that must be properly released.

Built on the condition system for error handling.

Core Pattern

bracket
  acquire    # Fx<S, Resource>
  release    # Resource -> Fx<S, {}>
  use        # Resource -> Fx<S, Value>

The release function ALWAYS runs, even on error.

Example

# Acquire file handle, ensure it closes
withFile = path: action:
  bracket
    (openFile path)           # acquire
    (handle: closeFile handle) # release (always runs)
    action;                    # use

result = runFx (withFile "data.txt" (handle:
  readContents handle
));

Namespace Contents

• bracket - Acquire/release/use pattern
• bracket_ - Ignore result, return use value
• finally - Ensure action runs after effect
• onError - Run action only on error
• onSuccess - Run action only on success
• bracketOnError - Release only on error

Combinators

bracket

General acquire/release/use pattern.

Acquires a resource, runs a computation with it, and ensures the resource is released regardless of success or failure. Returns both the computation result and release result.

Type Signature

Fx<S, R> -> (R -> Fx<S, C>) -> (R -> Fx<S, V>) -> Fx<S, {value: V, cleanup: C}>

Parameters

• acquire: Effect that acquires resource
• release: Function to release resource (always runs)
• use: Function to use resource

Example

bracket
  (openConnection "db.sqlite")
  (conn: closeConnection conn)
  (conn: query conn "SELECT * FROM users")
# => { value = queryResult; cleanup = {}; }

See Also

• bracket_ - Simpler version that discards cleanup result
• finally - Ensure action runs
• bracketOnError - Release only on error

bracketOnError

Acquire/release pattern that only releases on error.

Like bracket but cleanup only happens if use fails. On success, the resource is left acquired (caller’s responsibility).

Type Signature

Fx<S, R> -> (R -> Fx<S, {}>) -> (R -> Fx<S, V>) -> Fx<S, V>

Parameters

• acquire: Effect that acquires resource
• release: Function to release on error only
• use: Function to use resource

Example

bracketOnError
  (beginTransaction)
  (_: rollback)
  (tx: 
    do [
      (_: insertUser tx user)
      (_: insertPosts tx posts)
      (_: commit tx)  # Success: we committed
    ])
# rollback only runs if insertUser/insertPosts fail

See Also

• bracket - Always releases
• onError - Simpler error-only action

bracket_

Simplified bracket that discards release result.

Like bracket but only returns the use result, discarding the cleanup value. Most common case for resource management.

Type Signature

Fx<S, R> -> (R -> Fx<S, {}>) -> (R -> Fx<S, V>) -> Fx<S, V>

Parameters

• acquire: Effect that acquires resource
• release: Function to release resource
• use: Function to use resource

Example

withFile = path: action:
  bracket_
    (openFile path)
    (h: closeFile h)
    action;

content = runFx (withFile "data.txt" readAll);

See Also

• bracket - Full version with cleanup result
• finally - Simpler cleanup without resource

finally

Ensures an action runs after an effect, even on error.

Simpler than bracket when you don’t need to acquire/pass a resource. The cleanup action runs regardless of success or failure.

Type Signature

Fx<S, V> -> Fx<S, {}> -> Fx<S, V>

Parameters

• effect: Main computation
• cleanup: Action to run afterwards (always)

Example

finally
  (riskyComputation)
  (logMetrics)
# logMetrics runs whether riskyComputation succeeds or fails

See Also

• bracket - When you need acquire/release
• onError - Run only on failure
• onSuccess - Run only on success

onError

Runs an action only if the effect fails.

Error-specific cleanup or logging. The action runs before the error propagates. Original error is preserved.

Type Signature

Fx<S, V> -> Fx<S, {}> -> Fx<S, V>

Parameters

• effect: Computation that might fail
• cleanup: Action to run on error only

Example

onError
  (riskyOperation)
  (rollbackTransaction)
# rollbackTransaction only runs if riskyOperation fails

See Also

• onSuccess - Opposite pattern
• finally - Run on both success and failure
• bracketOnError - Release resource only on error

onSuccess

Runs an action only if the effect succeeds.

Success-specific actions like committing transactions or sending notifications. The action runs after success, before returning the value.

Type Signature

Fx<S, V> -> Fx<S, {}> -> Fx<S, V>

Parameters

• effect: Computation that might succeed
• action: Action to run on success only

Example

onSuccess
  (transaction)
  (commitToDatabase)
# commitToDatabase only runs if transaction succeeds

See Also

• onError - Opposite pattern
• finally - Run on both success and failure

Generated from /nix/store/mls72plk3raskl1r5afh3cl9ik3rn969-source/nix/bracket.nix