@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 239 lines 8.92 KB
Raw
1 /**
2 * Phantom-typed JSONata value references for the Step Functions program DSL.
3 *
4 * An {@link Expr} is a *typed reference to a value that will exist at
5 * execution time* — the execution input, the result of a previous state
6 * (an ASL variable), the current Map item, etc. Property access is a Proxy
7 * that builds up a JSONata path (`$states.context.Execution.Input.customerId`
8 * style); comparator helpers (`eq`, `gt`, `and`, …) build boolean
9 * expressions for Choice states.
10 *
11 * The same expression AST has two interpreters:
12 * - `compile.ts` renders it to a `{% ... %}` JSONata string in the ASL
13 * definition,
14 * - `simulate.ts` evaluates it in-process against a variable environment.
15 */
16
17 /** Brand key carried by every {@link Expr} proxy. */
18 export const ExprTypeId = Symbol.for("alchemy/AWS/StepFunctions/JsonataExpr");
19 export type ExprTypeId = typeof ExprTypeId;
20
21 /** The value roots a JSONata path can start from. */
22 export type ExprRoot =
23 /** The state machine execution input (`$states.context.Execution.Input`). */
24 | { readonly kind: "input" }
25 /** An ASL variable assigned by an earlier state (`$name`). */
26 | { readonly kind: "variable"; readonly name: string }
27 /** The callback task token (`$states.context.Task.Token`). */
28 | { readonly kind: "token" };
29
30 /** Binary comparison / boolean operators supported by the expression AST. */
31 export type ExprOperator = "=" | "!=" | ">" | ">=" | "<" | "<=" | "and" | "or";
32
33 /**
34 * The untyped expression AST behind an {@link Expr} proxy. Plain data — both
35 * the ASL printer and the local simulator interpret it structurally.
36 */
37 export type ExprNode =
38 | { readonly _: "root"; readonly root: ExprRoot }
39 | { readonly _: "prop"; readonly parent: ExprNode; readonly name: string }
40 | { readonly _: "literal"; readonly value: unknown }
41 | {
42 readonly _: "binop";
43 readonly op: ExprOperator;
44 readonly left: ExprNode;
45 readonly right: ExprNode;
46 }
47 | { readonly _: "not"; readonly inner: ExprNode }
48 /** Raw JSONata escape hatch — compiles verbatim, unsupported by simulate. */
49 | { readonly _: "raw"; readonly jsonata: string };
50
51 interface ExprBrand<T> {
52 readonly [ExprTypeId]: {
53 readonly node: ExprNode;
54 readonly _T: (_: never) => T;
55 };
56 }
57
58 /**
59 * A typed JSONata value reference. Property access is typed: given
60 * `input: Expr<{ order: { total: number } }>`, `input.order.total` is an
61 * `Expr<number>` that renders as `….order.total`.
62 *
63 * Arrays are opaque references (pass them to `Sfn.forEach`); primitives are
64 * leaf references usable in comparators and payloads.
65 */
66 export type Expr<T = any> = ExprBrand<T> &
67 ([T] extends [readonly any[]]
68 ? {}
69 : [T] extends [object]
70 ? { readonly [K in keyof T & string]-?: Expr<T[K]> }
71 : {});
72
73 /** A value of `T`, a typed reference to one, or `Expr<any>` (untyped hole). */
74 export type ExprInput<T> = T | Expr<T> | Expr<any>;
75
76 /** Recursively replace `Expr<T>` references with their referent type. */
77 export type UnwrapExpr<T> =
78 T extends Expr<infer A>
79 ? A
80 : T extends readonly (infer U)[]
81 ? UnwrapExpr<U>[]
82 : T extends object
83 ? { [K in keyof T]: UnwrapExpr<T[K]> }
84 : T;
85
86 /** Runtime guard for {@link Expr} proxies. */
87 export const isExpr = (value: unknown): value is Expr<any> =>
88 (typeof value === "object" || typeof value === "function") &&
89 value !== null &&
90 (value as ExprBrand<any>)[ExprTypeId] !== undefined;
91
92 /** Extract the AST node from an {@link Expr}. */
93 export const nodeOf = (expr: Expr<any>): ExprNode => expr[ExprTypeId].node;
94
95 /**
96 * Wrap an AST node in the typed Proxy. String property access appends a
97 * `prop` node; everything else (symbols, `then`, iteration protocols) is
98 * absent so the proxy never masquerades as a Promise, Effect, or Output.
99 */
100 export const makeExpr = <T>(node: ExprNode): Expr<T> => {
101 const brand = { node, _T: undefined as never };
102 return new Proxy(
103 {},
104 {
105 get: (_, prop) => {
106 if (prop === ExprTypeId) return brand;
107 if (typeof prop !== "string") return undefined;
108 // `toJSON`/`then` lookups happen when host code probes values
109 // (JSON.stringify, await). Treat them as path segments would be
110 // wrong; renderers detect Exprs *before* serialization, so any
111 // such probe reaching here is a misuse — return a child expr
112 // anyway (harmless, typed access never sees these names).
113 return makeExpr({ _: "prop", parent: node, name: prop });
114 },
115 has: (_, prop) => prop === ExprTypeId,
116 },
117 ) as Expr<T>;
118 };
119
120 const literalNode = (value: unknown): ExprNode => ({ _: "literal", value });
121
122 /** Lift a value or Expr to an AST node. */
123 export const toNode = (value: unknown): ExprNode =>
124 isExpr(value) ? nodeOf(value) : literalNode(value);
125
126 /** Lift a constant into a typed expression. */
127 export const literal = <T>(value: T): Expr<T> => makeExpr(literalNode(value));
128
129 /**
130 * Raw JSONata escape hatch. Compiles verbatim into the definition
131 * (`{% <jsonata> %}`); `simulate` rejects it with a `SimulateError`.
132 */
133 export const jsonata = <T = unknown>(expression: string): Expr<T> =>
134 makeExpr({ _: "raw", jsonata: expression });
135
136 const binop = (op: ExprOperator, left: unknown, right: unknown): Expr<boolean> =>
137 makeExpr({ _: "binop", op, left: toNode(left), right: toNode(right) });
138
139 /** `left = right` (JSONata equality). */
140 export const eq = <T>(left: ExprInput<T>, right: ExprInput<T>): Expr<boolean> =>
141 binop("=", left, right);
142 /** `left != right`. */
143 export const ne = <T>(left: ExprInput<T>, right: ExprInput<T>): Expr<boolean> =>
144 binop("!=", left, right);
145 /** `left > right`. */
146 export const gt = (left: ExprInput<number>, right: ExprInput<number>): Expr<boolean> =>
147 binop(">", left, right);
148 /** `left >= right`. */
149 export const gte = (left: ExprInput<number>, right: ExprInput<number>): Expr<boolean> =>
150 binop(">=", left, right);
151 /** `left < right`. */
152 export const lt = (left: ExprInput<number>, right: ExprInput<number>): Expr<boolean> =>
153 binop("<", left, right);
154 /** `left <= right`. */
155 export const lte = (left: ExprInput<number>, right: ExprInput<number>): Expr<boolean> =>
156 binop("<=", left, right);
157 /** Boolean conjunction. */
158 export const and = (
159 ...conditions: [ExprInput<boolean>, ExprInput<boolean>, ...ExprInput<boolean>[]]
160 ): Expr<boolean> =>
161 conditions
162 .slice(1)
163 .reduce<Expr<boolean>>(
164 (acc, c) => binop("and", acc, c),
165 isExpr(conditions[0]) ? (conditions[0] as Expr<boolean>) : literal(conditions[0] as boolean),
166 );
167 /** Boolean disjunction. */
168 export const or = (
169 ...conditions: [ExprInput<boolean>, ExprInput<boolean>, ...ExprInput<boolean>[]]
170 ): Expr<boolean> =>
171 conditions
172 .slice(1)
173 .reduce<Expr<boolean>>(
174 (acc, c) => binop("or", acc, c),
175 isExpr(conditions[0]) ? (conditions[0] as Expr<boolean>) : literal(conditions[0] as boolean),
176 );
177 /** Boolean negation (`$not(...)`). */
178 export const not = (condition: ExprInput<boolean>): Expr<boolean> =>
179 makeExpr({ _: "not", inner: toNode(condition) });
180
181 /** The execution-input root expression. */
182 export const inputExpr = <T>(): Expr<T> => makeExpr({ _: "root", root: { kind: "input" } });
183
184 /** A reference to the ASL variable `name`. */
185 export const variableExpr = <T>(name: string): Expr<T> =>
186 makeExpr({ _: "root", root: { kind: "variable", name } });
187
188 /**
189 * The callback task token (`$states.context.Task.Token`) — embed inside
190 * `Sfn.waitForTaskToken` arguments so the callback side can complete the
191 * task via `SendTaskSuccess`/`SendTaskFailure`.
192 */
193 export const taskToken: Expr<string> = makeExpr({
194 _: "root",
195 root: { kind: "token" },
196 });
197
198 // ---------------------------------------------------------------------------
199 // JSONata printer (used by compile.ts)
200 // ---------------------------------------------------------------------------
201
202 const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
203
204 const renderRoot = (root: ExprRoot): string => {
205 switch (root.kind) {
206 case "input":
207 return "$states.context.Execution.Input";
208 case "variable":
209 return `$${root.name}`;
210 case "token":
211 return "$states.context.Task.Token";
212 }
213 };
214
215 /** Render an AST node to JSONata source (without the `{% %}` wrapper). */
216 export const renderNode = (node: ExprNode): string => {
217 switch (node._) {
218 case "root":
219 return renderRoot(node.root);
220 case "prop": {
221 const parent =
222 node.parent._ === "root" || node.parent._ === "prop"
223 ? renderNode(node.parent)
224 : `(${renderNode(node.parent)})`;
225 return IDENT.test(node.name) ? `${parent}.${node.name}` : `${parent}.\`${node.name}\``;
226 }
227 case "literal":
228 return JSON.stringify(node.value === undefined ? null : node.value);
229 case "binop":
230 return `(${renderNode(node.left)} ${node.op} ${renderNode(node.right)})`;
231 case "not":
232 return `$not(${renderNode(node.inner)})`;
233 case "raw":
234 return node.jsonata;
235 }
236 };
237
238 /** Render an {@link Expr} to a `{% ... %}`-wrapped ASL JSONata string. */
239 export const renderExprString = (expr: Expr<any>): string => `{% ${renderNode(nodeOf(expr))} %}`;