@estiva-app/interop 0.74.1 → 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/CHANGELOG.md +19 -0
- package/README.md +2 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/projection.d.ts +10 -1
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +20 -5
- package/dist/projection.js.map +1 -1
- package/dist/topics.d.ts +89 -1
- package/dist/topics.d.ts.map +1 -1
- package/dist/topics.js +181 -5
- package/dist/topics.js.map +1 -1
- package/package.json +3 -3
- package/src/index.ts +6 -0
- package/src/projection.ts +27 -7
- package/src/topics.ts +252 -4
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 {
|
|
29
|
-
import {
|
|
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([
|
|
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.
|