Interscript API software — the GraphQL transliteration API as deployable software for Cloudflare Workers (or any Workers-compatible runtime).
This repository is the software only. Deployment configurations
(routes, domains, secrets, CI) live in separate deployment repositories —
interscript's own is interscript/api.interscript.org.
Any organization can deploy this package privately on their own domain.
Field-for-field identical to the long-running Ruby API:
| field | behavior |
|---|---|
info |
version JSON |
systemCodes |
all 287 transliteration systems |
transliterate(systemCode!, input!) |
transliterate (1MB input cap) |
detect(input!, output!) |
ranked [{mapName, distance}] |
Error strings match byte-for-byte (Couldn't locate <code>).
- Engine: the native async interpreter from
interscript-ts— no regex compilation. - Maps: the full corpus (287 systems + 4 dependency libraries,
compiled to schema-versioned JSON IR from interscript-maps) is a
deploy-time asset, not part of this npm package. Deployment repos fetch
a pinned map artifact from
interscript/maps, verify it, and expose it through the Workers Assets binding. Immutable per release, edge-cached, zero runtime third-party fetches. - Server: Hono + GraphQL Yoga.
npm install @interscript/api-worker
# Then fetch/extract a pinned interscript/maps JSON-IR artifact into ./maps.
# Do not copy maps from this npm package; the package is code-only.Minimal wrangler.jsonc:
A canonical wrangler.jsonc ships in this repository (no routes, no
secrets) — start from it, add your route, then wrangler deploy. It
includes an alias entry that redirects the engine's optional
onnxruntime-node probe to a stub (stubs/onnxruntime-node.js) so the
Worker bundle never traverses the native binary; if your own config
hits a "No loader is configured for ".node" files" error, add the same
alias. If you edit the config, regenerate the ambient runtime types
with npm run gen:types (writes worker-configuration.d.ts).
See the deployment repo
for a complete, working example (it pins this package and fetches a
release map artifact — the deploy commands there stay owner-run).
npm install
npm run build # tsc + esbuild bundle
npm test # vitest (incl. the production parity gate)
npm run typecheck
npm run lint
npm run gen:types # regenerate worker-configuration.d.ts after wrangler.jsonc editsRegenerating the map corpus (requires the interscript/maps and interscript-ts checkouts — the same TS converter that builds the interscript/maps release artifact):
node scripts/build-maps.mjs /path/to/interscript/maps /path/to/interscript-tsFor production deploys, prefer a pinned release artifact from
interscript/maps over local regeneration; verify the artifact checksum
before wrangler deploy.
test/fixtures/parity.json holds queries recorded from the production
Ruby API; CI replays them against this implementation. Zero-diff is the
release gate.
REST endpoints serve alongside GraphQL (which remains at POST /graphql):
GET /openapi.json— the OpenAPI 3.1 documentGET /v1/info— version + capability summaryGET /v1/maps/GET /v1/maps/{code}— bundled transliteration systemsPOST /v1/transliterate—{system, input}→{output}POST /v1/detect—{input, output}→ ranked systemsGET /v1/models/GET /v1/models/{id}— the neural model index (IMF v1, generated from interscript-ml's models.yaml vianpm run gen:models)POST /v1/infer—{model, input}→{output}; proxies to the inference service configured withML_ENDPOINT+ML_TOKENenv vars (Interscript runssrc/api/inference.pyon Modal: the same parity-verified ONNX decode that gates every release)
{ "name": "my-interscript-api", "main": "src/index.ts", "compatibility_date": "2026-08-01", "assets": { "directory": "./maps", "binding": "ASSETS", }, "routes": [{ "pattern": "api.example.org/*" }], }