Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 127 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,132 @@
> ⚠️ alchemy-effect is still experimental and not ready for production use (expect breaking changes). Come hang in our [Discord](https://discord.gg/jwKw8dBJdN) to participate in the early stages of development.

# alchemy-effect

Alchemy Effect is an Infrastructure-as-Effects (iae) framework that unifies Business Logic and Infrastructure-as-Code into a unified model that ensures least-privilege IAM Policies with the TypeScript type system:
1. *Resources* are declared in your code
2. *Business Logic* is expressed as Effects accessing those resources
3. *Bindings* are attached to Functions, Workers, Hosts, etc. and type-checked ensure least-privilege IAM policies
`alchemy-effect` is an **Infrastructure-as-Effects (iae)** framework that unifies business logic and infrastructure config into a single, type-safe program.

A program built with `alchemy-effect` is guaranteed to be configured correctly by the type system - e.g. type-checked Bindings ensure your IAM Policies are least-privilege 🔐.

This example demonstrates the type errors you receive when attempting to grant excessive or missing permissions to a Lambda Function:

<img src="./images/alchemy-effect.gif" alt="alchemy-effect demo" width="600"/>

<sub><i>Example showing type-safe IAM policies &ndash; it is not possible to under or over provide bindings.</i></sub>
An `alchemy-effect` program produces a Plan that can be reviewed prior to deployment:

<img src="./images/alchemy-effect-plan.gif" alt="alchemy-effect demo" width="600"/>

# Resources

Resources are declared along-side your business logic as classes, e.g. a FIFO SQS Queue:

```ts
class Messages extends SQS.Queue("Messages", {
fifo: true,
schema: S.String,
}) {}
```

# Functions

Functions are a special kind of Resource that includes a runtime implementation function.

The function always returns an `Effect<A, Err, Req>` which is then used to infer Capabilities and type-check your Bindings.

```ts
class Api extends Lambda.serve("Api", {
fetch: Effect.fn(function* (event) {
yield* SQS.sendMessage(Messages, event.body!).pipe(
Effect.catchAll(() => Effect.void),
);
}),
})({
main: import.meta.filename,
bindings: $(SQS.SendMessage(Messages)),
}) {}
```

# Bindings

A Binding is a connection between a **Resource** and a **Function** that satisfies a **Capability** (aka. runtime dependency, e.g. `SQS.SendMessage(to: Messages)`).

> [!TIP]
> Bindings are inferred from your business logic and then type-checked to ensure least-privilege IAM policies.

```ts
class Api extends Lambda.serve("Api", {
// ...
})({
main: import.meta.filename,
// Policy<Lambda.Function, SQS.SendMessage<Messages>>
bindings: $(SQS.SendMessage(Messages)),
}) {}
```

> [!CAUTION]
> Curring (`Lambda.serve(..)({ .. })`) is required because there's a limitation in TypeScript. We hope to simplify this in the future.

# Components

Infrastructure and business logic can be encapsulated as a Component using a simple function.

```ts
const Monitor = <const ID extends string, ReqAlarm, ReqResolved>(
id: ID,
{
onAlarm,
onResolved,
}: {
onAlarm: (
batch: SQS.QueueEvent<Message>,
) => Effect.Effect<void, never, ReqAlarm>;
onResolved?: (
batch: SQS.QueueEvent<Message>,
) => Effect.Effect<void, never, ReqResolved>;
},
) => {
class Messages extends SQS.Queue(`${id}-Messages`, {
fifo: true,
schema: Message,
}) {}

return <const Props extends Lambda.FunctionProps<ReqAlarm | ReqResolved>>({
bindings,
...props
}: Props) =>
Lambda.consume(id, {
queue: Messages,
handle: Effect.fn(function* (batch) {
yield* SQS.sendMessage(Messages, {
id: 1,
value: "1",
}).pipe(Effect.catchAll(() => Effect.void));
if (onAlarm) {
yield* onAlarm(batch);
}
if (onResolved) {
yield* onResolved(batch);
}
}),
})({
...props,
// Components are not leaky - the inner SQS.SendMessage(Messages) binding is not required to be passed in by the caler
bindings: bindings.and(SQS.SendMessage(Messages)),
});
};
```

> [!TIP]
> Components are very similar to React components, but for infrastructure. Instead of declaring state in your closure and returning a React element, you declare Resources and return a `Function`.

# Type-Safe Plan

All knowable information about the Plan is available at compile-time, for example the type of the Plan is:

<img src="./images/alchemy-effect-plan-type.png" alt="alchemy-effect demo" width="600"/>

> [!TIP]
> These types can be used to implement type-level validation of infrastructure policies, e.g. disallowing publicly accessible S3 buckets.

# Building your own Resources, Capabilities, and Bindings

> [!CAUTION]
> WIP - this is coming soon!
10 changes: 0 additions & 10 deletions alchemy-effect/src/state.ts
Original file line number Diff line number Diff line change
Expand Up @@ -147,16 +147,6 @@ export const localFs = Layer.effect(
JSON.stringify(
value,
(k, v) => {
if (typeof v === "function") {
if (k === "resource") {
console.log({
isResource: isResource(v),
keys: Object.keys(v),
values: Object.values(v),
});
}
}

if (isResource(v)) {
return {
id: v.id,
Expand Down
4 changes: 1 addition & 3 deletions example/alchemy.run.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,7 @@ import { Api } from "./src/index.ts";
const phase = process.argv.includes("--destroy") ? "destroy" : "update";

const plan = Alchemy.plan({
phase,
// phase: "update",
// phase: "destroy",
phase: process.argv.includes("--destroy") ? "destroy" : "update",
services: [Api],
});

Expand Down
Binary file added images/alchemy-effect-plan-type.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/alchemy-effect-plan.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.