create-acrylblends 0.2.4 → 0.2.5

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.
@@ -0,0 +1,202 @@
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
+ ## In a Cordis app
186
+
187
+ 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),
188
+ applies the `migrations` folder, and provides `db`; a plugin declares `inject: ['db']` and imports the types only:
189
+
190
+ ```ts
191
+ import type { Context } from '@deepseek-ai/cordis'
192
+ import type {} from 'acryl-db'
193
+
194
+ export const name = 'notes'
195
+ export const inject = ['db']
196
+
197
+ export function apply(ctx: Context) {
198
+ void ctx.db.run('INSERT INTO notes (title) VALUES (?)', 'first')
199
+ }
200
+ ```
201
+
202
+ 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 `node:sqlite`
7
-
8
- Node.js 22.19 and later include SQLite, so there is nothing to install. `DatabaseSync` is synchronous, which suits a small app.
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 { DatabaseSync } from 'node:sqlite'
12
-
13
- export function openDb(path = process.env.NOTES_DB ?? 'notes.db'): DatabaseSync {
14
- const db = new DatabaseSync(path)
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 passes `openDb(':memory:')`, and importing the app module does not create a file.
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 { DatabaseSync } from 'node:sqlite'
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: DatabaseSync) {
73
+ export function createApp(db: Db) {
71
74
  const userFor = (token: string | undefined) =>
72
75
  token
73
- ? (db
74
- .prepare('SELECT users.id AS id, users.email AS email FROM sessions JOIN users ON users.id = sessions.user_id WHERE token = ?')
75
- .get(token) as { id: number; email: string } | undefined)
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.prepare('INSERT INTO sessions (token, user_id) VALUES (?, ?)').run(token, 1)
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.prepare('DELETE FROM sessions WHERE token = ?').run(token)
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": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
5
+ "commit": "4721bb00960fa4e157e6070c330cf87c148739fc"
6
6
  },
7
- "files": 98,
8
- "digest": "sha256:396f882ac7b612455edc59961c52472fadc5f95ea1a778208e7edd860e4e6727"
7
+ "files": 99,
8
+ "digest": "sha256:ce484a4cf2bc9781d188fe468e98c498052d50155bb72f84c0a1ad384b1a5e85"
9
9
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-acrylblends",
3
- "version": "0.2.4",
3
+ "version": "0.2.5",
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.4",
40
+ "acrylblends": "^0.7.5",
41
41
  "@webboxes/app-persistence": "0.1.1"
42
42
  },
43
43
  "publishConfig": {
@@ -1,5 +1,6 @@
1
1
  node_modules/
2
- *.db
3
- *.db-*
2
+ data/
3
+ *.sqlite
4
+ *.sqlite-*
4
5
  .acrylblends/
5
6
  dist/
@@ -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
+ );
@@ -1,6 +1,8 @@
1
1
  import { createApp } from './chat-app.ts'
2
- import { openDb } from './db.ts'
2
+ import { openChatDb } from './db.ts'
3
3
 
4
- export const db = openDb()
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 type { DatabaseSync } from 'node:sqlite'
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: DatabaseSync = openDb(), llm: Llm = openAiCompatible) {
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(store.conversations(), current, current ? store.messages(current.id) : []),
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
  })
