Getting started

Installation

Install the package, meet the requirements, and put an API key where the runtime can find it.

Install the package#

$npm i jevascript

The package has zero runtime dependencies. It uses the platform's fetch, AbortSignal.any and AbortSignal.timeout, which is why it needs a recent Node.

Requirements#

	Minimum	Notes
Node.js	22.6	`AbortSignal.any` and `--experimental-strip-types` landed here.
TypeScript	5.0	Types are shipped in the package. `moduleResolution` must be `bundler`, `node16` or `nodenext`.
Module system	ESM	The package is ESM only. See below if your project is CommonJS.

Bun and Deno work with the same code paths; both implement the standard fetch and AbortSignal APIs the package relies on.

ESM only#

jevascript ships as ES modules. In a Node project, either set "type": "module" in package.json or use .mts files. require("jevascript") is not supported.

If you must call it from CommonJS, use a dynamic import:

legacy.cjs

const { semantic } = await import("jevascript")

Two entry points#

Import	Contains
`jevascript`	The runtime: `semantic`, `createSemantic`, the primitives, definitions, collections, providers, errors and every type.
`jevascript/testing`	`createMockSemanticProvider`, a provider that answers from a lookup table so tests run without a network or a key.

Add the API key#

The first provider is Jev, a decision model reached over HTTPS. It needs an API key. Put it in the environment under JEV_API_KEY and the runtime configures itself on first use:

.env

JEV_API_KEY=apikey_...

How the variable reaches your process depends on how you run it:

node --env-file=.env app.ts

import "dotenv/config"
import { semantic } from "jevascript"

Next.js, Nuxt, SvelteKit, Remix and Astro load .env files themselves. Add JEV_API_KEY to .env.local or your host's secret store. Never prefix it with NEXT_PUBLIC_ or VITE_; the key must stay on the server.

Verify the install#

This runs without a key. The mock provider answers from a table instead of the network, so it proves the import, the types and the batching:

check.ts

import { createSemantic } from "jevascript"
import { createMockSemanticProvider } from "jevascript/testing"

const provider = createMockSemanticProvider({ urgent: 0.9 })
const semantic = createSemantic({ provider })

const urgent = await semantic("All card payments are failing.").is("This is urgent.")

console.log(urgent)               // true
console.log(provider.requestCount) // 1

node --experimental-strip-types check.ts

If you see true and 1, the package is installed correctly. Continue with the quick start.

Upgrading#

The API may change before 1.0. Pin a minor version in package.json and read the changelog before moving between minors. Within a minor, releases are additive.