Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | # Effect v4 core patterns |
| 2 | |
| 3 | These are the patterns actually in the migrated source, not idealized examples. Every |
| 4 | excerpt below cites the file it came from — read that file for full context and to |
| 5 | confirm it still matches (it is the compile-checked source of truth, this reference is |
| 6 | not). |
| 7 | |
| 8 | ## Services: `Context.Service` + explicit layers |
| 9 | |
| 10 | V4 has no `Effect.Service`, `Context.Tag`, or `Context.GenericTag`, and it does not |
| 11 | auto-generate a `.Default` layer the way v3's `Effect.Service` did. Define the service |
| 12 | with `Context.Service` and build the layer yourself. |
| 13 | |
| 14 | Simple case with no dependencies, from `ts/packages/cli/src/services/node-os.ts`: |
| 15 | |
| 16 | ```ts |
| 17 | import os from 'node:os'; |
| 18 | import { Context, Layer } from 'effect'; |
| 19 | |
| 20 | export interface NodeOsShape { |
| 21 | readonly homedir: string; |
| 22 | readonly tmpdir: string; |
| 23 | readonly platform: NodeJS.Platform; |
| 24 | readonly arch: string; |
| 25 | } |
| 26 | |
| 27 | export class NodeOs extends Context.Service<NodeOs, NodeOsShape>()('services/NodeOs') { |
| 28 | static readonly Default: Layer.Layer<NodeOs> = Layer.succeed(NodeOs, { |
| 29 | homedir: os.homedir(), |
| 30 | tmpdir: os.tmpdir(), |
| 31 | platform: os.platform(), |
| 32 | arch: os.arch(), |
| 33 | }); |
| 34 | } |
| 35 | ``` |
| 36 | |
| 37 | `@composio/cli-keyring/src/effect.ts` uses the identical shape for its `KeyringService`: |
| 38 | `Context.Service<KeyringService, KeyringServiceShape>()('composio/cli-keyring/KeyringService')`. |
| 39 | |
| 40 | This repo's convention is a static layer field on the class — `Default` on most |
| 41 | services (`NodeOs`, `NodeProcess`, `ComposioClientSingleton`, `ComposioToolkitsRepository`, |
| 42 | `JsPackageManagerDetector`, `CommandRunner`, `ProjectEnvironmentDetector`), `layer` on a |
| 43 | few (`UpgradeBinary`, `SetupSkillInstaller`). **Check the service's |
| 44 | own class before writing `.Default` or `.layer`** — the two names are not |
| 45 | interchangeable and picking the wrong one is a real compile error, not a style nit. |
| 46 | |
| 47 | For services with dependencies, compose the layer where it is consumed rather than |
| 48 | inside the class, e.g. `ts/packages/cli/src/invocation/live.ts`: |
| 49 | |
| 50 | ```ts |
| 51 | import * as BunFileSystem from '@effect/platform-bun/BunFileSystem'; |
| 52 | import * as BunPath from '@effect/platform-bun/BunPath'; |
| 53 | import { Context, Layer } from 'effect'; |
| 54 | |
| 55 | declare class ComposioToolkitsRepository extends Context.Service< |
| 56 | ComposioToolkitsRepository, |
| 57 | object |
| 58 | >()('x') { |
| 59 | static readonly Default: Layer.Layer<ComposioToolkitsRepository, never, NodeOs>; |
| 60 | } |
| 61 | declare class NodeOs extends Context.Service<NodeOs, object>()('y') { |
| 62 | static readonly Default: Layer.Layer<NodeOs>; |
| 63 | } |
| 64 | declare const LogLevelFromConfigLive: Layer.Layer<never>; |
| 65 | type RequiredLayer = Layer.Layer<ComposioToolkitsRepository>; |
| 66 | |
| 67 | export const ComposioToolkitsRepositoryLive = Layer.provide( |
| 68 | ComposioToolkitsRepository.Default, |
| 69 | Layer.mergeAll(BunFileSystem.layer, BunPath.layer, NodeOs.Default, LogLevelFromConfigLive) |
| 70 | ) satisfies RequiredLayer; |
| 71 | ``` |
| 72 | |
| 73 | Construct an instance shape (mocks, `.of({...})`) with `X.of({...})` — `new X(...)` on a |
| 74 | `Context.Service` class only produces the type-level service-key brand, not a runtime |
| 75 | instance (see the mocks in `ts/packages/cli/test/__utils__/services/test-layer.ts`, e.g. |
| 76 | `ComposioToolkitsRepository.of({ getToolkits: () => Effect.succeed(...), ... })`). Where |
| 77 | a plain function parameter needs the resolved shape rather than the class, use the |
| 78 | exported `...Shape` type or `Context.Service.Shape<typeof X>` (see |
| 79 | `TestLiveInput.commandRunner?: Context.Service.Shape<typeof CommandRunner>` in the same |
| 80 | file), not the bare class name. |
| 81 | |
| 82 | ## Errors: `Data.TaggedError` (default) and `Schema.TaggedError` (schema-backed) |
| 83 | |
| 84 | The established convention in this repo — stated in `ts/packages/cli/AGENTS.md`'s |
| 85 | "Effect safety and migration boundaries" section — is: never wrap a plain `Error` in |
| 86 | `Effect.fail` for an expected failure; give it a `Data.TaggedError` with structured |
| 87 | fields and a preserved cause, then recover with `catchTag`/`catchTags`. This is |
| 88 | unchanged from v3 and is what nearly every error in `src/services/*.ts` uses, e.g. |
| 89 | `ts/packages/cli/src/services/toolkit-version-validation.ts`: |
| 90 | |
| 91 | ```ts |
| 92 | import { Data } from 'effect'; |
| 93 | |
| 94 | export class InvalidToolkitsError extends Data.TaggedError('services/InvalidToolkitsError')<{ |
| 95 | readonly invalidToolkits: ReadonlyArray<string>; |
| 96 | readonly availableToolkits: ReadonlyArray<string>; |
| 97 | }> {} |
| 98 | ``` |
| 99 | |
| 100 | Reach for `Schema.TaggedError` instead only when the error itself needs to be |
| 101 | Schema-encoded/decoded (e.g. it crosses a JSON boundary). It is defined in |
| 102 | `ts/vendor/effect/packages/effect/src/Schema.ts` and shaped like: |
| 103 | |
| 104 | ```ts |
| 105 | import { Schema } from 'effect'; |
| 106 | |
| 107 | class NotFound extends Schema.TaggedError<NotFound>()('NotFound', { |
| 108 | id: Schema.String, |
| 109 | }) {} |
| 110 | ``` |
| 111 | |
| 112 | Either way, recover with `Effect.catchTag`, `Effect.catchTags`, `Match.valueTags`, or a |
| 113 | `Predicate.isTagged` guard — never a manual `error._tag === '...'` branch. |
| 114 | |
| 115 | ## Promise boundaries |
| 116 | |
| 117 | `Effect.tryPromise({ try, catch })` for a Promise that can reject and needs a typed |
| 118 | error; `Effect.promise` turns rejection into a defect (only for Promises that are |
| 119 | truly infallible). No `async`/`await` or `try`/`catch` inside Effect-hosted code. oxlint |
| 120 | rejects `try`/`catch` in `ts/packages/cli/src`. Nothing lints `async`/`await`, so review catches it. From `@composio/cli-keyring`'s |
| 121 | `effect.ts`, both `Effect.tryPromise` and `Effect.promise` kept their v3 signatures |
| 122 | unchanged in v4. |
| 123 | |
| 124 | ## `Effect.gen` vs `Effect.fn`: which form where |
| 125 | |
| 126 | All of these wrap a generator, and all are lazy in the same way: the body is |
| 127 | `suspend`-wrapped, so it **re-runs on every execution** of the resulting effect — which is |
| 128 | why `Effect.retry`/`Effect.repeat` redo the work instead of replaying a cached result |
| 129 | (`gen` in `ts/vendor/effect/packages/effect/src/internal/effect.ts`). |
| 130 | `Effect.fnUntracedEager` is the one eager variant. The axis that actually differs is **what |
| 131 | the expression is** — an Effect value or a function — and **what the tracer records**: |
| 132 | |
| 133 | - `Effect.gen(function* () {...})` produces an Effect **value**. The default for one-shot |
| 134 | workflows and named module consts, from `ts/packages/cli/src/analytics/dispatch.ts`: |
| 135 | |
| 136 | ```ts no-check |
| 137 | const getUserApiKey = Effect.gen(function* () { |
| 138 | const envApiKey = configuredString( |
| 139 | yield* optionalString('COMPOSIO_USER_API_KEY').parse(getEnvironmentProvider()) |
| 140 | ); |
| 141 | if (envApiKey) { |
| 142 | return envApiKey; |
| 143 | } |
| 144 | // ... |
| 145 | }); |
| 146 | ``` |
| 147 | |
| 148 | - `(params) => Effect.gen(function* () {...})` is a plain function returning an effect — |
| 149 | the default for parameterized helpers, from |
| 150 | `ts/packages/cli/scripts/generate-toolkit-slugs.ts`: |
| 151 | |
| 152 | ```ts no-check |
| 153 | const fetchPage = (params: { |
| 154 | baseUrl: string; |
| 155 | headers: Record<string, string>; |
| 156 | cursor?: string; |
| 157 | }): Effect.Effect<ToolkitsPageDecoded, ToolkitFetchError> => |
| 158 | Effect.gen(function* () { |
| 159 | // ... |
| 160 | }); |
| 161 | ``` |
| 162 | |
| 163 | - `Effect.fn(function* (...) {...})` also returns a **function**, but every effect it |
| 164 | produces carries stack-frame annotations for both the call site and the definition site |
| 165 | (`makeFn` updates `CurrentStackFrame`) — this is what feeds the CLI's span-chain recovery |
| 166 | from `Cause.StackTrace` in error reports. The named form `Effect.fn('span.name')(...)` |
| 167 | additionally opens a **tracing span** per call; `Effect.fnUntraced` drops the frames. |
| 168 | Use it for service-shape members and combinator callbacks whose failures should be |
| 169 | attributable, from `ts/packages/cli/src/services/composio-clients.ts`: |
| 170 | |
| 171 | ```ts no-check |
| 172 | return { |
| 173 | get: Effect.fn(function* () { |
| 174 | // ... |
| 175 | }), |
| 176 | getFor: Effect.fn(function* (params: { |
| 177 | userApiKey?: string; |
| 178 | orgId?: string; |
| 179 | projectId?: string; |
| 180 | }) { |
| 181 | // ... |
| 182 | }), |
| 183 | }; |
| 184 | ``` |
| 185 | |
| 186 | The named form's per-call span is additive to those frames; add the name when the span |
| 187 | should appear in error reports, otherwise leave it off. |
| 188 | |
| 189 | When in doubt: value → `Effect.gen`; function → a plain arrow returning `Effect.gen`, |
| 190 | upgrading to `Effect.fn` when failure attribution in error reports is worth the annotation. |
| 191 | Do not migrate one form to the other wholesale. |
| 192 | |
| 193 | ## `Option`: combinators, not `isSome` ternaries |
| 194 | |
| 195 | Transform an `Option` with the module's combinators instead of unwrapping it with |
| 196 | `Option.isSome(x) ? … x.value … : …` and rebuilding it. The combinator names the intent, |
| 197 | and the `None` branch cannot be forgotten or written twice. Rewrites checked against |
| 198 | `effect@4.0.3` (`ts/vendor/effect/packages/effect/src/Option.ts`, `Effect.ts`): |
| 199 | |
| 200 | | Instead of | Write | |
| 201 | | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | |
| 202 | | `Option.map(o, () => b)` | `Option.as(o, b)` | |
| 203 | | `cond ? Option.none() : Option.map(o, f)` | `Option.map(Option.filter(o, () => !cond), f)`; filter once into a local when the condition guards several uses | |
| 204 | | `Option.match(o, { onNone: () => true, onSome: a => a === b })` | `Option.isNone(o) \|\| Option.contains(o, b)` (there is no `Option.forAll`) | |
| 205 | | `Option.match(o, { onNone: () => false, onSome: p })`, `Option.isSome(o) && p(o.value)` | `Option.exists(o, p)` | |
| 206 | | `Option.flatMap(Option.filter(o, p), f)` | `pipe(o, Option.filter(p), Option.flatMap(f))` | |
| 207 | | `Option.isSome(o) ? f(o.value) : x` | `Option.match(o, { onNone: () => x, onSome: f })` | |
| 208 | | `Option.isSome(o) ? f(o.value) : undefined` | `Option.getOrUndefined(Option.map(o, f))` | |
| 209 | | `Option.getOrUndefined(o) ?? x` | `Option.getOrElse(o, () => x)` | |
| 210 | | `Option.getOrUndefined(a) ?? Option.getOrUndefined(b)` | `Option.getOrUndefined(Option.orElse(a, () => b))` | |
| 211 | | `Option.isSome(o) ? Option.some(yield* f(o.value)) : Option.none()` | `yield* Effect.transposeOption(Option.map(o, f))` | |
| 212 | | `Option.isSome(o) ? o.value : yield* fallback` | `yield* Option.match(o, { onSome: Effect.succeed, onNone: () => fallback })` | |
| 213 | |
| 214 | The `??` rows are equivalent only while the `Option`'s value type excludes `null` and |
| 215 | `undefined`. Keep fallbacks lazy (`() => x`) so a `None`-only computation or effect still |
| 216 | runs only on `None`. |
| 217 | |
| 218 | Call `Option.getOrUndefined` only where the value leaves for a plain `?: T` parameter. From |
| 219 | `upgradeCmd` in `ts/packages/cli/src/commands/upgrade.cmd.ts`, where `tag` feeds |
| 220 | `upgrade(options: { prerelease?: boolean; tag?: string })`: |
| 221 | |
| 222 | ```ts no-check |
| 223 | ({ beta, version }) => |
| 224 | Effect.gen(function* () { |
| 225 | const upgradeBinary = yield* UpgradeBinary; |
| 226 | const tag = Option.getOrUndefined(Option.map(version, normalizeReleaseTag)); |
| 227 | const newReleaseTag = yield* upgradeBinary.upgrade({ prerelease: beta, tag }); |
| 228 | // ... |
| 229 | }); |
| 230 | ``` |
| 231 | |
| 232 | A fallback lookup that runs only when the `Option` is empty, from `isTelemetryDebugEnabled` |
| 233 | in `ts/packages/cli/src/services/runtime-flags.ts`: |
| 234 | |
| 235 | ```ts no-check |
| 236 | export const isTelemetryDebugEnabled: Effect.Effect<boolean> = Effect.gen(function* () { |
| 237 | // ... |
| 238 | const bootstrap = yield* Effect.serviceOption(TelemetryDebugMode); |
| 239 | return yield* Option.match(bootstrap, { |
| 240 | onSome: Effect.succeed, |
| 241 | onNone: () => Effect.orDie(DEBUG_CONFIG.TELEMETRY_DEBUG), |
| 242 | }); |
| 243 | }); |
| 244 | ``` |
| 245 | |
| 246 | ## Time in tests: drive `TestClock`, never wait on a real clock |
| 247 | |
| 248 | `it.effect` from `@effect/vitest` runs the test on a `TestClock` parked at epoch. Any sleep |
| 249 | on Effect's clock inside the code under test (`Effect.sleep`, `Effect.retry` with a |
| 250 | `Schedule`, `Effect.timeout`, the API client's retry backoff) only completes when the test |
| 251 | moves that clock. Awaiting such an effect on the test's own fiber hangs until the vitest |
| 252 | timeout, because nothing is left to advance time. Do not fix that with `it.live` when the |
| 253 | code waits out a real backoff, because CI would wait too. |
| 254 | |
| 255 | The pattern is fork, then yield and adjust until the fiber settles, then join: |
| 256 | |
| 257 | ```ts |
| 258 | import { it } from '@effect/vitest'; |
| 259 | import { Effect, Fiber, Schedule } from 'effect'; |
| 260 | import { TestClock } from 'effect/testing'; |
| 261 | |
| 262 | class Unreachable extends Error { |
| 263 | readonly _tag = 'Unreachable'; |
| 264 | } |
| 265 | |
| 266 | // Stands in for a client call that retries with a backoff on Effect's clock: |
| 267 | // `Schedule.max` stops when either schedule does, so two retries, half a second apart and doubling. |
| 268 | const lookup: Effect.Effect<never, Unreachable> = Effect.fail(new Unreachable('fetch failed')).pipe( |
| 269 | Effect.retry(Schedule.max([Schedule.exponential('500 millis'), Schedule.recurs(2)])) |
| 270 | ); |
| 271 | |
| 272 | it.effect('passes the failure through once the retries are spent', () => |
| 273 | Effect.gen(function* () { |
| 274 | // 1. Run the effect on its own fiber so the test fiber stays free to move the clock. |
| 275 | const fiber = yield* lookup.pipe(Effect.flip, Effect.forkChild); |
| 276 | // 2. Let the forked fiber run, then advance past every retry; `adjust` resumes each sleep |
| 277 | // in order, and a sleep scheduled by a resumed fiber inside the window is resumed too. |
| 278 | // Loop on the fiber's own state: when the code under test crosses a Promise boundary |
| 279 | // (a rejected `fetch`) before its first sleep, one yield is not guaranteed to reach it. |
| 280 | for (let step = 0; step < 100 && fiber.pollUnsafe() === undefined; step++) { |
| 281 | yield* Effect.yieldNow; |
| 282 | yield* TestClock.adjust('1 minute'); |
| 283 | } |
| 284 | // 3. Join: the fiber has settled, so this returns without waiting. |
| 285 | const error = yield* Fiber.join(fiber); |
| 286 | if (error._tag !== 'Unreachable') throw new Error('expected the failure to pass through'); |
| 287 | }) |
| 288 | ); |
| 289 | ``` |
| 290 | |
| 291 | Pick an `adjust` window larger than the whole schedule, not equal to one step; one call is |
| 292 | enough because the clock resumes sleeps iteratively up to the target time. Real uses: |
| 293 | `ts/packages/cli/test/src/services/command-project.test.ts` (the client's connection-failure |
| 294 | retry) and `ts/packages/cli/test/src/commands/setup.cmd.test.ts` (a two-minute command |
| 295 | timeout). |
| 296 | |
| 297 | `it.live` is for code that sleeps outside Effect's clock, such as a spawned process or a |
| 298 | `setTimeout` inside a non-Effect library, and even then the test should shorten the wait. |
| 299 | |
| 300 | One Effect-clock case also runs live: a test that answers the API client itself, through the |
| 301 | recording stub (`ts/packages/cli/test/__utils__/services/stub-composio-client.ts`) or a mocked |
| 302 | `fetch`, with a retryable response. Answer it with a `retry-after-ms: 0` header and run on the |
| 303 | live clock, with `it.live` or `layer(..., { excludeTestServices: true })`. The client's retry |
| 304 | then waits zero milliseconds, and a test that expects one request fails on the second instead |
| 305 | of hanging. Real uses: `ts/packages/cli/test/src/services/composio-clients.test.ts` and |
| 306 | `ts/packages/cli/test/src/commands/tools/execute/tools.execute.client.cmd.test.ts`. Nothing in the CLI suite |
| 307 | waits on wall-clock time. |
| 308 | |
| 309 | ## v3 → v4 rename table (historical — recognize stale patterns, don't copy them) |
| 310 | |
| 311 | Verified against `ts/vendor/effect/migration/v3-to-v4.md` and this migration's own |
| 312 | notes. If you see the left column in code or in your own memory of Effect, it is v3 and |
| 313 | needs translation. |
| 314 | |
| 315 | | v3 | v4 | |
| 316 | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | |
| 317 | | `Context.Tag`, `Context.GenericTag`, `Effect.Service` | `Context.Service` | |
| 318 | | generated `.Default` layer | explicit static `Default`/`layer` you define with `Layer.succeed`/`Layer.effect`/`Layer.provide` | |
| 319 | | `@effect/cli`, `@effect/platform` | `effect/cli`, `effect` core / `effect/*` | |
| 320 | | `Effect.catchAll` / `catchAllCause` / `catchAllDefect` / `catchSome` | `Effect.catch` / `catchCause` / `catchDefect` / `catchFilter` | |
| 321 | | `Either` | `Result` (not Effect-yieldable directly — wrap with `Effect.fromResult(...)` inside `Effect.gen`) | |
| 322 | | `ParseResult.ParseError`, `ParseResult.*` | `Schema.SchemaError`, `SchemaIssue.*` | |
| 323 | | `Schema.decodeUnknown` / `Schema.decode` / `Schema.encode` | `Schema.decodeUnknownEffect` / `Schema.decodeEffect` / `Schema.encodeEffect` | |
| 324 | | `Schema.parseJson(schema)` | `Schema.fromJsonString(schema)` | |
| 325 | | `Schema.Literal(a, b)`, `Schema.Union(A, B)` (variadic) | `Schema.Literals([a, b])`, `Schema.Union([A, B])` (array arg) | |
| 326 | | `Schema.Record({ key, value })` | `Schema.Record(key, value)` | |
| 327 | | `Schema.optionalWith(schema, { default })` | `schema.pipe(Schema.withDecodingDefaultType(Effect.succeed(value)))` | |
| 328 | | `.annotations({...})` | `.annotate({...})` | |
| 329 | | `Predicate.isRecord` | removed — use `Predicate.isObject` (or a local `isObject && !Array.isArray` helper) | |
| 330 | | `Cause.isInterruptedOnly` | `Cause.hasInterruptsOnly` | |
| 331 | | `Cause.failureOption` | `Cause.findFail` / `Cause.findErrorOption` | |
| 332 | | `FiberRef` (e.g. `Console`, `ConfigProvider`, `MinimumLogLevel`) | `Context.Reference`, provided via a `Layer`, not `Effect.with*` combinators | |
| 333 | | `Effect.withConfigProvider(provider)` | `Effect.provideService(ConfigProvider.ConfigProvider, provider)` / `Layer.succeed(...)` | |
| 334 | | `ConfigProvider.fromMap(map)` | `ConfigProvider.fromEnv({ env })` (no direct Map constructor) | |
| 335 | | `configProvider.load(config)` | `config.parse(provider)` | |
| 336 | | `Effect.runtime<R>()` + `Runtime.runFork/runPromise` | `Effect.context<R>()` + `Effect.runForkWith`/`runPromiseWith(services)` | |
| 337 | | `LogLevel.Info` etc. (namespace of constants) | plain string-literal union (`'Info'`, note `'Warn'` not `'Warning'`) | |
| 338 | | `it.scoped` (`@effect/vitest`) | removed — `it.effect` already runs `Effect.scoped` | |
| 339 | | `ValidationError`, `HelpDoc`, `CommandDescriptor` (`@effect/cli`) | `CliError`, plain `HelpDoc` data shape, public `Command` fields only — no descriptor introspection | |
| 340 | |
| 341 | For anything not in this table, or any release-to-release drift, verify against |
| 342 | `ts/vendor/effect/migration/*.md` and the actual `ts/vendor/effect/packages/effect/src` |
| 343 | source before writing code — do not extrapolate from this table alone. |