create-acrylblends 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.md +12 -1
  2. package/dist/index.d.ts +16 -1
  3. package/dist/index.js +301 -12
  4. package/dist/index.js.map +1 -1
  5. package/docs/framework/README.md +4 -3
  6. package/docs/framework/UPSTREAM.md +1 -1
  7. package/docs/framework/getting-started/aws-lambda.md +115 -0
  8. package/docs/framework/getting-started/bun.md +1 -3
  9. package/docs/framework/getting-started/cloudflare-pages.md +53 -0
  10. package/docs/framework/getting-started/cloudflare-workers.md +67 -0
  11. package/docs/framework/getting-started/lambda-edge.md +41 -0
  12. package/docs/framework/getting-started/netlify.md +25 -0
  13. package/docs/framework/getting-started/other-runtimes.md +20 -9
  14. package/docs/framework/getting-started/service-worker.md +31 -0
  15. package/docs/framework/getting-started/vercel.md +28 -0
  16. package/docs/framework/guides/client-modules.md +34 -0
  17. package/docs/framework/guides/create-acrylblends.md +40 -2
  18. package/docs/framework/guides/faq.md +2 -2
  19. package/docs/framework/helpers/conninfo.md +1 -1
  20. package/docs/framework/helpers/ssg.md +1 -1
  21. package/docs/framework/helpers/streaming.md +120 -0
  22. package/docs/framework/helpers/websocket.md +2 -2
  23. package/docs/framework/middleware/builtin/ip-restriction.md +1 -1
  24. package/docs/framework/upstream.json +3 -3
  25. package/package.json +3 -2
  26. package/templates/chat/gitignore +5 -0
  27. package/templates/chat/package.json +23 -0
  28. package/templates/chat/src/app.ts +6 -0
  29. package/templates/chat/src/chat-app.ts +96 -0
  30. package/templates/chat/src/client/chat.tsx +115 -0
  31. package/templates/chat/src/client/tsconfig.json +15 -0
  32. package/templates/chat/src/db.ts +59 -0
  33. package/templates/chat/src/index.ts +22 -0
  34. package/templates/chat/src/llm.ts +42 -0
  35. package/templates/chat/src/page.tsx +38 -0
  36. package/templates/chat/test/chat.test.ts +153 -0
  37. package/templates/chat/test/server.test.ts +59 -0
  38. package/templates/chat/tsconfig.json +19 -0
@@ -0,0 +1,28 @@
1
+ # Vercel
2
+
3
+ Vercel runs a function that takes a `Request` and returns a `Response`, which is what `app.fetch` is. `handle(app)` from `acrylblends/vercel` is that function.
4
+
5
+ > **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a `Request`. It has not been deployed to Vercel by the ACRYL team.
6
+
7
+ ## A function
8
+
9
+ Create `api/index.ts`:
10
+
11
+ ```ts
12
+ import { Acryl } from 'acrylblends'
13
+ import { handle } from 'acrylblends/vercel'
14
+
15
+ const app = new Acryl().basePath('/api')
16
+
17
+ app.get('/', (c) => c.text('Hello from Vercel'))
18
+ app.get('/hello', (c) => c.json({ hello: 'world' }))
19
+
20
+ export const GET = handle(app)
21
+ export const POST = handle(app)
22
+ ```
23
+
24
+ Export one handler per HTTP method the app answers. Run it locally with `vercel dev`, and publish with `vercel deploy`.
25
+
26
+ ## The client's address
27
+
28
+ The client's address comes from `getConnInfo` of `acrylblends/vercel`, which reads the `x-real-ip` header Vercel sets; see the [ConnInfo helper](../helpers/conninfo.md).
@@ -110,6 +110,40 @@ server's nodes are gone afterwards, together with anything the visitor did to th
110
110
  into an input. Keep the server markup the same as the component's first render, so the swap does not show, and keep inputs out of the
111
111
  server markup of an island, or render them only in the browser.
112
112
 
