naidejs 1.2.0 → 1.4.0

package/README.md

@@ -1,10 +1,13 @@
 # NAIDE
 
-**Node AI Development Environment** — A language designed for AI-speed code generation that transpiles to Node.js.
+**Node AI Development Environment** — A programming language designed for AI-speed code generation that transpiles to Node.js.
 
-Two modes:
-- **NAIDE** (`.naide`) — ~40% fewer tokens than JavaScript
-- **NAIDE-X** (`.nx`) — ~80% fewer tokens than JavaScript, AI-only readability
+NAIDE is built on three principles: one way to write everything (zero ambiguity), keyword-driven intent (the first token decides meaning), and minimal token count (fewer tokens = faster AI generation). It includes built-in declarations for servers, databases, authentication, file uploads, WebSockets, job queues, testing, and more — all with zero external dependencies.
+
+Two syntax modes:
+
+- **NAIDE** (`.naide`) — Human-readable, ~40% fewer tokens than JavaScript
+- **NAIDE-X** (`.nx`) — AI-only readability, ~80% fewer tokens than JavaScript
 
 ## Install
 
@@ -12,124 +15,310 @@ Two modes:
 npm install -g naidejs
 ```
 
-## Usage
+## Quick Start
+
+```bash
+# Create a new project
+naide init my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Or write a file directly:
+
+```python
+# app.naide
+server app port 3000:
+  get "/":
+    ret {message: "Hello from NAIDE"}
+```
 
 ```bash
-# Run a file
 naide app.naide
-naide app.nx
+```
 
-# Watch mode (auto-restart on changes)
-naide -w app.naide
+## CLI
 
-# Output generated JavaScript
-naide --emit app.nx
+```bash
+naide <file>                  # Run a .naide or .nx file
+naide init [dir]              # Scaffold a new project
+naide build [dir] [outdir]    # Transpile all files to JavaScript
+naide -w <file>               # Watch mode (auto-restart on changes)
+naide --emit <file>           # Print generated JavaScript
+naide -o <out.js> <file>      # Write JavaScript to file
+naide --mid <file.nx>         # Show intermediate NAIDE v1 (debug X mode)
+naide --ast <file>            # Print AST
+naide --tokens <file>         # Print token stream
+```
 
-# Write JS to file
-naide -o app.js app.nx
+## Language Reference
 
-# Show intermediate NAIDE v1 (X mode debug)
-naide --mid app.nx
+### Variables
+
+```python
+str name = "hello"          # immutable (const)
+int count = 42
+num price = 9.99
+bool active = true
+list items = [1, 2, 3]
+map config = {host: "localhost"}
+any data = null
+
+mut int counter = 0          # mutable (let)
+mut str label = "init"
+```
+
+Types: `str`, `int`, `num`, `bool`, `list`, `map`, `any`, `json`, `void`
+
+### String Interpolation
+
+```python
+str greeting = "Hello {name}, you have {count} items"
 ```
 
-## High-Level Features
+Double-quoted strings with `{expr}` are auto-interpolated.
 
-NAIDE includes built-in declarations for common backend patterns. Zero dependencies — the runtime is bundled with the package.
+### Functions
+
+```python
+fn add(int a, int b) -> int:
+  ret a + b
+
+fn greet(str name, str prefix = "Hello"):
+  log "{prefix}, {name}!"
+
+fn sum(...int nums) -> int:
+  mut int total = 0
+  each n in nums:
+    total += n
+  ret total
+
+fn.async fetchUser(str id) -> map:
+  any res = await fetch("/api/users/{id}")
+  ret await res.json()
+```
 
