alchemy-effect 0.0.0

package/src/apply.ts

@@ -0,0 +1,318 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type { Simplify } from "effect/Types";
+import { PlanReviewer, type PlanRejected } from "./approve.ts";
+import type { AnyBinding, BindingService } from "./binding.ts";
+import type { ApplyEvent, ApplyStatus } from "./event.ts";
+import { type BindNode, type CRUD, type Delete, type Plan } from "./plan.ts";
+import type { Resource } from "./resource.ts";
+import { State } from "./state.ts";
+
+export interface PlanStatusSession {
+  emit: (event: ApplyEvent) => Effect.Effect<void>;
+  done: () => Effect.Effect<void>;
+}
+
+export interface ScopedPlanStatusSession extends PlanStatusSession {
+  note: (note: string) => Effect.Effect<void>;
+}
+
+export class PlanStatusReporter extends Context.Tag("PlanStatusReporter")<
+  PlanStatusReporter,
+  {
+    start(plan: Plan): Effect.Effect<PlanStatusSession, never>;
+  }
+>() {}
+
+export const apply = <P extends Plan, Err, Req>(
+  plan: Effect.Effect<P, Err, Req>,
+) =>
+  plan.pipe(
+    Effect.flatMap((plan) =>
+      Effect.gen(function* () {
+        const state = yield* State;
+        const outputs = {} as Record<string, Effect.Effect<any, any>>;
+        const reviewer = yield* Effect.serviceOption(PlanReviewer);
+
+        if (Option.isSome(reviewer)) {
+          yield* reviewer.value.approve(plan);
+        }
+
+        const events = yield* Effect.serviceOption(PlanStatusReporter);
+
+        const session = Option.isSome(events)
+          ? yield* events.value.start(plan)
+          : ({
+              emit: () => Effect.void,
+              done: () => Effect.void,
+            } satisfies PlanStatusSession);
+        const { emit, done } = session;
+
+        const applyBindings = Effect.fn(function* (
+          resource: Resource,
+          bindings: BindNode[],
+          target: {
+            id: string;
+            props: any;
+            attr: any;
+          },
+        ) {
+          return yield* Effect.all(
+            bindings.map(
+              Effect.fn(function* (node) {
+                const binding = node.binding as AnyBinding & {
+                  // smuggled property (because it interacts poorly with inference)
+                  Tag: Context.Tag<never, BindingService>;
+                };
+                const provider = yield* binding.Tag;
+
+                const resourceId: string = node.binding.capability.resource.id;
+                const upstreamNode = plan.resources[resourceId];
+                const upstreamAttr = resource
+                  ? yield* apply(upstreamNode)
+                  : yield* Effect.dieMessage(
+                      `Resource ${resourceId} not found`,
+                    );
+
+                const attach = provider.attach({
+                  source: {
+                    id: resourceId,
+                    attr: upstreamAttr,
+                    props: upstreamNode.resource.props,
+                  },
+                  props: node.binding.props,
+                  target,
+                });
+                return Effect.isEffect(attach)
+                  ? yield* attach as Effect.Effect<any, never, never>
+                  : attach;
+              }),
+            ),
+          );
+        });
+
+        const apply: (node: CRUD) => Effect.Effect<any, never, never> = (
+          node,
+        ) =>
+          Effect.gen(function* () {
+            const checkpoint = <Out, Err>(
+              effect: Effect.Effect<Out, Err, never>,
+            ) =>
+              effect.pipe(
+                Effect.flatMap((output) =>
+                  state
+                    .set(node.resource.id, {
+                      id: node.resource.id,
+                      type: node.resource.type,
+                      status: node.action === "create" ? "created" : "updated",
+                      props: node.resource.props,
+                      output,
+                      bindings: node.bindings,
+                    })
+                    .pipe(Effect.map(() => output)),
+                ),
+              );
+
+            const id = node.resource.id;
+            const resource = node.resource;
+
+            const scopedSession = {
+              ...session,
+              note: (note: string) =>
+                session.emit({
+                  id,
+                  kind: "annotate",
+                  message: note,
+                }),
+            } satisfies ScopedPlanStatusSession;
+
+            return yield* (outputs[id] ??= yield* Effect.cached(
+              Effect.gen(function* () {
+                const report = (status: ApplyStatus) =>
+                  emit({
+                    kind: "status-change",
+                    id,
+                    type: node.resource.type,
+                    status,
+                  });
+
+                if (node.action === "noop") {
+                  return (yield* state.get(id))?.output;
+                } else if (node.action === "create") {
+                  let attr: any;
+                  if (node.provider.stub) {
+                    // stub the resource prior to resolving upstream resources or bindings if a stub is available
+                    attr = yield* node.provider.stub({
+                      id,
+                      news: node.news,
+                      session: scopedSession,
+                    });
+                  }
+
+                  const bindings = yield* applyBindings(
+                    resource,
+                    node.bindings,
+                    {
+                      id,
+                      props: node.news,
+                      attr,
+                    },
+                  );
+
+                  yield* report("creating");
+
+                  return yield* node.provider
+                    .create({
+                      id,
+                      news: node.news,
+                      bindings,
+                      session: scopedSession,
+                    })
+                    .pipe(
+                      checkpoint,
+                      Effect.tap(() => report("created")),
+                    );
+                } else if (node.action === "update") {
+                  const bindings = yield* applyBindings(
+                    resource,
+                    node.bindings,
+                    {
+                      id,
+                      props: node.news,
+                      attr: node.attributes,
+                    },
+                  );
+
+                  yield* report("updating");
+
+                  // const bindings = yield* applyDependencies(node.bindings);
+
+                  return yield* node.provider
+                    .update({
+                      id,
+                      news: node.news,
+                      olds: node.olds,
+                      output: node.output,
+                      bindings,
+                      session: scopedSession,
+                    })
+                    .pipe(
+                      checkpoint,
+                      Effect.tap(() => report("updated")),
+                    );
+                } else if (node.action === "delete") {
+                  yield* Effect.all(
+                    node.downstream.map((dep) =>
+                      dep in plan.resources
+                        ? apply(
+                            plan.resources[
+                              dep
+                            ] as P["resources"][keyof P["resources"]],
+                          )
+                        : Effect.void,
+                    ),
+                  );
+                  yield* report("deleting");
+
+                  return yield* node.provider
+                    .delete({
+                      id,
+                      olds: node.olds,
+                      output: node.output,
+                      session: scopedSession,
+                      bindings: [],
+                    })
+                    .pipe(
+                      Effect.flatMap(() => state.delete(id)),
+                      Effect.tap(() => report("deleted")),
+                    );
+                } else if (node.action === "replace") {
+                  const destroy = Effect.gen(function* () {
+                    yield* report("deleting");
+                    return yield* node.provider.delete({
+                      id,
+                      olds: node.olds,
+                      output: node.output,
+                      session: scopedSession,
+                      bindings: [],
+                    });
+                  });
+                  const create = Effect.gen(function* () {
+                    yield* report("creating");
+                    return yield* (
+                      node.provider
+                        .create({
+                          id,
+                          news: node.news,
+                          // TODO(sam): these need to only include attach actions
+                          bindings: yield* applyBindings(
+                            resource,
+                            node.bindings,
+                            {
+                              id,
+                              props: node.news,
+                              attr: node.attributes,
+                            },
+                          ),
+                          session: scopedSession,
+                        })
+                        // TODO(sam): delete and create will conflict here, we need to extend the state store for replace
+                        .pipe(
+                          checkpoint,
+                          Effect.tap(() => report("created")),
+                        )
+                    );
+                  });
+                  if (!node.deleteFirst) {
+                    const outputs = yield* create;
+                    yield* destroy;
+                    return outputs;
+                  } else {
+                    yield* destroy;
+                    return yield* create;
+                  }
+                }
+              }),
+            ));
+          }) as Effect.Effect<any, never, never>;
+
+        const nodes = [
+          ...Object.entries(plan.resources),
+          ...Object.entries(plan.deletions),
+        ];
+
+        const resources: any = Object.fromEntries(
+          yield* Effect.all(
+            nodes.map(
+              Effect.fn(function* ([id, node]) {
+                return [id, yield* apply(node as CRUD)];
+              }),
+            ),
+          ),
+        );
+        yield* done();
+        if (Object.keys(plan.resources).length === 0) {
+          // all resources are deleted, return undefined
+          return undefined;
+        }
+        return resources;
+      }),
+    ),
+  ) as Effect.Effect<
+    "update" extends P["phase"]
+      ?
+          | {
+              [id in keyof P["resources"]]: P["resources"][id] extends
+                | Delete<Resource>
+                | undefined
+                | never
+                ? never
+                : Simplify<P["resources"][id]["resource"]["attr"]>;
+            }
+          // union distribution isn't happening, so we gotta add this additional void here just in case
+          | ("destroy" extends P["phase"] ? void : never)
+      : void,
+    Err | PlanRejected,
+    Req
+  >;

