Clean Node Server

A Node.js runtime for Clean Language applications. Run your compiled Clean Language WebAssembly modules with full access to HTTP servers, databases, file systems, and more.

What is this?

Clean Node Server lets you run Clean Language .wasm files on any machine with Node.js. It provides all the "bridge functions" your Clean code needs to interact with the outside world - things like:

• Starting a web server and handling HTTP requests
• Connecting to PostgreSQL or SQLite databases
• Reading and writing files
• Making HTTP requests to other services
• User authentication with sessions and JWT tokens
• And much more!

Quick Start

Installation

npm install -g @ivan-pasco/clean-node-server

Or use it directly with npx:

npx @ivan-pasco/clean-node-server your-app.wasm

Running Your First App

Once you've compiled your Clean Language code to WebAssembly:

clean-node-server my-app.wasm

That's it! Your app is now running on http://localhost:3000

Common Options

# Run on a different port
clean-node-server my-app.wasm --port 8080

# Connect to a database
clean-node-server my-app.wasm --database "postgresql://user:pass@localhost/mydb"

# See what's happening under the hood
clean-node-server my-app.wasm --verbose

Documentation

| Guide | Description | |-------|-------------| | Getting Started | First steps with Clean Node Server | | HTTP Server | Building web APIs and handling requests | | Database | Working with PostgreSQL and SQLite | | Authentication | Sessions, passwords, and JWT tokens | | File System | Reading and writing files | | HTTP Client | Making requests to external services | | All Functions | Complete reference of available functions |

Command Line Options

| Option | Short | Default | What it does | |--------|-------|---------|--------------| | --port | -p | 3000 | Which port to listen on | | --host | -h | 0.0.0.0 | Which network interface to use | | --database | -d | none | Database connection URL | | --verbose | -v | off | Print detailed logs | | --session-secret | | auto | Secret for encrypting sessions | | --jwt-secret | | auto | Secret for signing JWT tokens | | --sandbox | | wasm dir | Root folder for file operations |

Database Connection URLs

PostgreSQL:

postgresql://username:password@hostname:5432/database_name

SQLite (file):

sqlite:///path/to/database.db

SQLite (in memory):

sqlite::memory:

Example: A Simple API

Here's what a Clean Language API might look like:

// Define a route that returns JSON
function handleHealth(): string {
    return _http_json('{"status": "ok", "message": "Server is running!"}')
}

// Set up the server
function main(): void {
    _http_route("GET", "/health", handleHealth)
    _http_listen(3000)
    print("Server started on port 3000")
}

Compile it and run:

clean-node-server my-api.wasm --verbose

Then visit http://localhost:3000/health to see your API in action!

Project Structure

src/
├── index.ts          # CLI - where it all starts
├── server.ts         # The Express HTTP server
├── bridge/           # All the functions your Clean code can call
│   ├── console.ts    # print, printl, etc.
│   ├── http-server.ts# Routes and responses
│   ├── request.ts    # Reading request data
│   ├── database.ts   # SQL queries
│   ├── auth.ts       # Authentication helpers
│   ├── crypto.ts     # Encryption and hashing
│   ├── file.ts       # File operations
│   └── ...more
├── wasm/             # WebAssembly loading and management
├── router/           # Route matching logic
├── session/          # Session storage
└── database/         # Database drivers

Development

Want to contribute or run from source?

# Clone the repo
git clone https://github.com/Ivan-Pasco/clean-node-server.git
cd clean-node-server

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Try it out
npm run dev -- path/to/your-app.wasm --verbose

Requirements

• Node.js 18 or later
• Your compiled Clean Language .wasm files

License

MIT - Use it however you like!

Links

• npm package
• GitHub repository
• Report an issue