alchemy-effect 0.5.0 → 0.6.2

package/src/Platform.ts

@@ -0,0 +1,398 @@
+import * as Effect from "effect/Effect";
+import { pipe } from "effect/Function";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import type { Scope } from "effect/Scope";
+import * as ServiceMap from "effect/ServiceMap";
+import type { HttpClient } from "effect/unstable/http/HttpClient";
+import { SingleShotGen } from "effect/Utils";
+import type { PolicyLike } from "./Binding.ts";
+import {
+  ExecutionContext,
+  type BaseExecutionContext,
+} from "./ExecutionContext.ts";
+import type { HttpEffect } from "./Http.ts";
+import type { InputProps } from "./Input.ts";
+import type { Provider } from "./Provider.ts";
+import {
+  Resource,
+  type ResourceLike,
+  type ResourceProviders,
+} from "./Resource.ts";
+import { Self } from "./Self.ts";
+import type { Stack, StackServices } from "./Stack.ts";
+import type { Stage } from "./Stage.ts";
+import { effectClass } from "./Util/effect.ts";
+import type { IsAny } from "./Util/types.ts";
+
+export interface PlatformProps {
+  /**
+   * @internal type used to signal when this is an effect-native implementation
+   * @default false
+   */
+  isExternal?: boolean;
+}
+
+export type Main<Services = never> = void | {
+  fetch: HttpEffect<Services | PlatformServices>;
+};
+
+export type Rpc<Shape> = {
+  "~alchemy-effect/rpc": Shape;
+};
+
+// services provided to the Resource
+export type PlatformServices =
+  | ExecutionContext
+  | HttpClient
+  | PolicyLike
+  | Provider<any>
+  | Scope
+  | Stack
+  | StackServices
+  | Stage;
+
+export interface Platform<
+  Resource extends ResourceLike<string, PlatformProps>,
+  Services,
+  MainShape,
+  ExecutionContext extends BaseExecutionContext,
+  BaseShape = {},
+> extends Effect.Effect<
+  Resource & ExecutionContext,
+  never,
+  Services | PlatformServices
+> {
+  provider: ResourceProviders<Resource>;
+
+  <Self, Shape>(): {
+    <PropsReq = never>(
+      id: string,
+      props:
+        | InputProps<Resource["Props"]>
+        | Effect.Effect<InputProps<Resource["Props"]>, never, PropsReq>,
+    ): Effect.Effect<
+      Resource & Rpc<Self>,
+      never,
+      Self | Provider<Resource> | PropsReq
+    > & {
+      make<InitReq = never>(
+        impl: Effect.Effect<Shape, never, InitReq>,
+      ): Layer.Layer<
+        Self,
+        never,
+        | Provider<Resource>
+        | Exclude<PropsReq | InitReq, Services | PlatformServices>
+      >;
+      new (_: never): MakeShape<Shape, BaseShape>;
+      promise(): PlatformPromise<Self>;
+      of(shape: Shape & MainShape): MakeShape<Shape, BaseShape>;
+    };
+  };
+  <Self>(): {
+    <
+      Shape extends MainShape,
+      PropsReq = never,
+      InitReq extends Services | PlatformServices = never,
+    >(
+      id: string,
+      props:
+        | InputProps<Resource["Props"]>
+        | Effect.Effect<Resource["Props"], never, PropsReq>,
+      impl: Effect.Effect<Shape, never, InitReq>,
+    ): Effect.Effect<
+      Resource & Rpc<Self>,
+      never,
+      | Provider<Resource>
+      | PropsReq
+      | Exclude<InitReq, Services | PlatformServices>
+    > & {
+      new (_: never): MakeShape<Shape, BaseShape>;
+      promise(): PlatformPromise<Self>;
+    };
+    <Shape, PropsReq = never>(
+      id: string,
+      props:
+        | InputProps<Resource["Props"]>
+        | Effect.Effect<InputProps<Resource["Props"]>, never, PropsReq>,
+    ): Effect.Effect<
+      Resource & Rpc<Self>,
+      never,
+      Provider<Resource> | PropsReq
+    > & {
+      make<InitReq extends Services | PlatformServices = never>(
+        impl: Effect.Effect<Shape, never, InitReq>,
+      ): Layer.Layer<
+        Self,
+        never,
+        | Provider<Resource>
+        | Exclude<PropsReq | InitReq, Services | PlatformServices>
+      >;
+      new (_: never): MakeShape<Shape, BaseShape>;
+      promise(): PlatformPromise<Self>;
+    } & (<InitReq extends Services | PlatformServices = never>(
+        impl: Effect.Effect<Shape, never, InitReq>,
+      ) => Effect.Effect<
+        Resource & Rpc<Self>,
+        never,
+        | Provider<Resource>
+        | PropsReq
+        | Exclude<InitReq, Services | PlatformServices>
+      >);
+  };
+  <PropsReq = never, InitReq extends Services | PlatformServices = never>(
+    id: string,
+    props:
+      | InputProps<Resource["Props"]>
+      | Effect.Effect<InputProps<Resource["Props"]>, never, PropsReq>,
+  ): Effect.Effect<
+    Resource,
+    never,
+    | Provider<Resource>
+    | PropsReq
+    | Exclude<InitReq, Services | PlatformServices>
+  >;
+  <
+    Shape extends MainShape,
+    PropsReq = never,
+    InitReq extends Services | PlatformServices = never,
+  >(
+    id: string,
+    props:
+      | InputProps<Resource["Props"]>
+      | Effect.Effect<InputProps<Resource["Props"]>, never, PropsReq>,
+    impl: Effect.Effect<Shape, never, InitReq>,
+  ): Effect.Effect<
+    Resource & Rpc<Shape>,
+    never,
+    | Provider<Resource>
+    | PropsReq
+    | Exclude<InitReq, Services | PlatformServices>
+  > & {
+    promise(): PlatformPromise<Shape>;
+  };
+}
+
+type MakeShape<Shape, BaseShape> = Shape extends never | undefined | void
+  ? BaseShape
+  : Shape & BaseShape;
+
+export const Platform = <
+  R extends ResourceLike<
+    string,
+    | {
+        env?: Record<string, any>;
+        exports?: string[];
+      }
+    | undefined
+  >,
+>(
+  type: R["Type"],
+  createExecutionContext: (id: string) => BaseExecutionContext,
+): any => {
+  type Props = any;
+  type Impl = Effect.Effect<any>;
+
+  const resource = Resource(type);
+  const PlatformContext = ExecutionContext(type);
+
+  const constructor = (
+    id?: string,
+    props?: any,
+    impl?: Impl,
+    isTag = false,
+  ): any => {
+    if (!id) {
+      // impl was not provided inline, this is a tagged instance
+      // e.g.
+      // export class Sandbox extends Cloudflare.Container<Sandbox>()(..) {}
+      //
+      // export const SandboxLive = Sandbox.make(..)
+      return (id: string, props?: any, impl?: Impl) =>
+        constructor(id, props, impl, true);
+    } else if (!impl) {
+      const cls = makeClass(id, props);
+      const asEffect = () =>
+        !isTag
+          ? // this is a non-tagged resource yielded without providing an implementation
+            // e.g.
+            // yield* Cloudflare.Worker("id", { main: "./src/worker.ts" })
+            //
+            // This is where we bridge to non-effect, e.g. bundling an ordinary worker
+            // export default {
+            //   fetch: (request: Request) => {
+            //     return new Response("Hello, world!");
+            //   }
+            // }
+            resource(id, {
+              ...props,
+              isExternal: true,
+            })
+          : Effect.flatMap(
+              // this is a tagged resource
+              Effect.serviceOption(cls.Self),
+              Option.match({
+                // we are likely running at runtime, so we create
+                onNone: () => resource(id, props),
+                onSome: Effect.succeed,
+              }),
+            );
+      return Object.assign(
+        function (impl: Impl) {
+          return cls.asEffect().pipe(Effect.provide(cls.make(impl)));
+        },
+        // we splice in the Effect so this can be yielded to indicate a non-Effect native instance
+        // e.g. here, we yield it - in this case we don't want to provide an implementation
+        // const worker = yield* Cloudflare.Worker("id", {
+        //  main: "./src/worker.ts"
+        // });
+        cls,
+        {
+          asEffect,
+          [Symbol.iterator]: () => new SingleShotGen({ asEffect }),
+        },
+      );
+    } else {
+      // impl was provided inline, this is a non-tagged eager instance
+      // e.g.
+      // export default Cloudflare.Worker("id", { main: "./src/worker.ts" }, Effect.gen(function* () { .. })
+      const cls = makeClass(id, props);
+      return cls.asEffect().pipe(Effect.provide(cls.make(impl)), effectClass);
+    }
+  };
+
+  const makeClass = (id: string, props: Props) => {
+    return class Platform {
+      static readonly Self = Self(`${type}<${id}>`);
+      static readonly Platform = ServiceMap.Service<Platform, Platform>(
+        `Platform<${type}<${id}>>`,
+      );
+      static [Symbol.iterator](): Iterator<
+        Effect.Yieldable<any, void, never, Self>,
+        Resource,
+        void
+      > {
+        return new SingleShotGen(this) as any;
+      }
+      static asEffect() {
+        return this.Self.asEffect();
+      }
+      static pipe(...args: any[]) {
+        // @ts-expect-error
+        return pipe(this.asEffect(), ...args);
+      }
+      static of = (shape: any) => shape;
+      static make = (impl: Impl) => {
+        // build the Layer once for the root Self
+        const SelfLayer = Layer.effect(
+          Self,
+          Effect.flatMap(
+            Effect.all([
+              Effect.isEffect(props) ? props : Effect.succeed(props ?? {}),
+              Effect.sync(() => createExecutionContext(id)),
+              Effect.services<never>(),
+            ]),
+            Effect.fnUntraced(function* ([
+              props,
+              executionContext,
+              outerServices,
+            ]) {
+              const instance = Object.assign(
+                yield* resource(id, props as any),
+                executionContext,
+              );
+
+              yield* impl.pipe(
+                Effect.flatMap((impl) =>
+                  impl
+                    ? (executionContext.serve?.(impl.fetch) ??
+                      Effect.die("No serve handler"))
+                    : Effect.void,
+                ),
+                Effect.provide(
+                  Layer.provideMerge(
+                    Layer.mergeAll(
+                      Layer.succeed(Platform.Platform, executionContext),
+                      Layer.succeed(PlatformContext, executionContext),
+                      Layer.succeed(ExecutionContext, executionContext),
+                      Layer.succeed(resource.Self, instance),
+                      Layer.succeed(Platform.Self, instance),
+                      Layer.succeed(Self, instance),
+                    ),
+                    Layer.succeedServices(outerServices),
+                  ),
+                ),
+              );
+
+              instance.Props = {
+                ...props,
+                env: {
+                  ...props?.env,
+                  ...executionContext.env,
+                },
+                exports: executionContext.exports
+                  ? yield* executionContext.exports
+                  : undefined,
+              };
+
+              return Object.assign(instance, {
+                ExecutionContext: executionContext,
+              }) as R;
+            }),
+          ),
+        );
+        const self = Self.asEffect() as any; // TODO(sam): why do we need to cast?
+
+        return Layer.provideMerge(
+          Layer.mergeAll(
+            // sets the Context for all self-hierarchies
+            // Self
+            // Self<Cloudflare.Worker>
+            // Self<Cloudflare.Worker<Api>>
+            Layer.effect(Self<R>(type), self),
+            Layer.effect(Self<R>(`${type}<${id}>`), self),
+          ),
+          // provide here so we build once and just mirror
+          SelfLayer,
+        );
+      };
+    };
+  };
+
+  const instance = Object.assign(constructor, resource, {
+    Platform: Platform,
+    asEffect: () => resource.Self.asEffect(),
+  }) as any;
+  return instance;
+};
+
+/**
+ * Bridge between the Effect and the Promise.
+ *
+ * Only map types if needed.
+ *
+ * TODO(sam): probably over engineering? Maybe just let the user run into the wall of Effect.runPromise and fix? Good friction is good!
+ */
+export type PlatformPromise<Shape> = [
+  HasRequirements<Extract<Shape[keyof Shape], Effect.Effect<any, any, any>>>,
+  Effect.Services<Extract<Shape[keyof Shape], Effect.Effect<any, any, any>>>,
+] extends [true, never]
+  ? Promise<Shape>
+  : Promise<{
+      [key in keyof Shape]: Shape[key] extends (
+        ...args: infer Args
+      ) => Effect.Effect<infer A, infer Err, any>
+        ? (...args: Args) => Effect.Effect<A, Err, never>
+        : Shape[key] extends Effect.Effect<infer A, infer Err, infer Req>
+          ? Req extends never
+            ? Shape[key]
+            : Effect.Effect<A, Err, never>
+          : Shape[key];
+    }>;
+
+type HasRequirements<E extends Effect.Effect<any, any, any>> =
+  IsAny<Effect.Services<E>> extends true
+    ? true
+    : Effect.Services<E> extends never
+      ? false
+      : true;

