@elaraai/e3-api-client
TypeScript client library for e3 API servers.
Installation
npm install @elaraai/e3-api-client
Overview
Stateless functions for interacting with an e3 API server. Uses BEAST2 binary serialization for efficient request/response encoding.
API
Repository
import { repoStatus, repoGc } from '@elaraai/e3-api-client';
const status = await repoStatus('http://localhost:3000');
// { path: '/path/to/repo', objectCount: 42n, packageCount: 3n, workspaceCount: 2n }
// Keep each workspace's last 5 runs and 30 days of history; the server's
// defaults when `none`
const gcResult = await repoGc(url, { dryRun: true, minAge: none, keepRuns: some(5n), keepDays: some(30n) });
// { deletedRuns: 2n, deletedExecutions: 14n, deletedObjects: 0n, retainedObjects: 42n, bytesFreed: 0n, ... }
Packages
import { packageList, packageImport, packageGet, packageExport, packageRemove } from '@elaraai/e3-api-client';
// List all packages
const packages = await packageList(url);
// [{ name: 'my-pkg', version: '1.0.0' }, ...]
// Import a package from zip bytes
const result = await packageImport(url, zipBytes);
// { name: 'my-pkg', version: '1.0.0', packageHash: 'abc123...', objectCount: 5n }
// Get package object
const pkg = await packageGet(url, 'my-pkg', '1.0.0');
// Export package as zip
const zip = await packageExport(url, 'my-pkg', '1.0.0');
// Remove package
await packageRemove(url, 'my-pkg', '1.0.0');
Workspaces
import { workspaceList, workspaceCreate, workspaceGet, workspaceStatus, workspaceDeploy, workspaceRemove } from '@elaraai/e3-api-client';
// Create workspace
const info = await workspaceCreate(url, 'production');
// { name: 'production', deployed: false, packageName: null, packageVersion: null }
// Deploy package to workspace: the server runs the deploy as a job, which
// this polls, and answers what it decided for each record and index
const deployed = await workspaceDeploy(url, 'production', '[email protected]');
// { records: [{ record: 'records/plans', action: <mint | keep | migrate | reset | drop | refused> }], indexes: [...], warnings: [] }
// Get workspace status
const status = await workspaceStatus(url, 'production');
// { workspace: 'production', datasets: [...], tasks: [...], summary: { ... } }
// List workspaces
const workspaces = await workspaceList(url);
A view that follows a few datasets asks for those alone:
workspaceStatus(url, repo, ws, options, { paths }) answers the datasets
named that the workspace has, and the tasks producing them, each as the whole
status gives it. It costs the server what the view binds, not the workspace.
A poll asks conditionally: workspaceStatusSince(url, repo, ws, etag, options, query) answers the status with its ETag, and null while the status
answered under the tag it was given is current, which costs the server a read
of the workspace's revision and nothing else. The tag does not name the
runner's view of an execution recorded running, so a poll that must notice a
runner gone asks unconditionally (etag null) now and then. A poll gains
nothing from retrying a transient failure, since its next poll is its retry:
pollRequestOptions(options) gives it one attempt (NO_RETRY) unless the
caller set a policy of its own.
Datasets
import { datasetList, datasetListAt, datasetGet, datasetSet } from '@elaraai/e3-api-client';
import { encodeBeast2For, decodeBeast2For, StringType, variant } from '@elaraai/east';
// List root fields
const fields = await datasetList(url, 'production');
// ['inputs', 'tasks']
// List nested fields
const inputFields = await datasetListAt(url, 'production', [variant('field', 'inputs')]);
// ['config', 'data']
// Get dataset value (raw BEAST2 bytes)
const path = [variant('field', 'inputs'), variant('field', 'config')];
const bytes = await datasetGet(url, 'production', path);
const value = decodeBeast2For(StringType)(bytes);
// Set dataset value
const encoded = encodeBeast2For(StringType)('new value');
await datasetSet(url, 'production', path, encoded);
datasetGet downloads a collection as the segment objects its manifest names,
a few at a time, checks each against its hash, and splices them into the value's
bytes, so no response carries more than one segment and a server whose host
caps its responses still serves a collection of any size.
A dataset that moves while it is read (a run writes a new value, and the old
one's objects can no longer be fetched) is read again. datasetGet starts over
from the new content, at most 3 times, and returns its hash.
datasetGetStream starts over only before it returns. Once it has returned a
hash, its chunks end in a DatasetHashMismatchError naming the content the
dataset holds now (currentHash), and the caller starts over. A manifest above
level 0, which only a newer e3 writes, is refused, naming the update to make.
A value named by its hash rather than by a dataset, such as a record's state at
a past commit, is read through the objects route the same way:
collectionGetStream streams a collection by its manifest's hash,
collectionOpen opens one to read a window at a time (below), and
objectGet reads any other value, which is one object. The caller picks by
the value's type. A client of a host's own routes reads a page with
parsePage, as datasetGetPage reads its own, and a JSON refusal with
parseErrorBody, so it throws the ApiError codes the rest of the client does.
Tasks
import { taskList, taskGet } from '@elaraai/e3-api-client';
// List tasks
const tasks = await taskList(url, 'production');
// [{ name: 'compute', hash: 'abc123...', role: <data | ui> }, ...]
// Get task details
const task = await taskGet(url, 'production', 'compute');
// { name: 'compute', hash: '...', body: <east program | command>, runner: <runtime>,
// inputs: [{ path, partition }], output: { path, kind }, role: <data | ui> }
Execution
import { dataflowExecuteLaunch, dataflowExecute, dataflowGraph, taskLogs } from '@elaraai/e3-api-client';
// Start execution (non-blocking), re-running every task even where cached
await dataflowExecuteLaunch(url, 'production', { force: true });
// Execute and wait for result (blocking), re-running only the tasks named;
// a filter is one task's exact name, run with the tasks it depends on
const result = await dataflowExecute(url, 'production', { force: ['import_sales'] });
// { success: true, executed: 1n, cached: 0n, failed: 0n, tasks: [...], duration: 1.234 }
// Get dependency graph
const graph = await dataflowGraph(url, 'production');
// { tasks: [{ name: 'compute', inputs: [...], output: '...', dependsOn: [...] }] }
// Read task logs
const logs = await taskLogs(url, 'production', 'compute', { stream: 'stdout' });
// { data: '...', offset: 0n, size: 1024n, totalSize: 2048n, complete: false }
Function calls
import {
workspaceFunctionCall, workspaceFunctionStart, workspaceFunctionCallStatus, workspaceFunctionCallCancel,
workspaceCallList, workspaceCallGet,
} from '@elaraai/e3-api-client';
import { encodeBeast2For, IntegerType, none, variant } from '@elaraai/east';
// Call a function of the workspace's package and wait for its result,
// however long it runs
const stop = new AbortController();
const result = await workspaceFunctionCall(url, repo, 'production', 'forecast', {
args: [variant('value', encodeBeast2For(IntegerType)(12n))], runner: none, limits: none,
}, options, { signal: stop.signal, onStarted: (id) => console.log(`call ${id} runs on`) });
// { outcome: <success | failed | invalid | too_large | timed_out>, stdout, stderr, inputs, ... }
// The calls the workspace keeps, the latest first, and one whole
const page = await workspaceCallList(url, repo, 'production', options, { state: 'failed' });
// { calls: [{ id, function: <some(name) | none for a one-shot>, caller, startedAt, endedAt, state }, ...], next: <none | some(cursor)> }
const call = await workspaceCallGet(url, repo, 'production', page.calls[0].id, options);
// { function, package: <some({ name, version }) | none>, args, inputs, limits, state: <succeeded { value: hash } | …>, stdout, stderr, expiresAt, ... }
A call through a workspace is the server's, and outlives the request that
starts it. workspaceFunctionCall starts it, which waits up to the server's
window (20 s), and polls a call still running to its end, each poll held by
the server until the call ends or a while passes, 250 ms apart at first and
backing off to 2 s: a call runs as long as its timeout allows, the server's
ceiling unless its limits ask for less. The client names the call before it
sends it, a UUIDv7 of its own, so aborting signal stops waiting at once —
whatever the fetch does with the abort — and asks the server to stop the
call by that id, its start's answer or not; the ask is sent keepalive, so
one a closing page makes still reaches the server. onStarted is told the id
of a call that runs on past its start, and startWaitMs tells it sooner. A
server that predates kept calls is called
through the sync route, workspaceFunctionCallSync, which a caller may also
name itself to answer within one request.
The pieces apart: workspaceFunctionStart(…, { waitMs, id }) answers the call's
id and status (?wait=0 answers running at once; an id of the caller's, a
UUIDv7 of now, names the call, and the server sets aside one far from its
clock), workspaceFunctionCallStatus(…, id, options, { waitMs, signal }) its status — running, completed with its
result, cancelled naming who asked, or lost — and
workspaceFunctionCallCancel asks a running call to stop. The server keeps
each call for its lifetime, an hour for a success or a cancel and a week for
any other end: who made it, its arguments, the versions of the inputs it read,
its value and its logs, by hash, which objectGet reads.
One-shot calls
import { oneShotCall, oneShotExecute } from '@elaraai/e3-api-client';
// Run a program of the caller's over the workspace's datasets, kept among the
// workspace's calls, and wait for its result however long it runs
const result = await oneShotCall(url, repo, 'production', request, options, { signal: stop.signal });
// { outcome: <success | failed | invalid | too_large | timed_out>, stdout, stderr, inputs, ... }
// Or within one request, its timeout clamped under the server's sync
// deadline, keeping nothing
const quick = await oneShotExecute(url, repo, 'production', request, options);
A one-shot is held to the caller's grant: one who may read the workspace runs
a platform-free program, a stock runner given no platform and a body that calls
none, and only an elevated grant any other. oneShotCall starts it as a call
(oneShotStart) and follows it as workspaceFunctionCall follows a
function's: its timeout the server's ceiling unless its limits ask for less,
polled to its end, stopped by signal through the id the client named it by,
and onStarted told its id. The workspace keeps it, naming no function or
package, so workspaceCallList lists it and workspaceCallGet reads it, and
its status and cancel are a function call's (workspaceFunctionCallStatus,
workspaceFunctionCallCancel). A server that predates kept one-shots runs it
within one request, as oneShotExecute does.
Split calls
import { collectionOpen, splitCall, splitCallCancel, splitCallLaunch, splitCallStatus } from '@elaraai/e3-api-client';
import { decodeBeast2For, variant } from '@elaraai/east';
// Run a program over a dataset's pieces as a job, polled to its end. Aborting
// the signal stops polling and cancels the job, so the server stops its units;
// the call rejects with the signal's reason.
const controller = new AbortController();
const { result, output, report } = await splitCall(url, 'my-repo', 'production', request, { token }, {
onProgress: (progress) => console.log(progress.phase.type, progress.done, progress.units),
signal: controller.signal,
});
// report: { pieces, ran, cached, peakBytes } — the pieces its input was cut
// into, the units this call ran and the cache served it, and the highest peak
// a unit reached. A call the cache served whole ran 0 and was served 0, and
// still names its pieces and peak.
// An array's first `limit` elements, in input order: the body emits as an
// array call's does, and the pieces run in order, a few at a time, stopping
// once they hold that many. The pieces are shared with an array call's.
const firstMatch = await splitCall(url, 'my-repo', 'production', { ...request, output: variant('first', { limit: 1n }) }, { token });
// A value over the call's result limit is answered too_large, naming the
// stored output instead: open it, and read it a window at a time. Each window
// fetches only the segments it overlaps, each checked against its hash.
if (result.outcome.type === 'too_large' && output !== null) {
const remote = await collectionOpen(url, 'my-repo', output, { token });
// remote.type: the collection's type; remote.totalElements: how many it holds
const page = await remote.page({ offset: 1_000, limit: 100 });
const rows = decodeBeast2For(remote.type)(page.data);
// page.count: fewer than asked at the end, and none past it
}
// Or launch, poll and cancel it yourself
const { id } = await splitCallLaunch(url, 'my-repo', 'production', request, { token });
const status = await splitCallStatus(url, 'my-repo', 'production', id, { token });
// processing | completed { result, output, report } | planned | failed | cancelled
const after = await splitCallCancel(url, 'my-repo', 'production', id, { token });
// cancelled, or the status the job had already ended with
Claude Code plugin
The East ecosystem also ships a Claude Code plugin — East language skills, example search, and preemptive diagnostics for East code — installed separately from the elaraai marketplace:
# Inside Claude Code
/plugin marketplace add elaraai/east-workspace
/plugin install east@elaraai
# From a terminal
claude plugin marketplace add elaraai/east-workspace
claude plugin install east@elaraai
License
BSL 1.1. See LICENSE.md.
Ecosystem
-
East: Statically typed, expression-based language with serializable IR. Run portable logic across TypeScript, Python, C, and other runtimes.
- @elaraai/east: Core language SDK with type system, expressions, and reference JS compiler
-
East Node: Node.js platform functions for I/O, databases, and system operations.
- @elaraai/east-node-std: Console, FileSystem, Fetch, Crypto, Time, Path, Random
- @elaraai/east-node-io: SQLite, PostgreSQL, MySQL, MongoDB, Redis, S3, FTP, SFTP, XLSX, XML, compression
- @elaraai/east-node-cli: CLI for running East IR programs in Node.js
-
East C: C11 native runtime for executing East IR. Distributed via npm (launcher + per-platform optional dependencies) and as tarballs on each GitHub Release.
- @elaraai/east-c-cli: npm launcher — installs the matching native binary as an optional dependency
east-c: Core runtime — type system, IR interpreter, builtins, serialization (Beast2, JSON, CSV, East text)east-c-std: Console, FileSystem, Fetch, Crypto, Time, Path, Randomeast-c-cli: CLI for running East IR programs natively
-
East Python: Python runtime, standard platform, I/O, and data-science platform functions. Published to PyPI.
- east-py: Core Python runtime — type system, IR compiler, 212+ builtins, Cython-accelerated hot paths
- east-py-std: Console, FileSystem, Fetch, Crypto, Time, Path, Random
- east-py-io: SQLite, PostgreSQL, MySQL, MongoDB, Redis, S3, FTP, SFTP, XLSX, XML, compression
- east-py-cli: CLI for running East IR programs in Python
- east-py-datascience (PyPI) + @elaraai/east-py-datascience (npm): Optimization (MADS, Optuna, ALNS, GoogleOR), ML (XGBoost, LightGBM, NGBoost, PyTorch, Lightning, GP), Bayesian inference (PyMC), explainability (SHAP), conformal prediction (MAPIE)
-
East UI: Typed UI component definitions and React renderer, plus VS Code preview.
- @elaraai/east-ui: 50+ typed UI components for layouts, forms, charts, tables, dialogs
- @elaraai/east-ui-components: React renderer with Chakra UI v3 styling
- @elaraai/e3-ui: e3 + UI bridge — Data bindings,
e3.ui()task, manifest - @elaraai/e3-ui-components: React Query hooks and preview components for the e3 API
-
e3 — East Execution Engine: Durable execution engine for running East pipelines at scale. Git-like content-addressable storage, automatic memoization, reactive dataflow, real-time monitoring.
- @elaraai/e3: SDK for authoring e3 packages with typed tasks and pipelines
- @elaraai/e3-core: Object store, dataflow orchestrator, execution state
- @elaraai/e3-types: Shared type definitions for e3 packages
- @elaraai/e3-cli:
e3 repo,e3 package,e3 workspace,e3 dataflow run,e3 watch,e3 task logscommands - @elaraai/e3-api-client: HTTP client for remote e3 repositories
- @elaraai/e3-api-server: REST API server for e3 repositories
- @elaraai/e3-api-tests: Shared API compliance test suites
Links
About Elara
East is developed by Elara AI Pty Ltd, an AI-powered platform that creates economic digital twins of businesses that optimize performance. Elara combines business objectives, decisions and data to help organizations make data-driven decisions across operations, purchasing, sales and customer engagement, and project and investment planning. East powers the computational layer of Elara solutions, enabling the expression of complex business logic and data in a simple, type-safe and portable language.
Developed by Elara AI Pty Ltd.
Developed by Elara AI Pty Ltd