@estiva-app/interop 0.87.0 → 0.88.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.87.0",
3
+ "version": "0.88.0",
4
4
  "description": "Render and act on another app's objects from its published NIP-89 manifest. The owner defines the projection; the consumer decides how it looks.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/projection.ts CHANGED
@@ -3613,7 +3613,9 @@ export async function resolveForeignObject(
3613
3613
  const childOwners = await childOwnersOf(plan, answered, childChanges, query, cache)
3614
3614
  const assembled = assembleObject(plan, answered, childChanges, childOwners, options.archivedChildren)
3615
3615
  if (assembled.object.unreachable) return assembled.object
3616
- if (options.archivedWith) await markArchivedParents([{ object: assembled.object, manifest: resolved.manifest }], query, cache)
3616
+ if (options.archivedWith) {
3617
+ await markArchivedParents([{ object: assembled.object, manifest: resolved.manifest }], query, cache, parentListKinds(options))
3618
+ }
3617
3619
  return withFiles(
3618
3620
  withBorrowed(
3619
3621
  withPeople(assembled, await (lookupPeople ?? peopleViaRelay(query))(peopleOf(assembled))),
@@ -3757,7 +3759,12 @@ export async function resolveForeignObjects(
3757
3759
  built: assembleObject(plan, events, childChanges, ownerLists[i], options.archivedChildren),
3758
3760
  }))
3759
3761
  if (options.archivedWith) {
3760
- await markArchivedParents(assembled.map(({ plan, built }) => ({ object: built.object, manifest: plan.resolved.manifest })), query, cache)
3762
+ await markArchivedParents(
3763
+ assembled.map(({ plan, built }) => ({ object: built.object, manifest: plan.resolved.manifest })),
3764
+ query,
3765
+ cache,
3766
+ parentListKinds(options),
3767
+ )
3761
3768
  }
3762
3769
  const wanted = [...new Set(assembled.flatMap(({ built }) => peopleOf(built)))]
3763
3770
  const reachable = assembled.some(({ built }) => !built.object.unreachable)
@@ -3915,16 +3922,12 @@ export async function resolveForeignRoots(
3915
3922
  const manifests = await manifestsOf(pointers.values(), query, cache)
3916
3923
 
3917
3924
  const filters: Record<string, unknown>[] = []
3918
- // One list read per author and kind: `limit` counts first records there, not the changes beside them.
3919
- const listedBy = new Map<string, { kind: number; pubkey: string; identifiers: string[] }>()
3925
+ const listedPointers: AddressPointer[] = []
3920
3926
  for (const [address, pointer] of pointers) {
3921
3927
  const resolved = manifests.get(manifestKeyOf(pointer))
3922
3928
  if (!resolved?.manifest.projections?.[String(pointer.kind)]) continue
3923
3929
  if (options.listRead && FILE_KINDS.includes(pointer.kind)) {
3924
- const key = `${pointer.kind}:${pointer.pubkey}`
3925
- const group = listedBy.get(key) ?? { kind: pointer.kind, pubkey: pointer.pubkey, identifiers: [] }
3926
- group.identifiers.push(pointer.identifier)
3927
- listedBy.set(key, group)
3930
+ listedPointers.push(pointer)
3928
3931
  continue
3929
3932
  }
3930
3933
  const root = { kinds: [pointer.kind], authors: [pointer.pubkey], '#d': [pointer.identifier], limit: 1 }
@@ -3934,13 +3937,7 @@ export async function resolveForeignRoots(
3934
3937
  )
3935
3938
  filters.push(root, { kinds: [...changeKinds], '#a': [address], limit: 500 })
3936
3939
  }
3937
- const listed: Record<string, unknown>[] = []
3938
- for (const { kind, pubkey, identifiers } of listedBy.values()) {
3939
- for (let start = 0; start < identifiers.length; start += RELAY_PAGE_CEILING) {
3940
- const chunk = identifiers.slice(start, start + RELAY_PAGE_CEILING)
3941
- listed.push({ kinds: [kind], authors: [pubkey], '#d': chunk, limit: chunk.length, fields: 'newest' })
3942
- }
3943
- }
3940
+ const listed = listReadFilters(listedPointers)
3944
3941
  if (filters.length === 0 && listed.length === 0) return []
3945
3942
  // A relay refuses a request mixing list reads with plain ones, so each goes on its own.
3946
3943
  const events = (await Promise.all([queryChunked(filters, query), queryChunked(listed, query)])).flat()
@@ -3951,11 +3948,46 @@ export async function resolveForeignRoots(
3951
3948
  const pointer = object.address ? addressPointerOf(object.address) : undefined
3952
3949
  return pointer ? manifests.get(manifestKeyOf(pointer))?.manifest : undefined
3953
3950
  }
3954
- await markArchivedParents(objects.map((object) => ({ object, manifest: manifestOf(object) })), query, cache)
3951
+ await markArchivedParents(
3952
+ objects.map((object) => ({ object, manifest: manifestOf(object) })),
3953
+ query,
3954
+ cache,
3955
+ options.listRead ? FILE_KINDS : [],
3956
+ )
3955
3957
  }
3956
3958
  return objects
3957
3959
  }
