@estiva-app/interop 0.70.1 → 0.71.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 +40 -0
- package/README.md +25 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -0
- package/dist/index.js.map +1 -1
- package/dist/projection.d.ts +9 -0
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +18 -8
- package/dist/projection.js.map +1 -1
- package/dist/topics.d.ts +131 -0
- package/dist/topics.d.ts.map +1 -0
- package/dist/topics.js +241 -0
- package/dist/topics.js.map +1 -0
- package/package.json +1 -1
- package/src/index.ts +21 -0
- package/src/projection.ts +39 -7
- package/src/topics.ts +295 -0
package/src/topics.ts
ADDED
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A topic's list of files — SPEC §6.14 "A file's list of other files"; record
|
|
3
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-topic-keeps-its-own-list-of-files.md
|
|
4
|
+
*
|
|
5
|
+
* A topic lists files from any Folder, one entry per file, by the file's id.
|
|
6
|
+
* An entry is a `kind:1851` change on the topic: `a` and `O` name the topic,
|
|
7
|
+
* `field` is `lists:<d>`, `value` is `true` or `false`, `h` is the topic's
|
|
8
|
+
* Folder, then `ts`, then `["o", <d>]` naming the listed file. The newest
|
|
9
|
+
* entry per topic and file counts (§6.3).
|
|
10
|
+
*
|
|
11
|
+
* `O` is the file the change is about and `o` another file it points at
|
|
12
|
+
* (why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-change-is-about-its-file-as-a-comment-is.md),
|
|
13
|
+
* so `#o` asks which topics list a file and `#O` asks what changed on a topic,
|
|
14
|
+
* and a file's own changes never include a topic's entry about it.
|
|
15
|
+
*
|
|
16
|
+
* Here rather than in each app because Peek, Ship and Leaf all add, remove
|
|
17
|
+
* and read entries, and a reader rule kept in one of them only is a list that
|
|
18
|
+
* reads differently in the next.
|
|
19
|
+
*
|
|
20
|
+
* ## What a listing is not
|
|
21
|
+
*
|
|
22
|
+
* It grants nothing: who reads the listed file is its own Folder's rule. It is
|
|
23
|
+
* not a mention, not a parent and not a Folder's listing, so Mentioned in, the
|
|
24
|
+
* archive chain and a Folder move all ignore it. It carries no `p`, so it adds
|
|
25
|
+
* nobody to the file (§11.8).
|
|
26
|
+
*/
|
|
27
|
+
import { type SignedEvent, type UnsignedEvent } from '@estiva-app/protocol'
|
|
28
|
+
import { byOrder } from '@estiva-app/conversation'
|
|
29
|
+
import { folderOf, type QueryFn } from './projection.js'
|
|
30
|
+
|
|
31
|
+
const KIND_CHANGE = 1851
|
|
32
|
+
/** The topic (bare file) kind: the only lists this stage reads (Miky, 2026-10-30). */
|
|
33
|
+
const KIND_TOPIC = 30840
|
|
34
|
+
const KIND_FOLDER = 39000
|
|
35
|
+
/** Listed ids resolved per request: 2 × this stays under a relay's usual `limit` cap. */
|
|
36
|
+
const RESOLVE_BATCH = 100
|
|
37
|
+
/**
|
|
38
|
+
* The file kinds a listed id is looked for under by default: topic, document,
|
|
39
|
+
* project, issue. Never a bare `#d`, since a Folder's `kind:39000` shares its
|
|
40
|
+
* uuid (§11.1). An app that knows more kinds from manifests passes them.
|
|
41
|
+
*/
|
|
42
|
+
export const LISTED_FILE_KINDS: readonly number[] = [30840, 30842, 30850, 30851]
|
|
43
|
+
|
|
44
|
+
const ADDRESS = /^(\d+):([0-9a-f]{64}):(.+)$/
|
|
45
|
+
const FIELD_PREFIX = 'lists:'
|
|
46
|
+
|
|
47
|
+
/** The field an entry for `file` sets: `lists:<d>`. */
|
|
48
|
+
export function listsField(file: string): string {
|
|
49
|
+
return `${FIELD_PREFIX}${file}`
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** The file a list carries entries on, as a write needs it. */
|
|
53
|
+
export interface ListHolder {
|
|
54
|
+
/** Its address, `<kind>:<pubkey>:<d>`. */
|
|
55
|
+
address: string
|
|
56
|
+
/** Its Folder, read from its root (`folderOf`), never the Folder it was opened from (§6.2). */
|
|
57
|
+
folder: string
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function entry(
|
|
61
|
+
pubkey: string,
|
|
62
|
+
createdAtMs: number,
|
|
63
|
+
args: { list: ListHolder; file: string; listed: boolean; note?: string },
|
|
64
|
+
): UnsignedEvent {
|
|
65
|
+
const holder = ADDRESS.exec(args.list.address)
|
|
66
|
+
if (!holder) throw new Error(`not a file address: ${JSON.stringify(args.list.address)}`)
|
|
67
|
+
if (!args.list.folder) throw new Error('a list entry names the Folder of the file that keeps the list')
|
|
68
|
+
if (!args.file || /\s/.test(args.file)) throw new Error(`not a file id: ${JSON.stringify(args.file)}`)
|
|
69
|
+
// A reader ignores a file on its own list (§6.14): refuse it here rather than publish an entry that shows nothing.
|
|
70
|
+
if (args.file === holder[3]) throw new Error('a file is not on its own list')
|
|
71
|
+
if (!Number.isSafeInteger(createdAtMs) || createdAtMs < 0) throw new Error(`not epoch milliseconds: ${createdAtMs}`)
|
|
72
|
+
return {
|
|
73
|
+
pubkey,
|
|
74
|
+
created_at: Math.floor(createdAtMs / 1000),
|
|
75
|
+
kind: KIND_CHANGE,
|
|
76
|
+
tags: [
|
|
77
|
+
['a', args.list.address],
|
|
78
|
+
['O', holder[3]],
|
|
79
|
+
['field', listsField(args.file)],
|
|
80
|
+
['value', args.listed ? 'true' : 'false'],
|
|
81
|
+
['h', args.list.folder],
|
|
82
|
+
['ts', String(createdAtMs)],
|
|
83
|
+
['o', args.file],
|
|
84
|
+
],
|
|
85
|
+
// Empty unless the person wrote a note: each app says "added" and "removed" in its own words (§6.14).
|
|
86
|
+
content: args.note ?? '',
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Put a file on a topic's list: `[kind:1851 lists:<d> = true]`, signed by
|
|
92
|
+
* whoever adds it. `file` is the listed file's id (its `d`), from any Folder.
|
|
93
|
+
*/
|
|
94
|
+
export function planListInTopic(
|
|
95
|
+
pubkey: string,
|
|
96
|
+
createdAtMs: number,
|
|
97
|
+
args: { topic: ListHolder; file: string; note?: string },
|
|
98
|
+
): UnsignedEvent[] {
|
|
99
|
+
return [entry(pubkey, createdAtMs, { list: args.topic, file: args.file, listed: true, note: args.note })]
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** Take a file off a topic's list: `[kind:1851 lists:<d> = false]`. {@link planListInTopic} in reverse. */
|
|
103
|
+
export function planRemoveFromTopic(
|
|
104
|
+
pubkey: string,
|
|
105
|
+
createdAtMs: number,
|
|
106
|
+
args: { topic: ListHolder; file: string; note?: string },
|
|
107
|
+
): UnsignedEvent[] {
|
|
108
|
+
return [entry(pubkey, createdAtMs, { list: args.topic, file: args.file, listed: false, note: args.note })]
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** Which topics list a file: every entry naming its id in `o`. Fold with {@link listEntries}. */
|
|
112
|
+
export function topicsOfFileFilter(file: string): Record<string, unknown> {
|
|
113
|
+
return { kinds: [KIND_CHANGE], '#o': [file] }
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** A topic's changes, its list entries among them: `#O` on its id. Fold with {@link listEntries}. */
|
|
117
|
+
export function topicListFilter(topic: string): Record<string, unknown> {
|
|
118
|
+
const holder = ADDRESS.exec(topic)
|
|
119
|
+
return { kinds: [KIND_CHANGE], '#O': [holder ? holder[3] : topic] }
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/** The newest entry for one list and one file. */
|
|
123
|
+
export interface ListEntry {
|
|
124
|
+
/** The address of the file keeping the list (a topic). */
|
|
125
|
+
list: string
|
|
126
|
+
/** The listed file's id. */
|
|
127
|
+
file: string
|
|
128
|
+
/** The entry's Folder: its first `h` with a value. */
|
|
129
|
+
folder: string
|
|
130
|
+
/** `true` when the newest entry lists the file. */
|
|
131
|
+
listed: boolean
|
|
132
|
+
event: SignedEvent
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
const tagOf = (event: Pick<SignedEvent, 'tags'>, name: string): string | undefined =>
|
|
136
|
+
event.tags.find((t) => t[0] === name && t[1])?.[1]
|
|
137
|
+
|
|
138
|
+
/** The file an entry lists: the `<d>` of its `lists:<d>` field, or `null` for any other change. */
|
|
139
|
+
const listedIn = (event: Pick<SignedEvent, 'tags'>): string | null => {
|
|
140
|
+
const field = tagOf(event, 'field')
|
|
141
|
+
return field?.startsWith(FIELD_PREFIX) ? field.slice(FIELD_PREFIX.length) || null : null
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* The newest entry per list and file, from any mix of changes: the reader
|
|
146
|
+
* rules of §6.14. A change counts as an entry only when its field is
|
|
147
|
+
* `lists:<d>`, one of its `o` tags is that same `<d>` (an `o` the field does
|
|
148
|
+
* not name is some other relation, a move's new parent for one), its `a`
|
|
149
|
+
* names a file whose `d` is its `O`, `<d>` is not that file itself, and it
|
|
150
|
+
* names a Folder. Anything else is skipped, not folded, so a malformed entry
|
|
151
|
+
* never hides a good one. A `value` other than exactly `true` does not list
|
|
152
|
+
* the file.
|
|
153
|
+
*
|
|
154
|
+
* `folderOfList` is §6.2's Folder check against each list's root, applied
|
|
155
|
+
* before the fold: an entry filed in any other Folder must not become the
|
|
156
|
+
* newest and hide the good one before it. A list it answers no Folder for (an
|
|
157
|
+
* unread root, or one naming none) keeps no entry. Without it the check is the
|
|
158
|
+
* caller's; {@link topicsOfFile} and {@link topicList} pass it.
|
|
159
|
+
*/
|
|
160
|
+
export function listEntries(
|
|
161
|
+
events: readonly SignedEvent[],
|
|
162
|
+
folderOfList?: (list: string) => string | null | undefined,
|
|
163
|
+
): ListEntry[] {
|
|
164
|
+
const newest = new Map<string, { event: SignedEvent; file: string }>()
|
|
165
|
+
for (const event of events) {
|
|
166
|
+
if (event.kind !== KIND_CHANGE) continue
|
|
167
|
+
const file = listedIn(event)
|
|
168
|
+
if (!file || !event.tags.some((t) => t[0] === 'o' && t[1] === file)) continue
|
|
169
|
+
const list = tagOf(event, 'a')
|
|
170
|
+
const holder = list ? ADDRESS.exec(list) : null
|
|
171
|
+
const folder = tagOf(event, 'h')
|
|
172
|
+
if (!holder || tagOf(event, 'O') !== holder[3] || file === holder[3] || !folder) continue
|
|
173
|
+
if (folderOfList && folderOfList(list!) !== folder) continue
|
|
174
|
+
const key = `${list}\n${file}`
|
|
175
|
+
const seen = newest.get(key)
|
|
176
|
+
if (!seen || byOrder(seen.event, event) < 0) newest.set(key, { event, file })
|
|
177
|
+
}
|
|
178
|
+
return [...newest.values()].map(({ event, file }) => ({
|
|
179
|
+
list: tagOf(event, 'a')!,
|
|
180
|
+
file,
|
|
181
|
+
folder: tagOf(event, 'h')!,
|
|
182
|
+
listed: event.tags.find((t) => t[0] === 'value')?.[1] === 'true',
|
|
183
|
+
event,
|
|
184
|
+
}))
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** The roots of the given list addresses that the reader can read, by address. */
|
|
188
|
+
async function rootsOf(query: QueryFn, addresses: readonly string[]): Promise<Map<string, SignedEvent>> {
|
|
189
|
+
const byKindAuthor = new Map<string, { kind: number; pubkey: string; ds: string[] }>()
|
|
190
|
+
for (const address of addresses) {
|
|
191
|
+
const [, kind, pubkey, d] = ADDRESS.exec(address) ?? []
|
|
192
|
+
if (!d) continue
|
|
193
|
+
const key = `${kind}:${pubkey}`
|
|
194
|
+
const group = byKindAuthor.get(key) ?? { kind: Number(kind), pubkey, ds: [] }
|
|
195
|
+
group.ds.push(d)
|
|
196
|
+
byKindAuthor.set(key, group)
|
|
197
|
+
}
|
|
198
|
+
if (byKindAuthor.size === 0) return new Map()
|
|
199
|
+
const filters = [...byKindAuthor.values()].map(({ kind, pubkey, ds }) => ({ kinds: [kind], authors: [pubkey], '#d': ds, limit: ds.length }))
|
|
200
|
+
const roots = new Map<string, SignedEvent>()
|
|
201
|
+
for (const root of await query(filters)) {
|
|
202
|
+
const address = `${root.kind}:${root.pubkey}:${tagOf(root, 'd') ?? ''}`
|
|
203
|
+
const held = roots.get(address)
|
|
204
|
+
// Two versions of one record: NIP-01's later created_at, then the lower id (§6.3).
|
|
205
|
+
if (!held || root.created_at > held.created_at || (root.created_at === held.created_at && root.id < held.id)) roots.set(address, root)
|
|
206
|
+
}
|
|
207
|
+
return roots
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/** A topic that lists a file. */
|
|
211
|
+
export interface FileTopic {
|
|
212
|
+
/** The topic's address. */
|
|
213
|
+
address: string
|
|
214
|
+
/** The topic's root, as the reader read it. */
|
|
215
|
+
root: SignedEvent
|
|
216
|
+
entry: ListEntry
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* Which topics list a file — `{kinds:[1851], "#o":[<d>]}`, folded per topic.
|
|
221
|
+
*
|
|
222
|
+
* Keeps an entry only when its newest value lists the file, it is on a topic
|
|
223
|
+
* (only topics' lists are read, Miky 2026-10-30), the topic's root is one the
|
|
224
|
+
* reader can read (a deleted or unreadable topic drops out), and the entry is
|
|
225
|
+
* filed in the topic's own Folder (§6.2). Two reads: the entries, then the
|
|
226
|
+
* topics' roots.
|
|
227
|
+
*/
|
|
228
|
+
export async function topicsOfFile(query: QueryFn, file: string): Promise<FileTopic[]> {
|
|
229
|
+
const isTopic = (entry: ListEntry) => entry.file === file && entry.list.startsWith(`${KIND_TOPIC}:`)
|
|
230
|
+
const events = await query([topicsOfFileFilter(file)])
|
|
231
|
+
const lists = [...new Set(listEntries(events).filter(isTopic).map((entry) => entry.list))]
|
|
232
|
+
if (lists.length === 0) return []
|
|
233
|
+
const roots = await rootsOf(query, lists)
|
|
234
|
+
const folderOfList = (list: string) => {
|
|
235
|
+
const root = roots.get(list)
|
|
236
|
+
return root ? folderOf(root) : null
|
|
237
|
+
}
|
|
238
|
+
return listEntries(events, folderOfList)
|
|
239
|
+
.filter((entry) => entry.listed && isTopic(entry))
|
|
240
|
+
.map((entry) => ({ address: entry.list, root: roots.get(entry.list)!, entry }))
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/** A file on a topic's list. */
|
|
244
|
+
export interface ListedFile {
|
|
245
|
+
/** The listed file's id. */
|
|
246
|
+
file: string
|
|
247
|
+
/** Its address when exactly one file the reader can read holds the id, else `null`: not drawn, not counted. */
|
|
248
|
+
address: string | null
|
|
249
|
+
entry: ListEntry
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* A topic's list, by the topic's address: its entries whose newest value
|
|
254
|
+
* lists the file, filed in the Folder the topic's root names (§6.2; read here,
|
|
255
|
+
* never taken from the caller), in no promised order (sort as the design
|
|
256
|
+
* says; `entry.event` carries the time), each id resolved over `fileKinds` by
|
|
257
|
+
* `#d`. A topic the reader cannot read, or whose root names no Folder, lists
|
|
258
|
+
* nothing. An id held by none the reader can read, or by two, resolves to
|
|
259
|
+
* `null`: a consumer draws and counts only the resolved ones (§3.2, the count
|
|
260
|
+
* is the disclosure).
|
|
261
|
+
*/
|
|
262
|
+
export async function topicList(
|
|
263
|
+
query: QueryFn,
|
|
264
|
+
topic: string,
|
|
265
|
+
options: { fileKinds?: readonly number[] } = {},
|
|
266
|
+
): Promise<ListedFile[]> {
|
|
267
|
+
const [roots, events] = await Promise.all([rootsOf(query, [topic]), query([topicListFilter(topic)])])
|
|
268
|
+
const root = roots.get(topic)
|
|
269
|
+
const folder = root ? folderOf(root) : null
|
|
270
|
+
if (!folder) return []
|
|
271
|
+
const entries = listEntries(events, (list) => (list === topic ? folder : null))
|
|
272
|
+
.filter((entry) => entry.listed)
|
|
273
|
+
.sort((a, b) => byOrder(a.event, b.event))
|
|
274
|
+
if (entries.length === 0) return []
|
|
275
|
+
const ids = [...new Set(entries.map((entry) => entry.file))]
|
|
276
|
+
// Never a Folder's `39000`, which shares its uuid (§11.1): an id only a Folder holds resolves to nothing.
|
|
277
|
+
const kinds = (options.fileKinds ?? LISTED_FILE_KINDS).filter((kind) => kind !== KIND_FOLDER)
|
|
278
|
+
// Room for a second holder of every id, so two holders are seen as two; in
|
|
279
|
+
// batches, so a relay's cap on `limit` cannot cut a long list short.
|
|
280
|
+
const batches: string[][] = []
|
|
281
|
+
for (let i = 0; i < ids.length; i += RESOLVE_BATCH) batches.push(ids.slice(i, i + RESOLVE_BATCH))
|
|
282
|
+
const found = (await Promise.all(batches.map((batch) => query([{ kinds, '#d': batch, limit: batch.length * 2 }])))).flat()
|
|
283
|
+
const holders = new Map<string, Set<string>>()
|
|
284
|
+
for (const event of found) {
|
|
285
|
+
const d = tagOf(event, 'd')
|
|
286
|
+
if (!d || !kinds.includes(event.kind)) continue
|
|
287
|
+
const set = holders.get(d) ?? new Set<string>()
|
|
288
|
+
set.add(`${event.kind}:${event.pubkey}`)
|
|
289
|
+
holders.set(d, set)
|
|
290
|
+
}
|
|
291
|
+
return entries.map((entry) => {
|
|
292
|
+
const set = holders.get(entry.file)
|
|
293
|
+
return { file: entry.file, address: set?.size === 1 ? `${[...set][0]}:${entry.file}` : null, entry }
|
|
294
|
+
})
|
|
295
|
+
}
|