diff --git a/packages/codemode/README.md b/packages/codemode/README.md index 5c658a0bc194..2294f286c121 100644 --- a/packages/codemode/README.md +++ b/packages/codemode/README.md @@ -223,8 +223,9 @@ that returns a Promise or an Effect, so a denied call rejects its promise like a Extension.make({ name: "web", globals: { fetch: Extension.async((url: string) => globalThis.fetch(url)) } }) ``` -A global may return a value, a Promise, or an Effect. An Effect's requirements join the runtime's environment the same -way a tool's do, so the host can provide per-execution services such as the calling session: +A global may return a value, a Promise, or an Effect. A synchronous global's Effect runs to completion before the call +returns, so the host can offer blocking calls such as `fs.readFileSync`. An Effect's requirements join the runtime's +environment the same way a tool's do, so the host can provide per-execution services such as the calling session: ```ts const web = Extension.make({ diff --git a/packages/codemode/interpreter-support.md b/packages/codemode/interpreter-support.md index a2298fd5109e..11ede69b69dc 100644 --- a/packages/codemode/interpreter-support.md +++ b/packages/codemode/interpreter-support.md @@ -632,6 +632,9 @@ Nothing is exposed unless a host provides it; extension calls are not tool calls `code`, `errno`, `syscall`, and `path` reach the program and `err.code === "ENOENT"` works. `stack` stays on its own side, no field may shadow an Error method, and a field that cannot cross (a class instance, a function) is left behind rather than replacing the error. +- [x] A synchronous global that returns an Effect blocks the program until the Effect completes and returns its + value or throws its error, as `fs.readFileSync` does. An `async` global (or one marked `Extension.async`) hands + the program a promise instead. - [ ] Program functions as arguments to extension code (callbacks such as `forEach`). - [ ] Host classes. Stateful host objects are expressed as closures; a declared method table would be the next step if `new X()` in a program is ever needed. diff --git a/packages/codemode/src/extension.ts b/packages/codemode/src/extension.ts index eb4342b8dc0c..c6864c1a1487 100644 --- a/packages/codemode/src/extension.ts +++ b/packages/codemode/src/extension.ts @@ -8,7 +8,9 @@ import type { Effect } from "effect" * function inside a result is callable the same way. Extension calls are not tool calls. A global may return a value, * a Promise, or an Effect, and an Effect's requirements join the runtime's environment. * - * A global is synchronous unless it is an `async` function or is marked with `async`. The `extension.before` hook + * A global is synchronous unless it is an `async` function or is marked with `async`. A synchronous global that + * returns an Effect blocks the program until the Effect completes and returns its value, as `fs.readFileSync` does; + * an asynchronous one hands the program a promise. The `extension.before` hook * runs before the call, so a denied call never reaches the host; it fails the way the global would, by rejecting the * promise of an asynchronous global and by throwing from a synchronous one. Functions inside a global object are * called the same way, named by their path (`fs.readFile`). @@ -34,13 +36,13 @@ export type Snapshot = { readonly decode: (data: unknown) => unknown } -/** The Effect environment required by an extension's Effect-returning functions, at the top level or one level in. */ +/** The Effect environment required by an extension's Effect-returning functions, at any depth (`fs.promises.readFile`). */ export type Services = E extends { readonly globals: infer Globals } ? GlobalServices : never type GlobalServices = Global extends (...args: never) => unknown ? Requirements : Global extends object - ? Requirements + ? GlobalServices : never type Requirements = F extends (...args: never) => infer Result ? Effect.Services : never diff --git a/packages/codemode/src/host.ts b/packages/codemode/src/host.ts index d1fdc3fd5949..7ddad97120a1 100644 --- a/packages/codemode/src/host.ts +++ b/packages/codemode/src/host.ts @@ -257,8 +257,8 @@ const arrayOf = (vm: HostVm, values: Array) => new Arr(vm.ctx.builtins.Ar /** * A synchronous extension function's call, staged here so its host values never enter a frame: the `extension.before` - * hook (blocking), then the host function; what it returns settles now (blocking) unless it is an Effect or a Promise, - * which the program holds a promise for. The call is active, holding live host values, until its result is a program + * hook (blocking), then the host function; what it returns settles now (blocking, an Effect + * included) unless it is a Promise, which the program holds a promise for. The call is active, holding live host values, until its result is a program * value or its concurrent call is queued. */ export const callExtension = ( diff --git a/packages/codemode/src/runtime/extensions.ts b/packages/codemode/src/runtime/extensions.ts index 1a4e8500dc4a..99b645f60b47 100644 --- a/packages/codemode/src/runtime/extensions.ts +++ b/packages/codemode/src/runtime/extensions.ts @@ -359,7 +359,8 @@ const pending = (ctx: Interpreter, call: ExtensionRequest, site: AstNode | /** * Calls a synchronous extension function's host function, once its `extension.before` hook allowed it: a promise for - * a result that settles later (an Effect or a Promise), or the request that settles what it returned or threw now. + * a returned Promise, or the request that settles what it returned or threw. A returned Effect settles through that + * request too, so the program blocks until it completes, as `fs.readFileSync` does. */ export const startExtensionCall = ( ctx: Interpreter, @@ -370,7 +371,7 @@ export const startExtensionCall = ( ): PromiseObj | ExtensionRequest => { const [result, threw] = callHost(host, args) const request = { stage: "settle", ...call, host: result, args, threw } as const - if (!threw && (Effect.isEffect(result) || result instanceof Promise)) return pending(ctx, request, site) + if (!threw && result instanceof Promise) return pending(ctx, request, site) return request } diff --git a/packages/codemode/test/extensions.test.ts b/packages/codemode/test/extensions.test.ts index 5e66727559e0..236a149fcacb 100644 --- a/packages/codemode/test/extensions.test.ts +++ b/packages/codemode/test/extensions.test.ts @@ -417,13 +417,18 @@ describe("Effect globals", () => { const web = Extension.make({ name: "web", globals: { - fetch: (url: string) => + fetch: Extension.async((url: string) => Effect.gen(function* () { const session = yield* Session sent.push(url) return { url, session: session.id } }), - fail: () => Effect.fail(new RangeError("denied")), + ), + fail: Extension.async(() => Effect.fail(new RangeError("denied"))), + fs: { + readSync: (path: string) => Session.use((session) => Effect.succeed(`${session.id}:${path}`)), + failSync: () => Effect.fail(new RangeError("missing")), + }, }, }) @@ -458,6 +463,18 @@ describe("Effect globals", () => { expect(result).toMatchObject({ ok: true, value: [true, "denied"] }) }) + test("a synchronous Effect global returns its value, or throws, before the next statement", async () => { + const result = await Effect.runPromise( + CodeMode.make({ extensions: [web] }) + .execute( + `const text = fs.readSync("a") + try { fs.failSync() } catch (e) { return [text, e instanceof RangeError, e.message] }`, + ) + .pipe(Effect.provideService(Session, { id: "ses_1" })), + ) + expect(result).toMatchObject({ ok: true, value: ["ses_1:a", true, "missing"] }) + }) + test("a denying before hook stops the Effect before it runs", async () => { sent.length = 0 const runtime = CodeMode.make({