-### schema — Data models with validation
+### Control Flow
+
+```python
+if count > 10:
+  log "many"
+elif count > 5:
+  log "some"
+else:
+  log "few"
+
+str size = if count > 10 then "big" else "small"
+```
+
+### Loops
+
+```python
+each item in items:
+  log item
+
+each key, val in config:
+  log "{key}: {val}"
+
+for i in 0..10:
+  log i
+
+while active:
+  log "running"
+  active = false
+```
+
+### Pattern Matching
+
+```python
+match status:
+  "ok": log "success"
+  "error": log "failed"
+  _: log "unknown"
+```
+
+### Error Handling
+
+```python
+try:
+  data = await fetchData(url)
+fail e:
+  log.error e.message
+```
+
+### Classes
+
+```python
+model User:
+  str name
+  str email
+  int age = 0
+
+  fn greet() -> str:
+    ret "Hi, I'm {self.name}"
+
+model Admin extends User:
+  str role = "admin"
+  fn permissions() -> list:
+    ret ["read", "write", "delete"]
+```
+
+### Pipe Operator
+
+```python
+list result = data
+  |> filter((x) => x.active)
+  |> map((x) => x.name)
+  |> sort()
+```
+
+### Imports / Exports
+
+```python
+use express
+use {readFile, writeFile} from "fs/promises"
+use axios from "axios"
+
+pub fn helper() -> str:
+  ret "exported"
+pub str VERSION = "1.0.0"
+```
+
+## Server & API Features
+
+All features below are zero-dependency — the runtime is bundled with the package.
+
+### server — Express App
+
+```python
+server app port 3000:
+  get "/":
+    ret {message: "hello"}
+  post "/api/data" (req, res):
+    ret req.body
+  put "/api/data/:id" (req, res):
+    ret {updated: true}
+  del "/api/data/:id":
+    ret {deleted: true}
+  patch "/api/data/:id" (req, res):
+    ret {patched: true}
+```
+
+### schema — Data Models
 
 ```python
 schema User:
-  id     auto
-  name   str required min(2) max(50)
-  email  str required email unique
-  age    int optional min(0) max(150)
-  role   enum("admin", "user") default("user")
-  joined timestamp auto
+  id       auto
+  name     str required min(2) max(50)
+  email    str required email unique
+  age      int optional min(0) max(150)
+  role     enum("admin", "user") default("user")
+  joined   timestamp auto
 ```
 
 Types: `str`, `int`, `num`, `bool`, `auto` (UUID), `timestamp`, `enum(...)`
 Modifiers: `required`, `optional`, `min(n)`, `max(n)`, `email`, `url`, `unique`, `auto`, `default(val)`
 
-### db — Persistent file storage
+### db — Persistent Storage
 
 ```python
 db "data/"
 ```
 
-When declared, all schema stores persist to JSON files automatically (`data/User.json`, `data/Todo.json`, etc.). Without `db`, data is in-memory only.
+Schemas auto-persist to JSON files (`data/User.json`, etc.). Without `db`, data is in-memory only.
 
-### crud — Auto-generate REST endpoints
+### crud — Auto-generated REST Endpoints
 
 ```python
 server app port 3000:
   crud "/api/users" User
 ```
 
-Generates GET (list + by ID), POST, PUT, DELETE routes with validation.
+Generates GET (list + by-ID), POST, PUT, DELETE with validation. Built-in pagination, search, and sort:
 
-**Built-in pagination, search, and sort:**
 ```
-GET /api/users                     # paginated (default 20 per page)
-GET /api/users?page=2&limit=10     # page 2, 10 items
-GET /api/users?q=john              # search all string fields
-GET /api/users?sort=name&order=asc # sort by field
+GET /api/users?page=2&limit=10&q=john&sort=name&order=asc
+```
+
+Response: `{ data: [...], total, page, limit, pages }`
+
+### validate — Request Validation
+
+```python
+server app port 3000:
+  validate "/api/users" User
+  post "/api/users" (req, res):
+    user = UserStore.create(req.body)   # body is pre-validated
+    ret user
 ```
 
-Response format: `{ data: [...], total, page, limit, pages }`
+Auto-validates POST/PUT/PATCH bodies against the schema. Returns `400` with error details if invalid. Validated data replaces `req.body`.
 
-### auth — JWT authentication
+### auth — JWT Authentication
 
 ```python
 server app port 3000:
   auth JWT_SECRET:
     protect "/api/*"
     public "/api/auth/*"
+
+  post "/api/auth/login" (req, res):
+    token = auth.sign({id: user.id})
+    ret {token}
 ```
 
-Built-in JWT sign/verify with no external dependencies.
+### cors / limit / cookie / session
 
-**Signing tokens in routes:**
 ```python
-post "/api/auth/login" (req, res):
-  token = auth.sign({id: user.id})    # uses auth secret automatically
-  ret {token}
+server app port 3000:
+  cors "*"                    # CORS middleware
+  limit "/api/*" 100 "1m"    # rate limiting (100 req/min)
+  cookie                     # cookie parser → req.cookies
+  session "my-secret"        # cookie sessions → req.session
 ```
 
-Also available as `sign(payload)` (same auto-secret) or `sign(payload, secret)` (explicit).
-
-### Password hashing
+### upload — File Uploads
 
 ```python
-str hashed = hash("mypassword")       # scrypt-based, returns salt:hash
-bool ok = verify("mypassword", hashed) # timing-safe comparison
+server app port 3000:
+  upload "/api/upload" "avatar" (req, res):
+    ret {filename: req.file.filename, size: req.file.size}
 ```
 
