Skip to main content

Typescript / JavaScript (v3 Beta)

TypeScript client version

The current TypeScript client version is v2.1.1.

Overview

The TypeScript client can be used for both JavaScript and TypeScript scripts. This page covers the Weaviate TypeScript client; weaviate-client on npm. This version is currently in beta. For usage information not specific to the Typescript client, such as code examples, see the relevant pages in the Weaviate documentation.

Installation and setup

The TypeScript client library package can be installed using npm.

npm install weaviate-client --tag beta

Some packages, like the Weaviate TypeScript client, require extra configuration. The root directory of a TypeScript project has a tsconfig.json file. Add the following to your tsconfig.json.

  • Compiler options

    • "target": "esnext"
    • "module": "esnext" (requires at least Node16)
    • "moduleResolution": "Node16"
  • "include": ["*.ts"] (Or specific files)

  • "lib": [ "es2018" ]

Don't specify filenames on the command line when you use tsconfig.json. Specify the TypeScript files in tsconfig.json instead. tsc only reads tsconfig.json when you run it by itself.

References

v2 → v3 client documentation migration

We are in the process of migrating our v2 client code examples to v3 as necessary. Please be patient as we work on documenting the rest.

At the moment, we've covered the following pages.

Our RESTful endpoints and GraphQL functions covered by the TypeScript client currently have JavaScript examples in the code blocks.

Design

A Collection first Approach

With the new v3 client, we've opted focus on collections as primary method of interaction with your Weaviate database. We've also utilized strong typing through custom Typescript types and user-defined generics.

Client Connection

Once installed, you can use the client in your TypeScript and JavaScript scripts, as shown in the following examples.

Connecting to Weaviate

const { default: weaviate } = require('weaviate-client');

const client = await weaviate.connectToWCS(
'WEAVIATE_INSTANCE_URL', {
authCredentials: new weaviate.ApiKey('api-key'),
}
)
console.log(client)
Troubleshooting imports with TypeScript

If you are having any issues with the import statement in TypeScript (e.g. if weaviate is undefined), try adding "esModuleInterop": true to your "compilerOptions" in tsconfig.json.

Type definitions

The type definitions can be found under each bundles respective folder; the subdirectory of node/cjs and node/esm in the *.d.ts files, for example as shown on the npm package page.

Authentication

For more comprehensive information on configuring authentication with Weaviate, refer to the authentication page.

The TypeScript client offers multiple options for authenticating against Weaviate, including multiple OIDC authentication flows.

The suitable authentication options and methods for the client largely depend on the specific configuration of the Weaviate instance.

WCS authentication

WCS + Weaviate client

Each Weaviate instance in Weaviate Cloud Services (WCS) is pre-configured to act as a token issuer for OIDC authentication.

See our WCS authentication documentation for instructions on how to authenticate against WCS with your preferred Weaviate client.

API key authentication

To authenticate against Weaviate using an API key, instantiate the client as follows:

const { default: weaviate } = require('weaviate-client');

// Instantiate the client with the auth config
const client = await weaviate.connectToWCS(
'WEAVIATE_INSTANCE_URL', {
authCredentials: new weaviate.ApiKey('api-key'), // Add your WCS API KEK here
}
)

console.log(client)

OIDC authentication

To authenticate against Weaviate with OIDC, you must select a flow made available by the identity provider and create the flow-specific authentication configuration.

This configuration will then be used by the Weaviate client to authenticate. The configuration includes secrets that help the client obtain an access token and, if configured, a refresh token.

The access token is added to the HTTP header of each request and is utilized for authentication with Weaviate. Typically, this token has a limited lifespan, and the refresh token can be employed to obtain a new set of tokens when necessary.

Background refresh processes with TS

When using OIDC with the TypeScript client, its background token refresh process can block a script from exiting. If this behavior is not desired, you can:

  1. Set the silentRefresh parameter as false in the OIDC configuration. Or,
  2. Stop the process via client.oidcAuth?.stopTokenRefresh(), e.g. when a script is expected to exit, or token refresh is no longer needed.

Resource Owner Password Flow

This OIDC flow uses the username and password to obtain required tokens for authentication.

Note that not every provider automatically includes a refresh token and an appropriate scope might be required that depends on your identity provider. The client uses offline_access as the default scope. This works with some providers, but as it depends on the configuration of the identity providers, we ask you to refer to the identity provider's documentation.

Without a refresh token, there is no possibility to acquire a new access token and the client becomes unauthenticated after expiration.

note

The Weaviate client does not save the username or password used.

They are only used to obtain the first tokens, after which existing tokens will be used to obtain subsequent tokens if possible.

const { default: weaviate } = require('weaviate-client');

