arrakis-js/README.md

Arrakis Javascript client library

# arrakis-js

Arrakis Javascript client library

[![npm](https://img.shields.io/npm/v/arrakis-js.svg)](https://www.npmjs.com/package/arrakis-js)
[![CI](https://git.ligo.org/ngdd/arrakis-js/badges/main/pipeline.svg)](https://git.ligo.org/ngdd/arrakis-js)

---

## Installation

This library is built as an ES module and works in both browser and Node.js environments.

### npm/yarn/pnpm

```bash
npm install arrakis-js
# or
yarn add arrakis-js
# or
pnpm add arrakis-js
```

### CDN

For browser usage, you can load the library directly from a CDN:

```html
<script type="module">
  import * as arrakis from 'https://cdn.jsdelivr.net/npm/arrakis-js/dist/index.js';
</script>
```

Or as a traditional script (creates global `arrakis` object):

```html
<script src="https://cdn.jsdelivr.net/npm/arrakis-js/dist/arrakis.min.js"></script>
```

### Node.js

For Node.js projects, you can use dynamic imports:

```javascript
const arrakis = await import('arrakis-js');
```

**Note:** The `find()` function requires an EventSource polyfill in Node.js:

```bash
npm install eventsource
```

## Server compatibility

This client targets the [Arrakis REST API](https://git.ligo.org/ngdd/arrakis-rest-api) `/api/v1/*` endpoints (`/api/v1/stream`, `/api/v1/count`, `/api/v1/find`, `/api/v1/describe`). See the upstream project for endpoint documentation and raw `curl` examples.

By default the client connects to `/arrakis` (typical reverse-proxy deployment).
Set the REST server base URL via the `Client` constructor -e.g `http://localhost:8000`- when running the REST API locally.

## Features

* Query live and historical timeseries data
* Describe channel metadata
* Search for channels matching a set of conditions

## Quickstart

### Stream timeseries

##### 1. Live data

``` javascript
import * as arrakis from 'arrakis-js';

const channels = [
    "H1:CAL-DELTAL_EXTERNAL_DQ",
    "H1:LSC-POP_A_LF_OUT_DQ",
];

for await (const block of arrakis.stream(channels)) {
	console.log(block);
}
```

##### 2. Historical data

``` javascript
import * as arrakis from 'arrakis-js';

const start = 1187000000;
const end = 1187001000;
const channels = [
    "H1:CAL-DELTAL_EXTERNAL_DQ",
    "H1:LSC-POP_A_LF_OUT_DQ",
];

for await (const block of arrakis.stream(channels, start, end)) {
    console.log(block);
}
```

### Describe metadata

``` javascript
import * as arrakis from 'arrakis-js';

const channels = [
    "H1:CAL-DELTAL_EXTERNAL_DQ",
    "H1:LSC-POP_A_LF_OUT_DQ",
];

const metadata = await arrakis.describe(channels);
```

where `metadata` is a dictionary mapping channel names to
`arrakis.channel.Channel`.

### Find channels

``` javascript
import * as arrakis from 'arrakis-js';

for await (const channel of arrakis.find("H1:LSC-*")) {
    console.log(channel);
}
```

where `channel` is an `arrakis.channel.Channel`.

### Count channels

``` javascript
import * as arrakis from 'arrakis-js';

const count = await arrakis.count("H1:LSC-*");
```

### Fetch timeseries data

``` javascript
import * as arrakis from 'arrakis-js';

const channels = [
    "H1:CAL-DELTAL_EXTERNAL_DQ",
    "H1:LSC-POP_A_LF_OUT_DQ",
];
const start = 1187000000;
const end = 1187001000;
const block = await arrakis.fetch(channels, start, end);
```

where `block` is an `arrakis.block.SeriesBlock`.

### GPS time utilities

``` javascript
import * as arrakis from 'arrakis-js';

const gpsTime = arrakis.now();
```

where `gpsTime` is the current time in GPS milliseconds.

``` javascript
import * as arrakis from 'arrakis-js';

const unixTime = arrakis.gpsToUnix(gpsTime);
const date = new Date(unixTime);
```

where `unixTime` is the current time in Unix time milliseconds and `date` is a JavaScript `Date` object.

``` javascript
import * as arrakis from 'arrakis-js';

const anyDate = new Date("2026-01-01");
const gpsTime = arrakis.unixToGps(anyDate.getTime());
```

where `gpsTime` is the time in GPS milliseconds for the given date.