HOST_DECLARATIONS

tcmts.cli.server_api.HOST_DECLARATIONS · #auafjvvm · term · runs anywhere

Types of #tcm/host (host protocol 1), for a server API library and the checker (the runtime is generated from createServerHost).

export const HOST_DECLARATIONS = `// generated by tcm — do not edit: tcm's server host, protocol 1
import type { DatabaseSync } from "node:sqlite";
export interface ServerRequest {
  method: string;
  url: string;
  headers: Headers;
  cookies: Record<string, string>;
  /** the client's address, as the socket sees it */
  ip: string | undefined;
  /** aborted when the client disconnects, so long work can stop early */
  signal: AbortSignal;
}
/** The call being answered: a request (\`request\`), or a background job (none). */
export interface ServerCall {
  request?: ServerRequest;
  /** the Set-Cookie headers the call sends */
  setCookies: string[];
  /** whether the request came over TLS */
  secure: boolean;
  /** where the app's data lives; in memory when absent (tests) */
  dataDir?: string;
  /** the path cookies are for unless they say: the app's base */
  cookiePath?: string;
}
/** The call being answered, if any. */
export declare function call(): ServerCall | undefined;
/** Where the app's data lives now: the call's, else the worker's; in memory when neither. */
export declare function dataDir(): string | undefined;
/**
 * The app's SQLite file for where its data lives now: \`store\` (tables \`rows\`: tbl, id, data, schema_hash, updated;
 * \`schemas\`: tbl, hash, schema, first_seen) or \`sessions\` (\`sessions\`: id, data, expires). One connection each.
 */
export declare function database(name: "store" | "sessions"): DatabaseSync;
/** Run \`fn\` holding \`key\` (the store's connection, as every table call does), waiting for whoever holds it; reentrant. */
export declare function exclusive<R>(key: object, fn: () => R | Promise<R>): Promise<R>;
/** One transaction over the store; jobs enqueued in it are queued when it commits. Nested ones are savepoints. */
export declare function transaction<R>(fn: () => R | Promise<R>): Promise<R>;
/** Queue \`fn(...args)\` (a codebase function, by its hash) to run at \`runAt\` (ms), with retries; its id. */
export declare function enqueue(runAt: number, fn: (...args: any[]) => unknown, args: unknown[], opts?: { attempts?: number }): string;
/** Run the queued jobs that are due (all of them with \`{ all: true }\`), inline. */
export declare function runJobs(opts?: { all?: boolean }): Promise<{ done: number; failed: number }>;
/** Throws unless \`spec\` is an interval ("15m") or five cron fields (UTC). */
export declare function checkSchedule(spec: string): void;
/** The wire codec: plain data, Dates, Maps, Sets, bigints and the like, as text. */
export declare function encode(value: unknown, what?: string): string;
export declare function decode(text: string): unknown;
/** Why \`value\` doesn't fit a schema tcm worked out from a type (undefined if it does). */
export declare function checkValue(schema: unknown, value: unknown, at: string, defs: unknown[]): string | undefined;
/** A random id people may type (base64url, never starting with \`-\`). */
export declare function randomId(bytes: number): string;
/** Run \`fn\` as the call answering this request; reports the Set-Cookie headers it produced. */
export declare function withCall<T>(
  request: { method: string; url: string; headers: Record<string, string | string[] | undefined>; ip: string | undefined; signal: AbortSignal },
  opts: { secure: boolean; dataDir?: string; cookiePath?: string },
  fn: () => Promise<T>,
): Promise<{ ok: true; value: T; setCookies: string[] } | { ok: false; error: unknown; setCookies: string[] }>;
/** For the runtime: the Set-Cookie headers the current call has produced so far. */
export declare function pendingCookies(): string[];
/** For the runtime: work the job queue, loading functions by hash. */
export declare function startWorker(opts: {
  dataDir: string;
  load: (hash: string) => Promise<(...args: unknown[]) => unknown>;
  log: (line: string) => void;
  concurrency?: number;
}): () => void;
/** For the runtime: the app's recurring jobs. */
export declare function setSchedules(opts: {
  dataDir: string;
  jobs: { name: string; spec: string; fn: (...args: unknown[]) => unknown; hash: string }[];
  log?: (line: string) => void;
}): void;
`

used by