@atomstate/atomstate-rest

JavaScript Atomstate REST Client

This repository contains the REST client for the Atomstate vector search engine.

Installation

npm install @atomstate/atomstate-rest
# or
yarn add @atomstate/atomstate-rest
# or
yarn i @atomstate/atomstate-rest

Usage

Run the Atomstate Docker container:

docker run -p 9352:9352 atomstate/atomstate

Instantiate a client

import {AtomstateClient} from '@atomstate/atomstate-rest';

const client = new AtomstateClient({host: '127.0.0.1', port: 9352});
// or
const client = new AtomstateClient({url: 'http://127.0.0.1:9352'});

Make requests

Using one of the available facade methods:

try {
    const result = await client.getCollections();
    console.log('List of collections:', result.collections);
} catch (err) {
    console.error('Could not get collections:', err);
}

Or directly using an endpoint from the API:

await client.api('collections').getCollections();

Typed Error Handling

A non-ok fetch response throws a generic ApiError

But an OpenAPI document can declare a different response type for each status code, or a default error response type.

These can be accessed via a discriminated union on status, as in code snippet below:

const findPetsByStatus = fetcher.path('/pet/findByStatus').method('get').create();
const addPet = fetcher.path('/pet').method('post').create();

try {
    const collection = await client.getCollection('bom-ada-002');
    // ...
} catch (e) {
    // verify which op threw the exception
    if (e instanceof client.getCollection.Error) {
        const error = e.getActualType();
        // sort error's logic
        if (error.status === 400) {
            error.data.status.error; // valid for a 4xx responses
        } else if (error.status === 500) {
            error.data.status.error; // valid for a 500 response
        } else {
            error.data.result;
            // ...
        }
    }
}

Support

The REST implementation uses the native fetch API, which is available in Deno and Node.js (starting from v18.0.0 without the experimental flag). The Deno implementation supports HTTP/2, while Node.js currently only supports HTTP/1.1 due to its reliance on undici.

Releases

Major and minor version numbers align with Atomstate's engine releases, while patch versions are reserved for fixes related to the current minor release.

Contributing

These are the most relevant scripts for development:

• yarn build: builds and bundles from TypeScript sources
• yarn pre-check: type-checks sources
• yarn pre-commit: same as pre-check, but for git hooks (husky)
• yarn test: run unit tests
• yarn test:integration: runs integration tests against a locally running Atomstate docker container
• yarn codegen:openapi-typescript: updates generated TS schema from the latest openapi.json remote