init Module API

The init module provides core application creation, routing, and middleware functions.

Nixi.new()

Creates a new Nixi application instance.

Nixi.new(config?)

Parameters:

Returns: App - The application instance

local app = Nixi.new({
    host = "0.0.0.0",
    port = 8080,
})

Nixi.new_context()

Creates a new request context object for testing or internal use.

Nixi.new_context(method, path, headers, body)

Parameters:

• method - HTTP method (string)
• path - Request URL path (string)
• headers - Request headers (table)
• body - Request body (string)

Returns: Context - A new context object

local ctx = Nixi.new_context("GET", "/users", {}, "")

Routing Methods

app:get(path, handler)

Register a GET route handler.

app:get("/path", function(ctx)
    return "Response"
end)

app:post(path, handler)

Register a POST route handler.

app:post("/api/data", function(ctx)
    local data = ctx.request.body
    return Nixi.json({ received = true })
end)

app:put(path, handler)

Register a PUT route handler.

app:put("/users/:id", function(ctx)
    local id = ctx.params.id
    return Nixi.json({ updated = id })
end)

app:delete(path, handler)

Register a DELETE route handler.

app:delete("/users/:id", function(ctx)
    local id = ctx.params.id
    return Nixi.json({ deleted = id })
end)

Middleware

app:use(middleware)

Register middleware to run before routes.

app:use(function(ctx)
    -- Called before every request
    print("Request:", ctx.request.path)
end)

Middleware can return early:

local function requireAuth(ctx)
    if not ctx.locals.user then
        return Nixi.redirect("/login")
    end
end

app:use(requireAuth)

Path-specific middleware:

app:use("/api", function(ctx)
    ctx.locals.isApiRequest = true
end)

Query Parsing

Nixi.parse_query(query_string)

Parses a URL query string into a table.

Nixi.parse_query(query_string)

Parameters:

• query_string - Raw query string (without leading ?)

Returns: table - Key-value pairs

local params = Nixi.parse_query("name=John&age=30")
-- { name = "John", age = "30" }

Response Helpers

Nixi.html(content)

Returns an HTML response.

Nixi.html(content)

Parameters:

• content - HTML string to return

Returns: Response - A response object

app:get("/", function(ctx)
    return Nixi.html([[
        <h1>Welcome!</h1>
        <p>Hello from Nixi!</p>
    ]])
end)

Nixi.json(data)

Returns a JSON response. Includes a built-in JSON encoder if dkjson is not available.

Nixi.json(data)

Parameters:

• data - Table to encode as JSON

app:get("/api/users", function(ctx)
    return Nixi.json({
        users = {
            { id = 1, name = "Alice" },
            { id = 2, name = "Bob" }
        }
    })
end)

Nixi.redirect(path, status?)

Returns a redirect response.

Nixi.redirect(path, status?)

Parameters:

• path - URL to redirect to
• status - HTTP status code (default: 302)

app:get("/old", function(ctx)
    return Nixi.redirect("/new")
end)

app:get("/moved", function(ctx)
    return Nixi.redirect("/new", 301) -- Permanent redirect
end)

Nixi.not_found(message?)

Returns a 404 Not Found response.

Nixi.not_found(message?)

Parameters:

• message - Custom error message (optional)

app:get("/resource/:id", function(ctx)
    local resource = find_resource(ctx.params.id)
    if not resource then
        return Nixi.not_found("Resource not found")
    end
    return Nixi.html("Found: " .. resource.name)
end)

app:route(path, handler, method, options?)

Generic route registration with method and options.

app:route(path, handler, method, options?)

Parameters:

• path - Route path
• handler - Handler function
• method - HTTP method (GET, POST, PUT, DELETE)
• options - Optional route options (name, middleware, layout)

app:route("/api/data", function(ctx)
    return Nixi.json({ data = "value" })
end, "GET", {
    name = "api.data",
    middleware = { log_request }
})

Route Matching

Nixi.match_route(pattern, path)

Matches a path against a route pattern and extracts parameters.

Nixi.match_route(pattern, path)

Parameters:

• pattern - Route pattern (e.g., "/users/:id")
• path - Actual path to match

Returns: table? - Table with params if matched, nil otherwise

local result = Nixi.match_route("/users/:id", "/users/123")
-- { params = { id = "123" }, matched = true }

local result = Nixi.match_route("/users/:id", "/posts/123")
-- nil

Type Definitions

---@class App
---@field get fun(path: string, handler: fun(ctx: Context): any): App
---@field post fun(path: string, handler: fun(ctx: Context): any): App
---@field put fun(path: string, handler: fun(ctx: Context): any): App
---@field delete fun(path: string, handler: fun(ctx: Context): any): App
---@field use fun(middleware: fun(ctx: Context): any?): App

---@class Context
---@field request Request
---@field params table
---@field locals table
---@field response Response

---@class Request
---@field method string
---@field path string
---@field query table
---@field headers table
---@field body table

---@class Response
---@field status number
---@field headers table
---@field body string

Complete Example

package.path = "src/?.lua;src/?/init.lua;" .. package.path
local Nixi = require("nixi.init")

local app = Nixi.new({
    host = "127.0.0.1",
    port = 3000,
})

app:use(function(ctx)
    ctx.locals.requestTime = os.time()
    print("Incoming request:", ctx.request.method, ctx.request.path)
end)

app:get("/", function(ctx)
    return "Welcome to Nixi!"
end)

app:get("/users/:id", function(ctx)
    local id = ctx.params.id
    return Nixi.json({ user_id = id })
end)

app:post("/data", function(ctx)
    local body = ctx.request.body
    return Nixi.json({ received = body })
end)

return app