Sn Tin

Learn Tin · Part 3: Real programs · Chapter 25

Calling JavaScript

import js and extern fn, checked at the boundary.

Tin's standard library is small. When you need something it doesn't have, such as a date library, a file format or a Node built-in, you call JavaScript. You don't write bindings: you declare the function with Tin types, and Tin checks what comes back.

A first extern

The examples in this chapter import this module, shapes.mjs, which sits next to them:

// The JavaScript side of the chapter's examples.
export function hypot(a, b) {
  return Math.hypot(a, b)
}

export function corners(sides, radius) {
  const points = []
  for (let i = 0; i < sides; i++) {
    const t = (2 * Math.PI * i) / sides
    points.push({ x: Math.round(radius * Math.cos(t) * 100) / 100, y: Math.round(radius * Math.sin(t) * 100) / 100 })
  }
  return points
}

export async function slowUpper(s) {
  await new Promise((r) => setTimeout(r, 5))
  return s.toUpperCase()
}

export function root(n) {
  if (n < 0) throw new Error(`no real square root of ${n}`)
  return Math.sqrt(n)
}

export function sides(name) {
  return { triangle: 3, square: 4 }[name] ?? 'many'
}

import js "./shapes.mjs" names the module. Each extern fn is a function it exports, with the types you expect:

hello-js.tintin run hello-js.tin
import js "./shapes.mjs"

extern fn hypot(a: float, b: float): float

fn main() {
  print(hypot(3.0, 4.0))
}
5.0

Data crosses, checked

Arguments and results cross as plain data: numbers, strings, arrays and objects. An object becomes a Tin struct if it has the right fields. An async function needs nothing special: Tin waits for it.

data.tintin run data.tin
import js "./shapes.mjs"

type Point = { x: float, y: float }

extern fn corners(sides: int, radius: float): Point[]   // JS returns objects; Tin checks the shape
extern fn slowUpper(s: string): string                  // an async JS function: just call it

fn main() {
  let square = corners(4, 1.0)
  print("{square.len} corners, first at ({square[0].x}, {square[0].y})")
  print(slowUpper("tin"))
}
4 corners, first at (1.0, 0.0)
TIN

JavaScript has no types to promise anything, so Tin checks each result on the way in. A wrong one stops the program at the boundary, instead of turning into a bug somewhere else:

wrong-type.tintin run wrong-type.tin
import js "./shapes.mjs"

extern fn sides(name: string): int

fn main() {
  print(sides("square"))
  print(sides("hexagon"))     // the JS returns the string "many"
}
4
panic: sides: expected an integer, got "many"

Node built-ins and packages

The spec can also be a Node built-in such as "node:path", or a package installed next to your program. A block says which module answers which externs. You need one when two modules export the same name.

node.tintin run node.tin
import js "node:path" {
  extern fn basename(path: string): string
  extern fn extname(path: string): string
}

fn main() {
  print(basename("/robots/arm/pose.tin"))
  print(extname("/robots/arm/pose.tin"))
}
pose.tin
.tin

Externs are checked before the program starts. A function no module exports means the program never runs:

missing.tintin run missing.tin
import js "./shapes.mjs"

extern fn area(radius: float): float

fn main() {
  print(area(1.0))
}
tin: no imported module exports a function 'area' (imports: ./shapes.mjs)

When JavaScript throws

Usually a JS exception stops the program. Declare the extern as returning Result<T, string> and a throw becomes Err(message) instead, which you handle like any other error (chapter 7):

throws.tintin run throws.tin
import js "./shapes.mjs"

extern fn root(n: float): Result<float, string>   // a JS throw becomes Err(message)

fn main() {
  print(root(16.0))
  print(root(-4.0))
}
Ok(4.0)
Err("no real square root of -4")

JavaScript and agents

JavaScript can do anything on the machine, so the compiler treats an extern as the capability js. A tool that a model may call freely is not allowed to reach one:

tool.tintin check tool.tin
import js "./shapes.mjs"

extern fn hypot(a: float, b: float): float

/// The length of a vector.
tool fn length(x: float, y: float): float => hypot(x, y)

agent Geometer { model: "mock", tools: [length] }

fn main() {
  print(Geometer("length 3 4"))
}
error: tool 'length' can call JavaScript (an extern fn), which can do anything on this machine, without anyone approving it
 --> tool.tin:6:1
  |
6 | tool fn length(x: float, y: float): float => hypot(x, y)
  | ^^^^^^^^^^^^^^
  = note: path: length → hypot
  = note: mark it `guarded tool fn length` so a person approves each call
  = fix: mark length as guarded

The fix is the one from chapter 18: make it guarded, so a person approves each call.

The examples in this chapter use files and Node, so they run with tin run, not in the playground. How a web page hosts Tin is in chapter 28.

Tasks

●○○ Task 1: Ask the operating system

Using node:os, declare platform() and cpus(). cpus() returns an array of objects with a model field. Print whether the machine has any CPUs.

Solution
task-1.solution.tintin run task-1.solution.tin
import js "node:os" {
  extern fn platform(): string
  extern fn cpus(): Cpu[]
}

type Cpu = { model: string }

fn main() {
  let n = cpus().len
  print(if n > 0 { "this machine has CPUs" } else { "no CPUs?" })
  print(platform().len > 0)
}
this machine has CPUs
true

The struct only needs the fields you use: Tin checks model and ignores the rest of each object.

●●○ Task 2: Let a model measure

Make the Geometer from JavaScript and agents compile, and run it with --yes.

Solution
task-2.solution.tintin run task-2.solution.tin --yes
import js "./shapes.mjs"

extern fn hypot(a: float, b: float): float

/// The length of a vector. Runs JavaScript, so a person approves each call.
guarded tool fn length(x: float, y: float): float => hypot(x, y)

agent Geometer { model: "mock", tools: [length] }

fn main() {
  print(Geometer("length 3 4"))
}
mock: 5

What's next

Next: A fleet of agents. A larger program, read piece by piece.

In the reference: Files, modules and import js · Capabilities