@estiva-app/interop 0.93.0 → 0.95.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
@@ -51,6 +51,8 @@ import {
51
51
  type ProjectionCache,
52
52
  type QueryFn,
53
53
  } from './projection.js'
54
+ import { fieldsSetBy } from './fields.js'
55
+ import { arrangementHeads, arrangementOf, fileOfListField, readsAs, sortArranged, type FileArrangement } from './topicArrangement.js'
54
56
 
55
57
  const KIND_CHANGE = 1851
56
58
  /** The topic (bare file) kind: the only lists this stage reads (Miky, 2026-10-30). */
@@ -252,7 +254,8 @@ export interface FileTopic {
252
254
  */
253
255
  export async function topicsOfFile(query: QueryFn, file: string): Promise<FileTopic[]> {
254
256
  const isTopic = (entry: ListEntry) => entry.file === file && entry.list.startsWith(`${KIND_TOPIC}:`)
255
- const events = await query([topicsOfFileFilter(file)])
257
+ // Paged: `#o` also returns every `order:` and `look:` change on the file (§6.14), one per move.
258
+ const events = await readAll(query, [topicsOfFileFilter(file)])
256
259
  const lists = [...new Set(listEntries(events).filter(isTopic).map((entry) => entry.list))]
257
260
  if (lists.length === 0) return []
258
261
  const roots = await rootsOf(query, lists)
@@ -265,8 +268,8 @@ export async function topicsOfFile(query: QueryFn, file: string): Promise<FileTo
265
268
  .map((entry) => ({ address: entry.list, root: roots.get(entry.list)!, entry }))
266
269
  }
267
270
 
268
- /** A file on a topic's list. */
269
- export interface ListedFile {
271
+ /** A file on a topic's list, with its place and look there (§6.14). */
272
+ export interface ListedFile extends FileArrangement {
270
273
  /** The listed file's id. */
271
274
  file: string
272
275
  /** Its address when exactly one file the reader can read holds the id, else `null`: not drawn, not counted. */
@@ -276,11 +279,25 @@ export interface ListedFile {
276
279
  entry: ListEntry
277
280
  }
278
281
 
282
+ /** How a topic's list is read. */
283
+ export interface ListReadOptions {
284
+ /** The file kinds a listed id resolves over (§6.14 "A listed id resolves"). */
285
+ fileKinds?: readonly number[]
286
+ /**
287
+ * The relay offers the list read (NIP-11 `file_list.newest`): read each
288
+ * topic's fields as their current changes, at most three per file however
289
+ * often its files were moved, not every change ever made (§6.13). Without
290
+ * it, every change by `#O`, which grows with each move.
291
+ */
292
+ listRead?: boolean
293
+ }
294
+
279
295
  /**
280
296
  * A topic's list, by the topic's address: its entries whose newest value
281
297
  * lists the file, filed in the Folder the topic's root names (§6.2; read here,
282
- * never taken from the caller), in no promised order (sort as the design
283
- * says; `entry.event` carries the time), each id resolved over `fileKinds` by
298
+ * never taken from the caller), in the topic's order (§6.14: placed files by
299
+ * key, then the rest oldest listed first), each with its look and the `prev`
300
+ * its next arrangement follows, each id resolved over `fileKinds` by
284
301
  * `#d`. A topic the reader cannot read, or whose root names no Folder, lists
285
302
  * nothing. An id held by none the reader can read, or by two, resolves to
286
303
  * `null`: a consumer draws and counts only the resolved ones (§3.2, the count
@@ -289,7 +306,7 @@ export interface ListedFile {
289
306
  export async function topicList(
290
307
  query: QueryFn,
291
308
  topic: string,
292
- options: { fileKinds?: readonly number[] } = {},
309
+ options: ListReadOptions = {},
293
310
  ): Promise<ListedFile[]> {
294
311
  return (await topicLists(query, [topic], options)).get(topic) ?? []
295
312
  }
@@ -306,7 +323,7 @@ export async function topicList(
306
323
  export async function topicLists(
307
324
  query: QueryFn,
308
325
  topics: readonly string[],
309
- options: { fileKinds?: readonly number[] } = {},
326
+ options: ListReadOptions = {},
310
327
  ): Promise<Map<string, ListedFile[]>> {
311
328
  const asked = [...new Set(topics)]
312
329
  if (asked.length === 0) return new Map()
@@ -318,27 +335,81 @@ async function listsOf(
318
335
  query: QueryFn,
319
336
  asked: readonly string[],
320
337
  rootsRead: Promise<ReadonlyMap<string, SignedEvent>>,
321
- options: { fileKinds?: readonly number[] },
338
+ options: ListReadOptions,
322
339
  ): Promise<Map<string, ListedFile[]>> {
323
340
  const out = new Map<string, ListedFile[]>(asked.map((topic) => [topic, []]))
324
- // 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.
325
- const [roots, events] = await Promise.all([rootsRead, query(asked.map(topicListFilter))])
341
+ // Paged without the list read: every move adds a change to a topic's `#O`, and an unpaged read would lose its oldest entries.
342
+ const [roots, events] = await Promise.all([rootsRead, options.listRead ? newestChanges(query, asked) : readAll(query, asked.map(topicListFilter))])
326
343
  const folderOfList = (list: string) => {
327
344
  const root = out.has(list) ? roots.get(list) : undefined
328
345
  return root ? folderOf(root) : null
329
346
  }
347
+ if (options.listRead) events.push(...(await skippedAgain(query, events, folderOfList)))
330
348
  const entries = listEntries(events, folderOfList)
331
349
  .filter((entry) => entry.listed)
332
350
  .sort((a, b) => byOrder(a.event, b.event))
333
351
  if (entries.length === 0) return out
352
+ const heads = arrangementHeads(events, folderOfList)
334
353
  const resolved = await resolveIds(query, [...new Set(entries.map((entry) => entry.file))], options.fileKinds)
335
354
  for (const entry of entries) {
336
355
  const held = resolved.get(entry.file)
337
- out.get(entry.list)!.push({ file: entry.file, address: held?.address ?? null, folder: held?.folder ?? null, entry })
356
+ const arranged = arrangementOf(heads.get(entry.list), entry.file, entry.event, roots.get(entry.list)!)
357
+ out.get(entry.list)!.push({ file: entry.file, address: held?.address ?? null, folder: held?.folder ?? null, entry, ...arranged })
338
358
  }
359
+ for (const [list, files] of out) out.set(list, sortArranged(files))
339
360
  return out
340
361
  }
341
362
 
363
+ /**
364
+ * Each topic's fields as their current changes, by the list read (§6.13):
365
+ * one filter per topic, all in one request, so a relay's cap on an answer
366
+ * cuts no more than it would for that topic alone, as the `#O` read does.
367
+ */
368
+ async function newestChanges(query: QueryFn, topics: readonly string[]): Promise<SignedEvent[]> {
369
+ const filters = topics.flatMap((topic) => {
370
+ const [, kind, , d] = ADDRESS.exec(topic) ?? []
371
+ return d ? [{ fields: 'newest', kinds: [Number(kind)], '#d': [d] }] : []
372
+ })
373
+ return filters.length ? query(filters) : []
374
+ }
375
+
376
+ /** The most files per topic the list read asks about again. */
377
+ const SKIPPED_READ_CAP = 100
378
+
379
+ /**
380
+ * The list read answers each field's newest change, a malformed one too (a
381
+ * wrong `o` the relay takes), so the good change before it is not in the
382
+ * answer. For each file where that happened, read its changes on that topic
383
+ * again (`#O` and `#o`), so it folds as a whole `#O` read would.
384
+ */
385
+ async function skippedAgain(
386
+ query: QueryFn,
387
+ events: readonly SignedEvent[],
388
+ folderOfList: (list: string) => string | null | undefined,
389
+ ): Promise<SignedEvent[]> {
390
+ const skipped = new Map<string, Set<string>>()
391
+ for (const event of events) {
392
+ if (event.kind !== KIND_CHANGE) continue
393
+ const list = tagOf(event, 'a')
394
+ // Only a list asked for and readable: a change on another author's same-id topic folds nowhere anyway.
395
+ if (!list || !folderOfList(list)) continue
396
+ for (const { field } of fieldsSetBy(event)) {
397
+ const file = fileOfListField(field)
398
+ // A list entry is read only in the one-field form (§6.14): one set in a `set` is skipped too.
399
+ const entryInSet = field.startsWith('lists:') && tagOf(event, 'field') === undefined
400
+ if (!file || (!entryInSet && readsAs(event, field, list, folderOfList(list)))) continue
401
+ const holder = ADDRESS.exec(list)
402
+ if (!holder) continue
403
+ const files = skipped.get(holder[3]) ?? new Set()
404
+ // Bounded: a change setting hundreds of junk fields asks again about the first few only.
405
+ if (files.size < SKIPPED_READ_CAP) files.add(file)
406
+ skipped.set(holder[3], files)
407
+ }
408
+ }
409
+ if (skipped.size === 0) return []
410
+ return readAll(query, [...skipped].map(([topic, files]) => ({ kinds: [KIND_CHANGE], '#O': [topic], '#o': [...files] })))
411
+ }
412
+
342
413
  /** A topic as {@link readTopics} reads it. */
343
414
  export interface ReadTopic {
344
415
  address: string
@@ -501,7 +572,7 @@ export async function readAll(query: QueryFn, filters: readonly Record<string, u
501
572
  export async function readTopics(
502
573
  query: QueryFn,
503
574
  me: string,
504
- options: { cache?: ProjectionCache; fileKinds?: readonly number[]; nowSeconds?: number; parentsListRead?: boolean } = {},
575
+ options: ListReadOptions & { cache?: ProjectionCache; nowSeconds?: number; parentsListRead?: boolean } = {},
505
576
  ): Promise<TopicsRead> {
506
577
  const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000)
507
578
  const rootEvents = await readAll(query, [{ kinds: [KIND_TOPIC] }])
@@ -517,7 +588,8 @@ export async function readTopics(
517
588
  if (addresses.length === 0) return { me, topics: [], membership: foldMemberships(me, [], nowSeconds), mentionedIn: new Set(), inConversations: new Map() }
518
589
  const [objects, lists, part, states] = await Promise.all([
519
590
  resolveForeignRoots(addresses, query, options.cache, { archivedWith: true, parentsListRead: options.parentsListRead }),
520
- listsOf(query, addresses, Promise.resolve(roots), options),
591
+ // The relay that offers the list read for the parents offers it for the topics' own lists.
592
+ listsOf(query, addresses, Promise.resolve(roots), { ...options, listRead: options.listRead ?? options.parentsListRead }),
521
593
  // Held once each, though one comment can answer two of the filters: the folds count events.
522
594
  readAll(query, personInFilesFilters(me, addresses)),
523
595
  // The team lists naming a topic, for which of them are spaces.