polar

Hosts

A host is a place your code runs, like Node or Browser. Polar uses each function's effects to work out which hosts it can run on, and builds a separate bundle for each.

Declaring hosts

A module lists the hosts it targets in the hosts zone. Every effect then says which host it lives on:

hosts
  Node

effects
  Clock in Node {
    now() -> Int
  }

The standard library declares the two common hosts with their effects. Std.Dom provides Browser and its Dom effect, and Std.Process provides Node and its Process effect.

Where code can run

You never mark a function with a host yourself. Polar works it out from its effects:

  • A pure function runs on every host.
  • A function that uses Clock runs only where Clock exists: Node.
  • A function that uses two effects runs only where both exist.

You can ask Polar what it decided with --emit=hosts. Here's the program from Effects:

$ polar build clock.px --emit=hosts
double : every host
main   : {Node}
stamp  : {Node}

Code that can't run anywhere

This function adds text to the page using Dom, which only exists in the browser. It also reads a count using Visits, which lives in Node:

start() -> {} / {Dom, Visits} {
  Dom.append_text("p", "#{Visits.count()} visits so far")
}

No host has both, and Polar says so before you ship it:

error[POLAR0811]: `start` can't run anywhere
  --> hosts_bad.px:23:3
   |
23 |   start() -> {} / {Dom, Visits} {
   |   ^^^^^ no host provides both `Visits` and `Dom`
24 |     Dom.append_text("p", "#{Visits.count()} visits so far")
   |     --------------- `Dom` runs on {Browser}
   |                             ------------ `Visits` runs on {Node}
   |
   = help: split the work: call a function that uses `Visits` from one host and one that uses `Dom` from the other

One way to fix this is a bridge, which makes Visits callable from the browser over HTTP. That has its own page: Bridges.

Building for several hosts

List the hosts in your project's polar.toml:

[project]
name = "visits"
hosts = ["Browser", "Node"]

polar build then writes one complete bundle per host. Each one contains only that host's binds, so browser code never ships your server's database code:

$ polar build
built visits (1 file) for Browser into dist/Browser in 118ms
built visits (1 file) for Node into dist/Node in 191ms

To build or run just one, pass --host:

$ polar build --host Node
$ polar run --host Node

The Native host

Native is the host of a program built with polar build --target native, which runs in polar-rt instead of Node. It has the standard library's Time, Url, Regex, Crypto, Fs and Process. Anything that is only bound for Node or Browser, including Http and Dom, can't run there, and the build says which function needs it.

A native program can also serve its effects to a browser bundle. Start the executable with --serve <PORT> and it answers the same requests as the Node bridge server, so the browser build doesn't change.

Native effects and force

Some effects truly belong to one host. Mark those native:

effects
  native Canvas in Browser {
    draw(shape: String) -> {}
  }

You can still bind a native effect on another host, for example to draw into an SVG buffer on the server. But that's an emulation, not the real thing, so Polar asks you to say so with force:

binds
  force Canvas in Node {
    draw(shape) {
      Log.info("svg buffer: #{shape}")
    }
  }

Without force, Polar reports that Canvas is native to Browser. With force where it isn't needed, you get a warning to remove it.

You've now seen every main concept. Let's put them together in a real program: Thinking in Polar.