3958
3960
 
3961
+ /**
3962
+ * SPEC §6.13's list read of these files: each one's first record and each
3963
+ * field's current change, without the text and without any older change. One
3964
+ * filter per author and kind, since `limit` counts first records there, not the
3965
+ * changes beside them. A deleted file, and one this reader cannot read, is
3966
+ * absent from the answer; {@link listedIn} tells which were answered.
3967
+ */
3968
+ function listReadFilters(pointers: Iterable<AddressPointer>): Record<string, unknown>[] {
3969
+ const groups = new Map<string, { kind: number; pubkey: string; identifiers: Set<string> }>()
3970
+ for (const { kind, pubkey, identifier } of pointers) {
3971
+ const group = groups.get(`${kind}:${pubkey}`) ?? { kind, pubkey, identifiers: new Set<string>() }
3972
+ group.identifiers.add(identifier)
3973
+ groups.set(`${kind}:${pubkey}`, group)
3974
+ }
3975
+ const filters: Record<string, unknown>[] = []
3976
+ for (const { kind, pubkey, identifiers } of groups.values()) {
3977
+ const all = [...identifiers]
3978
+ for (let start = 0; start < all.length; start += RELAY_PAGE_CEILING) {
3979
+ const chunk = all.slice(start, start + RELAY_PAGE_CEILING)
3980
+ filters.push({ kinds: [kind], authors: [pubkey], '#d': chunk, limit: chunk.length, fields: 'newest' })
3981
+ }
3982
+ }
3983
+ return filters
3984
+ }
3985
+
3986
+ /** Whether `events` hold the first record `pointer` names: what a list read answered. */
3987
+ function listedIn(events: readonly SignedEvent[], pointer: AddressPointer): boolean {
3988
+ return events.some((e) => e.kind === pointer.kind && e.pubkey === pointer.pubkey && tagValue(e, 'd') === pointer.identifier)
3989
+ }
3990
+
3959
3991
  /** The manifest each pointer's author reads it through, one read per `kind:pubkey`. */
3960
3992
  async function manifestsOf(pointers: Iterable<AddressPointer>, query: QueryFn, cache?: ProjectionCache): Promise<Map<string, ResolvedManifest>> {
3961
3993
  const manifests = new Map<string, ResolvedManifest>()
@@ -4028,6 +4060,13 @@ export async function resolveParents(
4028
4060
  query: QueryFn,
4029
4061
  /** See {@link ProjectionCache}. Omitting it still reads each app's manifest once per call. */
4030
4062
  cache?: ProjectionCache,
4063
+ /**
4064
+ * `listRead`, where the relay offers the list read (NIP-11 `file_list`): a
4065
+ * file of the relay's file kinds is read as its first record and its fields'
4066
+ * current changes (SPEC §6.13), not every change ever made to it. One the
4067
+ * list read leaves out (deleted, or not this reader's) is read as before.
4068
+ */
4069
+ options: { listRead?: boolean } = {},
4031
4070
  ): Promise<Record<string, string | null>> {
4032
4071
  const results: Record<string, string | null> = {}
4033
4072
  const asked: { reference: string; pointer: AddressPointer }[] = []
@@ -4047,11 +4086,47 @@ export async function resolveParents(
4047
4086
  }),
4048
4087
  )
4049
4088
 