package/src/approve.ts

@@ -0,0 +1,13 @@
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import type * as Effect from "effect/Effect";
+import type { Plan } from "./plan.ts";
+
+export class PlanRejected extends Data.TaggedError("PlanRejected")<{}> {}
+
+export class PlanReviewer extends Context.Tag("PlanReviewer")<
+  PlanReviewer,
+  {
+    approve: <P extends Plan>(plan: P) => Effect.Effect<void, PlanRejected>;
+  }
+>() {}

package/src/binding.ts

@@ -0,0 +1,144 @@
+import * as Context from "effect/Context";
+import type { Effect } from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { Capability, ICapability } from "./capability.ts";
+import type { Resource } from "./resource.ts";
+import type { Runtime } from "./runtime.ts";
+
+export interface BindingProps {
+  [key: string]: any;
+}
+
+export const isBinding = (b: any): b is AnyBinding =>
+  "runtime" in b && "capability" in b && "tag" in b && "output" in b;
+
+export type AnyBinding<F extends Runtime = any> = Binding<
+  F,
+  any,
+  any,
+  string,
+  boolean
+>;
+
+export interface Binding<
+  Run extends Runtime,
+  Cap extends Capability = Capability,
+  Props = any,
+  Tag extends string = Cap["type"],
+  IsCustom extends boolean = Cap["type"] extends Tag ? false : true,
+> {
+  runtime: Run;
+  capability: Cap;
+  tag: Tag;
+  props: Props;
+  isCustom: IsCustom;
+}
+
+/** Tag for a Service that can bind a Capability to a Runtime */
+export interface Bind<
+  F extends Runtime,
+  Cap extends Capability,
+  Tag extends string,
+> extends Context.Tag<
+    `${F["type"]}(${Cap["type"]}, ${Tag})`,
+    BindingService<
+      F,
+      Extract<Extract<Cap["resource"], Resource>["parent"], Resource>,
+      F["props"]
+    >
+  > {
+  /** @internal phantom */
+  name: Tag;
+}
+
+export const Binding: {
+  <F extends (resource: any, props?: any) => AnyBinding & { isCustom: true }>(
+    runtime: ReturnType<F>["runtime"],
+    // resource: new () => ReturnType<F>["capability"]["resource"],
+    type: ReturnType<F>["capability"]["type"],
+    tag: ReturnType<F>["tag"],
+  ): F & BindingDeclaration<ReturnType<F>["runtime"], F>;
+  <F extends (resource: any, props?: any) => AnyBinding & { isCustom: false }>(
+    runtime: ReturnType<F>["runtime"],
+    // resource: new () => ReturnType<F>["capability"]["resource"],
+    type: ReturnType<F>["capability"]["type"],
+  ): F & BindingDeclaration<ReturnType<F>["runtime"], F>;
+} = (runtime: any, cap: string, tag?: string) => {
+  const Tag = Context.Tag(`${runtime.type}(${cap}, ${tag ?? cap})`)();
+  return Object.assign(
+    (resource: any, props?: any) =>
+      ({
+        runtime,
+        capability: {
+          type: cap,
+          resource,
+          constraint: undefined!,
+          sid: `${cap}${resource.id}`.replace(/[^a-zA-Z0-9]/g, ""),
+          label: `${cap}(${resource.id})`,
+        } satisfies ICapability,
+        props,
+        isCustom: false,
+        tag: tag ?? cap,
+        // @ts-expect-error - we smuggle this property because it interacts poorly with inference
+        Tag,
+      }) satisfies Binding<any, any, any, string, false>,
+    {
+      provider: {
+        effect: (eff) => Layer.effect(Tag, eff),
+        succeed: (service) => Layer.succeed(Tag, service),
+      },
+    } satisfies BindingDeclaration<Runtime, any>,
+  );
+};
+
+export interface BindingDeclaration<
+  Run extends Runtime,
+  F extends (target: any, props?: any) => AnyBinding<Run>,
+  Tag extends string = ReturnType<F>["tag"],
+  Cap extends Capability = ReturnType<F>["capability"],
+> {
+  provider: {
+    effect<Err, Req>(
+      eff: Effect<
+        BindingService<Run, Parameters<F>[0], Parameters<F>[1]>,
+        Err,
+        Req
+      >,
+    ): Layer.Layer<Bind<Run, Cap, Tag>, Err, Req>;
+    succeed(
+      service: BindingService<Run, Parameters<F>[0], Parameters<F>[1]>,
+    ): Layer.Layer<Bind<Run, Cap, Tag>>;
+  };
+}
+
+export type BindingService<
+  Target extends Runtime = any,
+  Source extends Resource = Resource,
+  Props = any,
+  AttachReq = never,
+  DetachReq = never,
+> = {
+  attach: (props: {
+    source: {
+      id: string;
+      attr: Source["attr"];
+      props: Source["props"];
+    };
+    props: Props;
+    target: {
+      id: string;
+      props: Target["props"];
+      attr: Target["attr"];
+    };
+  }) =>
+    | Effect<Partial<Target["binding"]> | void, never, AttachReq>
+    | Partial<Target["binding"]>;
+  detach?: (
+    resource: {
+      id: string;
+      attr: Source["attr"];
+      props: Source["props"];
+    },
+    from: Target["binding"],
+  ) => Effect<void, never, DetachReq> | void;
+};

