Client SDK

The Disc TypeScript SDK provides a typed HTTP client for querying a Disc server, managing authentication, executing transactions, and subscribing to real-time updates over WebSocket.

Installation

Import from the SDK module directly:

import {
  AuthManager,
  createClient,
  createSubscriptionClient,
  DiscClient
} from "disc/sdk/mod.ts";

If you have generated a typed client with disc codegen, you can import the generated types alongside the SDK:

import { createClient } from "disc/sdk/mod.ts";
import type { Post, User } from "./dbschema/disc-client/interfaces.ts";

interfaces.ts is emitted only for multi-module schemas; a single-module schema emits types.ts instead, so import from ./dbschema/disc-client/types.ts in that case.

Creating a Client

Use createClient() to construct a DiscClient instance. All options are optional and have sensible defaults.

import { createClient } from "disc/sdk/mod.ts";

const client = createClient({
  baseUrl: "http://localhost:5656",
  headers: { "X-Custom-Header": "value" },
  retries: 3,
  retryDelay: 1000,
  timeout: 30000
});

Configuration Options

The DiscClient class can also be instantiated directly if you prefer:

import { DiscClient } from "disc/sdk/mod.ts";

const client = new DiscClient({ baseUrl: "https://disc.example.com" });

Zero-config baseUrl

When baseUrl is omitted, the client resolves the server URL automatically in this order:

1. config.baseUrl — an explicit value always wins.
2. DISC_SERVER_URL env var — works on any runtime (Deno, Node, Bun). The recommended option for deployed servers, where the working directory and filesystem permissions are unpredictable.
3. disc.toml — on Deno, the client walks up from the current working directory for a disc.toml (the same lookup the CLI uses) and derives http://<host>:<port> from its [server] section.
4. http://localhost:5656 — the final fallback.

So a codegen client running inside your project connects on the configured port with no options:

import { DiscClient } from "./dbschema/disc-client/index.ts";

const client = new DiscClient(); // baseUrl from DISC_SERVER_URL, else disc.toml

# Or pin it explicitly for a deployed GraphQL/API server:
DISC_SERVER_URL=http://db.internal:5656 deno run --allow-net --allow-env server.ts

disc.toml resolution is best-effort and Deno-only: a Node or Bun process (e.g. an Apollo/Yoga server) skips step 3 entirely, so set DISC_SERVER_URL there. Within Deno it also needs --allow-read for the project directory and --allow-env to read the variable. If a disc.toml is found but can’t be read (permission denied), the client emits a logger.warn (when a logger is configured) instead of silently falling back — pass { logger: console } while debugging:

const client = new DiscClient({ logger: console });
// → warns: "DiscClient: could not read …/disc.toml; falling back to http://localhost:5656…"

Basic Queries

client.query<T>(query, variables?, options?)

Executes an EdgeQL query and returns the result data directly. Throws DiscQueryError if the server returns any errors.

The optional options argument accepts { revive, validate }: revive auto-converts wire-encoded scalars (e.g. ISO date strings into Date), and validate runs a validator against the result, throwing DiscValidationError if it rejects.

bigint variables (the type codegen assigns to int64 fields) are supported directly — the client encodes them as numeric strings on the wire, so { count: 0n } works where plain JSON.stringify would throw "Do not know how to serialize a BigInt". Uint8Array values should be wrapped with encodeBytes() before being passed as variables.

// Select all users
const users = await client.query<User[]>("select User { email, name }");

// Select with variables
const user = await client.query<User>(
  `select User { email, name }
   filter .email = <str>$email`,
  { email: "ada@example.com" }
);

// Insert
const newUser = await client.query<User>(
  `insert User {
    email := <str>$email,
    name := <str>$name
  }`,
  { email: "billie@example.com", name: "Billie" }
);

// Update
await client.query(
  `update User
   filter .email = <str>$email
   set { name := <str>$name }`,
  { email: "billie@example.com", name: "Robert" }
);

// Delete
await client.query(
  `delete User filter .email = <str>$email`,
  { email: "billie@example.com" }
);

client.queryRaw<T>(query, variables?)

Returns the full response envelope including data, errors, and timing extensions. Does not throw on query errors -- you must check response.errors yourself.

const response = await client.queryRaw<User[]>("select User { email, name }");

if (response.errors && response.errors.length > 0) {
  for (const err of response.errors) {
    console.error(err.message, err.extensions);
  }
} else {
  console.log(response.data);
}

// Access timing information
console.log(response.extensions?.parseMs);
console.log(response.extensions?.compileMs);
console.log(response.extensions?.executeMs);
console.log(response.extensions?.cacheHit);

Response Envelope

The QueryResponse<T> type has this shape:

interface QueryResponse<T = unknown> {
  data?: T;
  errors?: QueryError[];
  extensions?: QueryExtensions;
}

interface QueryError {
  extensions?: Record<string, unknown>;
  locations?: Array<{ column: number; line: number; }>;
  message: string;
  path?: Array<string | number>;
}

interface QueryExtensions {
  cacheHit?: boolean;
  compileMs?: number;
  executeMs?: number;
  parseMs?: number;
  [key: string]: unknown;
}

Typed Multi-Link Writes

When you generate a typed client with disc codegen, junction-backed multi links are writable directly through the generated insert() / update() methods — no raw EdgeQL required. Multi links are typed as arrays of target UUIDs.

Given a schema where User has multi link teams -> Team:

// Insert — assign the full set of linked targets
const user = await client.user.insert({
  name: "Ada",
  teams: [teamId1, teamId2]
});

// Update (replace) — pass an array to replace the whole set
await client.user.update(user.id, { teams: [teamId2, teamId3] });

// Update (delta add) — add members without disturbing the rest
await client.user.update(user.id, { teams: { add: [teamId1] } });

// Update (delta remove) — remove members without disturbing the rest
await client.user.update(user.id, { teams: { remove: [teamId2] } });

The set semantics are:

• insert({ link: [...] }) assigns exactly the listed targets.
• update(id, { link: [...] }) replaces the set with exactly the listed targets.
• update(id, { link: { add: [...] } }) adds targets (existing members are left in place; re-adding an existing member is a no-op).
• update(id, { link: { remove: [...] } }) removes the listed targets.

add and remove may be combined in a single update call. Each write compiles to a single atomic statement against PostgreSQL, so the junction rows are never left half-applied.

Health Checks

The SDK provides three methods for checking server health, suitable for orchestration systems and monitoring.

client.health()

Returns the full health status including database connectivity, connection pool stats, uptime, and extension health.

const health = await client.health();
// health.database?.connected: boolean
// health.database?.latencyMs: number
// health.pool?.active: number
// health.pool?.idle: number
// health.status: "healthy" | "degraded" | "unhealthy"
// health.uptimeMs: number

client.isAlive()

Liveness probe. Returns true if the server process is running. Never throws -- returns false on any error.

const alive = await client.isAlive();

client.isReady()

Readiness probe. Returns true when the database is connected and the server can accept queries. Returns false if the database is unreachable.

const ready = await client.isReady();

Server Stats

client.stats()

Returns detailed server statistics including connection counts, query metrics, transaction counts, memory usage, cache stats, and rate limiter info.

const stats = await client.stats();

console.log("Active connections:", stats.connections.active);
console.log("Total queries:", stats.queries.total);
console.log("Failed queries:", stats.queries.failed);
console.log("Avg query duration:", stats.queries.avgDurationMs, "ms");
console.log("Active transactions:", stats.transactions.active);
console.log("Heap used:", stats.memoryUsage.heapUsed);
console.log("Uptime:", stats.uptimeMs, "ms");

// Cache stats (when available)
if (stats.cache) {
  console.log("Compilation cache hit rate:", stats.cache.compilation.hitRate);
  console.log("Parse cache size:", stats.cache.parse.size);
}

// Query performance metrics
if (stats.queryMetrics) {
  console.log("Avg parse time:", stats.queryMetrics.avgParseMs, "ms");
  console.log("Avg compile time:", stats.queryMetrics.avgCompileMs, "ms");
  console.log("Avg execute time:", stats.queryMetrics.avgExecuteMs, "ms");
  console.log("Cache hit rate:", stats.queryMetrics.cacheHitRate);
}

Authentication

The AuthManager class handles the full authentication lifecycle: registration, login, logout, token refresh, and profile management. It wraps a DiscClient and automatically sets the JWT token on the client after successful authentication.

Setup

import { AuthManager, createClient } from "disc/sdk/mod.ts";

const client = createClient({ baseUrl: "http://localhost:5656" });

const auth = new AuthManager(client, {
  autoRefresh: true, // automatically refresh tokens before expiry (default: true)
  refreshBuffer: 60 // seconds before expiry to trigger refresh (default: 60)
});

Registration

const response = await auth.register({
  email: "ada@example.com",
  metadata: { department: "engineering" }, // optional
  password: "secure-password-123",
  username: "ada" // optional
});

// response contains:
// - response.refreshToken: refresh token (optional)
// - response.session: session details (id, userId, expiresAt)
// - response.token: JWT access token
// - response.user: AuthUser object

After registration, the client is automatically authenticated. All subsequent queries include the JWT token.

Login

// Login with email
const response = await auth.login({
  email: "ada@example.com",
  password: "secure-password-123"
});

// Login with username
const response = await auth.login({
  password: "secure-password-123",
  username: "ada"
});

Checking Authentication State

auth.isAuthenticated(); // true if a token is set on the client
auth.getUser(); // cached AuthUser from the last login/register call

getUser() returns the user from the most recent successful login() or register() call without making a server request. Returns null if no session is active.

Fetching the Profile

const profile = await auth.getProfile();
// profile.email, profile.id, profile.username
// profile.createdAt, profile.updatedAt
// profile.active, profile.emailVerified
// profile.metadata

getProfile() makes a GET /auth/profile request and updates the cached user.

Updating the Password

await auth.updatePassword("old-password", "new-password");

Throws DiscAuthError if not authenticated.

Token Refresh

When autoRefresh is enabled (the default), the AuthManager parses the JWT exp claim and schedules a background refresh refreshBuffer seconds before the token expires. This happens automatically -- you do not need to call refreshTokens() manually.

To refresh manually:

const tokens = await auth.refreshTokens();
// tokens.refreshToken: new refresh token (if issued)
// tokens.token: new JWT access token

Throws DiscAuthError if no refresh token is available.

Logout

await auth.logout();

This sends a POST /auth/logout request, then clears all local state: tokens, cached user, and the auth header on the client.

Cleanup

When you are done with the AuthManager, call dispose() to cancel any pending auto-refresh timer:

auth.dispose();

This is important in environments where timers would prevent garbage collection or process exit.

Transactions

Transactions execute multiple queries atomically. The SDK uses a callback pattern: the transaction auto-commits on success and auto-rolls back on error.

Basic Usage

const result = await client.transaction(async tx => {
  const user = await tx.query<User>(
    `insert User { email := <str>$email, name := <str>$name }`,
    { email: "cher@example.com", name: "Cher" }
  );

  await tx.query(
    `insert Post {
      author := (select User filter .id = <uuid>$userId),
      body := <str>$body,
      title := <str>$title
    }`,
    { body: "Written atomically.", title: "First Post", userId: user.id }
  );

  return user;
});

If the callback throws, the transaction is automatically rolled back and the error is re-thrown.

Transaction Methods

Inside the callback, the tx object provides:

You do not need to call tx.commit() explicitly. The client.transaction() wrapper commits automatically when the callback returns without throwing. Explicit commit and rollback are available for advanced control flows.

Transaction State Machine

A Transaction transitions through these states:

active  -->  committed
   |
   +------>  rolled_back

Calling query(), commit(), or rollback() on a non-active transaction throws DiscTransactionError.

How It Works

Under the hood, client.transaction() performs these steps:

1. POST /transaction/begin -- server allocates a transaction and returns a transactionId.
2. Each tx.query() sends a POST /query with an X-Transaction-ID header linking the query to the transaction.
3. On callback success: POST /transaction/{id}/commit.
4. On callback error: POST /transaction/{id}/rollback, then re-throws.

WebSocket Subscriptions

The SubscriptionClient provides real-time data streaming over WebSocket. It supports automatic reconnection with exponential backoff and re-subscribes to all active subscriptions after reconnection.

Setup and Connection

import { createSubscriptionClient } from "disc/sdk/mod.ts";

const sub = createSubscriptionClient(
  { baseUrl: "http://localhost:5656" },
  {
    autoReconnect: true, // reconnect on disconnect (default: true)
    maxReconnectAttempts: 5, // max reconnect attempts (default: 5)
    reconnectDelay: 1000 // base delay in ms (default: 1000)
  }
);

await sub.connect();

The SubscriptionClient automatically converts http:// to ws:// and https:// to wss:// when connecting.

Subscribing to Queries

const handle = sub.subscribe<User[]>(
  "select User { email, name, posts: { title } }",
  {
    onComplete: () => {
      console.log("Subscription stream ended");
    },
    onData: data => {
      console.log("Received update:", data);
    },
    onError: error => {
      console.error("Subscription error:", error.message);
    }
  },
  { status: "active" } // optional variables
);

The subscribe() method returns a SubscriptionHandle:

interface SubscriptionHandle {
  id: string; // unique subscription ID
  unsubscribe: () => void; // unsubscribe from this subscription
}

Unsubscribing

// Via the handle
handle.unsubscribe();

// Or by ID
sub.unsubscribe(handle.id);

Connection Management

sub.isConnected(); // true when WebSocket is in OPEN state
sub.close(); // close the connection and clean up all subscriptions

Calling close() prevents any further reconnection attempts.

Auto-Reconnection

When the WebSocket connection drops and autoReconnect is true, the client automatically:

1. Waits with exponential backoff: reconnectDelay * 2^attempt milliseconds.
2. Reconnects to the server.
3. Re-subscribes to all active subscriptions.

If reconnection fails after maxReconnectAttempts, all active subscriptions receive an error via their onError callback.

Subscription Client Config

Error Handling

All SDK errors extend DiscClientError, which carries a code property from the DiscErrorCode enum.

Error Hierarchy

Catching Specific Errors

import {
  DiscAuthError,
  DiscConnectionError,
  DiscErrorCode,
  DiscQueryError,
  DiscServerError,
  DiscTimeoutError
} from "disc/sdk/mod.ts";

try {
  const users = await client.query("select User { email, name }");
} catch (error) {
  if (error instanceof DiscQueryError) {
    // Query syntax or execution error
    console.error("Query failed:", error.message);

    for (const qe of error.errors) {
      console.error("  -", qe.message, qe.extensions);
    }
  } else if (error instanceof DiscTimeoutError) {
    // Request took too long
    console.error(`Timed out after ${error.timeoutMs}ms`);
  } else if (error instanceof DiscAuthError) {
    // Authentication failure
    console.error(`Auth error (HTTP ${error.statusCode}):`, error.message);
  } else if (error instanceof DiscConnectionError) {
    // Server unreachable
    console.error("Connection failed:", error.message);
  } else if (error instanceof DiscServerError) {
    // 5xx server error
    console.error(`Server error (HTTP ${error.statusCode}):`, error.message);
  }
}

Using Error Codes

Every SDK error has a code property from the DiscErrorCode enum:

import { DiscClientError, DiscErrorCode } from "disc/sdk/mod.ts";

try {
  await client.query("bad query");
} catch (error) {
  if (error instanceof DiscClientError) {
    switch (error.code) {
      case DiscErrorCode.AUTH_ERROR: {
        // handle auth error
        break;
      }

      case DiscErrorCode.CONNECTION_ERROR: {
        // handle connection error
        break;
      }

      case DiscErrorCode.NETWORK_ERROR: {
        // handle network error
        break;
      }

      case DiscErrorCode.PROTOCOL_ERROR: {
        // handle protocol error
        break;
      }

      case DiscErrorCode.QUERY_ERROR: {
        // handle query error
        break;
      }

      case DiscErrorCode.SERVER_ERROR: {
        // handle server error
        break;
      }

      case DiscErrorCode.TIMEOUT: {
        // handle timeout
        break;
      }

      case DiscErrorCode.TRANSACTION_ERROR: {
        // handle transaction error
        break;
      }

      case DiscErrorCode.VALIDATION_ERROR: {
        // handle validation failure
        break;
      }
    }
  }
}

Retry Behavior

The client retries requests based on the error type:

Multi-Database

When the server has multi-database support enabled, you can target a specific database by passing a custom header or by including a query parameter.