-Zero-dependency — uses Node.js built-in `crypto.scryptSync`.
+Zero-dependency multipart parser. `req.file` = `{filename, contentType, data, size}`.
 
-### cors — CORS middleware
+### view — Template Rendering
 
 ```python
 server app port 3000:
-  cors "*"
-  # or: cors ["localhost:3000", "myapp.com"]
+  view "./views"
+  get "/":
+    ret.render "home" {title: "Welcome", items: ["a", "b"]}
 ```
 
-### limit — Rate limiting
+Reads `.html` files with `{{variable}}`, `{{if key}}...{{/if}}`, `{{each item in list}}...{{/each}}`.
+
+### sse — Server-Sent Events
 
 ```python
 server app port 3000:
-  limit "/api/*" 100 "1m"
+  sse "/events"
+  post "/api/notify" (req, res):
+    sse.broadcast req.body
+    ret {ok: true}
 ```
 
-### static — Serve static files
+`sse.send(data)`, `sse.broadcast(data)`, `sse.count`.
+
+### cache — Response Caching
 
 ```python
 server app port 3000:
-  static "/public"
+  cache "/api/*" "5m"
 ```
 
-Serves files from the `public/` directory.
+Caches GET responses in memory with TTL. Sets `X-Cache: HIT/MISS`.
 
 ### ws — WebSocket
 
@@ -144,9 +333,9 @@ server app port 3000:
       log "client left"
 ```
 
-Built-in `send(data)` and `broadcast(data)` helpers. Requires `npm install ws`.
+Built-in `send(data)` and `broadcast(data)`. Requires `npm install ws`.
 
-### group — Route groups
+### group — Route Groups
 
 ```python
 server app port 3000:
@@ -157,101 +346,140 @@ server app port 3000:
       ret req.body
 ```
 
-Generates an Express Router mounted at the prefix. Groups can be nested.
-
-### cookie — Cookie parsing
+### mid — Named Middleware
 
 ```python
+fn logger(req, res, next):
+  log req.method, req.url
+  next()
+
 server app port 3000:
-  cookie
-  get "/" (req, res):
-    str theme = req.cookies.theme
-    ret {theme}
+  mid logger               # apply globally
+  mid logger "/api"        # apply to path only
 ```
 
-Parses `Cookie` headers into `req.cookies`. Zero-dependency.
+### static — Serve Files
 
-### error — Error handler
+```python
+server app port 3000:
+  static "/public"
+```
+
+### error — Error Handler
 
 ```python
 server app port 3000:
-  get "/":
-    ret {ok: true}
   error (err, req, res):
     log.error err.message
     ret.status 500 {error: "Internal error"}
 ```
 
-Express error middleware. Catches unhandled errors in routes.
-
-### api — HTTP client
+### openapi — Auto-Generated API Docs
 
 ```python
-fn.async getUsers() -> any:
-  any users = await api.get("https://api.example.com/users")
-  ret users
+server app port 3000:
+  openapi "/docs"
+```
 
-fn.async createUser(map data) -> any:
-  any result = await api.post("https://api.example.com/users", data)
-  ret result
+Generates an OpenAPI 3.1 JSON spec from your schemas, served at the specified path.
+
+### Response Helpers
+
+```python
+ret {data: items}                 # JSON (default)
+ret.status 404 {error: "nope"}   # status code
+ret.redirect "/login"             # redirect
+ret.html "<h1>Hello</h1>"        # HTML
+ret.text "pong"                   # plain text
+ret.file "/path/to/file"         # send file
+ret.render "template" {data}     # render template (requires view)
 ```
 
-Methods: `api.get(url)`, `api.post(url, body)`, `api.put(url, body)`, `api.del(url)`, `api.raw(url, opts)`.
-Zero-dependency — uses Node.js 18+ built-in `fetch`. Auto-imported when used.
+## Testing
 
-### env — Environment variables with validation
+Built-in test syntax using Node.js test runner:
 
 ```python
-env:
-  PORT       int default(3000)
-  JWT_SECRET str required
-  DB_URL     str default("sqlite:data.db")
+test "user creation":
+  user = UserStore.create({name: "Alice", email: "alice@test.com"})
+  assert user.name == "Alice"
+  assert user.email == "alice@test.com"
+
+test "math":
+  assert 1 + 1 == 2
+  assert 10 > 5
 ```
 
-Variables become constants available throughout the file.
+`assert a == b` generates `assert.strictEqual` for better error messages. Run with `node --test`.
 
-### every — Scheduled tasks
+## Job Queue
+
+In-memory async job queue for background processing:
+
+```python
+queue jobs:
+  job "sendEmail" (data):
+    log "sending to {data.to}"
+  job "resize" (data):
+    log "resizing {data.path}"
+
+server app port 3000:
+  post "/api/notify" (req, res):
+    jobs.add("sendEmail", {to: req.body.email})
+    ret {queued: true}
+```
+
+## Scheduled Tasks & Events
 
 ```python
 every "5m":
   log "cleanup running"
