|
1 | | -# framework |
2 | | - |
3 | | -Modular TypeScript/Deno utilities for building type‑safe web apps: HTTP routing, typed clients, SPA URL-as-state navigation, SQLite helpers, time utilities, and shared types. |
4 | | - |
5 | | -## [`api`](./api) |
6 | | -Type-safe HTTP toolkit: router, server wrapper, request context, logger, response helpers, env utilities, and validator. Compose end-to-end typed APIs with consistent logging and errors. |
7 | | - |
8 | | -### [`api/router`](./api/router.ts) |
9 | | -Define routes with input/output schemas, optional authorization, and automatic responses. Produces types for clients; validates GET params/body and logs with sensitive-key redaction. |
10 | | - |
11 | | -### [`api/server`](./api/server.ts) |
12 | | -Wraps your router with logging, error barrier, cookie parsing, trace/span IDs, and `RequestContext` creation. Handles OPTIONS and integrates respond.* errors. |
13 | | - |
14 | | -### [`api/context`](./api/context.ts) |
15 | | -AsyncLocalStorage-powered `RequestContext` with `getContext`/`newContext`/`runContext`. Carries Request, URL, cookies, trace and span across async boundaries. |
16 | | - |
17 | | -### [`api/log`](./api/log.ts) |
18 | | -Environment-aware logger (dev/test/prod) with pretty colors, call-chain, batching to devtool, filtering, and context trace/span metadata. Exposes info/warn/error/debug. |
19 | | - |
20 | | -### [`api/response`](./api/response.ts) |
21 | | -`respond.*` helpers to build JSON Responses for every status and paired Error classes (`ResponseError`). Adds default JSON headers and bodyless handling (204/304, etc.). |
22 | | - |
23 | | -### [`api/env`](./api/env.ts) |
24 | | -`ENV()` getter with fallback and required enforcement; typed `APP_ENV` guard (dev/test/prod) with validation; `CI_COMMIT_SHA`, `DEVTOOL_TOKEN`, `DEVTOOL_URL` accessors. |
25 | | - |
26 | | -### [`api/validator`](./api/validator.ts) |
27 | | -High-performance, schema-based validation with `OBJ`, `ARR`, `STR`, `NUM`, `BOOL`, `LIST`, `UNION`, optional. Generates assert/report functions and infers types via `Asserted<T>`. |
28 | | - |
29 | | -## [`api-client`](./api-client) |
30 | | -Generates a strongly typed client from server route definitions. Provides fetch and reactive signal() helpers with abort/dedupe and rich JSON/body error types. |
31 | | - |
32 | | -## [`api-proxy`](./api-proxy) |
33 | | -Vite dev proxy for `/api/*` to a localhost backend. Streams requests/responses, preserves headers/status/cookies, merges Set-Cookie, and aborts on client disconnect—avoids CORS. |
34 | | - |
35 | | -## [`db`](./db) |
36 | | -SQLite helpers: declare tables, auto-generate insert/update/get/exists, foreign-key joins, tagged SQL and existence checks, singleton connection, and test restore points. |
37 | | - |
38 | | - |
39 | | -### [`db/migration`](./db/migration.ts) |
40 | | -Versioned migrations via SQLite `PRAGMA user_version`. Reads a migrations directory for files named `NNN-*.ts|js`, imports each `run(sql)` in order, applies them, and updates `user_version`. Skips work on a clean DB, logs progress, and surfaces errors. |
41 | | - |
42 | | -### [`db/entries`](./db/entries.ts) |
43 | | -Event-sourcing style “entries” with a star‑schema. `initEntries(ids, relations, types)` creates the `entryInternal` table, the `entry` view (active rows), per‑type views (`entry_<lowercase>`), and basic indexes. Generates per‑type `insert` functions that capture `RequestContext` `trace`/`span` and timestamps, supports optional typed `fields` stored in dedicated tables, soft‑archive via `archivedAt`, plus `insertListeners` for streaming/SSE triggers. |
44 | | - |
45 | | - |
46 | | -## [`signal-router`](./signal-router) |
47 | | -URL-as-state SPA routing on `@preact/signals`. Typed `A` component, `navigate`, `replaceParams`, reactive url helpers; normalizes trailing slashes and skips external and /api links. |
48 | | - |
49 | | -## [`time`](./time) |
50 | | -Time utilities in seconds: startTime, `now()` is a more precise `Date.now()`, and constants `SEC`, `MIN`, `HOUR`, `DAY`, `WEEK`, `YEAR`. |
51 | | - |
52 | | -## [`types`](./types) |
53 | | -Generic utility types: deep `Readonly`, `Expand`, `Awaitable`, `Nullish`, `IsUnknown`, `UnionToIntersection`, and `MatchKeys`. |
| 1 | +# framework |
| 2 | + |
| 3 | +Modular TypeScript/Deno utilities for building type‑safe web apps: HTTP routing, |
| 4 | +typed clients, SPA URL-as-state navigation, SQLite helpers, time utilities, and |
| 5 | +shared types. |
| 6 | + |
| 7 | +## [`api`](./api) |
| 8 | + |
| 9 | +Type-safe HTTP toolkit: router, server wrapper, request context, logger, |
| 10 | +response helpers, env utilities, and validator. Compose end-to-end typed APIs |
| 11 | +with consistent logging and errors. |
| 12 | + |
| 13 | +### [`api/router`](./api/router.ts) |
| 14 | + |
| 15 | +Define routes with input/output schemas, optional authorization, and automatic |
| 16 | +responses. Produces types for clients; validates GET params/body and logs with |
| 17 | +sensitive-key redaction. |
| 18 | + |
| 19 | +### [`api/server`](./api/server.ts) |
| 20 | + |
| 21 | +Wraps your router with logging, error barrier, cookie parsing, trace/span IDs, |
| 22 | +and `RequestContext` creation. Handles OPTIONS and integrates respond.* errors. |
| 23 | + |
| 24 | +### [`api/context`](./api/context.ts) |
| 25 | + |
| 26 | +AsyncLocalStorage-powered `RequestContext` with |
| 27 | +`getContext`/`newContext`/`runContext`. Carries Request, URL, cookies, trace and |
| 28 | +span across async boundaries. |
| 29 | + |
| 30 | +### [`api/log`](./api/log.ts) |
| 31 | + |
| 32 | +Environment-aware logger (dev/test/prod) with pretty colors, call-chain, |
| 33 | +batching to devtool, filtering, and context trace/span metadata. Exposes |
| 34 | +info/warn/error/debug. |
| 35 | + |
| 36 | +### [`api/response`](./api/response.ts) |
| 37 | + |
| 38 | +`respond.*` helpers to build JSON Responses for every status and paired Error |
| 39 | +classes (`ResponseError`). Adds default JSON headers and bodyless handling |
| 40 | +(204/304, etc.). |
| 41 | + |
| 42 | +### [`api/env`](./api/env.ts) |
| 43 | + |
| 44 | +`ENV()` getter with fallback and required enforcement; typed `APP_ENV` guard |
| 45 | +(dev/test/prod) with validation; `CI_COMMIT_SHA`, `DEVTOOL_TOKEN`, `DEVTOOL_URL` |
| 46 | +accessors. |
| 47 | + |
| 48 | +### [`api/validator`](./api/validator.ts) |
| 49 | + |
| 50 | +High-performance, schema-based validation with `OBJ`, `ARR`, `STR`, `NUM`, |
| 51 | +`BOOL`, `LIST`, `UNION`, optional. Generates assert/report functions and infers |
| 52 | +types via `Asserted<T>`. |
| 53 | + |
| 54 | +## [`api-client`](./api-client) |
| 55 | + |
| 56 | +Generates a strongly typed client from server route definitions. Provides fetch |
| 57 | +and reactive signal() helpers with abort/dedupe and rich JSON/body error types. |
| 58 | + |
| 59 | +## [`api-proxy`](./api-proxy) |
| 60 | + |
| 61 | +Vite dev proxy for `/api/*` to a localhost backend. Streams requests/responses, |
| 62 | +preserves headers/status/cookies, merges Set-Cookie, and aborts on client |
| 63 | +disconnect—avoids CORS. |
| 64 | + |
| 65 | +## [`db`](./db) |
| 66 | + |
| 67 | +SQLite helpers: declare tables, auto-generate insert/update/get/exists, |
| 68 | +foreign-key joins, tagged SQL and existence checks, singleton connection, and |
| 69 | +test restore points. |
| 70 | + |
| 71 | +### [`db/migration`](./db/migration.ts) |
| 72 | + |
| 73 | +Versioned migrations via SQLite `PRAGMA user_version`. Reads a migrations |
| 74 | +directory for files named `NNN-*.ts|js`, imports each `run(sql)` in order, |
| 75 | +applies them, and updates `user_version`. Skips work on a clean DB, logs |
| 76 | +progress, and surfaces errors. |
| 77 | + |
| 78 | +### [`db/entries`](./db/entries.ts) |
| 79 | + |
| 80 | +Event-sourcing style “entries” with a star‑schema. |
| 81 | +`initEntries(ids, relations, types)` creates the `entryInternal` table, the |
| 82 | +`entry` view (active rows), per‑type views (`entry_<lowercase>`), and basic |
| 83 | +indexes. Generates per‑type `insert` functions that capture `RequestContext` |
| 84 | +`trace`/`span` and timestamps, supports optional typed `fields` stored in |
| 85 | +dedicated tables, soft‑archive via `archivedAt`, plus `insertListeners` for |
| 86 | +streaming/SSE triggers. |
| 87 | + |
| 88 | +## [`signal-router`](./signal-router) |
| 89 | + |
| 90 | +URL-as-state SPA routing on `@preact/signals`. Typed `A` component, `navigate`, |
| 91 | +`replaceParams`, reactive url helpers; normalizes trailing slashes and skips |
| 92 | +external and /api links. |
| 93 | + |
| 94 | +## [`time`](./time) |
| 95 | + |
| 96 | +Time utilities in seconds: startTime, `now()` is a more precise `Date.now()`, |
| 97 | +and constants `SEC`, `MIN`, `HOUR`, `DAY`, `WEEK`, `YEAR`. |
| 98 | + |
| 99 | +## [`types`](./types) |
| 100 | + |
| 101 | +Generic utility types: deep `Readonly`, `Expand`, `Awaitable`, `Nullish`, |
| 102 | +`IsUnknown`, `UnionToIntersection`, and `MatchKeys`. |
0 commit comments