4050
- // The roots by author and kind, the one filter shape that names many; the
4051
- // moves by the app's change shape, only where the kind can be moved at all.
4089
+ const drawn = asked.filter(({ pointer }) => manifests.get(manifestKeyOf(pointer))?.projections?.[String(pointer.kind)])
4090
+ const byList = new Set(options.listRead ? drawn.filter(({ pointer }) => FILE_KINDS.includes(pointer.kind)) : [])
4091
+ const plainRead = (some: typeof asked) => {
4092
+ const filters = parentFilters(
4093
+ some.map(({ pointer }) => pointer),
4094
+ manifests,
4095
+ )
4096
+ return filters.length ? queryChunked(filters, query) : Promise.resolve<SignedEvent[]>([])
4097
+ }
4098
+ // A relay refuses a request mixing list reads with plain ones, so each goes on its own.
4099
+ const listFilters = listReadFilters([...byList].map(({ pointer }) => pointer))
4100
+ const [listed, plain] = await Promise.all([
4101
+ listFilters.length ? queryChunked(listFilters, query) : Promise.resolve<SignedEvent[]>([]),
4102
+ plainRead(drawn.filter((entry) => !byList.has(entry))),
4103
+ ])
4104
+ // Deleted, or not this reader's: read as before, so a deleted file still has its parent.
4105
+ const unanswered = [...byList].filter(({ pointer }) => !listedIn(listed, pointer))
4106
+ const events = [...listed, ...plain, ...(unanswered.length ? await plainRead(unanswered) : [])]
4107
+
4108
+ for (const { reference, pointer } of drawn) {
4109
+ const manifest = manifests.get(manifestKeyOf(pointer))!
4110
+ const root = events
4111
+ .filter((e) => e.kind === pointer.kind && e.pubkey === pointer.pubkey && tagValue(e, 'd') === pointer.identifier)
4112
+ .sort(byOrder)
4113
+ .at(-1)
4114
+ if (!root) continue
4115
+ const folded = foldOf(events, pointerToAddress(pointer), manifest, root)
4116
+ results[reference] = parentRefOf(manifest, pointer.kind, root, folded) ?? null
4117
+ }
4118
+ return results
4119
+ }
4120
+
4121
+ /**
4122
+ * {@link resolveParents}' read of every change: the roots by author and kind,
4123
+ * the one filter shape that names many, and the moves by the app's change
4124
+ * shape, only where the kind can be moved at all.
4125
+ */
4126
+ function parentFilters(pointers: readonly AddressPointer[], manifests: ReadonlyMap<string, Manifest>): Record<string, unknown>[] {
4052
4127
  const roots = new Map<string, { kind: number; pubkey: string; identifiers: Set<string> }>()
4053
4128
  const moves = new Map<string, { rule: RecordsRule; addresses: Set<string> }>()
4054
- for (const { pointer } of asked) {
4129
+ for (const pointer of pointers) {
4055
4130
  const manifest = manifests.get(manifestKeyOf(pointer))
4056
4131
  if (!manifest?.projections?.[String(pointer.kind)]) continue
4057
4132
  const group = `${pointer.kind}:${pointer.pubkey}`
@@ -4078,21 +4153,7 @@ export async function resolveParents(
4078
4153
  for (const { rule, addresses } of moves.values()) {
4079
4154
  for (const address of addresses) filters.push({ kinds: [rule.changeKind], [`#${rule.targetTag}`]: [address], limit: 500 })
4080
4155
  }
4081
- if (filters.length === 0) return results
4082
- const events = await queryChunked(filters, query)
4083
-
4084
- for (const { reference, pointer } of asked) {
4085
- const manifest = manifests.get(manifestKeyOf(pointer))
4086
- if (!manifest?.projections?.[String(pointer.kind)]) continue
4087
- const root = events
4088
- .filter((e) => e.kind === pointer.kind && e.pubkey === pointer.pubkey && tagValue(e, 'd') === pointer.identifier)
4089
- .sort(byOrder)
4090
- .at(-1)
4091
- if (!root) continue
4092
- const folded = foldOf(events, pointerToAddress(pointer), manifest, root)
4093
- results[reference] = parentRefOf(manifest, pointer.kind, root, folded) ?? null
4094
- }
4095
- return results
4156
+ return filters
4096
4157
  }
4097
4158
 
4098
4159
  /** What {@link resolveForeignObject} and {@link resolveForeignObjects} may read beyond the file itself. */
@@ -4151,6 +4212,22 @@ export interface ArchiveReadOptions {
4151
4212
  * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/opening-a-file-reads-its-current-text-not-its-history.md
4152
4213
  */
4153
4214
  openRead?: readonly number[]
4215
+ /**
4216
+ * With `archivedWith`: read each parent of the relay's file kinds by the list
4217
+ * read (SPEC §6.13), its first record and each field's current change, never
4218
+ * every change by `#a`. Pass it as soon as NIP-11 advertises
4219
+ * `file_list.newest`, switched or not. The kinds in `openRead` are read so
4220
+ * too. A parent the list read leaves out (deleted, not this reader's) is read
4221
+ * as before.
4222
+ *
4223
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-relay-advertises-the-list-read-apart-from-the-switch.md
4224
+ */
4225
+ listRead?: boolean
4226
+ }
4227
+
4228
+ /** The parent kinds an archived-with read reads by the list read: every file kind with `listRead`, else the opened ones. */
4229
+ function parentListKinds(options: Pick<ArchiveReadOptions, 'listRead' | 'openRead'>): readonly number[] {
4230
+ return options.listRead ? FILE_KINDS : (options.openRead ?? [])
4154
4231
  }
4155
4232
 
4156
4233
  /**
@@ -4199,11 +4276,17 @@ function withFiles(object: ForeignObject, files: ForeignObject[] | undefined): F
4199
4276
  * Each ancestor's rule is its own app's: the child's when that app also draws
4200
4277
  * the ancestor's kind — a project is Ship's as its issue is — otherwise the
4201
4278
  * ancestor's manifest, read through `cache`.
4279
+ *
4280
+ * An ancestor of a kind in `listKinds` is read by the relay's list read (SPEC
4281
+ * §6.13): its first record and each field's current change, the archive and
4282
+ * the move among them, never its older changes. One the list read leaves out
4283
+ * (deleted, or not this reader's) is read as before.
4202
4284
  */
4203
4285
  async function markArchivedParents(
4204
4286
  entries: { object: ForeignObject; manifest?: Manifest }[],
4205
4287
  query: QueryFn,
4206
4288
  cache?: ProjectionCache,
4289
+ listKinds: readonly number[] = [],
4207
4290
  ): Promise<void> {
4208
4291
  await walkArchivedAbove(
4209
4292
  entries
@@ -4218,9 +4301,32 @@ async function markArchivedParents(
4218
4301
  })),
4219
4302
  query,
4220
4303
  cache,
4304
+ listKinds,
4221
4305
  )
4222
4306
  }
4223
4307
 
4308
+ /** {@link walkArchivedAbove}'s read of every change: the ancestors' roots by author and kind, and their changes. */
4309
+ function ancestorFilters(addresses: readonly string[], rules: readonly RecordsRule[]): Record<string, unknown>[] {
4310
+ const roots = new Map<string, { kinds: number[]; authors: string[]; '#d': string[] }>()
4311
+ for (const address of addresses) {
4312
+ const pointer = addressPointerOf(address)!
4313
+ const group = `${pointer.kind}:${pointer.pubkey}`
4314
+ const filter = roots.get(group) ?? { kinds: [pointer.kind], authors: [pointer.pubkey], '#d': [] }
4315
+ filter['#d'].push(pointer.identifier)
4316
+ roots.set(group, filter)
4317
+ }
4318
+ return [
4319
+ ...[...roots.values()].flatMap((filter) => {
4320
+ const groups: Record<string, unknown>[] = []
4321
+ for (let start = 0; start < filter['#d'].length; start += PARENT_ROOT_GROUP) {
4322
+ groups.push({ ...filter, '#d': filter['#d'].slice(start, start + PARENT_ROOT_GROUP) })
4323
+ }
4324
+ return groups
4325
+ }),
4326
+ ...archiveFilters(addresses, rules),
4327
+ ]
4328
+ }
4329
+
4224
4330
  // An `naddr` parent names the same file as its plain address (FEE-2), and
4225
4331
  // only the plain one is what a change's target tag and `with` carry.
4226
4332
  function plainAddress(reference: string) {
@@ -4237,6 +4343,8 @@ async function walkArchivedAbove(
4237
4343
  starts: { at: string; manifest?: Manifest; seen: Set<string>; mark: (archive: Archive) => void }[],
4238
4344
  query: QueryFn,
4239
4345
  cache?: ProjectionCache,
4346
+ /** The kinds read by the list read, as {@link markArchivedParents}' `listKinds`. */
4347
+ listKinds: readonly number[] = [],
4240
4348
  ): Promise<void> {
4241
4349
  type Walk = (typeof starts)[number]
4242
4350
  let walking: Walk[] = starts
@@ -4273,25 +4381,23 @@ async function walkArchivedAbove(
4273
4381
  const ancestors = resolved.filter((a): a is typeof a & { manifest: Manifest } => !!a.manifest)
4274
4382
  const rules = ancestors.map(({ manifest }) => archiveRuleOf(manifest))
4275
4383
  const addresses = [...new Set(ancestors.map(({ address }) => address))]
4276
- const roots = new Map<string, { kinds: number[]; authors: string[]; '#d': string[] }>()
4277
- for (const address of addresses) {
4278
- const pointer = addressPointerOf(address)!
4279
- const group = `${pointer.kind}:${pointer.pubkey}`
4280
- const filter = roots.get(group) ?? { kinds: [pointer.kind], authors: [pointer.pubkey], '#d': [] }
4281
- filter['#d'].push(pointer.identifier)
4282
- roots.set(group, filter)
4283
- }
4284
- const filters = [
4285
- ...[...roots.values()].flatMap((filter) => {
4286
- const groups: Record<string, unknown>[] = []
4287
- for (let start = 0; start < filter['#d'].length; start += PARENT_ROOT_GROUP) {
4288
- groups.push({ ...filter, '#d': filter['#d'].slice(start, start + PARENT_ROOT_GROUP) })
4289
- }
4290
- return groups
4384
+ const byList = new Set(
4385
+ addresses.filter((address) => {
4386
+ const { kind } = addressPointerOf(address)!
4387
+ return listKinds.includes(kind) && FILE_KINDS.includes(kind)
4291
4388
  }),
4292
- ...archiveFilters(addresses, rules),
4293
- ]
4294
- const events = await queryChunked(filters, query)
4389
+ )
4390
+ const plainRead = (some: readonly string[]) =>
4391
+ some.length ? queryChunked(ancestorFilters(some, rules), query) : Promise.resolve<SignedEvent[]>([])
4392
+ // A relay refuses a request mixing list reads with plain ones, so each goes on its own.
4393
+ const listFilters = listReadFilters([...byList].map((address) => addressPointerOf(address)!))
4394
+ const [listed, plain] = await Promise.all([
4395
+ listFilters.length ? queryChunked(listFilters, query) : Promise.resolve<SignedEvent[]>([]),
4396
+ plainRead(addresses.filter((address) => !byList.has(address))),
4397
+ ])
4398
+ // Deleted, or not this reader's: read as before, so the walk ends where it always did.
4399
+ const unanswered = [...byList].filter((address) => !listedIn(listed, addressPointerOf(address)!))
4400
+ const events = [...listed, ...plain, ...(await plainRead(unanswered))]
4295
4401
  const read = new Map<string, { archive?: Archive; parent?: string; manifest?: Manifest }>()
4296
4402
  for (const [index, { key, address, pointer, manifest }] of ancestors.entries()) {
4297
4403
  const root = events
@@ -4498,9 +4604,7 @@ async function openedEvents(plans: readonly ObjectPlan[], query: QueryFn): Promi
4498
4604
  }
4499
4605
  }
4500
4606
  const answered = await queryChunked(filters, query)
4501
- const unanswered = [...opened.values()].filter(
4502
- ({ pointer }) => !answered.some((e) => e.kind === pointer.kind && e.pubkey === pointer.pubkey && tagValue(e, 'd') === pointer.identifier),
4503
- )
4607
+ const unanswered = [...opened.values()].filter(({ pointer }) => !listedIn(answered, pointer))
4504
4608
  const history = unanswered.length ? await queryChunked(unanswered.flatMap((plan) => plan.history), query) : []
4505
4609
  return [...answered, ...history]
4506
4610
  }
@@ -7477,6 +7581,7 @@ export async function resolveFolderContents(
7477
7581
  })),
7478
7582
  query,
7479
7583
  cache,
7584
+ options.listRead ? FILE_KINDS : [],
7480
7585
  )
7481
7586
  const files: ForeignObject[] = []
7482
7587
  for (const { file, archive } of listed) {