effect-pulumi 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,366 @@
+import * as effect_Cause from 'effect/Cause';
+import * as effect_Types from 'effect/Types';
+import * as pulumi from '@pulumi/pulumi';
+import { Effect } from 'effect';
+import { PulumiFn, LocalWorkspaceOptions, ConfigMap, UpOptions, PreviewOptions, Stack, UpResult, PreviewResult, DestroyOptions, DestroyResult, RefreshOptions, RefreshResult, RemoveOptions, OutputMap } from '@pulumi/pulumi/automation/index.js';
+
+declare const PulumiError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "PulumiError";
+} & Readonly<A>;
+/**
+ * Any synchronous failure constructing a resource (bad args, provider
+ * validation, etc.), or a failure resolving an Output's promise.
+ *
+ * Tagged `"PulumiError"`, so it can be matched by tag rather than by
+ * `instanceof`:
+ *
+ * @example
+ * ```ts
+ * program.pipe(
+ *   Effect.catchTag("PulumiError", (e) => Effect.logError(e.message))
+ * );
+ * ```
+ */
+declare class PulumiError extends PulumiError_base<{
+    /** The original thrown value or rejection reason, unwrapped and unmodified.
+     * Not necessarily an `Error`. */
+    readonly cause: unknown;
+}> {
+    /** Derived so anything reading `.message` — plain logging, test failure
+     * output, non-Effect error handling — sees the underlying failure instead
+     * of an empty string. */
+    get message(): string;
+}
+declare const AutomationError_base: new <A extends Record<string, any> = {}>(args: effect_Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => effect_Cause.YieldableError & {
+    readonly _tag: "AutomationError";
+} & Readonly<A>;
+/**
+ * Failure from an Automation API lifecycle call (up/preview/destroy/select).
+ *
+ * `stage` says which call failed, which matters most in the composite
+ * operations: a failed `deploy` could have died selecting the stack, applying
+ * config, or running the update, and the three want different responses.
+ *
+ * @example
+ * ```ts
+ * deploy(opts).pipe(
+ *   Effect.catchTag("AutomationError", (e) =>
+ *     e.stage === "createOrSelectStack"
+ *       ? Effect.fail(new BackendUnreachable())
+ *       : Effect.logError(e.message)
+ *   )
+ * );
+ * ```
+ */
+declare class AutomationError extends AutomationError_base<{
+    /** Which Automation API call failed. Named for the wrapper that raised it,
+     * so `deploy`'s failures still report the underlying stage. */
+    readonly stage: "createOrSelectStack" | "setConfig" | "up" | "preview" | "refresh" | "outputs" | "destroy" | "removeStack";
+    /** The rejection reason from the Automation API. For a failed update this is
+     * usually a `CommandError` carrying the CLI's stdout and stderr. */
+    readonly cause: unknown;
+}> {
+    /** `"<stage> failed: <cause>"` — the stage is included because the cause
+     * alone rarely says which operation produced it. */
+    get message(): string;
+}
+
+/**
+ * Lift a single Output into an Effect.
+ *
+ * `withUnknowns: true` matters during `pulumi preview`, where a not-yet-created
+ * resource's outputs have no value: it resolves to Pulumi's unknown sentinel
+ * instead of throwing, so a program that reads outputs still previews cleanly.
+ *
+ * @param output - The Output to resolve.
+ * @returns An Effect yielding the settled value, failing with
+ * {@link PulumiError} if the underlying promise rejects.
+ *
+ * @example
+ * ```ts
+ * const bucket = yield* eaws.s3.Bucket("assets", {});
+ * const id = yield* fromOutput(bucket.id); // string
+ * ```
+ *
+ * @remarks Reading an Output only makes sense inside a running Pulumi program.
+ * During `preview` the value may be the unknown sentinel rather than real data,
+ * so don't branch on it to decide what to create.
+ */
+declare const fromOutput: <T>(output: pulumi.Output<T>) => Effect.Effect<T, PulumiError>;
+/**
+ * Lift a record of Outputs into a single Effect of the resolved record — use
+ * this right after constructing a resource to grab several fields at once.
+ *
+ * Resolves them together via `pulumi.all`, so it costs one await rather than
+ * one per field.
+ *
+ * @param outputs - A record whose values are all Outputs. Interfaces work as
+ * well as object literals; the constraint is self-referential rather than
+ * `Record<string, Output<any>>` precisely so interface-typed bags are accepted.
+ * @returns An Effect yielding the same record with each value unwrapped.
+ *
+ * @example
+ * ```ts
+ * const bucket = yield* eaws.s3.Bucket("assets", {});
+ * const { id, arn } = yield* fromOutputs({ id: bucket.id, arn: bucket.arn });
+ * ```
+ */
+declare const fromOutputs: <T extends { [K in keyof T]: pulumi.Output<any>; }>(outputs: T) => Effect.Effect<{ [K in keyof T]: pulumi.Unwrap<T[K]>; }, PulumiError>;
+
+/**
+ * effectify — auto-wrap a Pulumi provider package (e.g. @pulumi/aws,
+ * @pulumi/cloudflare) so every resource constructor becomes an
+ * Effect-returning factory, without the caller ever writing `Effect.sync`.
+ *
+ * Usage:
+ *
+ *   import * as aws from "@pulumi/aws";
+ *   const eaws = effectify(aws);
+ *
+ *   const program = Effect.gen(function* () {
+ *     const bucket = yield* eaws.s3.Bucket("my-bucket", { forceDestroy: true });
+ *     //    ^ Effect<aws.s3.Bucket, PulumiError> — no manual wrapping
+ *   });
+ *
+ * How it works:
+ *  - Every Pulumi resource class extends `pulumi.Resource` under the hood
+ *    (via CustomResource / ComponentResource). That's the runtime marker
+ *    used to tell "this export is a resource constructor" apart from "this
+ *    export is a namespace object" (e.g. `aws.s3`) or "this export is an
+ *    invoke function" (e.g. `aws.s3.getBucket`).
+ *  - Namespace objects get recursively proxied (lazily, memoized).
+ *  - CustomResource constructors get wrapped so any field in their args
+ *    object may *additionally* be an Effect — resolved (concurrently, they
+ *    are independent by construction) before construction. This is safe
+ *    because codegen guarantees CustomResource args are always
+ *    Record<string, Input<T>>.
+ *  - Wrapped constructors keep their static members: `Bucket.get(...)`,
+ *    `Bucket.isInstance(...)` and friends forward to the original class, so
+ *    the wrapped package can be the only import a program needs.
+ *  - ComponentResource constructors get wrapped with no arg-lifting — args
+ *    pass through exactly as declared, since component args aren't
+ *    guaranteed to be Input<T>-shaped (hand-authored, may do synchronous
+ *    work on a bare primitive inside the constructor).
+ *  - Invoke functions (`aws.s3.getBucket`) return an Effect instead of a
+ *    Promise. There is no runtime marker for "this function is async", so
+ *    the wrapper calls the function and inspects the result: a thenable
+ *    becomes an Effect, anything else is returned as-is. That means the
+ *    invoke *starts* at the call site (see the caveat on `wrapInvokeLike`);
+ *    `*Output` invoke variants return an Output, which is not thenable, so
+ *    they pass through untouched — matching the type-level mapping, which
+ *    only rewrites Promise-returning signatures.
+ *  - Everything else (enums, plain values, non-resource classes) passes
+ *    through untouched.
+ *
+ * Resource registration remains synchronous under the hood — Effect.try
+ * runs its thunk immediately. This only removes hand-written wrapper
+ * boilerplate, not Pulumi's execution model.
+ */
+
+/** Allow any field of a CustomResource args object to *additionally* be an
+ * Effect. Homomorphic, so optional fields stay optional and plain
+ * `Input<T>`/`Output<T>` values keep working untouched. */
+type LiftedArgs<A> = A extends object ? {
+    [K in keyof A]: A[K] | Effect.Effect<A[K], PulumiError>;
+} : A;
+/** Apply `LiftedArgs` to the second constructor parameter (the args object),
+ * leaving `name` and `opts` alone. Mapping over the parameter tuple
+ * homomorphically preserves labels and optionality, so constructors whose
+ * args are optional stay callable as `Bucket("name")`. */
+type LiftArgsParam<P extends readonly unknown[]> = {
+    [K in keyof P]: K extends "1" ? LiftedArgs<P[K]> : P[K];
+};
+/** The class's static side, minus `prototype`: `keyof` on a constructor type
+ * yields exactly the statics (own and inherited, e.g. codegen'd `get` and
+ * `isInstance`), which the runtime wrapper forwards to the original class. */
+type StaticMembers<T> = Omit<T, "prototype">;
+/**
+ * The type of {@link effectify}'s result: `T` with every resource constructor
+ * and every `Promise`-returning invoke rewritten, and everything else left
+ * alone.
+ *
+ * The cases, in the order they are tried:
+ *
+ * | Input                       | Becomes                                        |
+ * | --------------------------- | ---------------------------------------------- |
+ * | `ComponentResource` class   | factory returning `Effect`, args **not** lifted |
+ * | `CustomResource` class      | factory returning `Effect`, args lifted         |
+ * | other class                 | unchanged                                       |
+ * | `(...) => Promise<R>`       | `(...) => Effect<R, PulumiError>`               |
+ * | other function              | unchanged (includes `*Output` invokes)          |
+ * | object                      | mapped recursively                              |
+ * | anything else               | unchanged                                       |
+ *
+ * Statics survive on the wrapped constructors, so `Bucket.get` and
+ * `Bucket.isInstance` remain callable.
+ */
+type Effectify<T> = T extends abstract new (...params: infer P) => infer R ? R extends pulumi.ComponentResource ? ((...params: P) => Effect.Effect<R, PulumiError>) & StaticMembers<T> : R extends pulumi.CustomResource ? ((...params: LiftArgsParam<P>) => Effect.Effect<R, PulumiError>) & StaticMembers<T> : T : T extends (...args: infer A) => Promise<infer R> ? (...args: A) => Effect.Effect<R, PulumiError> : T extends (...args: any[]) => any ? T : T extends object ? {
+    [K in keyof T]: Effectify<T[K]>;
+} : T;
+/**
+ * Wrap a provider package (or any namespace) once, turning every resource
+ * constructor into an `Effect`-returning factory and every `Promise`-returning
+ * invoke into an `Effect`-returning function.
+ *
+ * Call this once per package at module scope and export the result — the
+ * wrapper is cached, so repeated calls and repeated property reads hand back
+ * the same objects, but there is no reason to re-wrap.
+ *
+ * @param mod - The provider package, or any namespace within one. Not mutated;
+ * the result is a read-only proxy that forwards to it.
+ * @returns A same-shaped view of `mod`, typed by {@link Effectify}.
+ *
+ * @example Constructing a resource
+ * ```ts
+ * import * as aws from "@pulumi/aws";
+ * const eaws = effectify(aws);
+ *
+ * const program = Effect.gen(function* () {
+ *   const bucket = yield* eaws.s3.Bucket("assets", { forceDestroy: true });
+ *   return bucket.id;
+ * });
+ * ```
+ *
+ * @example Passing an Effect as an argument
+ * A `CustomResource`'s args may hold Effects, which are resolved concurrently
+ * before the resource is constructed:
+ * ```ts
+ * yield* eaws.s3.BucketObject("readme", {
+ *   bucket: bucketIdEffect,
+ *   content: "hello",
+ * });
+ * ```
+ *
+ * @throws Nothing. Failures surface in the returned Effect's error channel as
+ * {@link PulumiError} — including synchronous throws from the constructor.
+ *
+ * @see {@link Effectify} for the type-level mapping.
+ */
+declare function effectify<T extends object>(mod: T): Effectify<T>;
+
+/** Arguments for an inline program — the Pulumi program is a function in this
+ * process, with no `Pulumi.yaml` on disk. */
+interface InlineStackOptions {
+    /** Stack to select, created if absent. */
+    readonly stackName: string;
+    /** Project name to register the stack under. Chosen freely here, since
+     * there is no `Pulumi.yaml` to take it from — but it is part of the stack's
+     * identity in the backend, so changing it later points at a different
+     * stack. */
+    readonly projectName: string;
+    /** The program itself. Runs in this process, so it needs no separate Node
+     * runtime and can close over values from the caller. */
+    readonly program: PulumiFn;
+    readonly workspaceOptions?: LocalWorkspaceOptions;
+}
+/** Arguments for a local program — an existing Pulumi project on disk. */
+interface LocalStackOptions {
+    /** Stack to select, created if absent. */
+    readonly stackName: string;
+    /** Directory holding the project's `Pulumi.yaml`. Its `name:` supplies the
+     * project name, which is why there is no `projectName` here. */
+    readonly workDir: string;
+    readonly workspaceOptions?: LocalWorkspaceOptions;
+}
+/** Either flavour of stack. Discriminated at runtime by the presence of
+ * `workDir`, so the two are not interchangeable: an inline program needs
+ * `projectName`, a local one takes it from `Pulumi.yaml`. */
+type StackOptions = InlineStackOptions | LocalStackOptions;
+/** Select the stack, creating it if it does not exist, and return the handle
+ * every other operation here takes.
+ *
+ * Creating the workspace is itself work — it may write files and shell out to
+ * the CLI — so hold on to the returned `Stack` rather than re-selecting before
+ * each operation. */
+declare const createOrSelectStack: (opts: StackOptions) => Effect.Effect<Stack, AutomationError>;
+/** Apply the whole config map in one `setAllConfig` call — a single CLI
+ * round-trip, where per-key `setConfig` costs one `pulumi config set`
+ * invocation each. */
+declare const setStackConfig: (stack: Stack, config: ConfigMap | undefined) => Effect.Effect<void, AutomationError>;
+/** Compute the plan without applying it.
+ *
+ * A preview is a full engine run against the provider, not a cheap check — see
+ * {@link DeployOptions.preview} before pairing one with an `up`. */
+declare const previewStack: (stack: Stack, opts?: PreviewOptions) => Effect.Effect<PreviewResult, AutomationError>;
+/** Apply the program: create, update and delete resources to match it.
+ *
+ * The result carries the stack's outputs and a summary; pass `onOutput` to
+ * watch progress while it runs. */
+declare const upStack: (stack: Stack, opts?: UpOptions) => Effect.Effect<UpResult, AutomationError>;
+/** Refresh the stack's state from the actual cloud resources, without
+ * changing them — what to run when state may have drifted (manual console
+ * edits, a crashed update) before deciding what to do about it. */
+declare const refreshStack: (stack: Stack, opts?: RefreshOptions) => Effect.Effect<RefreshResult, AutomationError>;
+/** Read the stack's current outputs without running an update. */
+declare const stackOutputs: (stack: Stack) => Effect.Effect<OutputMap, AutomationError>;
+/** Destroy the stack's resources. The stack itself remains registered with
+ * the backend — see `removeStack` / `teardownStack` to delete it too. */
+declare const destroyStack: (stack: Stack, opts?: DestroyOptions) => Effect.Effect<DestroyResult, AutomationError>;
+/** Delete the stack and its configuration and history from the backend.
+ *
+ * This does not destroy resources — run `destroyStack` first, or use
+ * `teardownStack`. Pulumi refuses to remove a stack that still has resources
+ * unless `RemoveOptions.force` is set, and forcing it orphans them: they keep
+ * existing and billing with nothing tracking them. */
+declare const removeStack: (stack: Stack, opts?: RemoveOptions) => Effect.Effect<void, AutomationError>;
+/** Full teardown: destroy the resources, then delete the stack.
+ *
+ * `destroyStack` alone leaves an empty stack behind, so anything creating
+ * stacks per-run (ephemeral environments, tests naming stacks by timestamp)
+ * accumulates them in the backend. */
+declare const teardownStack: (stack: Stack, opts?: {
+    readonly destroy?: DestroyOptions;
+    readonly remove?: RemoveOptions;
+}) => Effect.Effect<DestroyResult, AutomationError>;
+/** {@link deploy}'s arguments: the stack to target, plus what to do with it. */
+type DeployOptions = StackOptions & {
+    /** Config to apply before the update, in one `setAllConfig` call. Keys are
+     * fully qualified (`"my-project:myKey"`). */
+    readonly config?: ConfigMap;
+    /** Options forwarded to the update — `onOutput` to stream progress,
+     * `parallel`, `target`, and so on. */
+    readonly up?: UpOptions;
+    /** Run `preview` before `up`, returning its result.
+     *
+     * Off by default: a preview is a full engine run against the provider, so
+     * previewing and then immediately upping does the work twice. `up` reports
+     * the same failures, so this earns its cost only when you want the plan
+     * itself. */
+    readonly preview?: PreviewOptions | boolean;
+};
+/** What {@link deploy} hands back. */
+interface DeployResult {
+    /** The selected stack, so teardown needs no second `createOrSelectStack`. */
+    readonly stack: Stack;
+    /** The update's result — `outputs` and `summary` live here. */
+    readonly result: UpResult;
+    /** Present only when `preview` was requested. */
+    readonly preview?: PreviewResult;
+}
+/**
+ * Select or create the stack, apply config, optionally preview, then up.
+ *
+ * The common path, assembled from the primitives above. Anything more
+ * involved — refreshing first, inspecting the plan before deciding, retrying a
+ * stage — should compose those directly rather than grow options here.
+ *
+ * @param opts - Which stack, and what to do with it.
+ * @returns The stack handle alongside the results, so callers can tear down
+ * afterwards without re-selecting.
+ *
+ * @example Deploy, use the outputs, then always tear down
+ * ```ts
+ * Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const { result } = yield* Effect.acquireRelease(
+ *       deploy({ stackName, projectName, program, up: { onOutput } }),
+ *       ({ stack }) => teardownStack(stack).pipe(Effect.ignore)
+ *     );
+ *     return result.outputs.bucketId?.value;
+ *   })
+ * );
+ * ```
+ */
+declare const deploy: (opts: DeployOptions) => Effect.Effect<DeployResult, AutomationError>;
+
+export { AutomationError, type DeployOptions, type DeployResult, type Effectify, type InlineStackOptions, type LocalStackOptions, PulumiError, type StackOptions, createOrSelectStack, deploy, destroyStack, effectify, fromOutput, fromOutputs, previewStack, refreshStack, removeStack, setStackConfig, stackOutputs, teardownStack, upStack };