@hew-lang/playground-client

Lightweight TypeScript client for the Hew Playground API.

Install

Install the compiled archive from the versioned public release:

npm install https://github.com/hew-lang/playground-client/releases/download/v0.3.5/hew-lang-playground-client-0.3.5.tgz

The archive includes JavaScript and TypeScript declarations. It needs no GitHub package token. The release also includes SHA256SUMS; consumers should commit their package-manager lockfile to pin the archive's integrity.

Simplest usage

import { HewPlaygroundClient } from '@hew-lang/playground-client';

const client = new HewPlaygroundClient('https://livecode-v1.hew.sh');

const result = await client.run(`
import std.io.scanner.{words};

enum Greeting {
  Message(string);
}

fn main() {
  let tokens = words("hello");
  let greeting: Greeting = .Message("hello");
  match greeting {
    .Message(text) => println(text),
  }
  println(tokens.len());
}
`);
console.log(result.stdout);

Hew 0.6.2 uses dotted module paths and grouped selections such as std.io.scanner.{words}. Variant constructors and patterns are contextual, so use .Message when the enum type is known. In this release, retired :: paths and Rust-style turbofish syntax produce migration diagnostics such as E_PATH_LEGACY_SEPARATOR and E_LEGACY_TURBOFISH.

This client neither embeds a compiler nor interprets compiler diagnostics: it transports source and preserves opaque compiler stderr from the server. Its default follows the server's current compiler; diagnostic text, codes, and supported syntax remain compiler-version-dependent. Use listVersions() to see which versions the server currently provides.

Execution targets

The hosted API runs native programs. It refuses execution_mode: "wasm" with HTTP 422 and never silently runs the request natively. For local browser execution, use @hew-lang/playground-sandbox. Its compiler and VM report capability refusals explicitly. Upgrade those two local engine packages together; they do not change the remote compiler selected by this HTTP client. Await both clients' run() calls and display compiler-authored errors, notes and suggestions without translating them into a different set of diagnostic rules.

Runtime requirements

• Works in modern browsers.
• Works in Node.js when fetch is available globally.
• For older runtimes or custom transport, pass your own fetch implementation in the client options.

Client construction

import { HewPlaygroundClient } from '@hew-lang/playground-client';

const client = new HewPlaygroundClient({
  baseUrl: 'https://livecode-v1.hew.sh',
  headers: {
    Authorization: 'Bearer <token>',
  },
});

Compiler version selection

By default, run() omits compiler_version so the server chooses its current default. Pin a version client-wide or per request when reproducible version selection is required. Passing null also selects the server default:

// Pin a version client-wide
const pinned = new HewPlaygroundClient({
  baseUrl: 'https://livecode-v1.hew.sh',
  compilerVersion: '0.4.0',
});

// Let the server decide (tracks the server's default as it advances)
const tracking = new HewPlaygroundClient({
  baseUrl: 'https://livecode-v1.hew.sh',
  compilerVersion: null,
});

// Per-request override
await pinned.run({ source: 'fn main() {}', compiler_version: '0.5.1' });

Examples returned by listExamples() carry a capabilities object describing their execution tier (browser is always 'analysis-only'; wasi is 'runnable' or 'unsupported').

Constructor options

Option	Type	Description
baseUrl	string	Base URL of the playground server.
fetch	PlaygroundFetch	Optional custom fetch implementation.
headers	PlaygroundHeadersInit	Optional default headers added to every request.
compilerVersion	string | null	Optional compiler_version sent on every run(). Omit it or pass null to use the server default.

API overview

The client mirrors the HTTP API with typed methods:

Method	Description
health()	Returns the plain-text health response.
run(sourceOrRequest)	Compiles and runs Hew source code.
listVersions()	Lists available compiler versions and the server default.
listExamples()	Lists built-in example programs.
createShare(sourceOrRequest)	Stores source code and returns a share ID.
getShare(id)	Fetches a previously shared snippet.

The package exports these request/response types:

• RunRequest, RunResponse
• Example, ExampleCapabilities
• ShareRequest, ShareResponse, ShareGetResponse
• VersionsResponse
• ErrorResponse
• PlaygroundClientOptions
• PlaygroundApiError

It also exports the createHewPlaygroundClient() factory and the isPlaygroundApiError() type guard.

Error handling

Non-2xx HTTP responses throw PlaygroundApiError.

import { HewPlaygroundClient, PlaygroundApiError } from '@hew-lang/playground-client';

const client = new HewPlaygroundClient('https://livecode-v1.hew.sh');

try {
  const share = await client.createShare('fn main() { println(1); }');
  console.log(share.id);
} catch (error) {
  if (error instanceof PlaygroundApiError) {
    console.error(error.status, error.body);
  }
}

run() has one important API-level nuance: compile failures still come back as a normal JSON RunResponse, so check success, compile_error, and exit_code rather than assuming every unsuccessful program run throws.

The share API stores source only. A UI that pins a shared snippet must retain the compiler version in its URL and pass that value to run() when executing the snippet.

Related artifacts

• openapi.json — machine-readable HTTP API specification.
• hew-playground-client.ts — canonical single-file SDK source if you want to vendor the client directly.

For a local checkout of this repository, you can swap the import path to ./hew-playground-client.

Releasing

1. Bump version in package.json and update the README/API docs.
2. Run npm run test:sdk locally.
3. Commit and push to main.
4. After publication approval, tag the release. The Release workflow checks the exact tag/version, installs and tests without registry credentials, then publishes the compiled archive and SHA256SUMS with the release notes.

An approved older tag can be packaged with the workflow's release_tag input. Reruns compare existing assets and refuse to replace different bytes. The separate Publish workflow remains available for optional registry mirrors; its ownership and permissions are unchanged.

License

MIT License. Copyright (c) 2026 Stephen Olesen.