@rip-lang/api 0.5.0

package/api.rip

@@ -0,0 +1,564 @@
+# ==============================================================================
+# @rip-lang/api — Pure Rip API Framework
+# ==============================================================================
+#
+# A zero-dependency, Hono-compatible API framework written entirely in Rip.
+# Provides Sinatra-style elegance with AsyncLocalStorage-powered context.
+#
+# Public exports:
+#   DSL:        get, post, put, patch, del, all, use, prefix
+#   Server:     start, startHandler, fetch, App
+#   Filters:    before, after
+#   Handlers:   onError, notFound
+#   Validation: read, validators, registerValidator, getValidator
+#   Context:    ctx, session, env
+#   Utilities:  isBlank, toName, toPhone
+#   Dev:        resetGlobals
+#
+# ==============================================================================
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+# ==============================================================================
+# Module State
+# ==============================================================================
+
+_                = null  # Match capture holder for Rip's =~
+_errorHandler    = null  # Custom error handler
+_notFoundHandler = null  # Custom 404 handler
+_beforeFilters   = []    # Before request filters
+_afterFilters    = []    # After request filters
+_routes          = []    # Route definitions
+_middlewares     = []    # Global middleware functions
+_prefix          = ''    # Current route prefix for grouping
+
+export resetGlobals = ->
+  _errorHandler    = null
+  _notFoundHandler = null
+  _beforeFilters   = []
+  _afterFilters    = []
+  _routes          = []
+  _middlewares     = []
+  _prefix          = ''
+
+# AsyncLocalStorage for request context (enables sync read() in handlers)
+export requestContext = new AsyncLocalStorage()
+
+# ==============================================================================
+# Router: Pattern Compiler
+# ==============================================================================
+
+compilePattern = (path) ->
+  keys = []
+  path = path.replace /\?$/, ''
+  escaped = path.replace /[.+^${}()|[\]\\]/g, '\\$&'
+  regex = escaped.replace /:(\w+)(?:\{([^}]+)\})?/g, (match, key, pattern) ->
+    keys.push key
+    "(#{pattern or '[^/]+'})"
+  regex = regex.replace /(?<![\\*])\*(?!\*)/g, '(.*)'
+  { regex: new RegExp("^#{regex}/?$"), keys }
+
+# ==============================================================================
+# Router: Route Matching
+# ==============================================================================
+
+matchRoute = (method, pathname) ->
+  for route in _routes
+    continue if route.middleware
+    continue unless route.method is method or route.method is 'ALL'
+    match = pathname.match route.regex
+    if match
+      params = {}
+      for key, i in route.keys
+        params[key] = decodeURIComponent(match[i + 1]) if match[i + 1]?
+      return { handler: route.handler, params, route }
+  null
+
+# ==============================================================================
+# Context Factory
+# ==============================================================================
+
+createContext = (req, params = {}) ->
+  url = new URL(req.url)
+  out = new Headers()
+
+  ctx =
+    json: (data, status = 200, headers = {}) ->
+      for k, v of headers then out.set(k, v)
+      out.set 'Content-Type', 'application/json'
+      new Response JSON.stringify(data), { status, headers: out }
+
+    text: (str, status = 200, headers = {}) ->
+      for k, v of headers then out.set(k, v)
+      out.set 'Content-Type', 'text/plain; charset=UTF-8'
+      new Response str, { status, headers: out }
+
+    html: (str, status = 200, headers = {}) ->
+      for k, v of headers then out.set(k, v)
+      out.set 'Content-Type', 'text/html; charset=UTF-8'
+      new Response str, { status, headers: out }
+
+    redirect: (location, status = 302) ->
+      new Response null, { status, headers: { Location: String(location) } }
+
+    body: (data, status = 200, headers = {}) ->
+      for k, v of headers then out.set(k, v)
+      new Response data, { status, headers: out }
+
+    header: (name, value, opts = {}) ->
+      if value?
+        if opts.append then out.append(name, value) else out.set(name, value)
+        return
+      out.get(name)
+
+    session: {}
+
+    req:
+      raw: req
+      method: req.method
+      url: req.url
+      path: url.pathname
+      param: (key) -> if key? then params[key] else { ...params }
+      query: (key) -> if key? then url.searchParams.get(key) else Object.fromEntries(url.searchParams)
+      header: (key) -> if key? then req.headers.get(key) else Object.fromEntries(req.headers)
+      json: -> req.json()
+      text: -> req.text()
+      formData: -> req.formData()
+      parseBody: (opts = {}) ->
+        ct = req.headers.get('content-type') or ''
+        if ct =~ /json/i
+          req.json!
+        else if ct =~ /form/i
+          fd = req.formData!
+          Object.fromEntries(fd)
+        else
+          {}
+
+  ctx
+
+# ==============================================================================
+# Middleware Composition (Koa-style)
+# ==============================================================================
+
+compose = (middlewares, beforeFilters, afterFilters, handler) ->
+  (c) ->
+    index = -1
+    dispatch = (i) ->
+      if i <= index
+        throw new Error 'next() called multiple times'
+      index = i
+
+      # Run middlewares first
+      if i < middlewares.length
+        fn = middlewares[i]
+        result = fn.call! c, c, -> dispatch!(i + 1)
+        c._response = result if result instanceof Response
+        return
+
+      # After middlewares, run before filters, handler, after filters
+      if i is middlewares.length
+        # Run before filters
+        for filter in beforeFilters
+          result = filter.call!(c, c)
+          if result instanceof Response
+            c._response = result
+            return
+
+        # Run handler
+        result = handler.call!(c, c)
+        c._response = result if result instanceof Response
+
+        # Run after filters
+        for filter in afterFilters
+          filter.call!(c, c)
+
+    dispatch!(0)
+    c
+
+# ==============================================================================
+# Smart Response Wrapper
+# ==============================================================================
+
+smart = (fn) ->
+  (c, next) ->
+    try
+      result = if fn.length > 0 then fn.call!(c, c) else fn.call!(c)
+      return result if result instanceof Response
+      return c.json(result) if result? and typeof result is 'object'
+      if typeof result is 'string'
+        type = if result.trimStart().startsWith('<') then 'html' else 'text'
+        return c[type](result)
+      return c.text(String(result)) if typeof result in ['number', 'boolean']
+      if result is null or result is undefined
+        return new Response(null, { status: 204 })
+      result
+    catch err
+      console.error 'Handler error:', err
+      status = err?.status or 500
+      message = err?.message or 'Internal Server Error'
+      new Response message, { status, headers: { 'Content-Type': 'text/plain' } }
+
+# ==============================================================================
+# DSL: Route Registration
+# ==============================================================================
+
+addRoute = (method, path, ...handlers) ->
+  fullPath = "#{_prefix}#{path}"
+  if fullPath.includes(':') and fullPath.endsWith('?')
+    basePath = fullPath.slice(0, -1).replace(/\/:[^\/]+$/, '')
+    addRoute method, basePath, ...handlers if basePath and basePath isnt fullPath.slice(0, -1)
+    fullPath = fullPath.slice(0, -1)
+  { regex, keys } = compilePattern(fullPath)
+  for handler in handlers
+    _routes.push { method: method.toUpperCase(), regex, keys, handler: smart(handler), path: fullPath }
+
+export get   = (path, ...handlers) -> addRoute 'GET',    path, ...handlers
+export post  = (path, ...handlers) -> addRoute 'POST',   path, ...handlers
+export put   = (path, ...handlers) -> addRoute 'PUT',    path, ...handlers
+export patch = (path, ...handlers) -> addRoute 'PATCH',  path, ...handlers
+export del   = (path, ...handlers) -> addRoute 'DELETE', path, ...handlers
+export all   = (path, ...handlers) -> addRoute 'ALL',    path, ...handlers
+
+export use = (pathOrMw, mw = null) ->
+  if typeof pathOrMw is 'function'
+    _middlewares.push pathOrMw
+  else
+    { regex, keys } = compilePattern(pathOrMw)
+    _routes.push { method: 'ALL', regex, keys, handler: mw, path: pathOrMw, middleware: true }
+
+export prefix = (base, fn) ->
+  old = _prefix
+  _prefix = "#{_prefix}#{base}"
+  try
+    fn?()
+  finally
+    _prefix = old
+
+export onError = (handler) -> _errorHandler = handler
+export notFound = (handler) -> _notFoundHandler = handler
+
+export before = (fn) -> _beforeFilters.push fn
+export after = (fn) -> _afterFilters.push fn
+
+# ==============================================================================
+# Main Fetch Handler
+# ==============================================================================
+
+export fetch = (req) ->
+  url = new URL(req.url)
+  pathname = url.pathname
+  method = req.method
+
+  if method is 'HEAD'
+    res = fetch!(new Request(req.url, { method: 'GET', headers: req.headers }))
+    return new Response(null, { status: res.status, headers: res.headers })
+
+  match = matchRoute(method, pathname)
+
+  unless match
+    c = createContext(req)
+    if _notFoundHandler?
+      return _notFoundHandler!(c)
+    return new Response('Not Found', { status: 404 })
+
+  c = createContext(req, match.params)
+
+  # Pre-parse body and query for sync read() — baked in, zero ceremony
+  data = {}
+  try
+    ct = req.headers.get('content-type') or ''
+    if method in ['POST', 'PUT', 'PATCH']
+      if ct =~ /json/i
+        data = c.req.json!
+      else if ct =~ /x-www-form-urlencoded|form-data/i
+        data = c.req.parseBody!
+  catch
+    data = {}
+  merged = { ...data, ...c.req.query(), ...match.params }
+
+  # Run handler inside AsyncLocalStorage context
+  requestContext.run! { env: c, data: merged }, ->
+    runHandler!(c, match.handler)
+
+# Internal: Execute handler with middleware and error handling
+runHandler = (c, handler) ->
+  try
+    # Compose runs: middlewares → before filters → handler → after filters
+    compose!(_middlewares, _beforeFilters, _afterFilters, handler)(c)
+    c._response or new Response('', { status: 204 })
+  catch err
+    console.error 'Request error:', err
+    if _errorHandler?
+      _errorHandler.call!(c, err, c)
+    else
+      new Response err?.message or 'Internal Server Error', { status: 500 }
+
+# ==============================================================================
+# Server Startup
+# ==============================================================================
+
+export startHandler = -> fetch
+
+export start = (opts = {}) ->
+  handler = startHandler()
+  host = opts.host or '0.0.0.0'
+  port = opts.port or 3000
+  server = Bun.serve { hostname: host, port: port, fetch: handler }
+  console.log "rip-api listening on http://#{host}:#{port}"
+  server
+
+export App = (fn) ->
+  resetGlobals()
+  fn?()
+  startHandler()
+
+# ==============================================================================
+# Utility: Get Current Environment/Context
+# ==============================================================================
+
+export ctx = ->
+  store = requestContext.getStore()
+  store?.env or null
+
+# Session proxy — access session.foo anywhere (via AsyncLocalStorage)
+export session = new Proxy {},
+  get: (_, key) ->
+    requestContext.getStore()?.env?.session?[key]
+  set: (_, key, value) ->
+    ctx = requestContext.getStore()?.env
+    return false unless ctx?
+    ctx.session ?= {}
+    ctx.session[key] = value
+    true
+  deleteProperty: (_, key) ->
+    ctx = requestContext.getStore()?.env
+    delete ctx.session[key] if ctx?.session?
+    true
+
+# Env proxy — access env.FOO anywhere (shortcut for process.env)
+export env = new Proxy {}, get: (_, key) -> process.env[key]
+
+# ==============================================================================
+# Utility Functions
+# ==============================================================================
+
+export isBlank = (obj) ->
+  return true unless obj?
+  return true if obj is false
+  return true if typeof obj is 'string' and /^\s*$/.test obj
+  return true if Array.isArray(obj) and obj.length is 0
+  return true if typeof obj is 'object' and Object.keys(obj).length is 0
+  false
+
+capitalize = (str) -> str.charAt(0).toUpperCase() + str.slice(1).toLowerCase()
+
+export toName = (str, type...) ->
+  s = String(str)
+  s = s.toLowerCase().replace(/\s+/g, ' ').trim()
+  s = s.replace /(^|(?<=\P{L}))(\p{L})/gu, (m, pre, ch) -> pre + ch.toUpperCase()
+  s = s.replace(/[`'']/g, "'").replace(/[""]/g, '"')
+  s = s.replace /\b([a-z])\. ?([bcdfghjklmnpqrstvwxyz])\.?(?=\W|$)/gi, (match, p1, p2) -> (p1 + p2).toUpperCase()
+  s = s.replace /(?<=^|\P{L})([A-Za-z](?:(?![AEIOUYaeiouy])[A-Za-z]){1,4})(?=$|\P{L})/gu, (m) -> m.toUpperCase()
+  s = s.replace /\b([djs]r|us|acct|[ai]nn?|apps|ed|erb|elk|esq|grp|in[cj]|of[cf]|st|up)\.?(?=\W|$)/gi, (match) -> capitalize(match)
+  s = s.replace /(^|(?<=\d ))?\b(and|at|as|of|then?|in|on|or|for|to|by|de l[ao]s?|del?|(el-)|el|las)($)?\b/ig, (m, p1, p2, p3, p4, offset) ->
+    if offset is 0 or p1? or p3? or p4? then capitalize(p2) else p2.toLowerCase()
+  s = s.replace /\b(mc|mac(?=d[ao][a-k,m-z][a-z]|[fgmpw])|[dol]')([a-z])/gi, (m, p1, p2) -> capitalize(p1) + capitalize(p2)
+  if type.includes 'name'
+    s = s.replace /\b(ahn|an[gh]|al|art[sz]?|ash|e[dnv]|echt|elms|emms|eng|epps|essl|i[mp]|mrs?|ms|ng|ock|o[hm]|ohrt|ong|orr|ohrt|ost|ott|oz|sng|tsz|u[br]|ung)\b/gi, (match) -> capitalize(match)
+  if type.includes 'address'
+    s = s.replace /(?<=^| |\p{P})(apt?s?|arch|ave?|bldg|blvd|cr?t|co?mn|drv?|elm|end|f[lt]|hts?|ln|old|pkw?y|plc?|prk|pt|r[dm]|spc|s[qt]r?|srt|street|[nesw])\.?(?=$|[^\p{L}\p{N}_])/giu, (matched) -> capitalize(matched)
+  s = s.replace /(1st|2nd|3rd|[\d]th|\bde l[ao]s)\b/gi, (match) -> match.toLowerCase()
+  s = s.replace /\b(ca|dba|fbo|ihop|mri|ucla|usa|vru|[ns][ew]|i{1,3}v?)\b/gi, (match) -> match.toUpperCase()
+  s = s.replace /\b([-@.\w]+\.(?:com|net|io|org))\b/gi, (match) -> match.toLowerCase()
+  s = s.replace /(?<=\p{L}')S\b/gu, 's'
+  s = s.replace /# /g, '#'
+  s = s.replace /\s*[.,#]+$/, ''
+  s = s.replace /\bP\.? ?O\.? ?Box/i, 'PO Box'
+  s
+
+export toPhone = (str) ->
+  return "" if isBlank(str)
+  num = str.toString().replace(/\s+/g, ' ').trim()
+  [num, ext] = num.split(/\s*(?:, ?)?(?:ext?\.?|x|#|:|,)\s*/i, 2)
+  ext = ext.replace(/\D+/g, "") if ext
+  if num =~ /^\+([-+#*.,\d ]+)$/
+    etc = _[1].replace(/[^#*,\d]+/g, "")
+    if etc.replace(/\D+/g, "").length >= 6
+      if etc =~ /^1(\d{10})$/
+        [num, ext] = [_[1], ""]
+      else
+        return "+#{etc}"
+  num = num.replace(/^[^2-9]*/, "").replace(/\D+/g, "")
+  if num =~ /^([2-9][0-8][0-9])([2-9]\d\d)(\d{4})$/
+    num = "(#{_[1]}) #{_[2]}-#{_[3]}"
+    num += ", ext. #{ext}" if ext
+  else
+    num = null
+  num
+
+# ==============================================================================
+# Validators
+# ==============================================================================
+
+export validators =
+  # Numbers & money
+  id:        (v) -> v[/^([1-9]\d{0,19})$/]            and parseInt(_[1])
+  whole:     (v) -> v[/^(0|[1-9]\d{0,19})$/]          and parseInt(_[1])
+  decimal:   (v) -> v[/^([-+]?\d+(?:\.\d*)?|\.\d+)$/] and parseFloat(_[1])
+  money:     (v) -> v[/^([-+]?\d+(?:\.\d*)?|\.\d+)$/] and Math.round(parseFloat(_[1]) * 100)
+
+  # Strings & formatting
+  string:    (v) -> v.replace(/\s\s+/g, ' ')
+  text:      (v) -> v.replace(/  +/g, ' ')
+
+  # Name/address
+  name:      (v) -> v.replace(/\s+/g, ' ').trim()
+  address:   (v) -> v.replace(/\s+/g, ' ').trim()
+
+  # Time & date
+  time:      (v) -> v[/^([01]?\d|2[0-3]):[0-5]\d(:[0-5]\d)?$/] and _[0]
+  date:      (v) -> v[/^\d{4}-\d{2}-\d{2}$/]                   and _[0]
+  dateutc:   (v) -> v[/^\d{4}-\d{2}-\d{2}Z?$/]                 and _[0]
+
+  # Booleans
+  truthy:    (v) -> (v =~ /^(true|t|1|yes|y|on)$/i)  and true
+  falsy:     (v) -> (v =~ /^(false|f|0|no|n|off)$/i) and true
+  bool:      (v) -> (v =~ /^(true|t|1|yes|y|on|false|f|0|no|n|off)$/i) and (v =~ /^(true|t|1|yes|y|on)$/i)
+
+  # Contact, geo, identity
+  email:     (v) -> v[/^([a-zA-Z0-9._%+-]+)@([a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$/] and _[0]
+  state:     (v) -> v[/^([a-z][a-z])$/i]              and _[1].toUpperCase()
+  zip:       (v) -> v[/^(\d{5})/]                     and _[1]
+  zipplus4:  (v) -> v[/^(\d{5})-?(\d{4})$/]           and "#{_[1]}-#{_[2]}"
+  ssn:       (v) -> v[/^(\d{3})-?(\d{2})-?(\d{4})$/]  and "#{_[1]}#{_[2]}#{_[3]}"
+  sex:       (v) -> v[/^(m|male|f|female|o|other)$/i] and _[1][0].toLowerCase()
+
+  # Phone
+  phone:     (v) -> toPhone(v)
+
+  # Web & technical
+  username:  (v) -> v[/^([a-zA-Z0-9_-]{3,20})$/]        and _[1].toLowerCase()
+  ip:        (v) -> v[/^(?:\d{1,3}\.){3}\d{1,3}$/]      and _[0]
+  mac:       (v) -> v[/^([0-9a-fA-F]{2})(?:[:-]?)([0-9a-fA-F]{2})(?:[:-]?)([0-9a-fA-F]{2})(?:[:-]?)([0-9a-fA-F]{2})(?:[:-]?)([0-9a-fA-F]{2})(?:[:-]?)([0-9a-fA-F]{2})$/] and "#{_[1]}:#{_[2]}:#{_[3]}:#{_[4]}:#{_[5]}:#{_[6]}".toLowerCase()
+  url:       (v) -> v[/^(https?:\/\/)?([\da-z\.-]+)\.([a-z\.]{2,6})([\/\w\.-]*)*\/?$/] and _[0]
+  color:     (v) -> v[/^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/] and "##{_[1].toLowerCase()}"
+  uuid:      (v) -> v[/^([0-9a-f]{8})-?([0-9a-f]{4})-?([0-9a-f]{4})-?([0-9a-f]{4})-?([0-9a-f]{12})$/i] and "#{_[1]}-#{_[2]}-#{_[3]}-#{_[4]}-#{_[5]}".toLowerCase()
+  semver:    (v) -> v[/^(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*))?(?:\+([a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*))?$/] and _[0]
+
+  # Time formats & currency
+  time24:    (v) -> v[/^([01]?[0-9]|2[0-3]):([0-5][0-9])(?::([0-5][0-9]))?$/] and _[0]
+  time12:    (v) -> v[/^(1[0-2]|0?[1-9]):([0-5][0-9])\s?(am|pm)$/i]           and _[0].toLowerCase()
+  currency:  (v) -> v[/^\$?(\d{1,3}(?:,\d{3})*(?:\.\d{2})?)$/]                and parseFloat(_[1].replace(/,/g, ''))
+
+  # Collections & structured
+  array:     (v) -> Array.isArray(v) and v or null
+  hash:      (v) -> (v? and typeof v is 'object' and not Array.isArray(v)) and v or null
+  json:      (v) -> if typeof v is 'string' then (try JSON.parse(v) catch then null) else if typeof v is 'object' then v else null
+
+  # Slugs & ids list
+  slug:      (v) -> v[/^([a-z0-9]+(?:-[a-z0-9]+)*)$/] and _[1]
+  ids:       (v) ->
+    cleaned = v.replace(/[, ]+/g, ' ').trim()
+    return null unless cleaned
+    try
+      nums = []
+      for part in cleaned.split(' ')
+        return null unless part[/^([1-9]\d{0,19})$/]
+        nums.push parseInt(_[1])
+      Array.from(new Set(nums)).sort((a, b) -> a - b)
+    catch then null
+
+export registerValidator = (name, fn) -> validators[name] = fn
+export getValidator      = (name)     -> validators[name]
+
+# ==============================================================================
+# read() — Sinatra-style Parameter Reading
+# ==============================================================================
+
+export read = (keyOrTag = null, tagOrMiss = null, missOrNil = null) ->
+  store = requestContext.getStore()
+  unless store?
+    throw new Error 'read() called outside request context'
+
+  data = store.data or {}
+  key  = null
+  tag  = null
+  miss = null
+
+  if keyOrTag? and (tagOrMiss? or missOrNil isnt null)
+    key  = keyOrTag
+    tag  = tagOrMiss
+    miss = missOrNil
+  else
+    key  = null
+    tag  = keyOrTag
+    miss = tagOrMiss
+
+  raw = if key? then data[key] else data
+  return raw unless tag?
+
+  required = false
+  if typeof tag is 'string' and tag.endsWith('!')
+    required = true
+    tag = tag.slice(0, -1)
+
+  v = raw
+
+  # Named validator
+  if typeof tag is 'string'
+    fn = getValidator(tag)
+    v = if fn then fn(String(v or '')) else null
+
+  # Array: [min, max] constraint or enumeration
+  else if Array.isArray(tag)
+    if typeof tag[0] is 'number'
+      minVal = tag[0]
+      maxVal = tag[1]
+      if typeof v is 'number' or (String(v) =~ /^[-+]?\d+$/)
+        n = if typeof v is 'number' then v else parseInt(String(v))
+        ok = not isNaN(n)
+        ok = false if minVal? and n < minVal
+        ok = false if maxVal? and n > maxVal
+        v = if ok then n else null
+      else
+        s = String(v or '')
+        ok = true
+        ok = false if minVal? and s.length < minVal
+        ok = false if maxVal? and s.length > maxVal
+        v = if ok then s else null
+    else
+      v = if tag.includes(String(v)) then String(v) else null
+
+  # Regex
+  else if tag instanceof RegExp
+    v = String(v or '')[tag] or null
+
+  # Object constraints
+  else if typeof tag is 'object'
+    if tag.start? or tag.end?
+      n = parseInt(v)
+      v = if not isNaN(n) and (not tag.start? or n >= tag.start) and (not tag.end? or n <= tag.end) then n else null
+    else if tag.min? or tag.max?
+      if typeof v is 'number' or (String(v or '') =~ /^[-+]?\d+$/)
+        n = if typeof v is 'number' then v else parseInt(String(v))
+        ok = not isNaN(n)
+        ok = false if tag.min? and n < tag.min
+        ok = false if tag.max? and n > tag.max
+        v = if ok then n else null
+      else
+        s = String(v or '')
+        ok = true
+        ok = false if tag.min? and s.length < tag.min
+        ok = false if tag.max? and s.length > tag.max
+        v = if ok then s else null
+
+  blank = v is null or v is undefined or (typeof v is 'string' and v.trim() is '')
+
+  if blank
+    if required
+      return miss?() if typeof miss is 'function'
+      throw new Error "Missing required field: #{key}"
+    else
+      return (miss?() if typeof miss is 'function') or miss or null
+
+  v