notes

5.7 KB

1. // lib/notes.hl — THE NOTES (ticket notes#1) and their SYNC (ticket notes#2). One hl:mpackdb table, storage/mpackdb/notes.db:
2. // pk @id index owner { owner (users @id), text (Markdown), created, edited, gone, local } times = ms
3. // gone = ms a note was deleted (0 = alive; the row stays as a TOMBSTONE so other devices learn of the delete);
4. // local = the id the creating device gave the note before it had a server id (makes a retried push idempotent)
5. // The SUBJECT of a note is not stored: it is the first non-empty line of the text, without leading `#`
6. // (CONCEPT.md "Decisions"); the browser (notes-offline.js) derives it and orders the sidebar by `edited`.
7. // Every function takes the owner's user id and only ever reaches that user's notes. Every write to the table is here.
8. // The browser keeps its own copy (IndexedDB) and pushes/pulls through /api/notes (lib/api.hl). A note's VERSION is its
9. // `edited` (ms); the browser remembers the `edited` it last saw of a note (`base`).
10. // Looked up in lib/notes-helpers.hl: textError (size limit), isAlive (tombstones), stampOf (version stamps), copyMark.
11. import { MPackDB } from 'hl:mpackdb'
12. import { now } from 'hl:time'
13. import { storageDir, countOfList } from './util.hl'
14. import { textError, isAlive, stampOf, copyMark } from './notes-helpers.hl'
16. static notesTable = new MPackDB(file = storageDir + '/notes.db', primaryKey = '@id', indexes = ['owner'])
18. // one note of this owner, or null
19. static noteOf = (userId, id) => {
20. if (id == null || hlTypeName(id) != 'String' || id == '') { return null }
21. n = notesTable.fetch(id)
22. if (n == null || n.owner != userId || !isAlive(n)) { return null }
23. return n
24. }
26. // what the browser needs to compare: id, edited, gone (no text) of every note of the owner, tombstones included
27. static metaRows = (userId) => {
28. found = notesTable.find('owner', userId)
29. out = []
30. let i = 0
31. n = countOfList(found)
32. while (i < n) {
33. out.push({ id = found[i].id edited = found[i].edited gone = isAlive(found[i]) ? 0 : found[i].gone })
34. i = i + 1
35. }
36. return out
37. }
39. // one note with its text, or null
40. static noteView = (userId, id) => {
41. n = noteOf(userId, id)
42. return n == null ? null : { id = n.id text = n.text edited = n.edited created = n.created }
43. }
45. static newNote = (userId, text, local, edited) => {
46. t = now()
47. id = notesTable.put({ owner = userId text = text created = t edited = stampOf(edited, 0) gone = 0 local = local })
48. return id
49. }
51. // a note pushed by a browser: { id (server id or ''), local (the browser's own id of a never-synced note), text,
52. // base (the `edited` the browser last saw, 0 = never), at (when the browser last edited it) }
53. // → { id, edited, text, copy? }: `text` is what the note is NOW (the browser takes it); `copy` = { id, edited, text }
54. // is the version that lost a conflict, kept as a note of its own — nothing is ever lost.
55. static pushNote = (userId, id, local, text, base, at) => {
56. bad = textError(text)
57. if (bad != null) { return { error = bad } }
58. let n = null
59. if (id != '') { n = noteOf(userId, id) }
60. if (n == null && local != '') {
61. // a retry after a lost answer: the note the same browser already made
62. mine = notesTable.find('owner', userId)
63. let i = 0
64. c = countOfList(mine)
65. while (i < c && n == null) {
66. if (isAlive(mine[i]) && mine[i].local == local) { n = mine[i] }
67. i = i + 1
68. }
69. }
70. if (n == null) {
71. // a new note (or one deleted elsewhere while this browser edited it: the edit becomes a note again)
72. nid = newNote(userId, text, local, at > 0 ? at : now())
73. if (nid == null) { return { error = 'could not store the note: ' + notesTable.lastError() } }
74. made = notesTable.fetch(nid)
75. return { id = nid edited = made.edited text = text }
76. }
77. if (n.text == text) { return { id = n.id edited = n.edited text = n.text } }
78. if (n.edited == base) {
79. ed = stampOf(at, n.edited)
80. notesTable.update(n.id, { id = n.id owner = userId text = text created = n.created edited = ed gone = 0 local = n.local == null ? '' : n.local })
81. after = notesTable.fetch(n.id)
82. if (after == null || after.text != text) { return { error = 'could not store the note: ' + notesTable.lastError() } }
83. return { id = n.id edited = after.edited text = text }
84. }
85. // CONFLICT: changed here AND there. The later edit wins (last write wins); the other version becomes a copy.
86. serverText = n.text
87. serverEdited = n.edited
88. if (at > serverEdited) {
89. cid = newNote(userId, serverText + copyMark, '', serverEdited)
90. ed = stampOf(at, n.edited)
91. notesTable.update(n.id, { id = n.id owner = userId text = text created = n.created edited = ed gone = 0 local = n.local == null ? '' : n.local })
92. after = notesTable.fetch(n.id)
93. cp = cid == null ? null : notesTable.fetch(cid)
94. return { id = n.id edited = after.edited text = text copy = cp == null ? null : { id = cp.id edited = cp.edited text = cp.text } }
95. }
96. cid = newNote(userId, text + copyMark, '', at)
97. cp = cid == null ? null : notesTable.fetch(cid)
98. return { id = n.id edited = n.edited text = n.text copy = cp == null ? null : { id = cp.id edited = cp.edited text = cp.text } }
99. }
101. // a delete pushed by a browser. Deleted elsewhere already = fine. Changed elsewhere since the browser's `base`
102. // = NOT deleted (the changed note is kept; the browser takes it back). Deleted = a tombstone (text '', gone = now).
103. static removeNote = (userId, id, base) => {
104. raw = id == null || hlTypeName(id) != 'String' || id == '' ? null : notesTable.fetch(id)
105. if (raw == null || raw.owner != userId) { return { ok = true } }
106. if (!isAlive(raw)) { return { ok = true } }
107. if (raw.edited != base) { return { kept = true id = raw.id edited = raw.edited text = raw.text } }
108. notesTable.update(id, { id = id owner = userId text = '' created = raw.created edited = raw.edited gone = now() local = raw.local == null ? '' : raw.local })
109. return { ok = true }
110. }