Dune

Dune is an open-source, cross-platform, shell around the V8 engine, written in Rust and capable of running JavaScript (dah) and TypeScript code out of the box.

Developed completely for fun and experimentation.

Installation

Mac, Linux:

curl -fsSL https://raw.githubusercontent.com/aalykiot/dune/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/aalykiot/dune/main/install.ps1 | iex

Otherwise you have to manually download and unzip the <a href="https://github.com/aalykiot/dune/releases/latest/download/dune-x86_64-pc-windows-msvc.zip">release</a> build.

From Source:

Clone the repo and build it using <a href="https://rustup.rs/">Cargo</a>.

git clone https://github.com/aalykiot/dune.git && cd ./dune && cargo build --release

Make sure to create a .dune directory under your user.

Getting Started

A simple example.

import shortid from 'https://cdn.skypack.dev/shortid';

console.log(shortid()); //=> "lXN1aGba2"

Another example using the net module.

import net from 'net';

const server = net.createServer(async (socket) => {
  console.log('Got new connection!');
  await socket.write('Hello! 👋\n');
  await socket.destroy();
});

await server.listen(3000, '127.0.0.1');

console.log('Server is listening on port 3000...');

JSX/TSX files are also supported for server side rendering.

import { h, Component } from 'https://esm.sh/preact@10.11.3';
import { render } from 'https://esm.sh/preact-render-to-string@5.2.6';

/** @jsx h */

// Classical components work.
class Fox extends Component {
  render({ name }) {
    return <span class="fox">{name}</span>;
  }
}

// ... and so do pure functional components:
const Box = ({ type, children }) => (
  <div class={`box box-${type}`}>{children}</div>
);

let html = render(
  <Box type="open">
    <Fox name="Finn" />
  </Box>
);

console.log(html);

For more examples look at the <a href="./examples">examples</a> directory.

Available APIs

Globals

• [x] global: Reference to the global object.
• [x] globalThis: Same as global.
• [x] console: A subset of the WHATWG console.
• [x] prompt: Shows the given message and waits for the user's input.
• [x] TextEncoder / TextDecoder: WHATWG encoding API.
• [x] setTimeout / setInterval / clearTimeout / clearInterval: DOM style timers.
• [x] setImmediate / clearImmediate: Node.js like immediate timers.
• [x] process: An object that provides info about the current dune process.
• [x] structuredClone: Creates a deep clone of a given value.
• [x] AbortController / AbortSignal: Allows you to communicate with a request and abort it.
• [x] fetch: A wrapper around http.request (not fully compatible with WHATWG fetch).
• [x] queueMicrotask: Queues a microtask to invoke a callback.

Module Metadata

• [x] import.meta.url: A string representation of the fully qualified module URL.
• [x] import.meta.main: A flag that indicates if the current module is the main module.
• [x] import.meta.resolve(specifier): A function that returns resolved specifier.

Process

• [x] argv: An array containing the command-line arguments passed when the dune process was launched.
• [x] cwd(): Current working directory.
• [x] env: An object containing the user environment.
• [x] exit(code?): Exits the program with the given code.
• [ ] getActiveResourcesInfo(): An array of strings containing the types of the active resources that are currently keeping the event loop alive. 🚧
• [x] memoryUsage(): An object describing the memory usage.
• [x] nextTick(cb, ...args?): Adds callback to the "next tick queue".
• [x] pid: PID of the process.
• [x] platform: A string identifying the operating system platform.
• [x] uptime(): A number describing the amount of time (in seconds) the process is running.
• [x] version: The dune version.
• [x] versions: An object listing the version strings of dune and its dependencies.
• [x] binding(module): Exposes modules with bindings to Rust.
• [x] kill(pid, signal?): Sends the signal to the process identified by pid.
• [x] stdout: Points to system's stdout stream.
• [x] stdin: Points to system's stdin stream.
• [x] stderr: Points to system's stderr stream.

Events

• [x] uncaughtException: Emitted when an uncaught exception bubbles up to Dune.
• [x] unhandledRejection: Emitted when a Promise is rejected with no handler.

Signal events will be emitted when the Dune process receives a signal. Please refer to signal(7) for a listing of standard POSIX signal names.

File System

This module also includes a Sync method for every async operation available.

