TypeScript client

Package: @eelgrass/client (clients/typescript).

Export paths

Import	Role
@eelgrass/client	eelgrass tagged template, EelgrassQuery, EelgrassParam, EelgrassExecutor
@eelgrass/client/money	Money class
@eelgrass/client/shape	Typecheck JSON contract (EelgrassType, EelgrassShape, decode)
@eelgrass/client/codegen	Escape-hatch tagged-template codegen (generateTypes)
@eelgrass/client/named-codegen	Named-query codegen (generateNamedQueryModules)
@eelgrass/client/config	eelgrass.config.json parse + glob helper (parseConfig, DEFAULT_CONFIG)

CLI bin: eelgrass-codegen.

Preferred path: named queries

1. Write schemas + named queries as .eel
2. Run eelgrass-codegen --config eelgrass.config.json
3. Import generated functions; pass them to an EelgrassExecutor

import { GetPaid } from "./generated/users.queries";
import { Money } from "@eelgrass/client/money";

const rows = await exec.execute(
  GetPaid({ min_balance: Money.minor(50_00n, "USD") }),
);
// rows typed from the query's select shape

Money constructors that exist today:

import { Money } from "@eelgrass/client/money";

Money.minor(4999n, "USD");     // minor units (cents)
Money.parse("49.99", "USD");   // decimal string only. Not a number.

There is no Money.usd. Cross-currency arithmetic is rejected at runtime. Same doctrine as the language.

See Named queries and Examples (examples/eelgrass.config.json).

Config

eelgrass.config.json fields (@eelgrass/client/config):

Field	Meaning	Default
schemas	Schema .eel paths (merged in order)	["schemas.eel"]
queries	Glob(s) for named-query .eel files	["src/queries/**/*.eel"]
outDir	Generated TypeScript modules	"src/generated"
moneyImport	Optional Money import path override	@eelgrass/client/money

Codegen shells out to the eelgrass binary (typecheck-queries). Set EELGRASS_BINARY if it is not on PATH.

Escape hatch

import { eelgrass } from "@eelgrass/client";
import type { EelgrassExecutor, EelgrassQuery } from "@eelgrass/client";

const q: EelgrassQuery = eelgrass`users |> select { id, name }`;
// await exec.execute(q)

Tagged-template codegen (legacy):

eelgrass-codegen <schemas.eel> <output.ts> <src1.ts> [src2.ts ...]

Use for one-offs and tests. Prefer named queries for day-to-day app work. Until a build plugin lands, the bare eelgrass…`` template returns EelgrassQuery with result types defaulting to unknown[] unless escape-hatch codegen wraps them.

EelgrassExecutor

interface EelgrassExecutor {
  execute<TRows>(
    q: EelgrassQuery<TRows>,
    opts?: { tenant?: string },
  ): Promise<TRows[]>;
  atomic<TRowses extends unknown[]>(
    qs: { [K in keyof TRowses]: EelgrassQuery<TRowses[K]> },
    opts?: { tenant?: string },
  ): Promise<TRowses>;
}

Transport reality

EelgrassExecutor is the contract. A shipping HTTP/IPC driver is not in the package yet. Today you:

• drive the engine via eelgrass run / Studio / wasm ABI, or
• implement EelgrassExecutor against eelgrass serve's /query for experiments.

See Status.