---
/**
* "One line does three jobs": for each tool, the code you write to read
* and write one DynamoDB table from a Lambda, the config it deploys (IAM
* policy + env var), and what the function's code gets at runtime.
* Line colors show where each piece comes from: in Alchemy, one capability
* line produces its policy statement, the table name, and a typed client.
* SST's link over-grants; Pulumi and Terraform deploy the policy and env var
* you write line by line, and define no client.
*/
import { highlightTS } from "../marketing/highlightTS";
// get / put: produced by that Alchemy capability line; both: the shared
// env var; link: generated by SST's link; over: access the code never uses;
// hand: SDK calls written by hand, unchecked; policy / env: IAM and env
// config you define line by line.
type Src = "get" | "put" | "both" | "link" | "over" | "hand" | "policy" | "env";
type Lang = "ts" | "hcl" | "yaml";
type Line = { text: string; src?: Src; write?: boolean; file?: boolean; lang?: Lang };
type ToolSet = {
id: "alchemy" | "sst" | "pulumi" | "terraform";
code: Line[];
config: Line[];
runtime: Line[];
};
// Pulumi and Terraform deploy exactly the policy you write, so every config
// line maps back to a line of code.
const HAND_CONFIG = (arn: string, env: string): Line[] => [
{ text: "# deployed config for api" },
{ text: "Role:", src: "policy" },
{ text: " Policy:", src: "policy" },
{ text: ' Version: "2012-10-17"', src: "policy" },
{ text: " Statement:", src: "policy" },
{ text: " - Effect: Allow", src: "policy" },
{ text: " Action: [dynamodb:GetItem, dynamodb:PutItem]", src: "policy" },
{ text: ` Resource: ${arn}`, src: "policy" },
{ text: "Environment:", src: "env" },
{ text: " Variables:", src: "env" },
{ text: ` ${env}`, src: "env" },
];
const NO_CLIENT: Line[] = [
{ text: "// runtime: no client definition" },
{ text: "// the handler builds its own SDK calls" },
{ text: "// against process.env.TABLE_NAME" },
];
const SETS: ToolSet[] = [
{
id: "alchemy",
code: [
{ text: "src/api.ts", file: true },
{ text: "export default class Api extends Lambda.Function<Api>()(" },
{ text: ' "Api",' },
{ text: " { main: import.meta.url }," },
{ text: " Effect.gen(function* () {" },
{ text: ' const sessions = yield* DynamoDB.Table("Sessions");' },
{ text: " const getSession = yield* DynamoDB.GetItem(sessions);", src: "get" },
{ text: " const saveSession = yield* DynamoDB.PutItem(sessions);", src: "put", write: true },
{ text: " return {" },
{ text: " fetch: Effect.gen(function* () {" },
{ text: " const { Item } = yield* getSession({ Key });" },
{ text: " yield* saveSession({ Item: next });", write: true },
{ text: " })," },
{ text: " };" },
{ text: " })," },
{ text: ") {}" },
],
config: [
{ text: "# deployed config for Api" },
{ text: "Role:" },
{ text: " Policy:" },
{ text: ' Version: "2012-10-17"' },
{ text: " Statement:" },
{ text: " - Effect: Allow", src: "get" },
{ text: " Action: dynamodb:GetItem", src: "get" },
{ text: " Resource: arn:…:table/api-sessions-8f2c", src: "get" },
{ text: " - Effect: Allow", src: "put", write: true },
{ text: " Action: dynamodb:PutItem", src: "put", write: true },
{ text: " Resource: arn:…:table/api-sessions-8f2c", src: "put", write: true },
{ text: "Environment:" },
{ text: " Variables:" },
{ text: " Sessions_tableName: api-sessions-8f2c", src: "both" },
],
runtime: [
{ text: "// runtime: typed clients" },
{ text: "const getSession: (", src: "get" },
{ text: " request: GetItemRequest,", src: "get" },
{ text: ") => Effect<GetItemOutput, GetItemError>", src: "get" },
{ text: "const saveSession: (", src: "put", write: true },
{ text: " request: PutItemRequest,", src: "put", write: true },
{ text: ") => Effect<PutItemOutput, PutItemError>", src: "put", write: true },
],
},
{
id: "sst",
code: [
{ text: "sst.config.ts", file: true },
{ text: 'const sessions = new sst.aws.Dynamo("Sessions", { … });' },
{ text: 'new sst.aws.Function("Api", {' },
{ text: ' handler: "src/api.handler",' },
{ text: " link: [sessions],", src: "link" },
{ text: "});" },
{ text: "src/api.ts", file: true },
{ text: 'import { Resource } from "sst";' },
{ text: "const client = new DynamoDBClient({});" },
{ text: "export const handler = async () => {" },
{ text: " const TableName = Resource.Sessions.name;", src: "link" },
{ text: " const { Item } = await client.send(", src: "hand" },
{ text: " new GetItemCommand({ TableName, Key }));", src: "hand" },
{ text: " await client.send(", src: "hand" },
{ text: " new PutItemCommand({ TableName, Item: next }));", src: "hand" },
{ text: "};" },
],
config: [
{ text: "# deployed config for Api" },
{ text: "Role:" },
{ text: " Policy:" },
{ text: ' Version: "2012-10-17"' },
{ text: " Statement:" },
{ text: " - Effect: Allow", src: "link" },
{ text: " # every DynamoDB action, DeleteTable too", src: "over" },
{ text: ' Action: "dynamodb:*"', src: "over" },
{ text: " Resource:", src: "link" },
{ text: " - arn:…:table/app-sessions", src: "link" },
{ text: " - arn:…:table/app-sessions/*", src: "link" },
{ text: "Environment:" },
{ text: " Variables:" },
{ text: ` SST_RESOURCE_Sessions: '{"name":"app-sessions",…}'`, src: "link" },
],
runtime: [
{ text: "// runtime" },
{ text: "const TableName: string; // typed by link", src: "link" },
{ text: "// no client definition: new DynamoDBClient()", src: "hand" },
{ text: "// and send() any command, allowed or not", src: "hand" },
],
},
{
id: "pulumi",
code: [
{ text: "index.ts", file: true },
{ text: 'const sessions = new aws.dynamodb.Table("sessions", { … });' },
{ text: 'const role = new aws.iam.Role("api", { assumeRolePolicy: … });', src: "policy" },
{ text: 'new aws.iam.RolePolicy("api", {', src: "policy" },
{ text: " role: role.id,", src: "policy" },
{ text: " policy: sessions.arn.apply((arn) => JSON.stringify({", src: "policy" },
{ text: ' Version: "2012-10-17",', src: "policy" },
{ text: " Statement: [{", src: "policy" },
{ text: ' Effect: "Allow",', src: "policy" },
{ text: ' Action: ["dynamodb:GetItem", "dynamodb:PutItem"],', src: "policy" },
{ text: " Resource: arn,", src: "policy" },
{ text: " }],", src: "policy" },
{ text: " })),", src: "policy" },
{ text: "});", src: "policy" },
{ text: 'new aws.lambda.Function("api", {' },
{ text: " role: role.arn," },
{ text: " environment: {", src: "env" },
{ text: " variables: { TABLE_NAME: sessions.name },", src: "env" },
{ text: " },", src: "env" },
{ text: "});" },
],
config: HAND_CONFIG("arn:…:table/sessions-4d1a", "TABLE_NAME: sessions-4d1a"),
runtime: NO_CLIENT,
},
{
id: "terraform",
code: [
{ text: "main.tf", file: true, lang: "hcl" },
{ text: 'resource "aws_dynamodb_table" "sessions" { … }', lang: "hcl" },
{ text: 'resource "aws_iam_role" "api" { assume_role_policy = … }', src: "policy", lang: "hcl" },
{ text: 'resource "aws_iam_role_policy" "api" {', src: "policy", lang: "hcl" },
{ text: " role = aws_iam_role.api.id", src: "policy", lang: "hcl" },
{ text: " policy = jsonencode({", src: "policy", lang: "hcl" },
{ text: ' Version = "2012-10-17"', src: "policy", lang: "hcl" },
{ text: " Statement = [{", src: "policy", lang: "hcl" },
{ text: ' Effect = "Allow"', src: "policy", lang: "hcl" },
{ text: ' Action = ["dynamodb:GetItem", "dynamodb:PutItem"]', src: "policy", lang: "hcl" },
{ text: " Resource = aws_dynamodb_table.sessions.arn", src: "policy", lang: "hcl" },
{ text: " }]", src: "policy", lang: "hcl" },
{ text: " })", src: "policy", lang: "hcl" },
{ text: "}", src: "policy", lang: "hcl" },
{ text: 'resource "aws_lambda_function" "api" {', lang: "hcl" },
{ text: " role = aws_iam_role.api.arn", lang: "hcl" },
{ text: " environment {", src: "env", lang: "hcl" },
{ text: " variables = {", src: "env", lang: "hcl" },
{ text: " TABLE_NAME = aws_dynamodb_table.sessions.name", src: "env", lang: "hcl" },
{ text: " }", src: "env", lang: "hcl" },
{ text: " }", src: "env", lang: "hcl" },
{ text: "}", lang: "hcl" },
],
config: HAND_CONFIG("arn:…:table/sessions", "TABLE_NAME: sessions"),
runtime: NO_CLIENT,
},
];
const esc = (t: string) => t.replace(/&/g, "&").replace(/</g, "<");
const yaml = (t: string) => {
if (/^\s*#/.test(t)) return `<span class="alc-tok-c">${esc(t)}</span>`;
const m = t.match(/^(\s*)(- )?([A-Za-z_]\w*):(\s.*|)$/);
if (!m) {
const d = t.match(/^(\s*)- (.*)$/);
return d
? `${d[1]}<span class="ol__dash">- </span><span class="ol__str">${esc(d[2]!)}</span>`
: esc(t);
}
const [, indent, dash = "", key, rest] = m;
const value = rest!.trim();
return (
indent +
(dash ? `<span class="ol__dash">${dash}</span>` : "") +
`<span class="ol__key">${esc(key!)}</span>:` +
(value ? ` <span class="ol__str">${esc(value)}</span>` : "")
);
};
const hcl = (t: string) =>
esc(t)
.replace(/("[^"]*")/g, '<span class="ol__str">$1</span>')
.replace(/^(\s*)(resource)\b/, '$1<span class="alc-tok-k">$2</span>')
.replace(/^(\s*)([A-Za-z_]\w*)(\s*=)/, '$1<span class="ol__key">$2</span>$3');
const render = (l: Line, lang: Lang) =>
l.file ? esc(l.text) : (l.lang ?? lang) === "hcl" ? hcl(l.text) : lang === "yaml" ? yaml(l.text) : highlightTS(l.text);
// Classes for a line, plus run edges so each colored block gets a little
// breathing room above and below.
const classes = (lines: Line[], i: number) => {
const l = lines[i]!;
return [
"ol__line",
l.src && `is-${l.src}`,
l.write && "is-write",
l.file && "is-file",
l.src && lines[i - 1]?.src !== l.src && "is-run-start",
l.src && lines[i + 1]?.src !== l.src && "is-run-end",
];
};
const label = { alchemy: "Alchemy", sst: "SST", pulumi: "Pulumi", terraform: "Terraform" };
---
<figure class="ol" data-state="read" data-tool="alchemy">
<fieldset class="ol__modes">
<legend class="ol__sr">Show how each tool wires the function</legend>
<label>
<input type="radio" name="ol-state" value="alchemy-read" checked />
<span data-copy>Alchemy · read</span>
</label>
<label>
<input type="radio" name="ol-state" value="alchemy-write" />
<span data-copy>Alchemy · read + write</span>
</label>
<label>
<input type="radio" name="ol-state" value="sst" />
<span data-copy>SST</span>
</label>
<label>
<input type="radio" name="ol-state" value="pulumi" />
<span data-copy>Pulumi</span>
</label>
<label>
<input type="radio" name="ol-state" value="terraform" />
<span data-copy>Terraform</span>
</label>
</fieldset>
<div class="ol__sets">
{
SETS.map((set) => (
<div class:list={["ol__set", set.id === "alchemy" && "is-active"]} data-set={set.id}>
<div class="ol__stage">
<div class="ol__card ol__code">
<pre class="ol__pre" tabindex="0" aria-label={`${label[set.id]}: the code you write`}><code>{
set.code.map((l, i) => (
<span class:list={classes(set.code, i)} set:html={render(l, "ts")} />
))
}</code></pre>
</div>
<div class="ol__outs">
<div class="ol__card">
<pre class="ol__pre" tabindex="0" aria-label={`${label[set.id]}: deployed IAM policy and environment variables`}><code>{
set.config.map((l, i) => (
<span class:list={classes(set.config, i)} set:html={render(l, "yaml")} />
))
}</code></pre>
</div>
<div class="ol__card">
<pre class="ol__pre" tabindex="0" aria-label={`${label[set.id]}: what the function's code gets at runtime`}><code>{
set.runtime.map((l, i) => (
<span class:list={classes(set.runtime, i)} set:html={render(l, "ts")} />
))
}</code></pre>
</div>
</div>
</div>
{set.id === "alchemy" && (
<>
<ul class="ol__legend" aria-label="Legend">
<li class="is-get" data-copy>
<code>GetItem</code> grants read and returns <code>getSession</code>
</li>
<li class="is-put is-write" data-copy>
<code>PutItem</code> grants write and returns <code>saveSession</code>
</li>
</ul>
<p class="ol__note" data-when="read" data-copy>
One line asks for read access. It grants exactly
<code>dynamodb:GetItem</code> on this table, injects the
table's name, and returns a typed client.
</p>
<p class="ol__note" data-when="write" data-copy>
Add <code>PutItem</code> and its statement, its env var, and
its client all follow. Remove a line and all three go with it.
</p>
</>
)}
{set.id === "sst" && (
<>
<ul class="ol__legend" aria-label="Legend">
<li class="is-link" data-copy>generated by <code>link</code></li>
<li class="is-over" data-copy>more access than the code uses</li>
<li class="is-hand" data-copy>written by hand, unchecked</li>
</ul>
<p class="ol__note" data-copy>
<code>link</code> writes the policy for you, but it grants <code>dynamodb:*</code> on the table, <code>DeleteTable</code> included, while the handler only calls <code>GetItem</code> and <code>PutItem</code>. There's no client definition, so the SDK calls are yours to keep in sync.
</p>
</>
)}
{(set.id === "pulumi" || set.id === "terraform") && (
<>
<ul class="ol__legend" aria-label="Legend">
<li class="is-policy" data-copy>IAM policy: every line is yours to write</li>
<li class="is-env" data-copy>env var: yours to wire</li>
</ul>
<p class="ol__note" data-copy>
{set.id === "pulumi" ? "Pulumi" : "Terraform"} deploys exactly
the policy you define: each statement, action, and ARN in the
config traces back to a line you wrote. There's no client
definition, so nothing checks your handler's SDK calls against
either.
</p>
</>
)}
</div>
))
}
</div>
<p class="ol__sr" aria-live="polite" data-live></p>
</figure>
<script>
// Switches between tools (crossfade, with the height easing between
// them) and between Alchemy's read and read + write (lines slide in and
// out, handled in CSS).
const SWITCH_MS = 420;
for (const fig of document.querySelectorAll<HTMLElement>(".ol")) {
const wrap = fig.querySelector<HTMLElement>(".ol__sets")!;
const sets = [...fig.querySelectorAll<HTMLElement>(".ol__set")];
const live = fig.querySelector<HTMLElement>("[data-live]")!;
for (const s of sets) if (!s.classList.contains("is-active")) s.inert = true;
let timer = 0;
const announce = () => {
const active = sets.find((s) => s.classList.contains("is-active"))!;
const note = [...active.querySelectorAll<HTMLElement>(".ol__note")].find(
(n) => getComputedStyle(n).display !== "none",
);
live.textContent = note?.textContent?.replace(/\s+/g, " ").trim() ?? "";
};
fig.addEventListener("change", (e) => {
const value = (e.target as HTMLInputElement).value;
const [tool, mode] = value.split("-") as [string, string | undefined];
if (mode) fig.dataset.state = mode;
if (tool === fig.dataset.tool) {
announce();
return;
}
fig.dataset.tool = tool;
clearTimeout(timer);
wrap.style.height = `${wrap.offsetHeight}px`;
for (const s of sets) {
const on = s.dataset.set === tool;
s.classList.toggle("is-active", on);
s.inert = !on;
}
const next = sets.find((s) => s.dataset.set === tool)!;
requestAnimationFrame(() => {
wrap.classList.add("is-switching");
wrap.style.height = `${next.offsetHeight}px`;
timer = window.setTimeout(() => {
wrap.classList.remove("is-switching");
wrap.style.height = "";
}, SWITCH_MS);
});
announce();
});
}
</script>
<style>
.ol {
/* A quarter of a code line. */
--run-pad: calc(1.65em / 4);
--get: var(--alc-accent);
--put: #6da4b4;
--link: var(--alc-accent);
--hand: var(--alc-warn);
--over: var(--alc-danger);
--policy: var(--alc-warn);
--env: #a592d6;
margin: 0;
}
:global([data-theme="light"]) .ol {
--put: #3f7a8c;
--env: #6c55a8;
}
.ol__sr {
position: absolute;
width: 1px;
height: 1px;
overflow: hidden;
clip-path: inset(50%);
white-space: nowrap;
}
/* ---------- picker ---------- */
.ol__modes {
display: flex;
flex-wrap: wrap;
gap: 8px;
margin: 0 0 18px;
padding: 0;
border: 0;
}
.ol__modes label {
position: relative;
cursor: pointer;
}
.ol__modes input {
position: absolute;
inset: 0;
margin: 0;
opacity: 0;
cursor: pointer;
}
.ol__modes span {
display: inline-block;
padding: 6px 14px;
border: 1px dashed var(--alc-hairline-3);
border-radius: 999px;
font-size: 13px;
color: var(--alc-fg-2);
transition:
border-color 200ms ease,
background 200ms ease,
color 200ms ease;
}
.ol__modes label:hover span {
color: var(--alc-fg-1);
}
.ol__modes input:checked + span {
border-style: solid;
border-color: var(--alc-accent);
background: color-mix(in srgb, var(--alc-accent) 12%, transparent);
color: var(--alc-fg-1);
}
.ol__modes input:focus-visible + span {
outline: 2px solid var(--alc-accent);
outline-offset: 2px;
}
/* ---------- tool sets: crossfade with the height easing ---------- */
.ol__sets {
position: relative;
}
.ol__sets.is-switching {
transition: height 420ms cubic-bezier(0.2, 0, 0, 1);
}
.ol__set {
position: absolute;
top: 0;
left: 0;
right: 0;
opacity: 0;
visibility: hidden;
transition:
opacity 220ms ease,
visibility 0s linear 220ms;
}
.ol__set.is-active {
position: relative;
opacity: 1;
visibility: visible;
transition: opacity 320ms ease 120ms;
}
/* ---------- layout ---------- */
.ol__stage {
display: grid;
grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
column-gap: 24px;
align-items: center;
}
.ol__outs {
display: grid;
gap: 14px;
}
/* ---------- cards ---------- */
.ol__card {
min-width: 0;
border: 1px solid rgba(232, 220, 192, 0.1);
border-radius: 12px;
background: var(--alc-bg-code);
overflow: hidden;
}
.ol__pre {
margin: 0;
padding: 12px 0;
overflow-x: auto;
font-family: var(--alc-font-mono);
font-size: 12px;
line-height: 1.65;
color: var(--alc-code-var);
}
.ol__pre:focus-visible {
outline: 2px solid var(--alc-accent);
outline-offset: -2px;
}
.ol__line {
display: block;
max-height: 1.65em;
/* Clip only vertically (for the slide); long lines still scroll the
card sideways. */
overflow-x: visible;
overflow-y: clip;
padding: 0 16px;
white-space: pre;
transition:
max-height 380ms cubic-bezier(0.2, 0, 0, 1),
padding 380ms cubic-bezier(0.2, 0, 0, 1),
opacity 280ms ease,
background 300ms ease,
box-shadow 300ms ease;
}
/* File names inside the code card. */
.ol__line.is-file {
color: var(--alc-code-comment);
font-size: 11px;
}
.ol__line.is-file:not(:first-child) {
margin-top: 10px;
padding-top: 8px;
border-top: 1px solid rgba(232, 220, 192, 0.08);
max-height: none;
}
/* Colored runs in the outputs get a little room above and below. */
.ol__outs .ol__line.is-run-start {
padding-top: var(--run-pad);
}
.ol__outs .ol__line.is-run-end {
padding-bottom: var(--run-pad);
}
/* Lines that only exist with PutItem slide closed in the read state. */
.ol[data-state="read"] .ol__line.is-write {
max-height: 0;
padding-top: 0;
padding-bottom: 0;
opacity: 0;
}
.ol__line.is-get {
background: color-mix(in srgb, var(--get) 14%, transparent);
box-shadow: inset 3px 0 0 var(--get);
}
.ol__line.is-put {
background: color-mix(in srgb, var(--put) 16%, transparent);
box-shadow: inset 3px 0 0 var(--put);
}
.ol__line.is-link {
background: color-mix(in srgb, var(--link) 14%, transparent);
box-shadow: inset 3px 0 0 var(--link);
}
.ol__line.is-hand {
background: color-mix(in srgb, var(--hand) 12%, transparent);
box-shadow: inset 3px 0 0 var(--hand);
}
.ol__line.is-over {
background: color-mix(in srgb, var(--over) 16%, transparent);
box-shadow: inset 3px 0 0 var(--over);
}
.ol__line.is-policy {
background: color-mix(in srgb, var(--policy) 12%, transparent);
box-shadow: inset 3px 0 0 var(--policy);
}
.ol__line.is-env {
background: color-mix(in srgb, var(--env) 16%, transparent);
box-shadow: inset 3px 0 0 var(--env);
}
/* The env var: both capabilities inject it once PutItem is added. */
.ol__line.is-both {
background: linear-gradient(
90deg,
color-mix(in srgb, var(--get) 14%, transparent),
color-mix(in srgb, var(--put) 16%, transparent)
);
box-shadow:
inset 3px 0 0 var(--get),
inset 6px 0 0 var(--put);
}
.ol[data-state="read"] .ol__line.is-both {
background: color-mix(in srgb, var(--get) 14%, transparent);
box-shadow: inset 3px 0 0 var(--get);
}
.ol__key {
color: var(--alc-code-type);
}
.ol__str {
color: var(--alc-code-string);
}
.ol__dash {
color: var(--alc-code-comment);
}
/* ---------- legend + note ---------- */
.ol__legend {
display: flex;
flex-wrap: wrap;
gap: 8px 22px;
margin: 18px 0 0;
padding: 0;
list-style: none;
font-size: 13px;
color: var(--alc-fg-3);
}
.ol__legend li {
display: inline-flex;
align-items: center;
gap: 8px;
transition: opacity 280ms ease;
}
.ol[data-state="read"] .ol__legend li.is-write {
opacity: 0;
}
.ol__legend li::before {
content: "";
flex: none;
width: 12px;
height: 12px;
border-radius: 3px;
}
.ol__legend li.is-get::before {
background: var(--get);
}
.ol__legend li.is-put::before {
background: var(--put);
}
.ol__legend li.is-link::before {
background: var(--link);
}
.ol__legend li.is-hand::before {
background: var(--hand);
}
.ol__legend li.is-over::before {
background: var(--over);
}
.ol__legend li.is-policy::before {
background: var(--policy);
}
.ol__legend li.is-env::before {
background: var(--env);
}
.ol__legend code,
.ol__note code {
font-family: var(--alc-font-mono);
font-size: 0.92em;
color: var(--alc-fg-1);
}
.ol__note {
max-width: 680px;
margin: 10px 0 0;
font-size: 15px;
line-height: 1.6;
color: var(--alc-fg-2);
}
.ol[data-state="read"] .ol__note[data-when="write"],
.ol[data-state="write"] .ol__note[data-when="read"] {
display: none;
}
@media (max-width: 1000px) {
.ol__stage {
grid-template-columns: minmax(0, 1fr);
row-gap: 14px;
}
}
@media (max-width: 640px) {
.ol__pre {
font-size: 11px;
}
}
</style>