• [x] copyFile(src, dest): Copies src to dest.
• [x] createReadStream(path, options?): Returns a new readable IO stream.
• [x] createWriteStream(path, options?): Returns a new writable IO stream.
• [x] open(path, mode?): Asynchronous file open.
• [x] mkdir(path, options?): Creates a directory.
• [x] readFile(path, options?): Reads the entire contents of a file.
• [x] rmdir(path, options?): Deletes a directory (must be empty).
• [x] readdir(path): Reads the contents of a directory.
• [x] rm(path, options?): Removes files and directories.
• [x] rename(from, to): Renames the file from oldPath to newPath.
• [x] stat(path): Retrieves statistics for the file.
• [x] watch(path, options?): Returns an async iterator that watches for changes over a path.
• [x] writeFile(path, data, options?): Writes data to the file, replacing the file if it already exists.

Data (to be written) must be of type String|Uint8Array.

File

• [x] fd: The numeric file descriptor.
• [x] close(): Closes the file.
• [x] read(buffer, offset?): Reads data from the file.
• [x] stat(): Retrieves statistics for the file.
• [x] write(data, offset?): Writes data to the file.

Net

• [x] createServer(connectionHandler?): Creates a new TCP server.
• [x] createConnection(options): Creates unix socket connection to a remote host.
• [x] connect(options): An alias of createConnection().
• [x] TimeoutError: Custom error signalling a socket (read) timeout.

net.Server

net.Server is a class extending EventEmitter and implements @@asyncIterator.

• [x] listen(port, host?): Begin accepting connections on the specified port and host.
• [x] accept(): Waits for a TCP client to connect and accepts the connection.
• [x] address(): Returns the bound address.
• [x] close(): Stops the server from accepting new connections and keeps existing connections.

Events

• [x] listening: Emitted when the server has been bound after calling server.listen.
• [x] connection: Emitted when a new connection is made.
• [x] close: Emitted when the server stops accepting new connections.
• [x] error: Emitted when an error occurs.

net.Socket

net.Socket is a class extending EventEmitter and implements @@asyncIterator.

• [x] connect(options): Opens the connection for a given socket.
• [x] setEncoding(encoding): Sets the encoding for the socket.
• [x] setTimeout(timeout): Sets the socket's timeout threshold when reading.
• [x] read(): Reads data out of the socket.
• [x] write(data): Sends data on the socket.
• [x] end(data?): Half-closes the socket. i.e., it sends a FIN packet.
• [x] destroy(): Closes and discards the TCP socket stream.
• [x] address(): Returns the bound address.
• [x] remoteAddress: The string representation of the remote IP address.
• [x] remotePort: The numeric representation of the remote port.
• [x] bytesRead: The amount of received bytes.
• [x] bytesWritten: The amount of bytes sent.

Events

• [x] connect: Emitted when a socket connection is successfully established.
• [x] data: Emitted when data is received.
• [x] end: Emitted when the other end of the socket sends a FIN packet.
• [x] error: Emitted when an error occurs.
• [x] close: Emitted once the socket is fully closed.
• [x] timeout: Emitted if the socket times out from (read) inactivity.

HTTP

The HTTP package is inspired by Node.js' undici package.

• [x] METHODS: A list of the HTTP methods that are supported by the parser.
• [x] STATUS_CODES: A collection of all the standard HTTP response status codes.
• [x] request(url, options?): Performs an HTTP request.
• [x] createServer(requestHandler?): Creates a new HTTP server.

<details><summary>Details</summary> <p></p>

const URL = 'http://localhost:3000/foo';

const { statusCode, headers, body } = await http.request(URL);

RequestOptions

• method: (string) - Default: GET
• headers: (object) - Default: null
• body: (string | Uint8Array | stream.Readable) - Default: null
• timeout: (number) - Default: 30000 (30 seconds) - Use 0 to disable it entirely.
• throwOnError: (boolean) - Default: false - Whether should throw an error upon receiving a 4xx or 5xx response.
• signal: (AbortSignal) - Default: null - Allows you to communicate with the request and abort it.

Body Mixins

The body mixins are the most common way to format the response body.

• [x] text(): Produces a UTF-8 string representation of the body.
• [x] json(): Formats the body using JSON parsing.

</details>

http.Server

http.Server is a class extending EventEmitter and implements @@asyncIterator.

• [x] listen(port, host?): Starts the HTTP server listening for connections.
• [x] close(): Stops the server from accepting new connections.
• [x] accept(): Waits for a client to connect and accepts the HTTP request.