@estiva-app/interop 0.69.1 → 0.70.1

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.69.1",
3
+ "version": "0.70.1",
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/index.ts CHANGED
@@ -110,7 +110,7 @@ export {
110
110
  * breadcrumbs and move targets, with cycles cut. No requests.
111
111
  */
112
112
  export { nestingOf, type Nestable, type Nesting } from './nesting.js'
113
- export { createLoadQuery } from './loadQuery.js'
113
+ export { createLoadQuery, type LoadQueryOptions } from './loadQuery.js'
114
114
 
115
115
  /**
116
116
  * The files `[` offers (PEE-21): resolved objects as rows, and typed text as
package/src/loadQuery.ts CHANGED
@@ -15,9 +15,21 @@
15
15
  * the relay's answer did not fill the page. A later filter in the same load
16
16
  * naming such a value gets the events already read, and asks only for the
17
17
  * rest.
18
+ * - **A read of a whole kind answers every later read of that kind** (APP-6).
19
+ * The agent's workspace reads every change with `{ kinds: [1851] }`, and
20
+ * `listFolders` beside it read the same changes again by `#a`: 37.6 MB, then
21
+ * 23.6 MB more, on production 27 Oct. A filter naming only kinds is complete
22
+ * on the same terms as one naming values, and a later filter of one of its
23
+ * kinds, by any one tag, is answered from it.
18
24
  * - **A read in flight is joined, not repeated.** A value still being read is
19
25
  * waited for, and an identical request still in flight shares its answer.
20
26
  *
27
+ * **A query that pages every filter to its end** (`Relay.queryAll`, the
28
+ * agent's) says so with `{ paged: true }`. Its answer is whole whatever its
29
+ * size and whatever `limit` the filter carried, so every such read counts;
30
+ * counting the page would never count a read past one page, which every
31
+ * workspace read is.
32
+ *
21
33
  * **One load, never longer.** What it holds is the relay's answer at the moment
22
34
  * of the load: a refresh, a live update, or the next screen must read afresh,
23
35
  * so the caller makes one per load and drops it after. Caching changes across
@@ -53,13 +65,66 @@ function byTagOf(filter: Filter): ByTag | null {
53
65
  return { kind: kinds[0], tag: tagKeys[0].slice(1), values, limit }
54
66
  }
55
67
 
68
+ /** `{ kinds: [...] }`, with or without a `limit`, and nothing else: every event of those kinds. */
69
+ interface WholeKinds {
70
+ kinds: number[]
71
+ limit: number
72
+ }
73
+
74
+ function wholeKindsOf(filter: Filter, paged: boolean): WholeKinds | null {
75
+ const { kinds, limit, ...rest } = filter
76
+ if (Object.keys(rest).length !== 0 || !Array.isArray(kinds) || kinds.length === 0) return null
77
+ if (!kinds.every((kind) => typeof kind === 'number')) return null
78
+ // A relay may give a filter with no limit a smaller page than its ceiling, so
79
+ // through one page only a stated limit says when the answer was cut short.
80
+ if (typeof limit !== 'number' && !(paged && limit === undefined)) return null
81
+ return { kinds, limit: limit ?? RELAY_PAGE_CEILING }
82
+ }
83
+
84
+ /**
85
+ * The tags a whole read answers a later read by: the ones the relay matches as
86
+ * NIP-01 does, on every kind. Never `h`, which is a Folder's scope on the relay
87
+ * (the event's first `h`, its membership checked there), so a tag match would
88
+ * take in a change one member planted with a second `h` naming a Folder they
89
+ * cannot write to. Never `d` either: a Folder's own events (39000–39003) are
90
+ * reached by naming the Folder, and a read naming no Folder misses some.
91
+ */
92
+ const WHOLE_READ_TAGS = new Set(['a', 'e'])
93
+
94
+ /** The events of a whole read naming each value of one tag, indexed once per read and tag. */
95
+ const indexes = new WeakMap<SignedEvent[], Map<string, Map<string, SignedEvent[]>>>()
96
+ function naming(events: SignedEvent[], tag: string, value: string): SignedEvent[] {
97
+ let byTag = indexes.get(events)
98
+ if (!byTag) indexes.set(events, (byTag = new Map()))
99
+ let byValue = byTag.get(tag)
100
+ if (!byValue) {
101
+ byTag.set(tag, (byValue = new Map()))
102
+ for (const event of events) {
103
+ for (const [name, held] of event.tags) {
104
+ if (name !== tag) continue
105
+ const list = byValue.get(held) ?? []
106
+ if (!list.includes(event)) list.push(event)
107
+ byValue.set(held, list)
108
+ }
109
+ }
110
+ }
111
+ return byValue.get(value) ?? []
112
+ }
113
+
114
+ /** Every event of the read's kinds, if this answer holds them all: see {@link completeByValue}. */
115
+ function completeWhole(shape: WholeKinds, answer: SignedEvent[], paged: boolean): SignedEvent[] | null {
116
+ const held = answer.filter((event) => shape.kinds.includes(event.kind))
117
+ return paged || held.length < Math.min(shape.limit, RELAY_PAGE_CEILING) ? held : null
118
+ }
119
+
56
120
  /**
57
121
  * The events naming each of the filter's values, if this answer holds them
58
- * all: fewer came back for the filter than its page. The count is of
59
- * everything in the pooled answer the filter matches, which can only
60
- * overcount — so a page is never taken as complete when it was full.
122
+ * all: fewer came back for the filter than its page, or the query pages to the
123
+ * end. The count is of everything in the pooled answer the filter matches,
124
+ * which can only overcount — so a page is never taken as complete when it was
125
+ * full.
61
126
  */
62
- function completeByValue(shape: ByTag, answer: SignedEvent[]): Map<string, SignedEvent[]> | null {
127
+ function completeByValue(shape: ByTag, answer: SignedEvent[], paged: boolean): Map<string, SignedEvent[]> | null {
63
128
  const byValue = new Map<string, SignedEvent[]>(shape.values.map((value) => [value, []]))
64
129
  let matched = 0
65
130
  for (const event of answer) {
@@ -74,17 +139,43 @@ function completeByValue(shape: ByTag, answer: SignedEvent[]): Map<string, Signe
74
139
  }
75
140
  if (hit) matched++
76
141
  }
77
- return matched >= Math.min(shape.limit, RELAY_PAGE_CEILING) ? null : byValue
142
+ return !paged && matched >= Math.min(shape.limit, RELAY_PAGE_CEILING) ? null : byValue
143
+ }
144
+
145
+ export interface LoadQueryOptions {
146
+ /** The query answers every filter in full, paging past the relay's page (`Relay.queryAll`): see the module's note. */
147
+ paged?: boolean
148
+ }
149
+
150
+ /** A read held for the load: what it found, `null` when its page was full, or the read still in flight — and the limit it was read with. */
151
+ interface Held {
152
+ limit: number
153
+ events: Promise<SignedEvent[] | null>
78
154
  }
79
155
 
80
156
  /** A query for one load: see the module's note. Make one per load and drop it after. */
81
- export function createLoadQuery(query: QueryFn): QueryFn {
82
- // Per `<kind>:<tag>:<value>`: the events naming it, `null` while unknown
83
- // (the page was full), or the read still in flight — and the limit it was
84
- // read with, since only an ask with as large a limit would have got them all.
85
- const known = new Map<string, { limit: number; events: Promise<SignedEvent[] | null> }>()
157
+ export function createLoadQuery(query: QueryFn, options: LoadQueryOptions = {}): QueryFn {
158
+ const paged = options.paged === true
159
+ // Only an ask with as large a limit as a held read would have got all it holds,
160
+ // so a smaller page goes to the relay. A paged read holds everything whatever its limit.
161
+ const answers = (held: Held | undefined, limit: number): held is Held => !!held && (paged || held.limit <= limit)
162
+ // Per `<kind>:<tag>:<value>`: the events naming it.
163
+ const known = new Map<string, Held>()
164
+ // Per kind: every event of it, read by a filter naming only kinds.
165
+ const wholes = new Map<number, Held>()
86
166
  const flights = new Map<string, Promise<SignedEvent[]>>()
87
167
 
168
+ const remember = <K>(memo: Map<K, Held>, key: K, entry: Held) => {
169
+ // A larger read of the same, in flight or done, is kept.
170
+ if ((memo.get(key)?.limit ?? -1) > entry.limit) return
171
+ memo.set(key, entry)
172
+ // Forget a refused read, and a page that came back full, so the next ask goes to the relay.
173
+ const forget = () => {
174
+ if (memo.get(key) === entry) memo.delete(key)
175
+ }
176
+ entry.events.then((events) => events ?? forget(), forget)
177
+ }
178
+
88
179
  const ask = (filters: Filter[]): Promise<SignedEvent[]> => {
89
180
  const key = JSON.stringify(filters)
90
181
  const held = flights.get(key)
@@ -97,18 +188,36 @@ export function createLoadQuery(query: QueryFn): QueryFn {
97
188
  return async (filters) => {
98
189
  const send: Filter[] = []
99
190
  const asked: ByTag[] = []
100
- const joined: { shape: ByTag; value: string; entry: Promise<SignedEvent[] | null> }[] = []
191
+ const askedWhole: WholeKinds[] = []
192
+ // Answered from a held read; `again` is what to ask if that read's page came back full.
193
+ const joined: { again: Filter; entry: Promise<SignedEvent[] | null> }[] = []
194
+ const joinedByTag: { shape: ByTag; value: string; entry: Promise<SignedEvent[] | null> }[] = []
101
195
  for (const filter of filters) {
196
+ const whole = wholeKindsOf(filter, paged)
197
+ if (whole) {
198
+ const held = whole.kinds.map((kind) => wholes.get(kind))
199
+ if (held.every((entry) => answers(entry, whole.limit))) {
200
+ const parts = Promise.all(held.map((entry) => entry!.events))
201
+ joined.push({ again: filter, entry: parts.then((all) => (all.includes(null) ? null : all.flat() as SignedEvent[])) })
202
+ } else {
203
+ send.push(filter)
204
+ askedWhole.push(whole)
205
+ }
206
+ continue
207
+ }
102
208
  const shape = byTagOf(filter)
103
209
  if (!shape) {
104
210
  send.push(filter)
105
211
  continue
106
212
  }
107
213
  const fresh: string[] = []
214
+ const read = WHOLE_READ_TAGS.has(shape.tag) ? wholes.get(shape.kind) : undefined
108
215
  for (const value of new Set(shape.values)) {
109
216
  const entry = known.get(`${shape.kind}:${shape.tag}:${value}`)
110
- // A smaller page than the read had might not have held them all: the relay is asked, as it was.
111
- if (entry && entry.limit <= shape.limit) joined.push({ shape, value, entry: entry.events })
217
+ if (answers(read, shape.limit)) {
218
+ const events = read.events.then((all) => all && naming(all, shape.tag, value))
219
+ joinedByTag.push({ shape, value, entry: events })
220
+ } else if (answers(entry, shape.limit)) joinedByTag.push({ shape, value, entry: entry.events })
112
221
  else fresh.push(value)
113
222
  }
114
223
  if (fresh.length === 0) continue
@@ -117,38 +226,36 @@ export function createLoadQuery(query: QueryFn): QueryFn {
117
226
  }
118
227
 
119
228
  const answer = send.length ? ask(send) : Promise.resolve([])
229
+ for (const shape of askedWhole) {
230
+ const split = answer.then((events) => completeWhole(shape, events, paged))
231
+ for (const kind of shape.kinds) {
232
+ remember(wholes, kind, { limit: shape.limit, events: split.then((events) => events && events.filter((event) => event.kind === kind)) })
233
+ }
234
+ }
120
235
  for (const shape of asked) {
121
- const split = answer.then((events) => completeByValue(shape, events))
236
+ const split = answer.then((events) => completeByValue(shape, events, paged))
122
237
  for (const value of shape.values) {
123
- const key = `${shape.kind}:${shape.tag}:${value}`
124
- // A larger read of the same value, in flight or done, is kept.
125
- if ((known.get(key)?.limit ?? -1) > shape.limit) continue
126
- const entry = { limit: shape.limit, events: split.then((byValue) => byValue?.get(value) ?? null) }
127
- known.set(key, entry)
128
- // Forget a refused read, and a page that came back full, so the next ask goes to the relay.
129
- const forget = () => {
130
- if (known.get(key) === entry) known.delete(key)
131
- }
132
- entry.events.then((events) => events ?? forget(), forget)
238
+ remember(known, `${shape.kind}:${shape.tag}:${value}`, { limit: shape.limit, events: split.then((byValue) => byValue?.get(value) ?? null) })
133
239
  }
134
240
  }
135
241
 
136
242
  const out = [...(await answer)]
243
+ const again: Filter[] = []
244
+ for (const { again: filter, entry } of joined) {
245
+ const events = await entry
246
+ if (events) out.push(...events)
247
+ else again.push(filter)
248
+ }
137
249
  // Per filter of the caller's, so a re-ask keeps the grouping it chose.
138
250
  const unknown = new Map<ByTag, string[]>()
139
- for (const { shape, value, entry } of joined) {
251
+ for (const { shape, value, entry } of joinedByTag) {
140
252
  const events = await entry
141
253
  if (events) out.push(...events)
142
254
  // That read's page was full: ask for this value here, as the caller would have.
143
255
  else unknown.set(shape, [...(unknown.get(shape) ?? []), value])
144
256
  }
145
- if (unknown.size) {
146
- out.push(
147
- ...(await ask(
148
- [...unknown].map(([shape, values]) => ({ kinds: [shape.kind], [`#${shape.tag}`]: values, limit: shape.limit })),
149
- )),
150
- )
151
- }
257
+ for (const [shape, values] of unknown) again.push({ kinds: [shape.kind], [`#${shape.tag}`]: values, limit: shape.limit })
258
+ if (again.length) out.push(...(await ask(again)))
152
259
 
153
260
  // One copy of each event, as one request to the relay answers.
154
261
  const seen = new Set<string>()
package/src/projection.ts CHANGED
@@ -1872,9 +1872,9 @@ type CachedManifests = ResolvedManifest | null | readonly ResolvedManifest[]
1872
1872
  /**
1873
1873
  * A memo for the half of a resolve that does not change between refreshes.
1874
1874
  *
1875
- * Resolving one reference costs four round trips, and **two of them are NIP-89
1876
- * discovery** — the author's `kind:31989` recommendation, then the `kind:31990`
1877
- * manifest itself. A consumer that re-resolves on a timer pays for both every
1875
+ * Resolving one reference costs four requests, and **two of them are NIP-89
1876
+ * discovery** — the author's `kind:31989` recommendation and the `kind:31990`
1877
+ * manifests claiming the kind, asked together (APP-3). A consumer that re-resolves on a timer pays for both every
1878
1878
  * time, and they answer the same thing until an app republishes its manifest.
1879
1879
  * Measured on Ship, where a reference widget re-resolves on the poll: 4
1880
1880
  * requests per reference per tick, identical on the second resolve, against a
@@ -2036,6 +2036,15 @@ async function resolveManifestUncached(
2036
2036
  const addressOf = (event: SignedEvent) =>
2037
2037
  `${event.kind}:${event.pubkey}:${tagValue(event, 'd') ?? ''}`
2038
2038
 
2039
+ // The claim is asked beside the recommendation, not after it (APP-3): asked
2040
+ // in turn they were two round trips before every opened object's own read,
2041
+ // ~0.5 s of a Leaf page opened by its link. A recommended manifest usually
2042
+ // claims the kind too, so the claim answers the recommendation's second read
2043
+ // as well. The claim's failure counts only when it is the answer.
2044
+ const claim = query([
2045
+ { kinds: [KIND_HANDLER_INFORMATION], '#k': [String(pointer.kind)], limit: 20 },
2046
+ ])
2047
+ void claim.catch(() => {})
2039
2048
  const recommended = await query(
2040
2049
  [
2041
2050
  {
@@ -2049,9 +2058,12 @@ async function resolveManifestUncached(
2049
2058
  const manifestAddr = recommended[0]?.tags.find((t) => t[0] === 'a')?.[1]
2050
2059
  if (manifestAddr) {
2051
2060
  const [kind, pubkey, ...rest] = manifestAddr.split(':')
2052
- const found = await query([
2053
- { kinds: [Number(kind)], authors: [pubkey], '#d': [rest.join(':')], limit: 1 },
2054
- ])
2061
+ const claimedCopy = (await claim.catch(() => []))
2062
+ .filter((event) => addressOf(event) === `${Number(kind)}:${pubkey}:${rest.join(':')}`)
2063
+ .sort((a, b) => b.created_at - a.created_at)
2064
+ const found = claimedCopy.length
2065
+ ? claimedCopy
2066
+ : await query([{ kinds: [Number(kind)], authors: [pubkey], '#d': [rest.join(':')], limit: 1 }])
2055
2067
  const manifest = found[0] ? parse(found[0]) : null
2056
2068
  if (manifest) {
2057
2069
  return {
@@ -2063,9 +2075,7 @@ async function resolveManifestUncached(
2063
2075
  }
2064
2076
  }
2065
2077
 
2066
- const claimed = await query([
2067
- { kinds: [KIND_HANDLER_INFORMATION], '#k': [String(pointer.kind)], limit: 20 },
2068
- ])
2078
+ const claimed = await claim
2069
2079
  // Newest wins among unrecommended candidates. Arbitrary, and honest about it:
2070
2080
  // there is no principled ranking without a recommendation, which is exactly
2071
2081
  // why the recommendation exists.