@estiva-app/interop 0.65.1 → 0.67.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 +30 -0
- package/README.md +20 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/loadQuery.d.ts +4 -0
- package/dist/loadQuery.d.ts.map +1 -0
- package/dist/loadQuery.js +149 -0
- package/dist/loadQuery.js.map +1 -0
- package/dist/projection.d.ts +18 -0
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +65 -38
- package/dist/projection.js.map +1 -1
- package/package.json +1 -1
- package/src/index.ts +3 -0
- package/src/loadQuery.ts +157 -0
- package/src/projection.ts +65 -32
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@estiva-app/interop",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.67.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/index.ts
CHANGED
|
@@ -36,6 +36,7 @@ export {
|
|
|
36
36
|
resolveFolderProject,
|
|
37
37
|
resolveFolderContents,
|
|
38
38
|
listFolders,
|
|
39
|
+
listFolderRecords,
|
|
39
40
|
topLevelFolders,
|
|
40
41
|
ARCHIVED_FIELD,
|
|
41
42
|
SUMMARY_FIELD,
|
|
@@ -93,6 +94,7 @@ export {
|
|
|
93
94
|
type FolderProject,
|
|
94
95
|
type FolderContents,
|
|
95
96
|
type FolderSummary,
|
|
97
|
+
type FolderRecord,
|
|
96
98
|
type ResolvedSlot,
|
|
97
99
|
type ResolvedAction,
|
|
98
100
|
type ActionFormField,
|
|
@@ -108,6 +110,7 @@ export {
|
|
|
108
110
|
* breadcrumbs and move targets, with cycles cut. No requests.
|
|
109
111
|
*/
|
|
110
112
|
export { nestingOf, type Nestable, type Nesting } from './nesting.js'
|
|
113
|
+
export { createLoadQuery } from './loadQuery.js'
|
|
111
114
|
|
|
112
115
|
/**
|
|
113
116
|
* The files `[` offers (PEE-21): resolved objects as rows, and typed text as
|
package/src/loadQuery.ts
ADDED
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One load's reads, each asked of the relay once (APP-2).
|
|
3
|
+
*
|
|
4
|
+
* A screen that lists the workspace reads it in two steps: `listFolders`, which
|
|
5
|
+
* reads every change naming every listed file to learn what is archived, and
|
|
6
|
+
* then `resolveFolderContents` once per Folder, which reads the same changes
|
|
7
|
+
* again to build each file. Measured on production 26 Oct: Leaf's Weekly Plans
|
|
8
|
+
* load read 79 MB, 78 MB of it changes, while 36.9 MB of changes existed.
|
|
9
|
+
*
|
|
10
|
+
* {@link createLoadQuery} wraps the caller's query for the length of one load:
|
|
11
|
+
*
|
|
12
|
+
* - **A read that came back complete is not asked again.** A filter asking for
|
|
13
|
+
* every event of one kind naming any of a list of values in one tag — the
|
|
14
|
+
* shape every change read uses — is complete for each of those values when
|
|
15
|
+
* the relay's answer did not fill the page. A later filter in the same load
|
|
16
|
+
* naming such a value gets the events already read, and asks only for the
|
|
17
|
+
* rest.
|
|
18
|
+
* - **A read in flight is joined, not repeated.** A value still being read is
|
|
19
|
+
* waited for, and an identical request still in flight shares its answer.
|
|
20
|
+
*
|
|
21
|
+
* **One load, never longer.** What it holds is the relay's answer at the moment
|
|
22
|
+
* of the load: a refresh, a live update, or the next screen must read afresh,
|
|
23
|
+
* so the caller makes one per load and drops it after. Caching changes across
|
|
24
|
+
* loads is how a live list becomes a screenshot (`ProjectionCache` keeps only
|
|
25
|
+
* manifests for that reason).
|
|
26
|
+
*
|
|
27
|
+
* A refused read fails every call waiting on it, and is forgotten, so a retry
|
|
28
|
+
* asks again: a listing missing what it should have read must still fail
|
|
29
|
+
* loudly (`placeRecordChannels`, 2026-09-22).
|
|
30
|
+
*/
|
|
31
|
+
import { RELAY_PAGE_CEILING, type SignedEvent } from '@estiva-app/protocol'
|
|
32
|
+
import type { QueryFn } from './projection.js'
|
|
33
|
+
|
|
34
|
+
type Filter = Record<string, unknown>
|
|
35
|
+
|
|
36
|
+
/** `{ kinds: [kind], '#<tag>': values, limit }` and nothing else. */
|
|
37
|
+
interface ByTag {
|
|
38
|
+
kind: number
|
|
39
|
+
tag: string
|
|
40
|
+
values: string[]
|
|
41
|
+
limit: number
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
function byTagOf(filter: Filter): ByTag | null {
|
|
45
|
+
const keys = Object.keys(filter)
|
|
46
|
+
const tagKeys = keys.filter((key) => key.startsWith('#'))
|
|
47
|
+
if (keys.length !== 3 || tagKeys.length !== 1 || tagKeys[0].length !== 2) return null
|
|
48
|
+
const { kinds, limit } = filter
|
|
49
|
+
const values = filter[tagKeys[0]]
|
|
50
|
+
if (!Array.isArray(kinds) || kinds.length !== 1 || typeof kinds[0] !== 'number') return null
|
|
51
|
+
if (typeof limit !== 'number' || !Array.isArray(values) || values.length === 0) return null
|
|
52
|
+
if (!values.every((value) => typeof value === 'string')) return null
|
|
53
|
+
return { kind: kinds[0], tag: tagKeys[0].slice(1), values, limit }
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* 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.
|
|
61
|
+
*/
|
|
62
|
+
function completeByValue(shape: ByTag, answer: SignedEvent[]): Map<string, SignedEvent[]> | null {
|
|
63
|
+
const byValue = new Map<string, SignedEvent[]>(shape.values.map((value) => [value, []]))
|
|
64
|
+
let matched = 0
|
|
65
|
+
for (const event of answer) {
|
|
66
|
+
if (event.kind !== shape.kind) continue
|
|
67
|
+
let hit = false
|
|
68
|
+
for (const [name, value] of event.tags) {
|
|
69
|
+
const held = name === shape.tag ? byValue.get(value) : undefined
|
|
70
|
+
if (held && !held.includes(event)) {
|
|
71
|
+
held.push(event)
|
|
72
|
+
hit = true
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
if (hit) matched++
|
|
76
|
+
}
|
|
77
|
+
return matched >= Math.min(shape.limit, RELAY_PAGE_CEILING) ? null : byValue
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** 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> }>()
|
|
86
|
+
const flights = new Map<string, Promise<SignedEvent[]>>()
|
|
87
|
+
|
|
88
|
+
const ask = (filters: Filter[]): Promise<SignedEvent[]> => {
|
|
89
|
+
const key = JSON.stringify(filters)
|
|
90
|
+
const held = flights.get(key)
|
|
91
|
+
if (held) return held
|
|
92
|
+
const flight = query(filters).finally(() => flights.delete(key))
|
|
93
|
+
flights.set(key, flight)
|
|
94
|
+
return flight
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
return async (filters) => {
|
|
98
|
+
const send: Filter[] = []
|
|
99
|
+
const asked: ByTag[] = []
|
|
100
|
+
const joined: { shape: ByTag; value: string; entry: Promise<SignedEvent[] | null> }[] = []
|
|
101
|
+
for (const filter of filters) {
|
|
102
|
+
const shape = byTagOf(filter)
|
|
103
|
+
if (!shape) {
|
|
104
|
+
send.push(filter)
|
|
105
|
+
continue
|
|
106
|
+
}
|
|
107
|
+
const fresh: string[] = []
|
|
108
|
+
for (const value of new Set(shape.values)) {
|
|
109
|
+
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 })
|
|
112
|
+
else fresh.push(value)
|
|
113
|
+
}
|
|
114
|
+
if (fresh.length === 0) continue
|
|
115
|
+
send.push({ ...filter, [`#${shape.tag}`]: fresh })
|
|
116
|
+
asked.push({ ...shape, values: fresh })
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
const answer = send.length ? ask(send) : Promise.resolve([])
|
|
120
|
+
for (const shape of asked) {
|
|
121
|
+
const split = answer.then((events) => completeByValue(shape, events))
|
|
122
|
+
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)
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
const out = [...(await answer)]
|
|
137
|
+
// Per filter of the caller's, so a re-ask keeps the grouping it chose.
|
|
138
|
+
const unknown = new Map<ByTag, string[]>()
|
|
139
|
+
for (const { shape, value, entry } of joined) {
|
|
140
|
+
const events = await entry
|
|
141
|
+
if (events) out.push(...events)
|
|
142
|
+
// That read's page was full: ask for this value here, as the caller would have.
|
|
143
|
+
else unknown.set(shape, [...(unknown.get(shape) ?? []), value])
|
|
144
|
+
}
|
|
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
|
+
}
|
|
152
|
+
|
|
153
|
+
// One copy of each event, as one request to the relay answers.
|
|
154
|
+
const seen = new Set<string>()
|
|
155
|
+
return out.filter((e) => !seen.has(e.id) && !!seen.add(e.id))
|
|
156
|
+
}
|
|
157
|
+
}
|
package/src/projection.ts
CHANGED
|
@@ -6321,6 +6321,63 @@ export interface FolderContents extends FolderSummary {
|
|
|
6321
6321
|
* This asks for folders by kind.
|
|
6322
6322
|
*/
|
|
6323
6323
|
export async function listFolders(query: QueryFn): Promise<FolderSummary[]> {
|
|
6324
|
+
const { events, byId } = await readFolderRecords(query)
|
|
6325
|
+
/*
|
|
6326
|
+
A folder listed in another folder's state is a file there. Read off the
|
|
6327
|
+
states already in hand: an `a` naming a `kind:39000` is a channel, and its
|
|
6328
|
+
`d` is the folder's id. Both `KIND_CHANNEL` and the state's own `d` are
|
|
6329
|
+
uuids, so no address has to be built to compare them.
|
|
6330
|
+
*/
|
|
6331
|
+
const listedIn = new Map<string, string[]>()
|
|
6332
|
+
for (const event of events) {
|
|
6333
|
+
if (event.kind !== KIND_FOLDER_STATE) continue
|
|
6334
|
+
const container = tagValue(event, 'd')
|
|
6335
|
+
if (!container) continue
|
|
6336
|
+
for (const tag of event.tags) {
|
|
6337
|
+
if (tag[0] !== 'a' || !tag[1]) continue
|
|
6338
|
+
const [kind, , identifier] = tag[1].split(':')
|
|
6339
|
+
if (Number(kind) !== KIND_CHANNEL || !identifier || identifier === container) continue
|
|
6340
|
+
const containers: string[] = listedIn.get(identifier) ?? []
|
|
6341
|
+
if (!containers.includes(container)) containers.push(container)
|
|
6342
|
+
listedIn.set(identifier, containers)
|
|
6343
|
+
}
|
|
6344
|
+
}
|
|
6345
|
+
const { recordsOf, archives, rootOf } = await placeRecordChannels(events, byId, listedIn, query)
|
|
6346
|
+
for (const [id, containers] of listedIn) {
|
|
6347
|
+
const folder = byId.get(id)
|
|
6348
|
+
if (folder) folder.listedIn = containers
|
|
6349
|
+
}
|
|
6350
|
+
markArchivedFolders(byId, recordsOf, archives, rootOf)
|
|
6351
|
+
return [...byId.values()].sort(byFolderName)
|
|
6352
|
+
}
|
|
6353
|
+
|
|
6354
|
+
/** A Folder as its own records say it: a {@link FolderSummary} before anything is read about the files Folders list. */
|
|
6355
|
+
export type FolderRecord = Omit<FolderSummary, 'listedIn' | 'archived'>
|
|
6356
|
+
|
|
6357
|
+
/**
|
|
6358
|
+
* Every Folder this identity can see, from the Folders' own records only — one
|
|
6359
|
+
* request: the name, privacy and admins (§3.2), the state's list and the
|
|
6360
|
+
* channel's address, as {@link listFolders} gives them.
|
|
6361
|
+
*
|
|
6362
|
+
* **Without `listedIn` and `archived`**, which are what {@link listFolders}
|
|
6363
|
+
* pays for: placing a record's channel and reading archives fetches every
|
|
6364
|
+
* change to every file a Folder lists, and a text save is a whole document.
|
|
6365
|
+
* Measured as the agent on production 2026-10-26: 22.9 MB and 112 s, of which
|
|
6366
|
+
* the `archived` changes it looks for were 44 KB; the Folders' records were
|
|
6367
|
+
* 66 KB in 0.7 s. So this is for finding a Folder by its name or id (the
|
|
6368
|
+
* agent's `file create`), never for a sidebar, which must leave archived and
|
|
6369
|
+
* nested Folders out. The full cost goes when a file's text moves out of its
|
|
6370
|
+
* change log (record a-files-type-is-a-shared-meaning-any-app-extends).
|
|
6371
|
+
*/
|
|
6372
|
+
export async function listFolderRecords(query: QueryFn): Promise<FolderRecord[]> {
|
|
6373
|
+
const { byId } = await readFolderRecords(query)
|
|
6374
|
+
return [...byId.values()].sort(byFolderName)
|
|
6375
|
+
}
|
|
6376
|
+
|
|
6377
|
+
const byFolderName = (a: FolderRecord, b: FolderRecord) => (a.name ?? a.id).localeCompare(b.name ?? b.id)
|
|
6378
|
+
|
|
6379
|
+
/** The Folders' own records, read in one request, as summaries without `listedIn` and `archived`. */
|
|
6380
|
+
async function readFolderRecords(query: QueryFn): Promise<{ events: SignedEvent[]; byId: Map<string, FolderSummary> }> {
|
|
6324
6381
|
const events = await query([
|
|
6325
6382
|
{ kinds: [KIND_FOLDER_STATE], limit: 500 },
|
|
6326
6383
|
{ kinds: [KIND_CHANNEL], limit: 500 },
|
|
@@ -6355,33 +6412,7 @@ export async function listFolders(query: QueryFn): Promise<FolderSummary[]> {
|
|
|
6355
6412
|
if (admins.length) folder.admins = admins
|
|
6356
6413
|
folder.channel = pointerToAddress({ kind: KIND_CHANNEL, pubkey: channel.pubkey, identifier: id, relays: [] })
|
|
6357
6414
|
}
|
|
6358
|
-
|
|
6359
|
-
A folder listed in another folder's state is a file there. Read off the
|
|
6360
|
-
states already in hand: an `a` naming a `kind:39000` is a channel, and its
|
|
6361
|
-
`d` is the folder's id. Both `KIND_CHANNEL` and the state's own `d` are
|
|
6362
|
-
uuids, so no address has to be built to compare them.
|
|
6363
|
-
*/
|
|
6364
|
-
const listedIn = new Map<string, string[]>()
|
|
6365
|
-
for (const event of events) {
|
|
6366
|
-
if (event.kind !== KIND_FOLDER_STATE) continue
|
|
6367
|
-
const container = tagValue(event, 'd')
|
|
6368
|
-
if (!container) continue
|
|
6369
|
-
for (const tag of event.tags) {
|
|
6370
|
-
if (tag[0] !== 'a' || !tag[1]) continue
|
|
6371
|
-
const [kind, , identifier] = tag[1].split(':')
|
|
6372
|
-
if (Number(kind) !== KIND_CHANNEL || !identifier || identifier === container) continue
|
|
6373
|
-
const containers: string[] = listedIn.get(identifier) ?? []
|
|
6374
|
-
if (!containers.includes(container)) containers.push(container)
|
|
6375
|
-
listedIn.set(identifier, containers)
|
|
6376
|
-
}
|
|
6377
|
-
}
|
|
6378
|
-
const { recordsOf, archives, rootOf } = await placeRecordChannels(events, byId, listedIn, query)
|
|
6379
|
-
for (const [id, containers] of listedIn) {
|
|
6380
|
-
const folder = byId.get(id)
|
|
6381
|
-
if (folder) folder.listedIn = containers
|
|
6382
|
-
}
|
|
6383
|
-
markArchivedFolders(byId, recordsOf, archives, rootOf)
|
|
6384
|
-
return [...byId.values()].sort((a, b) => (a.name ?? a.id).localeCompare(b.name ?? b.id))
|
|
6415
|
+
return { events, byId }
|
|
6385
6416
|
}
|
|
6386
6417
|
|
|
6387
6418
|
/**
|
|
@@ -6867,6 +6898,10 @@ export async function resolveFolderContents(
|
|
|
6867
6898
|
]),
|
|
6868
6899
|
]
|
|
6869
6900
|
const nestedFolderIds = pointers.filter(({ pointer }) => pointer.kind === KIND_CHANNEL).map(({ pointer }) => pointer.identifier)
|
|
6901
|
+
// SPEC's change kind is read whole by the archive filters below, so a filter
|
|
6902
|
+
// for it here only repeated them: its 500 newest are among each group's page
|
|
6903
|
+
// (APP-2, where it was most of a second copy of every change).
|
|
6904
|
+
const otherChangeKinds = changeKinds.filter((kind) => kind !== ARCHIVE_RULE.changeKind)
|
|
6870
6905
|
const events = await query([
|
|
6871
6906
|
...[...groups.values()].map(({ pointer, addresses: group }) => ({
|
|
6872
6907
|
kinds: [pointer.kind],
|
|
@@ -6874,11 +6909,9 @@ export async function resolveFolderContents(
|
|
|
6874
6909
|
'#d': group.map((a) => referenceToPointer(a).identifier),
|
|
6875
6910
|
limit: group.length,
|
|
6876
6911
|
})),
|
|
6877
|
-
{ kinds:
|
|
6878
|
-
//
|
|
6879
|
-
//
|
|
6880
|
-
// changes for every file together, and one Folder has already had 688.
|
|
6881
|
-
// Same request.
|
|
6912
|
+
...(otherChangeKinds.length ? [{ kinds: otherChangeKinds, '#a': addresses, limit: 500 }] : []),
|
|
6913
|
+
// Every change, in groups small enough that a busy Folder's changes cannot
|
|
6914
|
+
// push one file's off the page — one Folder has already had 688. Same request.
|
|
6882
6915
|
...archiveFilters(channelAddress ? [...addresses, channelAddress] : addresses),
|
|
6883
6916
|
// A Folder listed here counts its archive only from its own admins (§3.2). Same request.
|
|
6884
6917
|
...(nestedFolderIds.length ? [{ kinds: [KIND_CHANNEL_ADMINS], '#d': nestedFolderIds, limit: nestedFolderIds.length }] : []),
|