@rip-lang/api 0.5.0

package/README.md

@@ -0,0 +1,776 @@
+<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/rip.svg" style="width:50px" /> <br>
+
+# Rip API - @rip-lang/api
+
+> **Pure Rip API framework — elegant, fast, zero dependencies**
+
+## Overview
+
+`@rip-lang/api` is a complete API framework written entirely in Rip. It provides Hono-compatible routing, middleware composition, and powerful validation — all with no external dependencies.
+
+- **`api.rip`** (~565 lines) — Core framework: routing, validation, `read()`, `session`, server
+- **`middleware.rip`** (~395 lines) — Optional middleware: cors, logger, compress, cookies, sessions, etc.
+
+**Core Philosophy**: API development should be intuitive, safe, and beautiful. Every function eliminates boilerplate, prevents common errors, and makes your intent crystal clear.
+
+### Key Features
+
+- **Zero Dependencies** — Pure Rip implementation, no Hono or other frameworks
+- **Sinatra-Style Handlers** — Return data directly, no ceremony
+- **Magic `@` Access** — Use `@req`, `@json()`, `@session`, `@silent` like Sinatra
+- **Powerful Validation** — 37 built-in validators with elegant `read()` function
+- **Before/After Filters** — Sinatra-style request lifecycle hooks
+- **AsyncLocalStorage** — Safe, race-condition-free request context
+- **Hono-Compatible API** — Easy migration from existing Hono apps
+
+> **See Also**: For complete Rip language documentation, see the [main rip-lang repository](https://github.com/shreeve/rip-lang) and [docs/GUIDE.md](https://github.com/shreeve/rip-lang/blob/main/docs/GUIDE.md).
+
+## Try it Now
+
+Run the included example to see everything working:
+
+```bash
+# Clone the repo (if you haven't)
+git clone https://github.com/shreeve/rip-lang.git
+cd rip-lang
+
+# Run the example server
+bun packages/api/test/example.rip
+```
+
+**Test the endpoints:**
+
+```bash
+# Basic routes
+curl http://localhost:3000/
+curl http://localhost:3000/json
+curl http://localhost:3000/users/42
+
+# Session demo (use -c/-b for cookies)
+curl -c cookies.txt -b cookies.txt http://localhost:3000/session
+# {"views":1,"loggedIn":false}
+
+curl -c cookies.txt -b cookies.txt http://localhost:3000/session
+# {"views":2,"loggedIn":false}
+
+curl -c cookies.txt -b cookies.txt http://localhost:3000/login
+# {"loggedIn":true,"userId":123}
+
+curl -c cookies.txt -b cookies.txt http://localhost:3000/session
+# {"views":4,"userId":123,"loggedIn":true}
+
+curl -c cookies.txt -b cookies.txt http://localhost:3000/logout
+# {"loggedOut":true}
+
+# POST with validation
+curl -X POST http://localhost:3000/signup \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","age":25}'
+```
+
+## Quick Start
+
+### Installation
+
+```bash
+bun add @rip-lang/api
+```
+
+### Basic Usage
+
+```coffee
+import { get, post, use, read, start } from '@rip-lang/api'
+
+# Context-free handlers — just return data!
+get '/', -> 'Hello, World!'
+
+get '/json', -> { message: 'It works!', timestamp: Date.now() }
+
+# Path parameters
+get '/users/:id', ->
+  id = read 'id', 'id!'
+  { user: { id, name: "User #{id}" } }
+
+# Form validation
+post '/signup', ->
+  email = read 'email', 'email!'
+  phone = read 'phone', 'phone'
+  age   = read 'age', 'int', [18, 120]
+  { success: true, email, phone, age }
+
+start port: 3000
+```
+
+### With Context (when needed)
+
+```coffee
+# Access full context for headers, redirects, etc.
+get '/download/:id', (env) ->
+  env.header 'Content-Disposition', 'attachment'
+  env.body getFile!(read 'id', 'id!')
+
+get '/redirect', (env) ->
+  env.redirect 'https://example.com'
+
+get '/custom', (env) ->
+  env.json { created: true }, 201
+```
+
+## The `read()` Function
+
+The crown jewel of `@rip-lang/api` — a validation and parsing powerhouse that eliminates 90% of API boilerplate.
+
+### Basic Patterns
+
+```coffee
+# Required field (throws if missing)
+email = read 'email', 'email!'
+
+# Optional field (returns null if missing)
+phone = read 'phone', 'phone'
+
+# With default value
+role = read 'role', ['admin', 'user'], 'user'
+
+# Get entire payload
+data = read()
+```
+
+### Range Validation
+
+The `[min, max]` syntax works for both numbers and string lengths:
+
+```coffee
+# Numbers: value range
+age = read 'age', 'int', [18, 120]        # Between 18 and 120
+priority = read 'priority', 'int', [1, 10]  # 1-10 range
+
+# Strings: length range
+username = read 'username', 'string', [3, 20]  # 3-20 characters
+bio = read 'bio', 'string', [0, 500]           # Up to 500 chars
+
+# Numbers: value range
+views = read 'views', 'int', min: 0            # Non-negative integer
+discount = read 'discount', 'number', max: 100  # Up to 100
+```
+
+### Enumeration Validation
+
+```coffee
+# Must be one of these values
+role = read 'role', ['admin', 'user', 'guest']
+status = read 'status', ['pending', 'active', 'closed']
+```
+
+### Regex Validation
+
+```coffee
+# Custom pattern matching
+code = read 'code', /^[A-Z]{3,6}$/
+```
+
+## Built-in Validators
+
+`@rip-lang/api` includes 37 validators for every common API need:
+
+### Numbers & Money
+```coffee
+id = read 'user_id', 'id!'       # Positive integer (1+)
+count = read 'count', 'whole'    # Non-negative integer (0+)
+price = read 'price', 'decimal'  # Decimal number
+cost = read 'cost', 'money'      # Cents (multiplies by 100)
+```
+
+### Text Processing
+```coffee
+title = read 'title', 'string'   # Collapses whitespace
+bio = read 'bio', 'text'         # Light cleanup
+name = read 'name', 'name'       # Trims and normalizes
+```
+
+### Contact Information
+```coffee
+email = read 'email', 'email'        # Valid email format
+phone = read 'phone', 'phone'        # US phone → (555) 123-4567
+address = read 'address', 'address'  # Trimmed address
+```
+
+### Geographic Data
+```coffee
+state = read 'state', 'state'      # Two-letter → uppercase
+zip = read 'zip', 'zip'            # 5-digit zip
+zipplus4 = read 'zip', 'zipplus4'  # 12345-6789 format
+```
+
+### Identity & Security
+```coffee
+ssn = read 'ssn', 'ssn'                # SSN → digits only
+sex = read 'gender', 'sex'             # m/f/o
+username = read 'username', 'username' # 3-20 chars, lowercase
+```
+
+### Web & Technical
+```coffee
+url = read 'website', 'url'      # Valid URL
+ip = read 'ip_address', 'ip'     # IPv4 address
+mac = read 'mac', 'mac'          # MAC address
+color = read 'color', 'color'    # Hex color → #abc123
+uuid = read 'user_id', 'uuid'    # UUID format
+semver = read 'version', 'semver' # Semantic version
+```
+
+### Time & Date
+```coffee
+time = read 'time', 'time'        # HH:MM or HH:MM:SS
+date = read 'date', 'date'        # YYYY-MM-DD
+time24 = read 'time', 'time24'    # 24-hour format
+time12 = read 'time', 'time12'    # 12-hour with am/pm
+```
+
+### Boolean & Collections
+```coffee
+active = read 'active', 'truthy'    # true/t/1/yes/y/on → true
+inactive = read 'off', 'falsy'      # false/f/0/no/n/off → true
+flag = read 'flag', 'bool'          # Either → boolean
+tags = read 'tags', 'array'         # Must be array
+config = read 'config', 'hash'      # Must be object
+settings = read 'data', 'json'      # Parse JSON string
+ids = read 'ids', 'ids'             # "1,2,3" → [1, 2, 3]
+slug = read 'slug', 'slug'          # URL-safe slug
+```
+
+### Custom Validators
+
+Register your own validators:
+
+```coffee
+import { registerValidator, read } from '@rip-lang/api'
+
+registerValidator 'postalCode', (v) ->
+  if v =~ /^[A-Z]\d[A-Z] \d[A-Z]\d$/i
+    _[0].toUpperCase()
+  else
+    null
+
+# Now use it
+code = read 'postal', 'postalCode!'
+```
+
+## Routing
+
+### HTTP Methods
+
+```coffee
+import { get, post, put, patch, del, all } from '@rip-lang/api'
+
+get    '/users',     -> listUsers!
+post   '/users',     -> createUser!
+get    '/users/:id', -> getUser!
+put    '/users/:id', -> updateUser!
+patch  '/users/:id', -> patchUser!
+del    '/users/:id', -> deleteUser!
+all    '/health',    -> 'ok'  # All methods
+```
+
+### Path Parameters
+
+```coffee
+# Basic parameters
+get '/users/:id', ->
+  id = read 'id', 'id!'
+  { id }
+
+# Multiple parameters
+get '/users/:userId/posts/:postId', ->
+  userId = read 'userId', 'id!'
+  postId = read 'postId', 'id!'
+  { userId, postId }
+
+# Custom patterns
+get '/files/:name{[a-z]+\\.txt}', ->
+  name = read 'name'
+  { file: name }
+
+# Wildcards
+get '/static/*', (env) ->
+  { path: env.req.path }
+```
+
+### Route Grouping
+
+```coffee
+import { prefix } from '@rip-lang/api'
+
+prefix '/api/v1', ->
+  get '/users', -> listUsers!
+  get '/posts', -> listPosts!
+
+prefix '/api/v2', ->
+  get '/users', -> listUsersV2!
+```
+
+## Middleware
+
+### Built-in Middleware
+
+Import from `@rip-lang/api/middleware`:
+
+```coffee
+import { use } from '@rip-lang/api'
+import { cors, logger, compress, cookies, sessions, secureHeaders, timeout, bodyLimit } from '@rip-lang/api/middleware'
+
+# Logging
+use logger()
+use logger format: 'tiny'                # Minimal output
+use logger format: 'dev'                 # Colorized (default)
+use logger skip: (c) -> c.req.path is '/health'
+
+# CORS
+use cors()                               # Allow all origins
+use cors origin: 'https://myapp.com'     # Specific origin
+use cors origin: ['https://a.com', 'https://b.com']
+use cors credentials: true, maxAge: 86400
+
+# Compression (gzip/deflate)
+use compress()
+use compress threshold: 1024             # Min bytes to compress
+
+# Cookies
+use cookies()
+use cookies secret: 'my-secret', secure: true, httpOnly: true
+
+# Security headers
+use secureHeaders()
+use secureHeaders hsts: true, contentSecurityPolicy: "default-src 'self'"
+
+# Request limits
+use timeout ms: 30000                    # 30 second timeout
+use bodyLimit maxSize: 1024 * 1024       # 1MB max body
+```
+
+### Middleware Options
+
+| Middleware | Options |
+|------------|---------|
+| `logger()` | `format`, `skip`, `stream` |
+| `cors()` | `origin`, `methods`, `headers`, `credentials`, `maxAge` |
+| `compress()` | `threshold`, `encodings` |
+| `cookies()` | `secure`, `httpOnly`, `sameSite`, `maxAge`, `path` |
+| `sessions()` | `name`, `maxAge`, `secure`, `httpOnly`, `sameSite` |
+| `secureHeaders()` | `hsts`, `hstsMaxAge`, `contentSecurityPolicy`, `frameOptions` |
+| `timeout()` | `ms`, `message`, `status` |
+| `bodyLimit()` | `maxSize`, `message` |
+
+### Session Usage
+
+```coffee
+import { get, use, before, session } from '@rip-lang/api'
+import { cookies, sessions } from '@rip-lang/api/middleware'
+
+use cookies()
+use sessions()
+
+before ->
+  session.views ?= 0
+  session.views += 1
+
+get '/profile', ->
+  { userId: session.userId, views: session.views }
+
+get '/login', ->
+  session.userId = 123
+  { loggedIn: true }
+
+get '/logout', ->
+  delete session.userId
+  { loggedOut: true }
+```
+
+The `session` import works anywhere via AsyncLocalStorage — no `@` needed, works in helpers and nested callbacks.
+
+### Cookie Usage (low-level)
+
+```coffee
+import { get, use } from '@rip-lang/api'
+import { cookies } from '@rip-lang/api/middleware'
+
+use cookies()
+
+get '/set-cookie', ->
+  @cookie 'theme', 'dark', maxAge: 3600
+  { success: true }
+
+get '/get-cookie', ->
+  theme = @cookie 'theme'
+  { theme }
+
+get '/logout', ->
+  @clearCookie 'theme'
+  { cleared: true }
+```
+
+### Custom Middleware
+
+```coffee
+# Authentication middleware
+use (c, next) ->
+  token = @req.header 'Authorization'
+  unless token
+    return @json { error: 'Unauthorized' }, 401
+  @user = validateToken!(token)
+  await next()
+
+# Timing middleware
+use (c, next) ->
+  start = Date.now()
+  await next()
+  @header 'X-Response-Time', "#{Date.now() - start}ms"
+```
+
+### Middleware Chain
+
+Middleware runs in registration order with Koa-style `next()`:
+
+```coffee
+use (c, next) ->
+  console.log 'Before handler'
+  await next()
+  console.log 'After handler'
+```
+
+### Before/After Filters (Sinatra-style)
+
+For simpler cases, use `before` and `after` filters. Use `@` to access context:
+
+```coffee
+import { before, after, get } from '@rip-lang/api'
+
+skipPaths = ['/favicon.ico', '/ping', '/health']
+
+# Runs before every request
+before ->
+  @start = Date.now()
+  @silent = @req.path in skipPaths
+  # Return a Response to short-circuit (e.g., for auth)
+  unless @req.header 'Authorization'
+    return @json { error: 'Unauthorized' }, 401
+
+# Runs after every request
+after ->
+  return if @silent
+  console.log "#{@req.method} #{@req.path} - #{Date.now() - @start}ms"
+```
+
+**How `@` works:** Handlers are called with `this` bound to the context, so `@foo` is `this.foo`. This gives you Sinatra-like magic access to:
+- `@req` — Request object
+- `@json()`, `@text()`, `@html()`, `@redirect()` — Response helpers
+- `@header()` — Response header modifier
+- `@anything` — Custom per-request state
+
+**Imports that work anywhere** (via AsyncLocalStorage or Proxy):
+- `read` — Validated request parameters
+- `session` — Session data (if middleware enabled)
+- `env` — `process.env` shortcut (e.g., `env.DATABASE_URL`)
+
+```coffee
+import { get, read, session } from '@rip-lang/api'
+
+get '/profile', ->
+  id = read 'id', 'id!'     # Works anywhere
+  { id, user: session.userId }  # No @ needed
+```
+
+**Note:** In nested callbacks, use fat arrow `=>` to preserve `@`:
+
+```coffee
+get '/delayed', ->
+  @user = 'alice'
+  setTimeout =>           # Fat arrow preserves @
+    console.log @user     # Works!
+  , 100
+```
+
+## Context Object
+
+When you need full control, handlers receive a context object:
+
+### Response Helpers
+
+```coffee
+get '/demo', (c) ->
+  # JSON response
+  c.json { data: 'value' }
+  c.json { data: 'value' }, 201  # With status
+  c.json { data: 'value' }, 200, { 'X-Custom': 'header' }
+
+  # Text response
+  c.text 'Hello'
+  c.text 'Created', 201
+
+  # HTML response
+  c.html '<h1>Hello</h1>'
+
+  # Redirect
+  c.redirect '/new-location'
+  c.redirect '/new-location', 301  # Permanent
+
+  # Raw body
+  c.body data, 200, { 'Content-Type': 'application/octet-stream' }
+```
+
+### Request Helpers
+
+```coffee
+get '/info', (c) ->
+  # Path parameters
+  id = c.req.param 'id'
+  allParams = c.req.param()
+
+  # Query parameters
+  q = c.req.query 'q'
+  allQuery = c.req.query()
+
+  # Headers
+  auth = c.req.header 'Authorization'
+  allHeaders = c.req.header()
+
+  # Body (async)
+  json = c.req.json!
+  text = c.req.text!
+  form = c.req.formData!
+  parsed = c.req.parseBody!
+
+  # Raw request
+  c.req.raw     # Native Request object
+  c.req.method  # 'GET', 'POST', etc.
+  c.req.url     # Full URL
+  c.req.path    # Path only
+```
+
+### Request-Scoped State
+
+Use `@` to store per-request state (each request gets a fresh context):
+
+```coffee
+# Store data for later middleware/handlers
+use (c, next) ->
+  @user = { id: 1, name: 'Alice' }
+  @startTime = Date.now()
+  await next()
+
+get '/profile', ->
+  @json @user
+```
+
+## Error Handling
+
+### Custom Error Handler
+
+```coffee
+import { onError } from '@rip-lang/api'
+
+onError (err, c) ->
+  console.error 'Error:', err
+  c.json { error: err.message }, err.status or 500
+```
+
+### Custom 404 Handler
+
+```coffee
+import { notFound } from '@rip-lang/api'
+
+notFound (c) ->
+  c.json { error: 'Not found', path: c.req.path }, 404
+```
+
+## Server Options
+
+### Basic Server
+
+```coffee
+import { start } from '@rip-lang/api'
+
+start port: 3000
+start port: 3000, host: '0.0.0.0'
+```
+
+### Handler Only (for @rip-lang/server)
+
+```coffee
+import { startHandler } from '@rip-lang/api'
+
+export default startHandler()
+```
+
+### App Pattern
+
+```coffee
+import { App, get, post } from '@rip-lang/api'
+
+export default App ->
+  get '/', -> 'Hello'
+  post '/echo', -> read()
+```
+
+## Utility Functions
+
+### isBlank
+
+```coffee
+import { isBlank } from '@rip-lang/api'
+
+isBlank null        # true
+isBlank undefined   # true
+isBlank ''          # true
+isBlank '   '       # true
+isBlank []          # true
+isBlank {}          # true
+isBlank false       # true
+isBlank 'hello'     # false
+isBlank [1, 2]      # false
+```
+
+### toName
+
+Advanced name formatting with intelligent capitalization:
+
+```coffee
+import { toName } from '@rip-lang/api'
+
+toName 'john doe'           # 'John Doe'
+toName 'JANE SMITH'         # 'Jane Smith'
+toName "o'brien"            # "O'Brien"
+toName 'mcdonald'           # 'McDonald'
+toName 'los angeles', 'address'  # 'Los Angeles'
+```
+
+### toPhone
+
+US phone number formatting:
+
+```coffee
+import { toPhone } from '@rip-lang/api'
+
+toPhone '5551234567'        # '(555) 123-4567'
+toPhone '555-123-4567'      # '(555) 123-4567'
+toPhone '555.123.4567 x99'  # '(555) 123-4567, ext. 99'
+toPhone '+1 555 123 4567'   # '(555) 123-4567'
+```
+
+## Migration from Hono
+
+`@rip-lang/api` provides a Hono-compatible API surface:
+
+### Before (Hono)
+
+```coffee
+import { Hono } from 'hono'
+
+app = new Hono()
+app.get '/users/:id', (c) ->
+  id = c.req.param 'id'
+  c.json { id }
+
+export default app
+```
+
+### After (@rip-lang/api)
+
+```coffee
+import { get, read, startHandler } from '@rip-lang/api'
+
+get '/users/:id', ->
+  id = read 'id', 'id!'
+  { id }
+
+export default startHandler()
+```
+
+### API Compatibility
+
+| Hono | @rip-lang/api |
+|------|---------------|
+| `app.get(path, handler)` | `get path, handler` |
+| `app.post(path, handler)` | `post path, handler` |
+| `app.use(middleware)` | `use middleware` |
+| `app.basePath(path)` | `prefix path, -> ...` |
+| `c.json(data)` | `@json(data)` or return `{ data }` |
+| `c.req.param('id')` | `@req.param('id')` or `read 'id'` |
+| `c.req.query('q')` | `@req.query('q')` or `read 'q'` |
+
+## Real-World Example
+
+```coffee
+import { get, post, put, del, use, read, start, before, after, onError } from '@rip-lang/api'
+import { logger } from '@rip-lang/api/middleware'
+
+# Middleware
+use logger()
+
+# Filters
+before ->
+  @start = Date.now()
+
+after ->
+  console.log "#{@req.method} #{@req.path} - #{Date.now() - @start}ms"
+
+# Error handling
+onError (err) ->
+  @json { error: err.message }, err.status or 500
+
+# Routes
+get '/', ->
+  { name: 'My API', version: '1.0' }
+
+get '/users', ->
+  page = read 'page', 'int', [1, 100]
+  limit = read 'limit', 'int', [1, 50]
+  users = db.listUsers! page or 1, limit or 10
+  { users, page, limit }
+
+get '/users/:id', ->
+  id = read 'id', 'id!'
+  user = db.getUser!(id)
+  unless user
+    throw { message: 'User not found', status: 404 }
+  { user }
+
+post '/users', ->
+  email = read 'email', 'email!'
+  name = read 'name', 'string', [1, 100]
+  phone = read 'phone', 'phone'
+  user = db.createUser! { email, name, phone }
+  { user, created: true }
+
+put '/users/:id', ->
+  id = read 'id', 'id!'
+  email = read 'email', 'email'
+  name = read 'name', 'string', [1, 100]
+  user = db.updateUser! id, { email, name }
+  { user, updated: true }
+
+del '/users/:id', ->
+  id = read 'id', 'id!'
+  db.deleteUser!(id)
+  { deleted: true }
+
+start port: 3000
+```
+
+## Performance
+
+- **Minimal footprint** — Core is ~565 lines, optional middleware ~395 lines
+- **Zero dependencies** — No external packages to load
+- **Compiled patterns** — Route regexes compiled once at startup
+- **Smart response wrapping** — Minimal overhead for return-value handlers
+- **AsyncLocalStorage** — Industry-standard, zero-copy context propagation
+
+## Contributing
+
+Contributions that enhance developer productivity and code clarity are welcome. See the [main rip-lang repository](https://github.com/shreeve/rip-lang) for contribution guidelines.
+
+---
+
+**Transform your API development from verbose boilerplate to clear, elegant code.**
+
+*"90% less code, 100% more clarity"*