nightshade/nerak
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

nerak repo

Browse Source
This commit is contained in:
nightshade
2026-07-13 17:19:33 -05:00
parent 3d2c18cb29
commit 0e8c9854bf
2 changed files with 54 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+41 -41
View File
@@ -1243,7 +1243,7 @@ task("daily_digest", {
**`.errors` / `.repairs`** *(per task)*: each task can declare its own handlers, resolved the same way as resource pipelines (the task's own handlers, then its module's). See [Error and Repair Pipelines](#error-and-repair-pipelines).
```c
task("send_invoice", {
fetch({.url = "https://api.billing.dev/invoices/{{invoice_id}}", .ctx_key = "inv"})
fetch({n_get, "https://api.billing.dev/invoices/{{invoice_id}}", "inv"})
}, .repairs = {{n_not_authorized, {run(.call = refresh_billing_token)}}});
```
@@ -1289,43 +1289,43 @@ Built-in regex macros are defined in `nerak.h`; define your own the same way: `#
**`.ctx_key` *(by order)***: name of the parameter to validate.
```c
input({"title", "^\\S+$", "required"})
input({.ctx_key = "title", .regex = "^\\S+$", .err_msg = "required"})
```
**`.regex` *(by order)***: regex pattern, or a built-in validator macro.
```c
input({"email", n_email, "bad email"})
input({.ctx_key = "email", .regex = n_email, .err_msg = "bad email"})
```
**`.err_msg` *(by order)***: human-readable error shown via `{{error_message:name}}`.
```c
input({"age", n_int, "must be a number"})
input({.ctx_key = "age", .regex = n_int, .err_msg = "must be a number"})
```
**`.opt`**: skip validation when the parameter is absent.
```c
input({"filter", "^(active|done)$", .opt = true})
input({.ctx_key = "filter", .regex = "^(active|done)$", .opt = true})
```
**`.def`**: default value injected when the parameter is absent.
```c
input({"page", n_int, .def = "1"})
input({.ctx_key = "page", .regex = n_int, .def = "1"})
```
Combined:
```c
input(
{"email", n_email, "must be a valid email"},
{"title", n_not_empty, "cannot be empty"},
{"page", n_int, "must be a number", .def = "1"},
{"filter", "^(active|done)$", "must be 'active' or 'done'", .opt = true},
{"username", n_user, "must be alphanumeric"}
{.ctx_key = "email", .regex = n_email, .err_msg = "must be a valid email"},
{.ctx_key = "title", .regex = n_not_empty, .err_msg = "cannot be empty"},
{.ctx_key = "page", .regex = n_int, .err_msg = "must be a number", .def = "1"},
{.ctx_key = "filter", .regex = "^(active|done)$", .err_msg = "must be 'active' or 'done'", .opt = true},
{.ctx_key = "username", .regex = n_user, .err_msg = "must be alphanumeric"}
)
```
For checks beyond regex (uniqueness, cross-field rules, lookups), pair `input()` with a query and `run()`:
```c
input({"username", n_user, "must be alphanumeric"}),
input({.ctx_key = "username", .regex = n_user, .err_msg = "must be alphanumeric"}),
sqlite_query({"users_db", "find_username", "existing"}),
run(^(){
auto rows = get("existing");
@@ -1350,39 +1350,39 @@ Each engine provides its own query step: `sqlite_query()`, `postgres_query()`, `
**`.db` *(by order)***: database name, matching the name a `<engine>_config(...)` was registered with.
```c
sqlite_query({"todos_db", "get_todos", "todos_data"})
sqlite_query({.db = "todos_db", .q = "get_todos", .ctx_key = "todos_data"})
```
**`.q` *(by order)***: context key holding the SQL to run.
```c
sqlite_query({"todos_db", "get_todos", "todos_data"})
sqlite_query({.db = "todos_db", .q = "get_todos", .ctx_key = "todos_data"})
```
**`.ctx_key` *(by order)***: context key for the result table. Optional; omit when the result isn't needed (e.g. an insert without `RETURNING`).
```c
sqlite_query({"todos_db", "create_todo"}) // no result captured
sqlite_query({"todos_db", "get_todos", "todos_data"}) // result under "todos_data"
sqlite_query({.db = "todos_db", .q = "create_todo"}) // no result captured
sqlite_query({.db = "todos_db", .q = "get_todos", .ctx_key = "todos_data"}) // result under "todos_data"
```
**`.err_on_empty`**: when true, raise `404 Not Found` if the query affects/returns zero rows. Default false.
```c
sqlite_query({"todos_db", "get_todo", "todo", .err_on_empty = true})
sqlite_query({.db = "todos_db", .q = "get_todo", .ctx_key = "todo", .err_on_empty = true})
```
**`.if_ctx` / `.not_ctx`** *(per item)*: conditionally include or skip individual queries while running the others concurrently.
```c
sqlite_query(
{"db", "get_todos", "todos_data"},
{"db", "get_urgent", "urgent", .if_ctx = "show_urgent"}
{.db = "db", .q = "get_todos", .ctx_key = "todos_data"},
{.db = "db", .q = "get_urgent", .ctx_key = "urgent", .if_ctx = "show_urgent"}
)
```
Combined:
```c
sqlite_query(
{"todos_db", "get_todos", "todos_data"},
{"todos_db", "get_todo", "todo", .err_on_empty = true},
{"todos_db", "get_urgent", "urgent", .if_ctx = "show_urgent"}
{.db = "todos_db", .q = "get_todos", .ctx_key = "todos_data"},
{.db = "todos_db", .q = "get_todo", .ctx_key = "todo", .err_on_empty = true},
{.db = "todos_db", .q = "get_urgent", .ctx_key = "urgent", .if_ctx = "show_urgent"}
)
```
@@ -1417,7 +1417,7 @@ Nests records from one context table into each matching record of another, like
Combined:
```c
join("projects", "id", "todos", "project_id")
join(.parent_ctx_key = "projects", .parent_field_key = "id", .child_ctx_key = "todos", .child_field_key = "project_id")
```
**Full context example.** Concurrent query → `join()` → `mustache()`: fetch parent and children from separate queries, render as one nested structure. Blog + comments, single database:
@@ -1450,7 +1450,7 @@ resource("blog", "/blogs/:id",
),
// Nest each comment into its matching blog record
join("blog", "id", "comments", "blog_id"),
join(.parent_ctx_key = "blog", .parent_field_key = "id", .child_ctx_key = "comments", .child_field_key = "blog_id"),
// Enter {{#blog}} first; after join(), comments lives INSIDE each blog record
mustache("blog", "blog_s"),
@@ -1606,7 +1606,7 @@ Pushes a Server-Sent Event. With `.chan`, the event broadcasts to all clients on
**`.chan` *(by order)***: channel to broadcast on; supports `{{interpolation}}`.
```c
sse("todos:{{user_id}}", .event = "new_todo", .data = {"{{todo}}"})
sse(.chan = "todos:{{user_id}}", .event = "new_todo", .data = {"{{todo}}"})
```
**`.event`**: SSE `event:` line value.
@@ -1626,7 +1626,7 @@ sse(.comment = "keep-alive")
Combined:
```c
sse("todos:{{user_id}}",
sse(.chan = "todos:{{user_id}}",
.event = "todo_updated",
.data = {"id: {{todo_id}}", "title: {{title}}"},
.comment = "broadcast at {{timestamp}}"
@@ -1639,23 +1639,23 @@ Renders a template into the pipeline context. `mustache()` renders Mustache; `md
**`.template_ctx_key` *(by order)***: context key holding the template string to render.
```c
mustache("todos", "todos_s")
mustache(.template_ctx_key = "todos", .ctx_key = "todos_s")
```
**`.ctx_key` *(by order)***: context key to write the rendered output to.
```c
mustache("todos", "todos_s")
mustache(.template_ctx_key = "todos", .ctx_key = "todos_s")
```
JSON:
```c
json("todos", "todos_j")
json(.template_ctx_key = "todos", .ctx_key = "todos_j")
```
Markdown-with-Mustache:
```c
context("welcome", "# Welcome, {{user_name}}");
mdm("welcome", "welcome_s")
mdm(.template_ctx_key = "welcome", .ctx_key = "welcome_s")
```
#### respond
@@ -1664,23 +1664,23 @@ Sends a pipeline context value as the HTTP response.
**`.ctx_key` *(by order)***: key of the rendered content to send.
```c
respond("todos_s")
respond(.ctx_key = "todos_s")
```
**`.status`**: HTTP response status (default `n_ok`). Values: `n_ok` (200), `n_created` (201), `n_redirect` (302), `n_bad_request` (400), `n_not_authorized` (401), `n_not_found` (404), `n_error` (500).
```c
respond("not_found_s", .status = n_not_found)
respond(.ctx_key = "not_found_s", .status = n_not_found)
```
**`.mime`**: override the response content type. Values: `n_html`, `n_txt`, `n_es`, `n_json`, `n_js`.
```c
respond("plain_s", .mime = n_txt)
respond(.ctx_key = "plain_s", .mime = n_txt)
```
Combined:
```c
mustache("not_found", "not_found_s"),
respond("not_found_s", .status = n_not_found)
respond(.ctx_key = "not_found_s", .status = n_not_found)
```
#### headers and cookies
@@ -1961,7 +1961,7 @@ respond("standard_s", .not_ctx = "is_urgent")
```c
// One request per row in `users`, all concurrent.
// Each row's `id` fills the URL; responses collected into `profiles`, aligned with `users`.
fetch({.url = "https://api.users.dev/{{id}}", .ctx_key = "profiles", .map = "users"})
fetch({n_get, "https://api.users.dev/{{id}}", "profiles", .map = "users"})
```
**`.map_key`**: context key under which the current row is exposed as a single-row table. Pairs with `.map`.
@@ -2037,9 +2037,9 @@ For `GET /todos/5` the executed order is: `input({"id", ...})` (resource `.all`)
config(blogs){
sqlite_config(
.name = "blog_db",
.conn = "file:blogs.db?mode=rwc",
.migrations = {"create_blogs_table", "create_comments_table"}
"blog_db",
"file:blogs.db?mode=rwc",
{"create_blogs_table", "create_comments_table"}
);
resource("blog", "/blogs/:id",
@@ -2119,7 +2119,7 @@ Activate with `#include <datastar.h>`. Serves the Datastar runtime as the `{{> d
**`.chan` *(by order)***: channel to push to.
```c
mustache("todo_row", "todo_row_s"),
datastar("todos:{{user_id}}", .target = "#todo-list", .mode = ds_append, .elements = "todo_row_s")
datastar(.chan = "todos:{{user_id}}", .target = "#todo-list", .mode = ds_append, .elements = "todo_row_s")
```
**`.target`**: element id or CSS selector for the element to patch; supports `{{interpolation}}`.
@@ -2162,7 +2162,7 @@ resource("todos", "/todos",
sqlite_query({"todos_db", "insert_todo", "todo", .err_on_empty = true}),
// Render the new row, then patch it into the list for everyone on the channel.
mustache("todo_row", "todo_row_s"),
datastar("todos:{{user_id}}",
datastar(.chan = "todos:{{user_id}}",
.target = "#todo-list",
.mode = ds_append,
.elements = "todo_row_s"
@@ -2173,7 +2173,7 @@ resource("todos", "/todos",
Removing an element needs only a selector:
```c
datastar("todos:{{user_id}}", .target = "#todo-{{id}}", .mode = ds_remove)
datastar(.chan = "todos:{{user_id}}", .target = "#todo-{{id}}", .mode = ds_remove)
```
Datastar sets a context flag on requests it originates, usable with `.if_ctx`.