eraspace 0.0.0-stage → 0.2.0

package/sdk/src/server/index.ts

@@ -0,0 +1,635 @@
+// Generated by scripts/generate-server-api.ts. Edit api/server-api.ts or api/server.ts.in.
+// eraspace/server: capsule definition API.
+//
+// V8 supplies this module from the engine bootstrap. These descriptors also run in Node for tooling and tests;
+// their types drive client and server inference.
+//
+// Type design. `ctx.db` must be typed from `schema` even though both live in the same object literal:
+//
+//   capsule({ schema: {...}, queries: { list: query(async (ctx) => ctx.db.todos.collect()) } })
+//
+// `query()` is generic over the schema `S` and returns a *callable* definition type. TypeScript skips nested calls
+// to generic functions that return functions in its first inference pass over `capsule()`'s argument, so `S` is
+// inferred from `schema` first. In the second pass `query(...)` is checked with the contextual type
+// `QueryDefinition<S>`, and return-type inference hands `S` to the handler's `ctx`. Without the call signature this
+// does not work (see sdk/test/types).
+
+// ---------------------------------------------------------------------------------------------------------------
+// Ids and validators
+
+declare const tableBrand: unique symbol;
+
+/** A row id tagged with the table it points at. Any `Id<T>` is a `string`. */
+export type Id<TableName extends string = string> = string & { readonly [tableBrand]?: TableName };
+
+export type FieldKind = "string" | "number" | "boolean" | "id" | "userId" | "any" | "array" | "object";
+
+/**
+ * One column (or nested value) validator: what `string()`, `number()`, `id()`, ... return.
+ * `Out` is the stored/read type, `In` the accepted write type.
+ */
+export interface Field<Out = unknown, In = Out, Opt extends boolean = boolean, Def extends boolean = boolean> {
+  readonly kind: FieldKind;
+  readonly isOptional: Opt;
+  readonly hasDefault: Def;
+  readonly defaultValue?: Out;
+  readonly table?: string;
+  readonly element?: AnyField;
+  readonly fields?: Record<string, AnyField>;
+  /** Allow absence; writes accept null to clear the field. */
+  optional(): Field<Out, In, true, Def>;
+  /** Fill omitted insert values with this default. */
+  default(value: In): Field<Out, In, Opt, true>;
+  /** Phantom inference marker, never set at runtime. */
+  readonly __types?: { out: Out; in: In };
+}
+
+export type AnyField = Field<any, any, boolean, boolean>;
+export type FieldMap = Record<string, AnyField>;
+
+type FieldOut<F> = F extends Field<infer O, any, any, any> ? O : never;
+type FieldIn<F> = F extends Field<any, infer I, any, any> ? I : never;
+type IsOpt<F> = F extends Field<any, any, infer O, any> ? (O extends true ? true : false) : false;
+type HasDef<F> = F extends Field<any, any, any, infer D> ? (D extends true ? true : false) : false;
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+/** Keys that may be absent on a read: optional without a default. */
+type ReadOptionalKeys<F extends FieldMap> = {
+  [K in keyof F]: IsOpt<F[K]> extends true ? (HasDef<F[K]> extends true ? never : K) : never;
+}[keyof F];
+type ReadRequiredKeys<F extends FieldMap> = Exclude<keyof F, ReadOptionalKeys<F>>;
+type WriteOptionalKeys<F extends FieldMap> = {
+  [K in keyof F]: IsOpt<F[K]> extends true ? K : HasDef<F[K]> extends true ? K : never;
+}[keyof F];
+type WriteRequiredKeys<F extends FieldMap> = Exclude<keyof F, WriteOptionalKeys<F>>;
+type Nullable<F, T> = IsOpt<F> extends true ? T | null : T;
+
+/** The fields of a stored row (without `id`/`createdAt`). */
+export type InferFields<F extends FieldMap> = Simplify<
+  { [K in ReadRequiredKeys<F>]: FieldOut<F[K]> } & { [K in ReadOptionalKeys<F>]?: FieldOut<F[K]> }
+>;
+/** What `insert`/`replace` accept. */
+export type InferInsert<F extends FieldMap> = Simplify<
+  { [K in WriteRequiredKeys<F>]: FieldIn<F[K]> } & { [K in WriteOptionalKeys<F>]?: Nullable<F[K], FieldIn<F[K]>> }
+>;
+/** What `update` accepts. `null` removes an optional field. */
+export type InferPatch<F extends FieldMap> = Simplify<{ [K in keyof F]?: Nullable<F[K], FieldIn<F[K]>> }>;
+
+function makeField(kind: FieldKind, extra: Partial<Record<string, unknown>> = {}): any {
+  const base = {
+    kind,
+    isOptional: false,
+    hasDefault: false,
+    ...extra,
+    optional() {
+      return makeField(kind, { ...strip(this), isOptional: true });
+    },
+    default(value: unknown) {
+      return makeField(kind, { ...strip(this), hasDefault: true, defaultValue: value });
+    },
+    toJSON() {
+      return describeField(this as AnyField);
+    },
+  };
+  return base;
+}
+
+function strip(f: any): Record<string, unknown> {
+  const { kind: _k, optional: _o, default: _d, toJSON: _t, ...rest } = f;
+  return rest;
+}
+
+function describeField(f: AnyField): Record<string, unknown> {
+  const out: Record<string, unknown> = { type: f.kind };
+  if (f.isOptional) out.optional = true;
+  if (f.hasDefault) out.default = f.defaultValue;
+  if (f.table) out.table = f.table;
+  if (f.element) out.element = describeField(f.element);
+  if (f.fields) out.fields = Object.fromEntries(Object.entries(f.fields).map(([k, v]) => [k, describeField(v)]));
+  return out;
+}
+
+export function string(): Field<string, string, false, false> {
+  return makeField("string");
+}
+export function number(): Field<number, number, false, false> {
+  return makeField("number");
+}
+export function boolean(): Field<boolean, boolean, false, false> {
+  return makeField("boolean");
+}
+/** A row id from the named table. Reads as `Id<table>`, accepts any string on write. */
+export function id<T extends string>(table: T): Field<Id<T>, string, false, false> {
+  return makeField("id", { table });
+}
+/** A user reference (in v1 a per-browser guest id from `ctx.auth`). */
+export function userId(): Field<string, string, false, false> {
+  return makeField("userId");
+}
+export function any(): Field<any, any, false, false> {
+  return makeField("any");
+}
+export function array<F extends AnyField>(element: F): Field<FieldOut<F>[], FieldIn<F>[], false, false> {
+  return makeField("array", { element });
+}
+export function object<F extends FieldMap>(fields: F): Field<InferFields<F>, InferInsert<F>, false, false> {
+  return makeField("object", { fields });
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Tables and schema
+
+export type IndexMap = Record<string, readonly string[]>;
+
+export interface TableDefinition<F extends FieldMap = FieldMap, I extends IndexMap = {}> {
+  readonly kind: "table";
+  readonly fields: F;
+  readonly indexes: I;
+  /** Declare an index with an implicit createdAt, id suffix. */
+  index<const N extends string, const Fs extends readonly (keyof F & string)[]>(
+    name: N,
+    fields: Fs,
+  ): TableDefinition<F, Simplify<I & { [P in N]: Fs }>>;
+}
+
+export type AnyTable = TableDefinition<any, any>;
+export type Schema = Record<string, AnyTable>;
+/** The schema a capsule gets when it declares none. Tables and fields are untyped. */
+export type DefaultSchema = Record<string, TableDefinition<Record<string, Field<any, any, boolean, boolean>>, IndexMap>>;
+
+export function table<const F extends FieldMap>(fields: F): TableDefinition<F, {}> {
+  const indexes: Record<string, readonly string[]> = {};
+  const def: any = {
+    kind: "table",
+    fields,
+    indexes,
+    index(name: string, idx: readonly string[]) {
+      if (name === "by_creation" || name in indexes) throw new Error(`Duplicate index ${name}`);
+      indexes[name] = idx;
+      return def;
+    },
+    toJSON() {
+      return {
+        fields: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, describeField(v)])),
+        indexes,
+      };
+    },
+  };
+  return def;
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Documents and the database
+
+type IsLoose<S> = string extends keyof S ? true : false;
+type TableFields<S, T extends keyof S> = S[T] extends TableDefinition<infer F, any> ? F : never;
+type TableIndexes<S, T extends keyof S> = S[T] extends TableDefinition<any, infer I> ? I : never;
+
+/** A stored row of table `T`: its fields plus `id` and `createdAt` (epoch ms). */
+export type Doc<S extends Schema = DefaultSchema, T extends keyof S & string = keyof S & string> =
+  IsLoose<S> extends true
+    ? { id: Id<T>; createdAt: number; [field: string]: any }
+    : Simplify<{ id: Id<T>; createdAt: number } & InferFields<TableFields<S, T>>>;
+
+export interface PaginationOptions {
+  cursor: string | null;
+  numItems: number;
+}
+export interface PaginationResult<T> {
+  page: T[];
+  isDone: boolean;
+  continueCursor: string;
+}
+
+/** Marker returned by an index range callback. */
+export interface IndexRange {
+  readonly __indexRange: true;
+}
+
+type Head<Fs extends readonly string[]> = Fs extends readonly [infer H extends string, ...any[]] ? H : never;
+type Tail<Fs extends readonly string[]> = Fs extends readonly [any, ...infer R extends string[]] ? R : [];
+type ValueOf<D, K> = K extends keyof D
+  ? undefined extends D[K]
+    ? Exclude<D[K], undefined> | null
+    : D[K]
+  : never;
+type RangeValue<D, K> = K extends keyof D ? Exclude<D[K], undefined> : never;
+
+/** `q` in `withIndex(name, q => ...)`: an equality prefix, then one range on the next index field. */
+export interface IndexRangeBuilder<D, Fs extends readonly string[]> extends IndexRange {
+  eq<K extends Head<Fs>>(field: K, value: ValueOf<D, K>): IndexRangeBuilder<D, Tail<Fs>>;
+  gt<K extends Head<Fs>>(field: K, value: RangeValue<D, K>): UpperBoundBuilder<D, K>;
+  gte<K extends Head<Fs>>(field: K, value: RangeValue<D, K>): UpperBoundBuilder<D, K>;
+  lt<K extends Head<Fs>>(field: K, value: RangeValue<D, K>): LowerBoundBuilder<D, K>;
+  lte<K extends Head<Fs>>(field: K, value: RangeValue<D, K>): LowerBoundBuilder<D, K>;
+}
+export interface UpperBoundBuilder<D, K> extends IndexRange {
+  lt(field: K, value: RangeValue<D, K>): IndexRange;
+  lte(field: K, value: RangeValue<D, K>): IndexRange;
+}
+export interface LowerBoundBuilder<D, K> extends IndexRange {
+  gt(field: K, value: RangeValue<D, K>): IndexRange;
+  gte(field: K, value: RangeValue<D, K>): IndexRange;
+}
+
+/** An ordered index scan. Terminals are async. */
+export interface OrderedQuery<D> {
+  collect(): Promise<D[]>;
+  take(n: number): Promise<D[]>;
+  /** Return null when no row matches. */
+  first(): Promise<D | null>;
+  /** Return null when no row matches; throw if more than one row matches. */
+  unique(): Promise<D | null>;
+  count(): Promise<number>;
+  paginate(options: PaginationOptions): Promise<PaginationResult<D>>;
+}
+export interface IndexQuery<D> extends OrderedQuery<D> {
+  order(order: "asc" | "desc"): OrderedQuery<D>;
+}
+
+type IndexFieldsOf<I, N> = N extends "by_creation"
+  ? ["createdAt"]
+  : N extends keyof I
+    ? I[N] extends readonly string[]
+      ? [...I[N], "createdAt"]
+      : never
+    : never;
+
+/** Read access to one table. Table-level `order/collect/take/...` scan the implicit `by_creation` index. */
+export interface ReadTable<D, I extends IndexMap> extends IndexQuery<D> {
+  get(id: string): Promise<D | null>;
+  withIndex<N extends (keyof I & string) | "by_creation">(
+    name: N,
+    range?: (q: IndexRangeBuilder<D, IndexFieldsOf<I, N>>) => IndexRange,
+  ): IndexQuery<D>;
+}
+export interface WriteTable<D, I extends IndexMap, Ins, Patch, T extends string = string> extends ReadTable<D, I> {
+  insert(doc: Ins): Promise<Id<T>>;
+  /** Shallow merge; null removes an optional field. */
+  update(id: string, patch: Patch): Promise<void>;
+  replace(id: string, doc: Ins): Promise<void>;
+  delete(id: string): Promise<void>;
+  /** Shallow merge; null removes an optional field. */
+  patch(id: string, patch: Patch): Promise<void>;
+}
+
+type LooseDoc = Doc<DefaultSchema, string>;
+interface LooseQuery extends OrderedQuery<LooseDoc> {
+  order(order: "asc" | "desc"): OrderedQuery<LooseDoc>;
+}
+/** Untyped table access (no schema type available). Any typed table is assignable to it. */
+interface LooseRead extends LooseQuery {
+  get(id: string): Promise<LooseDoc | null>;
+  withIndex(name: string, range?: (q: any) => any): LooseQuery;
+}
+interface LooseWrite extends LooseRead {
+  insert(doc: Record<string, any>): Promise<Id<any>>;
+  update(id: string, patch: Record<string, any>): Promise<void>;
+  patch(id: string, patch: Record<string, any>): Promise<void>;
+  replace(id: string, doc: Record<string, any>): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+
+/** Read-only `ctx.db`, used by queries and actions. */
+export type DbContext<S extends Schema = DefaultSchema> =
+  IsLoose<S> extends true
+    ? Record<string, LooseRead>
+    : { readonly [T in keyof S & string]: ReadTable<Doc<S, T>, TableIndexes<S, T>> };
+
+/** Writable `ctx.db`, used by mutations and writable endpoints. */
+export type MutationDbContext<S extends Schema = DefaultSchema> =
+  IsLoose<S> extends true
+    ? Record<string, LooseWrite>
+    : {
+        readonly [T in keyof S & string]: WriteTable<
+          Doc<S, T>,
+          TableIndexes<S, T>,
+          InferInsert<TableFields<S, T>>,
+          InferPatch<TableFields<S, T>>,
+          T
+        >;
+      };
+
+// ---------------------------------------------------------------------------------------------------------------
+// Handler contexts
+
+export interface LogContext {
+  debug(message: string, data?: unknown): void;
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+}
+
+export interface Identity {
+  userId: string;
+  isGuest: true;
+  displayName: string;
+}
+export interface AuthContext {
+  /** The caller's guest id, or null for an anonymous request. */
+  readonly userId: string | null;
+  /** Throw if the request has no identity. */
+  requireIdentity(): Identity;
+  getIdentity(): Identity | null;
+  requireSignedIn(): never;
+  readonly isGuest: true;
+  readonly isSignedIn: false;
+}
+
+interface BaseContext {
+  log: LogContext;
+  /** Deployment environment, never sent to the client. */
+  env: Record<string, string | undefined>;
+  auth: AuthContext;
+}
+
+// The contexts are parameterised by their db type (not the schema) so that TypeScript compares them structurally:
+// a typed `ServerContext<typeof schema>` is assignable to the untyped `ServerContext`.
+interface DbHolder<Db> extends BaseContext {
+  db: Db;
+}
+interface ActionHolder<Db> extends DbHolder<Db> {
+  runQuery(name: string, ...args: any[]): Promise<any>;
+  runMutation(name: string, ...args: any[]): Promise<any>;
+  runAction(name: string, ...args: unknown[]): Promise<unknown>;
+}
+
+/** The `ctx` a `query()` (or a `readOnly` endpoint) receives. */
+export type QueryServerContext<S extends Schema = DefaultSchema> = DbHolder<DbContext<S>>;
+/** The `ctx` a `mutation()` or writable `endpoint()` receives. Its `db` can write. */
+export type ServerContext<S extends Schema = DefaultSchema> = DbHolder<MutationDbContext<S>>;
+/** The `ctx` an `action()` receives: read-only db plus `runQuery`/`runMutation`. Use global `fetch` for HTTP. */
+export type ActionServerContext<S extends Schema = DefaultSchema> = ActionHolder<DbContext<S>>;
+
+// ---------------------------------------------------------------------------------------------------------------
+// Handlers
+
+export interface ToolOptions<A extends FieldMap | undefined = FieldMap | undefined> {
+  /** What the tool does, what it returns, and where its inputs come from. Written for an agent. */
+  description: string;
+  args?: A;
+}
+export interface HandlerOptions<A extends FieldMap | undefined = FieldMap | undefined> {
+  tool?: ToolOptions<A>;
+}
+
+export type HandlerKind = "query" | "mutation" | "action" | "endpoint";
+
+interface DefinitionBase<K extends HandlerKind, A extends any[], R> {
+  readonly kind: K;
+  readonly tool?: ToolOptions;
+  /** Phantom marker for the client types. Never set at runtime. */
+  readonly __types?: { args: A; result: R };
+}
+
+export interface QueryDefinition<S extends Schema, A extends any[], R> extends DefinitionBase<"query", A, R> {
+  (ctx: QueryServerContext<S>, ...args: A): Promise<R>;
+}
+export interface MutationDefinition<S extends Schema, A extends any[], R> extends DefinitionBase<"mutation", A, R> {
+  (ctx: ServerContext<S>, ...args: A): Promise<R>;
+}
+export interface ActionDefinition<S extends Schema, A extends any[], R> extends DefinitionBase<"action", A, R> {
+  (ctx: ActionServerContext<S>, ...args: A): Promise<R>;
+}
+
+type ToolArgs<TA extends FieldMap> = InferFields<TA>;
+
+function define(kind: HandlerKind, fn: Function, options?: HandlerOptions<any>): any {
+  const def: any = (ctx: unknown, ...args: unknown[]) => Promise.resolve(fn(ctx, ...args));
+  def.kind = kind;
+  def.handler = fn;
+  if (options?.tool) def.tool = options.tool;
+  return def;
+}
+
+/** A read-only handler. Clients subscribe to it with `useQuery` and get live updates. */
+export function query<S extends Schema, const TA extends FieldMap, R>(
+  handler: (ctx: QueryServerContext<S>, args: ToolArgs<TA>) => R,
+  options: { tool: ToolOptions<TA> & { args: TA } },
+): QueryDefinition<S, [args: ToolArgs<TA>], Awaited<R>>;
+export function query<S extends Schema, A extends any[], R>(
+  handler: (ctx: QueryServerContext<S>, ...args: A) => R,
+  options?: HandlerOptions<undefined>,
+): QueryDefinition<S, A, Awaited<R>>;
+export function query(handler: Function, options?: HandlerOptions<any>): any {
+  return define("query", handler, options);
+}
+
+/** A serializable write. Conflicts retry the handler; fetch is forbidden. */
+export function mutation<S extends Schema, const TA extends FieldMap, R>(
+  handler: (ctx: ServerContext<S>, args: ToolArgs<TA>) => R,
+  options: { tool: ToolOptions<TA> & { args: TA } },
+): MutationDefinition<S, [args: ToolArgs<TA>], Awaited<R>>;
+export function mutation<S extends Schema, A extends any[], R>(
+  handler: (ctx: ServerContext<S>, ...args: A) => R,
+  options?: HandlerOptions<undefined>,
+): MutationDefinition<S, A, Awaited<R>>;
+export function mutation(handler: Function, options?: HandlerOptions<any>): any {
+  return define("mutation", handler, options);
+}
+
+/** Server work with read-only db access, `fetch`, and `ctx.runQuery`/`ctx.runMutation`. */
+export function action<S extends Schema, const TA extends FieldMap, R>(
+  handler: (ctx: ActionServerContext<S>, args: ToolArgs<TA>) => R,
+  options: { tool: ToolOptions<TA> & { args: TA } },
+): ActionDefinition<S, [args: ToolArgs<TA>], Awaited<R>>;
+export function action<S extends Schema, A extends any[], R>(
+  handler: (ctx: ActionServerContext<S>, ...args: A) => R,
+  options?: HandlerOptions<undefined>,
+): ActionDefinition<S, A, Awaited<R>>;
+export function action(handler: Function, options?: HandlerOptions<any>): any {
+  return define("action", handler, options);
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Endpoints
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+
+export interface EndpointRoute {
+  method: HttpMethod;
+  /** Path under the app, e.g. `/api/hook`. Served at `/<app>/api/hook`. */
+  path: string;
+  /** Read-only endpoints get a read-only `ctx.db`. */
+  readOnly?: boolean;
+}
+
+export interface EndpointHeaders {
+  get(name: string): string | null;
+  has(name: string): boolean;
+  entries(): [string, string][];
+  keys(): string[];
+}
+export interface EndpointQuery {
+  get(name: string): string | null;
+  has(name: string): boolean;
+  entries(): [string, string][];
+  getAll(name: string): string[];
+}
+export interface EndpointRequest {
+  method: string;
+  path: string;
+  url: string;
+  headers: EndpointHeaders;
+  query: EndpointQuery;
+  text(): Promise<string>;
+  json<T = unknown>(): Promise<T>;
+  /** Request body bytes as a JSON-compatible number array. */
+  bytes(): Promise<number[]>;
+}
+
+export interface EndpointResponseOptions {
+  status?: number;
+  headers?: Record<string, string>;
+}
+export interface EndpointResponse {
+  readonly kind: "response";
+  status: number;
+  headers: Record<string, string>;
+  body: string | null;
+}
+
+type EndpointContext<S extends Schema, R extends EndpointRoute> = R extends { readOnly: true }
+  ? QueryServerContext<S>
+  : ServerContext<S>;
+
+export interface EndpointDefinition<S extends Schema = DefaultSchema, R extends EndpointRoute = EndpointRoute>
+  extends DefinitionBase<"endpoint", [request: EndpointRequest], EndpointResponse | unknown> {
+  (ctx: EndpointContext<S, R>, request: EndpointRequest): Promise<EndpointResponse | unknown>;
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly readOnly: boolean;
+}
+
+/** An HTTP route under `/<app>/`. Return `json() / text() / empty() / redirect()`, or a plain value (sent as JSON). */
+export function endpoint<S extends Schema, const R extends EndpointRoute>(
+  route: R,
+  handler: (ctx: EndpointContext<S, R>, request: EndpointRequest) => unknown,
+): EndpointDefinition<S, R> {
+  const def = define("endpoint", handler);
+  def.method = route.method;
+  def.path = route.path;
+  def.readOnly = route.readOnly === true;
+  return def;
+}
+
+function response(status: number, contentType: string | null, body: string | null, options?: EndpointResponseOptions): EndpointResponse {
+  const headers: Record<string, string> = {};
+  if (contentType) headers["content-type"] = contentType;
+  if (options?.headers) for (const k of Object.keys(options.headers)) headers[k.toLowerCase()] = options.headers[k]!;
+  return { kind: "response", status: options?.status ?? status, headers, body };
+}
+
+/** JSON body, status 200. */
+export function json(value: unknown, options?: EndpointResponseOptions): EndpointResponse {
+  return response(200, "application/json; charset=utf-8", JSON.stringify(value) ?? "null", options);
+}
+/** Plain text body, status 200. */
+export function text(value: string, options?: EndpointResponseOptions): EndpointResponse {
+  return response(200, "text/plain; charset=utf-8", value, options);
+}
+/** No body, status 204. */
+export function empty(options?: EndpointResponseOptions): EndpointResponse {
+  return response(204, null, null, options);
+}
+/** No body, status 302, `Location: url`. */
+export function redirect(url: string, options?: EndpointResponseOptions): EndpointResponse {
+  return response(302, null, null, { ...options, headers: { location: url, ...options?.headers } });
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// capsule()
+
+/** Any handler definition, matched by its `kind` marker (contexts are not compared). */
+export type AnyHandler = DefinitionBase<HandlerKind, any[], any> & ((...args: any[]) => any);
+
+type HandlerFor<S extends Schema> =
+  | QueryDefinition<S, any, any>
+  | MutationDefinition<S, any, any>
+  | ActionDefinition<S, any, any>
+  | EndpointDefinition<S, any>;
+
+const GROUP_KEYS = ["queries", "mutations", "actions", "endpoints"] as const;
+type GroupKey = (typeof GROUP_KEYS)[number];
+type ReservedKey = GroupKey | "schema";
+
+/** The argument of `capsule()`. Handlers go in groups (Lakebed form) or at the top level (flat form). */
+export interface CapsuleConfig<S extends Schema> {
+  schema?: S;
+  queries?: Record<string, QueryDefinition<S, any, any>>;
+  mutations?: Record<string, MutationDefinition<S, any, any>>;
+  actions?: Record<string, ActionDefinition<S, any, any>>;
+  endpoints?: Record<string, EndpointDefinition<S, any>>;
+  [name: string]:
+    | S
+    | HandlerFor<S>
+    | Record<string, QueryDefinition<S, any, any>>
+    | Record<string, MutationDefinition<S, any, any>>
+    | Record<string, ActionDefinition<S, any, any>>
+    | Record<string, EndpointDefinition<S, any>>
+    | undefined;
+}
+
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type GroupHandlers<D> = UnionToIntersection<
+  { [G in GroupKey]: G extends keyof D ? (NonNullable<D[G]> extends Record<string, any> ? NonNullable<D[G]> : {}) : {} }[GroupKey]
+>;
+type FlatHandlers<D> = { [K in keyof D as K extends ReservedKey ? never : D[K] extends AnyHandler ? K : never]: D[K] };
+
+/** All handlers of a capsule config, by name. */
+export type HandlersOf<D> = Simplify<GroupHandlers<D> & FlatHandlers<D>>;
+
+/** What `capsule()` returns. Import it on the client with `import type app from "../server/index"`. */
+export interface Capsule<S extends Schema = Schema, H = Record<string, AnyHandler>> {
+  readonly kind: "capsule";
+  readonly schema: S;
+  readonly functions: H;
+}
+
+/** Define the capsule. `server/index.ts` must `export default capsule({...})`. */
+export function capsule<S extends Schema = {}, D extends CapsuleConfig<S> = CapsuleConfig<S>>(
+  config: D & { schema?: S },
+): Capsule<S, HandlersOf<D>> {
+  const functions: Record<string, AnyHandler> = {};
+  const add = (name: string, def: any) => {
+    if (typeof def !== "function" || !def.kind) throw new Error(`capsule: ${name} is not a query/mutation/action/endpoint`);
+    if (name in functions) throw new Error(`capsule: duplicate handler name ${name}`);
+    functions[name] = def;
+  };
+  for (const key of Object.keys(config)) {
+    const value: any = (config as any)[key];
+    if (key === "schema" || value === undefined) continue;
+    if ((GROUP_KEYS as readonly string[]).includes(key)) {
+      for (const name of Object.keys(value)) add(name, value[name]);
+    } else {
+      add(key, value);
+    }
+  }
+  return { kind: "capsule", schema: (config.schema ?? {}) as S, functions: functions as unknown as HandlersOf<D> };
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Type helpers over a capsule (used by eraspace/client)
+
+export type SchemaOf<C> = C extends Capsule<infer S, any> ? S : never;
+export type HandlersOfCapsule<C> = C extends Capsule<any, infer H> ? H : never;
+export type ReadDatabaseOf<C> = DbContext<SchemaOf<C>>;
+export type WriteDatabaseOf<C> = MutationDbContext<SchemaOf<C>>;
+
+type NamesOfKind<C, K extends HandlerKind> = {
+  [N in keyof HandlersOfCapsule<C>]: HandlersOfCapsule<C>[N] extends { kind: K } ? N : never;
+}[keyof HandlersOfCapsule<C>] &
+  string;
+type ArgsOf<D> = D extends { __types?: { args: infer A } } ? (A extends any[] ? A : never) : never;
+type ResultOf<D> = D extends { __types?: { result: infer R } } ? R : never;
+
+export type QueryName<C> = NamesOfKind<C, "query">;
+export type MutationName<C> = NamesOfKind<C, "mutation">;
+export type ActionName<C> = NamesOfKind<C, "action">;
+export type QueryArgs<C, N extends QueryName<C>> = ArgsOf<HandlersOfCapsule<C>[N]>;
+export type QueryResult<C, N extends QueryName<C>> = ResultOf<HandlersOfCapsule<C>[N]>;
+export type MutationArgs<C, N extends MutationName<C>> = ArgsOf<HandlersOfCapsule<C>[N]>;
+export type MutationResult<C, N extends MutationName<C>> = ResultOf<HandlersOfCapsule<C>[N]>;
+export type ActionArgs<C, N extends ActionName<C>> = ArgsOf<HandlersOfCapsule<C>[N]>;
+export type ActionResult<C, N extends ActionName<C>> = ResultOf<HandlersOfCapsule<C>[N]>;

package/templates/chat/client/index.tsx

@@ -0,0 +1,41 @@
+import { createClient, FilePreview, FileUpload, type FileRef } from "eraspace/client";
+import { useState, useEffect } from "preact/hooks";
+import type app from "../server/index";
+const client = createClient<typeof app>({ reloadOnDeploy: true });
+export default function App() {
+  const [room, setRoom] = useState("general");
+  const [author, setAuthor] = useState("Guest");
+  const [body, setBody] = useState("");
+  const [error, setError] = useState("");
+  const [sending, setSending] = useState(false);
+  const [typing, setTyping] = useState("");
+  const [file, setFile] = useState<FileRef | null>(null);
+  const messages = client.useQuery("messages", room);
+  const send = client.useMutation("send");
+  const channel = client.useRoom<{ name: string }> (room, { name: author });
+  useEffect(() => channel.on("typing", (payload: unknown) => {
+    if (typeof payload === "string") setTyping(payload);
+  }), [room]);
+  useEffect(() => { if (!typing) return; const timer = setTimeout(() => setTyping(""), 1500); return () => clearTimeout(timer); }, [typing]);
+  return <main>
+    <header><h1>chat / {room}</h1><small>{client.status.value}</small></header>
+    <form onSubmit={e => { e.preventDefault(); const data = new FormData(e.currentTarget); setRoom(String(data.get("room") || "general")); }}>
+      <input name="room" aria-label="Room" defaultValue={room} maxLength={40}/><button class="subtle">Join room</button>
+    </form>
+    <div class="presence">{channel.presence.length} online · {channel.presence.map(member => member.meta.name || "Guest").join(", ")}</div>
+    {messages === undefined ? <p>Loading messages…</p> : messages.length === 0 ? <p>Send the first message.</p> : <ul>{[...messages].reverse().map(message => <li key={message.id}><strong>{message.author}</strong><span>{message.body}{message.file && <FilePreview client={client} file={message.file} class="attachment"/>}</span><time>{new Date(message.createdAt).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}</time></li>)}</ul>}
+    <form onSubmit={async e => {
+      e.preventDefault(); setSending(true); setError("");
+      try { await send(room, author, body, file); setBody(""); setFile(null); } catch (err) { setError(err instanceof Error ? err.message : String(err)); } finally { setSending(false); }
+    }}>
+      <input aria-label="Your name" value={author} maxLength={40} onInput={e => setAuthor(e.currentTarget.value)}/>
+      <input aria-label="Message" placeholder="Message" value={body} maxLength={2000} required={!file} onInput={e => { setBody(e.currentTarget.value); channel.broadcast("typing", author); }}/>
+      <button disabled={sending || (!body.trim() && !file)}>Send</button>
+      {file
+        ? <div class="pending"><FilePreview client={client} file={file} caption={false} class="attachment"/><span>{file.name}</span><button type="button" class="subtle" disabled={sending} onClick={() => { void client.storage.delete(file.key).catch(() => {}); setFile(null); }}>Remove</button></div>
+        : <FileUpload client={client} class="attach" onUpload={setFile}>Attach a file (up to 5 MB)</FileUpload>}
+    </form>
+    {typing && <small>{typing} is typing</small>}
+    {error && <p role="alert">{error}</p>}
+  </main>;
+}