package/src/capability.ts

@@ -0,0 +1,19 @@
+export interface ICapability<
+  Type extends string = string,
+  Resource = unknown,
+  Constraint = unknown,
+> {
+  type: Type;
+  resource: Resource;
+  constraint: Constraint;
+  sid: string;
+  label: string;
+}
+
+export interface Capability<
+  Type extends string = string,
+  Resource = unknown,
+  Constraint = unknown,
+> extends ICapability<Type, Resource, Constraint> {
+  new (): {};
+}

package/src/destroy.ts

@@ -0,0 +1,4 @@
+import type * as Effect from "effect/Effect";
+import type { App } from "./app.ts";
+
+export declare const destroy: () => Effect.Effect<void, never, App>;

package/src/dot-alchemy.ts

@@ -0,0 +1,17 @@
+import { FileSystem } from "@effect/platform";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import path from "node:path";
+
+export class DotAlchemy extends Context.Tag(".alchemy")<DotAlchemy, string>() {}
+
+export const dotAlchemy = Layer.effect(
+  DotAlchemy,
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const dir = path.join(process.cwd(), ".alchemy");
+    yield* fs.makeDirectory(dir, { recursive: true });
+    return dir;
+  }),
+);

package/src/env.ts

@@ -0,0 +1,51 @@
+export const toEnvKey = <const ID extends string, const Suffix extends string>(
+  id: ID,
+  suffix: Suffix,
+) => `${replace(toUpper(id))}_${replace(toUpper(suffix))}` as const;
+
+const toUpper = <const S extends string>(str: S) =>
+  str.toUpperCase() as string extends S ? S : Uppercase<S>;
+
+const replace = <const S extends string>(str: S) =>
+  str.replace(/-/g, "_") as Replace<S>;
+
+type Replace<S extends string, Accum extends string = ""> = string extends S
+  ? S
+  : S extends ""
+    ? Accum
+    : S extends `${infer S}${infer Rest}`
+      ? S extends "-"
+        ? Replace<Rest, `${Accum}_`>
+        : Replace<Rest, `${Accum}${S}`>
+      : Accum;
+
+function _test_both_literals() {
+  const key = toEnvKey("my-id", "my-suffix");
+  const _: typeof key = "MY_ID_MY_SUFFIX";
+  // @ts-expect-error
+  const _err: typeof key = "MY_ID_MY_SUFFIX2";
+}
+function _test_replace_wide_string() {
+  const ___ = toUpper(undefined! as string);
+  const id: string = "my-id";
+  const key = toEnvKey(id, "my-suffix");
+  const _: typeof key = "MY_ID_MY_SUFFIX";
+  const _2: typeof key = `${id}_MY_SUFFIX` as const;
+  // @ts-expect-error
+  const _err: typeof key = "MY_ID_MY_SUFFIX2";
+  // @ts-expect-error
+  const _err2: typeof key = `${id}_MY_SUFFIX2` as const;
+}
+
+function _test_replace_wide_suffix() {
+  const ___ = toUpper(undefined! as string);
+  const id = "my-id";
+  const suffix = "my-suffix" as string;
+  const key = toEnvKey(id, suffix);
+  const _: typeof key = "MY_ID_MY_SUFFIX";
+  const _2: typeof key = `MY_ID_${suffix}` as const;
+  // @ts-expect-error
+  const _err: typeof key = "WRONG_PREFIX_MY_SUFFIX";
+  // @ts-expect-error
+  const _err2: typeof key = `WRONG_PREFIX_${suffix}`;
+}

