@estiva-app/interop 0.74.0 → 0.75.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/src/topics.ts CHANGED
@@ -25,13 +25,36 @@
25
25
  * nobody to the file (§11.8).
26
26
  */
27
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'
28
+ import { RELAY_PAGE_CEILING } from '@estiva-app/protocol'
29
+ import {
30
+ byOrder,
31
+ candidateFilesOf,
32
+ fileContext,
33
+ foldMemberships,
34
+ HORIZON_SECONDS,
35
+ membersOf,
36
+ membershipJudges,
37
+ REPLY_FLOOR_CONTEXT,
38
+ streamHasUnread,
39
+ streamTermsOf,
40
+ THREAD_RULE_FROM,
41
+ type MembershipRead,
42
+ } from '@estiva-app/conversation'
43
+ import {
44
+ conversationsOf,
45
+ folderOf,
46
+ isArchived,
47
+ resolveForeignRoots,
48
+ type ForeignObject,
49
+ type ProjectionCache,
50
+ type QueryFn,
51
+ } from './projection.js'
30
52
 
31
53
  const KIND_CHANGE = 1851
32
54
  /** The topic (bare file) kind: the only lists this stage reads (Miky, 2026-10-30). */
33
55
  const KIND_TOPIC = 30840
34
56
  const KIND_FOLDER = 39000
57
+ const KIND_COMMENT = 1111
35
58
  /** Listed ids resolved per request: 2 × this stays under a relay's usual `limit` cap. */
36
59
  const RESOLVE_BATCH = 100
