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 release build.

From Source:

Clone the repo and build it using Cargo.

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 examples directory.

Available APIs

Globals

global: Reference to the global object.
globalThis: Same as global.
console: A subset of the WHATWG console.
prompt: Shows the given message and waits for the user's input.
TextEncoder / TextDecoder: WHATWG encoding API.
setTimeout / setInterval / clearTimeout / clearInterval: DOM style timers.
setImmediate / clearImmediate: Node.js like immediate timers.
process: An object that provides info about the current dune process.
structuredClone: Creates a deep clone of a given value.

Module Metadata

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

Process

File System

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

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

File

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

Net

createServer(connectionListener?): Creates a new TCP server.
createConnection(options): Creates unix socket connection to a remote host.
TimeoutError: Custom error signalling a socket (read) timeout.

Net.Server

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

listen(port, host?): Begin accepting connections on the specified port and host.
accept(): Waits for a TCP client to connect and accepts the connection.
address(): Returns the bound address.
close(): Stops the server from accepting new connections and keeps existing connections.
Event: 'listening': Emitted when the server has been bound after calling server.listen.
Event: 'connection': Emitted when a new connection is made.
Event: 'close': Emitted when the server stops accepting new connections.
Event: 'error': Emitted when an error occurs.

Net.Socket

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

HTTP

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

METHODS: A list of the HTTP methods that are supported by the parser.
STATUS_CODES: A collection of all the standard HTTP response status codes.
request(url, options?): Performs an HTTP request.

Details

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.

Body Mixins

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

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

Stream

Streams are very different from Node.js and are based on async-generators.

pipe(source, ...targets): An alias of pipeline().
pipeline(source, ...targets): Pipes between streams while forwarding errors.
compose(...targets): Combines two or more streams into a Duplex stream.

Performance Measurement

timeOrigin: Specifies the millisecond timestamp at which the current process began.
now(): Returns the millisecond timestamp, where 0 represents the start of the current process.

Assert

The assertion API is copied from: https://assert-js.norbert.tech/

Contributing

Contributions are always welcome!

See CONTRIBUTING.md for ways to get started.

eugenever/dune