const client = await weaviate.connectToWCS(
'WEAVIATE_INSTANCE_URL', // Replace with your instance URL
{
authCredentials: new weaviate.AuthUserPasswordCredentials({
username: 'username',
password: 'password',
silentRefresh: true, // Default: true - if false, you must refresh the token manually; if true, this background process will prevent a script from exiting.
scopes: ['offline_acess'] // optional, depends on the configuration of your identity provider (not required with WCS)
})
}
)

Client Credentials flow

This OIDC flow uses a client secret to obtain required tokens for authentication.

This flow is recommended for server-to-server communication without end-users and authenticates an application to Weaviate. This authentication flow is typically regarded as more secure than the resource owner password flow: a compromised client secret can be simply revoked, whereas a compromised password may have larger implications beyond the scope of breached authentication.

To authenticate a client secret most identity providers require a scope to be specified. This scope depends on the configuration of the identity providers, so we ask you to refer to the identity provider's documentation.

Most providers do not include a refresh token in their response so client secret is saved in the client to obtain a new access token on expiration of the existing one.

const { default: weaviate } = require('weaviate-client');

const client = await weaviate.connectToWCS(
'https://WEAVIATE_INSTANCE_URL', // Replace with your instance URL
{
authCredentials: new weaviate.AuthClientCredentials({
clientSecret: 'supersupersecret',
silentRefresh: true, // Default: true - if false, you must refresh the token manually; if true, this background process will prevent a script from exiting.
scopes: ['scope1', 'scope2'] // optional, depends on the configuration of your identity provider
})
}
)

Refresh Token flow

Any other OIDC authentication method can be used to obtain tokens directly from your identity provider, for example by using this step-by-step guide of the hybrid flow.

If no refresh token is provided, there is no possibility to obtain a new access token and the client becomes unauthenticated after expiration.

const { default: weaviate } = require('weaviate-client');

const client = await weaviate.connectToWCS(
'https://WEAVIATE_INSTANCE_URL', // Replace with your instance URL
{
authCredentials: new weaviate.AuthAccessTokenCredentials({
accessToken: 'acessToken',
expiresIn: 900,
refreshToken: 'refreshToken',
silentRefresh: true // Default: true - if false, you must refresh the token manually; if true, this background process will prevent a script from exiting.
})
}
)

Custom headers

You can pass custom headers to the client, which are added at initialization:

const { default: weaviate } = require('weaviate-client');

const client = await weaviate.connectToWCS(
'https://WEAVIATE_INSTANCE_URL', // Replace with your instance URL
{
authCredentials: new weaviate.ApiKey('some-api-key'),
headers: {
someHeaderName: 'header-value',
}
}
)

These headers will then be included in every request that the client makes.

Separated Node and Web Versions

We've chosen to break up the new TypeScript client into Node and Web versions. With the addition of gRPC to Weaviate, we now have the HTTP/2 protocol to contend with and we quickly discovered that gRPC and HTTP/2 don't play nicely with browsers.

In this beta, you only have access to the Node version of the client. We will use the beta period to work on the Web version of the client.

What can you do with the Node Bundle?

All CRUD (Create, Read, Update and Delete) operations powered by gRPC and REST.

What will you be able to do with the Web bundle?

Only Read operations powered by GraphQL.

General notes

  • All methods use ES6 Promises to deal with asynchronous code, so you need to use .then() after function calls, or have async/await support.
  • In the case of an error, the Promise rejects with the specific error message. (If using async/await, a rejected promises acts like a thrown exception).
  • Internally the client uses isomorphic-fetch to make the REST calls, so it should work from both the browser and NodeJS applications without any required changes.

TypeScript for JavaScript users

TypeScript is a superset of JavaScript. There are, however, some differences that you should be aware of. This section offers some suggestions for JavaScript users who are new to TypeScript.

Run a TypeScript file

To run a TypeScript file, first convert it to JavaScript. The typescript package from npm includes the tsc utility. Use tsc to convert (transpile) the TypeScript file.

Install the typescript package. Add the -g flag if you want the package to be available globally.

npm install typescript

You can then use this command to transpile the TypeScript file.

tsc

node only allows the import statement in modules. To allow the import statement, add the following to your package.json file.

{
"type": "module"
}

Example

To run this example, complete these steps.

  • Install the typescript package.
  • Update the tsconfig.json and package.json files as described above.
  • Copy the sample code.
  • Save the code as sample.ts in the same directory as tsconfig.json and package.json.
  • Convert and run the code.

Use this code to create sample.ts.

Sample TypeScript code
import weaviate, { WeaviateClient } from 'weaviate-client'

const client: WeaviateClient = await weaviate.connectToWCS(
'WEAVIATE_INSTANCE_URL', // Replace with your instance URL
{
authCredentials: new weaviate.ApiKey('api-key'),
}
)

console.log(await client.isReady())

Convert sample.ts.

tsc

Run the converted file.

node sample.js

The output looks like this.

Sample output
{
"clientId": "wcs",
"href": "https://auth.wcs.api.weaviate.io/auth/realms/SeMI/.well-known/openid-configuration"
}