ThingTalk

2.1.1 verified Fri May 01 auth: no javascript

ThingTalk is a declarative, rule-based distributed programming language for virtual assistants, developed by Stanford Open Virtual Assistant Lab. This package (v2.1.1, not semver: minor bumps can break library APIs) provides the grammar, just-in-time compiler, interface for SMT-based program analysis, natural language translation, and runtime libraries. It connects web services and IoT devices via 'when-get-do' statements, leveraging Thingpedia API primitives. Differentiators: unique focus on virtual assistants, crowdsourced API repository, and non-semver versioning where minor versions may introduce breaking API changes. Release cadence: irregular, with major version bumps for language incompatibility, minor for library changes, patch for bug fixes.

Common errors

error SyntaxError: Unexpected token ↓

cause Invalid ThingTalk syntax, possibly due to missing semicolons or wrong invocation syntax.

fix

Ensure each statement ends with a semicolon and uses correct triple arrow syntax: => @service.function(params). Refer to ThingTalk language specification.

error Error: Cannot find module 'thingtalk' ↓

cause Missing dependency or incorrect import path in CommonJS project.

fix

Run npm install thingtalk and use import { compile } from 'thingtalk' (ESM) or ensure your bundler supports ESM. For CommonJS, use dynamic import: const { compile } = await import('thingtalk').

error TypeError: compile is not a function ↓

cause Importing default export instead of named export.

fix

Replace import compile from 'thingtalk' with import { compile } from 'thingtalk'.

error ThingTalk version mismatch: expected 2.1.x, got 2.2.0 ↓

cause Generating syntax with a newer library version that is incompatible with the client version specified.

fix

Pass { libraryVersion: '2.1.0' } in the compile options to output syntax compatible with the older client.

Warnings

breaking Minor version bumps can break library APIs. Use tilde version ranges. ↓

fix Specify dependency as "thingtalk": "~2.1.0" in package.json to allow only patch updates.

gotcha No default export; all exports are named. ↓

fix Use named imports like `import { compile } from 'thingtalk'` instead of `import compile from 'thingtalk'`.

deprecated The `translate` function has been deprecated in favor of `compileWithTranslation`. ↓

fix Use `compileWithTranslation` instead.

gotcha ThingTalk syntax generated by a newer version may not parse with an older client. Specify library version for compatibility. ↓

fix Pass `{ libraryVersion: '2.1.0' }` in options when compiling for older clients.

Install

npm install thingtalk

yarn add thingtalk

pnpm add thingtalk

Imports

compile

wrong

const compile = require('thingtalk').compile;

correct

import { compile } from 'thingtalk'

ESM only since v2; no default export

Grammar

wrong

import Grammar from 'thingtalk';

correct

import { Grammar } from 'thingtalk'

Grammar is a named export, not default

Ast
wrong
```
import { Ast } from 'thingtalk';
```
correct
```
import type { Ast } from 'thingtalk'
```
Ast is a type; use 'import type' in TypeScript to avoid runtime import

Quickstart

Compiles a ThingTalk program that monitors Washington Post articles, translates to Chinese, and posts to Facebook.

import { compile } from 'thingtalk';

const code = `
monitor(@com.washingtonpost.get_article(section=enum world))
=> @com.yandex.translate.translate(target_language="zh", text=title)
=> @com.facebook.post(status=$result);
`;

try {
  const compiled = compile(code, { locale: 'en-US', timezone: 'America/Los_Angeles' });
  console.log('Compiled program:', JSON.stringify(compiled, null, 2));
} catch (err) {
  console.error('Compilation failed:', err);
}