create-acrylblends 0.2.4 → 0.2.6
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.
- package/dist/index.js +10 -7
- package/dist/index.js.map +1 -1
- package/docs/framework/README.md +2 -1
- package/docs/framework/UPSTREAM.md +1 -1
- package/docs/framework/getting-started/deploy.md +5 -5
- package/docs/framework/getting-started/service-worker.md +5 -3
- package/docs/framework/guides/create-acrylblends.md +2 -2
- package/docs/framework/guides/data.md +237 -0
- package/docs/framework/guides/forms-and-sessions.md +34 -30
- package/docs/framework/upstream.json +3 -3
- package/package.json +2 -2
- package/templates/chat/gitignore +3 -2
- package/templates/chat/migrations/001-chat.sql +12 -0
- package/templates/chat/package.json +5 -2
- package/templates/chat/src/app.ts +4 -2
- package/templates/chat/src/chat-app.ts +22 -18
- package/templates/chat/src/db.ts +30 -36
- package/templates/chat/src/index.ts +9 -4
- package/templates/chat/test/chat.test.ts +21 -9
- package/templates/chat/test/server.test.ts +1 -1
- package/templates/nodejs/package.json +2 -2
- package/templates/notes/gitignore +3 -2
- package/templates/notes/migrations/001-notes.sql +18 -0
- package/templates/notes/package.json +5 -2
- package/templates/notes/src/app.ts +4 -3
- package/templates/notes/src/auth.ts +21 -19
- package/templates/notes/src/db.ts +40 -50
- package/templates/notes/src/index.ts +9 -4
- package/templates/notes/src/notes-app.ts +35 -29
- package/templates/notes/test/notes.test.ts +27 -20
- package/templates/notes/test/server.test.ts +1 -1
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
# Data: the `db` port, migrations and choosing a store
|
|
2
|
+
|
|
3
|
+
An app that keeps records (users, notes, orders) keeps them in a SQL database, and reaches it through one small interface, `db`. Handlers and
|
|
4
|
+
stores take a `Db` as an argument and never import a driver, so the file or server behind it can change without touching them. SQLite is the
|
|
5
|
+
provider today; a Postgres provider (Postgres or Supabase through `DATABASE_URL`) is planned and serves the same interface.
|
|
6
|
+
|
|
7
|
+
## Choosing
|
|
8
|
+
|
|
9
|
+
| The app | Use | State |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| Normal web or desktop app, users, lists, orders | `db` with SQLite (the `notes` and `chat` templates) | available |
|
|
12
|
+
| Hosted, many users | `db` with Postgres or Supabase | planned |
|
|
13
|
+
| Tiny, one person, a few screens | `kv`, named JSON documents with no SQL | planned |
|
|
14
|
+
| Agents or long tasks that must survive a restart | `durable`, in the same database as `db` | planned |
|
|
15
|
+
|
|
16
|
+
Start with `db`. It is the only one of the four you can use today, and SQL is what people and coding agents already know.
|
|
17
|
+
|
|
18
|
+
## Open the database
|
|
19
|
+
|
|
20
|
+
`openDb` from `acrylblends/db/sqlite` opens one SQLite file, applies your migrations, and returns the database next to the function that closes it:
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import { openDb } from 'acrylblends/db/sqlite'
|
|
24
|
+
|
|
25
|
+
const { db, close } = await openDb({ path: 'data/app.sqlite', migrations: 'migrations' })
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
- `path` is the file, created with its folder when it does not exist. `':memory:'` opens a database that lives and dies with the process, which
|
|
29
|
+
is what tests use.
|
|
30
|
+
- `migrations` is a folder of numbered SQL files, relative to the working directory (see below).
|
|
31
|
+
- `db` is the port: `exec`, `run`, `get`, `all` and `transaction`, every one returning a promise. It has no `close`, so no part of the app can
|
|
32
|
+
close the database another part is using. `close` is the opener's: call it once, when the process stops.
|
|
33
|
+
|
|
34
|
+
Pass `db` to the code that needs it. Nothing opens the database at import time, so importing a module never creates a file:
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import type { Db } from 'acrylblends/db'
|
|
38
|
+
|
|
39
|
+
export function notesStore(db: Db) {
|
|
40
|
+
return {
|
|
41
|
+
async titles(userId: number): Promise<string[]> {
|
|
42
|
+
const rows = await db.all<{ title: string }>(
|
|
43
|
+
'SELECT title FROM notes WHERE user_id = ? ORDER BY updated_at DESC',
|
|
44
|
+
userId,
|
|
45
|
+
)
|
|
46
|
+
return rows.map((row) => row.title)
|
|
47
|
+
},
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Migrations
|
|
53
|
+
|
|
54
|
+
The shape of the database lives in `migrations/`, one numbered file per change:
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
migrations/
|
|
58
|
+
001-notes.sql
|
|
59
|
+
002-tags.sql
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
```sql
|
|
63
|
+
-- migrations/002-tags.sql
|
|
64
|
+
CREATE TABLE tags (
|
|
65
|
+
note_id INTEGER NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
|
|
66
|
+
name TEXT NOT NULL,
|
|
67
|
+
PRIMARY KEY (note_id, name)
|
|
68
|
+
);
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
- Files are named `NNN-name.sql` and numbered from 1 with no gaps. A gap, a repeated number or a file named otherwise stops the app at start
|
|
72
|
+
with a message that names it.
|
|
73
|
+
- On start, `openDb` applies the files that have not run yet, in order, **in one transaction**: a failing file leaves the database as it was.
|
|
74
|
+
- The version is recorded in the `_migrations` table. Do not touch that table.
|
|
75
|
+
- **Never edit a file that has been applied.** A database that already ran `001` does not run it again, so an edit changes only new databases.
|
|
76
|
+
To change a table, add the next file (`ALTER TABLE notes ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0`).
|
|
77
|
+
- A database whose version is newer than your files (an older build started on newer data) is refused. The app does not start.
|
|
78
|
+
- A migration is plain SQL. Put the data change next to the shape change in the same file when they belong together.
|
|
79
|
+
|
|
80
|
+
To add a feature that needs a column or a table, the work is always the same three steps: write the next migration, change the store that
|
|
81
|
+
reads and writes it, and change the handlers and views that use the store.
|
|
82
|
+
|
|
83
|
+
## Reading and writing
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
// One row, or undefined.
|
|
87
|
+
const note = await db.get<Note>('SELECT * FROM notes WHERE id = ? AND user_id = ?', id, userId)
|
|
88
|
+
|
|
89
|
+
// Many rows.
|
|
90
|
+
const notes = await db.all<Note>('SELECT * FROM notes WHERE user_id = ? ORDER BY id', userId)
|
|
91
|
+
|
|
92
|
+
// A write: how many rows it changed.
|
|
93
|
+
const { changes } = await db.run('DELETE FROM notes WHERE id = ? AND user_id = ?', id, userId)
|
|
94
|
+
if (changes === 0) return c.notFound()
|
|
95
|
+
|
|
96
|
+
// A write that gives back the row it made.
|
|
97
|
+
const created = await db.get<Note>(
|
|
98
|
+
'INSERT INTO notes (user_id, title, body, updated_at) VALUES (?, ?, ?, ?) RETURNING *',
|
|
99
|
+
userId, title, body, new Date().toISOString(),
|
|
100
|
+
)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
- Values go in as **bindings** after the SQL (`?`, in order), never inside the SQL text. This is what keeps a title like `'); DROP TABLE notes;--`
|
|
104
|
+
a title. A binding is `null`, a number, a bigint, a string or a `Uint8Array`; turn a boolean into `0` or `1` and a date into
|
|
105
|
+
`toISOString()` yourself.
|
|
106
|
+
- `exec(sql)` runs SQL text with no bindings, and may hold several statements. Use it for setup, not for user input.
|
|
107
|
+
- `db.get` has no `lastInsertRowid`. To get the new row or its id, end the insert with `RETURNING *` or `RETURNING id`.
|
|
108
|
+
- `changes` is what makes "update only if nothing changed meanwhile" possible: `UPDATE ... WHERE id = ? AND version = ?` and check `changes`.
|
|
109
|
+
|
|
110
|
+
## Transactions
|
|
111
|
+
|
|
112
|
+
Changes that must happen together go in `transaction`. Everything inside goes through the handle the callback receives:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
await db.transaction(async (tx) => {
|
|
116
|
+
const { changes } = await tx.run('UPDATE accounts SET balance = balance - ? WHERE id = ? AND balance >= ?', amount, from, amount)
|
|
117
|
+
if (changes === 0) throw new Error('not enough money')
|
|
118
|
+
await tx.run('UPDATE accounts SET balance = balance + ? WHERE id = ?', amount, to)
|
|
119
|
+
})
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
- If the callback throws, the transaction is rolled back and `transaction` rejects with that same error.
|
|
123
|
+
- Other calls, and other transactions, wait until the transaction finishes. So **never call `db` itself inside the callback**, only `tx`: that
|
|
124
|
+
call would wait for a transaction that waits for it, and never return.
|
|
125
|
+
- The handle stops working when the callback settles. Do not keep it.
|
|
126
|
+
|
|
127
|
+
## Writing SQL that moves to Postgres
|
|
128
|
+
|
|
129
|
+
The Postgres provider is not released yet, and it will serve the same interface. SQL that stays inside this list runs on both:
|
|
130
|
+
|
|
131
|
+
- Placeholders are `?` on every provider.
|
|
132
|
+
- Use `RETURNING` to get a new row, not a driver-specific "last id".
|
|
133
|
+
- Keep dates as ISO 8601 text (`new Date().toISOString()`), and booleans as `0` and `1`.
|
|
134
|
+
- Keep identifiers lower case and unquoted.
|
|
135
|
+
- `INTEGER PRIMARY KEY` makes an automatically numbered key in SQLite. The identity column of another database is spelled differently, so keep key
|
|
136
|
+
definitions in migration files, where a different provider's version of the file can differ.
|
|
137
|
+
- SQLite lets a column hold a value of another type than it declares; most other databases do not. Store what you declare.
|
|
138
|
+
|
|
139
|
+
## In tests
|
|
140
|
+
|
|
141
|
+
A test opens its own database in memory, with the same migrations as production, and closes it:
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
import { afterEach, beforeEach, expect, test } from 'vitest'
|
|
145
|
+
import { openDb } from 'acrylblends/db/sqlite'
|
|
146
|
+
import { notesStore } from './db.ts'
|
|
147
|
+
|
|
148
|
+
let close: () => Promise<void>
|
|
149
|
+
let store: ReturnType<typeof notesStore>
|
|
150
|
+
|
|
151
|
+
beforeEach(async () => {
|
|
152
|
+
const opened = await openDb({ path: ':memory:', migrations: 'migrations' })
|
|
153
|
+
close = opened.close
|
|
154
|
+
store = notesStore(opened.db)
|
|
155
|
+
})
|
|
156
|
+
afterEach(() => close())
|
|
157
|
+
|
|
158
|
+
test('a new store has no notes', async () => {
|
|
159
|
+
expect(await store.titles(1)).toEqual([])
|
|
160
|
+
})
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## In production
|
|
164
|
+
|
|
165
|
+
Open the database once at start, serve, and close it when the process is told to stop, after the server has stopped taking requests:
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
import { serve } from 'acrylblends/node-server'
|
|
169
|
+
import { openDb } from 'acrylblends/db/sqlite'
|
|
170
|
+
import { createApp } from './app.ts'
|
|
171
|
+
|
|
172
|
+
const { db, close } = await openDb({ path: process.env.DATABASE_FILE ?? 'data/app.sqlite', migrations: 'migrations' })
|
|
173
|
+
const server = serve({ fetch: createApp(db).fetch, port: Number(process.env.PORT ?? 3000) })
|
|
174
|
+
|
|
175
|
+
process.once('SIGTERM', async () => {
|
|
176
|
+
server.close()
|
|
177
|
+
await close()
|
|
178
|
+
})
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
`close` waits for the calls and the transaction that are running, flushes the write-ahead log into the main file, and releases the file, so a
|
|
182
|
+
copy of `data/app.sqlite` made afterwards is complete. Keep the file on a disk that outlives a deploy; on a host with only an ephemeral disk the
|
|
183
|
+
data goes with the machine.
|
|
184
|
+
|
|
185
|
+
## Why the database is opened in one place
|
|
186
|
+
|
|
187
|
+
Only one file of an app opens the database: the **opener** (`src/db.ts` in the templates). Every other file receives a `Db` as an argument and
|
|
188
|
+
imports its type from `acrylblends/db`. Nothing outside the opener imports `node:sqlite`, `pg`, `postgres`, `@electric-sql/pglite` or another
|
|
189
|
+
driver, or `acrylblends/db/sqlite` itself.
|
|
190
|
+
|
|
191
|
+
Why it matters:
|
|
192
|
+
|
|
193
|
+
- **Changing the database is one file.** Moving from SQLite to Postgres changes what the opener calls, and no route, store or test.
|
|
194
|
+
- **A test opens its own database.** Code that opens a database by itself cannot be given an in-memory one, and a test that reaches the real file
|
|
195
|
+
breaks the next one.
|
|
196
|
+
- **There is one place to close it.** The code that opened a database closes it; the port has no `close`, so a route cannot do it by mistake.
|
|
197
|
+
- **An agent that adds a feature keeps the shape.** A coding agent asked for "tags" writes a migration and a store function, and has no reason to
|
|
198
|
+
reach for a driver when the interface is in front of it.
|
|
199
|
+
|
|
200
|
+
The rule is checked, not hoped for. The app names its opener once, in `package.json`:
|
|
201
|
+
|
|
202
|
+
```json
|
|
203
|
+
{
|
|
204
|
+
"acryl": { "opener": "src/db.ts" }
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
`acrylblends check-deps` reads every `.ts`, `.tsx` and `.js` file in `src/`, `test/`, `tests/` and `extensions/`, and fails when a file other than
|
|
209
|
+
the opener imports a database driver, an opener such as `acrylblends/db/sqlite` or `acryl-db-sqlite`, or (outside `src/plugins/desktop`) `electron`.
|
|
210
|
+
It names the file and the line:
|
|
211
|
+
|
|
212
|
+
```
|
|
213
|
+
src/routes.ts:3: "node:sqlite" is a database driver; take a Db (import type { Db } from "acrylblends/db") as an argument and let src/db.ts open the database
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
The `notes` and `chat` templates run it in `npm test` and `npm run check`. List more than one opener as an array (`"opener": ["src/db.ts", "src/app.ts"]`).
|
|
217
|
+
In a Blend app, `acrylblends add db` declares `src/app.ts`, where the provider is mounted, and a plugin that declares `inject: ['db']` must not import
|
|
218
|
+
`acryl-db-sqlite`: it receives `ctx.db`.
|
|
219
|
+
|
|
220
|
+
## In a Cordis app
|
|
221
|
+
|
|
222
|
+
An ACRYL app gets the same interface as a service. The `acryl-db-sqlite` plugin row opens the file (by default `data.sqlite` in the app home),
|
|
223
|
+
applies the `migrations` folder, and provides `db`; a plugin declares `inject: ['db']` and imports the types only:
|
|
224
|
+
|
|
225
|
+
```ts
|
|
226
|
+
import type { Context } from '@deepseek-ai/cordis'
|
|
227
|
+
import type {} from 'acryl-db'
|
|
228
|
+
|
|
229
|
+
export const name = 'notes'
|
|
230
|
+
export const inject = ['db']
|
|
231
|
+
|
|
232
|
+
export function apply(ctx: Context) {
|
|
233
|
+
void ctx.db.run('INSERT INTO notes (title) VALUES (?)', 'first')
|
|
234
|
+
}
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
The plugin never imports a driver, so replacing the SQLite row by another provider is a change to the configuration.
|
|
@@ -3,31 +3,34 @@
|
|
|
3
3
|
This page shows the parts a small multi-user app needs, in the order an app uses them: a database, passwords, a cookie session, HTML forms with server-side validation, and a JSON API that shares the same rules.
|
|
4
4
|
It is the shape of a "Notes" app built from these docs alone (sign up, log in, create, edit, delete and search notes, a typed test client for the API).
|
|
5
5
|
|
|
6
|
-
## A database with `
|
|
7
|
-
|
|
8
|
-
Node.js 22.19 and later include SQLite, so there is nothing to install
|
|
6
|
+
## A database with the `db` port
|
|
7
|
+
|
|
8
|
+
`openDb` from `acrylblends/db/sqlite` opens a SQLite file (Node.js 22.19 and later include SQLite, so there is nothing to install), applies the SQL files in `migrations/`, and returns `{ db, close }`.
|
|
9
|
+
Every call on `db` returns a promise, so `await` it. The [data guide](data.md) has the whole story: migrations, transactions, tests and shutdown.
|
|
10
|
+
|
|
11
|
+
```sql
|
|
12
|
+
-- migrations/001-notes.sql
|
|
13
|
+
CREATE TABLE users (
|
|
14
|
+
id INTEGER PRIMARY KEY,
|
|
15
|
+
email TEXT NOT NULL UNIQUE,
|
|
16
|
+
password_hash TEXT NOT NULL
|
|
17
|
+
);
|
|
18
|
+
|
|
19
|
+
CREATE TABLE sessions (
|
|
20
|
+
token TEXT PRIMARY KEY,
|
|
21
|
+
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE
|
|
22
|
+
);
|
|
23
|
+
```
|
|
9
24
|
|
|
10
25
|
```ts
|
|
11
|
-
import {
|
|
12
|
-
|
|
13
|
-
export function
|
|
14
|
-
|
|
15
|
-
db.exec(`
|
|
16
|
-
CREATE TABLE IF NOT EXISTS users (
|
|
17
|
-
id INTEGER PRIMARY KEY,
|
|
18
|
-
email TEXT NOT NULL UNIQUE,
|
|
19
|
-
password_hash TEXT NOT NULL
|
|
20
|
-
);
|
|
21
|
-
CREATE TABLE IF NOT EXISTS sessions (
|
|
22
|
-
token TEXT PRIMARY KEY,
|
|
23
|
-
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE
|
|
24
|
-
);
|
|
25
|
-
`)
|
|
26
|
-
return db
|
|
26
|
+
import { openDb } from 'acrylblends/db/sqlite'
|
|
27
|
+
|
|
28
|
+
export function openNotesDb(path = process.env.NOTES_DB ?? 'data/notes.sqlite') {
|
|
29
|
+
return openDb({ path, migrations: 'migrations' })
|
|
27
30
|
}
|
|
28
31
|
```
|
|
29
32
|
|
|
30
|
-
Take the database as an argument (`createApp(db)`) instead of opening it at import time. A test then
|
|
33
|
+
Take the database as an argument (`createApp(db)`) instead of opening it at import time. A test then opens `openNotesDb(':memory:')`, and importing the app module does not create a file.
|
|
31
34
|
|
|
32
35
|
## Passwords with `node:crypto`
|
|
33
36
|
|
|
@@ -63,20 +66,21 @@ import { Acryl } from 'acrylblends'
|
|
|
63
66
|
import { createMiddleware } from 'acrylblends/factory'
|
|
64
67
|
import { deleteCookie, getCookie, setCookie } from 'acrylblends/cookie'
|
|
65
68
|
import { randomBytes } from 'node:crypto'
|
|
66
|
-
import type {
|
|
69
|
+
import type { Db } from 'acrylblends/db'
|
|
67
70
|
|
|
68
71
|
type Env = { Variables: { user: { id: number; email: string } } }
|
|
69
72
|
|
|
70
|
-
export function createApp(db:
|
|
73
|
+
export function createApp(db: Db) {
|
|
71
74
|
const userFor = (token: string | undefined) =>
|
|
72
75
|
token
|
|
73
|
-
? (
|
|
74
|
-
|
|
75
|
-
|
|
76
|
+
? db.get<{ id: number; email: string }>(
|
|
77
|
+
'SELECT users.id AS id, users.email AS email FROM sessions JOIN users ON users.id = sessions.user_id WHERE token = ?',
|
|
78
|
+
token
|
|
79
|
+
)
|
|
76
80
|
: undefined
|
|
77
81
|
|
|
78
82
|
const requireUser = createMiddleware<Env>(async (c, next) => {
|
|
79
|
-
const user = userFor(getCookie(c, 'sid'))
|
|
83
|
+
const user = await userFor(getCookie(c, 'sid'))
|
|
80
84
|
if (!user) return c.redirect('/login')
|
|
81
85
|
c.set('user', user)
|
|
82
86
|
await next()
|
|
@@ -87,16 +91,16 @@ export function createApp(db: DatabaseSync) {
|
|
|
87
91
|
app.use('/notes/*', requireUser)
|
|
88
92
|
app.get('/notes', (c) => c.text(`Hello ${c.get('user').email}`))
|
|
89
93
|
|
|
90
|
-
app.post('/login-example', (c) => {
|
|
94
|
+
app.post('/login-example', async (c) => {
|
|
91
95
|
const token = randomBytes(32).toString('hex')
|
|
92
|
-
db.
|
|
96
|
+
await db.run('INSERT INTO sessions (token, user_id) VALUES (?, ?)', token, 1)
|
|
93
97
|
setCookie(c, 'sid', token, { path: '/', httpOnly: true, sameSite: 'Lax', maxAge: 60 * 60 * 24 * 30 })
|
|
94
98
|
return c.redirect('/notes', 303)
|
|
95
99
|
})
|
|
96
100
|
|
|
97
|
-
app.post('/logout', (c) => {
|
|
101
|
+
app.post('/logout', async (c) => {
|
|
98
102
|
const token = getCookie(c, 'sid')
|
|
99
|
-
if (token) db.
|
|
103
|
+
if (token) await db.run('DELETE FROM sessions WHERE token = ?', token)
|
|
100
104
|
deleteCookie(c, 'sid', { path: '/' })
|
|
101
105
|
return c.redirect('/login', 303)
|
|
102
106
|
})
|
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
"source": {
|
|
3
3
|
"repo": "acryldev/acryl",
|
|
4
4
|
"path": "docs/framework",
|
|
5
|
-
"commit": "
|
|
5
|
+
"commit": "8e23e14336647943d4232047e3ea253e434535d3"
|
|
6
6
|
},
|
|
7
|
-
"files":
|
|
8
|
-
"digest": "sha256:
|
|
7
|
+
"files": 99,
|
|
8
|
+
"digest": "sha256:2ff7cb6e36f1a04caece3bc14736ff23fd6eb2f86752453255973344e3344a0a"
|
|
9
9
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-acrylblends",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.6",
|
|
4
4
|
"description": "Create an Acryl app: npm create acrylblends@latest",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
"scaffold"
|
|
38
38
|
],
|
|
39
39
|
"dependencies": {
|
|
40
|
-
"acrylblends": "^0.7.
|
|
40
|
+
"acrylblends": "^0.7.6",
|
|
41
41
|
"@webboxes/app-persistence": "0.1.1"
|
|
42
42
|
},
|
|
43
43
|
"publishConfig": {
|
package/templates/chat/gitignore
CHANGED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
CREATE TABLE conversations (
|
|
2
|
+
id INTEGER PRIMARY KEY,
|
|
3
|
+
title TEXT NOT NULL,
|
|
4
|
+
created_at TEXT NOT NULL
|
|
5
|
+
);
|
|
6
|
+
|
|
7
|
+
CREATE TABLE messages (
|
|
8
|
+
id INTEGER PRIMARY KEY,
|
|
9
|
+
conversation_id INTEGER NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
|
|
10
|
+
role TEXT NOT NULL CHECK (role IN ('user', 'assistant')),
|
|
11
|
+
content TEXT NOT NULL
|
|
12
|
+
);
|
|
@@ -3,14 +3,17 @@
|
|
|
3
3
|
"version": "0.1.0",
|
|
4
4
|
"private": true,
|
|
5
5
|
"type": "module",
|
|
6
|
+
"acryl": {
|
|
7
|
+
"opener": "src/db.ts"
|
|
8
|
+
},
|
|
6
9
|
"engines": {
|
|
7
10
|
"node": ">=22.19.0"
|
|
8
11
|
},
|
|
9
12
|
"scripts": {
|
|
10
13
|
"dev": "node --watch --import acrylblends/node-server/register src/index.ts",
|
|
11
14
|
"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",
|
|
15
|
+
"test": "acrylblends check-deps && node --import acrylblends/node-server/register --test \"test/**/*.test.{ts,tsx}\"",
|
|
16
|
+
"check": "tsc --noEmit && tsc --noEmit -p src/client && acrylblends check-deps",
|
|
14
17
|
"build": "acrylblends build-client"
|
|
15
18
|
},
|
|
16
19
|
"dependencies": {
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { createApp } from './chat-app.ts'
|
|
2
|
-
import {
|
|
2
|
+
import { openChatDb } from './db.ts'
|
|
3
3
|
|
|
4
|
-
|
|
4
|
+
/** The composition root: opens the database (once) and builds the app. `index.ts` serves it; the desktop shell does too, and calls `close` when it stops. */
|
|
5
|
+
const { db, close } = await openChatDb()
|
|
5
6
|
|
|
7
|
+
export { close }
|
|
6
8
|
export default createApp(db)
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import { __CLASS__ } from '__PACKAGE__'
|
|
2
|
+
import type { Db } from '__PACKAGE__/db'
|
|
2
3
|
import { clientModules } from '__PACKAGE__/node-server'
|
|
3
4
|
import { type StandardSchema, schemaValidator } from '__PACKAGE__/schema-validator'
|
|
4
5
|
import { streamSSE } from '__PACKAGE__/streaming'
|
|
5
|
-
import
|
|
6
|
-
import { chatStore, openDb } from './db.ts'
|
|
6
|
+
import { chatStore } from './db.ts'
|
|
7
7
|
import { type Llm, openAiCompatible } from './llm.ts'
|
|
8
8
|
import { chatPage } from './page.tsx'
|
|
9
9
|
|
|
@@ -30,41 +30,45 @@ const ChatSchema: StandardSchema<ChatInput> = {
|
|
|
30
30
|
},
|
|
31
31
|
}
|
|
32
32
|
|
|
33
|
-
export function createApp(db:
|
|
33
|
+
export function createApp(db: Db, llm: Llm = openAiCompatible) {
|
|
34
34
|
const store = chatStore(db)
|
|
35
35
|
const app = new __CLASS__()
|
|
36
36
|
|
|
37
|
-
app.get('/', (c) => {
|
|
37
|
+
app.get('/', async (c) => {
|
|
38
38
|
const id = Number(c.req.query('c'))
|
|
39
|
-
const current = Number.isInteger(id) ? store.conversation(id) : undefined
|
|
39
|
+
const current = Number.isInteger(id) ? await store.conversation(id) : undefined
|
|
40
40
|
return c.html(
|
|
41
|
-
chatPage(
|
|
41
|
+
chatPage(
|
|
42
|
+
await store.conversations(),
|
|
43
|
+
current,
|
|
44
|
+
current ? await store.messages(current.id) : [],
|
|
45
|
+
),
|
|
42
46
|
)
|
|
43
47
|
})
|
|
44
48
|
|
|
45
|
-
app.get('/api/conversations', (c) => c.json({ conversations: store.conversations() }))
|
|
46
|
-
app.get('/api/conversations/:id', (c) => {
|
|
49
|
+
app.get('/api/conversations', async (c) => c.json({ conversations: await store.conversations() }))
|
|
50
|
+
app.get('/api/conversations/:id', async (c) => {
|
|
47
51
|
const id = Number(c.req.param('id'))
|
|
48
|
-
const conversation = store.conversation(id)
|
|
52
|
+
const conversation = await store.conversation(id)
|
|
49
53
|
return conversation
|
|
50
|
-
? c.json({ conversation, messages: store.messages(id) })
|
|
54
|
+
? c.json({ conversation, messages: await store.messages(id) })
|
|
51
55
|
: c.json({ error: 'No such conversation.' }, 404)
|
|
52
56
|
})
|
|
53
|
-
app.delete('/api/conversations/:id', (c) =>
|
|
54
|
-
store.remove(Number(c.req.param('id')))
|
|
57
|
+
app.delete('/api/conversations/:id', async (c) =>
|
|
58
|
+
(await store.remove(Number(c.req.param('id'))))
|
|
55
59
|
? c.json({ ok: true })
|
|
56
60
|
: c.json({ error: 'No such conversation.' }, 404),
|
|
57
61
|
)
|
|
58
62
|
|
|
59
63
|
// The answer streams as Server-Sent Events: `meta` (the conversation id), then one `token` per piece, then `done`, or `error`.
|
|
60
64
|
// 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) => {
|
|
65
|
+
app.post('/api/chat', schemaValidator('json', ChatSchema), async (c) => {
|
|
62
66
|
const { message, conversation } = c.req.valid('json')
|
|
63
|
-
const known = conversation === undefined ? undefined : store.conversation(conversation)
|
|
67
|
+
const known = conversation === undefined ? undefined : await store.conversation(conversation)
|
|
64
68
|
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 }))
|
|
69
|
+
const id = known?.id ?? (await store.start(message))
|
|
70
|
+
await store.add(id, 'user', message)
|
|
71
|
+
const history = (await store.messages(id)).map(({ role, content }) => ({ role, content }))
|
|
68
72
|
const signal = c.req.raw.signal
|
|
69
73
|
return streamSSE(c, async (stream) => {
|
|
70
74
|
let answer = ''
|
|
@@ -86,7 +90,7 @@ export function createApp(db: DatabaseSync = openDb(), llm: Llm = openAiCompatib
|
|
|
86
90
|
}
|
|
87
91
|
} finally {
|
|
88
92
|
// What arrived is kept, also when the reader pressed Stop.
|
|
89
|
-
if (answer !== '') store.add(id, 'assistant', answer)
|
|
93
|
+
if (answer !== '') await store.add(id, 'assistant', answer)
|
|
90
94
|
}
|
|
91
95
|
})
|
|
92
96
|
})
|
package/templates/chat/src/db.ts
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import type { Db } from '__PACKAGE__/db'
|
|
2
|
+
import { openDb } from '__PACKAGE__/db/sqlite'
|
|
3
|
+
import { fileURLToPath } from 'node:url'
|
|
2
4
|
|
|
3
5
|
export interface Message {
|
|
4
6
|
id: number
|
|
@@ -11,49 +13,41 @@ export interface Conversation {
|
|
|
11
13
|
title: string
|
|
12
14
|
}
|
|
13
15
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
id INTEGER PRIMARY KEY,
|
|
21
|
-
conversation_id INTEGER NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
|
|
22
|
-
role TEXT NOT NULL CHECK (role IN ('user', 'assistant')),
|
|
23
|
-
content TEXT NOT NULL
|
|
24
|
-
);
|
|
25
|
-
`)
|
|
26
|
-
return db
|
|
16
|
+
/** The folder of numbered SQL files (001-chat.sql, ...). Applied on start, each once, in one transaction. */
|
|
17
|
+
const MIGRATIONS = fileURLToPath(new URL('../migrations', import.meta.url))
|
|
18
|
+
|
|
19
|
+
/** Open the chat database and apply the migrations. Call `close` once, when the process stops. */
|
|
20
|
+
export function openChatDb(path = process.env.CHAT_DB ?? 'data/chat.sqlite') {
|
|
21
|
+
return openDb({ path, migrations: MIGRATIONS })
|
|
27
22
|
}
|
|
28
23
|
|
|
29
|
-
export function chatStore(db:
|
|
24
|
+
export function chatStore(db: Db) {
|
|
30
25
|
return {
|
|
31
|
-
conversations: () =>
|
|
32
|
-
db
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
db.
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
.
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
const info = db
|
|
45
|
-
.prepare('INSERT INTO conversations (title, created_at) VALUES (?, ?)')
|
|
46
|
-
.run(title.slice(0, 60), new Date().toISOString())
|
|
47
|
-
return Number(info.lastInsertRowid)
|
|
26
|
+
conversations: (): Promise<Conversation[]> =>
|
|
27
|
+
db.all<Conversation>('SELECT id, title FROM conversations ORDER BY id DESC'),
|
|
28
|
+
conversation: (id: number): Promise<Conversation | undefined> =>
|
|
29
|
+
db.get<Conversation>('SELECT id, title FROM conversations WHERE id = ?', id),
|
|
30
|
+
messages: (id: number): Promise<Message[]> =>
|
|
31
|
+
db.all<Message>('SELECT * FROM messages WHERE conversation_id = ? ORDER BY id', id),
|
|
32
|
+
async start(title: string): Promise<number> {
|
|
33
|
+
const row = await db.get<{ id: number }>(
|
|
34
|
+
'INSERT INTO conversations (title, created_at) VALUES (?, ?) RETURNING id',
|
|
35
|
+
title.slice(0, 60),
|
|
36
|
+
new Date().toISOString(),
|
|
37
|
+
)
|
|
38
|
+
return row!.id
|
|
48
39
|
},
|
|
49
|
-
add(conversationId: number, role: Message['role'], content: string) {
|
|
50
|
-
db.
|
|
40
|
+
async add(conversationId: number, role: Message['role'], content: string): Promise<void> {
|
|
41
|
+
await db.run(
|
|
42
|
+
'INSERT INTO messages (conversation_id, role, content) VALUES (?, ?, ?)',
|
|
51
43
|
conversationId,
|
|
52
44
|
role,
|
|
53
45
|
content,
|
|
54
46
|
)
|
|
55
47
|
},
|
|
56
|
-
remove
|
|
57
|
-
|
|
48
|
+
async remove(id: number): Promise<boolean> {
|
|
49
|
+
const { changes } = await db.run('DELETE FROM conversations WHERE id = ?', id)
|
|
50
|
+
return changes > 0
|
|
51
|
+
},
|
|
58
52
|
}
|
|
59
53
|
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { serve } from '__PACKAGE__/node-server'
|
|
2
|
-
import app, {
|
|
2
|
+
import app, { close } from './app.ts'
|
|
3
3
|
|
|
4
4
|
const port = Number(process.env.PORT || 3000)
|
|
5
5
|
// Local by default. Behind a reverse proxy on the same machine this is right; in a container set HOST=0.0.0.0.
|
|
@@ -9,11 +9,16 @@ const server = serve({ fetch: app.fetch, port, hostname }, (info) => {
|
|
|
9
9
|
console.log(`listening on http://${info.address}:${info.port}`)
|
|
10
10
|
})
|
|
11
11
|
|
|
12
|
-
// Stop taking requests, let the ones in flight finish, then exit. A connection that never ends cannot keep the process alive past 10 seconds.
|
|
12
|
+
// Stop taking requests, let the ones in flight finish, then close the database and exit. A connection that never ends cannot keep the process alive past 10 seconds.
|
|
13
13
|
function shutdown(): void {
|
|
14
14
|
server.close(() => {
|
|
15
|
-
|
|
16
|
-
|
|
15
|
+
close().then(
|
|
16
|
+
() => process.exit(0),
|
|
17
|
+
(error) => {
|
|
18
|
+
console.error(error)
|
|
19
|
+
process.exit(1)
|
|
20
|
+
},
|
|
21
|
+
)
|
|
17
22
|
})
|
|
18
23
|
server.closeIdleConnections()
|
|
19
24
|
setTimeout(() => process.exit(1), 10_000).unref()
|