alchemy-effect 0.2.0 → 0.4.0

package/src/policy.ts

@@ -3,7 +3,7 @@ import * as Effect from "effect/Effect";
 import * as S from "effect/Schema";
 import { type AnyBinding, type Bind } from "./binding.ts";
 import type { Capability } from "./capability.ts";
-import type { Runtime } from "./runtime.ts";
+import type { IRuntime, Runtime } from "./runtime.ts";
 
 /**
  * A Policy binds a set of Capbilities (e.g SQS.SendMessage, SQS.Consume, etc.) to a
@@ -15,10 +15,11 @@ import type { Runtime } from "./runtime.ts";
  * A Policy is invariant over the set of Capabilities to ensure least-privilege.
  */
 export interface Policy<
-  F extends Runtime,
+  F extends IRuntime,
   in out Capabilities,
   Tags = unknown,
 > {
+  readonly kind: "alchemy/Policy";
   readonly runtime: F;
   readonly tags: Tags[];
   readonly capabilities: Capabilities[];
@@ -34,9 +35,6 @@ export interface Policy<
   >;
 }
 
-export type $<T> = Instance<T>;
-export const $ = Policy;
-
 type BindingTags<B extends AnyBinding> = B extends any
   ? Bind<B["runtime"], B["capability"], Extract<B["tag"], string>>
   : never;

package/src/provider.ts

@@ -1,74 +1,113 @@
 import * as Context from "effect/Context";
-import type * as Effect from "effect/Effect";
-import type { ScopedPlanStatusSession } from "./apply.ts";
+import * as Effect from "effect/Effect";
+import type { ScopedPlanStatusSession } from "./cli/service.ts";
+import type { Diff } from "./diff.ts";
+import type { Input } from "./input.ts";
 import type { Resource } from "./resource.ts";
 import type { Runtime } from "./runtime.ts";
+import type { Service } from "./service.ts";
 
-export type Provider<R extends Resource> = Context.TagClass<
-  Provider<R>,
-  R["type"],
-  ProviderService<R>
->;
+export interface Provider<R extends Resource | Service>
+  extends Context.TagClass<
+    Provider<R>,
+    R["type"],
+    ProviderService<any>
+    // TODO(sam): we are using any here because the R["type"] is enough and gaining access to the sub type (e.g. SQS.Queue)
+    // is currently not possible in the current approach
 
-export type Diff =
-  | {
-      action: "update" | "noop";
-      deleteFirst?: undefined;
-    }
-  | {
-      action: "replace";
-      deleteFirst?: boolean;
-    };
+    // preferred:
+    // ProviderService<R>
+  > {}
 
 type BindingData<Res extends Resource> = [Res] extends [Runtime]
   ? Res["binding"][]
   : any[];
 
-export interface ProviderService<Res extends Resource = Resource> {
+type Props<Res extends Resource> = Input.ResolveOpaque<Res["props"]>;
+
+export interface ProviderService<
+  Res extends Resource = Resource,
+  ReadReq = never,
+  DiffReq = never,
+  PrecreateReq = never,
+  CreateReq = never,
+  UpdateReq = never,
+  DeleteReq = never,
+> {
+  /**
+   * The version of the provider.
+   *
+   * @default 0
+   */
+  version?: number;
   // tail();
   // watch();
   // replace(): Effect.Effect<void, never, never>;
-
   // different interface that is persistent, watching, reloads
   // run?() {}
   read?(input: {
     id: string;
-    olds: Res["props"] | undefined;
+    instanceId: string;
+    olds: Props<Res> | undefined;
     // what is the ARN?
     output: Res["attr"] | undefined; // current state -> synced state
     session: ScopedPlanStatusSession;
     bindings: BindingData<Res>;
-  }): Effect.Effect<Res["attr"] | undefined, any, never>;
+  }): Effect.Effect<Res["attr"] | undefined, any, ReadReq>;
+  /**
+   * Properties that are always stable across any update.
+   */
+  stables?: Extract<keyof Res["attr"], string>[];
   diff?(input: {
     id: string;
-    olds: Res["props"];
+    olds: Props<Res>;
+    instanceId: string;
+    // Note: we do not resolve (Props<Res>) here because diff runs during plan
+    // -> we need a way for the diff handlers to work with Outputs
     news: Res["props"];
     output: Res["attr"];
-  }): Effect.Effect<Diff | void, never, never>;
+  }): Effect.Effect<Diff | void, never, DiffReq>;
   precreate?(input: {
     id: string;
-    news: Res["props"];
+    news: Props<Res>;
+    instanceId: string;
     session: ScopedPlanStatusSession;
-  }): Effect.Effect<Res["attr"], any, never>;
+  }): Effect.Effect<Res["attr"], any, PrecreateReq>;
   create(input: {
     id: string;
-    news: Res["props"];
+    instanceId: string;
+    news: Props<Res>;
     session: ScopedPlanStatusSession;
     bindings: BindingData<Res>;
-  }): Effect.Effect<Res["attr"], any, never>;
+  }): Effect.Effect<Res["attr"], any, CreateReq>;
   update(input: {
     id: string;
-    news: Res["props"];
-    olds: Res["props"];
+    instanceId: string;
+    news: Props<Res>;
+    olds: Props<Res>;
     output: Res["attr"];
     session: ScopedPlanStatusSession;
     bindings: BindingData<Res>;
-  }): Effect.Effect<Res["attr"], any, never>;
+  }): Effect.Effect<Res["attr"], any, UpdateReq>;
   delete(input: {
     id: string;
-    olds: Res["props"];
+    instanceId: string;
+    olds: Props<Res>;
     output: Res["attr"];
     session: ScopedPlanStatusSession;
     bindings: BindingData<Res>;
-  }): Effect.Effect<void, any, never>;
+  }): Effect.Effect<void, any, DeleteReq>;
 }
+
+export const getProviderByType = Effect.fnUntraced(function* (
+  resourceType: string,
+) {
+  const context = yield* Effect.context<never>();
+  const provider: ProviderService = context.unsafeMap.get(resourceType);
+  if (!provider) {
+    return yield* Effect.die(
+      new Error(`Provider not found for ${resourceType}`),
+    );
+  }
+  return provider;
+});

package/src/ref.ts

@@ -0,0 +1,48 @@
+import type { Resource, AnyResource } from "./resource.ts";
+import * as Output from "./output.ts";
+
+// special runtime-only symbol for probing the Ref proxy for its metadata
+const RefMetadata = Symbol.for("alchemy/RefMetadata");
+
+export const isRef = (s: any): s is Ref<any> =>
+  s && s[RefMetadata] !== undefined;
+
+export const getRefMetadata = <R extends Resource<string, string, any, any>>(
+  ref: Ref<R>,
+): RefMetadata<R> => (ref as any)[RefMetadata];
+
+export interface Ref<
+  R extends Resource<string, string, any, any> = AnyResource,
+> {
+  /** @internal phantom */
+  Ref: R;
+}
+
+export interface RefMetadata<R extends Resource<string, string, any, any>> {
+  stack?: string;
+  stage?: string;
+  resourceId: R["id"];
+}
+
+export const ref = <R extends Resource<string, string, any, any>>({
+  stack,
+  resourceId,
+  stage,
+}: RefMetadata<R>): Ref<R> => {
+  const ref = new Proxy(
+    {},
+    {
+      get: (_, prop) => {
+        if (prop === RefMetadata) {
+          return {
+            stack,
+            stage,
+            resourceId,
+          };
+        }
+        return (Output.of(ref) as any)[prop];
+      },
+    },
+  ) as Ref<R>;
+  return ref;
+};

package/src/resource.ts

@@ -9,28 +9,87 @@ export const isResource = (r: any): r is Resource => {
   );
 };
 
-export interface Resource<
+export type AnyResource = Resource<string, string, any, any>;
+
+export interface IResource<
   Type extends string = string,
   ID extends string = string,
   Props = unknown,
   Attrs = unknown,
+  Base = unknown,
 > {
   id: ID;
   type: Type;
+  Props: unknown;
   props: Props;
+  base: Base;
+  /** @internal phantom */
   attr: Attrs;
-  parent: unknown;
-  // oxlint-disable-next-line no-misused-new
-  new (): Resource<Type, ID, Props, Attrs>;
 }
 
-export interface ResourceTags<R extends Resource> {
+export interface Resource<
+  Type extends string = string,
+  ID extends string = string,
+  Props = unknown,
+  Attrs = unknown,
+  Base = unknown,
+> extends IResource<Type, ID, Props, Attrs, Base> {
+  new (): Resource<Type, ID, Props, Attrs, Base>;
+}
+
+export interface ResourceTags<R extends Resource<string, string, any, any>> {
   of<S extends ProviderService<R>>(service: S): S;
-  tag: Context.TagClass<Provider<R>, R["type"], ProviderService<R>>;
-  effect<Err, Req>(
-    eff: Effect<ProviderService<R>, Err, Req>,
-  ): Layer.Layer<Provider<R>, Err, Req>;
-  succeed(service: ProviderService<R>): Layer.Layer<Provider<R>>;
+  tag: Provider<R>;
+  effect<
+    Err,
+    Req,
+    ReadReq = never,
+    DiffReq = never,
+    PrecreateReq = never,
+    CreateReq = never,
+    UpdateReq = never,
+    DeleteReq = never,
+  >(
+    eff: Effect<
+      ProviderService<
+        R,
+        ReadReq,
+        DiffReq,
+        PrecreateReq,
+        CreateReq,
+        UpdateReq,
+        DeleteReq
+      >,
+      Err,
+      Req
+    >,
+  ): Layer.Layer<
+    Provider<R>,
+    Err,
+    Req | ReadReq | DiffReq | PrecreateReq | CreateReq | UpdateReq | DeleteReq
+  >;
+  succeed<
+    ReadReq = never,
+    DiffReq = never,
+    PrecreateReq = never,
+    CreateReq = never,
+    UpdateReq = never,
+    DeleteReq = never,
+  >(
+    service: ProviderService<
+      R,
+      ReadReq,
+      DiffReq,
+      PrecreateReq,
+      CreateReq,
+      UpdateReq,
+      DeleteReq
+    >,
+  ): Layer.Layer<
+    Provider<R>,
+    never,
+    ReadReq | DiffReq | PrecreateReq | CreateReq | UpdateReq | DeleteReq
+  >;
 }
 
 export const Resource = <Ctor extends (id: string, props: any) => Resource>(
@@ -56,6 +115,7 @@ export const Resource = <Ctor extends (id: string, props: any) => Resource>(
       };
     } as unknown as Ctor & {
       type: ReturnType<Ctor>["type"];
+      parent: ReturnType<Ctor>;
       new (): ReturnType<Ctor> & {
         parent: ReturnType<Ctor>;
       };

package/src/runtime.ts

@@ -5,7 +5,7 @@ import * as Layer from "effect/Layer";
 import type { Capability } from "./capability.ts";
 import type { Policy } from "./policy.ts";
 import type { ProviderService } from "./provider.ts";
-import type { Resource, ResourceTags } from "./resource.ts";
+import type { IResource, Resource, ResourceTags } from "./resource.ts";
 import type { IService, Service } from "./service.ts";
 
 export type RuntimeHandler<
@@ -37,21 +37,30 @@ export declare namespace Runtime {
 
 export type AnyRuntime = Runtime<string>;
 
-export interface RuntimeProps<Run extends Runtime, Req> {
+export interface RuntimeProps<Run extends IRuntime, Req> {
   bindings: Policy<Run, Extract<Req, Capability>, unknown>;
 }
 
-export interface Runtime<
+export interface IRuntime<
   Type extends string = string,
   Handler = unknown,
   Props = unknown,
-> extends Resource<Type, string, Props, unknown> {
+> extends IResource<Type, string, Props> {
   type: Type;
   props: Props;
   handler: Handler;
   binding: unknown;
   /** @internal phantom */
   capability: unknown;
+}
+
+export interface Runtime<
+  Type extends string = string,
+  Handler = unknown,
+  Props = unknown,
+> extends IRuntime<Type, Handler, Props>,
+    Resource<Type, string, Props> {
+  provider: ResourceTags<this>;
   <
     const ID extends string,
     Inputs extends any[],
@@ -75,9 +84,7 @@ export interface Runtime<
 
 export const Runtime =
   <const Type extends string>(type: Type) =>
-  <Self extends Runtime>(): Self & {
-    provider: ResourceTags<Self>;
-  } => {
+  <Self extends Runtime>(): Self => {
     const Tag = Context.Tag(type)();
     const provider = {
       tag: Tag,
@@ -122,7 +129,7 @@ export const Runtime =
                 parent: self,
                 // @ts-expect-error
                 provider,
-              } satisfies IService<string, Self, any, any>,
+              } satisfies IService<string, Self, any, any, Self>,
             );
         }
       },

package/src/service.ts

@@ -1,15 +1,16 @@
 import type { Effect } from "effect/Effect";
 import type { Capability } from "./capability.ts";
-import type { Resource } from "./resource.ts";
-import type { Runtime, RuntimeHandler, RuntimeProps } from "./runtime.ts";
+import type { IResource } from "./resource.ts";
+import type { IRuntime, RuntimeHandler, RuntimeProps } from "./runtime.ts";
 
 export interface IService<
   ID extends string = string,
-  F extends Runtime = Runtime,
+  F extends IRuntime = IRuntime,
   Handler extends RuntimeHandler = RuntimeHandler,
   Props extends RuntimeProps<F, any> = RuntimeProps<F, any>,
   Attr = (F & { props: Props })["attr"],
-> extends Resource<F["type"], ID, Props, Attr> {
+  Base = unknown,
+> extends IResource<F["type"], ID, Props, Attr, F> {
   kind: "Service";
   type: F["type"];
   id: ID;
@@ -39,16 +40,19 @@ export interface IService<
   attr: Attr;
   /** @internal phantom type of this resource's parent */
   parent: unknown;
+  new (): Service<ID, F, Handler, Props, Attr, Base>;
 }
 
+export interface AnyService extends IService {}
+
 export interface Service<
   ID extends string = string,
-  F extends Runtime = Runtime,
+  F extends IRuntime = IRuntime,
   Handler extends RuntimeHandler = RuntimeHandler,
   Props extends RuntimeProps<F, any> = RuntimeProps<F, any>,
   Attr = (F & { props: Props })["attr"],
-> extends IService<ID, F, Handler, Props, Attr>,
-    Resource<F["type"], ID, Props, Attr> {}
+  Base = unknown,
+> extends IService<ID, F, Handler, Props, Attr, Base> {}
 
 export const isService = (resource: any): resource is IService => {
   return resource && resource.kind === "Service";

package/src/stack.ts

@@ -0,0 +1,116 @@
+import type { HttpClient } from "@effect/platform/HttpClient";
+import { FileSystem } from "@effect/platform/FileSystem";
+import { Path } from "@effect/platform/Path";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as App from "./app.ts";
+import { type AppliedPlan } from "./apply.ts";
+import { DotAlchemy } from "./dot-alchemy.ts";
+import type { DerivePlan, Providers, TraverseResources } from "./plan.ts";
+import type { Instance } from "./policy.ts";
+import type { AnyResource } from "./resource.ts";
+import type { AnyService } from "./service.ts";
+import { type StageConfig, type Stages } from "./stage.ts";
+import * as State from "./state.ts";
+import type { Ref } from "./ref.ts";
+import type { CLI } from "./cli/service.ts";
+
+export const defineStack = <
+  const Name extends string,
+  Resources extends (AnyResource | AnyService)[],
+  Req = never,
+  Err = never,
+>(
+  stack: StackConfig<Name, Resources, Req, Err>,
+): Stack<Name, Instance<Resources[number]>, Req, Err> => stack as any;
+
+export type StackConfig<
+  Name extends string,
+  Resources extends (AnyResource | AnyService)[] = (AnyResource | AnyService)[],
+  StagesReq = never,
+  StagesErr = never,
+  TapReq = never,
+  TapErr = never,
+> = {
+  name: Name;
+  stages: Stages<StagesReq, StagesErr>;
+  resources: Resources;
+  providers: Layer.Layer<
+    Providers<Instance<Resources[number]>>,
+    any,
+    App.App | FileSystem | Path | DotAlchemy | HttpClient
+  >;
+  state?: Layer.Layer<State.State>;
+  tap?: (
+    output: StackOutput<Instance<Resources[number]>>,
+  ) => Effect.Effect<any, TapErr, TapReq>;
+} & (Exclude<NoInfer<StagesReq | TapReq>, BuiltInServices> extends never
+  ? {
+      layers?: never;
+    }
+  : {
+      layers: Layer.Layer<
+        Exclude<StagesReq | TapReq, BuiltInServices>,
+        never,
+        never
+      >;
+    });
+
+export type StackOutput<Resources extends AnyResource | AnyService> =
+  AppliedPlan<DerivePlan<Resources>>;
+
+export type Stack<
+  Name extends string = string,
+  Resources extends AnyResource | AnyService = any,
+  StagesReq = any,
+  StagesErr = any,
+  TapReq = any,
+  TapErr = any,
+> = {
+  name: Name;
+  stages: Stages<StagesReq, StagesErr>;
+  resources: Resources[];
+  providers: Layer.Layer<Providers<Resources>, any, BuiltInServices>;
+  state?: Layer.Layer<State.State>;
+  cli?: Layer.Layer<CLI>;
+  tap?: (output: StackOutput<Resources>) => Effect.Effect<void, TapErr, TapReq>;
+} & (Exclude<StagesReq | TapReq, BuiltInServices> extends never
+  ? {
+      layers?: never;
+    }
+  : {
+      layers: Layer.Layer<
+        Exclude<StagesReq | TapReq, BuiltInServices>,
+        never,
+        never
+      >;
+    });
+
+export type StackName<S extends Stack> =
+  S extends Stack<infer Name, infer _> ? Name : never;
+
+export type StackResources<S extends Stack> =
+  S extends Stack<infer _, infer Resources> ? Resources : never;
+
+export type BuiltInServices =
+  | App.App
+  | FileSystem
+  | Path
+  | DotAlchemy
+  | HttpClient;
+
+export interface StackRefConfig<S extends Stack> extends StageConfig {
+  stack: S extends Stack<infer Name, any> ? Name : never;
+  stage?: string;
+}
+
+export type StackRef<Resources extends AnyResource | AnyService> = {
+  [Id in keyof AsRecord<Resources>]: Ref<AsRecord<Resources>[Id]>;
+};
+
+type AsRecord<Resources extends AnyResource | AnyService> = {
+  [Id in TraverseResources<Resources>["id"]]: Extract<
+    TraverseResources<Resources>,
+    { id: Id }
+  >;
+};

package/src/stage.ts

@@ -0,0 +1,85 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import type { StackName, StackRef, Stack, StackResources } from "./stack.ts";
+import { ref } from "./ref.ts";
+
+export interface StageConfig {
+  /**
+   * Whether to retain the stage when destroying the stack.
+   *
+   * @default - true if the current stage starts with "prod"
+   */
+  retain?: boolean;
+
+  /**
+   * Whether to adopt resources that already exist during the created phase.
+   *
+   * @default false
+   */
+  adopt?: boolean;
+}
+
+export class Stage extends Context.Tag("Stage")<Stage, string>() {}
+
+export type Stages<Req = never, Err = never> = {
+  config: (stage: string) => StageConfig | Effect.Effect<StageConfig, Err, Req>;
+  ref<S extends Stack>(name: StackName<S>): StackRefs<S>;
+};
+
+export const defineStages = <Req = never, Err = never>(
+  config: (stage: string) => StageConfig | Effect.Effect<StageConfig, Err, Req>,
+): Stages<Req, Err> => ({
+  config,
+  ref: <S extends Stack>(stack: StackName<NoInfer<S>>): StackRefs<S> => {
+    const proxy = (get: (id: string) => any) =>
+      new Proxy({}, { get: (_, id: string) => get(id) });
+    const proxyStage = (stage: string) =>
+      proxy((resourceId: string) =>
+        ref({
+          stack,
+          stage,
+          resourceId,
+        }),
+      );
+    return proxy((stage) =>
+      stage == "as"
+        ? (builders: StackRefBuilders) =>
+            proxy((stage: string) => {
+              if (stage in builders) {
+                const builder = builders[stage as keyof typeof builders];
+                return typeof builder === "string"
+                  ? proxyStage(stage)
+                  : (...args: any[]) => proxyStage(builder(...args));
+              }
+              return proxyStage(stage);
+            })
+        : proxy((resourceId: string) =>
+            ref({
+              stack,
+              stage,
+              resourceId,
+            }),
+          ),
+    ) as StackRefs<S>;
+  },
+});
+
+export interface StackRefBuilders {
+  [stage: string]: string | ((...args: any[]) => string);
+}
+
+export type StackRefs<S extends Stack> = {
+  [stage in string]: StackRef<StackResources<S>>;
+} & {
+  as<Builders extends StackRefBuilders>(
+    stages?: Builders,
+  ): {
+    [stage in Exclude<string, keyof Builders>]: StackRef<StackResources<S>>;
+  } & {
+    [builder in keyof Builders]: Builders[builder] extends string
+      ? StackRef<StackResources<S>>
+      : Builders[builder] extends (...args: infer Args) => any
+        ? (...args: Args) => StackRef<StackResources<S>>
+        : never;
+  };
+};