TypeScript SDK

KodiScript TypeScript SDK provides a lightweight, embeddable scripting language for JavaScript/TypeScript applications.

Installation

npm install @issadicko/kodi-script
# or
yarn add @issadicko/kodi-script
# or
pnpm add @issadicko/kodi-script

Quick Start

import { KodiScript } from '@issadicko/kodi-script';
 
const result = KodiScript.run(`
  let name = "World"
  print("Hello " + name)
`);
 
console.log(result.output); // ['Hello World']

Variable Injection

const result = KodiScript.run(`
  let greeting = "Hello " + user.name
  let status = user?.active ?: "offline"
  print(greeting)
`, {
  user: { name: 'Alice', active: true }
});

Builder Pattern

const result = KodiScript.builder(`
  let greeting = customGreet("World")
  print(greeting)
`)
  .withVariable('version', '1.0')
  .registerFunction('customGreet', (name) => `Hello, ${name}!`)
  .execute();

API Reference

`KodiScript.run(source, variables?)`

Runs a script with optional variables and returns a ScriptResult.

type ErrorKind = 'none' | 'parse' | 'runtime' | 'timeout' | 'max_operations';
 
interface ScriptResult {
  output: string[];    // print() output, in order
  value: unknown;      // final expression value
  errors: string[];    // error messages (empty on success)
  errorKind: ErrorKind; // typed error category
}

`KodiScript.builder(source)`

Creates a builder for advanced configuration. The builder methods are chainable:

Method	Description
`.withVariable(name, value)`	Inject a single variable
`.withVariables({ ... })`	Inject multiple variables
`.registerFunction(name, fn)`	Register a custom native function
`.bind(name, obj)`	Bind an object so scripts can call its methods/properties
`.silentPrint(true)`	Capture `print()` output without writing to the console
`.withOutput(sink)`	Route each `print()` line to a callback (still captured)
`.withCache(true)`	Enable AST caching (on by default)
`.withMaxOperations(n)`	Cap the number of operations
`.withTimeout(ms)`	Cap wall-clock execution time
`.execute()`	Run and return a `ScriptResult`

const result = KodiScript.builder('add(2, 3)')
  .withVariable('multiplier', 10)
  .withVariables({ x: 1, y: 2 })
  .registerFunction('add', (a, b) => a + b)
  .execute();

Streaming output with `withOutput`

Receive each printed line as it happens instead of reading result.output at the end:

const lines: string[] = [];
KodiScript.builder('print("a")\nprint("b")')
  .withOutput(line => lines.push(line))
  .execute();
// lines === ['a', 'b']

Handling errors by kind

const result = KodiScript.builder(script).withMaxOperations(1000).execute();
 
switch (result.errorKind) {
  case 'none':           /* success */ break;
  case 'parse':          /* syntax error */ break;
  case 'runtime':        /* bad operation, undefined variable, recursion, ... */ break;
  case 'timeout':        /* exceeded withTimeout */ break;
  case 'max_operations': /* exceeded withMaxOperations */ break;
}

Custom Functions

const result = KodiScript.builder(`
  let doubled = double(21)
  let greeting = greet("TypeScript")
  print(greeting + " - " + doubled)
`)
  .registerFunction('double', (n) => n * 2)
  .registerFunction('greet', (name) => `Hello, ${name}!`)
  .execute();
 
console.log(result.output); // ['Hello, TypeScript! - 42']

Express.js Integration

import express from 'express';
import { KodiScript } from '@issadicko/kodi-script';
 
const app = express();
app.use(express.json());
 
app.post('/api/execute', (req, res) => {
  const { script, variables } = req.body;
  
  try {
    const result = KodiScript.run(script, variables);
    res.json(result);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});
 
app.listen(3000);

Browser Usage

KodiScript works in the browser with any bundler:

<script type="module">
  import { KodiScript } from '@issadicko/kodi-script';
  
  const result = KodiScript.run(`
    let x = 10
    let y = 20
    print(x + y)
  `);
  
  console.log(result.output); // ['30']
</script>

TypeScript Support

Full TypeScript definitions are included:

import { KodiScript, ScriptResult, KodiScriptBuilder } from '@issadicko/kodi-script';
 
const builder: KodiScriptBuilder = KodiScript.builder('1 + 2');
const result: ScriptResult = builder.execute();

Links

Dart SDK PHP SDK