@@ -1,4 +1,6 @@
1
- import { DatabaseSync } from 'node:sqlite'
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
- export function openDb(path = process.env.CHAT_DB ?? 'chat.db'): DatabaseSync {
15
- const db = new DatabaseSync(path)
16
- db.exec(`
17
- PRAGMA foreign_keys = ON;
18
- CREATE TABLE IF NOT EXISTS conversations (id INTEGER PRIMARY KEY, title TEXT NOT NULL, created_at TEXT NOT NULL);
19
- CREATE TABLE IF NOT EXISTS messages (
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: DatabaseSync) {
24
+ export function chatStore(db: Db) {
30
25
  return {
31
- conversations: () =>
32
- db
33
- .prepare('SELECT id, title FROM conversations ORDER BY id DESC')
34
- .all() as unknown as Conversation[],
35
- conversation: (id: number) =>
36
- db.prepare('SELECT id, title FROM conversations WHERE id = ?').get(id) as unknown as
37
- | Conversation
38
- | undefined,
39
- messages: (id: number) =>
40
- db
41
- .prepare('SELECT * FROM messages WHERE conversation_id = ? ORDER BY id')
42
- .all(id) as unknown as Message[],
43
- start(title: string): number {
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.prepare('INSERT INTO messages (conversation_id, role, content) VALUES (?, ?, ?)').run(
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: (id: number) =>
57
- Number(db.prepare('DELETE FROM conversations WHERE id = ?').run(id).changes) > 0,
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, { db } from './app.ts'
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
- db.close()
16
- process.exit(0)
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()
@@ -1,9 +1,19 @@
1
+ import type { Db } from '__PACKAGE__/db'
1
2
  import assert from 'node:assert/strict'
2
- import { test } from 'node:test'
3
+ import { after, test } from 'node:test'
3
4
  import { createApp } from '../src/chat-app.ts'
4
- import { openDb } from '../src/db.ts'
5
+ import { openChatDb } from '../src/db.ts'
5
6
  import type { Llm } from '../src/llm.ts'
6
7
 
8
+ /** A fresh database in memory with the real migrations; every one is closed when the tests end. */
9
+ const closers: (() => Promise<void>)[] = []
10
+ after(() => Promise.all(closers.map((close) => close())))
11
+ async function memoryDb(): Promise<Db> {
12
+ const { db, close } = await openChatDb(':memory:')
13
+ closers.push(close)
14
+ return db
15
+ }
16
+
7
17
  /** A model that answers with fixed pieces and records what it was asked. */
8
18
  function mock(pieces: string[]) {
9
19
  const asked: { role: string; content: string }[][] = []
@@ -34,7 +44,7 @@ function events(text: string): [string, string][] {
34
44
 
35
45
  test('the answer streams as events: meta, one token per piece, done', async () => {
36
46
  const { llm } = mock(['Hel', 'lo ', 'there\nline'])
37
- const app = createApp(openDb(':memory:'), llm)
47
+ const app = createApp(await memoryDb(), llm)
38
48
  const res = await app.request('/api/chat', post({ message: 'hi' }))
39
49
  assert.equal(res.status, 200)
40
50
  assert.match(res.headers.get('content-type') ?? '', /text\/event-stream/)
@@ -54,7 +64,7 @@ test('the answer streams as events: meta, one token per piece, done', async () =
54
64
 
55
65
  test('history is stored, sent back to the model, and listed', async () => {
56
66
  const { llm, asked } = mock(['ok'])
57
- const app = createApp(openDb(':memory:'), llm)
67
+ const app = createApp(await memoryDb(), llm)
58
68
  const first = events(
59
69
  await (await app.request('/api/chat', post({ message: 'first question' }))).text(),
60
70
  )
@@ -82,7 +92,7 @@ test('history is stored, sent back to the model, and listed', async () => {
82
92
 
83
93
  test('a bad message answers 400 with a message, an unknown conversation 404, and nothing reaches the model', async () => {
84
94
  const { llm, asked } = mock(['x'])
85
- const app = createApp(openDb(':memory:'), llm)
95
+ const app = createApp(await memoryDb(), llm)
86
96
  const empty = await app.request('/api/chat', post({ message: ' ' }))
87
97
  assert.equal(empty.status, 400)
88
98
  assert.match(JSON.stringify(await empty.json()), /Write a message/)
@@ -94,7 +104,7 @@ test('a bad message answers 400 with a message, an unknown conversation 404, and
94
104
  })
95
105
 
96
106
  test('a conversation can be deleted', async () => {
97
- const app = createApp(openDb(':memory:'), mock(['a']).llm)
107
+ const app = createApp(await memoryDb(), mock(['a']).llm)
98
108
  const first = events(await (await app.request('/api/chat', post({ message: 'hi' }))).text())
99
109
  const id = (JSON.parse(first[0]![1]) as { conversation: number }).conversation
100
110
  assert.equal((await app.request(`/api/conversations/${id}`, { method: 'DELETE' })).status, 200)
@@ -107,7 +117,7 @@ test('a failing model sends an error event with a plain message and no detail',
107
117
  yield 'partial '
108
118
  throw new Error('upstream secret detail')
109
119
  }
110
- const app = createApp(openDb(':memory:'), llm)
120
+ const app = createApp(await memoryDb(), llm)
111
121
  const text = await (await app.request('/api/chat', post({ message: 'hi' }))).text()
112
122
  assert.doesNotMatch(text, /secret detail/)
113
123
  const last = events(text).at(-1)
@@ -131,7 +141,7 @@ test('when the client goes away the model call is aborted and what arrived is ke
131
141
  if (signal.aborted) throw new DOMException('aborted', 'AbortError')
132
142
  yield 'never sent'
133
143
  }
134
- const db = openDb(':memory:')
144
+ const db = await memoryDb()
135
145
  const app = createApp(db, llm)
136
146
  const controller = new AbortController()
137
147
  const res = await app.request('/api/chat', {
@@ -145,7 +155,9 @@ test('when the client goes away the model call is aborted and what arrived is ke
145
155
  controller.abort()
146
156
  assert.equal(await aborted, true)
147
157
  await new Promise((resolve) => setTimeout(resolve, 50))
148
- const rows = db.prepare('SELECT role, content FROM messages ORDER BY id').all()
158
+ const rows = await db.all<{ role: string; content: string }>(
159
+ 'SELECT role, content FROM messages ORDER BY id',
160
+ )
149
161
  assert.deepEqual(
150
162
  rows.map((r) => `${r.role}:${r.content}`),
151
163
  ['user:hi', 'assistant:first '],