effect-pulumi 0.1.1 → 0.2.0

package/README.md

@@ -12,6 +12,7 @@ Mixing Effect and Pulumi by hand means wrapping every constructor and every
 data-source call yourself:
 
 ```ts
+// InfraError here is a tagged error you have to define yourself
 const bucket = yield* Effect.try({
   try: () => new aws.s3.Bucket("assets", { forceDestroy: true }),
   catch: (cause) => new InfraError({ cause }),
@@ -39,8 +40,9 @@ npm install effect-pulumi
 ```
 
 Requires Node.js ≥ 22 (the floor `@pulumi/pulumi` itself sets). The peer
-ranges are `@pulumi/pulumi ^3.0.0` and `effect ^3.0.0`, currently verified
-against `@pulumi/pulumi` 3.255 and `effect` 3.22.
+ranges are `@pulumi/pulumi ^3.0.0` and `effect ^4.0.0`. Projects still on
+Effect 3 should stay on `effect-pulumi@0.1.2`, the last release that supports
+it.
 
 `@pulumi/pulumi` and `effect` are peer dependencies - this library extends
 your Pulumi and Effect runtimes, so it must use the same copies you do rather
@@ -52,12 +54,7 @@ npm install @pulumi/pulumi effect
 ```
 
 Ships as dual ESM + CommonJS, so it works from a conventional CJS Pulumi
-program as well as an ESM one:
-
-```ts
-import { effectify } from "effect-pulumi";   // ESM
-const { effectify } = require("effect-pulumi"); // CJS
-```
+program as well as an ESM one - both are shown below.
 
 ## Quick start
 
@@ -86,101 +83,34 @@ const program = Effect.gen(function* () {
 export const { id, key } = await Effect.runPromise(program);
 ```
 
