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.
@@ -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 `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": "8e23e14336647943d4232047e3ea253e434535d3"
6
6
  },
7
- "files": 98,
8
- "digest": "sha256:396f882ac7b612455edc59961c52472fadc5f95ea1a778208e7edd860e4e6727"
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.4",
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.4",
40
+ "acrylblends": "^0.7.6",
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
+ );
@@ -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 { 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()