JavaScript / TypeScript • npm jangada-ai

Jangada in JavaScript and TypeScript

The TypeScript port of the Python library, with the same idea: swap provider, model and key without touching the rest of your code, with retry and fallback by error type, structured output (Zod), tools, streaming, agents, MCP, RAG and cost on every response. Runs on Node 22+, Bun, Deno and edge.

$npm install jangada-aiPrefer Python?→

trocar-provider.ts

PythonTypeScript

import { LLM } from "jangada-ai";
// troque o provider numa linha, o resto não muda
let llm = new LLM("anthropic", "claude-sonnet-4-5");
llm = new LLM("openai",    "gpt-5");
const r = await llm.complete("Resuma {{ tema }}.");
console.log(r.text, r.cost);

With fallback and a template:

import { LLM } from "jangada-ai";
import "jangada-ai/node"; // loads the project's .env

const llm = new LLM("openai", "gpt-4o-mini", {
  fallbacks: [new LLM("anthropic", "claude-haiku-4-5")],
});
const comp = await llm.complete("Hi, {{ name }}!", { variables: { name: "Ana" } });
console.log(comp.text, comp.usage, comp.cost);

Current version: 1.0.5 (npm). The VERSION constant exported by the package holds the same number.

What's in the package

The source is TypeScript. The published package is JavaScript in two formats, ESM (import) and CommonJS (require), with the types (.d.ts) included. It works in plain JS projects; in TypeScript you get autocomplete and type checking without installing any @types package.

It runs on Node 22 or newer, Bun, Deno and edge runtimes (Cloudflare Workers, Vercel Edge). The core does not use the file system or any node:* module. What depends on Node (reading files, loading .env, starting an HTTP server) lives in the jangada-ai/node subpath.

SDKs loaded on demand

The provider SDKs (openai, @anthropic-ai/sdk, @google/genai and others) are optional peerDependencies. Install only the ones you use. Each provider's adapter is loaded on the first call, and the SDK comes in through await import() inside it. That is why import "jangada-ai" works with no SDK installed, and an app that only uses OpenAI never loads the Anthropic adapter.

If the SDK is missing, the error shows up on the first call, with the install command in the message (Instale o SDK da OpenAI para usar 'openai': npm install openai). The full peer table is in Getting started.

Parity with Python

Version 1.0 covers what the Python library does: 11 providers, retry and fallback, structured output, tools and native tools, streaming, vision and documents, transcription, embeddings, OCR, cost, cache, guardrails, agents, MCP, RAG, Gemini Interactions, A2A, observability and eval.

The test cases for templates, error classification, cost calculation, profiles and the price catalog are generated by the Python library and run against the port, so both sides give the same result. RAG uses the same schema in Postgres and MongoDB: Python and JS can read and write the same database.

The differences come from the language: async-only API, camelCase names, template variables in an object, Zod instead of Pydantic, signal to cancel. The full list is in Differences from Python.

Pages in this section

Getting started:

• Getting started: installation, .env, first call in ESM and CommonJS.
• Providers: the 11 providers, keys, apiKey, clientOptions and per-provider details.
• Parameters: {{ }} templates, generation params, per-model profiles and call options.
• Differences from Python

Capabilities:

• Structured output: Zod, Standard Schema and JSON Schema with parse().
• Tools: tool(), the tool call loop and native tools.
• Streaming: stream(), streamComplete() and cancellation.
• Vision and documents
• Agents
• MCP
• RAG
• Gemini Interactions
• A2A
• Guardrails
• Observability
• Eval

Reliability:

• Errors and fallback
• Cost and cache