feat(core): Inputs and Outputs (#19)

Author: sam-goodwin

.gitignore

@@ -29,4 +29,6 @@ smoke
 *.tgz
 *.js
 *.d.ts
-*.map
+*.map
+
+.attest

.vscode/settings.json

@@ -1,7 +1,9 @@
 {
-  "typescript.experimental.useTsgo": false,
+  "typescript.experimental.useTsgo": true,
   "typescript.tsdk": "node_modules/typescript/lib",
   "typescript.enablePromptUseWorkspaceTsdk": true,
+  "typescript.preferences.importModuleSpecifier": "relative",
+  "typescript.preferences.importModuleSpecifierEnding": "js",
   "oxc.fmt.experimental": true, 
   "oxc.enable": true,
   "editor.defaultFormatter": "oxc.oxc-vscode",

AGENTS.md

@@ -15,4 +15,8 @@ Conduct each engagement with the user as follows:
   - Creating a Client for an AWS scope (see [aws/lambda/client.ts](alchemy-effect/src/aws/lambda/client.ts) and [aws/sqs/client.ts](alchemy-effect/src/aws/sqs/client.ts))
   - Compiling the AWS.live layer (see [aws/index.ts](alchemy-effect/src/aws/index.ts))
   - Using resources (see [example/src/api.ts](example/src/api.ts) and [example/src/consumer.ts](example/src/consumer.ts))
-3. When implementing a Resource Provider, make sure to read the [itty-aws](./alchemy-effect/node_modules/itty-aws/dist/services/*/types.d.ts)  type defnitions for that service and come up with a plan for which errors to retry, which to consider fatal, and design the overall create, update, delete flow for each of the resource lifecycle handlers. We are using effect, so we gain the benefit of type-safe errors, delcarative retry behavior (declarative flow control).
+3. When implementing a Resource Provider, make sure to read the [itty-aws](./alchemy-effect/node_modules/itty-aws/dist/services/*/types.d.ts)  type defnitions for that service and come up with a plan for which errors to retry, which to consider fatal, and design the overall create, update, delete flow for each of the resource lifecycle handlers. We are using effect, so we gain the benefit of type-safe errors, delcarative retry behavior (declarative flow control).
+
+Restrictions:
+1. Never use `Effect.catchAll`, always use `Effect.catchTag` or `Effect.catchTags`
+1. Always use `bun` (never npm, pnpm, yarn, etc.)

alchemy-effect/package.json

@@ -23,14 +23,21 @@
     "build": "bun bundle && bun pm pack",
     "bundle": "tsdown",
     "bundle:watch": "tsdown --watch",
-    "publish:npm": "cp ../README.md . && bun publish && rm README.md"
+    "publish:npm": "cp ../README.md . && bun publish && rm README.md",
+    "test": "vitest run",
+    "test:benchmark": "tsx --tsconfig tsconfig.test.json test/types.benchmark.ts"
   },
   "exports": {
     ".": {
       "bun": "./src/index.ts",
       "import": "./lib/index.js",
       "types": "./src/index.d.ts"
     },
+    "./Output": {
+      "bun": "./src/output.ts",
+      "import": "./lib/output.js",
+      "types": "./lib/output.d.ts"
+    },
     "./aws": {
       "bun": "./src/aws/index.ts",
       "import": "./lib/aws/index.js",
@@ -128,6 +135,7 @@
     "@cloudflare/workers-types": "catalog:",
     "@effect/platform": "catalog:",
     "@effect/platform-node": "catalog:",
+    "@effect/typeclass": "catalog:",
     "@types/aws-lambda": "catalog:",
     "@types/bun": "catalog:",
     "@types/node": "catalog:",
@@ -137,7 +145,9 @@
     "react": "^19.2.0",
     "react-devtools-core": "^7.0.1",
     "tsconfig-paths": "^4.2.0",
-    "tsdown": "^0.15.4"
+    "tsdown": "^0.15.4",
+    "tsx": "^4.20.6",
+    "typescript": "catalog:"
   },
   "peerDependencies": {
     "@effect/platform": "*",

alchemy-effect/src/$.ts

@@ -0,0 +1,14 @@
+import { type Instance, Policy } from "./policy.ts";
+import { isResource } from "./resource.ts";
+import * as Output from "./output.ts";
+
+export type $ = typeof Policy & typeof Output.interpolate & typeof Output.of;
+export const $ = ((...args: any[]) =>
+  Array.isArray(args[0])
+    ? Output.interpolate(
+        args[0] as unknown as TemplateStringsArray,
+        ...args.slice(1),
+      )
+    : isResource(args[0])
+      ? Output.of(args[0])
+      : Policy(...args)) as $;

alchemy-effect/src/apply.ts

@@ -5,17 +5,22 @@ 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 * as Output from "./output.ts";
 import {
   plan,
   type BindNode,
   type Create,
   type CRUD,
   type Delete,
+  type IPlan,
   type Plan,
   type Update,
+  type DerivePlan,
+  type BindingTags,
 } from "./plan.ts";
-import type { Resource } from "./resource.ts";
-import type { Service } from "./service.ts";
+import type { Instance } from "./policy.ts";
+import type { AnyResource, Resource } from "./resource.ts";
+import type { AnyService, Service } from "./service.ts";
 import { State } from "./state.ts";
 
 export interface PlanStatusSession {
@@ -30,40 +35,45 @@ export interface ScopedPlanStatusSession extends PlanStatusSession {
 export class PlanStatusReporter extends Context.Tag("PlanStatusReporter")<
   PlanStatusReporter,
   {
-    start(plan: Plan): Effect.Effect<PlanStatusSession, never>;
+    start(plan: IPlan): Effect.Effect<PlanStatusSession, never>;
   }
 >() {}
 
-export const apply: typeof applyPlan &
-  typeof applyResources &
-  typeof applyResourcesPhase = (...args: any[]): any =>
-  Effect.isEffect(args[0])
-    ? applyPlan(args[0] as any)
-    : args.length === 1 && "phase" in args[0]
-      ? applyResourcesPhase(args[0])
-      : applyResources(...args);
-
-export const applyResourcesPhase = <
-  const Phase extends "update" | "destroy",
-  const Resources extends (Service | Resource)[],
->(props: {
-  resources: Resources;
-  phase: Phase;
-}) => applyPlan(plan(props));
-
-export const applyResources = <const Resources extends (Service | Resource)[]>(
+export type ApplyEffect<
+  P extends IPlan,
+  Err = never,
+  Req = never,
+> = Effect.Effect<
+  {
+    [k in keyof AppliedPlan<P>]: AppliedPlan<P>[k];
+  },
+  Err | PlanRejected,
+  Req
+>;
+
+export type AppliedPlan<P extends IPlan> = {
+  [id in keyof P["resources"]]: P["resources"][id] extends
+    | Delete<Resource>
+    | undefined
+    | never
+    ? never
+    : Simplify<P["resources"][id]["resource"]["attr"]>;
+};
+
+export const apply = <
+  const Resources extends (AnyService | AnyResource)[] = never,
+>(
   ...resources: Resources
-) =>
-  applyPlan(
-    plan({
-      phase: "update",
-      resources,
-    }),
-  );
-
-export const applyPlan = <P extends Plan, Err, Req>(
+): ApplyEffect<
+  DerivePlan<Instance<Resources[number]>>,
+  never,
+  State | BindingTags<Instance<Resources[number]>>
+  // TODO(sam): don't cast to any
+> => applyPlan(plan(...resources)) as any;
+
+export const applyPlan = <P extends IPlan, Err = never, Req = never>(
   plan: Effect.Effect<P, Err, Req>,
-) =>
+): ApplyEffect<P, Err, Req> =>
   plan.pipe(
     Effect.flatMap((plan) =>
       Effect.gen(function* () {
@@ -90,6 +100,18 @@ export const applyPlan = <P extends Plan, Err, Req>(
         ): Effect.Effect<T, Err, Req> =>
           Effect.isEffect(effect) ? effect : Effect.succeed(effect);
 
+        const resolveUpstream = Effect.fn(function* (resourceId: string) {
+          const upstreamNode = plan.resources[resourceId];
+          const upstreamAttr = upstreamNode
+            ? yield* apply(upstreamNode)
+            : yield* Effect.dieMessage(`Resource ${resourceId} not found`);
+          return {
+            resourceId,
+            upstreamAttr,
+            upstreamNode,
+          };
+        });
+
         const resolveBindingUpstream = Effect.fn(function* ({
           node,
           resource,
@@ -104,10 +126,8 @@ export const applyPlan = <P extends Plan, Err, Req>(
           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 { upstreamAttr, upstreamNode } =
+            yield* resolveUpstream(resourceId);
 
           return {
             resourceId,
@@ -221,23 +241,21 @@ export const applyPlan = <P extends Plan, Err, Req>(
           node,
         ) =>
           Effect.gen(function* () {
-            const checkpoint = <Out, Err>(
-              effect: Effect.Effect<Out, Err, never>,
-            ) => effect.pipe(Effect.flatMap((output) => saveState({ output })));
-
             const saveState = <Output>({
               output,
               bindings = node.bindings,
+              news,
             }: {
               output: Output;
               bindings?: BindNode[];
+              news: any;
             }) =>
               state
                 .set(node.resource.id, {
                   id: node.resource.id,
                   type: node.resource.type,
                   status: node.action === "create" ? "created" : "updated",
-                  props: node.resource.props,
+                  props: news,
                   output,
                   bindings,
                 })
@@ -271,18 +289,33 @@ export const applyPlan = <P extends Plan, Err, Req>(
                   attr,
                   phase,
                 }: {
-                  node: Create<Resource> | Update<Resource>;
+                  node: Create | Update;
                   attr: any;
                   phase: "create" | "update";
                 }) {
+                  const upstream = Object.fromEntries(
+                    yield* Effect.all(
+                      Object.entries(Output.resolveUpstream(node.news)).map(
+                        ([id, resource]) =>
+                          resolveUpstream(id).pipe(
+                            Effect.map(({ upstreamAttr }) => [
+                              id,
+                              upstreamAttr,
+                            ]),
+                          ),
+                      ),
+                    ),
+                  );
+                  const news = yield* Output.evaluate(node.news, upstream);
+
                   yield* report(phase === "create" ? "creating" : "updating");
 
                   let bindingOutputs = yield* attachBindings({
                     resource,
                     bindings: node.bindings,
                     target: {
                       id,
-                      props: node.news,
+                      props: news,
                       attr,
                     },
                   });
@@ -293,7 +326,7 @@ export const applyPlan = <P extends Plan, Err, Req>(
                       : node.provider.update
                   )({
                     id,
-                    news: node.news,
+                    news,
                     bindings: bindingOutputs,
                     session: scopedSession,
                     ...(node.action === "update"
@@ -316,12 +349,13 @@ export const applyPlan = <P extends Plan, Err, Req>(
                     bindingOutputs,
                     target: {
                       id,
-                      props: node.news,
+                      props: news,
                       attr,
                     },
                   });
 
                   yield* saveState({
+                    news,
                     output,
                     bindings: node.bindings.map((binding, i) => ({
                       ...binding,
@@ -364,11 +398,7 @@ export const applyPlan = <P extends Plan, Err, Req>(
                   yield* Effect.all(
                     node.downstream.map((dep) =>
                       dep in plan.resources
-                        ? apply(
-                            plan.resources[
-                              dep
-                            ] as P["resources"][keyof P["resources"]],
-                          )
+                        ? apply(plan.resources[dep] as any)
                         : Effect.void,
                     ),
                   );
@@ -399,29 +429,30 @@ export const applyPlan = <P extends Plan, Err, Req>(
                   });
                   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* attachBindings({
-                            resource,
-                            bindings: node.bindings,
-                            target: {
-                              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")),
-                        )
-                    );
+
+                    // TODO(sam): delete and create will conflict here, we need to extend the state store for replace
+                    return yield* node.provider
+                      .create({
+                        id,
+                        news: node.news,
+                        // TODO(sam): these need to only include attach actions
+                        bindings: yield* attachBindings({
+                          resource,
+                          bindings: node.bindings,
+                          target: {
+                            id,
+                            // TODO(sam): resolve the news
+                            props: node.news,
+                            attr: node.attributes,
+                          },
+                        }),
+                        session: scopedSession,
+                      })
+                      .pipe(
+                        Effect.tap((output) =>
+                          saveState({ news: node.news, output }),
+                        ),
+                      );
                   });
                   if (!node.deleteFirst) {
                     yield* destroy;
@@ -457,20 +488,4 @@ export const applyPlan = <P extends Plan, Err, Req>(
         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
-  >;
+  ) as ApplyEffect<P>;