package/src/Provider.ts

@@ -0,0 +1,156 @@
+import * as Effect from "effect/Effect";
+import * as ServiceMap from "effect/ServiceMap";
+import type * as Stream from "effect/Stream";
+import type { ScopedPlanStatusSession } from "./Cli/index.ts";
+import type { Diff } from "./Diff.ts";
+import type { Input } from "./Input.ts";
+import type { ResourceBinding, ResourceLike } from "./Resource.ts";
+
+export interface Provider<
+  R extends ResourceLike = ResourceLike,
+> extends ServiceMap.ServiceClass<
+  Provider<R>,
+  R["Type"],
+  ProviderService<R>
+  // 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
+
+  // preferred:
+  // ProviderService<R>
+> {}
+
+export const Provider = <R extends ResourceLike>(
+  type: R["Type"],
+): Provider<R> => ServiceMap.Service<Provider<R>, ProviderService<R>>()(type);
+
+type BindingData<Res extends ResourceLike> = [Res] extends [
+  { Binding: infer B },
+]
+  ? ResourceBinding<B>[]
+  : any[];
+
+type Props<Res extends ResourceLike> = keyof Res["Props"] extends never
+  ? Res["Props"] | undefined
+  : Res["Props"];
+
+export interface LogLine {
+  timestamp: Date;
+  message: string;
+}
+
+export interface LogsInput {
+  since?: Date;
+  limit?: number;
+}
+
+export interface ProviderService<
+  Res extends ResourceLike = ResourceLike,
+  ReadReq = never,
+  DiffReq = never,
+  PrecreateReq = never,
+  CreateReq = never,
+  UpdateReq = never,
+  DeleteReq = never,
+  TailReq = never,
+  LogsReq = never,
+> {
+  /**
+   * The version of the provider.
+   *
+   * @default 0
+   */
+  version?: number;
+  /**
+   * Returns a stream of log lines for a deployed resource.
+   * Used by `alchemy tail` to stream real-time logs.
+   */
+  tail?(input: {
+    id: string;
+    instanceId: string;
+    props: Props<Res>;
+    output: Res["Attributes"];
+  }): Stream.Stream<LogLine, any, TailReq>;
+  /**
+   * Queries historical logs for a deployed resource.
+   * Used by `alchemy logs` to fetch past log entries.
+   */
+  logs?(input: {
+    id: string;
+    instanceId: string;
+    props: Props<Res>;
+    output: Res["Attributes"];
+    options: LogsInput;
+  }): Effect.Effect<LogLine[], any, LogsReq>;
+  // watch();
+  // replace(): Effect.Effect<void, never, never>;
+  // different interface that is persistent, watching, reloads
+  // run?() {}
+  // branch?() {}
+  read?(input: {
+    id: string;
+    instanceId: string;
+    olds: Props<Res>;
+    // what is the ARN?
+    output: Res["Attributes"] | undefined; // current state -> synced state
+  }): Effect.Effect<Res["Attributes"] | undefined, any, ReadReq>;
+  /**
+   * Properties that are always stable across any update.
+   */
+  stables?: Extract<keyof Res["Attributes"], string>[];
+  diff?(input: {
+    id: string;
+    instanceId: string;
+    olds: Props<Res>;
+    // Note: we do not resolve (Res["Props"]) here because diff runs during plan
+    // -> we need a way for the diff handlers to work with Outputs
+    news: Input<Props<Res>>;
+    oldBindings: BindingData<Res>;
+    newBindings: Input<BindingData<Res>>;
+    output: Res["Attributes"] | undefined;
+  }): Effect.Effect<Diff | void, any, DiffReq>;
+  // dev?:() => Effect.Effect<void, any, DevReq>;
+  precreate?(input: {
+    id: string;
+    news: Props<Res>;
+    instanceId: string;
+    session: ScopedPlanStatusSession;
+  }): Effect.Effect<Res["Attributes"], any, PrecreateReq>;
+  create(input: {
+    id: string;
+    instanceId: string;
+    news: Props<Res>;
+    session: ScopedPlanStatusSession;
+    bindings: BindingData<Res>;
+    output?: Res["Attributes"];
+  }): Effect.Effect<Res["Attributes"], any, CreateReq>;
+  update(input: {
+    id: string;
+    instanceId: string;
+    news: Props<Res>;
+    olds: Props<Res>;
+    output: Res["Attributes"];
+    session: ScopedPlanStatusSession;
+    bindings: BindingData<Res>;
+  }): Effect.Effect<Res["Attributes"], any, UpdateReq>;
+  delete(input: {
+    id: string;
+    instanceId: string;
+    olds: Props<Res>;
+    output: Res["Attributes"];
+    session: ScopedPlanStatusSession;
+    bindings: BindingData<Res>;
+  }): Effect.Effect<void, any, DeleteReq>;
+}
+
+export const getProviderByType = Effect.fnUntraced(function* <
+  R extends ResourceLike,
+>(resourceType: string) {
+  const context = yield* Effect.services<never>();
+  const provider: ProviderService<R> = context.mapUnsafe.get(resourceType);
+  if (!provider) {
+    return yield* Effect.die(
+      new Error(`Provider not found for ${resourceType}`),
+    );
+  }
+  return provider;
+});

