@soffits/dsh-card-board 0.6.0 → 0.7.1
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/CHANGELOG.md +13 -0
- package/README.md +59 -11
- package/client.js +1375 -1057
- package/examples/boards/home/board.json +6 -0
- package/examples/boards/home/cards/chores.json +16 -4
- package/examples/boards/home/cards/countdown.json +57 -0
- package/examples/boards/home/cards/house.json +15 -5
- package/examples/boards/home/cards/savings.json +3 -1
- package/examples/boards/home/cards/summary.json +50 -0
- package/examples/boards/home/cards/weather.json +43 -5
- package/index.js +7 -1
- package/locale/en.json +9 -3
- package/locale/fr.json +9 -3
- package/locale/zh.json +9 -3
- package/package.json +9 -5
- package/src/routes.js +135 -19
- package/src/schema.js +119 -12
- package/src/seen.js +111 -0
- package/src/store.js +17 -3
- package/src/watch.js +113 -0
package/src/schema.js
CHANGED
|
@@ -8,16 +8,22 @@
|
|
|
8
8
|
* fails at write time instead of quietly not showing.
|
|
9
9
|
*/
|
|
10
10
|
|
|
11
|
-
export const CARD_TYPES = Object.freeze(['stat', 'line', 'bar', 'donut', 'list', 'timeline', 'status'])
|
|
12
|
-
export const TONES = Object.freeze(['ok', 'warn', 'bad', 'muted', 'accent'])
|
|
11
|
+
export const CARD_TYPES = Object.freeze(['summary', 'countdown', 'stat', 'line', 'bar', 'donut', 'list', 'timeline', 'status'])
|
|
12
|
+
export const TONES = Object.freeze(['ok', 'warn', 'bad', 'muted', 'accent', 'violet'])
|
|
13
|
+
/** Icon names: the page draws the ones its icon set has (Lucide names) and nothing for the rest. */
|
|
14
|
+
export const ICON_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/
|
|
13
15
|
export const ACTION_KINDS = Object.freeze(['chat', 'step', 'done', 'snooze', 'event', 'link'])
|
|
14
16
|
/** Kinds the server records as events; chat and link happen in the browser only. */
|
|
15
17
|
export const PRESS_KINDS = Object.freeze(['step', 'done', 'snooze', 'event'])
|
|
16
18
|
/** Suggested steps per card or row: a few clear next moves, not a menu. */
|
|
17
19
|
export const MAX_STEPS = 3
|
|
18
20
|
export const ACTION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$/
|
|
21
|
+
/** Row keys: stable ids, so the page can tell which row changed. The same shape as action ids. */
|
|
22
|
+
export const KEY_PATTERN = ACTION_ID_PATTERN
|
|
19
23
|
const MAX_ACTIONS = 6
|
|
20
24
|
const MAX_PAYLOAD_BYTES = 4096
|
|
25
|
+
/** Which way a stat's change goes, for its arrow. */
|
|
26
|
+
export const DIRECTIONS = Object.freeze(['up', 'down', 'flat'])
|
|
21
27
|
export const TIMELINE_KINDS = Object.freeze(['travel', 'due', 'event', 'health', 'home', 'money'])
|
|
22
28
|
/** Board and card ids: also folder and file names, so nothing that can climb out of the data folder. */
|
|
23
29
|
export const ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/
|
|
@@ -144,6 +150,30 @@ function tone(c, value, path) {
|
|
|
144
150
|
c.optional(value, 'tone', v => c.oneOf(v, join(path, 'tone'), TONES))
|
|
145
151
|
}
|
|
146
152
|
|
|
153
|
+
function icon(c, value, path) {
|
|
154
|
+
c.optional(value, 'icon', v => (typeof v === 'string' && v.length <= 48 && ICON_PATTERN.test(v)) || c.fail(join(path, 'icon'), 'must be an icon name like plane-takeoff'))
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** A window of time, `{ from, to }`, both ISO date-times with a zone, `to` after `from`. */
|
|
158
|
+
function timeWindow(c, value, path) {
|
|
159
|
+
if (!c.object(value, path, ['from', 'to'])) return
|
|
160
|
+
const fromOk = c.dateTime(value.from, join(path, 'from'))
|
|
161
|
+
const toOk = c.dateTime(value.to, join(path, 'to'))
|
|
162
|
+
if (fromOk && toOk && Date.parse(value.to) <= Date.parse(value.from)) c.fail(join(path, 'to'), 'must be after from')
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** The optional icon, tone, key and active window of a list or status row; keys must not repeat within a card. */
|
|
166
|
+
function rowLook(c, row, path, keys, { toneRequired = false } = {}) {
|
|
167
|
+
icon(c, row, path)
|
|
168
|
+
if (!toneRequired) tone(c, row, path)
|
|
169
|
+
c.optional(row, 'key', v => {
|
|
170
|
+
if (typeof v !== 'string' || !KEY_PATTERN.test(v)) return c.fail(join(path, 'key'), 'must be letters, digits and . _ : - (up to 100), starting with a letter or digit')
|
|
171
|
+
if (keys.has(v)) return c.fail(join(path, 'key'), 'repeats another row\'s key')
|
|
172
|
+
keys.add(v)
|
|
173
|
+
})
|
|
174
|
+
c.optional(row, 'active', v => timeWindow(c, v, join(path, 'active')))
|
|
175
|
+
}
|
|
176
|
+
|
|
147
177
|
/** Problems with an `actions` list (on a card, a list row or a status row). */
|
|
148
178
|
function actions(c, list, path) {
|
|
149
179
|
if (!c.array(list, path, { max: MAX_ACTIONS })) return
|
|
@@ -182,7 +212,7 @@ function statData(c, data, path) {
|
|
|
182
212
|
if (!c.array(data.items, join(path, 'items'), { min: 1, max: 6 })) return
|
|
183
213
|
data.items.forEach((item, i) => {
|
|
184
214
|
const p = join(join(path, 'items'), i)
|
|
185
|
-
if (!c.object(item, p, ['label', 'value'], ['unit', 'delta', 'sub', 'tone'])) return
|
|
215
|
+
if (!c.object(item, p, ['label', 'value'], ['unit', 'delta', 'sub', 'tone', 'spark', 'progress', 'strip'])) return
|
|
186
216
|
c.label(item.label, join(p, 'label'))
|
|
187
217
|
c.labelOrNumber(item.value, join(p, 'value'))
|
|
188
218
|
c.optional(item, 'unit', v => c.label(v, join(p, 'unit'), { max: 20 }))
|
|
@@ -190,10 +220,32 @@ function statData(c, data, path) {
|
|
|
190
220
|
tone(c, item, p)
|
|
191
221
|
c.optional(item, 'delta', delta => {
|
|
192
222
|
const dp = join(p, 'delta')
|
|
193
|
-
if (!c.object(delta, dp, ['
|
|
194
|
-
c.
|
|
195
|
-
c.optional(delta, 'unit', v => c.label(v, join(dp, 'unit'), { max: 20 }))
|
|
223
|
+
if (!c.object(delta, dp, ['text'], ['tone', 'dir'])) return
|
|
224
|
+
c.label(delta.text, join(dp, 'text'), { max: 80 })
|
|
196
225
|
tone(c, delta, dp)
|
|
226
|
+
c.optional(delta, 'dir', v => c.oneOf(v, join(dp, 'dir'), DIRECTIONS))
|
|
227
|
+
})
|
|
228
|
+
c.optional(item, 'spark', spark => {
|
|
229
|
+
if (!c.array(spark, join(p, 'spark'), { min: 2, max: 400 })) return
|
|
230
|
+
spark.forEach((v, j) => v === null || c.number(v, join(join(p, 'spark'), j)))
|
|
231
|
+
})
|
|
232
|
+
c.optional(item, 'progress', progress => {
|
|
233
|
+
const pp = join(p, 'progress')
|
|
234
|
+
if (!c.object(progress, pp, ['value', 'max'], ['text'])) return
|
|
235
|
+
c.number(progress.value, join(pp, 'value'), { min: 0 })
|
|
236
|
+
c.number(progress.max, join(pp, 'max'), { min: 0 })
|
|
237
|
+
c.optional(progress, 'text', v => c.label(v, join(pp, 'text')))
|
|
238
|
+
})
|
|
239
|
+
c.optional(item, 'strip', strip => {
|
|
240
|
+
if (!c.array(strip, join(p, 'strip'), { min: 1, max: 24 })) return
|
|
241
|
+
strip.forEach((cell, j) => {
|
|
242
|
+
const sp = join(join(p, 'strip'), j)
|
|
243
|
+
if (!c.object(cell, sp, ['label', 'value'], ['icon', 'on'])) return
|
|
244
|
+
c.label(cell.label, join(sp, 'label'), { max: 20 })
|
|
245
|
+
c.labelOrNumber(cell.value, join(sp, 'value'))
|
|
246
|
+
icon(c, cell, sp)
|
|
247
|
+
c.optional(cell, 'on', v => c.boolean(v, join(sp, 'on')))
|
|
248
|
+
})
|
|
197
249
|
})
|
|
198
250
|
})
|
|
199
251
|
}
|
|
@@ -291,10 +343,12 @@ function donutData(c, data, path) {
|
|
|
291
343
|
|
|
292
344
|
function listData(c, data, path) {
|
|
293
345
|
if (!c.object(data, path, ['rows'], ['empty', 'progress'])) return
|
|
346
|
+
const keys = new Set()
|
|
294
347
|
if (c.array(data.rows, join(path, 'rows'), { max: 100 }))
|
|
295
348
|
data.rows.forEach((row, i) => {
|
|
296
349
|
const p = join(join(path, 'rows'), i)
|
|
297
|
-
if (!c.object(row, p, ['title'], ['sub', 'chip', 'checked', 'date', 'actions'])) return
|
|
350
|
+
if (!c.object(row, p, ['title'], ['sub', 'chip', 'checked', 'date', 'actions', 'icon', 'tone', 'key', 'active'])) return
|
|
351
|
+
rowLook(c, row, p, keys)
|
|
298
352
|
c.optional(row, 'actions', v => actions(c, v, join(p, 'actions')))
|
|
299
353
|
c.label(row.title, join(p, 'title'))
|
|
300
354
|
c.optional(row, 'sub', v => c.label(v, join(p, 'sub')))
|
|
@@ -310,11 +364,12 @@ function listData(c, data, path) {
|
|
|
310
364
|
c.optional(data, 'empty', v => c.label(v, join(path, 'empty')))
|
|
311
365
|
c.optional(data, 'progress', progress => {
|
|
312
366
|
const p = join(path, 'progress')
|
|
313
|
-
if (!c.object(progress, p, ['done', 'total'], ['label'])) return
|
|
367
|
+
if (!c.object(progress, p, ['done', 'total'], ['label', 'sub'])) return
|
|
314
368
|
const done = c.number(progress.done, join(p, 'done'), { min: 0 })
|
|
315
369
|
const total = c.number(progress.total, join(p, 'total'), { min: 0 })
|
|
316
370
|
if (done && total && progress.done > progress.total) c.fail(join(p, 'done'), 'must not be more than total')
|
|
317
371
|
c.optional(progress, 'label', v => c.label(v, join(p, 'label'), { max: 40 }))
|
|
372
|
+
c.optional(progress, 'sub', v => c.label(v, join(p, 'sub')))
|
|
318
373
|
})
|
|
319
374
|
}
|
|
320
375
|
|
|
@@ -351,9 +406,11 @@ function timelineData(c, data, path) {
|
|
|
351
406
|
function statusData(c, data, path) {
|
|
352
407
|
if (!c.object(data, path, ['rows'])) return
|
|
353
408
|
if (!c.array(data.rows, join(path, 'rows'), { min: 1, max: 50 })) return
|
|
409
|
+
const keys = new Set()
|
|
354
410
|
data.rows.forEach((row, i) => {
|
|
355
411
|
const p = join(join(path, 'rows'), i)
|
|
356
|
-
if (!c.object(row, p, ['label', 'value', 'tone'], ['sub', 'spark', 'actions'])) return
|
|
412
|
+
if (!c.object(row, p, ['label', 'value', 'tone'], ['sub', 'spark', 'actions', 'icon', 'key', 'active'])) return
|
|
413
|
+
rowLook(c, row, p, keys, { toneRequired: true })
|
|
357
414
|
c.optional(row, 'actions', v => actions(c, v, join(p, 'actions')))
|
|
358
415
|
c.label(row.label, join(p, 'label'))
|
|
359
416
|
c.labelOrNumber(row.value, join(p, 'value'))
|
|
@@ -366,7 +423,55 @@ function statusData(c, data, path) {
|
|
|
366
423
|
})
|
|
367
424
|
}
|
|
368
425
|
|
|
369
|
-
|
|
426
|
+
function summaryData(c, data, path) {
|
|
427
|
+
if (!c.object(data, path, ['text'], ['chips'])) return
|
|
428
|
+
c.label(data.text, join(path, 'text'), { max: 400 })
|
|
429
|
+
c.optional(data, 'chips', chips => {
|
|
430
|
+
if (!c.array(chips, join(path, 'chips'), { max: 8 })) return
|
|
431
|
+
chips.forEach((chip, i) => {
|
|
432
|
+
const p = join(join(path, 'chips'), i)
|
|
433
|
+
if (!c.object(chip, p, ['text'], ['icon', 'tone', 'to'])) return
|
|
434
|
+
c.label(chip.text, join(p, 'text'), { max: 60 })
|
|
435
|
+
icon(c, chip, p)
|
|
436
|
+
tone(c, chip, p)
|
|
437
|
+
c.optional(chip, 'to', v => c.dateTime(v, join(p, 'to')))
|
|
438
|
+
})
|
|
439
|
+
})
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
function countdownData(c, data, path) {
|
|
443
|
+
if (!c.object(data, path, ['to', 'label'], ['sub', 'steps', 'expiresAt'])) return
|
|
444
|
+
const toOk = c.dateTime(data.to, join(path, 'to'))
|
|
445
|
+
c.label(data.label, join(path, 'label'))
|
|
446
|
+
c.optional(data, 'sub', v => c.label(v, join(path, 'sub')))
|
|
447
|
+
c.optional(data, 'expiresAt', v => {
|
|
448
|
+
if (c.dateTime(v, join(path, 'expiresAt')) && toOk && Date.parse(v) < Date.parse(data.to)) c.fail(join(path, 'expiresAt'), 'must not be before to')
|
|
449
|
+
})
|
|
450
|
+
c.optional(data, 'steps', steps => {
|
|
451
|
+
if (!c.array(steps, join(path, 'steps'), { min: 1, max: 8 })) return
|
|
452
|
+
steps.forEach((step, i) => {
|
|
453
|
+
const p = join(join(path, 'steps'), i)
|
|
454
|
+
if (!c.object(step, p, ['at', 'label'], ['sub', 'zone'])) return
|
|
455
|
+
c.dateTime(step.at, join(p, 'at'))
|
|
456
|
+
c.label(step.label, join(p, 'label'), { max: 80 })
|
|
457
|
+
c.optional(step, 'sub', v => c.label(v, join(p, 'sub'), { max: 80 }))
|
|
458
|
+
c.optional(step, 'zone', v => (typeof v === 'string' && isTimeZone(v)) || c.fail(join(p, 'zone'), 'must be an IANA time zone like Europe/Paris'))
|
|
459
|
+
})
|
|
460
|
+
})
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
/** A time zone name this runtime knows. */
|
|
464
|
+
function isTimeZone(value) {
|
|
465
|
+
if (value.length > 64) return false
|
|
466
|
+
try {
|
|
467
|
+
new Intl.DateTimeFormat('en', { timeZone: value })
|
|
468
|
+
return true
|
|
469
|
+
} catch {
|
|
470
|
+
return false
|
|
471
|
+
}
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
const DATA = { summary: summaryData, countdown: countdownData, stat: statData, line: lineData, bar: barData, donut: donutData, list: listData, timeline: timelineData, status: statusData }
|
|
370
475
|
|
|
371
476
|
/** Links a card may open: web pages and paths on the same site, nothing that runs script. */
|
|
372
477
|
export function isSafeLink(value) {
|
|
@@ -383,14 +488,16 @@ export function isSafeLink(value) {
|
|
|
383
488
|
/** Problems with one card file's parsed content. */
|
|
384
489
|
export function checkCard(card) {
|
|
385
490
|
const c = new Check()
|
|
386
|
-
if (!c.object(card, '', ['type', 'title', 'updatedAt', 'data'], ['staleAfter', 'link', 'stat', 'actions'])) return c.problems
|
|
491
|
+
if (!c.object(card, '', ['type', 'title', 'updatedAt', 'data'], ['staleAfter', 'link', 'stat', 'actions', 'icon', 'tone'])) return c.problems
|
|
387
492
|
if (!c.oneOf(card.type, 'type', CARD_TYPES)) return c.problems
|
|
388
493
|
c.label(card.title, 'title', { max: 120 })
|
|
389
494
|
c.dateTime(card.updatedAt, 'updatedAt')
|
|
495
|
+
icon(c, card, '')
|
|
496
|
+
tone(c, card, '')
|
|
390
497
|
c.optional(card, 'staleAfter', v => c.number(v, 'staleAfter', { min: 1 }))
|
|
391
498
|
c.optional(card, 'link', v => isSafeLink(v) || c.fail('link', 'must be an http(s) URL or a path starting with /'))
|
|
392
499
|
c.optional(card, 'stat', v => {
|
|
393
|
-
if (
|
|
500
|
+
if (['stat', 'summary', 'countdown'].includes(card.type)) return c.fail('stat', `doesn't go on a ${card.type} card; it heads a card's chart or rows`)
|
|
394
501
|
statData(c, v, 'stat')
|
|
395
502
|
})
|
|
396
503
|
c.optional(card, 'actions', v => actions(c, v, 'actions'))
|
package/src/seen.js
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* "New since you last looked", kept per person on the server so it holds
|
|
3
|
+
* across devices.
|
|
4
|
+
*
|
|
5
|
+
* Each card has a content version (a hash of the card without `updatedAt`, so
|
|
6
|
+
* a producer rewriting the same data changes nothing), and each list or status
|
|
7
|
+
* row with a `key` has its own. The page tells the server which versions the
|
|
8
|
+
* person has seen; a later version is new for them. A person who never looked
|
|
9
|
+
* at a board sees nothing marked new there.
|
|
10
|
+
*
|
|
11
|
+
* <dataDir>/.seen/<hash of the person>.json
|
|
12
|
+
* { "boards": { "<board>": { "<card>": { "v": "…", "rows": { "<key>": "…" } } } } }
|
|
13
|
+
*/
|
|
14
|
+
import { createHash } from 'node:crypto'
|
|
15
|
+
import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
|
|
16
|
+
import { join } from 'node:path'
|
|
17
|
+
import { ID_PATTERN, KEY_PATTERN } from './schema.js'
|
|
18
|
+
|
|
19
|
+
const VERSION = /^[A-Za-z0-9_-]{1,32}$/
|
|
20
|
+
const MAX_ROWS = 100
|
|
21
|
+
|
|
22
|
+
function hash(value) {
|
|
23
|
+
return createHash('sha256').update(JSON.stringify(value)).digest('base64url').slice(0, 12)
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** The content version of a card, and of each of its keyed rows. */
|
|
27
|
+
export function cardVersions(card) {
|
|
28
|
+
const { updatedAt, ...content } = card
|
|
29
|
+
const rows = {}
|
|
30
|
+
if (card.type === 'list' || card.type === 'status') for (const row of card.data?.rows ?? []) if (typeof row.key === 'string') rows[row.key] = hash(row)
|
|
31
|
+
return Object.keys(rows).length > 0 ? { version: hash(content), rows } : { version: hash(content) }
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* What is new for a person in one card: `{ card: true }` when its version differs from the one they saw (or they
|
|
36
|
+
* never saw the card), with `rows` listing keyed rows that are new or changed. Undefined when nothing is new, or
|
|
37
|
+
* when they have never looked at the board at all.
|
|
38
|
+
*/
|
|
39
|
+
export function freshness(seenBoard, versions) {
|
|
40
|
+
if (seenBoard === undefined) return undefined
|
|
41
|
+
const seen = seenBoard[versions.id]
|
|
42
|
+
if (seen === undefined) return { card: true, rows: [] }
|
|
43
|
+
if (seen.v === versions.version) return undefined
|
|
44
|
+
const rows = Object.entries(versions.rows ?? {}).filter(([key, v]) => seen.rows?.[key] !== v).map(([key]) => key)
|
|
45
|
+
return { card: true, rows }
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** The body of a "seen" report from the page, checked: `{ board, cards: { <id>: { v, rows? } } }`; undefined when malformed. */
|
|
49
|
+
export function parseSeen(body) {
|
|
50
|
+
if (typeof body !== 'object' || body === null || typeof body.board !== 'string' || !ID_PATTERN.test(body.board)) return undefined
|
|
51
|
+
const cards = body.cards
|
|
52
|
+
if (typeof cards !== 'object' || cards === null || Array.isArray(cards) || Object.keys(cards).length > 100) return undefined
|
|
53
|
+
const clean = {}
|
|
54
|
+
for (const [id, seen] of Object.entries(cards)) {
|
|
55
|
+
if (!ID_PATTERN.test(id) || typeof seen?.v !== 'string' || !VERSION.test(seen.v)) return undefined
|
|
56
|
+
const rows = {}
|
|
57
|
+
const given = seen.rows ?? {}
|
|
58
|
+
if (typeof given !== 'object' || given === null || Object.keys(given).length > MAX_ROWS) return undefined
|
|
59
|
+
for (const [key, v] of Object.entries(given)) {
|
|
60
|
+
if (!KEY_PATTERN.test(key) || typeof v !== 'string' || !VERSION.test(v)) return undefined
|
|
61
|
+
rows[key] = v
|
|
62
|
+
}
|
|
63
|
+
clean[id] = Object.keys(rows).length > 0 ? { v: seen.v, rows } : { v: seen.v }
|
|
64
|
+
}
|
|
65
|
+
return { board: body.board, cards: clean }
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** The seen marks of every person, one small file each, written one at a time and atomically. */
|
|
69
|
+
export function createSeenStore(dir) {
|
|
70
|
+
const fileOf = person => join(dir, `${hash(String(person).toLowerCase())}.json`)
|
|
71
|
+
const queues = new Map()
|
|
72
|
+
|
|
73
|
+
async function readFileOf(person) {
|
|
74
|
+
try {
|
|
75
|
+
const value = JSON.parse(await readFile(fileOf(person), 'utf8'))
|
|
76
|
+
return typeof value?.boards === 'object' && value.boards !== null ? value : { boards: {} }
|
|
77
|
+
} catch {
|
|
78
|
+
return { boards: {} }
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
return {
|
|
83
|
+
/** What a person has seen on a board, by card id; undefined when they never looked at it. */
|
|
84
|
+
async board(person, board) {
|
|
85
|
+
return (await readFileOf(person)).boards[board]
|
|
86
|
+
},
|
|
87
|
+
|
|
88
|
+
/** A tag that changes whenever this person's marks change, for ETags. */
|
|
89
|
+
async tag(person) {
|
|
90
|
+
const info = await stat(fileOf(person)).catch(() => undefined)
|
|
91
|
+
return info ? `${info.size}:${info.mtimeMs}` : '-'
|
|
92
|
+
},
|
|
93
|
+
|
|
94
|
+
/** Record cards a person has seen on a board, keeping only cards that still exist (`present`). */
|
|
95
|
+
record(person, board, cards, present) {
|
|
96
|
+
const path = fileOf(person)
|
|
97
|
+
const previous = queues.get(path) ?? Promise.resolve()
|
|
98
|
+
const next = previous.catch(() => {}).then(async () => {
|
|
99
|
+
const value = await readFileOf(person)
|
|
100
|
+
const kept = Object.fromEntries(Object.entries({ ...value.boards[board], ...cards }).filter(([id]) => present.has(id)))
|
|
101
|
+
value.boards[board] = kept
|
|
102
|
+
await mkdir(dir, { recursive: true, mode: 0o700 })
|
|
103
|
+
const tmp = `${path}.${process.pid}.tmp`
|
|
104
|
+
await writeFile(tmp, JSON.stringify(value), { mode: 0o600 })
|
|
105
|
+
await rename(tmp, path)
|
|
106
|
+
})
|
|
107
|
+
queues.set(path, next)
|
|
108
|
+
return next.finally(() => { if (queues.get(path) === next) queues.delete(path) })
|
|
109
|
+
},
|
|
110
|
+
}
|
|
111
|
+
}
|
package/src/store.js
CHANGED
|
@@ -116,6 +116,16 @@ export async function boardTag(root, id, salt = '') {
|
|
|
116
116
|
return `W/"${hash.digest('base64url').slice(0, 27)}"`
|
|
117
117
|
}
|
|
118
118
|
|
|
119
|
+
/** A cheap version tag for one card: its file, board.json (the card's size lives there) and `salt`. */
|
|
120
|
+
export async function cardTag(root, board, card, salt = '') {
|
|
121
|
+
const hash = createHash('sha256').update(salt)
|
|
122
|
+
for (const path of [join(root, board, 'board.json'), cardPath(root, board, card)]) {
|
|
123
|
+
const info = await stat(path).catch(() => undefined)
|
|
124
|
+
hash.update(`${info ? `${info.size}:${info.mtimeMs}` : '-'}\n`)
|
|
125
|
+
}
|
|
126
|
+
return `W/"${hash.digest('base64url').slice(0, 27)}"`
|
|
127
|
+
}
|
|
128
|
+
|
|
119
129
|
/** The path of a card file (ids already checked). */
|
|
120
130
|
export function cardPath(root, board, card) {
|
|
121
131
|
return join(root, board, 'cards', `${card}.json`)
|
|
@@ -128,11 +138,15 @@ export async function readCard(root, board, card) {
|
|
|
128
138
|
return result.problems.length === 0 ? result.value : undefined
|
|
129
139
|
}
|
|
130
140
|
|
|
131
|
-
/**
|
|
132
|
-
|
|
141
|
+
/**
|
|
142
|
+
* Every card of a board in order, each with its size on the grid and either the card or its problems; with `only`,
|
|
143
|
+
* just that card (an empty list when it isn't there).
|
|
144
|
+
*/
|
|
145
|
+
export async function readCards(root, id, board, only) {
|
|
133
146
|
const layout = board?.layout ?? {}
|
|
134
147
|
const cards = []
|
|
135
|
-
|
|
148
|
+
const ids = await cardFiles(root, id, board?.order)
|
|
149
|
+
for (const card of only === undefined ? ids : ids.filter(card => card === only)) {
|
|
136
150
|
const size = { w: layout[card]?.w ?? 1, h: layout[card]?.h ?? 1 }
|
|
137
151
|
const result = await readJson(root, join(root, id, 'cards', `${card}.json`), MAX_CARD_BYTES, checkCard)
|
|
138
152
|
cards.push(result.problems.length > 0 ? { id: card, ...size, problems: result.problems.slice(0, 5) } : { id: card, ...size, card: result.value })
|
package/src/watch.js
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Noticing changes to a board's files, for the live events route.
|
|
3
|
+
*
|
|
4
|
+
* One watch per board, shared by every page that has it open. `fs.watch` on
|
|
5
|
+
* the board folder and its cards folder only triggers a rescan; a slower stat
|
|
6
|
+
* poll does the same where watching is unreliable (network file systems, some
|
|
7
|
+
* containers). The scan compares file sizes and times, so what reaches the
|
|
8
|
+
* listeners is exact: `{ type: 'card', id }` for a card written, added or
|
|
9
|
+
* removed, `{ type: 'board' }` for board.json.
|
|
10
|
+
*/
|
|
11
|
+
import { watch as fsWatch } from 'node:fs'
|
|
12
|
+
import { readdir, stat } from 'node:fs/promises'
|
|
13
|
+
import { join } from 'node:path'
|
|
14
|
+
import { ID_PATTERN } from './schema.js'
|
|
15
|
+
|
|
16
|
+
async function snapshot(dir) {
|
|
17
|
+
const files = new Map()
|
|
18
|
+
const add = async (name, path) => {
|
|
19
|
+
const info = await stat(path).catch(() => undefined)
|
|
20
|
+
if (info?.isFile()) files.set(name, `${info.size}:${info.mtimeMs}`)
|
|
21
|
+
}
|
|
22
|
+
await add('board.json', join(dir, 'board.json'))
|
|
23
|
+
const names = await readdir(join(dir, 'cards')).catch(() => [])
|
|
24
|
+
for (const name of names) if (name.endsWith('.json') && ID_PATTERN.test(name.slice(0, -5))) await add(name, join(dir, 'cards', name))
|
|
25
|
+
return files
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** What changed between two snapshots, as events. */
|
|
29
|
+
export function changes(before, after) {
|
|
30
|
+
const names = new Set([...before.keys(), ...after.keys()])
|
|
31
|
+
const events = []
|
|
32
|
+
for (const name of [...names].sort()) {
|
|
33
|
+
if (before.get(name) === after.get(name)) continue
|
|
34
|
+
events.push(name === 'board.json' ? { type: 'board' } : { type: 'card', id: name.slice(0, -5) })
|
|
35
|
+
}
|
|
36
|
+
return events
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* @param {object} [options]
|
|
41
|
+
* @param {number} [options.pollMs] - the stat poll's interval (default 10 s)
|
|
42
|
+
* @param {number} [options.settleMs] - how long a burst of file events is gathered before one scan (default 120 ms)
|
|
43
|
+
*/
|
|
44
|
+
export function createWatches({ pollMs = 10_000, settleMs = 120 } = {}) {
|
|
45
|
+
const boards = new Map()
|
|
46
|
+
|
|
47
|
+
function open(dir) {
|
|
48
|
+
const entry = { listeners: new Set(), files: null, watchers: [], timer: null, poll: null, scanning: null }
|
|
49
|
+
const scan = async () => {
|
|
50
|
+
// One scan at a time; a request during a scan runs once more after it.
|
|
51
|
+
if (entry.scanning) { entry.again = true; return entry.scanning }
|
|
52
|
+
entry.scanning = (async () => {
|
|
53
|
+
do {
|
|
54
|
+
entry.again = false
|
|
55
|
+
const files = await snapshot(dir)
|
|
56
|
+
const events = entry.files === null ? [] : changes(entry.files, files)
|
|
57
|
+
entry.files = files
|
|
58
|
+
for (const event of events) for (const listener of entry.listeners) listener(event)
|
|
59
|
+
} while (entry.again)
|
|
60
|
+
})().finally(() => { entry.scanning = null })
|
|
61
|
+
return entry.scanning
|
|
62
|
+
}
|
|
63
|
+
const soon = () => {
|
|
64
|
+
clearTimeout(entry.timer)
|
|
65
|
+
entry.timer = setTimeout(scan, settleMs)
|
|
66
|
+
}
|
|
67
|
+
for (const path of [dir, join(dir, 'cards')]) {
|
|
68
|
+
try {
|
|
69
|
+
entry.watchers.push(fsWatch(path, { persistent: false }, soon).on('error', () => {}))
|
|
70
|
+
} catch {
|
|
71
|
+
// a missing cards folder: the poll notices when it appears
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
entry.poll = setInterval(scan, pollMs)
|
|
75
|
+
entry.poll.unref?.()
|
|
76
|
+
entry.ready = scan()
|
|
77
|
+
entry.close = () => {
|
|
78
|
+
clearTimeout(entry.timer)
|
|
79
|
+
clearInterval(entry.poll)
|
|
80
|
+
for (const watcher of entry.watchers) watcher.close()
|
|
81
|
+
}
|
|
82
|
+
return entry
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
return {
|
|
86
|
+
/**
|
|
87
|
+
* Call `listener` with each change to the board in `dir` until the returned function is called. Resolves once
|
|
88
|
+
* the first scan is done, so changes after that are all reported.
|
|
89
|
+
*/
|
|
90
|
+
async watch(dir, listener) {
|
|
91
|
+
let entry = boards.get(dir)
|
|
92
|
+
if (entry === undefined) {
|
|
93
|
+
entry = open(dir)
|
|
94
|
+
boards.set(dir, entry)
|
|
95
|
+
}
|
|
96
|
+
entry.listeners.add(listener)
|
|
97
|
+
await entry.ready
|
|
98
|
+
return () => {
|
|
99
|
+
entry.listeners.delete(listener)
|
|
100
|
+
if (entry.listeners.size === 0 && boards.get(dir) === entry) {
|
|
101
|
+
entry.close()
|
|
102
|
+
boards.delete(dir)
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
},
|
|
106
|
+
|
|
107
|
+
/** Stop every watch (the plugin is unloading). */
|
|
108
|
+
close() {
|
|
109
|
+
for (const entry of boards.values()) entry.close()
|
|
110
|
+
boards.clear()
|
|
111
|
+
},
|
|
112
|
+
}
|
|
113
|
+
}
|