37
60
  /**
@@ -282,10 +305,20 @@ export async function topicLists(
282
305
  options: { fileKinds?: readonly number[] } = {},
283
306
  ): Promise<Map<string, ListedFile[]>> {
284
307
  const asked = [...new Set(topics)]
308
+ if (asked.length === 0) return new Map()
309
+ return listsOf(query, asked, rootsOf(query, asked), options)
310
+ }
311
+
312
+ /** {@link topicLists} with the roots already asked for: {@link readTopics} reads them once for everything. */
313
+ async function listsOf(
314
+ query: QueryFn,
315
+ asked: readonly string[],
316
+ rootsRead: Promise<ReadonlyMap<string, SignedEvent>>,
317
+ options: { fileKinds?: readonly number[] },
318
+ ): Promise<Map<string, ListedFile[]>> {
285
319
  const out = new Map<string, ListedFile[]>(asked.map((topic) => [topic, []]))
286
- if (asked.length === 0) return out
287
320
  // One filter per topic in one request, so a relay's cap on an answer cuts no more than it would for that topic alone.
288
- const [roots, events] = await Promise.all([rootsOf(query, asked), query(asked.map(topicListFilter))])
321
+ const [roots, events] = await Promise.all([rootsRead, query(asked.map(topicListFilter))])
289
322
  const folderOfList = (list: string) => {
290
323
  const root = out.has(list) ? roots.get(list) : undefined
291
324
  return root ? folderOf(root) : null
@@ -299,6 +332,221 @@ export async function topicLists(
299
332
  return out
300
333
  }
301
334
 
335
+ /** A topic as {@link readTopics} reads it. */
336
+ export interface ReadTopic {
337
+ address: string
338
+ /** As its roots and changes draw it: its title and summary slots, and `archived`, its own or its parent's (§6.5). */
339
+ object: ForeignObject
340
+ /** Its Folder, from its root (§6.2): where an entry on its list is filed. */
341
+ folder: string
342
+ /** Its list, as {@link topicLists} reads it. */
343
+ listed: ListedFile[]
344
+ /**
345
+ * The viewer is a member (§11.8): by the horizon's membership read, or,
346
+ * where that read has no word on them, over all history — a topic joined
347
+ * before the horizon with nothing since is still theirs, as Peek's Topics
348
+ * says.
349
+ */
350
+ yours: boolean
351
+ }
352
+
353
+ /** Every topic the viewer can read, and the membership read that judges their dots. */
354
+ export interface TopicsRead {
355
+ me: string
356
+ topics: ReadTopic[]
357
+ membership: MembershipRead
358
+ }
359
+
360
+ /** The filters for a person's part in some files over all history: the changes naming them, what they wrote, what names them. */
361
+ function personInFilesFilters(person: string, files: readonly string[]): Record<string, unknown>[] {
362
+ return [
363
+ { kinds: [KIND_CHANGE], '#a': files, '#p': [person] },
364
+ { kinds: [KIND_COMMENT], '#A': files, authors: [person] },
365
+ { kinds: [KIND_COMMENT], '#a': files, authors: [person] },
366
+ { kinds: [KIND_COMMENT], '#A': files, '#p': [person] },
367
+ { kinds: [KIND_COMMENT], '#a': files, '#p': [person] },
368
+ ]
369
+ }
370
+
371
+ /** Whether an event answers a filter, as NIP-01 reads it: kinds, authors, `#x` tags, `since` and `until`. */
372
+ function answers(event: SignedEvent, filter: Record<string, unknown>): boolean {
373
+ const { kinds, authors, since, until } = filter as { kinds?: number[]; authors?: string[]; since?: number; until?: number }
374
+ if (kinds && !kinds.includes(event.kind)) return false
375
+ if (authors && !authors.includes(event.pubkey)) return false
376
+ if (since !== undefined && event.created_at < since) return false
377
+ if (until !== undefined && event.created_at > until) return false
378
+ return Object.entries(filter).every(
379
+ ([key, values]) => !key.startsWith('#') || event.tags.some((t) => t[0] === key.slice(1) && (values as string[]).includes(t[1])),
380
+ )
381
+ }
382
+
383
+ /**
384
+ * Everything the filters match, however many: each asked with a page's
385
+ * `limit`, and a filter whose answer filled it asked again from its oldest
386
+ * second down (`until`), until a page comes back short. One request when
387
+ * nothing fills a page, as at Miky's scale; never a silent cut at the relay's
388
+ * cap. A second holding a page's worth on its own ends the walk there.
389
+ */
390
+ async function readAll(query: QueryFn, filters: readonly Record<string, unknown>[]): Promise<SignedEvent[]> {
391
+ const out = new Map<string, SignedEvent>()
392
+ let open = filters.map((filter) => ({ ...filter, limit: RELAY_PAGE_CEILING }))
393
+ while (open.length) {
394
+ const events = await query(open)
395
+ for (const event of events) out.set(event.id, event)
396
+ open = open.flatMap((filter) => {
397
+ const page = events.filter((event) => answers(event, filter))
398
+ if (page.length < filter.limit) return []
399
+ const until = Math.min(...page.map((event) => event.created_at))
400
+ return until === (filter as { until?: number }).until ? [] : [{ ...filter, until }]
401
+ })
402
+ }
403
+ return [...out.values()]
404
+ }
405
+
406
+ /** Whether the person is a member of the file over all history, folded as its own page folds it. */
407
+ function memberOverAllHistory(person: string, file: string, events: readonly SignedEvent[]): boolean {
408
+ const [kind, pubkey, ...d] = file.split(':')
409
+ // The root, dated before everything: its author is a member unless a leave of theirs says otherwise.
410
+ const root = { id: '0'.repeat(64), pubkey: pubkey ?? '', kind: Number(kind), created_at: 0, tags: [['d', d.join(':')]], content: '', sig: '' }
411
+ return membersOf(file, [root, ...events]).has(person)
412
+ }
413
+
414
+ /**
415
+ * Every topic the viewer can read, once (SHIPS-2): each with its list, its
416
+ * archive (its own, or with its project), its Folder and whether it is the
417
+ * viewer's — the one read Ship's Topics, a topic's page and Add to topic draw
418
+ * from, and Leaf's Add to topic too.
419
+ *
420
+ * Three rounds whatever the number of topics: every `kind:30840` root; then
421
+ * the topics as drawn, their lists and the viewer's part in them; then the
422
+ * listed ids and archived parents. No conversation is read here:
423
+ * {@link topicConversations} is for a page that draws them.
424
+ *
425
+ * The viewer's part is one read over all history, narrowed to the topics —
426
+ * the changes naming them, what they wrote, what names them — and the
427
+ * horizon's membership is folded from the part of it inside the horizon, as
428
+ * {@link membershipQueries} would have read it for these files. On
429
+ * production, QA-2's horizon read over every file was 500 KB; over the topics
430
+ * it is a few.
431
+ *
432
+ * "Yours" is today's membership fold (§11.8); following replaces it in this
433
+ * same function (Teams and following, milestone 5).
434
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-topic-keeps-its-own-list-of-files.md
435
+ */
436
+ export async function readTopics(
437
+ query: QueryFn,
438
+ me: string,
439
+ options: { cache?: ProjectionCache; fileKinds?: readonly number[]; nowSeconds?: number } = {},
440
+ ): Promise<TopicsRead> {
441
+ const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000)
442
+ const rootEvents = await readAll(query, [{ kinds: [KIND_TOPIC] }])
443
+ const roots = new Map<string, SignedEvent>()
444
+ for (const root of rootEvents) {
445
+ if (root.kind !== KIND_TOPIC) continue
446
+ const address = `${root.kind}:${root.pubkey}:${tagOf(root, 'd') ?? ''}`
447
+ const held = roots.get(address)
448
+ // Two versions of one record: NIP-01's later created_at, then the lower id (§6.3).
449
+ if (!held || root.created_at > held.created_at || (root.created_at === held.created_at && root.id < held.id)) roots.set(address, root)
450
+ }
451
+ const addresses = [...roots.keys()]
452
+ if (addresses.length === 0) return { me, topics: [], membership: foldMemberships(me, [], nowSeconds) }
453
+ const [objects, lists, part] = await Promise.all([
454
+ resolveForeignRoots(addresses, query, options.cache, { archivedWith: true }),
455
+ listsOf(query, addresses, Promise.resolve(roots), options),
456
+ // Held once each, though one comment can answer two of the filters: the folds count events.
457
+ readAll(query, personInFilesFilters(me, addresses)),
458
+ ])
459
+ const membership = foldMemberships(me, part.filter((e) => e.created_at >= nowSeconds - HORIZON_SECONDS), nowSeconds)
460
+ // Each topic's own events, so each is folded over its own and not over all of them.
461
+ const byTopic = new Map<string, SignedEvent[]>()
462
+ for (const event of part) for (const file of candidateFilesOf(event)) byTopic.set(file, [...(byTopic.get(file) ?? []), event])
463
+ const none = new Set<string>()
464
+ const topics = objects.flatMap((object): ReadTopic[] => {
465
+ const root = object.address ? roots.get(object.address) : undefined
466
+ const folder = root ? folderOf(root) : null
467
+ if (!root || !folder || object.unreachable) return []
468
+ const address = object.address!
469
+ const yours =
470
+ streamTermsOf(address, membership, me, none).member || (!membershipJudges(address, membership, me) && memberOverAllHistory(me, address, byTopic.get(address) ?? []))
471
+ return [{ address, object, folder, listed: lists.get(address) ?? [], yours }]
472
+ })
473
+ return { me, topics, membership }
474
+ }
475
+
476
+ // An untitled topic sorts where the apps' "Untitled topic" would.
477
+ const titleOf = (topic: ReadTopic) => topic.object.slots.title?.value || 'Untitled topic'
478
+
479
+ /**
480
+ * What Add to topic offers: the open topics in a Folder the viewer is in —
481
+ * `folders`, the Folders the relay lists for them, where it accepts their
482
+ * entry — theirs first, then the rest, each A–Z. An archived topic, its own
483
+ * or with its project, is read-only and is not offered.
484
+ */
485
+ export function addableTopics(read: TopicsRead, folders: ReadonlySet<string>): { yours: ReadTopic[]; others: ReadTopic[] } {
486
+ const open = read.topics
487
+ .filter((topic) => !isArchived(topic.object) && folders.has(topic.folder))
488
+ .sort((a, b) => titleOf(a).localeCompare(titleOf(b)))
489
+ return { yours: open.filter((topic) => topic.yours), others: open.filter((topic) => !topic.yours) }
490
+ }
491
+
492
+ /** A topic's conversations in Peek: how many, and whether one has something new for the viewer. */
493
+ export interface TopicConversation {
494
+ /** Thread roots addressed to the topic, as Peek's Topics badge counts them. */
495
+ conversations: number
496
+ /** Peek's dot: only on an open topic of the viewer's. */
497
+ unread: boolean
498
+ }
499
+
500
+ /**
501
+ * Each topic's conversations and dot, as Peek's Topics shows them (SHIPS-2):
502
+ * the count is the thread roots addressed to the topic (`conversationsOf`),
503
+ * the dot is {@link streamHasUnread} on the topic's own marker, gated by
504
+ * membership (§11.8), on the viewer's open topics only.
505
+ *
506
+ * The read state and the muted list are encrypted, so the app hands in what
507
+ * it holds: `merged` (the merged markers, once the first merge has landed)
508
+ * and `muted`. Replies are read only for the topics a dot is judged on, and
509
+ * only from the latest second before which none can be unread: the thread
510
+ * rule's cut-over, the reply floor, and when the viewer joined (§11.3: a
511
+ * reply is read by its thread's marker or the floor, never the topic's).
512
+ */
513
+ export async function topicConversations(
514
+ read: TopicsRead,
515
+ query: QueryFn,
516
+ state: { merged: Readonly<Record<string, number>>; muted: ReadonlySet<string>; nowSeconds?: number },
517
+ options: { cache?: ProjectionCache } = {},
518
+ ): Promise<Map<string, TopicConversation>> {
519
+ const nowSeconds = state.nowSeconds ?? Math.floor(Date.now() / 1000)
520
+ const terms = (address: string) => streamTermsOf(address, read.membership, read.me, state.muted)
521
+ const judged = new Set(read.topics.filter((topic) => topic.yours && !isArchived(topic.object)).map((topic) => topic.address))
522
+ const repliesSince = (address: string) => {
523
+ if (!judged.has(address)) return null
524
+ const floor = state.merged[REPLY_FLOOR_CONTEXT]
525
+ return Math.max(THREAD_RULE_FROM, floor ?? 0, terms(address).since ?? 0)
526
+ }
527
+ const files = read.topics.map((topic) => ({ ...topic.object, ref: topic.address }))
528
+ const held = await conversationsOf(files, query, options.cache, { replies: true, repliesSince })
529
+ const out = new Map<string, TopicConversation>()
530
+ for (const topic of read.topics) {
531
+ const messages = held[topic.address]
532
+ if (!messages) continue
533
+ const context = fileContext(topic.address)
534
+ const unread =
535
+ !!context &&
536
+ judged.has(topic.address) &&
537
+ streamHasUnread(
538
+ // A reply from before the thread rule's cut-over never lit a row (CON-34).
539
+ messages.filter((m) => m.root === m.id || m.at >= THREAD_RULE_FROM),
540
+ context,
541
+ terms(topic.address),
542
+ { merged: state.merged, me: read.me, nowSeconds, horizonSeconds: HORIZON_SECONDS },
543
+ (id) => read.membership.mentioned.has(id),
544
+ )
545
+ out.set(topic.address, { conversations: messages.filter((m) => m.root === m.id).length, unread })
546
+ }
547
+ return out
548
+ }
549
+
302
550
  /** Each id's address when exactly one file of `fileKinds` the reader can read holds it; an id held by none or by two is left out. */
303
551
  async function resolveIds(query: QueryFn, ids: readonly string[], fileKinds?: readonly number[]): Promise<Map<string, string>> {
304
552
  // Never a Folder's `39000`, which shares its uuid (§11.1): an id only a Folder holds resolves to nothing.