Skip to content

Commit

Permalink
Add runMain docs (#4249)
Browse files Browse the repository at this point in the history
  • Loading branch information
gcanti authored Jan 14, 2025
1 parent d0a9da2 commit ca07bd6
Show file tree
Hide file tree
Showing 2 changed files with 153 additions and 0 deletions.
105 changes: 105 additions & 0 deletions packages/platform/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,111 @@ Welcome to the documentation for `@effect/platform`, a library designed for crea
> [!WARNING]
> This documentation focuses on **unstable modules**. For stable modules, refer to the [official website documentation](https://effect.website/docs/guides/platform/introduction).
# Running Your Main Program with runMain

`runMain` helps you execute a main effect with built-in error handling, logging, and signal management. You can concentrate on your effect while `runMain` looks after finalizing resources, logging errors, and setting exit codes.

- **Exit Codes**
If your effect fails or is interrupted, `runMain` assigns a suitable exit code (for example, `1` for errors and `0` for success).
- **Logs**
By default, it records errors. This can be turned off if needed.
- **Pretty Logging**
By default, error messages are recorded using a "pretty" format. You can switch this off when required.
- **Interrupt Handling**
If the application receives `SIGINT` (Ctrl+C) or a similar signal, `runMain` will interrupt the effect and still run any necessary teardown steps.
- **Teardown Logic**
You can rely on the default teardown or define your own. The default sets an exit code of `1` for a non-interrupted failure.

## Usage Options

When calling `runMain`, pass in a configuration object with these fields (all optional):

- `disableErrorReporting`: If `true`, errors are not automatically logged.
- `disablePrettyLogger`: If `true`, it avoids adding the "pretty" logger.
- `teardown`: Provide a custom function for finalizing the program. If missing, the default sets exit code `1` for a non-interrupted failure.

**Example** (Running a Successful Program)

```ts
import { NodeRuntime } from "@effect/platform-node"
import { Effect } from "effect"

const success = Effect.succeed("Hello, World!")

NodeRuntime.runMain(success)
// No Output
```

**Example** (Running a Failing Program)

```ts
import { NodeRuntime } from "@effect/platform-node"
import { Effect } from "effect"

const failure = Effect.fail("Uh oh!")

NodeRuntime.runMain(failure)
/*
Output:
[12:43:07.186] ERROR (#0):
Error: Uh oh!
*/
```

**Example** (Running a Failing Program Without Pretty Logger)

```ts
import { NodeRuntime } from "@effect/platform-node"
import { Effect } from "effect"

const failure = Effect.fail("Uh oh!")

NodeRuntime.runMain(failure, { disablePrettyLogger: true })
/*
Output:
timestamp=2025-01-14T11:43:46.276Z level=ERROR fiber=#0 cause="Error: Uh oh!"
*/
```

**Example** (Running a Failing Program Without Error Reporting)

```ts
import { NodeRuntime } from "@effect/platform-node"
import { Effect } from "effect"

const failure = Effect.fail("Uh oh!")

NodeRuntime.runMain(failure, { disableErrorReporting: true })
// No Output
```

**Example** (Running a Failing Program With Custom Teardown)

```ts
import { NodeRuntime } from "@effect/platform-node"
import { Effect } from "effect"

const failure = Effect.fail("Uh oh!")

NodeRuntime.runMain(failure, {
teardown: function customTeardown(exit, onExit) {
if (exit._tag === "Failure") {
console.error("Program ended with an error.")
onExit(1)
} else {
console.log("Program finished successfully.")
onExit(0)
}
}
})
/*
Output:
[12:46:39.871] ERROR (#0):
Error: Uh oh!
Program ended with an error.
*/
```

# HTTP API

## Overview
Expand Down
48 changes: 48 additions & 0 deletions packages/platform/src/Runtime.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,61 @@ export const defaultTeardown: Teardown = <E, A>(
* @since 1.0.0
*/
export interface RunMain {
/**
* Helps you run a main effect with built-in error handling, logging, and signal management.
*
* **Details**
*
* This function launches an Effect as the main entry point, setting exit codes
* based on success or failure, handling interrupts (e.g., Ctrl+C), and optionally
* logging errors. By default, it logs errors and uses a "pretty" format, but both
* behaviors can be turned off. You can also provide custom teardown logic to
* finalize resources or produce different exit codes.
*
* **Options**
*
* An optional object that can include:
* - `disableErrorReporting`: Turn off automatic error logging.
* - `disablePrettyLogger`: Avoid adding the pretty logger.
* - `teardown`: Provide custom finalization logic.
*
* **When to Use**
*
* Use this function to run an Effect as your application’s main program, especially
* when you need structured error handling, log management, interrupt support,
* or advanced teardown capabilities.
*/
(
options?: {
readonly disableErrorReporting?: boolean | undefined
readonly disablePrettyLogger?: boolean | undefined
readonly teardown?: Teardown | undefined
}
): <E, A>(effect: Effect.Effect<A, E>) => void
/**
* Helps you run a main effect with built-in error handling, logging, and signal management.
*
* **Details**
*
* This function launches an Effect as the main entry point, setting exit codes
* based on success or failure, handling interrupts (e.g., Ctrl+C), and optionally
* logging errors. By default, it logs errors and uses a "pretty" format, but both
* behaviors can be turned off. You can also provide custom teardown logic to
* finalize resources or produce different exit codes.
*
* **Options**
*
* An optional object that can include:
* - `disableErrorReporting`: Turn off automatic error logging.
* - `disablePrettyLogger`: Avoid adding the pretty logger.
* - `teardown`: Provide custom finalization logic.
*
* **When to Use**
*
* Use this function to run an Effect as your application’s main program, especially
* when you need structured error handling, log management, interrupt support,
* or advanced teardown capabilities.
*/
<E, A>(
effect: Effect.Effect<A, E>,
options?: {
Expand Down

0 comments on commit ca07bd6

Please sign in to comment.