pa.js Macroframework – Docs & Tutorial

🔰 Overview

pa.js is a single-file Node.js macroframework for building modern, scalable, secure, and real-time applications-no external packages required. Created by John Mwirigi Mahugu ("Kesh"), it bundles routing, middleware, ORM, templating, database, search, CLI tools, WebSockets, and more-all in one file.

📦 Features

Middleware & Routing (grouping, event-driven)
Advanced ORM (relations, migrations, transactions)
Template engine (inheritance, interpolation)
Embedded NoSQL DB (PajsDB)
Full-text search engine (PaJua)
CSRF, CORS, secure cookies, rate limiting
Session, flash, caching
CLI and test runner
WebSocket and long polling
File uploads/downloads, static files
HTML helper and AJAX (PaJSX)
Python/JS integration

⚡ Quickstart

// app.js
const Pa = require('./pa.js');
const app = new Pa();
app.route('GET', '/', (req, res) => res.send('Hello, pa.js!'));
app.listen(3000, () => console.log('Running on http://localhost:3000'));

🛠️ Tutorial: Build a Customer Management App

Step 1: Project Setup
Download pa.js and create cma.js:

curl -O https://raw.githubusercontent.com/johnmwirigimahugu/pa/main/pa.js
touch cma.js

Step 2: Basic Routing and Templating

// cma.js
const Pa = require('./pa.js');
const app = new Pa();
app.static('/static', './public');
app.route('GET', '/', async (req, res) => {
  const customers = await Pa.R.find('customers');
  res.render('index', { customers });
});
app.listen(3000, () => console.log('http://localhost:3000'));

Create views/index.html:

<!DOCTYPE html>
<html>
<head><title>Customer Management App</title></head>
<body>
  <h1>Customer List</h1>
  <ul>
    {% for customer in customers %}
      <li>{{ customer.name }} - {{ customer.email }}</li>
    {% else %}
      <li>No customers yet!</li>
    {% endfor %}
  </ul>
  <a href="/customers/add">Add New Customer</a>
</body>
</html>

Step 3: ORM and Database Migrations

(async () => {
  await Pa.R.migrate('customers', {
    id: 'string',
    name: 'string',
    email: 'string',
    phone: 'string',
    createdAt: 'datetime'
  });
})();

Step 4: Adding New Customers

// Add route for form (GET)
app.route('GET', '/customers/add', (req, res) => {
  res.render('add-customer');
});
// Handle form submission (POST)
app.route('POST', '/customers/add', async (req, res) => {
  const { name, email, phone } = req.body;
  const customer = await Pa.R.dispense('customers');
  customer.name = name;
  customer.email = email;
  customer.phone = phone;
  customer.createdAt = new Date();
  await Pa.R.store(customer);
  res.redirect('/');
});

Create views/add-customer.html:

<form method="post" action="/customers/add">
  <input name="name" placeholder="Name" required><br>
  <input name="email" placeholder="Email" required><br>
  <input name="phone" placeholder="Phone"><br>
  <button type="submit">Add Customer</button>
</form>

Step 5: Search & Real-Time Updates

// Search route
app.route('GET', '/search', async (req, res) => {
  const q = req.query.q || '';
  const results = app.pajua.search(q);
  res.render('search', { results });
});

// WebSocket for real-time updates
const http = require('http');
const server = http.createServer(app.handler());
app.enableWebSocket(server);
server.listen(3000, () => console.log('WebSocket running on port 3000'));

🎉 Done! You now have a working Customer Management App with pa.js, including ORM, templates, search, and real-time updates.

📁 Suggested Project Structure

project-root/
├── pa.js                  # The framework file
├── cma.js                 # Your entry point
├── views/                 # Template files
├── static/                # Static assets
└── python-as-js/          # Python integration bridge (optional)

💾 Installation

curl -O https://raw.githubusercontent.com/johnmwirigimahugu/pa/main/pa.js
node app.js

pa.js Macroframework v3.1.6