-Alternatively, hand `program` to the [Automation API](#automation-api) as an
-inline program and deploy it from the same process.
-
-The full version of the program above lives in
-[`test/s3-bucket-program.ts`](test/s3-bucket-program.ts). It sits in `test/`
-rather than `examples/` because it is a fixture rather than a project you can
-run - its only consumer today is the mocked suite in `npm test`, exercising a
-real `@pulumi/aws` package under Pulumi's mocks, no cloud account involved.
-
-For examples you can actually deploy, see [`examples/`](examples/) - those use
-`@pulumi/random`, whose resources take no inputs from one another, so they
-don't show `fromOutput` or an Effect in an args slot. For that, see
-[`test/random-password-file-program.ts`](test/random-password-file-program.ts):
-a `RandomPassword`'s Output flows into a `local.File`'s args, and it's
-deployed for real by `npm run test:live` - no cloud credentials needed, since
-`@pulumi/local` only touches the local filesystem.
-
-## What `effectify` does
-
-`effectify(mod)` returns a lazy, memoized proxy over a provider package:
-
-| Export kind | Result |
-| --- | --- |
-| `CustomResource` subclass | `(name, args, opts?) => Effect<R, PulumiError>`, and any **top-level** args field may additionally be an `Effect` (several resolve concurrently) |
-| `ComponentResource` subclass | `(name, args, opts?) => Effect<R, PulumiError>`, args passed through verbatim - never auto-lifted |
-| Namespace object (`aws.s3`) | Recursively proxied, lazily |
-| Invoke function (`aws.s3.getBucket`) | Returns `Effect<R, PulumiError>` instead of `Promise<R>` |
-| `*Output` invoke variant (`getBucketOutput`) | Passed through untouched (returns an `Output`, as upstream) |
-| Enums, plain values, sync functions | Passed through untouched |
-
-Semantics worth knowing:
-
-- **Outputs still work exactly as in vanilla Pulumi.** `effectify` only
-  *additionally* accepts `Effect`s; passing a bare `Output<T>` or `Input<T>`
-  needs no unwrapping or rewrapping.
-- **Statics survive the wrapping.** `eaws.s3.Bucket.get(name, id)` (adopt an
-  existing resource), `isInstance`, and any other codegen'd static forward to
-  the original class - `instanceof` works too - so the wrapped package can be
-  the only import a program needs.
-- **Component args are never lifted.** Component args aren't guaranteed to be
-  `Input<T>`-shaped the way codegen'd `CustomResource` args are - a component
-  may do synchronous work on a bare primitive in its constructor - so passing
-  an `Effect` where a component expects a primitive is a type error. See
-  [Component resources](#component-resources) for the patterns this implies.
-- **Invokes start when you call them.** Whether a function is async is only
-  knowable by calling it, so `eaws.getAmi(args)` fires the invoke immediately
-  and hands back an Effect that resolves the already-in-flight call - the
-  failure still lands in the typed error channel, but `Effect.retry` re-awaits
-  the same call rather than re-invoking. To re-invoke per attempt, defer the
-  call site: `Effect.suspend(() => eaws.getAmi(args))`.
-
-Resource registration stays synchronous under the hood; `Effect.try` runs its
-thunk immediately. This removes wrapper boilerplate, not Pulumi's execution
-model.
-
-## Component resources
-
-Component resources are fully supported as *consumers*: `effectify` detects
-any class extending `pulumi.ComponentResource` - your own, or those in a
-component-based package like `@pulumi/awsx` - and wraps its constructor into
-an Effect factory, exactly like a custom resource. Construction errors land
-in the typed error channel, and the component sequences with `yield*` like
-everything else.
-
-What differs is the args object. Custom resource args can carry `Effect`
-fields because codegen guarantees they are all `Input<T>`-shaped, so
-substituting a resolved value is always legal. Component args are
-hand-authored: a component may take a bare `replicas: number` and do
-synchronous arithmetic on it inside its constructor, and an `Effect` silently
-swapped in there would break it. So for components, `effectify` refuses at
-the type level instead of guessing - resolve your Effects first, then
-construct with plain values:
+Pulumi's TypeScript programs default to CommonJS (no `"type": "module"` in
+`package.json`), where top-level `await` isn't available. `fromOutput` and
+`fromOutputs` resolve an Output's real value, which is genuinely
+asynchronous, so `Effect.runSync` isn't an option here either - it throws on
+any effect that suspends on real async work. Export the Promise itself
+instead; Pulumi's engine awaits an exported Promise the same way it would an
+awaited value. The `program` itself is unchanged - only the first and last
+lines differ:
 
 ```ts
-const eawsx = effectify(awsx);
+const aws = require("@pulumi/aws");
+const { Effect } = require("effect");
+const { effectify, fromOutput, fromOutputs } = require("effect-pulumi");
 
-const program = Effect.gen(function* () {
-  // ✗ type error - component args are never auto-lifted:
-  //   eawsx.ecs.Cluster("app", { vpcId: fromOutput(vpc.id) })
+// ... same program ...
 
-  // ✓ resolve first, then pass a plain value (or just pass the Output -
-  //   Input<T>-typed component args accept those as in vanilla Pulumi):
-  const vpcId = yield* fromOutput(vpc.id);
-  const cluster = yield* eawsx.ecs.Cluster("app", { vpcId });
-});
+module.exports = Effect.runPromise(program);
 ```
 
-*Authoring* a component is different: a `ComponentResource` constructor is
-synchronous, so you cannot `yield*` inside it. Write a component's internals
-in plain Pulumi - its children are ordinary constructor calls - and use
-`effectify` at the program level, where composition actually happens. The
-wrapped and unwrapped worlds interoperate freely: a component built from raw
-Pulumi children can itself be constructed through an effectified package,
-and its `Output` properties flow into `fromOutput`/`fromOutputs` like any
-other resource's.
+`Effect.runSync` does work for programs that never resolve an Output's value
+- e.g. [`examples/random-pet`](examples/random-pet), which exports raw
+`Output`s from resource properties directly rather than reading through them
+with `fromOutput`.
+
+Alternatively, hand `program` to the [Automation API](#automation-api) as an
+inline program and deploy it from the same process.
+
+For projects you can deploy as-is, see [`examples/`](examples/).
 
 ## Automation API
 
@@ -191,93 +121,33 @@ re-selecting.
 ```ts
 const exit = await Effect.runPromiseExit(
   deploy({
-    stackName,
-    projectName,
-    program: inlineProgram("dev"),
+    stackName: "dev",
+    projectName: "my-infra",
+    // a PulumiFn - run the Effect, return its result as the stack outputs
+    program: async () => Effect.runPromise(program),
     up: { onOutput: (out) => process.stdout.write(out) },
   })
 );
 // Exit/Cause instead of a thrown, stringified error
 ```
 
-Every operation forwards the matching Pulumi options type - `UpOptions`,
-`PreviewOptions`, `RefreshOptions`, `DestroyOptions`, `RemoveOptions`. Pass
+Stacks are either inline programs (`projectName` + `program`, above) or an
+existing project on disk (`workDir`), and every operation forwards the
+matching Pulumi options type - `UpOptions`, `DestroyOptions`, and so on. Pass
 `onOutput` to stream the CLI's progress; without it a multi-minute deploy
-prints nothing until it finishes. Stacks can be inline programs
-(`projectName` + `program`) or an existing project on disk (`workDir`).
-
-Previewing is opt-in via `preview: true` (or a `PreviewOptions` object), and
-its result comes back on `DeployResult.preview`. It is off by default because
-a preview is a full engine run against the provider, so previewing and then
-immediately upping does the work twice - and `up` surfaces the same failures.
-
-Teardown is two steps. `destroyStack` removes the resources but leaves the
-stack registered with the backend; `teardownStack` destroys and then deletes
-it, which is what you want for per-run stacks. `RemoveOptions.force` deletes a
-stack while leaving its resources alive and billing - it is reachable, but it
-orphans them.
+prints nothing until it finishes.
 
-## Handling failures
+Preview is opt-in via `preview: true` and comes back on
+`DeployResult.preview`. It is off by default because a preview is a full
+engine run, so previewing and then immediately upping does the work twice -
+and `up` surfaces the same failures anyway.
 
-Failures are values with types, not stringified stack traces. `PulumiError`
-covers resource construction and Output resolution; `AutomationError` adds
-the lifecycle `stage` it came from. Both derive `.message` from the
-underlying cause, so they read well even outside Effect.
+Teardown is two steps: `destroyStack` removes the resources but leaves the
+stack registered, while `teardownStack` destroys and then deletes it - the
+latter is what per-run stacks want. Avoid `RemoveOptions.force`, which drops
+a stack while leaving its resources alive and billing with nothing tracking
+them.
 
-```ts
-import { Effect } from "effect";
-import { deploy } from "effect-pulumi";
-
-const guarded = deploy({ stackName, projectName, program }).pipe(
-  // Transient engine failures during `up` are worth another attempt; a
-  // failure creating the stack or setting config is not.
-  Effect.retry({ times: 2, while: (error) => error.stage === "up" }),
-  Effect.catchTag("AutomationError", (error) =>
-    Effect.fail(new Error(`deploy failed at ${error.stage}: ${error.message}`))
-  )
-);
-```
+## License
 
-The same works inside a program: `Effect.catchTag("PulumiError", …)` around a
-resource, or `Effect.exit` / `runPromiseExit` at the edge to inspect the full
-`Cause`.
-
-## API
-
-| Export | What it does |
-| --- | --- |
-| `effectify(mod)` | Wrap a provider package (or any namespace) once; see the table above |
-| `fromOutput(output)` | `Output<T>` → `Effect<T, PulumiError>`; resolves to the unknown sentinel during `preview` instead of throwing |
-| `fromOutputs(record)` | Record of Outputs → `Effect` of the resolved record |
-| `deploy(opts)` | Select/create stack → apply config → optional preview → `up`; returns `{ stack, result, preview? }` |
-| `createOrSelectStack(opts)` | Inline (`projectName` + `program`) or local (`workDir`) stack |
-| `setStackConfig(stack, config)` | Apply a whole config map in one `setAllConfig` round-trip |
-| `previewStack(stack, opts?)` | `pulumi preview`, returning the `PreviewResult` |
-| `upStack(stack, opts?)` | `pulumi up`, returning the `UpResult` |
-| `refreshStack(stack, opts?)` | Re-sync state from the actual cloud resources |
-| `stackOutputs(stack)` | Read current outputs without running an update |
-| `destroyStack(stack, opts?)` | Destroy resources; the stack stays registered |
-| `removeStack(stack, opts?)` | Delete the stack from the backend |
-| `teardownStack(stack, opts?)` | Destroy then remove - skips the remove if the destroy failed |
-| `PulumiError` | Construction / Output-resolution failure; carries `cause` |
-| `AutomationError` | Lifecycle failure; carries `stage` and `cause` |
-
-## Scripts
-
-| Command | What it does |
-| --- | --- |
-| `npm run build` | Build dual ESM + CJS (`tsup`) with declarations to `dist/` |
-| `npm run typecheck` | Type-check everything, including tests and examples |
-| `npm run lint` | Lint with `oxlint` (`npm run lint:fix` applies safe fixes) |
-| `npm run format` | Format with `oxfmt` (`npm run format:check` asserts instead) |
-| `npm run check` | `typecheck` + `lint` + `format:check`, the pre-commit sweep |
-| `npm test` | Unit + mocked-provider tests. No credentials needed |
-| `npm run test:package` | Builds, packs a tarball and consumes it from ESM and CJS projects |
-| `npm run test:live` | Deploys `test/s3-bucket-program.ts` against real AWS, then destroys it |
-
-`npm test` never runs the live harness: it's excluded in `vitest.config.ts`
-and additionally gated on `EFFECT_PULUMI_RUN_LIVE_TESTS=1`. The live harness
-picks up credentials from the environment the normal way each provider expects
-(e.g. `AWS_PROFILE` / `AWS_ACCESS_KEY_ID`), and uses
-`Effect.acquireRelease` + `Effect.scoped` so the stack is destroyed even when
-an assertion fails.
+MIT - see [LICENSE](LICENSE).