/** @effect-diagnostics anyUnknownInErrorContext:off */
import * as Effect from "effect/Effect";
type Op = { kind: "get"; prop: PropertyKey } | { kind: "call"; args: unknown[] };
interface ChainState {
readonly cached: Effect.Effect<unknown, any, any>;
readonly ops: ReadonlyArray<Op>;
}
/**
* Every proxy produced by {@link chain} is registered here so that a chain
* passed as an *argument* to another chain over the same `cached` effect
* (e.g. `` sql`... ${sql.insert(row)}` `` — the nested `sql.insert(row)` is
* itself a proxy) can be recognized and replayed against the same resolved
* root instead of being handed to the real client as an opaque proxy.
*/
const chainStates = new WeakMap<object, ChainState>();
/**
* Replay an op chain against a real value. `get` reads a property,
* `call` invokes — bound to the previous receiver so `this` resolves
* to the object the method was read from (drizzle's `select()` etc.
* read `this._.session`, so dropping `this` would throw).
*/
const replay = (
root: unknown,
ops: ReadonlyArray<Op>,
cached: Effect.Effect<unknown, any, any>,
): unknown => {
let cur: any = root;
let receiver: any = root;
for (const op of ops) {
if (op.kind === "get") {
receiver = cur;
cur = cur[op.prop];
} else {
cur = cur.apply(receiver, replayArgs(root, op.args, cached));
receiver = cur;
}
}
return cur;
};
/**
* Resolve nested chain proxies inside a call's arguments. Only proxies over
* the *same* `cached` effect can be replayed synchronously (the root is
* already resolved); proxies over a different effect pass through untouched.
* Returns the original array when nothing needed resolving, so identity-
* sensitive values (e.g. a `TemplateStringsArray` with its `raw` property)
* are preserved.
*/
const replayArgs = (
root: unknown,
args: ReadonlyArray<unknown>,
cached: Effect.Effect<unknown, any, any>,
): ReadonlyArray<unknown> => {
let out: unknown[] | undefined;
for (let i = 0; i < args.length; i++) {
const resolved = replayArg(root, args[i], cached);
if (resolved !== args[i]) {
out ??= [...args];
out[i] = resolved;
}
}
return out ?? args;
};
const replayArg = (
root: unknown,
arg: unknown,
cached: Effect.Effect<unknown, any, any>,
): unknown => {
if (arg === null || (typeof arg !== "object" && typeof arg !== "function")) {
return arg;
}
const state = chainStates.get(arg);
if (state?.cached === cached) {
return replay(root, state.ops, cached);
}
// Fragments may arrive wrapped in arrays (e.g. `sql.and([a, b])`).
if (Array.isArray(arg)) {
return replayArgs(root, arg, cached);
}
return arg;
};
/**
* Wrap a cached `Effect<T>` in a chainable Proxy so callers can use the
* returned value as if it were `T` itself — every property read and call
* records a step, and the chain is replayed against the resolved value
* when it's finally yielded as an Effect.
*
* Compare:
*
* ```typescript
* // Without proxyChain — caller has to yield the cached Effect first:
* const conn = yield* makeConnection(); // Effect<Db>
* fetch: Effect.gen(function* () {
* const db = yield* conn;
* const rows = yield* db.select().from(users);
* });
*
* // With proxyChain — caller treats the return as the value directly:
* const db = proxyChain(yield* Effect.cached(makeDb)); // T
* fetch: Effect.gen(function* () {
* const rows = yield* db.select().from(users);
* });
* ```
*
* The chain ends when the proxy is yielded as an Effect — the resolved
* value at that point must be a `Yieldable` (an Effect, drizzle query
* builder, etc). Anything before that is recorded as ops.
*
* A chain passed as an *argument* to another chain over the same effect —
* e.g. `` sql`INSERT INTO users ${sql.insert(row)}` ``, where `sql.insert(row)`
* is itself a deferred proxy — is replayed against the same resolved root
* before the outer call runs, so synchronous fragment helpers compose.
*/
export const proxyChain = <T>(cached: Effect.Effect<T, any, any>): T => chain(cached) as T;
/**
* Property reads the Effect runtime uses as *brand probes* — `symbol` keys
* and `~effect/...` type-id strings (`~effect/Exit`, `~effect/Effect`, …).
* The fiber's generator runner distinguishes a yielded Effect from an Exit
* with `value[ExitTypeId] !== undefined` (effect ≥ 4.0.0-rc.113; earlier
* releases used `in`, which the `has` trap already answers). Recording such
* a read as a chain step would hand back a truthy proxy, so the runner
* would treat every chain as an already-settled Exit and resume the
* generator with `proxy.value` — another proxy — instead of running it.
* Brand probes therefore answer `undefined` when the underlying effect
* lacks the key; the `has` trap keeps `in`-based probes correct too.
*/
const isBrandProbe = (prop: PropertyKey): boolean =>
typeof prop === "symbol" || (typeof prop === "string" && prop.startsWith("~effect/"));
const chain = (cached: Effect.Effect<unknown, any, any>, ops: ReadonlyArray<Op> = []): unknown => {
const effect = Effect.flatMap(
cached,
(root) => replay(root, ops, cached) as Effect.Effect<unknown, unknown, unknown>,
);
const proxy = new Proxy(function () {}, {
get(_, prop) {
if (Reflect.has(effect, prop)) {
return Reflect.get(effect, prop);
}
if (isBrandProbe(prop)) {
return undefined;
}
return chain(cached, [...ops, { kind: "get", prop }]);
},
has(target, prop) {
return Reflect.has(target, prop) || Reflect.has(effect, prop);
},
apply(_, __, args) {
return chain(cached, [...ops, { kind: "call", args }]);
},
});
chainStates.set(proxy, { cached, ops });
return proxy;
};