package/src/event.ts

@@ -0,0 +1,27 @@
+export type ApplyStatus =
+  | "pending"
+  | "creating"
+  | "created"
+  | "updating"
+  | "updated"
+  | "deleting"
+  | "deleted"
+  | "success"
+  | "fail";
+
+export type ApplyEvent = AnnotateEvent | StatusChangeEvent;
+
+export interface AnnotateEvent {
+  kind: "annotate";
+  id: string;
+  message: string;
+}
+
+export interface StatusChangeEvent {
+  kind: "status-change";
+  id: string; // resource id (e.g. "messages", "api")
+  type: string; // resource type (e.g. "AWS::Lambda::Function", "Cloudflare::Worker")
+  status: ApplyStatus;
+  message?: string; // optional details
+  bindingId?: string; // if this event is for a binding
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from "./app.ts";
+export * from "./apply.ts";
+export * from "./approve.ts";
+export * from "./binding.ts";
+export * from "./capability.ts";
+export * from "./destroy.ts";
+export * from "./dot-alchemy.ts";
+export * from "./env.ts";
+export * from "./event.ts";
+export * from "./phase.ts";
+export * from "./plan.ts";
+export * from "./policy.ts";
+export * from "./provider.ts";
+export * from "./resource.ts";
+export * from "./runtime.ts";
+export * from "./service.ts";
+export * as State from "./state.ts";

package/src/phase.ts

@@ -0,0 +1 @@
+export type Phase = "update" | "destroy";

package/src/physical-name.ts

@@ -0,0 +1,7 @@
+import * as Effect from "effect/Effect";
+import { App } from "./app.ts";
+
+export const physicalName = Effect.fn(function* (id: string) {
+  const app = yield* App;
+  return `${app.name}-${id}-${app.stage}`;
+});