Via Custom Headers

const client = createClient({
  baseUrl: "http://localhost:5656",
  headers: { "X-Database": "analytics" }
});

const data = await client.query("select Event { name, timestamp }");

Per-Request Override

If you need to query different databases from the same client, set the header on individual requests by using queryRaw with the underlying fetch:

// Default database
const users = await client.query("select User { name }");

// Different database via a second client
const analyticsClient = createClient({
  baseUrl: "http://localhost:5656",
  headers: { "X-Database": "analytics" }
});

const events = await analyticsClient.query("select Event { name }");

The server resolves the database name in this order:

1. X-Database header
2. ?database= query parameter
3. Default: "disc"

Codegen-free query builder

A runtime DSL that gives the same end-to-end type safety as disc codegen without producing any generated files. Useful when CI shouldn’t carry a codegen step or when the schema lives in TypeScript next to the application code.

Declare the schema in TypeScript

defineSchema() accepts a record of type definitions; field markers come from the t.* namespace:

import { defineSchema, t } from "disc/sdk/mod.ts";

export const schema = defineSchema({
  User: {
    email: t.str(),
    name: t.optional(t.str()),
    score: t.int64(),
    posts: t.multi("Post")
  },
  Post: {
    title: t.str(),
    body: t.optional(t.str()),
    author: t.single("User")
  }
});

The t.* markers carry compile-time type information; defineSchema() validates at construction (PascalCase type names, valid field names, link targets that resolve to defined types) and throws synchronously on misuse.

Build typed queries

createQueryBuilder(client, schema) returns a Proxy where each property is a typed selection chain:

import { createClient, createQueryBuilder } from "disc/sdk/mod.ts";
import { schema } from "./schema.ts";

const client = createClient();
const qb = createQueryBuilder(client, schema);

// Awaiting the chain runs the query through `client.query()`.
const users = await qb
  .User
  .select({ email: true, name: true })
  .filter(u => u.email.eq("alice@example.com"))
  .first();
//    ^? { email: string; name: string | null } | null

select narrows the awaited row type to the picked shape. filter predicates receive a typed reference where each property accepts only the right comparison operand: u.email.eq(...) requires a string, u.score.gt(...) requires a number. Identifier safety is enforced at construction so schema typos fail before reaching the server.

Composability with client.query

The query builder compiles to the same EdgeQL strings the raw client.query("select User { ... }") path does and runs through the same access-policy + read-only + auth-gate pipeline. The two patterns interoperate freely — pick whichever reads better at the call site, no migration needed. (sdk/query-builder.ts, sdk/schema-types.ts)

TypeScript Types

When using generated types from disc codegen, you can pass them as type parameters to query() for full type safety:

import { createClient } from "disc/sdk/mod.ts";
import type { Post, User } from "./dbschema/disc-client/interfaces.ts";

const client = createClient();

// Type-safe query results
const users = await client.query<User[]>("select User { email, name }");
// users is typed as User[]

// Type-safe within transactions
const result = await client.transaction(async tx => {
  const user = await tx.query<User>(
    `insert User { email := <str>$email, name := <str>$name }`,
    { email: "daena@example.com", name: "Daena" }
  );

  return user; // typed as User
});

// Type-safe subscriptions
const sub = createSubscriptionClient();
await sub.connect();

sub.subscribe<User[]>(
  "select User { email, name }",
  {
    onData: users => {
      // users is typed as User[]
      for (const user of users) {
        console.log(user.email, user.name);
      }
    }
  }
);

SDK Exports

The complete list of exports from disc/sdk/mod.ts:

Classes

Factory Functions

Error Classes

Types

Query Builder & Schema

Codegen-free query-builder DSL and schema declaration exports.

Schema-declaration type exports: FieldMarker, FieldType, IsLink, Link, LinkCardinality, LinkStub, LinkTarget, Optional, ResolveSelected, ResolveType, Scalar, SchemaSpec, SelectShape.

Codecs

Wire-format encode/decode helpers.

See Also

• Getting Started -- Quick introduction to Disc
• EdgeQL -- Query language reference
• Server Configuration -- Server setup, HTTP API, and environment variables
• Auth -- Authentication system details
• Codegen -- Generating typed clients from your schema