+
+watch User.create (event):
+  log "new user: {event.data.name}"
 ```
 
-Intervals: `"30s"`, `"5m"`, `"1h"`, `"1d"`
+Intervals: `"30s"`, `"5m"`, `"1h"`, `"1d"`.
+`watch` connects to `crud` events automatically.
 
-### watch — React to events
+## Environment Variables
 
 ```python
-watch User.create (event):
-  log "new user: {event.data.name}"
+env:
+  PORT       int default(3000)
+  JWT_SECRET str required
+  DB_URL     str default("data/")
 ```
 
-Automatically connected to `crud` events.
+Variables become constants. Missing `required` vars exit with an error.
 
-### Response helpers
+## Built-in Functions
 
 ```python
-ret {data: items}              # JSON response (default)
-ret.status 404 {error: "nope"} # custom status code
-ret.redirect "/login"           # HTTP redirect
-ret.html "<h1>Hello</h1>"      # HTML response
-ret.text "pong"                 # plain text response
-ret.file "/path/to/file"       # send file
+str id = uuid()                          # UUID
+str hashed = hash("password")            # scrypt hash
+bool ok = verify("password", hashed)     # timing-safe verify
+str token = sign({id: 1})                # JWT (uses auth secret)
+str token = sign({id: 1}, "my-secret")   # JWT (explicit secret)
 ```
 
-### Built-in functions
+Auto-imported from the runtime when used.
+
+## HTTP Client
 
 ```python
-str id = uuid()                         # generate UUID
-str hashed = hash("password")           # hash password
-bool ok = verify("password", hashed)    # verify password
-str token = sign({id: 1})               # sign JWT (uses auth secret)
-str token = sign({id: 1}, "my-secret")  # sign JWT (explicit secret)
+fn.async getUsers() -> any:
+  any users = await api.get("https://api.example.com/users")
+  ret users
+
+fn.async createUser(map data) -> any:
+  any result = await api.post("https://api.example.com/users", data)
+  ret result
 ```
 
-These are auto-imported from the runtime when used.
+Methods: `api.get(url)`, `api.post(url, body)`, `api.put(url, body)`, `api.del(url)`, `api.raw(url, opts)`.
 
-### Full example
+## Full Example
 
 ```python
 db "data/"
@@ -266,24 +494,29 @@ schema User:
   email str required email
   password str required
 
+queue jobs:
+  job "welcome" (data):
+    log "Welcome email to {data.email}"
+
 server app port PORT:
   cors "*"
   cookie
+  session JWT_SECRET
   auth JWT_SECRET:
     protect "/api/*"
     public "/api/auth/*"
   limit "/api/*" 100 "1m"
   static "/public"
+  cache "/api/users" "1m"
+  validate "/api/users" User
   crud "/api/users" User
-
-  group "/api/v1":
-    get "/status":
-      ret {version: "1.0"}
+  openapi "/docs"
 
   post "/api/auth/register" (req, res):
     str hashed = hash(req.body.password)
     user = UserStore.create({...req.body, password: hashed})
     token = auth.sign({id: user.id})
+    jobs.add("welcome", {email: user.email})
     ret {token, user}
 
   post "/api/auth/login" (req, res):
@@ -299,6 +532,8 @@ server app port PORT:
     on "message" (data):
       broadcast(data)
 
+  sse "/events"
+
   get "/":
     ret.html "<h1>Welcome</h1>"
 
@@ -308,130 +543,47 @@ server app port PORT:
 
 watch User.create (event):
   log "new user: {event.data.name}"
-```
-
-This generates a complete production API with persistent storage, auth, password hashing, CORS, cookies, rate limiting, CRUD with pagination/search, WebSocket, route groups, error handling, and static files — from ~45 lines.
-
-## NAIDE syntax (.naide)
-
-```python
-# Variables with types
-str name = "World"
-int count = 3
-mut int counter = 0
-
-# Functions
-fn greet(str who) -> str:
-  ret "Hello, {who}!"
-
-# Async
-fn.async fetchData(str url) -> any:
-  ret await fetch(url)
-
-# Control flow
-if count > 5:
-  log "many"
-elif count > 2:
-  log "some"
-else:
-  log "few"
-
-# Loops
-each item in items:
-  log item
-
-for i in 0..10:
-  log i
-
-# Server (Express built-in)
-server app port 3000:
-  get "/users":
-    ret users
-  post "/users" (req, res):
-    ret req.body
 
