create-acrylblends 0.0.0-stage → 0.1.1

package/docs/framework/api/summary.md

@@ -0,0 +1,140 @@
+# API summary
+
+One page with the calls an ordinary app uses, each linked to the page that explains it. Imports are from `acryl-router` unless noted.
+
+## A plugin that serves an app
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { Acryl } from 'acrylblends'
+import { trimTrailingSlash } from 'acrylblends/trailing-slash'
+import { schemaValidator, type StandardSchema } from 'acrylblends/schema-validator'
+import { streamSSE } from 'acrylblends/streaming'
+import type {} from 'acryl-state'
+
+export const name = 'orders'                 // the package name and the Loader row id
+export const inject = ['router', 'state']    // the plugin waits (PENDING) until both exist
+
+interface Order { id: string, item: string }
+const NewOrder: StandardSchema<{ item: string }> = {
+  '~standard': {
+    validate: value => {
+      const item = (value as { item?: unknown } | null)?.item
+      return typeof item === 'string' && item !== '' ? { value: { item } } : { issues: [{ message: 'item is required', path: ['item'] }] }
+    },
+  },
+}
+
+export function apply(ctx: Context): void {
+  const orders = ctx.state.cell<Order[]>('orders.list', [])
+  const app = new Acryl()
+    .use(trimTrailingSlash())
+    .get('/', c => c.json(orders.get()))
+    .post('/', schemaValidator('json', NewOrder), c => {
+      const order = { id: crypto.randomUUID(), ...c.req.valid('json') }
+      orders.update(list => [...list, order])
+      return c.json(order, 201)
+    })
+    .get('/events', c => streamSSE(c, async stream => {
+      const ended = new Promise<void>(resolve => { stream.onAbort(resolve) })
+      const stop = orders.subscribe(list => { void stream.writeSSE({ data: JSON.stringify(list) }) })
+      await stream.writeSSE({ data: JSON.stringify(orders.get()) })
+      try { await ended } finally { stop() }
+    }))
+  ctx.router.route('/orders', app)
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/orders') })
+}
+```
+
+## `Acryl` ([Routing](../api/routing.md))
+
+| Call | Does |
+| --- | --- |
+| `new Acryl()` | an application: a route table plus middleware |
+| `.get / .post / .put / .patch / .delete / .options (path, ...handlers)` | a route; handlers before the last are middleware for that route |
+| `.all(path, ...)`, `.on(methods, path, ...)` | any method, or a list of methods |
+| `.use([path], ...middleware)` | middleware for every route below `path` (all routes without it), registered before the routes it wraps |
+| `.route(path, otherApp)` | copy another app's routes below `path` |
+| `.basePath(path)` | the same app with a prefix on every route registered through it |
+| `.onError((err, c) => ...)`, `.notFound(c => ...)` | the app's error and not-found answers |
+| `.request(pathOrRequest, init?)` | call the app in process (tests) |
+| `.fetch(request)` | the app as a fetch handler |
+
+Paths: `/posts/:id` (parameter), `/posts/:id?` (optional), `/files/*` (wildcard), `/:name{[a-z]+}` (pattern). `/a` and `/a/` are different
+paths: see [Trailing slashes](../api/routing.md#trailing-slashes).
+
+## The handler context `c` ([Context](../api/context.md))
+
+| Call | Does |
+| --- | --- |
+| `c.json(value, status?, headers?)` | a JSON answer |
+| `c.text(text, status?)`, `c.html(html, status?)` | a text or HTML answer |
+| `c.body(data, status?, headers?)` | a raw answer (`c.body(null, 204)`) |
+| `c.redirect(location, status = 302)` | a redirect |
+| `c.notFound()` | the app's not-found answer |
+| `c.header(name, value)`, `c.status(code)` | set a header or the status (also after `await next()` in middleware) |
+| `c.set(key, value)`, `c.get(key)`, `c.var.key` | values for this request only, passed from middleware to handlers |
+| `c.req.raw.signal` | aborts when the caller leaves, the serving plugin unloads, or the router is disposed |
+| `c.executionCtx.waitUntil(promise)` | keep the request in flight until background work settles |
+| `connectionOf(c)` / `getConnInfo(c)` | the caller's address and the local port, when a transport supplied them |
+| `throw new HTTPException(status, { message })` | stop with that status from anywhere in the chain |
+
+## The request `c.req` ([Request](../api/request.md))
+
+| Call | Gives |
+| --- | --- |
+| `c.req.param('id')`, `c.req.param()` | route parameters |
+| `c.req.query('page')`, `c.req.query()`, `c.req.queries('tag')` | query string values (`queries` for repeated keys) |
+| `c.req.header('x-name')`, `c.req.header()` | request headers |
+| `await c.req.json()`, `c.req.text()`, `c.req.formData()`, `c.req.parseBody()`, `c.req.arrayBuffer()`, `c.req.blob()` | the body, once |
+| `c.req.valid(target)` | the value a validator checked, typed by its schema |
+| `c.req.method`, `c.req.path`, `c.req.url`, `c.req.raw` | the method, path, full URL and the Web `Request` |
+
+## Validation ([Validation](../cordis/validation.md))
+
+```ts
+import { schemaValidator } from 'acrylblends/schema-validator'
+import { validator } from 'acrylblends/validator'
+app.post('/', schemaValidator('json', Schema), c => c.json(c.req.valid('json')))
+```
+
+- Targets: `json`, `form`, `query`, `param`, `header`, `cookie`. `Schema` is any Standard Schema (Schemastery, Zod, Valibot, or an
+  object with `'~standard': { validate }`).
+- A failure is 400 `{ error: 'invalid <target>', issues: [{ message, path }] }`; `path` is dotted, and `""` when the issue has none.
+- The `json` target reads the body only with a JSON `Content-Type`; otherwise the schema sees `{}`.
+- `validator(target, (value, c) => valueOrResponse)` is the same middleware with a function instead of a schema.
+- Put `bodyLimit({ maxSize })` from `acrylblends/body-limit` in front on routes open to untrusted callers.
+
+## Streaming ([Helpers](../guides/helpers.md))
+
+| Call | Does |
+| --- | --- |
+| `streamSSE(c, async stream => { ... })` | a server-sent event answer |
+| `stream.writeSSE({ data, event?, id?, retry? })` | send one event (`data` is a string) |
+| `stream.write(text)`, `stream.writeln(text)` | raw bytes or a line (a comment line such as `: keep-alive\n\n` keeps a proxy from closing the stream) |
+| `stream.onAbort(fn)`, `stream.aborted` | the client left or the plugin unloaded: stop work and release subscriptions |
+| `stream(c, ...)`, `streamText(c, ...)` | a byte stream or a text stream instead of events |
+
+Do not start timers inside a handler for keep-alives; let the plugin own one timer and write to the open streams.
+
+## Cordis services
+
+| Call | Service | Does |
+| --- | --- | --- |
+| `ctx.router.route(path, app)` | `router` (`acryl-router`) | serve `app` below `path` for as long as the calling plugin is loaded; returns a function that removes it sooner |
+| `ctx.router.request(path, init?)`, `ctx.router.fetch(request)` | `router` | call the mounted routes in process (terminal UI, tests, other plugins) |
+| `ctx.router.onError(handler)`, `ctx.router.notFound(handler)` | `router` | router-wide error and not-found answers, owned by the caller |
+| `ctx.routerHttp.mount(prefix)` | `routerHttp` (`acryl-router-http`) | inside the ACRYL Host: serve a router prefix on the Host's web server (Web and Desktop). Use it through `ctx.inject(['routerHttp'], ...)` so the app also runs where there is no Host |
+| `ctx.nodeServer.url`, `ctx.nodeServer.port` | `nodeServer` (`acryl-node-server`) | without the Host: one Node server for the whole router; options `hostname` (`127.0.0.1`), `port` (`0`), `scan` (`20`). See [Node server](../cordis/node-server.md) |
+| `ctx.state.cell(key, initial)` | `state` (`acryl-state`) | a writable cell owned by the plugin: `get()`, `set(value)`, `update(fn)`, `subscribe(fn)` returning an unsubscribe |
+| `ctx.state.derive(key, [cells], fn)` | `state` | a read-only cell computed from others |
+| `GET /api/state/:key`, `GET /api/state/:key/events` | `state` | each cell over the router, read-only; `useCell(cell)` from `acryl-state/react` in a React page |
+
+Everything a plugin registers this way (mounts, cells, handlers) goes away when the plugin unloads, and comes back once when it reloads:
+see [Plugin lifecycle and disposal](../cordis/plugin-lifecycle.md).
+
+## Middleware ([Middleware](../concepts/middleware.md))
+
+Each from its own subpath (`acrylblends/body-limit`, `acrylblends/cors`, ...): `bodyLimit`, `cors`, `csrf`, `secureHeaders`, `etag`, `compress`, `logger`, `requestId`, `timeout`,
+`bearerAuth`, `basicAuth`, `jwt`, `jwk`, `ipRestriction`, `methodNotAllowed`, `trimTrailingSlash`, `appendTrailingSlash`, `some` /
+`every` / `except`, and ACRYL's `loopbackOnly` for private loopback routes.

package/docs/framework/concepts/benchmarks.md

@@ -0,0 +1,26 @@
+# Benchmarks
+
+> **Not yet measured.** The routers in the framework are designed for different situations (see [Routers](routers.md)), but benchmark results for Acryl itself have not been
+> produced yet, and this page does not quote anyone else's numbers as ours. When Acryl has its own reproducible benchmark suite, its scripts and results will be here.
+
+To compare routers on your own workload today, register your routes on an `Acryl` app with each router and time `app.request()` for the paths you care about:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { RegExpRouter } from 'acrylblends/router/reg-exp-router'
+import { TrieRouter } from 'acrylblends/router/trie-router'
+
+const routes = ['/', '/users/:id', '/posts/:id/comments']
+
+const apps = {
+  RegExpRouter: new Acryl({ router: new RegExpRouter() }),
+  TrieRouter: new Acryl({ router: new TrieRouter() }),
+}
+
+for (const [name, app] of Object.entries(apps)) {
+  for (const path of routes) app.get(path, (c) => c.text('ok'))
+  const start = performance.now()
+  for (let i = 0; i < 100_000; i++) await app.request('/users/42')
+  console.log(name, Math.round(performance.now() - start), 'ms')
+}
+```

package/docs/framework/concepts/developer-experience.md

@@ -0,0 +1,5 @@
+# Developer Experience
+
+To create a great application, we need great development experience.
+Fortunately, we can write applications for Node.js and Bun in TypeScript without having the need to transpile it to JavaScript.
+Acryl is written in TypeScript and can make applications type-safe.

package/docs/framework/concepts/middleware.md

@@ -0,0 +1,21 @@
+# Middleware
+
+We call the primitive that returns `Response` as "Handler".
+"Middleware" is executed before and after the Handler and handles the `Request` and `Response`.
+It's like an onion structure.
+
+For example, we can write the middleware to add the "X-Response-Time" header as follows.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.use(async (c, next) => {
+  const start = performance.now()
+  await next()
+  const end = performance.now()
+  c.res.headers.set('X-Response-Time', `${end - start}`)
+})
+```
+
+With this simple method, we can write our own custom middleware and we can use the built-in or third party middleware.

package/docs/framework/concepts/motivation.md

@@ -0,0 +1,14 @@
+# Philosophy
+
+## Motivation
+
+A web application should not be written twice because it runs in two places. Acryl builds on the Web Standard APIs (`Request`, `Response`, `fetch`, `URL`, streams), so a
+handler written once runs on Node.js (and experimentally Bun), in a test with no socket, and inside a Cordis app.
+
+Three ideas follow from that:
+
+- **The handler is a function over Web Standards.** There is no runtime object to import, so there is nothing to replace when the runtime changes. See
+  [Web Standards](web-standard.md).
+- **A plugin owns what it mounts.** Inside a Cordis app an application is mounted by a plugin and disappears when that plugin unloads, which is what lets an agent add,
+  update and remove features while the app runs. See [Plugin lifecycle](../cordis/plugin-lifecycle.md).
+- **The documentation travels with the app.** A generated app contains these pages, so a person or a coding agent working in the folder reads the API from the folder.

package/docs/framework/concepts/routers.md

@@ -0,0 +1,63 @@
+# Routers
+
+The router decides which handler answers a request. Acryl has five routers behind one API, and an `Acryl` app uses `SmartRouter` unless you choose another.
+
+| Router | Import | Built for |
+| --- | --- | --- |
+| `SmartRouter` | `acrylblends/router/smart-router` | the default: it picks from the routers it is given, by the routes registered |
+| `RegExpRouter` | `acrylblends/router/reg-exp-router` | matching all routes with one regular expression built before dispatch |
+| `TrieRouter` | `acrylblends/router/trie-router` | all route patterns, with a trie tree and no linear loop |
+| `LinearRouter` | `acrylblends/router/linear-router` | applications that register routes at every start, because registration compiles nothing |
+| `PatternRouter` | `acrylblends/router/pattern-router` | the smallest implementation |
+
+## RegExpRouter
+
+**RegExpRouter** turns the route patterns into one large regular expression and gets the result with one match. It is not the kind of "RegExp router" that tries each
+route's expression in a loop, so matching does not repeat for every route.
+
+It does not support every routing pattern, so it is normally combined with a router that does, through `SmartRouter`.
+
+## TrieRouter
+
+**TrieRouter** uses a trie tree, and like RegExpRouter it does not loop over the routes. It supports all patterns.
+
+## SmartRouter
+
+**SmartRouter** is for using several routers. It infers, from the routes registered, which of the routers it was given can serve them, and keeps using that one. An `Acryl`
+app defaults to:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { RegExpRouter } from 'acrylblends/router/reg-exp-router'
+import { SmartRouter } from 'acrylblends/router/smart-router'
+import { TrieRouter } from 'acrylblends/router/trie-router'
+
+const app = new Acryl({
+  router: new SmartRouter({ routers: [new RegExpRouter(), new TrieRouter()] }),
+})
+```
+
+## LinearRouter
+
+**LinearRouter** registers a route without compiling anything, by keeping the routes in a list and matching them in order. Registration is cheap and matching is linear in
+the number of routes, so it suits an environment that builds the application at every start and serves few requests.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { LinearRouter } from 'acrylblends/router/linear-router'
+
+const app = new Acryl({ router: new LinearRouter() })
+```
+
+## PatternRouter
+
+**PatternRouter** is the smallest of the routers: it adds a pattern and matches it, and nothing else. Choose it when size matters more than anything else.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { PatternRouter } from 'acrylblends/router/pattern-router'
+
+const app = new Acryl({ router: new PatternRouter() })
+```
+
+How the routers compare on your workload is for you to measure; see [Benchmarks](benchmarks.md).

package/docs/framework/concepts/stacks.md

@@ -0,0 +1,235 @@
+# Acryl Stacks
+
+Acryl makes easy things easy and hard things easy.
+It is suitable for not just only returning JSON, but it's also great for building the full-stack application including REST API servers and the client.
+
+## RPC
+
+Acryl's RPC feature allows you to share API specs with little change to your code.
+The client generated by `hc` will read the spec and access the endpoint type-safety.
+
+The following libraries make it possible.
+
+- Acryl - API Server
+- [Zod](https://zod.dev) - Validator
+- Zod Validator Middleware
+- `hc` - HTTP Client
+
+We can call the set of these components the **Acryl Stack**.
+Now let's create an API server and a client with it.
+
+## Writing API
+
+First, write an endpoint that receives a GET request and returns JSON.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/hello', (c) => {
+  return c.json({
+    message: `Hello!`,
+  })
+})
+```
+
+## Validation with Zod
+
+Validate with Zod to receive the value of the query parameter.
+
+```ts
+import { schemaValidator } from 'acrylblends/schema-validator'
+import * as z from 'zod'
+
+app.get(
+  '/hello',
+  schemaValidator(
+    'query',
+    z.object({
+      name: z.string(),
+    })
+  ),
+  (c) => {
+    const { name } = c.req.valid('query')
+    return c.json({
+      message: `Hello! ${name}`,
+    })
+  }
+)
+```
+
+## Sharing the Types
+
+To emit an endpoint specification, export its type.
+
+> **Warning.**
+> For the RPC to infer routes correctly, all included methods must be chained, and the endpoint or app type must be inferred from a declared variable. For more, see [Best Practices for RPC](../guides/best-practices.md#if-you-want-to-use-rpc-features).
+>
+
+```ts
+const route = app.get(
+  '/hello',
+  schemaValidator(
+    'query',
+    z.object({
+      name: z.string(),
+    })
+  ),
+  (c) => {
+    const { name } = c.req.valid('query')
+    return c.json({
+      message: `Hello! ${name}`,
+    })
+  }
+)
+
+export type AppType = typeof route
+```
+
+## Client
+
+Next, The client-side implementation.
+Create a client object by passing the `AppType` type to `hc` as generics.
+Then, magically, completion works and the endpoint path and request type are suggested.
+
+```ts
+import type { AppType } from './server'
+import { hc } from 'acrylblends/client'
+
+const client = hc<AppType>('/api')
+const res = await client.hello.$get({
+  query: {
+    name: 'Acryl',
+  },
+})
+```
+
+The `Response` is compatible with the fetch API, but the data that can be retrieved with `json()` has a type.
+
+```ts
+const data = await res.json()
+console.log(`${data.message}`)
+```
+
+Sharing API specifications means that you can be aware of server-side changes.
+
+## With React
+
+You can create an application with a React front-end using the typed client.
+
+The API server.
+
+```ts
+// src/index.ts
+import { Acryl } from 'acrylblends'
+import * as z from 'zod'
+import { schemaValidator } from 'acrylblends/schema-validator'
+
+const schema = z.object({
+  id: z.string(),
+  title: z.string(),
+})
+
+type Todo = z.infer<typeof schema>
+
+const todos: Todo[] = []
+
+const api = new Acryl()
+  .post('/todo', schemaValidator('form', schema), (c) => {
+    const todo = c.req.valid('form')
+    todos.push(todo)
+    return c.json({
+      message: 'created!',
+    })
+  })
+  .get('/todo', (c) => {
+    return c.json({
+      todos,
+    })
+  })
+
+export type AppType = typeof api
+
+const app = new Acryl()
+app.route('/api', api)
+
+export default app
+```
+
+The client with React and React Query.
+
+```tsx
+// src/App.tsx
+import {
+  useQuery,
+  useMutation,
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query'
+import type { AppType } from '../functions/api/[[route]]'
+import { hc, InferResponseType, InferRequestType } from 'acrylblends/client'
+
+const queryClient = new QueryClient()
+const client = hc<AppType>('/api')
+
+export default function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Todos />
+    </QueryClientProvider>
+  )
+}
+
+const Todos = () => {
+  const query = useQuery({
+    queryKey: ['todos'],
+    queryFn: async () => {
+      const res = await client.todo.$get()
+      return await res.json()
+    },
+  })
+
+  const $post = client.todo.$post
+
+  const mutation = useMutation<
+    InferResponseType<typeof $post>,
+    Error,
+    InferRequestType<typeof $post>['form']
+  >({
+    mutationFn: async (todo) => {
+      const res = await $post({
+        form: todo,
+      })
+      return await res.json()
+    },
+    onSuccess: async () => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+    onError: (error) => {
+      console.log(error)
+    },
+  })
+
+  return (
+    <div>
+      <button
+        onClick={() => {
+          mutation.mutate({
+            id: Date.now().toString(),
+            title: 'Write code',
+          })
+        }}
+      >
+        Add Todo
+      </button>
+
+      <ul>
+        {query.data?.todos.map((todo) => (
+          <li key={todo.id}>{todo.title}</li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```

package/docs/framework/concepts/web-standard.md

@@ -0,0 +1,37 @@
+# Web Standards
+
+Acryl uses only **Web Standards** like Fetch.
+They were originally used in the `fetch` function and consist of basic objects that handle HTTP requests and responses.
+In addition to `Requests` and `Responses`, there are `URL`, `URLSearchParam`, `Headers` and others.
+
+Cloudflare Workers, Deno, and Bun also are built upon Web Standards.
+For example, a server that returns "Hello World" could be written as below. This could run on Cloudflare Workers and Bun.
+
+```ts twoslash
+export default {
+  async fetch() {
+    return new Response('Hello World')
+  },
+}
+```
+
+Acryl uses only Web Standards, which means that Acryl can run on any runtime that supports them.
+In addition, we have a Node.js adapter. Acryl runs on these runtimes:
+
+- Cloudflare Workers (`workerd`)
+- Deno
+- Bun
+- Fastly Compute
+- AWS Lambda
+- Node.js
+- Vercel (edge-light)
+- WebAssembly (w/ [WebAssembly System Interface (WASI)][wasi] via [`wasi:http`][wasi-http])
+
+It also works on Netlify and other platforms.
+The same code runs on all platforms.
+
+Cloudflare Workers, Deno, Shopify, and others launched [WinterCG](https://wintercg.org) to discuss the possibility of using the Web Standards to enable "web-interoperability".
+Acryl will follow their steps and go for **the Standard of the Web Standards**.
+
+[wasi]: https://github.com/WebAssembly/wasi
+[wasi-http]: https://github.com/WebAssembly/wasi-http