Modules

ESM Import

import express from ///express///
import [Hono] from ///hono///
import [describe, it, expect] from ///vitest///
import axios, [AxiosError] from ///axios///
import all as fs from ///fs///

import express from "express";
import { Hono } from "hono";
import { describe, it, expect } from "vitest";
import axios, { AxiosError } from "axios";
import * as fs from "fs";

from...import syntax

You can also write imports with the module path first:

from ///express/// import express
from ///hono/// import [Hono]
from ///vitest/// import [describe, it, expect]
from ///axios/// import axios, [AxiosError]
from ///fs/// import all as fs

This compiles to the same JavaScript as the import...from syntax above.

Side-effect Import

Import a module for its side effects only (no bindings):

import ///dotenv/config///
import ///./polyfills///

import "dotenv/config";
import "./polyfills";

Import Attributes

Use the with keyword to specify import attributes:

import package from ///./package.json/// with [ type be ///json/// ]
import [name; version] from ///./package.json/// with [ type be ///json/// ]

import package from "./package.json" with { type: "json" };
import { name, version } from "./package.json" with { type: "json" };

The from...import syntax also supports with:

from ///./data.json/// import data with [ type be ///json/// ]
from ///./package.json/// import [name, version] with [ type be ///json/// ]

import data from "./data.json" with { type: "json" };
import { name, version } from "./package.json" with { type: "json" };

Use (Standard Library)

The use keyword imports Purus built-in standard library modules. All module names are prefixed with p- to avoid keyword conflicts. The as keyword is optional — if omitted, the module name is used as the binding name (with - converted to _ in the JS output). Tree-shaking ensures only the functions you actually reference are included in the compiled output.

use p-random as r
use p-math as m
use p-string as s
use p-datetime as dt
use p-json as j
use p-object as o
use p-number as n
use p-array as a
use p-error as e

-- `as` can be omitted:
use p-math              -- same as: use p-math as p-math (binding: p_math)
use p-random            -- same as: use p-random as p-random (binding: p_random)

// Only used functions are emitted (tree-shaking)
const r = { randint(a, b) { ... }, choice(arr) { ... } };
const m = { floor: Math.floor, pi: Math.PI };
const s = { upper(str) { ... }, reverse(str) { ... } };

Available Modules

Module	Contents
p-random	random, randint, randrange, randbool, uniform, triangular, gauss, expovariate, gammavariate, betavariate, lognormvariate, vonmisesvariate, paretovariate, weibullvariate, choice, choices, wchoices, shuffle, sample, binomial, poisson, geometric, clamp, lerp
p-math	JS Math alias + lowercase constant aliases (pi, e, ln2, ln10, log2e, log10e, sqrt2, sqrt1_2)
p-string	len, contains, startswith, endswith, indexof, count, upper, lower, capitalize, title, trim, trimstart, trimend, reverse, repeat, replace, replacefirst, padstart, padend, split, lines, words, join, chars, slice, charat, codeat, fromcode
p-datetime	now, today, timestamp, create, utccreate, fromiso, year, month, day, weekday, hour, minute, second, ms, utcyear, utcmonth, utcday, utcweekday, utchour, utcminute, utcsecond, utcms, tzyear, tzmonth, tzday, tzweekday, tzhour, tzminute, tzsecond, toiso, tolocale, todate, totime, format, addms, addseconds, addminutes, addhours, adddays, diff, diffdays, diffhours, diffminutes, diffseconds, offset, localtz
p-json	parse, stringify, prettify
p-object	keys, values, entries, fromentries, assign, freeze, seal, isfrozen, issealed, hasown, create, is, len, merge, clone, pick, omit
p-number	isfinite, isinteger, isnan, issafe, parsefloat, parseint, tofixed, toprecision, toexponential, tostring, clamp + constants: maxsafe, minsafe, epsilon, maxvalue, minvalue, posinf, neginf
p-array	isarray, from, of, len, first, last, range, flatten, unique, zip, unzip, chunk, sum, product, min, max, sortasc, sortdesc, compact, count, groupby
p-error	create, type, range, reference, syntax, uri, iserror, message, name, stack, cause, wrap

Export

public fn greet name to console.log[name]
public const VERSION be ///1.0///
export default fn main
  console.log[///hi///]

export function greet(name) { console.log(name); }
export const VERSION = "1.0";
export default function main() {
  console.log("hi");
}

Module namespace

namespace utils
  fn helper
    return 42

const utils = (() => {
  function helper() {
    return 42;
  }
})();

Module Type Configuration

By default, .purus files are compiled as ES Modules (ESM). You can configure the module type to CommonJS using the --type CLI option, config.purus, or package.json.

Resolution Order

1. CLI --type option (highest priority)
2. config.purus type field
3. package.json type field
4. Default: module (ESM)

CLI Option

purus build --type commonjs
purus build --type module

config.purus

const type be ///module///

or

const type be ///commonjs///

Values are the same as package.json’s type field: module (ESM) or commonjs (CJS).

CommonJS Output

When module type is set to commonjs, imports and exports are compiled to CJS syntax:

import express from ///express///
import [Hono] from ///hono///
import all as fs from ///fs///
import ///dotenv/config///

const express = require("express");
const { Hono } = require("hono");
const fs = require("fs");
require("dotenv/config");

public const VERSION be ///1.0///
export default 42

const VERSION = "1.0";
exports.VERSION = VERSION;
module.exports = 42;

Note

.cpurus files always compile to CommonJS (.cjs), and .mpurus files always compile to ES Modules (.mjs), regardless of the module type configuration.

CommonJS

const fs be require[///fs///]

const fs = require("fs");