nova_common

Shared utilities for the Nova ecosystem. This package contains the foundational building blocks (exceptions, response helpers, and types) that work independently of Nova core.

Installation

pesde add hypernova/nova_commmon
pesde install

Modules

Exception

A set of constructor functions for standard HTTP exceptions. Each returns a { statusCode, message } payload that Nova's error handling pipeline understands.

local Exception = require("path/to/exception")

-- Generic
Exception.HttpException(418, "I'm a teapot")

-- 4xx
Exception.BadRequest()
Exception.Unauthorized("Token expired")
Exception.Forbidden()
Exception.NotFound("User not found")
Exception.Conflict()
Exception.TooManyRequests()

-- 5xx
Exception.InternalServerError()
Exception.BadGateway()
Exception.ServiceUnavailable()

All message arguments are optional and fall back to the standard HTTP reason phrase.

---

Response

Helper functions for constructing ResponsePayload values. Each function sets a sensible default Content-Type and status code (200) while allowing full overrides through an optional config.

local Response = require("path/to/response")

-- Plain text
Response.send("Hello, world!")

-- JSON (body is encoded automatically)
Response.json({ ok = true, data = user })

-- HTML, CSS, JS
Response.html("<h1>Hello</h1>")
Response.css("body { margin: 0; }")
Response.js("console.log('hi')")

-- With config overrides
Response.json({ error = "Not found" }, { status = 404 })
Response.send("Created", {
    status = 201,
    headers = { ["X-Request-Id"] = id }
})

---

Types

Shared type definitions for the Nova ecosystem. Import these in your middleware or handler libraries to stay compatible with Nova's type contracts without depending on core.

local Types = require("path/to/types")

-- Useful types:
-- Types.Request
-- Types.RequestWith<T>       -- parameterized request with typed params/query
-- Types.Middleware
-- Types.Handler
-- Types.Next
-- Types.ResponsePayload
-- Types.ResponseOptions
-- Types.ValidatorSchema

Example — writing a typed middleware:

local Types = require("path/to/types")
local Exception = require("path/to/exception")

local function AuthRule(req: Types.Request, next: Types.Next)
    local token = req.headers and req.headers["Authorization"]

    if not token then
        error(Exception.Unauthorized())
    end

    next()
end

return AuthRule

License

MIT