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
- TerminusDB running locally or a TerminusCMS account
- Node.js 22+ installed
- The client installed and connected — see Install JS Client and Connect to JS Client
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.
const [person, name] = TerminusClient.WOQL.vars("person", "name")
const v = TerminusClient.WOQL.Vars("person", "name") // v.person, v.nameTyped 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.
// 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)
}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.
// 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)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.
// 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)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.
// 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
}
}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.