TypeScript with the JavaScript Client

Open inAnthropic

What you'll achieve By the end of this guide you will call the TerminusDB JavaScript client from TypeScript with typed query bindings, typed documents, version-tracked responses, and a documented error shape.

The terminusdb package ships generated TypeScript declarations, so import works out of the box with no extra @types package. This guide covers what those declarations give you beyond plain JavaScript: generic result types, typed WOQL variables, and the shared type definitions exported under typedef. It does not add runtime validation — the type parameters describe what you expect the server to return, they do not check it.

Prerequisites

Typed WOQL variables

Wherever a WOQL parameter expects a variable, the generated types accept both the "v:name" string form and Var objects produced by WOQL.vars(...) (array) or WOQL.Vars(...) (record). Use whichever reads better; the compiler accepts both.

Example: TypeScript
const [person, name] = TerminusClient.WOQL.vars("person", "name")
const v = TerminusClient.WOQL.Vars("person", "name") // v.person, v.name

Typed query bindings

client.query<T> takes a type parameter describing one result row. The resolved promise has bindings: T[] plus the update counters the server returns for write queries.

TYPESCRIPT
Run locally
// The type parameter on query<T> describes each row in result.bindings.
const v = TerminusClient.WOQL.Vars("name")
const result = await client.query<NameRow>(
  TerminusClient.WOQL.triple("v:person", "name", v.name),
)
for (const row of result.bindings) {
  console.log(row.name)
}
Run the setup example above first to create the database

When a call is made without a type argument the result stays any, so existing JavaScript-flavoured TypeScript keeps compiling unchanged.

Typed documents

getDocument, addDocument, updateDocument, deleteDocument and queryDocument all take an optional document type. Choose T for a single document or T[] when the call returns a list, for example with as_list: true.

TYPESCRIPT
Run locally
// getDocument<T> resolves to T; use T[] when the call returns a list.
const person = await client.getDocument<Person>({ id: "Person/ada" })
console.log(person["@id"], person.name)

const people = await client.getDocument<Person[]>({
  as_list: true,
  type: "Person",
})
console.log(people.length)
Run the setup example above first to create the database

getSchema<T> resolves to T[] and is typed the same way for schema documents.

Version-tracked responses

Methods with a getDataVersion parameter accept a second type parameter for the wrapped response: WithDataVersion<T> gives you result and the dataVersion token used for optimistic concurrency.

TYPESCRIPT
Run locally
// With getDataVersion: true, pass WithDataVersion<T> as the second type
// parameter to describe the wrapped response.
const wrapped = await client.getDocument<Person, WithDataVersion<Person>>(
  { id: "Person/ada" },
  undefined, undefined, undefined, true,
)
console.log(wrapped.result["@id"], wrapped.dataVersion)
Run the setup example above first to create the database

Error handling

Failed calls reject with a standard Error carrying the HTTP status on .status and the parsed server error body on .data, modelled as TerminusDBError. A missing document is a catchable 404 with api:DocumentNotFound in the error body — an empty as_list result remains a successful [], not an error.

TYPESCRIPT
Run locally
// Rejected calls are standard Error objects carrying the HTTP status and the
// parsed server error body. A missing document is a catchable 404.
try {
  await client.getDocument<Person>({ id: "Person/does-not-exist" })
} catch (err) {
  const e = err as TerminusDBError
  if (e.status === 404) {
    console.log(e.data?.["api:error"]?.["@type"]) // "api:DocumentNotFound"
  } else {
    throw err
  }
}
Run the setup example above first to create the database

Shared type definitions

All reusable shapes — WOQLQueryResult, WithDataVersion, APIErrorBody, TerminusDBError, and the DocParams* parameter objects — are importable by name from the package root and also exported under the typedef namespace. See JavaScript Client Type Definitions for the full reference.

Type parameters are checked at compile time only. The client does not validate responses against them at runtime; a schema change server-side can still produce a shape your type does not describe.

Was this helpful?