@estiva-app/interop 0.72.0 → 0.73.0
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 +33 -0
- package/dist/fields.d.ts +205 -0
- package/dist/fields.d.ts.map +1 -0
- package/dist/fields.js +250 -0
- package/dist/fields.js.map +1 -0
- package/dist/folders.d.ts +2 -0
- package/dist/folders.d.ts.map +1 -1
- package/dist/folders.js +6 -0
- package/dist/folders.js.map +1 -1
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -1
- package/dist/projection.d.ts +11 -0
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +23 -1
- package/dist/projection.js.map +1 -1
- package/package.json +3 -3
- package/src/fields.ts +346 -0
- package/src/folders.ts +7 -0
- package/src/index.ts +21 -0
- package/src/projection.ts +33 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@estiva-app/interop",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.73.0",
|
|
4
4
|
"description": "Render and act on another app's objects from its published NIP-89 manifest. The owner defines the projection; the consumer decides how it looks.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -48,11 +48,11 @@
|
|
|
48
48
|
},
|
|
49
49
|
"peerDependencies": {
|
|
50
50
|
"@estiva-app/conversation": ">=0.20.0",
|
|
51
|
-
"@estiva-app/protocol": ">=0.
|
|
51
|
+
"@estiva-app/protocol": ">=0.48.0"
|
|
52
52
|
},
|
|
53
53
|
"devDependencies": {
|
|
54
54
|
"@estiva-app/conversation": ">=0.20.0",
|
|
55
|
-
"@estiva-app/protocol": ">=0.
|
|
55
|
+
"@estiva-app/protocol": ">=0.48.0",
|
|
56
56
|
"typescript": "~5.9.3"
|
|
57
57
|
}
|
|
58
58
|
}
|
package/src/fields.ts
ADDED
|
@@ -0,0 +1,346 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A file as its fields, each kept in order by the relay — SPEC §6.2, §6.13.
|
|
3
|
+
*
|
|
4
|
+
* Two halves, both for any type the relay keeps:
|
|
5
|
+
*
|
|
6
|
+
* - **Reading** a list or one file with the relay's list read
|
|
7
|
+
* (`"fields": "newest"`), which answers each file's first record and, for
|
|
8
|
+
* each field, only its current change: a list never carries the text, and
|
|
9
|
+
* opening one file (`"text": true` beside `#d`) carries its current text and
|
|
10
|
+
* none of its history. Each change's id is that field's next `prev`.
|
|
11
|
+
* - **Writing** a change that names the one it follows, and answering the
|
|
12
|
+
* relay's `conflict:` as §6.2 says: a field set again keeps the later, and a
|
|
13
|
+
* text merges by §13.3's rule, or stops and asks when a block was changed by
|
|
14
|
+
* both or edited against a delete. It never writes over someone's newer
|
|
15
|
+
* words.
|
|
16
|
+
*
|
|
17
|
+
* Only for a relay whose NIP-11 advertises `file_list` (`relayFileReadsOf` in
|
|
18
|
+
* `@estiva-app/protocol`), and `"text"` only where it says `text`: a relay
|
|
19
|
+
* without them answers these reads as if they were plain ones.
|
|
20
|
+
*
|
|
21
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-its-fields-each-kept-in-order-by-the-relay.md
|
|
22
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/opening-a-file-reads-its-current-text-not-its-history.md
|
|
23
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/merging-two-changes-to-one-text-never-loses-words.md
|
|
24
|
+
*/
|
|
25
|
+
import {
|
|
26
|
+
CONTENT_FORMAT_TAG,
|
|
27
|
+
mergeTexts,
|
|
28
|
+
type MergeAsk,
|
|
29
|
+
type MergeText,
|
|
30
|
+
type SignedEvent,
|
|
31
|
+
type UnsignedEvent,
|
|
32
|
+
} from '@estiva-app/protocol'
|
|
33
|
+
import { folderOf, type QueryFn } from './projection.js'
|
|
34
|
+
|
|
35
|
+
/** The change event every Estiva app writes (SPEC §6.2). */
|
|
36
|
+
const KIND_CHANGE = 1851
|
|
37
|
+
|
|
38
|
+
/** The field that holds a file's text (§6.10): the one field that merges rather than re-sets. */
|
|
39
|
+
export const TEXT_FIELD = 'description'
|
|
40
|
+
|
|
41
|
+
/** One field's current value, and the change that set it. */
|
|
42
|
+
export interface CurrentField {
|
|
43
|
+
value: string
|
|
44
|
+
/** The value's `content-format`, for the text; absent for marker text. */
|
|
45
|
+
format?: string
|
|
46
|
+
/** The change's id: the field's next `prev`. */
|
|
47
|
+
id: string
|
|
48
|
+
/** Who set it. */
|
|
49
|
+
pubkey: string
|
|
50
|
+
/** When, in ms: `ts` where it agrees with `created_at` to the second (§6.2), else `created_at`. */
|
|
51
|
+
at: number
|
|
52
|
+
event: SignedEvent
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** A file read by its fields. */
|
|
56
|
+
export interface FileFields {
|
|
57
|
+
root: SignedEvent
|
|
58
|
+
/** `<kind>:<pubkey>:<d>`. */
|
|
59
|
+
address: string
|
|
60
|
+
/** Each field's current change. The text is here only when the file was opened with it. */
|
|
61
|
+
fields: Record<string, CurrentField>
|
|
62
|
+
/** The root and each current change, as signed — what a fold of every change would read the same. */
|
|
63
|
+
events: SignedEvent[]
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
const tagValue = (event: { tags: string[][] }, name: string) => event.tags.find((t) => t[0] === name)?.[1]
|
|
67
|
+
|
|
68
|
+
/** When a change happened, in ms, by §6.3's order. */
|
|
69
|
+
export function changedAt(event: SignedEvent): number {
|
|
70
|
+
const ts = Number(tagValue(event, 'ts'))
|
|
71
|
+
return Number.isFinite(ts) && Math.floor(ts / 1000) === event.created_at ? ts : event.created_at * 1000
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** Newer first by §6.3: time, then `created_at`, then id. */
|
|
75
|
+
function newer(a: SignedEvent, b: SignedEvent): boolean {
|
|
76
|
+
const at = changedAt(a) - changedAt(b)
|
|
77
|
+
if (at !== 0) return at > 0
|
|
78
|
+
if (a.created_at !== b.created_at) return a.created_at > b.created_at
|
|
79
|
+
return a.id > b.id
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The fields one change sets, with their values: one `field`/`value`, or one
|
|
84
|
+
* per `set` (§6.2). A change setting the text carries its `content-format`.
|
|
85
|
+
*/
|
|
86
|
+
export function fieldsSetBy(event: { tags: string[][] }): { field: string; value: string; format?: string }[] {
|
|
87
|
+
const format = tagValue(event, CONTENT_FORMAT_TAG)
|
|
88
|
+
const withFormat = (field: string, value: string) =>
|
|
89
|
+
field === TEXT_FIELD && format ? { field, value, format } : { field, value }
|
|
90
|
+
const sets = event.tags.filter((t) => t[0] === 'set' && typeof t[1] === 'string')
|
|
91
|
+
if (sets.length) return sets.map((t) => withFormat(t[1], t[2] ?? ''))
|
|
92
|
+
const field = tagValue(event, 'field')
|
|
93
|
+
return field === undefined ? [] : [withFormat(field, tagValue(event, 'value') ?? '')]
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
const addressOfRoot = (root: SignedEvent) => `${root.kind}:${root.pubkey}:${tagValue(root, 'd') ?? ''}`
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Each file the events hold, by its first record and the current change of each
|
|
100
|
+
* of its fields.
|
|
101
|
+
*
|
|
102
|
+
* A change counts only where §6.2 says a reader folds it: its `a` names the
|
|
103
|
+
* file, its `O` (if any) is the file's id, and its `h` is the file's home. The
|
|
104
|
+
* text counts only when `withText`: a list never takes the text from a change
|
|
105
|
+
* that set several fields, since a later text-only change may have replaced it
|
|
106
|
+
* (§6.13).
|
|
107
|
+
*/
|
|
108
|
+
export function filesOf(events: readonly SignedEvent[], options: { withText?: boolean } = {}): FileFields[] {
|
|
109
|
+
const roots = new Map<string, SignedEvent>()
|
|
110
|
+
for (const event of events) {
|
|
111
|
+
if (event.kind === KIND_CHANGE || tagValue(event, 'd') === undefined) continue
|
|
112
|
+
const address = addressOfRoot(event)
|
|
113
|
+
const held = roots.get(address)
|
|
114
|
+
if (!held || event.created_at > held.created_at) roots.set(address, event)
|
|
115
|
+
}
|
|
116
|
+
const files = new Map<string, FileFields>()
|
|
117
|
+
for (const [address, root] of roots) files.set(address, { root, address, fields: {}, events: [root] })
|
|
118
|
+
|
|
119
|
+
for (const event of events) {
|
|
120
|
+
if (event.kind !== KIND_CHANGE) continue
|
|
121
|
+
const file = files.get(tagValue(event, 'a') ?? '')
|
|
122
|
+
if (!file) continue
|
|
123
|
+
const O = tagValue(event, 'O')
|
|
124
|
+
if (O !== undefined && O !== tagValue(file.root, 'd')) continue
|
|
125
|
+
if (tagValue(event, 'h') !== (folderOf(file.root) ?? undefined)) continue
|
|
126
|
+
for (const set of fieldsSetBy(event)) {
|
|
127
|
+
if (set.field === TEXT_FIELD && !options.withText) continue
|
|
128
|
+
const held = file.fields[set.field]
|
|
129
|
+
if (held && !newer(event, held.event)) continue
|
|
130
|
+
file.fields[set.field] = { ...set, id: event.id, pubkey: event.pubkey, at: changedAt(event), event }
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
// The root and each change some field still points at, once.
|
|
134
|
+
for (const file of files.values()) {
|
|
135
|
+
const current = new Map(Object.values(file.fields).map((f) => [f.id, f.event]))
|
|
136
|
+
file.events = [file.root, ...current.values()]
|
|
137
|
+
}
|
|
138
|
+
return [...files.values()]
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* A list of files by the relay's list read: each first record the filter picks,
|
|
143
|
+
* with its fields' current changes and never its text (§6.13).
|
|
144
|
+
*
|
|
145
|
+
* `filter` picks first records, as §6.13 says: `#h` for a Folder's issues,
|
|
146
|
+
* `kinds` alone for the workspace's projects, `#d` for named ones, `search`
|
|
147
|
+
* for typing. Only for a relay advertising `file_list`.
|
|
148
|
+
*/
|
|
149
|
+
export async function listFiles(query: QueryFn, filter: Record<string, unknown>): Promise<FileFields[]> {
|
|
150
|
+
if ('text' in filter) throw new Error('A list never carries text; open one file to read it.')
|
|
151
|
+
const events = await query([{ ...filter, fields: 'newest' }])
|
|
152
|
+
return filesOf(events)
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* One file, opened: its first record, its fields' current changes and, where
|
|
157
|
+
* the relay says `file_list.text`, its current text — one text however long
|
|
158
|
+
* its history (§6.13, C40). Undefined when the relay holds no such file the
|
|
159
|
+
* reader may read.
|
|
160
|
+
*
|
|
161
|
+
* Without `text` the answer has no text field at all, which is not "the text
|
|
162
|
+
* was never changed": a caller that needs it reads it the old way.
|
|
163
|
+
*/
|
|
164
|
+
export async function openFile(
|
|
165
|
+
query: QueryFn,
|
|
166
|
+
file: { kind: number; pubkey: string; d: string },
|
|
167
|
+
options: { text: boolean },
|
|
168
|
+
): Promise<FileFields | undefined> {
|
|
169
|
+
// By `#d` alone, the shape §6.13 names; the author is checked below.
|
|
170
|
+
const filter: Record<string, unknown> = { fields: 'newest', kinds: [file.kind], '#d': [file.d] }
|
|
171
|
+
if (options.text) filter.text = true
|
|
172
|
+
const events = await query([filter])
|
|
173
|
+
const address = `${file.kind}:${file.pubkey}:${file.d}`
|
|
174
|
+
return filesOf(events, { withText: options.text }).find((f) => f.address === address)
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* The text a change or first record holds: a change's `description`, or a
|
|
179
|
+
* first record's seed — a project's `description` tag, then its `content`
|
|
180
|
+
* (§6.2, §7.2).
|
|
181
|
+
*/
|
|
182
|
+
export function textOf(event: SignedEvent): MergeText | undefined {
|
|
183
|
+
if (event.kind === KIND_CHANGE) {
|
|
184
|
+
const set = fieldsSetBy(event).find((f) => f.field === TEXT_FIELD)
|
|
185
|
+
return set ? { value: set.value, ...(set.format ? { format: set.format } : {}) } : undefined
|
|
186
|
+
}
|
|
187
|
+
const format = tagValue(event, CONTENT_FORMAT_TAG)
|
|
188
|
+
const value = tagValue(event, TEXT_FIELD) ?? event.content
|
|
189
|
+
return { value, ...(format ? { format } : {}) }
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** What a `conflict:` refusal says (§6.2), as the relay words it. */
|
|
193
|
+
export type Conflict =
|
|
194
|
+
| { kind: 'stale'; field: string; current?: string }
|
|
195
|
+
| { kind: 'sorts-before'; field: string }
|
|
196
|
+
| { kind: 'other' }
|
|
197
|
+
|
|
198
|
+
export function conflictOf(reason: string): Conflict | undefined {
|
|
199
|
+
if (!reason.startsWith('conflict:')) return undefined
|
|
200
|
+
const sorts = /^conflict: (\S+) does not sort after its prev\b/.exec(reason)
|
|
201
|
+
if (sorts) return { kind: 'sorts-before', field: sorts[1] }
|
|
202
|
+
const follows = /^conflict: (\S+) follows ([0-9a-f]{64})\s*$/.exec(reason)
|
|
203
|
+
if (follows) return { kind: 'stale', field: follows[1], current: follows[2] }
|
|
204
|
+
// A signer who cannot read the file's home is told only the field.
|
|
205
|
+
const bare = /^conflict: (\S+)\s*$/.exec(reason)
|
|
206
|
+
if (bare) return { kind: 'stale', field: bare[1] }
|
|
207
|
+
return { kind: 'other' }
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/** What {@link writeChange} is handed. */
|
|
211
|
+
export interface WriteChangeArgs {
|
|
212
|
+
field: string
|
|
213
|
+
/** The value to set; for the text, mine. */
|
|
214
|
+
value: string
|
|
215
|
+
/** The text's `content-format`, when it is one. */
|
|
216
|
+
format?: string
|
|
217
|
+
/**
|
|
218
|
+
* The change this one follows, as the writer read it: the field's current
|
|
219
|
+
* change, or the first record's id for its first change. For the text it is
|
|
220
|
+
* also the base a merge starts from — the version the person, or the agent,
|
|
221
|
+
* last read.
|
|
222
|
+
*/
|
|
223
|
+
prev: string
|
|
224
|
+
/**
|
|
225
|
+
* The unsigned change for this value, `prev` and time — `buildActionEvent`
|
|
226
|
+
* bound to the field's action, so the manifest decides its shape and every
|
|
227
|
+
* attempt carries the same tags.
|
|
228
|
+
*/
|
|
229
|
+
build: (input: { value: string; format?: string; prev: string; createdAtMs: number }) => UnsignedEvent | string
|
|
230
|
+
sign: (event: UnsignedEvent) => Promise<SignedEvent>
|
|
231
|
+
publish: (event: SignedEvent) => Promise<{ ok: boolean; reason?: string; eventId?: string }>
|
|
232
|
+
/** Reads events by id, and the field's current change when a refusal names none. */
|
|
233
|
+
query: QueryFn
|
|
234
|
+
/** The field's current change, read again: {@link openFile}'s, for this field. */
|
|
235
|
+
current: (field: string) => Promise<SignedEvent | undefined>
|
|
236
|
+
/** The clock, in ms. */
|
|
237
|
+
now?: () => number
|
|
238
|
+
/** How many sends before giving up; 4 unless said. */
|
|
239
|
+
tries?: number
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
export type WriteChangeResult =
|
|
243
|
+
| {
|
|
244
|
+
ok: true
|
|
245
|
+
/** The id the relay accepted: the field's next `prev`. */
|
|
246
|
+
id: string
|
|
247
|
+
event: SignedEvent
|
|
248
|
+
/** Set when the text was merged onto someone's newer change, which it names. */
|
|
249
|
+
mergedOnto?: SignedEvent
|
|
250
|
+
}
|
|
251
|
+
| {
|
|
252
|
+
ok: true
|
|
253
|
+
/** Nothing was sent: mine, merged onto theirs, says nothing theirs does not. */
|
|
254
|
+
unchanged: true
|
|
255
|
+
id: string
|
|
256
|
+
mergedOnto: SignedEvent
|
|
257
|
+
}
|
|
258
|
+
| {
|
|
259
|
+
ok: false
|
|
260
|
+
/** Why nothing was saved, in the relay's words or the builder's. */
|
|
261
|
+
refused: string
|
|
262
|
+
}
|
|
263
|
+
| {
|
|
264
|
+
ok: false
|
|
265
|
+
/** The text asks: these blocks were changed by both, or edited against a delete. Nothing was saved. */
|
|
266
|
+
asks: MergeAsk[]
|
|
267
|
+
/** The change now current, whose words must be kept. */
|
|
268
|
+
theirs: SignedEvent
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
const byId = async (query: QueryFn, id: string) => (await query([{ ids: [id] }])).find((e) => e.id === id)
|
|
272
|
+
|
|
273
|
+
/**
|
|
274
|
+
* Write one field's change, naming the one it follows, and answer a
|
|
275
|
+
* `conflict:` as §6.2 says.
|
|
276
|
+
*
|
|
277
|
+
* - **Stale `prev`, a field other than the text**: read the current change
|
|
278
|
+
* (by the id the relay named, or {@link WriteChangeArgs.current} when it
|
|
279
|
+
* named none) and set the value again after it. Two setting one field is not
|
|
280
|
+
* a conflict to show: the later stands.
|
|
281
|
+
* - **Stale `prev`, the text**: merge mine onto the current text by §13.3,
|
|
282
|
+
* with the text `prev` named as the base, and send the merge after it. When
|
|
283
|
+
* a block asks, nothing is sent and the answer carries the blocks and
|
|
284
|
+
* theirs. Refused again, it merges again with what it last sent as mine and
|
|
285
|
+
* what it merged onto as the base.
|
|
286
|
+
* - **Does not sort after its `prev`**: the clock is behind; stamp it 1 ms
|
|
287
|
+
* after `prev`, `ts` and `created_at` agreeing.
|
|
288
|
+
* - **Anything else** (`invalid:` and the rest) is never sent again.
|
|
289
|
+
*
|
|
290
|
+
* A few tries, then it stops with the relay's last answer.
|
|
291
|
+
*/
|
|
292
|
+
export async function writeChange(args: WriteChangeArgs): Promise<WriteChangeResult> {
|
|
293
|
+
const now = args.now ?? Date.now
|
|
294
|
+
const tries = args.tries ?? 4
|
|
295
|
+
const isText = args.field === TEXT_FIELD
|
|
296
|
+
let prev = args.prev
|
|
297
|
+
let after = 0
|
|
298
|
+
let mine: MergeText = { value: args.value, ...(args.format ? { format: args.format } : {}) }
|
|
299
|
+
let base: MergeText | undefined
|
|
300
|
+
let mergedOnto: SignedEvent | undefined
|
|
301
|
+
let last = ''
|
|
302
|
+
|
|
303
|
+
for (let attempt = 0; attempt < tries; attempt++) {
|
|
304
|
+
const built = args.build({ value: mine.value, format: mine.format, prev, createdAtMs: Math.max(now(), after) })
|
|
305
|
+
if (typeof built === 'string') return { ok: false, refused: built }
|
|
306
|
+
const signed = await args.sign(built)
|
|
307
|
+
const answer = await args.publish(signed)
|
|
308
|
+
if (answer.ok) return { ok: true, id: answer.eventId ?? signed.id, event: signed, ...(mergedOnto ? { mergedOnto } : {}) }
|
|
309
|
+
last = answer.reason ?? 'refused with no reason'
|
|
310
|
+
const conflict = conflictOf(last)
|
|
311
|
+
if (!conflict || conflict.kind === 'other' || conflict.field !== args.field) return { ok: false, refused: last }
|
|
312
|
+
|
|
313
|
+
if (conflict.kind === 'sorts-before') {
|
|
314
|
+
const followed = await byId(args.query, prev)
|
|
315
|
+
if (!followed) return { ok: false, refused: last }
|
|
316
|
+
after = changedAt(followed) + 1
|
|
317
|
+
continue
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
const head = conflict.current ? await byId(args.query, conflict.current) : await args.current(args.field)
|
|
321
|
+
if (!head) return { ok: false, refused: last }
|
|
322
|
+
after = changedAt(head) + 1
|
|
323
|
+
if (!isText) {
|
|
324
|
+
prev = head.id
|
|
325
|
+
continue
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
if (!base) {
|
|
329
|
+
const followed = await byId(args.query, prev)
|
|
330
|
+
base = followed && textOf(followed)
|
|
331
|
+
if (!base) return { ok: false, refused: `${last} (the text it followed, ${prev}, could not be read to merge onto)` }
|
|
332
|
+
}
|
|
333
|
+
const theirs = textOf(head)
|
|
334
|
+
if (!theirs) return { ok: false, refused: last }
|
|
335
|
+
const merge = mergeTexts(base, theirs, mine)
|
|
336
|
+
if (merge.asks) return { ok: false, asks: merge.asks, theirs: head }
|
|
337
|
+
mergedOnto = head
|
|
338
|
+
if (merge.merged.value === theirs.value && (merge.merged.format ?? '') === (theirs.format ?? '')) {
|
|
339
|
+
return { ok: true, unchanged: true, id: head.id, mergedOnto: head }
|
|
340
|
+
}
|
|
341
|
+
base = theirs
|
|
342
|
+
mine = merge.merged
|
|
343
|
+
prev = head.id
|
|
344
|
+
}
|
|
345
|
+
return { ok: false, refused: `still refused after ${tries} tries: ${last}` }
|
|
346
|
+
}
|
package/src/folders.ts
CHANGED
|
@@ -206,6 +206,8 @@ export function planArchiveFolder(
|
|
|
206
206
|
// shape produce the same tags.
|
|
207
207
|
tags: [
|
|
208
208
|
['a', args.channel],
|
|
209
|
+
// The file it is about, by its id (§6.2).
|
|
210
|
+
...(identifierOf(args.channel) !== undefined ? [['O', identifierOf(args.channel)!]] : []),
|
|
209
211
|
['field', 'archived'],
|
|
210
212
|
['value', args.archived ? 'true' : ''],
|
|
211
213
|
['h', args.folder],
|
|
@@ -216,6 +218,11 @@ export function planArchiveFolder(
|
|
|
216
218
|
]
|
|
217
219
|
}
|
|
218
220
|
|
|
221
|
+
/** The file's id, the `d` of an address `<kind>:<pubkey>:<d>`; undefined for anything else. */
|
|
222
|
+
export function identifierOf(address: string): string | undefined {
|
|
223
|
+
return /^\d+:[0-9a-f]{64}:([^]*)$/.exec(address)?.[1]
|
|
224
|
+
}
|
|
225
|
+
|
|
219
226
|
/**
|
|
220
227
|
* A file as a move needs it. A `ForeignObject` from `resolveFolderContents` is
|
|
221
228
|
* one: `ref` is its identity, `parentRef` the file it is drawn beneath, and
|
package/src/index.ts
CHANGED
|
@@ -169,6 +169,27 @@ export {
|
|
|
169
169
|
type ListedFile,
|
|
170
170
|
} from './topics.js'
|
|
171
171
|
|
|
172
|
+
/**
|
|
173
|
+
* A file as its fields, each kept in order by the relay (SPEC §6.2, §6.13):
|
|
174
|
+
* the list and open reads, and the change writer that answers `conflict:`.
|
|
175
|
+
*/
|
|
176
|
+
export {
|
|
177
|
+
TEXT_FIELD,
|
|
178
|
+
changedAt,
|
|
179
|
+
fieldsSetBy,
|
|
180
|
+
filesOf,
|
|
181
|
+
listFiles,
|
|
182
|
+
openFile,
|
|
183
|
+
textOf,
|
|
184
|
+
conflictOf,
|
|
185
|
+
writeChange,
|
|
186
|
+
type CurrentField,
|
|
187
|
+
type FileFields,
|
|
188
|
+
type Conflict,
|
|
189
|
+
type WriteChangeArgs,
|
|
190
|
+
type WriteChangeResult,
|
|
191
|
+
} from './fields.js'
|
|
192
|
+
|
|
172
193
|
/**
|
|
173
194
|
* What an app link names, and where a file is mentioned — once for every app
|
|
174
195
|
* (SPEC §7.7, §13.1, §6.8; PEEKM-7). Each app passes its relay read; none
|
package/src/projection.ts
CHANGED
|
@@ -22,7 +22,7 @@ import {
|
|
|
22
22
|
imetaTag,
|
|
23
23
|
parseBlockDocument,
|
|
24
24
|
} from '@estiva-app/protocol'
|
|
25
|
-
import { planPlaceFile, planUnlistFile, type FolderRef } from './folders.js'
|
|
25
|
+
import { identifierOf, planPlaceFile, planUnlistFile, type FolderRef } from './folders.js'
|
|
26
26
|
/*
|
|
27
27
|
SPEC §6.4's comment strength and §6.3's ordering are the conversation
|
|
28
28
|
package's (CON-5): one copy of each rule, read here for a file's `comments`,
|
|
@@ -5805,6 +5805,9 @@ function buildCreationEvent(args: {
|
|
|
5805
5805
|
*/
|
|
5806
5806
|
const PERSON_KEY = /^[0-9a-f]{64}$/
|
|
5807
5807
|
|
|
5808
|
+
/** An event id as the relay reads a `prev`: lower-case hex. */
|
|
5809
|
+
const EVENT_ID = /^[0-9a-f]{64}$/
|
|
5810
|
+
|
|
5808
5811
|
/** Why `value` is neither `''` nor a person's key, or undefined when it is one. */
|
|
5809
5812
|
function personKeyProblem(label: string, value: string): string | undefined {
|
|
5810
5813
|
if (value === '' || PERSON_KEY.test(value)) return undefined
|
|
@@ -5879,6 +5882,17 @@ export interface ActionEventArgs {
|
|
|
5879
5882
|
* only: a comment's text is its `value`, and a creation has its own body.
|
|
5880
5883
|
*/
|
|
5881
5884
|
note?: string
|
|
5885
|
+
/**
|
|
5886
|
+
* The change this one follows for its field: the id of that field's current
|
|
5887
|
+
* change as the writer read it, or the file's first record's id for its
|
|
5888
|
+
* first change (SPEC §6.2). A change only. Every writer should send it; a
|
|
5889
|
+
* relay that keeps the type in order refuses a change without it, and one
|
|
5890
|
+
* naming a change that is no longer current with `conflict:`, which
|
|
5891
|
+
* {@link writeChange} answers.
|
|
5892
|
+
*
|
|
5893
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-its-fields-each-kept-in-order-by-the-relay.md
|
|
5894
|
+
*/
|
|
5895
|
+
prev?: string
|
|
5882
5896
|
pubkey: string
|
|
5883
5897
|
createdAtMs: number
|
|
5884
5898
|
}
|
|
@@ -5988,6 +6002,13 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
|
|
|
5988
6002
|
if (args.note !== undefined && (isCreation || !declared.emits.field || declared.emits.kind === KIND_DELETION)) {
|
|
5989
6003
|
return `"${declared.label}" is not a change, so it takes no note.`
|
|
5990
6004
|
}
|
|
6005
|
+
// Only a change follows another for its field (§6.2).
|
|
6006
|
+
if (args.prev !== undefined && (isCreation || !declared.emits.field || declared.emits.kind === KIND_DELETION)) {
|
|
6007
|
+
return `"${declared.label}" is not a change, so it follows no change.`
|
|
6008
|
+
}
|
|
6009
|
+
if (args.prev !== undefined && !EVENT_ID.test(args.prev)) {
|
|
6010
|
+
return `"${declared.label}" follows ${JSON.stringify(args.prev)}, which is not an event id.`
|
|
6011
|
+
}
|
|
5991
6012
|
|
|
5992
6013
|
// An object-creating action is a different event entirely — a new object
|
|
5993
6014
|
// rather than a change to one — so it branches before the scalar path.
|
|
@@ -6072,9 +6093,13 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
|
|
|
6072
6093
|
if (typeof prose === 'string') return prose
|
|
6073
6094
|
const [formatTag, ...files] = prose
|
|
6074
6095
|
|
|
6096
|
+
// The file the change is about, by its id, beside its address (§6.2): the
|
|
6097
|
+
// relay keeps each field in order by it.
|
|
6098
|
+
const fileId = records.targetTag === 'a' ? identifierOf(address) : undefined
|
|
6075
6099
|
const tags: string[][] = declared.emits.field
|
|
6076
6100
|
? [
|
|
6077
6101
|
[records.targetTag, address],
|
|
6102
|
+
...(fileId !== undefined ? [['O', fileId]] : []),
|
|
6078
6103
|
[records.fieldTag, declared.emits.field],
|
|
6079
6104
|
[records.valueTag, value],
|
|
6080
6105
|
['h', folder],
|
|
@@ -6114,6 +6139,7 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
|
|
|
6114
6139
|
// second would be separated by event id — arbitrarily, and differently
|
|
6115
6140
|
// depending on which app you asked (FRICTION.md A6).
|
|
6116
6141
|
if (records.order?.includes('ts')) tags.push(['ts', String(args.createdAtMs)])
|
|
6142
|
+
if (args.prev !== undefined) tags.push(['prev', args.prev])
|
|
6117
6143
|
tags.push(...files)
|
|
6118
6144
|
// The person, where the relay indexes them: `value` is not indexed, so
|
|
6119
6145
|
// without this `#p` never finds the change and §11.8 makes nobody a member.
|
|
@@ -6150,6 +6176,12 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
|
|
|
6150
6176
|
if (moved?.field === declared.emits.field && typeof value === 'string' && parentAddress.test(value)) {
|
|
6151
6177
|
tags.push([MOVED_TO_TAG, value])
|
|
6152
6178
|
}
|
|
6179
|
+
// What the chosen option means, last (§6.2's `stage`): a status says
|
|
6180
|
+
// whether it is open, started, done or dropped, whichever app reads it.
|
|
6181
|
+
const stage = declared.emits.field && declared.input?.enum
|
|
6182
|
+
? manifest.vocabularies?.[declared.input.enum]?.find((entry) => entry.value === value)?.stage
|
|
6183
|
+
: undefined
|
|
6184
|
+
if (declared.emits.field && stage && STAGES.has(stage as Stage)) tags.push(['stage', declared.emits.field, stage])
|
|
6153
6185
|
|
|
6154
6186
|
return {
|
|
6155
6187
|
pubkey: args.pubkey,
|