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:
tin run hello-js.tinimport 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.
tin run data.tinimport 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:
tin run wrong-type.tinimport 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.
tin run node.tinimport 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:
tin run missing.tinimport 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):
tin run throws.tinimport 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:
tin check tool.tinimport 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
tin run task-1.solution.tinimport 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
tin run task-2.solution.tin --yesimport 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