113
+ ## A form and its state in an island
114
+
115
+ An island that owns an input keeps the text in state and writes it back to the element, so typing and clearing the box both work:
116
+
117
+ ```tsx
118
+ import { render, useState } from 'acrylblends/jsx/dom'
119
+
120
+ const Ask = () => {
121
+ const [text, setText] = useState('')
122
+ const [sent, setSent] = useState<string[]>([])
123
+ const submit = (event: Event) => {
124
+ event.preventDefault()
125
+ if (text.trim() === '') return
126
+ setSent([...sent, text.trim()])
127
+ setText('')
128
+ }
129
+ return (
130
+ <form onSubmit={submit}>
131
+ <textarea value={text} onInput={(e) => setText((e.target as HTMLTextAreaElement).value)} />
132
+ <button type="submit">Send</button>
133
+ <ul>
134
+ {sent.map((message) => (
135
+ <li>{message}</li>
136
+ ))}
137
+ </ul>
138
+ </form>
139
+ )
140
+ }
141
+
142
+ render(<Ask />, document.getElementById('ask')!)
143
+ ```
144
+
145
+ For a request that streams its answer and a Stop button (an `AbortController` kept in a `useRef`), see [Streaming an answer from a model](../helpers/streaming.md#streaming-an-answer-from-a-model).
146
+
113
147
  ## How the imports reach the browser
114
148
 
115
149
  - JSX in a client module always compiles for the DOM renderer (`acrylblends/jsx/dom`), whatever the server's `tsconfig.json` says. A file's
@@ -8,6 +8,8 @@
8
8
  | Template | What you get |
9
9
  | --- | --- |
10
10
  | `nodejs` | an Acryl application served with `serve()` from `acrylblends/node-server`; run with Node.js 22.19 or newer |
11
+ | `notes` | a full-stack starter: accounts (scrypt, cookie session), notes in SQLite (`node:sqlite`), validated forms, search, a JSON API with a typed test client, csrf, a test for every route, a client-component counter |
12
+ | `chat` | an AI chat starter: the answer streams token by token from an OpenAI-compatible API (DeepSeek by default, key only from `DEEPSEEK_API_KEY`), a client component with a Stop button that also stops the request to the model, history in SQLite, tests with a mock model |
11
13
  | `bun` (experimental) | an Acryl application with `export default app`, run with `bun` |
12
14
  | `acryl-app` | a Cordis app built from plugins, with an agent that can extend it while it runs (the same app `npx acrylblends init --template agent` creates) |
13
15
 
@@ -47,14 +49,50 @@ bun create acrylblends@latest my-app --template nodejs
47
49
  | Argument | Description | Example |
48
50
  | :-- | :-- | :-- |
49
51
  | `[directory]` | The folder to create. It must not exist or must be empty. Asked for when it is missing. | `my-app` |
50
- | `--template <template>` | One of `nodejs`, `bun` (experimental), `acryl-app`. Skips the template question. | `--template bun` |
51
- | `--install` | Install the dependencies with the package manager after creating the project. | `--install` |
52
+ | `[source]` | A template from outside the package: `github:owner/repo[#ref]`, `@scope/name[@version]` or a packed `.tgz` file. See [Templates from a repository or a package](#templates-from-a-repository-or-a-package). | `github:acme/starter` |
53
+ | `--template <template>` | One of `nodejs`, `notes`, `chat`, `bun` (experimental), `acryl-app`. Skips the template question. | `--template bun` |
54
+ | `--install` | Install the dependencies with the package manager after creating the project. For a template from a source, the install scripts it will run are listed first. | `--install` |
52
55
  | `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
53
56
  | `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |
54
57
  | `--help` | Print the arguments. | `--help` |
55
58
 
56
59
  The templates are inside the package, so creating a project needs no network except for `--install`.
57
60
 
61
+ ## Templates from a repository or a package
62
+
63
+ A second argument after the directory makes the app from someone else's template:
64
+
65
+ ```sh
66
+ npm create acrylblends@latest my-app github:acme/starter # a GitHub repository (the default branch)
67
+ npm create acrylblends@latest my-app github:acme/starter#v1.2 # a tag, branch or commit
68
+ npm create acrylblends@latest my-app @acme/starter # an npm package
69
+ npm create acrylblends@latest my-app ./acme-starter-1.0.0.tgz # a packed template on disk
70
+ ```
71
+
72
+ A template is a folder (a repository, or an npm package) with an `acryl.template.json` at its top:
73
+
74
+ ```json
75
+ {
76
+ "name": "starter",
77
+ "description": "What the app is",
78
+ "plugins": ["desktop"]
79
+ }
80
+ ```
81
+
82
+ `name` and `description` are required and shown when the app is created. `plugins` is optional: library plugins the template needs, which the command lists with the `acrylblends add` line that adds them. A source without the file is refused with a message.
83
+
84
+ What the command does, in order:
85
+
86
+ 1. **Fetches without running anything.** A GitHub source is downloaded as a tarball (never cloned, so no git hook can run). An npm source is fetched with `npm pack --ignore-scripts`. The archive is unpacked into a scratch folder; one with a path that leaves its folder, a symbolic link, more than 5,000 files or more than 50 MB is refused.
87
+ 2. **Reads `acryl.template.json`** and refuses the source if it is missing or malformed.
88
+ 3. **Fills the template in.** `__APP_NAME__`, `__PACKAGE__`, `__CLASS__` and `__RANGE__` in text files are replaced as in the built-in templates, `package.json` gets the app's name, a dependency on `acrylblends` is set to the release this command carries, a `gitignore` file becomes `.gitignore` (npm does not publish a `.gitignore`), `docs/framework/` is added, and so are `AGENTS.md` and `CLAUDE.md` when the template has none of its own.
89
+ 4. **Looks for secrets.** The result is checked with the secret scan the save step of Blend apps uses; a template that holds a key or a password is refused, and the file and line are named (never the value).
90
+ 5. **Creates the folder** only if all of that passed.
91
+
92
+ Nothing of the template is installed or run. If its `package.json` defines `preinstall`, `install`, `postinstall` or `prepare`, the command says so and prints them: `npm install` would run them. Read them first. With `--install` the command prints the list of what will be installed and which scripts will run, then runs the install.
93
+
94
+ To publish your own: put `acryl.template.json` in the repository or package, name the files with the placeholders above, keep a file named `gitignore` instead of `.gitignore`, and keep secrets out.
95
+
58
96
  ## Example flows
59
97
 
60
98
  ### Interactive
@@ -12,8 +12,8 @@ A `json` validation target reads the body only when the request has a JSON `Cont
12
12
 
13
13
  ## Which runtimes are verified?
14
14
 
15
- Node.js. Bun is experimental. The others are listed, as not yet verified, on [Other runtimes](../getting-started/other-runtimes.md).
15
+ Node.js. Bun is experimental. The hosting platforms with an adapter (AWS Lambda, Lambda@Edge, Cloudflare Workers and Pages, Vercel, Netlify, Service Worker) and the ones without are listed on [Other runtimes](../getting-started/other-runtimes.md).
16
16
 
17
17
  ## Where are the parts marked "not yet available"?
18
18
 
19
- Their pages are part of the documentation so that the structure is complete; each starts with a note saying so. They are enabled as they are ported.
19
+ Their pages are part of the documentation so that the structure is complete; each starts with a note saying so. They are enabled as they are built.
@@ -4,7 +4,7 @@ The ConnInfo Helper helps you to get the connection information. For example, yo
4
4
 
5
5
  ## Import
6
6
 
7
- Only the Node.js adapter, `acrylblends/node-server`, is available today. The adapters for the other platforms (Cloudflare Workers, Bun, Vercel, AWS Lambda, Netlify and Lambda@Edge) are **not yet available**; their imports are shown for completeness and are not checked by the docs tests.
7
+ Each adapter has its own `getConnInfo`: `acrylblends/node-server`, `acrylblends/cloudflare-workers`, `acrylblends/vercel`, `acrylblends/aws-lambda`, `acrylblends/netlify`, `acrylblends/lambda-edge` and `acrylblends/bun`. The Bun example is not type-checked by the docs tests, which run without Bun's types.
8
8
 
9
9
  **Cloudflare Workers**
10
10
 
@@ -98,7 +98,7 @@ export interface FileSystemModule {
98
98
 
99
99
  ### Using the adapter for Bun
100
100
 
101
- On Bun, a `toSSG` function is provided by `acrylblends/bun` (not yet available).
101
+ On Bun, a `toSSG` function is provided by `acrylblends/bun`; it writes the files with `Bun.write`.
102
102
 
103
103
  ### Options
104
104
 
@@ -81,6 +81,126 @@ app.get('/sse', async (c) => {
81
81
  })
82
82
  ```
83
83
 
84
+ ## Cancelling work when the client leaves
85
+
86
+ A reader that closes the tab, loses the network or presses a Stop button should not leave your server working for nobody (a request to a paid model, a database scan). There are two signals, and they are not the same:
87
+
88
+ - **`c.req.raw.signal`** is the request's `AbortSignal`. It aborts when the client goes away. Pass it to anything that takes a `signal`, such as `fetch`, and the work stops with the client. This is the one to use for cancelling work.
89
+ - **`stream.onAbort(callback)`** and **`stream.aborted`** belong to the response stream. They report that the *reader of the response* was cancelled. Measured: when you call `app.request()` with a `signal` and abort it, `c.req.raw.signal` aborts and `stream.aborted` stays `false`; when the reader of the response body is cancelled, `stream.onAbort` fires and `c.req.raw.signal` does not. On a real connection the request signal is what fired when a browser aborted its `fetch`. Use `c.req.raw.signal` for the work, and `stream.onAbort` for cleanup of the stream itself.
90
+
91
+ An abort event that has already fired does not fire again, so check `signal.aborted` before you wait for it:
92
+
93
+ ```ts
94
+ const waitForAbort = (signal: AbortSignal) =>
95
+ signal.aborted
96
+ ? Promise.resolve()
97
+ : new Promise<void>((resolve) => signal.addEventListener('abort', () => resolve(), { once: true }))
98
+ ```
99
+
100
+ Keep what you have when the client leaves by saving it in a `finally` block: the stream callback runs to the end whether or not the client is still there.
101
+
102
+ ## Streaming an answer from a model
103
+
104
+ A chat answer that arrives token by token is a `streamSSE` response that reads a streaming upstream. This server route calls an OpenAI-compatible chat completions API (`stream: true`), forwards each piece as an event, and cancels the upstream request when the client leaves. The key comes from the environment and is never written anywhere.
105
+
106
+ ```ts
107
+ import { Acryl } from 'acrylblends'
108
+ import { streamSSE } from 'acrylblends/streaming'
109
+
110
+ /** The pieces of an OpenAI-compatible streaming answer: each `data:` line holds a JSON chunk, and `[DONE]` ends it. */
111
+ async function* modelPieces(messages: { role: string; content: string }[], signal: AbortSignal): AsyncGenerator<string> {
112
+ const key = process.env.DEEPSEEK_API_KEY
113
+ if (!key) throw new Error('DEEPSEEK_API_KEY is not set')
114
+ const base = process.env.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com'
115
+ const response = await fetch(`${base}/chat/completions`, {
116
+ method: 'POST',
117
+ headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
118
+ body: JSON.stringify({ model: process.env.DEEPSEEK_MODEL ?? 'deepseek-chat', messages, stream: true }),
119
+ signal,
120
+ })
121
+ if (!response.ok || !response.body) throw new Error(`the model service answered ${response.status}`)
122
+ const decoder = new TextDecoder()
123
+ let buffer = ''
124
+ for await (const chunk of response.body) {
125
+ buffer += decoder.decode(chunk, { stream: true })
126
+ const lines = buffer.split('\n')
127
+ buffer = lines.pop() ?? ''
128
+ for (const line of lines) {
129
+ if (!line.startsWith('data:')) continue
130
+ const data = line.slice(5).trim()
131
+ if (data === '[DONE]') return
132
+ const piece = (JSON.parse(data) as { choices?: { delta?: { content?: string } }[] }).choices?.[0]?.delta?.content
133
+ if (piece) yield piece
134
+ }
135
+ }
136
+ }
137
+
138
+ const app = new Acryl()
139
+
140
+ app.post('/api/chat', async (c) => {
141
+ const { message } = await c.req.json<{ message: string }>()
142
+ const signal = c.req.raw.signal // aborts when the client goes away
143
+ return streamSSE(c, async (stream) => {
144
+ let answer = ''
145
+ try {
146
+ for await (const piece of modelPieces([{ role: 'user', content: message }], signal)) {
147
+ answer += piece
148
+ // JSON-encode the piece: a piece may contain a newline, which would end an SSE `data:` line.
149
+ await stream.writeSSE({ event: 'token', data: JSON.stringify(piece) })
150
+ }
151
+ await stream.writeSSE({ event: 'done', data: '{}' })
152
+ } catch (error) {
153
+ if (!signal.aborted) await stream.writeSSE({ event: 'error', data: JSON.stringify('The model could not answer.') })
154
+ } finally {
155
+ console.log(`kept ${answer.length} characters`) // save what arrived, also when the client pressed Stop
156
+ }
157
+ })
158
+ })
159
+ ```
160
+
161
+ ## Reading a POST event stream in the browser
162
+
163
+ `EventSource` can only send a GET request. For a POST (a chat message), read the response body yourself; this function calls `on` for each event as it arrives:
164
+
165
+ ```ts
166
+ async function readEvents(body: ReadableStream<Uint8Array>, on: (event: string, data: string) => void): Promise<void> {
167
+ const reader = body.getReader()
168
+ const decoder = new TextDecoder()
169
+ let buffer = ''
170
+ for (;;) {
171
+ const { done, value } = await reader.read()
172
+ if (done) return
173
+ // Line endings may be CRLF; a \r at the end of a chunk is completed by the next chunk, so normalise the whole buffer.
174
+ buffer = (buffer + decoder.decode(value, { stream: true })).replaceAll('\r\n', '\n')
175
+ const blocks = buffer.split('\n\n')
176
+ buffer = blocks.pop() ?? ''
177
+ for (const block of blocks) {
178
+ let event = 'message'
179
+ const data: string[] = []
180
+ for (const line of block.split('\n')) {
181
+ if (line.startsWith('event:')) event = line.slice(6).trim()
182
+ else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')) // the SSE spec strips one leading space only
183
+ }
184
+ on(event, data.join('\n'))
185
+ }
186
+ }
187
+ }
188
+
189
+ const controller = new AbortController() // controller.abort() is the Stop button
190
+ const response = await fetch('/api/chat', {
191
+ method: 'POST',
192
+ headers: { 'content-type': 'application/json' },
193
+ body: JSON.stringify({ message: 'Hello' }),
194
+ signal: controller.signal,
195
+ })
196
+ let answer = ''
197
+ await readEvents(response.body!, (event, data) => {
198
+ if (event === 'token') answer += JSON.parse(data) as string
199
+ })
200
+ ```
201
+
202
+ A complete chat component built on this is in the `chat` template of `create-acrylblends` (`npm create acrylblends@latest my-chat -- --template chat`).
203
+
84
204
  ## Error Handling
85
205
 
86
206
  The third argument of the streaming helper is an error handler.
@@ -1,11 +1,11 @@
1
1
  # WebSocket Helper
2
2
 
3
3
  WebSocket Helper is a helper for server-side WebSockets in Acryl applications.
4
- The Node.js adapter is available; the others are not yet available.
4
+ The Node.js, Cloudflare Workers and Bun adapters are available.
5
5
 
6
6
  ## Import
7
7
 
8
- Only the Node.js adapter, `acrylblends/node-server`, is available today. The adapters for the other platforms (Cloudflare Workers, Bun, Vercel, AWS Lambda, Netlify and Lambda@Edge) are **not yet available**; their imports are shown for completeness and are not checked by the docs tests.
8
+ The Node.js adapter (`acrylblends/node-server`), the Cloudflare Workers adapter (`acrylblends/cloudflare-workers`) and the Bun adapter (`acrylblends/bun`) provide `upgradeWebSocket`. The other platforms have no WebSocket support in their adapters. The Bun adapter is checked on Bun in the framework's release check; its examples below are not type-checked by the docs tests, which run without Bun's types.
9
9
 
10
10
  **Cloudflare Workers**
11
11
 
@@ -31,7 +31,7 @@ app.use(
31
31
  app.get('/', (c) => c.text('Acryl!'))
32
32
  ```
33
33
 
34
- Pass the `getConninfo` from the [ConnInfo helper](../../helpers/conninfo.md) appropriate for your environment as the first argument of `ipRestriction`. For a runtime whose adapter is not yet available there is no `getConnInfo` to pass yet.
34
+ Pass the `getConninfo` from the [ConnInfo helper](../../helpers/conninfo.md) appropriate for your environment as the first argument of `ipRestriction`. Every adapter has one (`acrylblends/bun`, `acrylblends/aws-lambda`, `acrylblends/node-server` and the others).
35
35
 
36
36
  ## Rules
37
37
 
@@ -2,8 +2,8 @@
2
2
  "source": {
3
3
  "repo": "acryldev/acryl",
4
4
  "path": "docs/framework",
5
- "commit": "cdc083e1bbaedaeafa7494fe646bdb202ce86d09"
5
+ "commit": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
6
6
  },
7
- "files": 91,
8
- "digest": "sha256:964e5ff58d487ce53394469d359a251265a3ef093354f55b6b4c47c55051774b"
7
+ "files": 98,
8
+ "digest": "sha256:396f882ac7b612455edc59961c52472fadc5f95ea1a778208e7edd860e4e6727"
9
9
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-acrylblends",
3
- "version": "0.2.2",
3
+ "version": "0.2.4",
4
4
  "description": "Create an Acryl app: npm create acrylblends@latest",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -37,7 +37,8 @@
37
37
  "scaffold"
38
38
  ],
39
39
  "dependencies": {
40
- "acrylblends": "^0.7.2"
40
+ "acrylblends": "^0.7.4",
41
+ "@webboxes/app-persistence": "0.1.1"
41
42
  },
42
43
  "publishConfig": {
43
44
  "access": "public"
@@ -0,0 +1,5 @@
1
+ node_modules/
2
+ *.db
3
+ *.db-*
4
+ .acrylblends/
5
+ dist/
@@ -0,0 +1,23 @@
1
+ {
2
+ "name": "__APP_NAME__",
3
+ "version": "0.1.0",
4
+ "private": true,
5
+ "type": "module",
6
+ "engines": {
7
+ "node": ">=22.19.0"
8
+ },
9
+ "scripts": {
10
+ "dev": "node --watch --import acrylblends/node-server/register src/index.ts",
11
+ "start": "node --import acrylblends/node-server/register src/index.ts",
12
+ "test": "node --import acrylblends/node-server/register --test \"test/**/*.test.{ts,tsx}\"",
13
+ "check": "tsc --noEmit && tsc --noEmit -p src/client",
14
+ "build": "acrylblends build-client"
15
+ },
16
+ "dependencies": {
17
+ "__PACKAGE__": "__RANGE__",
18
+ "typescript": "6.0.3"
19
+ },
20
+ "devDependencies": {
21
+ "@types/node": "^24.0.0"
22
+ }
23
+ }
@@ -0,0 +1,6 @@
1
+ import { createApp } from './chat-app.ts'
2
+ import { openDb } from './db.ts'
3
+
4
+ export const db = openDb()
5
+
6
+ export default createApp(db)
@@ -0,0 +1,96 @@
1
+ import { __CLASS__ } from '__PACKAGE__'
2
+ import { clientModules } from '__PACKAGE__/node-server'
3
+ import { type StandardSchema, schemaValidator } from '__PACKAGE__/schema-validator'
4
+ import { streamSSE } from '__PACKAGE__/streaming'
5
+ import type { DatabaseSync } from 'node:sqlite'
6
+ import { chatStore, openDb } from './db.ts'
7
+ import { type Llm, openAiCompatible } from './llm.ts'
8
+ import { chatPage } from './page.tsx'
9
+
10
+ interface ChatInput {
11
+ message: string
12
+ conversation?: number
13
+ }
14
+
15
+ const ChatSchema: StandardSchema<ChatInput> = {
16
+ '~standard': {
17
+ validate: (value) => {
18
+ const input = (value ?? {}) as Record<string, unknown>
19
+ const message = typeof input.message === 'string' ? input.message.trim() : ''
20
+ const issues = []
21
+ if (message === '') issues.push({ message: 'Write a message.', path: ['message'] })
22
+ else if (message.length > 4000)
23
+ issues.push({ message: 'The message is at most 4000 characters.', path: ['message'] })
24
+ if (input.conversation !== undefined && !Number.isInteger(input.conversation))
25
+ issues.push({ message: 'The conversation is a number.', path: ['conversation'] })
26
+ return issues.length > 0
27
+ ? { issues }
28
+ : { value: { message, conversation: input.conversation as number | undefined } }
29
+ },
30
+ },
31
+ }
32
+
33
+ export function createApp(db: DatabaseSync = openDb(), llm: Llm = openAiCompatible) {
34
+ const store = chatStore(db)
35
+ const app = new __CLASS__()
36
+
37
+ app.get('/', (c) => {
38
+ const id = Number(c.req.query('c'))
39
+ const current = Number.isInteger(id) ? store.conversation(id) : undefined
40
+ return c.html(
41
+ chatPage(store.conversations(), current, current ? store.messages(current.id) : []),
42
+ )
43
+ })
44
+
45
+ app.get('/api/conversations', (c) => c.json({ conversations: store.conversations() }))
46
+ app.get('/api/conversations/:id', (c) => {
47
+ const id = Number(c.req.param('id'))
48
+ const conversation = store.conversation(id)
49
+ return conversation
50
+ ? c.json({ conversation, messages: store.messages(id) })
51
+ : c.json({ error: 'No such conversation.' }, 404)
52
+ })
53
+ app.delete('/api/conversations/:id', (c) =>
54
+ store.remove(Number(c.req.param('id')))
55
+ ? c.json({ ok: true })
56
+ : c.json({ error: 'No such conversation.' }, 404),
57
+ )
58
+
59
+ // The answer streams as Server-Sent Events: `meta` (the conversation id), then one `token` per piece, then `done`, or `error`.
60
+ // The request's signal aborts when the client goes away (the Stop button, a closed tab); it is passed to the model call so the upstream request stops too.
61
+ app.post('/api/chat', schemaValidator('json', ChatSchema), (c) => {
62
+ const { message, conversation } = c.req.valid('json')
63
+ const known = conversation === undefined ? undefined : store.conversation(conversation)
64
+ if (conversation !== undefined && !known) return c.json({ error: 'No such conversation.' }, 404)
65
+ const id = known?.id ?? store.start(message)
66
+ store.add(id, 'user', message)
67
+ const history = store.messages(id).map(({ role, content }) => ({ role, content }))
68
+ const signal = c.req.raw.signal
69
+ return streamSSE(c, async (stream) => {
70
+ let answer = ''
71
+ await stream.writeSSE({ event: 'meta', data: JSON.stringify({ conversation: id }) })
72
+ try {
73
+ for await (const piece of llm(history, signal)) {
74
+ answer += piece
75
+ await stream.writeSSE({ event: 'token', data: JSON.stringify(piece) })
76
+ }
77
+ await stream.writeSSE({ event: 'done', data: '{}' })
78
+ } catch (error) {
79
+ if (!signal.aborted) {
80
+ console.error(error)
81
+ // The reason stays in the log; the page gets a plain message.
82
+ await stream.writeSSE({
83
+ event: 'error',
84
+ data: JSON.stringify('The model could not answer. Try again.'),
85
+ })
86
+ }
87
+ } finally {
88
+ // What arrived is kept, also when the reader pressed Stop.
89
+ if (answer !== '') store.add(id, 'assistant', answer)
90
+ }
91
+ })
92
+ })
93
+
94
+ app.route('/client', clientModules({ root: 'src/client', compiled: 'dist/client' }))
95
+ return app
96
+ }
@@ -0,0 +1,115 @@
1
+ import { render, useRef, useState } from '__PACKAGE__/jsx/dom'
2
+
3
+ /** Read a Server-Sent Events body: calls `on(event, data)` for each event as it arrives. (EventSource only does GET, and this is a POST.) */
4
+ async function readEvents(
5
+ body: ReadableStream<Uint8Array>,
6
+ on: (event: string, data: string) => void,
7
+ ): Promise<void> {
8
+ const reader = body.getReader()
9
+ const decoder = new TextDecoder()
10
+ let buffer = ''
11
+ for (;;) {
12
+ const { done, value } = await reader.read()
13
+ if (done) return
14
+ // Line endings may be CRLF; a \r at the end of a chunk is completed by the next chunk, so normalise the whole buffer.
15
+ buffer = (buffer + decoder.decode(value, { stream: true })).replaceAll('\r\n', '\n')
16
+ const blocks = buffer.split('\n\n')
17
+ buffer = blocks.pop() ?? ''
18
+ for (const block of blocks) {
19
+ let event = 'message'
20
+ const data: string[] = []
21
+ for (const line of block.split('\n')) {
22
+ if (line.startsWith('event:')) event = line.slice(6).trim()
23
+ else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')) // the SSE spec strips one leading space only
24
+ }
25
+ on(event, data.join('\n'))
26
+ }
27
+ }
28
+ }
29
+
30
+ const Chat = ({ start }: { start: number | undefined }) => {
31
+ const [text, setText] = useState('')
32
+ const [asked, setAsked] = useState('')
33
+ const [answer, setAnswer] = useState('')
34
+ const [error, setError] = useState('')
35
+ const [busy, setBusy] = useState(false)
36
+ const conversation = useRef<number | undefined>(start)
37
+ const controller = useRef<AbortController | undefined>(undefined)
38
+
39
+ const send = async (event: Event) => {
40
+ event.preventDefault()
41
+ const message = text.trim()
42
+ if (message === '' || busy) return
43
+ setAsked(message)
44
+ setAnswer('')
45
+ setError('')
46
+ setText('')
47
+ setBusy(true)
48
+ controller.current = new AbortController()
49
+ try {
50
+ const response = await fetch('/api/chat', {
51
+ method: 'POST',
52
+ headers: { 'content-type': 'application/json' },
53
+ body: JSON.stringify({ message, conversation: conversation.current }),
54
+ signal: controller.current.signal,
55
+ })
56
+ if (!response.ok || !response.body) {
57
+ const problem = (await response.json().catch(() => ({}))) as {
58
+ issues?: { message: string }[]
59
+ error?: string
60
+ }
61
+ setError(problem.issues?.[0]?.message ?? problem.error ?? 'The message was not accepted.')
62
+ return
63
+ }
64
+ let soFar = ''
65
+ await readEvents(response.body, (name, data) => {
66
+ if (name === 'meta') {
67
+ conversation.current = (JSON.parse(data) as { conversation: number }).conversation
68
+ history.replaceState(null, '', `/?c=${conversation.current}`)
69
+ } else if (name === 'token') {
70
+ soFar += JSON.parse(data) as string
71
+ setAnswer(soFar)
72
+ } else if (name === 'error') setError(JSON.parse(data) as string)
73
+ })
74
+ } catch (caught) {
75
+ if (!(caught instanceof DOMException && caught.name === 'AbortError'))
76
+ setError('The connection was lost.')
77
+ } finally {
78
+ setBusy(false)
79
+ }
80
+ }
81
+
82
+ return (
83
+ <div>
84
+ {asked !== '' && <p class="row user">{asked}</p>}
85
+ {answer !== '' && <p class="row">{answer}</p>}
86
+ {error !== '' && (
87
+ <p class="row error" role="alert">
88
+ {error}
89
+ </p>
90
+ )}
91
+ <form onSubmit={send}>
92
+ <textarea
93
+ rows={3}
94
+ value={text}
95
+ placeholder="Ask something"
96
+ onInput={(e) => setText((e.target as HTMLTextAreaElement).value)}
97
+ />
98
+ <p>
99
+ <button type="submit" disabled={busy}>
100
+ Send
101
+ </button>{' '}
102
+ {busy && (
103
+ <button type="button" onClick={() => controller.current?.abort()}>
104
+ Stop
105
+ </button>
106
+ )}
107
+ </p>
108
+ </form>
109
+ </div>
110
+ )
111
+ }
112
+
113
+ const root = document.getElementById('chat')!
114
+ const start = root.dataset.conversation ? Number(root.dataset.conversation) : undefined
115
+ render(<Chat start={start} />, root)
@@ -0,0 +1,15 @@
1
+ {
2
+ "compilerOptions": {
3
+ "target": "ES2024",
4
+ "lib": ["ES2024", "DOM", "DOM.Iterable"],
5
+ "module": "NodeNext",
6
+ "moduleResolution": "NodeNext",
7
+ "strict": true,
8
+ "noEmit": true,
9
+ "allowImportingTsExtensions": true,
10
+ "jsx": "react-jsx",
11
+ "jsxImportSource": "__PACKAGE__/jsx/dom",
12
+ "types": []
13
+ },
14
+ "include": ["**/*.ts", "**/*.tsx"]
15
+ }