package/src/Ref.ts

@@ -0,0 +1,46 @@
+import * as Output from "./Output.ts";
+import type { ResourceLike } from "./Resource.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 ResourceLike>(
+  ref: Ref<R>,
+): RefMetadata<R> => (ref as any)[RefMetadata];
+
+export interface Ref<R extends ResourceLike = ResourceLike> {
+  /** @internal phantom */
+  Ref: R;
+}
+
+export interface RefMetadata<R extends ResourceLike> {
+  id: R["LogicalId"];
+  stack?: string;
+  stage?: string;
+}
+
+export const ref = <R extends ResourceLike>({
+  stack,
+  id,
+  stage,
+}: RefMetadata<R>): Ref<R> => {
+  const ref = new Proxy(
+    {},
+    {
+      get: (_, prop) => {
+        if (prop === RefMetadata) {
+          return {
+            stack,
+            stage,
+            id,
+          } satisfies RefMetadata<R>;
+        }
+        return (Output.of(ref) as any)[prop];
+      },
+    },
+  ) as Ref<R>;
+  return ref;
+};

package/src/RemovalPolicy.ts

@@ -0,0 +1,51 @@
+import * as Effect from "effect/Effect";
+import * as ServiceMap from "effect/ServiceMap";
+
+export class RemovalPolicy extends ServiceMap.Service<
+  RemovalPolicy,
+  "retain" | "destroy"
+>()("RemovalPolicy") {}
+
+export const retain: {
+  (
+    enabled?: boolean,
+  ): <R, Req = never>(
+    enabled: Effect.Effect<R, never, Req>,
+  ) => Effect.Effect<R, never, Req>;
+  <Req = never>(
+    enabled: Effect.Effect<boolean, never, Req>,
+  ): <R, Req2 = never>(
+    a: Effect.Effect<R, never, Req2>,
+  ) => Effect.Effect<R, never, Req | Req2>;
+} = ((enabled: boolean | Effect.Effect<boolean, never, any>) =>
+  (eff: Effect.Effect<any, never, any>) =>
+    eff.pipe(
+      typeof enabled === "boolean"
+        ? Effect.provideService(RemovalPolicy, enabled ? "retain" : "destroy")
+        : Effect.provideServiceEffect(
+            RemovalPolicy,
+            enabled.pipe(Effect.map((a) => (a ? "retain" : "destroy"))),
+          ),
+    )) as any;
+
+export const destroy: {
+  (
+    enabled?: boolean,
+  ): <R, Req = never>(
+    enabled: Effect.Effect<R, never, Req>,
+  ) => Effect.Effect<R, never, Req>;
+  <Req = never>(
+    enabled: Effect.Effect<boolean, never, Req>,
+  ): <R, Req2 = never>(
+    a: Effect.Effect<R, never, Req2>,
+  ) => Effect.Effect<R, never, Req | Req2>;
+} = ((enabled: boolean | Effect.Effect<boolean, never, any>) =>
+  (eff: Effect.Effect<any, never, any>) =>
+    eff.pipe(
+      typeof enabled === "boolean"
+        ? Effect.provideService(RemovalPolicy, enabled ? "destroy" : "retain")
+        : Effect.provideServiceEffect(
+            RemovalPolicy,
+            enabled.pipe(Effect.map((a) => (a ? "destroy" : "retain"))),
+          ),
+    )) as any;