@estiva-app/interop 0.88.0 → 0.90.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 +42 -0
- package/dist/activity.d.ts +131 -0
- package/dist/activity.d.ts.map +1 -0
- package/dist/activity.js +495 -0
- package/dist/activity.js.map +1 -0
- 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 +3 -0
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +3 -1
- package/dist/projection.js.map +1 -1
- package/dist/topics.d.ts +18 -0
- package/dist/topics.d.ts.map +1 -1
- package/dist/topics.js +9 -4
- package/dist/topics.js.map +1 -1
- package/package.json +1 -1
- package/src/activity.ts +524 -0
- package/src/index.ts +16 -0
- package/src/projection.ts +4 -2
- package/src/topics.ts +12 -5
package/src/activity.ts
ADDED
|
@@ -0,0 +1,524 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Your topics, newest activity first: the one shared rule Peek, Ship and Leaf
|
|
3
|
+
* order topics by (TOPI-10; Miky, 2026-11-06, "Where anything moved").
|
|
4
|
+
*
|
|
5
|
+
* A topic's time is when anything last happened in it, deep:
|
|
6
|
+
*
|
|
7
|
+
* - a message or reply in its own conversation (`kind:1111`/`9` with its `A`);
|
|
8
|
+
* - a change to the topic itself, except tidying it: its `order:<d>` and
|
|
9
|
+
* `look:<d>` (arranging, a row/card switch), a file taken off its list
|
|
10
|
+
* (`lists:<d>` = `false`) — a file put on it counts;
|
|
11
|
+
* - a change to, or a comment on, any file its list holds, and on every file
|
|
12
|
+
* under one: a listed project's issues, a listed document's pages, any depth
|
|
13
|
+
* (the newest {@link MAX_CHILDREN} under each);
|
|
14
|
+
* - a new file under one (an issue filed in a listed project).
|
|
15
|
+
*
|
|
16
|
+
* Never, anywhere: a rename (`title`, on the topic or any file; Miky,
|
|
17
|
+
* 2026-11-09), who is on a file or at what level (`member:<P>`, `follow:<P>`,
|
|
18
|
+
* §11.8) — joining would move a topic up for everyone — and read state
|
|
19
|
+
* (`kind:30078`). The agent's own writes count like anyone's.
|
|
20
|
+
*
|
|
21
|
+
* An event counts only on the file it is on as the fold reads it, never by a
|
|
22
|
+
* tag alone: a change by its first `a`, in its file's own team (`h`); a
|
|
23
|
+
* comment by its root, never a crossed one; a new file by its one `a`.
|
|
24
|
+
* With nothing else, a topic's time is its first record's.
|
|
25
|
+
*
|
|
26
|
+
* Every `created_at` is the author's to write, and the relay takes one up to
|
|
27
|
+
* 15 minutes ahead: each time is capped at the reader's clock, so a
|
|
28
|
+
* future-dated event cannot pin a topic to the top.
|
|
29
|
+
*
|
|
30
|
+
* Two people's orders may differ where a listed file sits in a team only one
|
|
31
|
+
* of them reads; nothing unreadable is revealed, since each reads as itself.
|
|
32
|
+
*
|
|
33
|
+
* The rule takes any set of topics, so an Explore page orders every topic the
|
|
34
|
+
* reader can open with the same read ({@link readTopicActivity}), and a live
|
|
35
|
+
* app keeps it current with {@link watchTopicActivity}.
|
|
36
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/each-file-on-a-topic-keeps-its-own-place-and-look.md
|
|
37
|
+
*/
|
|
38
|
+
import { fileIdOf, MAX_FILTERS_PER_QUERY, type LiveRelay, type SignedEvent } from '@estiva-app/protocol'
|
|
39
|
+
import { isAbout, KIND_COMMENT } from '@estiva-app/conversation'
|
|
40
|
+
import { folderOf, KIND_MESSAGE, type QueryFn } from './projection.js'
|
|
41
|
+
import { answers, readAll, type ReadTopic } from './topics.js'
|
|
42
|
+
import { LISTED_WATCH_REBUILD_MS, MAX_FILTERS_PER_REQ } from './listedConversations.js'
|
|
43
|
+
|
|
44
|
+
const KIND_CHANGE = 1851
|
|
45
|
+
const KIND_READ_STATE = 30078
|
|
46
|
+
const KIND_PROJECT = 30850
|
|
47
|
+
const KIND_ISSUE = 30851
|
|
48
|
+
const KIND_DOCUMENT = 30842
|
|
49
|
+
/** What may sit under a file, by the file's kind: a project's issues, a document's pages (§6.7). */
|
|
50
|
+
const CHILD_KINDS: Readonly<Record<number, readonly number[]>> = {
|
|
51
|
+
[KIND_PROJECT]: [KIND_ISSUE],
|
|
52
|
+
[KIND_DOCUMENT]: [KIND_DOCUMENT],
|
|
53
|
+
}
|
|
54
|
+
/** How deep the pages under a listed document are walked. */
|
|
55
|
+
const MAX_DEPTH = 8
|
|
56
|
+
/** The newest files under one parent that are read and listened to: a team member filing thousands cannot multiply the reads. */
|
|
57
|
+
const MAX_CHILDREN = 500
|
|
58
|
+
/** Newest events asked per target in the first round; a target whose page holds only what does not count is asked again, older. */
|
|
59
|
+
const FIRST_PAGE = 1
|
|
60
|
+
const MAX_ROUNDS = 6
|
|
61
|
+
const ADDRESS = /^(\d+):([0-9a-f]{64}):(.+)$/
|
|
62
|
+
/** Values per tag in one live filter: the watch's filters stay small whatever the number of files. */
|
|
63
|
+
const VALUES_PER_FILTER = 100
|
|
64
|
+
|
|
65
|
+
/** A file whose activity is a topic's: on its list, or under a file on it. */
|
|
66
|
+
export interface ActivityFile {
|
|
67
|
+
/** Its address, `<kind>:<pubkey>:<d>`. */
|
|
68
|
+
address: string
|
|
69
|
+
/** Its team, from its root (§6.2), when the reader holds it: a live watch names it. */
|
|
70
|
+
folder: string | null
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** A topic to order, as the reader holds it. */
|
|
74
|
+
export interface ActivityTopic {
|
|
75
|
+
/** Its address. */
|
|
76
|
+
address: string
|
|
77
|
+
/** Its first record's time (Unix seconds): its time, when nothing has happened in it since. */
|
|
78
|
+
createdAt?: number
|
|
79
|
+
/** Its team, from its root: a change to it counts only in it, and a live watch names it. */
|
|
80
|
+
folder?: string | null
|
|
81
|
+
/** The files its list holds. A file under one of them is found by the read. */
|
|
82
|
+
files: readonly ActivityFile[]
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** {@link readTopicActivity}'s answer, and what {@link watchTopicActivity} keeps current. */
|
|
86
|
+
export interface TopicActivity {
|
|
87
|
+
/** Each topic asked for, by address: Unix seconds of the newest thing that happened in it, capped at the reader's clock; 0 when nothing is known. */
|
|
88
|
+
at: Map<string, number>
|
|
89
|
+
/** Each topic's files, by address: the listed ones and every file under them. */
|
|
90
|
+
files: Map<string, ActivityFile[]>
|
|
91
|
+
/** Each topic's team, as asked. */
|
|
92
|
+
folders: Map<string, string | null>
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** {@link ActivityTopic}s from {@link readTopics}' answer: each topic with its resolved list. */
|
|
96
|
+
export function activityTopics(topics: readonly ReadTopic[]): ActivityTopic[] {
|
|
97
|
+
return topics.map((topic) => ({
|
|
98
|
+
address: topic.address,
|
|
99
|
+
createdAt: topic.createdAt,
|
|
100
|
+
folder: topic.folder,
|
|
101
|
+
files: topic.listed.flatMap((listed) => (listed.address ? [{ address: listed.address, folder: listed.folder }] : [])),
|
|
102
|
+
}))
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/** The fields a change sets: `field`, or one `set` per field. */
|
|
106
|
+
function fieldsOf(event: SignedEvent): { field: string; value: string | undefined }[] {
|
|
107
|
+
const out: { field: string; value: string | undefined }[] = []
|
|
108
|
+
for (const tag of event.tags) {
|
|
109
|
+
if (tag[0] === 'set' && tag[1]) out.push({ field: tag[1], value: tag[2] })
|
|
110
|
+
}
|
|
111
|
+
const field = event.tags.find((tag) => tag[0] === 'field')?.[1]
|
|
112
|
+
if (field) out.push({ field, value: event.tags.find((tag) => tag[0] === 'value')?.[1] })
|
|
113
|
+
return out
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Whether an event is news for the topic it is read for: the rule above,
|
|
118
|
+
* event by event. `topic` is the address of the topic being ordered, so a
|
|
119
|
+
* change to the topic itself is judged as tidying or not.
|
|
120
|
+
*/
|
|
121
|
+
export function countsAsActivity(event: SignedEvent, topic: string): boolean {
|
|
122
|
+
if (event.kind === KIND_READ_STATE) return false
|
|
123
|
+
if (event.kind !== KIND_CHANGE) return true
|
|
124
|
+
// A change's file is its first `a` (§6.10); any later one is no target.
|
|
125
|
+
const own = tagValues(event, 'a')[0] === topic
|
|
126
|
+
return fieldsOf(event).some(({ field, value }) => {
|
|
127
|
+
// A rename moves nothing, on the topic or on any file (Miky, 2026-11-09).
|
|
128
|
+
if (field.startsWith('member:') || field.startsWith('follow:') || field === 'title') return false
|
|
129
|
+
if (!own) return true
|
|
130
|
+
if (field.startsWith('order:') || field.startsWith('look:')) return false
|
|
131
|
+
if (field.startsWith('lists:')) return value === 'true'
|
|
132
|
+
return true
|
|
133
|
+
})
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** Newest first, then by address: the order of a set of topics, from {@link TopicActivity.at}. */
|
|
137
|
+
export function byActivity(at: ReadonlyMap<string, number>): (a: string, b: string) => number {
|
|
138
|
+
return (a, b) => (at.get(b) ?? 0) - (at.get(a) ?? 0) || (a < b ? -1 : a > b ? 1 : 0)
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
function idOf(address: string): string | undefined {
|
|
142
|
+
return ADDRESS.exec(address)?.[3]
|
|
143
|
+
}
|
|
144
|
+
function kindOf(address: string): number | undefined {
|
|
145
|
+
const m = ADDRESS.exec(address)
|
|
146
|
+
return m ? Number(m[1]) : undefined
|
|
147
|
+
}
|
|
148
|
+
function tagValues(event: SignedEvent, name: string): string[] {
|
|
149
|
+
return event.tags.filter((tag) => tag[0] === name && tag[1]).map((tag) => tag[1]!)
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* Whether an event is on the file at `address` (whose root names `folder`),
|
|
154
|
+
* as the fold reads it, rather than merely tagging it: a change by its first
|
|
155
|
+
* `a`, its `O` when it carries one, and its file's own team in `h` (§6.10); a
|
|
156
|
+
* comment by its root (`isAbout`: its one `A`, or its `O` when it has no root,
|
|
157
|
+
* never a crossed one, §6.4); a message by its first `A`. Anybody may tag any
|
|
158
|
+
* file, so a tag alone would let a write in one team move a topic in another.
|
|
159
|
+
*/
|
|
160
|
+
function isOn(event: SignedEvent, address: string, folder: string | null): boolean {
|
|
161
|
+
if (event.kind === KIND_CHANGE) {
|
|
162
|
+
const id = tagValues(event, 'O')[0]
|
|
163
|
+
return tagValues(event, 'a')[0] === address && (id === undefined || id === idOf(address)) && tagValues(event, 'h')[0] === (folder ?? undefined)
|
|
164
|
+
}
|
|
165
|
+
if (event.kind === KIND_COMMENT) return isAbout(event, address)
|
|
166
|
+
return tagValues(event, 'A')[0] === address
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
async function queryChunked(query: QueryFn, filters: readonly Record<string, unknown>[]): Promise<SignedEvent[]> {
|
|
170
|
+
const runs: Promise<SignedEvent[]>[] = []
|
|
171
|
+
for (let i = 0; i < filters.length; i += MAX_FILTERS_PER_QUERY) runs.push(query(filters.slice(i, i + MAX_FILTERS_PER_QUERY)))
|
|
172
|
+
return (await Promise.all(runs)).flat()
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Every file under the given ones, any depth: a project's issues, a
|
|
177
|
+
* document's pages, each by its root's `a` (§6.7). One request per level.
|
|
178
|
+
* Each found file with its root's team and its root's time.
|
|
179
|
+
*/
|
|
180
|
+
async function filesUnder(
|
|
181
|
+
query: QueryFn,
|
|
182
|
+
parents: readonly string[],
|
|
183
|
+
): Promise<{ parent: string; file: ActivityFile; at: number }[]> {
|
|
184
|
+
const out: { parent: string; file: ActivityFile; at: number }[] = []
|
|
185
|
+
// Each file under one is answered once per parent, even when it is listed itself (on another topic, say);
|
|
186
|
+
// each parent is walked once.
|
|
187
|
+
const found = new Set<string>()
|
|
188
|
+
let level = parents.filter((address) => CHILD_KINDS[kindOf(address) ?? -1])
|
|
189
|
+
const walked = new Set(level)
|
|
190
|
+
for (let depth = 0; depth < MAX_DEPTH && level.length > 0; depth++) {
|
|
191
|
+
const kinds = [...new Set(level.flatMap((address) => CHILD_KINDS[kindOf(address)!]!))]
|
|
192
|
+
const filters: Record<string, unknown>[] = []
|
|
193
|
+
for (let i = 0; i < level.length; i += VALUES_PER_FILTER) filters.push({ kinds, '#a': level.slice(i, i + VALUES_PER_FILTER) })
|
|
194
|
+
// Every one, however many: paged past the relay's cap rather than cut at it.
|
|
195
|
+
const roots = await readAll(query, filters)
|
|
196
|
+
const asked = new Set(level)
|
|
197
|
+
const next: string[] = []
|
|
198
|
+
// A replaceable root the relay still holds twice is one file: its newest names its team.
|
|
199
|
+
const newest = new Map<string, { root: SignedEvent; parent: string }>()
|
|
200
|
+
for (const root of roots) {
|
|
201
|
+
const d = tagValues(root, 'd')[0]
|
|
202
|
+
// A root's parent is its one `a` (§6.7): a later one is no parent.
|
|
203
|
+
const parent = tagValues(root, 'a')[0]
|
|
204
|
+
if (!d || !parent || !asked.has(parent) || !(CHILD_KINDS[kindOf(parent)!] ?? []).includes(root.kind)) continue
|
|
205
|
+
const address = `${root.kind}:${root.pubkey}:${d}`
|
|
206
|
+
const held = newest.get(address)
|
|
207
|
+
if (!held || root.created_at > held.root.created_at) newest.set(address, { root, parent })
|
|
208
|
+
}
|
|
209
|
+
const perParent = new Map<string, number>()
|
|
210
|
+
for (const [address, { root, parent }] of [...newest].sort((a, b) => b[1].root.created_at - a[1].root.created_at)) {
|
|
211
|
+
const count = perParent.get(parent) ?? 0
|
|
212
|
+
if (count >= MAX_CHILDREN) continue
|
|
213
|
+
perParent.set(parent, count + 1)
|
|
214
|
+
if (found.has(`${parent} ${address}`)) continue
|
|
215
|
+
found.add(`${parent} ${address}`)
|
|
216
|
+
out.push({ parent, file: { address, folder: folderOf(root) }, at: root.created_at })
|
|
217
|
+
if (CHILD_KINDS[root.kind] && !walked.has(address)) {
|
|
218
|
+
walked.add(address)
|
|
219
|
+
next.push(address)
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
level = next
|
|
223
|
+
}
|
|
224
|
+
return out
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/** One thing to find the newest counting event of: a filter, the file it is on, and the topics its answer is news for. */
|
|
228
|
+
interface Probe {
|
|
229
|
+
filter: Record<string, unknown>
|
|
230
|
+
target: ActivityFile
|
|
231
|
+
topics: string[]
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/**
|
|
235
|
+
* Each topic's newest activity (the rule above), for any set of topics the
|
|
236
|
+
* reader holds — theirs, or every one they can open.
|
|
237
|
+
*
|
|
238
|
+
* Reads, whatever the number of topics: one request per level of files under
|
|
239
|
+
* the listed ones (a project's issues, then each further level of pages),
|
|
240
|
+
* then the newest few events of each topic's conversation and own changes and
|
|
241
|
+
* of each file's changes and comments, every target one filter in the same
|
|
242
|
+
* request (another per {@link MAX_FILTERS_PER_QUERY}). A target whose newest
|
|
243
|
+
* events are all tidying is asked again from older ones, up to a few rounds.
|
|
244
|
+
*
|
|
245
|
+
* Measured 9 Nov 2026 on production over the 47 topics the agent can read
|
|
246
|
+
* (Miky is in 24 of them): about 1.9 MB in 7 requests, 1 s. Most of it is the
|
|
247
|
+
* newest text save of a file, which carries the whole text, and the roots of
|
|
248
|
+
* the issues under listed projects.
|
|
249
|
+
*
|
|
250
|
+
* `query` answers each filter as one request would, honouring `limit` and
|
|
251
|
+
* `until` (the apps' viewer query does). A failed read rejects.
|
|
252
|
+
*/
|
|
253
|
+
export async function readTopicActivity(
|
|
254
|
+
query: QueryFn,
|
|
255
|
+
topics: readonly ActivityTopic[],
|
|
256
|
+
options: { nowSeconds?: number } = {},
|
|
257
|
+
): Promise<TopicActivity> {
|
|
258
|
+
const now = options.nowSeconds ?? Math.floor(Date.now() / 1000)
|
|
259
|
+
const capped = (at: number) => Math.min(at, now)
|
|
260
|
+
const at = new Map<string, number>()
|
|
261
|
+
const files = new Map<string, ActivityFile[]>()
|
|
262
|
+
const folders = new Map<string, string | null>()
|
|
263
|
+
for (const topic of topics) {
|
|
264
|
+
at.set(topic.address, topic.createdAt ? capped(topic.createdAt) : 0)
|
|
265
|
+
files.set(topic.address, [...topic.files])
|
|
266
|
+
folders.set(topic.address, topic.folder ?? null)
|
|
267
|
+
}
|
|
268
|
+
if (topics.length === 0) return { at, files, folders }
|
|
269
|
+
const bump = (topic: string, when: number) => {
|
|
270
|
+
if (capped(when) > (at.get(topic) ?? 0)) at.set(topic, capped(when))
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
// Which topics each file is on (a file can be on several), then the files under them.
|
|
274
|
+
const topicsOf = new Map<string, Set<string>>()
|
|
275
|
+
const onTopic = (file: string, topic: string) => {
|
|
276
|
+
const set = topicsOf.get(file) ?? new Set<string>()
|
|
277
|
+
set.add(topic)
|
|
278
|
+
topicsOf.set(file, set)
|
|
279
|
+
}
|
|
280
|
+
for (const topic of topics) for (const file of topic.files) onTopic(file.address, topic.address)
|
|
281
|
+
const listed = new Map([...topicsOf].map(([file, on]) => [file, new Set(on)]))
|
|
282
|
+
|
|
283
|
+
// Each listed file's team, from its root, for the changes' `h`.
|
|
284
|
+
const folderOfFile = new Map<string, string | null>()
|
|
285
|
+
for (const topic of topics) for (const file of topic.files) if (!folderOfFile.get(file.address)) folderOfFile.set(file.address, file.folder)
|
|
286
|
+
|
|
287
|
+
const fileProbes = (target: ActivityFile, list: string[]): Probe[] => {
|
|
288
|
+
const file = target.address
|
|
289
|
+
const id = fileIdOf(file)
|
|
290
|
+
// Every change carries the file's `a`; its `O` only since 30 Oct 2026. A comment carries `A`, or `O` in its newer form (§6.4).
|
|
291
|
+
return [
|
|
292
|
+
{ filter: { kinds: [KIND_CHANGE], '#a': [file] }, target, topics: list },
|
|
293
|
+
{ filter: { kinds: [KIND_COMMENT], '#A': [file] }, target, topics: list },
|
|
294
|
+
...(id ? [{ filter: { kinds: [KIND_COMMENT], '#O': [id] }, target, topics: list }] : []),
|
|
295
|
+
]
|
|
296
|
+
}
|
|
297
|
+
const first: Probe[] = []
|
|
298
|
+
for (const topic of topics) {
|
|
299
|
+
const target = { address: topic.address, folder: topic.folder ?? null }
|
|
300
|
+
first.push({ filter: { kinds: [KIND_COMMENT, KIND_MESSAGE], '#A': [topic.address] }, target, topics: [topic.address] })
|
|
301
|
+
first.push({ filter: { kinds: [KIND_CHANGE], '#a': [topic.address] }, target, topics: [topic.address] })
|
|
302
|
+
}
|
|
303
|
+
for (const [file, on] of listed) first.push(...fileProbes({ address: file, folder: folderOfFile.get(file) ?? null }, [...on]))
|
|
304
|
+
|
|
305
|
+
// The topics and their listed files are read while the files under them are found, and those as soon as they are.
|
|
306
|
+
const deep = async () => {
|
|
307
|
+
const under = await filesUnder(query, [...listed.keys()])
|
|
308
|
+
// Parents come before their children in `under`, so a page two levels down inherits its topics.
|
|
309
|
+
for (const { parent, file, at: created } of under) {
|
|
310
|
+
for (const topic of topicsOf.get(parent) ?? []) {
|
|
311
|
+
if (!topicsOf.get(file.address)?.has(topic)) files.get(topic)!.push(file)
|
|
312
|
+
onTopic(file.address, topic)
|
|
313
|
+
// A new issue filed in a listed project is news.
|
|
314
|
+
bump(topic, created)
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
const then: Probe[] = []
|
|
318
|
+
const asFound = new Map(under.map((found) => [found.file.address, found.file]))
|
|
319
|
+
for (const [file, target] of asFound) {
|
|
320
|
+
// Only for the topics it was not already read for as a listed file.
|
|
321
|
+
const fresh = [...(topicsOf.get(file) ?? [])].filter((topic) => !listed.get(file)?.has(topic))
|
|
322
|
+
if (fresh.length > 0) then.push(...fileProbes(target, fresh))
|
|
323
|
+
}
|
|
324
|
+
await newestOf(then)
|
|
325
|
+
}
|
|
326
|
+
await Promise.all([deep(), newestOf(first)])
|
|
327
|
+
return { at, files, folders }
|
|
328
|
+
|
|
329
|
+
/** Per probe, the newest event that counts for one of its topics. Read in rounds; each round asks only what is still open. */
|
|
330
|
+
async function newestOf(probes: readonly Probe[]): Promise<void> {
|
|
331
|
+
let open = probes.map((probe) => ({ probe, filter: { ...probe.filter, limit: FIRST_PAGE } as Record<string, unknown> }))
|
|
332
|
+
for (let round = 0; round < MAX_ROUNDS && open.length > 0; round++) {
|
|
333
|
+
const events = await queryChunked(query, open.map((o) => o.filter))
|
|
334
|
+
const still: typeof open = []
|
|
335
|
+
for (const o of open) {
|
|
336
|
+
const page = events.filter((event) => answers(event, o.filter)).sort((a, b) => b.created_at - a.created_at)
|
|
337
|
+
const left = new Set(o.probe.topics)
|
|
338
|
+
for (const event of page) {
|
|
339
|
+
if (!isOn(event, o.probe.target.address, o.probe.target.folder)) continue
|
|
340
|
+
for (const topic of [...left]) {
|
|
341
|
+
if (!countsAsActivity(event, topic)) continue
|
|
342
|
+
bump(topic, event.created_at)
|
|
343
|
+
left.delete(topic)
|
|
344
|
+
}
|
|
345
|
+
if (left.size === 0) break
|
|
346
|
+
}
|
|
347
|
+
const limit = o.filter.limit as number
|
|
348
|
+
if (left.size === 0 || page.length < limit) continue
|
|
349
|
+
const until = page[page.length - 1]!.created_at
|
|
350
|
+
// A second holding a whole page on its own: ask a bigger page of it rather than step past it.
|
|
351
|
+
const same = until === (o.filter.until as number | undefined)
|
|
352
|
+
still.push({ probe: { ...o.probe, topics: [...left] }, filter: { ...o.probe.filter, until, limit: same ? limit * 4 : limit * 2 } })
|
|
353
|
+
}
|
|
354
|
+
open = still
|
|
355
|
+
}
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
/** A live watch's handle. */
|
|
360
|
+
export interface ActivityWatch {
|
|
361
|
+
/** Idempotent. Closes its subscriptions. */
|
|
362
|
+
stop(): void
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
function chunked<T>(list: readonly T[], size: number): T[][] {
|
|
366
|
+
const out: T[][] = []
|
|
367
|
+
for (let i = 0; i < list.length; i += size) out.push(list.slice(i, i + size))
|
|
368
|
+
return out
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
/**
|
|
372
|
+
* Keep {@link TopicActivity} current, live: hear every new event that is news
|
|
373
|
+
* for a topic it holds (the rule above), raise that topic's time, and say so.
|
|
374
|
+
* A new file under a listed one (an issue filed in a listed project) is news,
|
|
375
|
+
* and its own activity is heard from then on.
|
|
376
|
+
*
|
|
377
|
+
* One REQ for every topic (another per {@link MAX_FILTERS_PER_REQ} filters).
|
|
378
|
+
* `onActivity` is called with the topic and its new time, after `activity.at`
|
|
379
|
+
* is raised in place; an event that is not news, or older than what is held,
|
|
380
|
+
* says nothing.
|
|
381
|
+
*
|
|
382
|
+
* As {@link watchListedConversations} does, every filter also names the teams
|
|
383
|
+
* of the topics and their files (`namesTeams`, on by default), since our
|
|
384
|
+
* relay does not yet deliver a team's event live to a subscription that names
|
|
385
|
+
* no team. A file whose team is unknown is still asked for; it is heard once
|
|
386
|
+
* the relay delivers by file.
|
|
387
|
+
*/
|
|
388
|
+
export function watchTopicActivity(
|
|
389
|
+
relay: Pick<LiveRelay, 'subscribe'>,
|
|
390
|
+
activity: TopicActivity,
|
|
391
|
+
onActivity: (topic: string, at: number) => void,
|
|
392
|
+
options: {
|
|
393
|
+
/** Unix seconds to hear from. Defaults to now. */
|
|
394
|
+
since?: number
|
|
395
|
+
namesTeams?: boolean
|
|
396
|
+
onClosed?: (reason: string) => void
|
|
397
|
+
now?: () => number
|
|
398
|
+
setTimer?: (run: () => void, ms: number) => unknown
|
|
399
|
+
clearTimer?: (timer: unknown) => void
|
|
400
|
+
} = {},
|
|
401
|
+
): ActivityWatch {
|
|
402
|
+
const timers = globalThis as unknown as { setTimeout(run: () => void, ms: number): unknown; clearTimeout(timer: unknown): void }
|
|
403
|
+
const setTimer = options.setTimer ?? ((run: () => void, ms: number) => timers.setTimeout(run, ms))
|
|
404
|
+
const clearTimer = options.clearTimer ?? ((timer: unknown) => timers.clearTimeout(timer))
|
|
405
|
+
const nowSeconds = () => Math.floor((options.now ?? Date.now)() / 1000)
|
|
406
|
+
const namesTeams = options.namesTeams ?? true
|
|
407
|
+
let since = Math.min(options.since ?? nowSeconds(), nowSeconds())
|
|
408
|
+
|
|
409
|
+
// Which topics each file is news for; each file's team; the files by id, for a comment's `O`.
|
|
410
|
+
const byAddress = new Map<string, Set<string>>()
|
|
411
|
+
const folderOfFile = new Map<string, string | null>()
|
|
412
|
+
const byId = new Map<string, Set<string>>()
|
|
413
|
+
const teams = new Set<string>()
|
|
414
|
+
const add = (file: ActivityFile, topic: string) => {
|
|
415
|
+
const set = byAddress.get(file.address) ?? new Set<string>()
|
|
416
|
+
set.add(topic)
|
|
417
|
+
byAddress.set(file.address, set)
|
|
418
|
+
if (!folderOfFile.get(file.address)) folderOfFile.set(file.address, file.folder)
|
|
419
|
+
const id = fileIdOf(file.address)
|
|
420
|
+
if (id) byId.set(id, (byId.get(id) ?? new Set<string>()).add(file.address))
|
|
421
|
+
if (file.folder) teams.add(file.folder)
|
|
422
|
+
}
|
|
423
|
+
for (const [topic, list] of activity.files) for (const file of list) add(file, topic)
|
|
424
|
+
// Files heard under each parent since the watch began, beside those read: capped as the read is.
|
|
425
|
+
const children = new Map<string, number>()
|
|
426
|
+
for (const folder of activity.folders.values()) if (folder) teams.add(folder)
|
|
427
|
+
const topicSet = new Set(activity.at.keys())
|
|
428
|
+
|
|
429
|
+
let subs: { close(): void }[] = []
|
|
430
|
+
let timer: unknown = null
|
|
431
|
+
let stopped = false
|
|
432
|
+
|
|
433
|
+
const filtersNow = (): Record<string, unknown>[] => {
|
|
434
|
+
const topicAddresses = [...topicSet]
|
|
435
|
+
const fileAddresses = [...byAddress.keys()]
|
|
436
|
+
const parents = fileAddresses.filter((address) => CHILD_KINDS[kindOf(address) ?? -1])
|
|
437
|
+
const childKinds = [...new Set(parents.flatMap((address) => CHILD_KINDS[kindOf(address)!]!))]
|
|
438
|
+
const base: Record<string, unknown>[] = [
|
|
439
|
+
...chunked(topicAddresses, VALUES_PER_FILTER).map((values) => ({ kinds: [KIND_COMMENT, KIND_MESSAGE], '#A': values })),
|
|
440
|
+
...chunked([...topicAddresses, ...fileAddresses], VALUES_PER_FILTER).map((values) => ({ kinds: [KIND_CHANGE], '#a': values })),
|
|
441
|
+
...chunked(fileAddresses, VALUES_PER_FILTER).map((values) => ({ kinds: [KIND_COMMENT], '#A': values })),
|
|
442
|
+
...chunked([...byId.keys()], VALUES_PER_FILTER).map((values) => ({ kinds: [KIND_COMMENT], '#O': values })),
|
|
443
|
+
...chunked(parents, VALUES_PER_FILTER).map((values) => ({ kinds: childKinds, '#a': values })),
|
|
444
|
+
]
|
|
445
|
+
const teamChunks = namesTeams && teams.size > 0 ? chunked([...teams], 128) : [undefined]
|
|
446
|
+
return teamChunks.flatMap((h) => base.map((f) => ({ ...f, ...(h ? { '#h': h } : {}), since })))
|
|
447
|
+
}
|
|
448
|
+
|
|
449
|
+
const open = () => {
|
|
450
|
+
for (const sub of subs) sub.close()
|
|
451
|
+
subs = chunked(filtersNow(), MAX_FILTERS_PER_REQ).map((filters) =>
|
|
452
|
+
relay.subscribe(filters, hear, options.onClosed ? { onClosed: options.onClosed } : undefined),
|
|
453
|
+
)
|
|
454
|
+
}
|
|
455
|
+
const reopenSoon = () => {
|
|
456
|
+
if (stopped || timer !== null) return
|
|
457
|
+
timer = setTimer(() => {
|
|
458
|
+
timer = null
|
|
459
|
+
if (!stopped) open()
|
|
460
|
+
}, LISTED_WATCH_REBUILD_MS)
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
function raise(topic: string, created: number) {
|
|
464
|
+
const when = Math.min(created, nowSeconds())
|
|
465
|
+
if (when <= (activity.at.get(topic) ?? 0)) return
|
|
466
|
+
activity.at.set(topic, when)
|
|
467
|
+
onActivity(topic, when)
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
function hear(event: SignedEvent) {
|
|
471
|
+
if (stopped) return
|
|
472
|
+
since = Math.max(since, Math.min(event.created_at, nowSeconds()))
|
|
473
|
+
// A new file under a listed one: news, and listened to from now on.
|
|
474
|
+
const d = tagValues(event, 'd')[0]
|
|
475
|
+
// Its parent is its one `a` (§6.7), a held file whose kind holds this kind (a project its issue, a page its page).
|
|
476
|
+
const first = tagValues(event, 'a')[0]
|
|
477
|
+
const parent = d && first && byAddress.has(first) && CHILD_KINDS[kindOf(first) ?? -1]?.includes(event.kind) ? first : undefined
|
|
478
|
+
if (parent && d) {
|
|
479
|
+
const file = { address: `${event.kind}:${event.pubkey}:${d}`, folder: folderOf(event) }
|
|
480
|
+
const fresh = !byAddress.has(file.address)
|
|
481
|
+
const listen = fresh && (children.get(parent) ?? 0) < MAX_CHILDREN
|
|
482
|
+
if (listen) children.set(parent, (children.get(parent) ?? 0) + 1)
|
|
483
|
+
for (const topic of byAddress.get(parent)!) {
|
|
484
|
+
if (listen) {
|
|
485
|
+
activity.files.get(topic)?.push(file)
|
|
486
|
+
add(file, topic)
|
|
487
|
+
}
|
|
488
|
+
raise(topic, event.created_at)
|
|
489
|
+
}
|
|
490
|
+
if (listen) reopenSoon()
|
|
491
|
+
return
|
|
492
|
+
}
|
|
493
|
+
// The files and topics it may be on, then only those it is on as the read judges it.
|
|
494
|
+
const names = new Set<string>()
|
|
495
|
+
if (event.kind === KIND_CHANGE) {
|
|
496
|
+
if (first) names.add(first)
|
|
497
|
+
} else if (event.kind === KIND_COMMENT) {
|
|
498
|
+
const root = tagValues(event, 'A')[0] ?? first
|
|
499
|
+
if (root) names.add(root)
|
|
500
|
+
for (const id of tagValues(event, 'O')) for (const address of byId.get(id) ?? []) names.add(address)
|
|
501
|
+
} else {
|
|
502
|
+
// A chat message is a topic's only, as the read asks for it: none lists under a file.
|
|
503
|
+
const root = tagValues(event, 'A')[0]
|
|
504
|
+
if (root && topicSet.has(root)) names.add(root)
|
|
505
|
+
}
|
|
506
|
+
const topics = new Set<string>()
|
|
507
|
+
for (const name of names) {
|
|
508
|
+
if (topicSet.has(name) && isOn(event, name, activity.folders.get(name) ?? null)) topics.add(name)
|
|
509
|
+
if (byAddress.has(name) && isOn(event, name, folderOfFile.get(name) ?? null)) for (const topic of byAddress.get(name)!) topics.add(topic)
|
|
510
|
+
}
|
|
511
|
+
for (const topic of topics) if (countsAsActivity(event, topic)) raise(topic, event.created_at)
|
|
512
|
+
}
|
|
513
|
+
|
|
514
|
+
open()
|
|
515
|
+
return {
|
|
516
|
+
stop() {
|
|
517
|
+
if (stopped) return
|
|
518
|
+
stopped = true
|
|
519
|
+
if (timer !== null) clearTimer(timer)
|
|
520
|
+
for (const sub of subs) sub.close()
|
|
521
|
+
subs = []
|
|
522
|
+
},
|
|
523
|
+
}
|
|
524
|
+
}
|
package/src/index.ts
CHANGED
|
@@ -182,6 +182,22 @@ export {
|
|
|
182
182
|
type ListedFile,
|
|
183
183
|
} from './topics.js'
|
|
184
184
|
|
|
185
|
+
/**
|
|
186
|
+
* Your topics, newest activity first: the one rule every app orders topics by
|
|
187
|
+
* (TOPI-10), read once for any set of topics and kept current live.
|
|
188
|
+
*/
|
|
189
|
+
export {
|
|
190
|
+
readTopicActivity,
|
|
191
|
+
watchTopicActivity,
|
|
192
|
+
countsAsActivity,
|
|
193
|
+
byActivity,
|
|
194
|
+
activityTopics,
|
|
195
|
+
type ActivityFile,
|
|
196
|
+
type ActivityTopic,
|
|
197
|
+
type TopicActivity,
|
|
198
|
+
type ActivityWatch,
|
|
199
|
+
} from './activity.js'
|
|
200
|
+
|
|
185
201
|
/**
|
|
186
202
|
* A topic's All: the conversations of every file on its list, read in one go
|
|
187
203
|
* and kept live, each file's events ready for the shared fold (SPEC §11.8).
|
package/src/projection.ts
CHANGED
|
@@ -3910,8 +3910,10 @@ export async function resolveForeignRoots(
|
|
|
3910
3910
|
* `listRead`, where the relay offers the list read (NIP-11 `file_list`), reads each file of the relay's file kinds
|
|
3911
3911
|
* as its first record and its fields' current changes (§6.13), not every change ever made to it: no text, and a
|
|
3912
3912
|
* deleted file is absent. Other kinds are read as before.
|
|
3913
|
+
* `parentsListRead`, with `archivedWith`, reads only the parents walked for an archive by the list read (with
|
|
3914
|
+
* `listRead`'s fallback for one it leaves out); the files asked for are still read in full, their text included.
|
|
3913
3915
|
*/
|
|
3914
|
-
options: Pick<ArchiveReadOptions, 'archivedWith'> & { listRead?: boolean } = {},
|
|
3916
|
+
options: Pick<ArchiveReadOptions, 'archivedWith'> & { listRead?: boolean; parentsListRead?: boolean } = {},
|
|
3915
3917
|
): Promise<ForeignObject[]> {
|
|
3916
3918
|
const pointers = new Map<string, AddressPointer>()
|
|
3917
3919
|
for (const reference of references) {
|
|
@@ -3952,7 +3954,7 @@ export async function resolveForeignRoots(
|
|
|
3952
3954
|
objects.map((object) => ({ object, manifest: manifestOf(object) })),
|
|
3953
3955
|
query,
|
|
3954
3956
|
cache,
|
|
3955
|
-
options.listRead ? FILE_KINDS : [],
|
|
3957
|
+
options.listRead || options.parentsListRead ? FILE_KINDS : [],
|
|
3956
3958
|
)
|
|
3957
3959
|
}
|
|
3958
3960
|
return objects
|
package/src/topics.ts
CHANGED
|
@@ -346,6 +346,8 @@ export interface ReadTopic {
|
|
|
346
346
|
object: ForeignObject
|
|
347
347
|
/** Its Folder, from its root (§6.2): where an entry on its list is filed. */
|
|
348
348
|
folder: string
|
|
349
|
+
/** Its first record's time, Unix seconds: its time in the order of topics when nothing has happened in it since. */
|
|
350
|
+
createdAt: number
|
|
349
351
|
/** Its list, as {@link topicLists} reads it. */
|
|
350
352
|
listed: ListedFile[]
|
|
351
353
|
/**
|
|
@@ -434,7 +436,7 @@ function personInFilesFilters(person: string, files: readonly string[]): Record<
|
|
|
434
436
|
}
|
|
435
437
|
|
|
436
438
|
/** Whether an event answers a filter, as NIP-01 reads it: kinds, authors, `#x` tags, `since` and `until`. */
|
|
437
|
-
function answers(event: SignedEvent, filter: Record<string, unknown>): boolean {
|
|
439
|
+
export function answers(event: SignedEvent, filter: Record<string, unknown>): boolean {
|
|
438
440
|
const { kinds, authors, since, until } = filter as { kinds?: number[]; authors?: string[]; since?: number; until?: number }
|
|
439
441
|
if (kinds && !kinds.includes(event.kind)) return false
|
|
440
442
|
if (authors && !authors.includes(event.pubkey)) return false
|
|
@@ -452,7 +454,7 @@ function answers(event: SignedEvent, filter: Record<string, unknown>): boolean {
|
|
|
452
454
|
* nothing fills a page, as at Miky's scale; never a silent cut at the relay's
|
|
453
455
|
* cap. A second holding a page's worth on its own ends the walk there.
|
|
454
456
|
*/
|
|
455
|
-
async function readAll(query: QueryFn, filters: readonly Record<string, unknown>[]): Promise<SignedEvent[]> {
|
|
457
|
+
export async function readAll(query: QueryFn, filters: readonly Record<string, unknown>[]): Promise<SignedEvent[]> {
|
|
456
458
|
const out = new Map<string, SignedEvent>()
|
|
457
459
|
let open = filters.map((filter) => ({ ...filter, limit: RELAY_PAGE_CEILING }))
|
|
458
460
|
while (open.length) {
|
|
@@ -489,12 +491,17 @@ async function readAll(query: QueryFn, filters: readonly Record<string, unknown>
|
|
|
489
491
|
*
|
|
490
492
|
* How the viewer is in each topic is {@link followingOf} over its root and
|
|
491
493
|
* the changes naming them (TEA-6), the fold Peek's switch reads too.
|
|
494
|
+
* `parentsListRead`, where the relay offers the list read (NIP-11
|
|
495
|
+
* `file_list`): the parents walked to see whether a topic is archived with one
|
|
496
|
+
* are read as their current values (§6.13), not every change ever made to them
|
|
497
|
+
* (ALO-15). The topics themselves are read as before, their text included.
|
|
498
|
+
*
|
|
492
499
|
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-topic-keeps-its-own-list-of-files.md
|
|
493
500
|
*/
|
|
494
501
|
export async function readTopics(
|
|
495
502
|
query: QueryFn,
|
|
496
503
|
me: string,
|
|
497
|
-
options: { cache?: ProjectionCache; fileKinds?: readonly number[]; nowSeconds?: number } = {},
|
|
504
|
+
options: { cache?: ProjectionCache; fileKinds?: readonly number[]; nowSeconds?: number; parentsListRead?: boolean } = {},
|
|
498
505
|
): Promise<TopicsRead> {
|
|
499
506
|
const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000)
|
|
500
507
|
const rootEvents = await readAll(query, [{ kinds: [KIND_TOPIC] }])
|
|
@@ -509,7 +516,7 @@ export async function readTopics(
|
|
|
509
516
|
const addresses = [...roots.keys()]
|
|
510
517
|
if (addresses.length === 0) return { me, topics: [], membership: foldMemberships(me, [], nowSeconds), mentionedIn: new Set(), inConversations: new Map() }
|
|
511
518
|
const [objects, lists, part, states] = await Promise.all([
|
|
512
|
-
resolveForeignRoots(addresses, query, options.cache, { archivedWith: true }),
|
|
519
|
+
resolveForeignRoots(addresses, query, options.cache, { archivedWith: true, parentsListRead: options.parentsListRead }),
|
|
513
520
|
listsOf(query, addresses, Promise.resolve(roots), options),
|
|
514
521
|
// Held once each, though one comment can answer two of the filters: the folds count events.
|
|
515
522
|
readAll(query, personInFilesFilters(me, addresses)),
|
|
@@ -550,7 +557,7 @@ export async function readTopics(
|
|
|
550
557
|
const address = object.address!
|
|
551
558
|
// The team is the topic's own Folder; a team's default reaches no topic, so its roster is not needed (§11.8).
|
|
552
559
|
const following = followingOf({ address, team: folder }, me, { events: [root, ...(byTopic.get(address) ?? [])], listing: states })
|
|
553
|
-
return [{ address, object, folder, listed: lists.get(address) ?? [], following, yours: following.in, space: spaces.has(address) }]
|
|
560
|
+
return [{ address, object, folder, createdAt: root.created_at, listed: lists.get(address) ?? [], following, yours: following.in, space: spaces.has(address) }]
|
|
554
561
|
})
|
|
555
562
|
return { me, topics, membership, mentionedIn, inConversations }
|
|
556
563
|
}
|