Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 343 lines 20.1 KB
Rendered Raw
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.