@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/CHANGELOG.md +30 -0
- package/README.md +13 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/loadQuery.d.ts +5 -1
- package/dist/loadQuery.d.ts.map +1 -1
- package/dist/loadQuery.js +130 -29
- package/dist/loadQuery.js.map +1 -1
- package/dist/projection.d.ts +3 -3
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +16 -6
- package/dist/projection.js.map +1 -1
- package/package.json +1 -1
- package/src/index.ts +1 -1
- package/src/loadQuery.ts +139 -32
- package/src/projection.ts +19 -9
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@estiva-app/interop",
|
|
3
|
-
"version": "0.
|
|
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
|
|
59
|
-
* everything in the pooled answer the filter matches,
|
|
60
|
-
* overcount — so a page is never taken as complete when it was
|
|
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
|
-
|
|
83
|
-
//
|
|
84
|
-
//
|
|
85
|
-
const
|
|
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
|
|
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
|
-
|
|
111
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
146
|
-
|
|
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
|
|
1876
|
-
* discovery** — the author's `kind:31989` recommendation
|
|
1877
|
-
*
|
|
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
|
|
2053
|
-
|
|
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
|
|
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.
|