create-acrylblends 0.2.6 → 0.2.7
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.
|
@@ -1,3 +1,3 @@
|
|
|
1
1
|
# Generated copy
|
|
2
2
|
|
|
3
|
-
This folder is a copy of `docs/framework` of acryldev/acryl at commit `
|
|
3
|
+
This folder is a copy of `docs/framework` of acryldev/acryl at commit `f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb`, made by `scripts/sync-framework.mjs`. Do not edit it here: change the text in ACRYL and sync again. `pnpm run verify:framework` fails when a page differs from the recorded digest.
|
|
@@ -10,10 +10,74 @@ provider today; a Postgres provider (Postgres or Supabase through `DATABASE_URL`
|
|
|
10
10
|
| --- | --- | --- |
|
|
11
11
|
| Normal web or desktop app, users, lists, orders | `db` with SQLite (the `notes` and `chat` templates) | available |
|
|
12
12
|
| Hosted, many users | `db` with Postgres or Supabase | planned |
|
|
13
|
-
| Tiny, one person, a few screens | `kv
|
|
13
|
+
| Tiny, one person, a few screens | [`kv`](#a-tiny-app-kv), named JSON documents with no SQL | available |
|
|
14
14
|
| Agents or long tasks that must survive a restart | `durable`, in the same database as `db` | planned |
|
|
15
15
|
|
|
16
|
-
Start with `db
|
|
16
|
+
Start with `db` when the data has users, lists or relations: SQL is what people and coding agents already know. Start with `kv` when the whole
|
|
17
|
+
data is a handful of settings or a small list that one process reads and writes.
|
|
18
|
+
|
|
19
|
+
## A tiny app: `kv`
|
|
20
|
+
|
|
21
|
+
`kv` keeps named JSON documents in one file, with no SQL and no migrations. It suits a settings page, a demo, a one-person tool.
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import { openKv } from 'acrylblends/kv/json'
|
|
25
|
+
|
|
26
|
+
const { kv, close } = await openKv({ path: 'data/kv.json' })
|
|
27
|
+
|
|
28
|
+
await kv.set('theme', 'dark')
|
|
29
|
+
const theme = await kv.get<string>('theme') // 'dark'; undefined for a key that was never set
|
|
30
|
+
|
|
31
|
+
// Change a value from the value it has now, without losing a concurrent change.
|
|
32
|
+
const visits = await kv.update<number>('visits', (current) => (current ?? 0) + 1)
|
|
33
|
+
|
|
34
|
+
await kv.set('todos/1', { title: 'Buy milk', done: false })
|
|
35
|
+
await kv.set('todos/2', { title: 'Write docs', done: true })
|
|
36
|
+
const keys = await kv.list('todos/') // ['todos/1', 'todos/2'], sorted by code point
|
|
37
|
+
|
|
38
|
+
await kv.delete('todos/1') // a key that is not there is not an error
|
|
39
|
+
await close()
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
- A key is a non-empty string; a prefix such as `todos/` groups related documents. A value is JSON (`null`, booleans, numbers, strings, arrays,
|
|
43
|
+
objects). `undefined`, functions, bigints and `NaN` are refused with a `TypeError` before anything is written, and a value read back is a copy.
|
|
44
|
+
- `update` runs your function with the current value (`undefined` when the key is missing) and stores what it returns. The function is
|
|
45
|
+
**synchronous**: an `async` function is a type error. Read what you need first with `await kv.get(...)`, then update with a plain function.
|
|
46
|
+
If it throws, the value stays as it was.
|
|
47
|
+
- Every write reaches the disk before its promise resolves, and the file is replaced as a whole (a temporary file, then a rename), so a crash
|
|
48
|
+
or a power cut leaves the old file or the new one, never half of one. A file that exists but does not parse stops the app with a message that
|
|
49
|
+
names it; it is never started over.
|
|
50
|
+
- Like `db`, the store is passed to the code that needs it (`createApp(kv)`), opened in one place, and closed when the process stops.
|
|
51
|
+
A test opens a file in a temporary folder.
|
|
52
|
+
|
|
53
|
+
### When to move to SQL
|
|
54
|
+
|
|
55
|
+
The whole file is kept in memory and rewritten on every write, and one process owns it. Move to `db` when:
|
|
56
|
+
|
|
57
|
+
- more than one process must write (two writers would overwrite each other);
|
|
58
|
+
- the file grows past a few megabytes, or you need to search, sort or join the data;
|
|
59
|
+
- the data gets relations (users who own notes).
|
|
60
|
+
|
|
61
|
+
The same `kv` interface runs on SQL, so the code does not change, only the line that opens it. `kvOnDb` keeps the documents in a `kv` table of the
|
|
62
|
+
database from `openDb`, and `copyKv` moves what the file holds:
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
import { copyKv } from 'acrylblends/kv'
|
|
66
|
+
import { openKv } from 'acrylblends/kv/json'
|
|
67
|
+
import { kvOnDb } from 'acrylblends/kv/db'
|
|
68
|
+
import { openDb } from 'acrylblends/db/sqlite'
|
|
69
|
+
|
|
70
|
+
const file = await openKv({ path: 'data/kv.json' })
|
|
71
|
+
const sql = await openDb({ path: 'data/app.sqlite', migrations: 'migrations' })
|
|
72
|
+
|
|
73
|
+
const { copied } = await copyKv(file.kv, kvOnDb(sql.db)) // refuses to overwrite a key the table already has, unless you pass { overwrite: true }
|
|
74
|
+
|
|
75
|
+
await file.close()
|
|
76
|
+
await sql.close()
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
On the command line, `npx acrylblends kv import data/kv.json data/app.sqlite` does the same (add `--overwrite` to replace keys the table has).
|
|
80
|
+
The table is created on first use, beside the app's own tables; nothing else changes.
|
|
17
81
|
|
|
18
82
|
## Open the database
|
|
19
83
|
|
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
"source": {
|
|
3
3
|
"repo": "acryldev/acryl",
|
|
4
4
|
"path": "docs/framework",
|
|
5
|
-
"commit": "
|
|
5
|
+
"commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
|
|
6
6
|
},
|
|
7
7
|
"files": 99,
|
|
8
|
-
"digest": "sha256:
|
|
8
|
+
"digest": "sha256:075d537930a53f7ba46b989ff82f9d83a720270c60d848917e6501bfabff6df1"
|
|
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.7",
|
|
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.7",
|
|
41
41
|
"@webboxes/app-persistence": "0.1.1"
|
|
42
42
|
},
|
|
43
43
|
"publishConfig": {
|