@estiva-app/interop 0.82.0 → 0.84.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/references.ts CHANGED
@@ -25,12 +25,13 @@ import {
25
25
  import {
26
26
  isClosedStatus,
27
27
  KIND_BARE_FILE,
28
+ projectListedFiles,
28
29
  resolveForeignRoots,
29
30
  type ForeignObject,
30
31
  type ProjectionCache,
31
32
  type QueryFn,
32
33
  } from './projection.js'
33
- import { fileIdFormOf } from '@estiva-app/protocol'
34
+ import { fileIdFormOf, type SearchMatch, type SignedEvent } from '@estiva-app/protocol'
34
35
 
35
36
  const KIND_PROJECT = 30850
36
37
  const KIND_ISSUE = 30851
@@ -81,6 +82,8 @@ export interface FileCandidatesOptions {
81
82
  inOrder?: readonly string[]
82
83
  /** The host Ship serves projects from: a picked project's link is `<it>/project/<d>`. Ship's own unless said, so every app picks the same link. */
83
84
  projectOrigin?: string
85
+ /** The relay offers the list read: an issue's project, read for its caption, is read by its current fields (`resolveForeignRoots`). */
86
+ listRead?: boolean
84
87
  }
85
88
 
86
89
  /** Where Ship serves projects (§13.1, decided 2026-11-03): one link for a project, whichever app picked it. */
@@ -116,7 +119,7 @@ export async function fileCandidates(
116
119
  objects: readonly (ForeignObject | null | undefined)[],
117
120
  tier: number,
118
121
  query: QueryFn,
119
- { cache, at, inOrder, projectOrigin }: FileCandidatesOptions = {},
122
+ { cache, at, inOrder, projectOrigin, listRead }: FileCandidatesOptions = {},
120
123
  ): Promise<ReferenceCandidate[]> {
121
124
  const files = objects.filter(offerable)
122
125
  const parents = new Map<string, ForeignObject>()
@@ -125,7 +128,7 @@ export async function fileCandidates(
125
128
  ...new Set(files.flatMap((o) => (o.kind === KIND_ISSUE && o.parentRef && !parents.has(o.parentRef) ? [o.parentRef] : []))),
126
129
  ]
127
130
  if (missing.length) {
128
- const read = await resolveForeignRoots(missing, query, cache).catch(() => [])
131
+ const read = await resolveForeignRoots(missing, query, cache, { listRead }).catch(() => [])
129
132
  for (const parent of read) if (parent.address) parents.set(parent.address, parent)
130
133
  }
131
134
  return files.map((o) => {
@@ -150,9 +153,24 @@ export async function fileCandidates(
150
153
  })
151
154
  }
152
155
 
156
+ /** A `/query` that keeps what a `search` found besides its events (protocol's `Relay.queryWithMatches`). */
157
+ export type SearchQueryFn = (filters: Record<string, unknown>[]) => Promise<{ events: SignedEvent[]; matches: readonly SearchMatch[] }>
158
+
153
159
  export interface SearchFileReferencesOptions extends Omit<FileCandidatesOptions, 'at'> {
154
160
  /** How many roots, and separately how many renames, the relay is asked for. Default 32. */
155
161
  limit?: number
162
+ /**
163
+ * The kinds the relay finds by the words of their current fields (NIP-11
164
+ * `file_search`, `RelayFileReads.search`), and the read that asks it. Those
165
+ * kinds are found by their summary, key and text too, through the list read;
166
+ * every other kind by its title as before.
167
+ */
168
+ byFields?: {
169
+ kinds: readonly number[]
170
+ query: SearchQueryFn
171
+ /** The relay's `file_search.max_page_size`, which refuses a larger page. Default 20, production's. */
172
+ limit?: number
173
+ }
156
174
  }
157
175
 
158
176
  const tagOf = (event: { tags: string[][] }, name: string) => event.tags.find((t) => t[0] === name)?.[1]
@@ -181,17 +199,38 @@ const searchedChange = (field: string | undefined, address: string | undefined)
181
199
  * still sent for a relay from before that rule. A relay that indexes none of these
182
200
  * kinds answers nothing, and so does this. A failed read rejects, for
183
201
  * `referenceSearch` to answer no hits for a while.
202
+ *
203
+ * With `byFields`, its kinds are found by the words of their current fields
204
+ * instead, ahead of the title hits (`searchByFields`).
184
205
  */
185
206
  export async function searchFileReferences(
186
207
  text: string,
187
208
  query: QueryFn,
188
- { limit = 32, ...options }: SearchFileReferencesOptions = {},
209
+ { limit = 32, byFields, ...options }: SearchFileReferencesOptions = {},
189
210
  ): Promise<ReferenceCandidate[]> {
190
211
  const wanted = text.trim()
191
212
  if (!wanted) return []
213
+ const fieldKinds = new Set(byFields?.kinds.filter((kind) => typeOf(kind)) ?? [])
214
+ const [byTitle, found] = await Promise.all([
215
+ searchByTitle(wanted, query, limit, fieldKinds, options),
216
+ byFields && fieldKinds.size ? searchByFields(wanted, byFields.query, [...fieldKinds], byFields.limit ?? 20, query, options) : [],
217
+ ])
218
+ return [...found, ...byTitle]
219
+ }
220
+
221
+ /** The files of every kind but `skip` whose current title or ref holds `wanted`. */
222
+ async function searchByTitle(
223
+ wanted: string,
224
+ query: QueryFn,
225
+ limit: number,
226
+ skip: ReadonlySet<number>,
227
+ options: Omit<FileCandidatesOptions, 'at'>,
228
+ ): Promise<ReferenceCandidate[]> {
229
+ const kinds = Object.keys(REFERENCE_FILE_TYPES).map(Number).filter((kind) => !skip.has(kind))
230
+ if (!kinds.length) return []
192
231
  const asked = { search: wanted, search_mode: 'prefix', limit }
193
232
  const hits = await query([
194
- { kinds: Object.keys(REFERENCE_FILE_TYPES).map(Number), ...asked },
233
+ { kinds, ...asked },
195
234
  { kinds: [KIND_CHANGE], ...asked },
196
235
  ])
197
236
  const at = new Map<string, number>()
@@ -200,7 +239,8 @@ export async function searchFileReferences(
200
239
  hit.kind === KIND_CHANGE
201
240
  ? searchedChange(tagOf(hit, 'field'), tagOf(hit, 'a'))
202
241
  : typeOf(hit.kind) && `${hit.kind}:${hit.pubkey}:${tagOf(hit, 'd') ?? ''}`
203
- if (!address || !typeOf(Number(address.split(':')[0]))) continue
242
+ const kind = Number(address?.split(':')[0])
243
+ if (!address || !typeOf(kind) || skip.has(kind)) continue
204
244
  at.set(address, Math.max(at.get(address) ?? 0, hit.created_at))
205
245
  }
206
246
  if (at.size === 0) return []
@@ -208,3 +248,39 @@ export async function searchFileReferences(
208
248
  const matching = objects.filter((o) => (o.slots.title && referenceMatch(o.slots.title.value, wanted) > 0) || refMatch(refOf(o), wanted) > 0)
209
249
  return fileCandidates(matching, FILE_TIER.search, query, { ...options, at })
210
250
  }
251
+
252
+ /**
253
+ * The files of `kinds` whose current title, summary, key or text holds
254
+ * `wanted`, by the relay's list read with `search` (§6.13): each hit is its
255
+ * first record and its fields' current changes, so nothing is folded from its
256
+ * history and nothing older than its current values matches. A hit found only
257
+ * in its text shows the words around the match as its second line.
258
+ *
259
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/search-finds-a-file-by-the-words-of-its-current-fields.md
260
+ */
261
+ async function searchByFields(
262
+ wanted: string,
263
+ search: SearchQueryFn,
264
+ kinds: readonly number[],
265
+ limit: number,
266
+ query: QueryFn,
267
+ options: Omit<FileCandidatesOptions, 'at'>,
268
+ ): Promise<ReferenceCandidate[]> {
269
+ const { events, matches } = await search([{ kinds, search: wanted, limit, fields: 'newest' }])
270
+ const why = new Map(matches.map((m) => [m.a, m.match]))
271
+ const at = new Map<string, number>()
272
+ const objects = (await projectListedFiles(events, query, options.cache)).filter((o) => o.address && why.has(o.address))
273
+ for (const event of events) {
274
+ const address = event.kind === KIND_CHANGE ? tagOf(event, 'a') : `${event.kind}:${event.pubkey}:${tagOf(event, 'd') ?? ''}`
275
+ if (address && why.has(address)) at.set(address, Math.max(at.get(address) ?? 0, event.created_at))
276
+ }
277
+ const rank = new Map(matches.map((m, i) => [m.a, i]))
278
+ objects.sort((a, b) => rank.get(a.address!)! - rank.get(b.address!)!)
279
+ const rows = await fileCandidates(objects, FILE_TIER.search, query, { ...options, at })
280
+ return rows.map((row) => {
281
+ const match = why.get(row.id)!
282
+ const around = match.fields[0] === 'text' ? match.around?.replace(/\s+/g, ' ').trim() : undefined
283
+ // "…" marks words from inside the text, not the file's own summary; the relay does not say where they start.
284
+ return { ...row, matched: match.fields, ...(around ? { summary: `…${around}` } : {}) }
285
+ })
286
+ }