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,59 @@
1
+ import { DatabaseSync } from 'node:sqlite'
2
+
3
+ export interface Message {
4
+ id: number
5
+ conversation_id: number
6
+ role: 'user' | 'assistant'
7
+ content: string
8
+ }
9
+ export interface Conversation {
10
+ id: number
11
+ title: string
12
+ }
13
+
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
27
+ }
28
+
29
+ export function chatStore(db: DatabaseSync) {
30
+ 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)
48
+ },
49
+ add(conversationId: number, role: Message['role'], content: string) {
50
+ db.prepare('INSERT INTO messages (conversation_id, role, content) VALUES (?, ?, ?)').run(
51
+ conversationId,
52
+ role,
53
+ content,
54
+ )
55
+ },
56
+ remove: (id: number) =>
57
+ Number(db.prepare('DELETE FROM conversations WHERE id = ?').run(id).changes) > 0,
58
+ }
59
+ }
@@ -0,0 +1,22 @@
1
+ import { serve } from '__PACKAGE__/node-server'
2
+ import app, { db } from './app.ts'
3
+
4
+ const port = Number(process.env.PORT || 3000)
5
+ // Local by default. Behind a reverse proxy on the same machine this is right; in a container set HOST=0.0.0.0.
6
+ const hostname = process.env.HOST || '127.0.0.1'
7
+
8
+ const server = serve({ fetch: app.fetch, port, hostname }, (info) => {
9
+ console.log(`listening on http://${info.address}:${info.port}`)
10
+ })
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.
13
+ function shutdown(): void {
14
+ server.close(() => {
15
+ db.close()
16
+ process.exit(0)
17
+ })
18
+ server.closeIdleConnections()
19
+ setTimeout(() => process.exit(1), 10_000).unref()
20
+ }
21
+ process.once('SIGINT', shutdown)
22
+ process.once('SIGTERM', shutdown)
@@ -0,0 +1,42 @@
1
+ /** What the app needs from a language model: the conversation so far in, the answer out piece by piece. Aborting the signal must stop the work. */
2
+ export type Llm = (
3
+ messages: { role: string; content: string }[],
4
+ signal: AbortSignal,
5
+ ) => AsyncIterable<string>
6
+
7
+ /**
8
+ * An OpenAI-compatible chat completions API with `stream: true` (DeepSeek by default). The key is read from DEEPSEEK_API_KEY at the moment of the call and
9
+ * is never stored; DEEPSEEK_BASE_URL and DEEPSEEK_MODEL choose the service.
10
+ */
11
+ export const openAiCompatible: Llm = async function* (messages, signal) {
12
+ const key = process.env.DEEPSEEK_API_KEY
13
+ if (!key) throw new Error('DEEPSEEK_API_KEY is not set')
14
+ const base = (process.env.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com').replace(/\/$/, '')
15
+ const response = await fetch(`${base}/chat/completions`, {
16
+ method: 'POST',
17
+ headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
18
+ body: JSON.stringify({
19
+ model: process.env.DEEPSEEK_MODEL ?? 'deepseek-chat',
20
+ messages,
21
+ stream: true,
22
+ }),
23
+ signal,
24
+ })
25
+ if (!response.ok || !response.body)
26
+ throw new Error(`the model service answered ${response.status}`)
27
+ const decoder = new TextDecoder()
28
+ let buffer = ''
29
+ for await (const chunk of response.body) {
30
+ buffer += decoder.decode(chunk, { stream: true })
31
+ const lines = buffer.split('\n')
32
+ buffer = lines.pop() ?? ''
33
+ for (const line of lines) {
34
+ if (!line.startsWith('data:')) continue
35
+ const data = line.slice(5).trim()
36
+ if (data === '[DONE]') return
37
+ const piece = (JSON.parse(data) as { choices?: { delta?: { content?: string } }[] })
38
+ .choices?.[0]?.delta?.content
39
+ if (piece) yield piece
40
+ }
41
+ }
42
+ }
@@ -0,0 +1,38 @@
1
+ import type { Conversation, Message } from './db.ts'
2
+
3
+ export const chatPage = (
4
+ conversations: Conversation[],
5
+ current: Conversation | undefined,
6
+ messages: Message[],
7
+ ): string =>
8
+ (
9
+ <html lang="en">
10
+ <head>
11
+ <meta charset="utf-8" />
12
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
13
+ <title>Chat</title>
14
+ <style
15
+ dangerouslySetInnerHTML={{
16
+ __html:
17
+ 'body{font:16px system-ui;max-width:48rem;margin:2rem auto;padding:0 1rem}.row{white-space:pre-wrap;margin:.75rem 0}.user{font-weight:600}.error{color:#b00020}textarea{width:100%;box-sizing:border-box;padding:.5rem}nav a{margin-right:.75rem}',
18
+ }}
19
+ />
20
+ </head>
21
+ <body>
22
+ <h1>Chat</h1>
23
+ <nav>
24
+ <a href="/">New chat</a>
25
+ {conversations.map((c) => (
26
+ <a href={`/?c=${c.id}`}>{c.title}</a>
27
+ ))}
28
+ </nav>
29
+ <div id="log">
30
+ {messages.map((m) => (
31
+ <p class={`row ${m.role}`}>{m.content}</p>
32
+ ))}
33
+ </div>
34
+ <div id="chat" data-conversation={current ? String(current.id) : ''} />
35
+ <script type="module" src="/client/chat.tsx" />
36
+ </body>
37
+ </html>
38
+ ).toString()
@@ -0,0 +1,153 @@
1
+ import assert from 'node:assert/strict'
2
+ import { test } from 'node:test'
3
+ import { createApp } from '../src/chat-app.ts'
4
+ import { openDb } from '../src/db.ts'
5
+ import type { Llm } from '../src/llm.ts'
6
+
7
+ /** A model that answers with fixed pieces and records what it was asked. */
8
+ function mock(pieces: string[]) {
9
+ const asked: { role: string; content: string }[][] = []
10
+ const llm: Llm = async function* (messages) {
11
+ asked.push(messages)
12
+ for (const piece of pieces) yield piece
13
+ }
14
+ return { llm, asked }
15
+ }
16
+
17
+ const post = (body: unknown): RequestInit => ({
18
+ method: 'POST',
19
+ headers: { 'content-type': 'application/json' },
20
+ body: JSON.stringify(body),
21
+ })
22
+
23
+ /** Parse a Server-Sent Events body into [event, data] pairs. */
24
+ function events(text: string): [string, string][] {
25
+ return text
26
+ .split('\n\n')
27
+ .filter(Boolean)
28
+ .map((block) => {
29
+ const event = /^event: (.*)$/m.exec(block)?.[1] ?? 'message'
30
+ const data = /^data: (.*)$/m.exec(block)?.[1] ?? ''
31
+ return [event, data]
32
+ })
33
+ }
34
+
35
+ test('the answer streams as events: meta, one token per piece, done', async () => {
36
+ const { llm } = mock(['Hel', 'lo ', 'there\nline'])
37
+ const app = createApp(openDb(':memory:'), llm)
38
+ const res = await app.request('/api/chat', post({ message: 'hi' }))
39
+ assert.equal(res.status, 200)
40
+ assert.match(res.headers.get('content-type') ?? '', /text\/event-stream/)
41
+ const got = events(await res.text())
42
+ assert.deepEqual(
43
+ got.map(([e]) => e),
44
+ ['meta', 'token', 'token', 'token', 'done'],
45
+ )
46
+ assert.equal(
47
+ got
48
+ .filter(([e]) => e === 'token')
49
+ .map(([, d]) => JSON.parse(d) as string)
50
+ .join(''),
51
+ 'Hello there\nline',
52
+ )
53
+ })
54
+
55
+ test('history is stored, sent back to the model, and listed', async () => {
56
+ const { llm, asked } = mock(['ok'])
57
+ const app = createApp(openDb(':memory:'), llm)
58
+ const first = events(
59
+ await (await app.request('/api/chat', post({ message: 'first question' }))).text(),
60
+ )
61
+ const id = (JSON.parse(first[0]![1]) as { conversation: number }).conversation
62
+ await (await app.request('/api/chat', post({ message: 'second', conversation: id }))).text()
63
+ assert.deepEqual(
64
+ asked[1]?.map((m) => m.content),
65
+ ['first question', 'ok', 'second'],
66
+ )
67
+ const one = (await (await app.request(`/api/conversations/${id}`)).json()) as {
68
+ messages: { role: string }[]
69
+ }
70
+ assert.deepEqual(
71
+ one.messages.map((m) => m.role),
72
+ ['user', 'assistant', 'user', 'assistant'],
73
+ )
74
+ const list = (await (await app.request('/api/conversations')).json()) as {
75
+ conversations: { title: string }[]
76
+ }
77
+ assert.equal(list.conversations[0]?.title, 'first question')
78
+ const page = await (await app.request(`/?c=${id}`)).text()
79
+ assert.match(page, /first question/)
80
+ assert.match(page, /src="\/client\/chat\.tsx"/)
81
+ })
82
+
83
+ test('a bad message answers 400 with a message, an unknown conversation 404, and nothing reaches the model', async () => {
84
+ const { llm, asked } = mock(['x'])
85
+ const app = createApp(openDb(':memory:'), llm)
86
+ const empty = await app.request('/api/chat', post({ message: ' ' }))
87
+ assert.equal(empty.status, 400)
88
+ assert.match(JSON.stringify(await empty.json()), /Write a message/)
89
+ assert.equal(
90
+ (await app.request('/api/chat', post({ message: 'hi', conversation: 99 }))).status,
91
+ 404,
92
+ )
93
+ assert.equal(asked.length, 0)
94
+ })
95
+
96
+ test('a conversation can be deleted', async () => {
97
+ const app = createApp(openDb(':memory:'), mock(['a']).llm)
98
+ const first = events(await (await app.request('/api/chat', post({ message: 'hi' }))).text())
99
+ const id = (JSON.parse(first[0]![1]) as { conversation: number }).conversation
100
+ assert.equal((await app.request(`/api/conversations/${id}`, { method: 'DELETE' })).status, 200)
101
+ assert.equal((await app.request(`/api/conversations/${id}`)).status, 404)
102
+ assert.equal((await app.request(`/api/conversations/${id}`, { method: 'DELETE' })).status, 404)
103
+ })
104
+
105
+ test('a failing model sends an error event with a plain message and no detail', async () => {
106
+ const llm: Llm = async function* () {
107
+ yield 'partial '
108
+ throw new Error('upstream secret detail')
109
+ }
110
+ const app = createApp(openDb(':memory:'), llm)
111
+ const text = await (await app.request('/api/chat', post({ message: 'hi' }))).text()
112
+ assert.doesNotMatch(text, /secret detail/)
113
+ const last = events(text).at(-1)
114
+ assert.equal(last?.[0], 'error')
115
+ assert.match(last?.[1] ?? '', /could not answer/)
116
+ })
117
+
118
+ test('when the client goes away the model call is aborted and what arrived is kept', async () => {
119
+ let sawAbort: (value: boolean) => void = () => {}
120
+ const aborted = new Promise<boolean>((resolve) => {
121
+ sawAbort = resolve
122
+ })
123
+ const llm: Llm = async function* (_messages, signal) {
124
+ yield 'first '
125
+ // The signal may already be aborted by the time the model is asked for more: an abort event that has fired does not fire again.
126
+ if (!signal.aborted)
127
+ await new Promise<void>((resolve) =>
128
+ signal.addEventListener('abort', () => resolve(), { once: true }),
129
+ )
130
+ sawAbort(signal.aborted)
131
+ if (signal.aborted) throw new DOMException('aborted', 'AbortError')
132
+ yield 'never sent'
133
+ }
134
+ const db = openDb(':memory:')
135
+ const app = createApp(db, llm)
136
+ const controller = new AbortController()
137
+ const res = await app.request('/api/chat', {
138
+ ...post({ message: 'hi' }),
139
+ signal: controller.signal,
140
+ })
141
+ const reader = res.body!.getReader()
142
+ const decoder = new TextDecoder()
143
+ let seen = ''
144
+ while (!seen.includes('first')) seen += decoder.decode((await reader.read()).value)
145
+ controller.abort()
146
+ assert.equal(await aborted, true)
147
+ await new Promise((resolve) => setTimeout(resolve, 50))
148
+ const rows = db.prepare('SELECT role, content FROM messages ORDER BY id').all()
149
+ assert.deepEqual(
150
+ rows.map((r) => `${r.role}:${r.content}`),
151
+ ['user:hi', 'assistant:first '],
152
+ )
153
+ })
@@ -0,0 +1,59 @@
1
+ import assert from 'node:assert/strict'
2
+ import { spawn } from 'node:child_process'
3
+ import { once } from 'node:events'
4
+ import { mkdtempSync } from 'node:fs'
5
+ import { tmpdir } from 'node:os'
6
+ import { join } from 'node:path'
7
+ import { test } from 'node:test'
8
+
9
+ /** Start `src/index.ts` the way `npm start` does, on a port the system chooses, and read the address it prints. */
10
+ async function start(env: Record<string, string> = {}) {
11
+ const child = spawn(
12
+ process.execPath,
13
+ ['--import', '__PACKAGE__/node-server/register', 'src/index.ts'],
14
+ {
15
+ env: {
16
+ ...process.env,
17
+ PORT: '0',
18
+ CHAT_DB: join(mkdtempSync(join(tmpdir(), 'chat-')), 'chat.db'),
19
+ ...env,
20
+ },
21
+ stdio: ['ignore', 'pipe', 'inherit'],
22
+ },
23
+ )
24
+ let out = ''
25
+ const address = await new Promise<string>((resolve, reject) => {
26
+ child.once('exit', (code) =>
27
+ reject(new Error(`the server exited with ${code} before it listened`)),
28
+ )
29
+ child.stdout.on('data', (chunk) => {
30
+ out += chunk
31
+ const match = /listening on (http:\/\/\S+)/.exec(out)
32
+ if (match?.[1]) resolve(match[1])
33
+ })
34
+ })
35
+ return { child, address }
36
+ }
37
+
38
+ test('the server listens on 127.0.0.1 unless HOST says otherwise', async () => {
39
+ const { child, address } = await start()
40
+ try {
41
+ assert.match(address, /^http:\/\/127\.0\.0\.1:\d+$/)
42
+ } finally {
43
+ child.kill('SIGTERM')
44
+ await once(child, 'exit')
45
+ }
46
+ })
47
+
48
+ for (const signal of ['SIGTERM', 'SIGINT'] as const) {
49
+ test(`${signal} stops the server cleanly and frees the port`, async () => {
50
+ const { child, address } = await start()
51
+ assert.equal((await fetch(`${address}/`)).status, 200)
52
+ const started = Date.now()
53
+ child.kill(signal)
54
+ const [code] = await once(child, 'exit')
55
+ assert.equal(code, 0)
56
+ assert.ok(Date.now() - started < 5000, 'the server took too long to stop')
57
+ await assert.rejects(fetch(address), 'the port should be free')
58
+ })
59
+ }
@@ -0,0 +1,19 @@
1
+ {
2
+ "compilerOptions": {
3
+ "target": "ES2024",
4
+ "lib": ["ES2024", "DOM", "DOM.Iterable"],
5
+ "module": "NodeNext",
6
+ "moduleResolution": "NodeNext",
7
+ "strict": true,
8
+ "verbatimModuleSyntax": true,
9
+ "erasableSyntaxOnly": true,
10
+ "allowImportingTsExtensions": true,
11
+ "noEmit": true,
12
+ "skipLibCheck": true,
13
+ "types": ["node"],
14
+ "jsx": "react-jsx",
15
+ "jsxImportSource": "__PACKAGE__/jsx"
16
+ },
17
+ "include": ["src", "test"],
18
+ "exclude": ["src/client"]
19
+ }