TypeScript SDK
Reference for the TypeScript SDK (npm `telys-ai`) — the encapsulated in-process runtime, the Telys/Collection surface, Eq filters, persistence shared with Python, and the runtime ops.
Telys ships a TypeScript SDK alongside the Python one: npm install telys-ai (Node >= 22). It is the same engine with the same guarantees — embedded, on-device, zero cloud roundtrips at query time — loaded in-process inside your Node process. There is no sidecar process and nothing to manage.
npm install telys-aiimport { Telys, Eq } from "telys-ai";
const db = await Telys.open("./memory");
const col = db.createCollection("docs", {
dim: 768,
partitionBy: "tenant_id",
filterColumns: ["lang"],
});
col.add(vectors, ids, metadata); // bring your own vectors (embedding-agnostic)
const hits = col.search(queryVec, {
topK: 10,
where: new Eq("tenant_id", "acme"),
explain: true,
});How the runtime gets there (encapsulated)
The closed Mojo runtime (libty_runtime) is loaded through a frozen C-ABI inside your process:
A runtime already installed by the Python CLI (
telys runtime install) is reused from$TELYS_HOME/runtime/<platform>/(default~/.telys) — both SDKs share one verified install.Otherwise, when a token is available (
TELYS_TOKEN/TELYS_API_KEY), the SDK fetches the signed bundle itself from the download host and verifies it OFFLINE — RS256 manifest signature over the exact shipped bytes, SHA-256 artifact hashes, and the strict ver:2 license policy (alg pinned to RS256, nocrit, issuer/audience/expiry/grace,products.telyswith a tier + features). This is the same trust core as the Python SDK, ported tonode:crypto.
Installing the runtime is the only networked step. Queries never touch the network.
The surface
Engine
await Telys.open(path) · Telys.openSync(path) · createCollection · openCollection · collections() · scopeKey(...parts)
Collection
add (new ids only) · upsert · update (strict — unknown ids raise) · search · ids(where?) · fetch(ids) · delete · compact · snapshot · stats · save
Filters
new Eq(column, value) on the partition key or a declared filter column
Runtime ops
ensureRuntime() · installFromHost() · installFromFile() · verifyInstalled() · resolveRuntimeLib()
Trust core
verifyManifest() · verifyLicense() · verifyArtifact()
Semantics match the Python SDK exactly: add raises on existing ids, upsert adds-or-replaces (a new visible version, never a duplicate row), update replaces existing rows only and raises for unknown or deleted ids, deletes are tombstones reclaimed by compact.
Shared persistence
Collections persist in the same on-disk format as the Python SDK (ty_base.npy + ty_native.json + collection.json), so a store is portable across languages in either direction — a collection written by Python opens in TypeScript and vice versa.
Scope today
Vectors in, vectors out: filtered dense search over bring-your-own embeddings. Text embedders (the kernel-backed bigram/multigram) and the lexical code index are Python-side today and come to this SDK later — from TypeScript, embed with any model and pass the vectors.
Platforms: macOS arm64 and Linux x86_64 runtime targets (the signed-bundle P0 set). See Supported platforms.
Next
Last updated
Was this helpful?