@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/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, ['value'], ['unit', 'tone'])) return
194
- c.number(delta.value, join(dp, 'value'))
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
- const DATA = { stat: statData, line: lineData, bar: barData, donut: donutData, list: listData, timeline: timelineData, status: statusData }
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 (card.type === 'stat') return c.fail('stat', 'is for chart cards; a stat card has its numbers in data')
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
- /** Every card of a board in order, each with its size on the grid and either the card or its problems. */
132
- export async function readCards(root, id, board) {
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
- for (const card of await cardFiles(root, id, board?.order)) {
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
+ }