-# Error handling
-try:
-  data = await fetchData(url)
-fail e:
-  log.error e.message
-
-# Classes
-model User:
-  str name
-  int age = 0
-  fn greet() -> str:
-    ret "Hi {self.name}"
-
-# Pipe operator
-list result = data
-  |> filter((x) => x.active)
-  |> map((x) => x.name)
+every "30m":
+  log "cleanup"
 ```
 
-## NAIDE-X syntax (.nx)
+This generates a complete production API — auth, password hashing, CORS, sessions, rate limiting, CRUD with pagination/search, WebSocket, SSE, file caching, request validation, background jobs, auto-generated API docs, and event-driven hooks — from ~55 lines.
+
+## NAIDE-X Syntax (.nx)
 
 Every keyword is a single character. Line-start symbol = intent.
 
 ```
--- Variables
-s:name="World"
-i:count=3
-~i:counter=0
-
--- Function
-f greet(s:who)s
-  >"Hello, {who}!"
-
--- Async
-~f fetchData(s:url)a
-  >~fetch(url)
-
--- Control flow
-?count>5
-  log"many"
-|count>2
-  log"some"
-:
-  log"few"
-
--- Loops
-@item<items
-  log item
-@i<0..10
-  log i
+s:name="World"              -- str name = "World"
+i:count=42                  -- int count = 42
+~i:counter=0                -- mut int counter = 0
+
+f greet(s:who)s             -- fn greet(str who) -> str:
+  >"Hello, {who}!"          --   ret "Hello, {who}!"
+
+~f fetchData(s:url)a        -- fn.async fetchData(str url) -> any:
+  >~fetch(url)              --   ret await fetch(url)
+
+?count>5                    -- if count > 5:
+  log"many"                 --   log "many"
+|count>2                    -- elif count > 2:
+  log"some"                 --   log "some"
+:                           -- else:
+  log"few"                  --   log "few"
+
+@item<items                 -- each item in items:
+@i<0..10                    -- for i in 0..10:
+*active                     -- while active:
+
+$app:3000                   -- server app port 3000:
+  G"/users"                 --   get "/users":
+    >users                  --     ret users
+  P"/users"(req,res)        --   post "/users" (req, res):
+    >req.body               --     ret req.body
+```
 
--- Server with high-level features
-$app:3000
-  cors "*"
-  auth SECRET:
-    protect "/api/*"
-  static "/public"
-  crud "/api/users" User
-  G"/users"
-    >users
-  P"/users"(req,res)
-    >req.body
-  G"/old"
-    >.r "/new"
-  G"/"
-    >.h "<h1>Hello</h1>"
-
--- Error handling
-!
-  data=~fetchData(url)
-!!e
-  log.e e.message
-
--- Model
-^User
-  s:name
-  i:age=0
-  f greet()s
-    >"Hi {self.name}"
-```
-
-### NAIDE-X cheat sheet
+### NAIDE-X Cheat Sheet
 
 | Symbol | Meaning | Symbol | Meaning |
 |--------|---------|--------|---------|
@@ -445,14 +597,15 @@ $app:3000
 | `+` | export | `~` | await |
 | `G` | GET | `P` | POST |
 | `U` | PUT | `D` | DELETE |
-| `>.s` | ret.status | `>.r` | ret.redirect |
-| `>.h` | ret.html | `>.t` | ret.text |
+| `X` | PATCH | `>.s` | ret.status |
+| `>.r` | ret.redirect | `>.h` | ret.html |
+| `>.t` | ret.text | `>.v` | ret.render |
 
 Types: `s`=str `i`=int `n`=num `b`=bool `l`=list `m`=map `a`=any
 
-High-level: `schema`, `crud`, `auth`, `cors`, `limit`, `env`, `every`, `watch`, `static`, `ws`, `db`, `group`, `cookie`, `error` — same syntax in both modes. `api` is auto-imported.
+High-level keywords work in both modes: `schema`, `crud`, `auth`, `cors`, `limit`, `env`, `every`, `watch`, `static`, `ws`, `db`, `group`, `cookie`, `error`, `session`, `upload`, `view`, `sse`, `cache`, `patch`, `validate`, `test`, `assert`, `queue`, `openapi`.
 
-## Why?
+## Why NAIDE?
 
 AI code generation speed depends on: