alchemy-effect 0.1.0 → 0.3.0

package/src/policy.ts

@@ -1,8 +1,9 @@
 import * as Context from "effect/Context";
 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
@@ -14,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[];
@@ -26,12 +28,13 @@ export interface Policy<
   /** Add more Capabilities to a Policy */
   and<B extends AnyBinding[]>(
     ...bindings: B
-  ): Policy<F, B[number]["capability"] | Capabilities, Tags>;
+  ): Policy<
+    F,
+    B[number]["capability"] | Capabilities,
+    BindingTags<B[number]> | Exclude<Tags, unknown>
+  >;
 }
 
-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;
@@ -46,7 +49,7 @@ export function Policy<B extends AnyBinding[]>(
 >;
 export function Policy(...bindings: AnyBinding[]): any {
   return {
-    runtime: bindings[0]["runtime"],
+    runtime: bindings[0]?.["runtime"],
     capabilities: bindings.map((b) => b.capability),
     tags: bindings.map((b) => Context.Tag(b.tag as any)()),
     bindings,
@@ -57,6 +60,54 @@ export function Policy(...bindings: AnyBinding[]): any {
   };
 }
 
+export namespace Policy {
+  export interface AnyOf<in out T> {
+    readonly anyOf: T[];
+  }
+  type Generalize<T> = T extends S.Schema<infer U> ? U : T;
+
+  export const anyOf = <const T>(...anyOf: T[]): AnyOf<Generalize<T>> => ({
+    anyOf: anyOf as Generalize<T>[],
+  });
+
+  export const join = <
+    const Strings extends readonly string[],
+    const Delimiter extends string,
+  >(
+    strings: Strings,
+    delimiter: Delimiter,
+  ) => strings.join(delimiter) as Join<Strings, Delimiter>;
+
+  type ___ = Join<string[], ",">;
+  type Join<
+    T extends readonly string[],
+    Delimiter extends string,
+  > = T extends readonly [infer First extends string]
+    ? First
+    : T extends readonly [
+          infer First extends string,
+          ...infer Rest extends readonly string[],
+        ]
+      ? `${First}${Delimiter}${Join<Rest, Delimiter>}`
+      : T extends string[]
+        ? string
+        : "";
+
+  export type Constraint<T> = Pick<
+    T,
+    {
+      [k in keyof T]: T[k] extends never
+        ? never
+        : T[k] extends AnyOf<never>
+          ? never
+          : k;
+    }[keyof T]
+  >;
+
+  // TODO(sam): one day we might infer policies using a compiler plugin, this is a placeholder
+  export const infer = <T>(): T => undefined!;
+}
+
 /** declare a Policy requiring Capabilities in some context */
 export const declare = <S extends Capability>() =>
   Effect.gen(function* () {}) as Effect.Effect<void, never, S>;

package/src/provider.ts

@@ -1,39 +1,39 @@
 import * as Context from "effect/Context";
 import type * as Effect from "effect/Effect";
-import type { ScopedPlanStatusSession } from "./apply.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";
+import type { ScopedPlanStatusSession } from "./cli/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[];
 
+type Props<Res extends Resource> = Input.ResolveOpaque<Res["props"]>;
+
 export interface ProviderService<Res extends Resource = Resource> {
   // tail();
   // watch();
   // replace(): Effect.Effect<void, never, never>;
-
   // different interface that is persistent, watching, reloads
   // run?() {}
   read?(input: {
     id: string;
-    olds: Res["props"] | undefined;
+    olds: Props<Res> | undefined;
     // what is the ARN?
     output: Res["attr"] | undefined; // current state -> synced state
     session: ScopedPlanStatusSession;
@@ -41,32 +41,34 @@ export interface ProviderService<Res extends Resource = Resource> {
   }): Effect.Effect<Res["attr"] | undefined, any, never>;
   diff?(input: {
     id: string;
-    olds: Res["props"];
+    olds: Props<Res>;
+    // 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, never, never>;
-  stub?(input: {
+  }): Effect.Effect<Diff | void, never, never>;
+  precreate?(input: {
     id: string;
-    news: Res["props"];
+    news: Props<Res>;
     session: ScopedPlanStatusSession;
   }): Effect.Effect<Res["attr"], any, never>;
   create(input: {
     id: string;
-    news: Res["props"];
+    news: Props<Res>;
     session: ScopedPlanStatusSession;
     bindings: BindingData<Res>;
   }): Effect.Effect<Res["attr"], any, never>;
   update(input: {
     id: string;
-    news: Res["props"];
-    olds: Res["props"];
+    news: Props<Res>;
+    olds: Props<Res>;
     output: Res["attr"];
     session: ScopedPlanStatusSession;
     bindings: BindingData<Res>;
   }): Effect.Effect<Res["attr"], any, never>;
   delete(input: {
     id: string;
-    olds: Res["props"];
+    olds: Props<Res>;
     output: Res["attr"];
     session: ScopedPlanStatusSession;
     bindings: BindingData<Res>;

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,24 +9,37 @@ 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>>;
+  tag: Provider<R>;
   effect<Err, Req>(
     eff: Effect<ProviderService<R>, Err, Req>,
   ): Layer.Layer<Provider<R>, Err, Req>;
@@ -37,13 +50,14 @@ export const Resource = <Ctor extends (id: string, props: any) => Resource>(
   type: ReturnType<Ctor>["type"],
 ) => {
   const Tag = Context.Tag(type)();
-  const provider = {
-    tag: Tag,
+  const provider: ResourceTags<ReturnType<Ctor>> = {
+    tag: Tag as any,
     effect: <Err, Req>(
       eff: Effect<ProviderService<ReturnType<Ctor>>, Err, Req>,
     ) => Layer.effect(Tag, eff),
     succeed: (service: ProviderService<ReturnType<Ctor>>) =>
       Layer.succeed(Tag, service),
+    of: (service) => service,
   };
   return Object.assign(
     function (id: string, props: any) {
@@ -55,6 +69,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> {
-  bindings: Policy<Run, Extract<Req, Capability>>;
+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/schema.ts

@@ -0,0 +1,102 @@
+import * as S from "effect/Schema";
+import type { AST } from "effect/SchemaAST";
+
+const Description = Symbol.for("effect/annotation/Description");
+
+export const isTag = <T extends S.Schema<any>>(tag: T["ast"]["_tag"]) =>
+  ((schema) =>
+    S.isSchema(schema)
+      ? S.encodedSchema(schema).ast._tag === tag
+      : schema._tag === tag) as {
+    (schema: S.Schema<any>): schema is T;
+    (schema: AST): boolean;
+  };
+
+export const hasGenericAnnotation =
+  (type: string) => (ast: AST | undefined) => {
+    const description: string | undefined = ast?.annotations?.[
+      Description
+    ] as string;
+    return (
+      description &&
+      description?.startsWith(`${type}<`) &&
+      description?.endsWith(">")
+    );
+  };
+
+export const isNullishSchema = (schema: S.Schema<any>) =>
+  isNullSchema(schema) || isUndefinedSchema(schema);
+export const isNullSchema = (schema: S.Schema<any>) =>
+  schema.ast._tag === "Literal" && schema.ast.literal === null;
+export const isUndefinedSchema = isTag("UndefinedKeyword");
+export const isBooleanSchema = isTag<S.Schema<boolean>>("BooleanKeyword");
+export const isStringSchema = isTag<S.Schema<string>>("StringKeyword");
+export const isNumberSchema = isTag<S.Schema<number>>("NumberKeyword");
+
+export const hasMapAnnotation = hasGenericAnnotation("Map");
+
+export const isRecordLikeSchema = (schema: S.Schema<any>) =>
+  isMapSchema(schema) ||
+  isRecordSchema(schema) ||
+  isStructSchema(schema) ||
+  isClassSchema(schema) ||
+  false;
+
+export const isMapSchema = (schema: S.Schema<any>) =>
+  hasMapAnnotation(schema.ast) ||
+  // @ts-expect-error - ast.to?. is not narrowed, we don't care
+  hasMapAnnotation(schema.ast.to) ||
+  false;
+
+export const isClassSchema = (schema: S.Schema<any>) => {
+  const encoded = S.encodedSchema(schema);
+  return (
+    encoded.ast._tag === "TypeLiteral" &&
+    encoded.ast.propertySignatures !== undefined
+  );
+};
+
+export const isStructSchema = (schema: S.Schema<any>) => {
+  return (
+    schema.ast._tag === "TypeLiteral" &&
+    schema.ast.propertySignatures !== undefined
+  );
+};
+
+export const isRecordSchema = (schema: S.Schema<any>) => {
+  const encoded = S.encodedSchema(schema);
+  return (
+    encoded.ast._tag === "TypeLiteral" &&
+    encoded.ast.indexSignatures?.[0] !== undefined
+  );
+};
+
+export const isListSchema = (schema: S.Schema<any>) => {
+  return (
+    hasListAnnotation(schema.ast) ||
+    (S.encodedSchema(schema).ast._tag === "TupleType" && !isMapSchema(schema))
+  );
+};
+export const hasListAnnotation = (ast: AST | undefined) => {
+  const description: string | undefined = ast?.annotations?.[
+    Description
+  ] as string;
+  return (
+    description &&
+    description?.startsWith("List<") &&
+    description?.endsWith(">")
+  );
+};
+
+export const isSetSchema = (schema: S.Schema<any>) => {
+  return (
+    // @ts-expect-error - ast.to?. is not narrowed, we don't care
+    hasSetAnnotation(schema.ast) || hasSetAnnotation(schema.ast.to) || false
+  );
+};
+
+export const hasSetAnnotation = hasGenericAnnotation("Set");
+
+export const getSetValueAST = (schema: S.Schema<any>): AST =>
+  // @ts-expect-error - ast.to?. is not narrowed, we don't care
+  isSetSchema(schema) && schema.ast.to?.typeParameters[0];

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/sha256.ts

@@ -0,0 +1,23 @@
+import * as Effect from "effect/Effect";
+
+type Input = ArrayBuffer | Uint8Array | string;
+
+export const sha256 = (input: Input) =>
+  Effect.promise(async () => {
+    const digest = await crypto.subtle.digest("SHA-256", toArrayBuffer(input));
+    const hashArray = Array.from(new Uint8Array(digest));
+    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  });
+
+const toArrayBuffer = (input: Input) => {
+  if (input instanceof ArrayBuffer) {
+    return input;
+  }
+  if (typeof input === "string") {
+    return new TextEncoder().encode(input);
+  }
+  return input.buffer.slice(
+    input.byteOffset,
+    input.byteOffset + input.byteLength,
+  ) as ArrayBuffer;
+};

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 }
+  >;
+};