@estiva-app/interop 0.37.1 → 0.39.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/projection.ts CHANGED
@@ -1091,12 +1091,36 @@ export interface ResolvedAction {
1091
1091
  field?: string
1092
1092
  }
1093
1093
 
1094
+ /** How the owning app asks one of its kinds to be drawn (RFC 0.4 §13.3). */
1095
+ interface Projection {
1096
+ widget: string | string[]
1097
+ slots: Record<string, SlotSpec | SlotSpec[]>
1098
+ /**
1099
+ * What one of these is called, lower case and singular — "issue",
1100
+ * "project". Resolved onto {@link ForeignObject.noun}; see there.
1101
+ */
1102
+ noun?: string
1103
+ }
1104
+
1105
+ /**
1106
+ * The projection's `noun`, when it is one: a non-empty string, trimmed.
1107
+ *
1108
+ * A manifest is another app's self-description and nothing validates it on
1109
+ * the way in, so `"noun": 5` is publishable. Passed through, it reaches a
1110
+ * consumer typed as a string and breaks there — the first `.charAt` throws
1111
+ * while a menu draws. Anything else reads as "this app does not say" (§7.9).
1112
+ */
1113
+ function nounOf(projection: Projection): { noun?: string } {
1114
+ const noun = typeof projection.noun === 'string' ? projection.noun.trim() : ''
1115
+ return noun ? { noun } : {}
1116
+ }
1117
+
1094
1118
  interface Manifest {
1095
1119
  name?: string
1096
1120
  about?: string
1097
1121
  actions?: ManifestAction[]
1098
1122
  records?: RecordsRule
1099
- projections?: Record<string, { widget: string | string[]; slots: Record<string, SlotSpec | SlotSpec[]> }>
1123
+ projections?: Record<string, Projection>
1100
1124
  vocabularies?: Record<string, { value: string; label: string; colour: string; stage?: string }[]>
1101
1125
  /**
1102
1126
  * Which aspect of *every* file this app renders — RFC 0.5 §10.7's one
@@ -2068,6 +2092,21 @@ function foldChanges(changes: SignedEvent[], rule: RecordsRule) {
2068
2092
  return fields
2069
2093
  }
2070
2094
 
2095
+ /**
2096
+ * One object's fold out of a pooled answer: its app's change kind, naming it as
2097
+ * the **first** target tag, as `archiveOf` reads it. Empty when the app declares
2098
+ * no change events — `foldRuleOf`'s substitute is never asked for.
2099
+ */
2100
+ function foldOf(events: SignedEvent[], address: string, manifest: Manifest) {
2101
+ const records = foldRuleOf(manifest)
2102
+ return foldChanges(
2103
+ manifest.records
2104
+ ? events.filter((e) => e.kind === records.changeKind && tagValue(e, records.targetTag) === address)
2105
+ : [],
2106
+ records,
2107
+ )
2108
+ }
2109
+
2071
2110
  /**
2072
2111
  * How an `archived` change is read when the file's kind declares no rule of its
2073
2112
  * own — a Folder, whose `kind:39000` no app owns, and a bare file. SPEC §7.1's
@@ -2770,6 +2809,18 @@ export interface ForeignObject {
2770
2809
  */
2771
2810
  widget: string | string[]
2772
2811
  appName?: string
2812
+ /**
2813
+ * What the owning app calls one of these — "issue", "project" — read off
2814
+ * its projection's `noun`, lower case and singular (PEE-41).
2815
+ *
2816
+ * For a consumer that names the object in its own words: a menu's "Delete
2817
+ * issue", a confirm's "Delete this project?". Without it Peek called a Ship
2818
+ * issue a topic, because the only way to know better was to check the kind
2819
+ * number, which is the check a manifest exists to replace. Absent when the
2820
+ * owner declares none, and for the bare file, whose manifest lives here: a
2821
+ * consumer says its own word for a file nobody owns.
2822
+ */
2823
+ noun?: string
2773
2824
  /** Named single slots: title, subtitle, status. */
2774
2825
  slots: Record<string, ResolvedSlot>
2775
2826
  /** Repeating slots, e.g. `meta`. */
@@ -2844,7 +2895,7 @@ function buildObject(args: {
2844
2895
  root: SignedEvent
2845
2896
  pointer: AddressPointer
2846
2897
  manifest: Manifest
2847
- projection: { widget: string | string[]; slots: Record<string, SlotSpec | SlotSpec[]> }
2898
+ projection: Projection
2848
2899
  folded: Record<string, { value: string; format?: ContentFormat }>
2849
2900
  viaRecommendation: boolean
2850
2901
  webTemplate?: string
@@ -2885,6 +2936,7 @@ function buildObject(args: {
2885
2936
  kind: pointer.kind,
2886
2937
  widget: projection.widget,
2887
2938
  appName: manifest.name,
2939
+ ...nounOf(projection),
2888
2940
  slots,
2889
2941
  meta,
2890
2942
  comments: args.comments ?? [],
@@ -3018,7 +3070,9 @@ export async function resolveForeignObject(
3018
3070
  const plan = planObject(naddr, pointer, resolved, depth)
3019
3071
  if (!plan) return null
3020
3072
 
3021
- const assembled = assembleObject(plan, await query(plan.filters))
3073
+ const answered = await query(plan.filters)
3074
+ const followUp = childChangeFilters(plan, answered)
3075
+ const assembled = assembleObject(plan, answered, followUp.length ? await queryChunked(followUp, query) : [])
3022
3076
  if (assembled.object.unreachable) return assembled.object
3023
3077
  if (options.archivedWith) await markArchivedParents([{ object: assembled.object, manifest: resolved.manifest }], query)
3024
3078
  return withPeople(assembled, await (lookupPeople ?? peopleViaRelay(query))(peopleOf(assembled)))
@@ -3107,13 +3161,24 @@ export async function resolveForeignObjects(
3107
3161
  planned.add(plan.address)
3108
3162
  filters.push(...plan.filters)
3109
3163
  }
3110
- const chunks: Record<string, unknown>[][] = []
3111
- for (let start = 0; start < filters.length; start += MAX_FILTERS_PER_QUERY) {
3112
- chunks.push(filters.slice(start, start + MAX_FILTERS_PER_QUERY))
3164
+ const events = await queryChunked(filters, query)
3165
+
3166
+ // Every card's children's changes in one more read for the whole set, not
3167
+ // one per card (MAN-7) — and none at all when no card has a fold to read.
3168
+ const followUp: Record<string, unknown>[] = []
3169
+ const followed = new Set<string>()
3170
+ for (const { plan } of plans) {
3171
+ if (followed.has(plan.address)) continue
3172
+ followed.add(plan.address)
3173
+ followUp.push(...childChangeFilters(plan, events))
3113
3174
  }
3114
- const events = (await Promise.all(chunks.map((chunk) => query(chunk)))).flat()
3175
+ const childChanges = followUp.length ? await queryChunked(followUp, query) : []
3115
3176
 
3116
- const assembled = plans.map(({ reference, plan }) => ({ reference, plan, built: assembleObject(plan, events) }))
3177
+ const assembled = plans.map(({ reference, plan }) => ({
3178
+ reference,
3179
+ plan,
3180
+ built: assembleObject(plan, events, childChanges),
3181
+ }))
3117
3182
  if (options.archivedWith) {
3118
3183
  await markArchivedParents(assembled.map(({ plan, built }) => ({ object: built.object, manifest: plan.resolved.manifest })), query)
3119
3184
  }
@@ -3203,12 +3268,16 @@ const ARCHIVE_READ_GROUP = 25
3203
3268
  * The filters asking for every change naming these addresses, once per distinct
3204
3269
  * change shape among `rules` — SPEC's alone unless an app writes its own.
3205
3270
  */
3206
- function archiveFilters(addresses: readonly string[], rules: readonly RecordsRule[] = [ARCHIVE_RULE]): Record<string, unknown>[] {
3271
+ function archiveFilters(
3272
+ addresses: readonly string[],
3273
+ rules: readonly RecordsRule[] = [ARCHIVE_RULE],
3274
+ groupSize = ARCHIVE_READ_GROUP,
3275
+ ): Record<string, unknown>[] {
3207
3276
  const shapes = new Map(rules.map((rule) => [`${rule.changeKind}:${rule.targetTag}`, rule]))
3208
3277
  const filters: Record<string, unknown>[] = []
3209
3278
  for (const rule of shapes.values()) {
3210
- for (let start = 0; start < addresses.length; start += ARCHIVE_READ_GROUP) {
3211
- const group = addresses.slice(start, start + ARCHIVE_READ_GROUP)
3279
+ for (let start = 0; start < addresses.length; start += groupSize) {
3280
+ const group = addresses.slice(start, start + groupSize)
3212
3281
  filters.push({ kinds: [rule.changeKind], [`#${rule.targetTag}`]: group, limit: RELAY_PAGE_CEILING })
3213
3282
  }
3214
3283
  }
@@ -3221,12 +3290,16 @@ async function readArchiveChanges(
3221
3290
  query: QueryFn,
3222
3291
  rules?: readonly RecordsRule[],
3223
3292
  ): Promise<SignedEvent[]> {
3224
- const filters = archiveFilters(addresses, rules)
3225
- const events: SignedEvent[] = []
3293
+ return queryChunked(archiveFilters(addresses, rules), query)
3294
+ }
3295
+
3296
+ /** `filters` in as few POSTs as the relay takes, answers pooled. */
3297
+ async function queryChunked(filters: Record<string, unknown>[], query: QueryFn): Promise<SignedEvent[]> {
3298
+ const chunks: Record<string, unknown>[][] = []
3226
3299
  for (let start = 0; start < filters.length; start += MAX_FILTERS_PER_QUERY) {
3227
- events.push(...(await query(filters.slice(start, start + MAX_FILTERS_PER_QUERY))))
3300
+ chunks.push(filters.slice(start, start + MAX_FILTERS_PER_QUERY))
3228
3301
  }
3229
- return events
3302
+ return (await Promise.all(chunks.map((chunk) => query(chunk)))).flat()
3230
3303
  }
3231
3304
 
3232
3305
  /** An `naddr` or a `<kind>:<pubkey>:<d>`, or null for anything else. */
@@ -3253,7 +3326,7 @@ interface ObjectPlan {
3253
3326
  pointer: AddressPointer
3254
3327
  address: string
3255
3328
  resolved: ResolvedManifest
3256
- projection: { widget: string | string[]; slots: Record<string, SlotSpec | SlotSpec[]> }
3329
+ projection: Projection
3257
3330
  records: RecordsRule
3258
3331
  commentKinds: number[]
3259
3332
  childFilter: ReturnType<typeof childFilterFor>
@@ -3332,8 +3405,8 @@ interface AssembledObject {
3332
3405
  * filters match — a comment naming two files in the set, a `kind:9` that is a
3333
3406
  * Topic's child and its comment — would otherwise be drawn twice.
3334
3407
  */
3335
- function assembleObject(plan: ObjectPlan, answered: SignedEvent[]): AssembledObject {
3336
- const { naddr, pointer, address, resolved, projection, records, commentKinds, childFilter, openUrl } = plan
3408
+ function assembleObject(plan: ObjectPlan, answered: SignedEvent[], childChanges: SignedEvent[] = []): AssembledObject {
3409
+ const { naddr, pointer, address, resolved, projection, commentKinds, childFilter, openUrl } = plan
3337
3410
  const { manifest, viaRecommendation } = resolved
3338
3411
  const seen = new Set<string>()
3339
3412
  const events = answered.filter((e) => !seen.has(e.id) && !!seen.add(e.id))
@@ -3355,6 +3428,7 @@ function assembleObject(plan: ObjectPlan, answered: SignedEvent[]): AssembledObj
3355
3428
  kind: pointer.kind,
3356
3429
  widget: projection.widget,
3357
3430
  appName: manifest.name,
3431
+ ...nounOf(projection),
3358
3432
  slots: {},
3359
3433
  meta: [],
3360
3434
  comments: [],
@@ -3368,12 +3442,7 @@ function assembleObject(plan: ObjectPlan, answered: SignedEvent[]): AssembledObj
3368
3442
  }
3369
3443
  }
3370
3444
 
3371
- const folded = foldChanges(
3372
- manifest.records
3373
- ? events.filter((e) => e.kind === records.changeKind && tagValue(e, records.targetTag) === address)
3374
- : [],
3375
- records,
3376
- )
3445
+ const folded = foldOf(events, address, manifest)
3377
3446
 
3378
3447
  /*
3379
3448
  Matched on the comment filter's own criteria — the kind **and** the `a` tag.
@@ -3427,6 +3496,7 @@ function assembleObject(plan: ObjectPlan, answered: SignedEvent[]): AssembledObj
3427
3496
  manifest,
3428
3497
  webTemplate: resolved.webTemplate,
3429
3498
  viaRecommendation,
3499
+ childChanges,
3430
3500
  })
3431
3501
 
3432
3502
  return { object, ...(children ? { children } : {}) }
@@ -3587,11 +3657,11 @@ function listsChildrenOf(
3587
3657
  }
3588
3658
 
3589
3659
  function childFilterFor(args: {
3590
- projection: { widget: string | string[]; slots: Record<string, SlotSpec | SlotSpec[]> }
3660
+ projection: Projection
3591
3661
  manifest: Manifest
3592
3662
  pointer: AddressPointer
3593
3663
  depth: number
3594
- }): { filter: Record<string, unknown>; kind: number; via: string; parent: string } | null | undefined {
3664
+ }): { filter: Record<string, unknown>; kind: number; via: string; parent: string; movedBy?: string } | null | undefined {
3595
3665
  const { projection, manifest, pointer, depth } = args
3596
3666
  const children = declaredChildSpec(projection)
3597
3667
  if (!children) return undefined
@@ -3612,6 +3682,9 @@ function childFilterFor(args: {
3612
3682
  kind: children.kind,
3613
3683
  via: children.via,
3614
3684
  parent,
3685
+ // This list's own, not whichever projection declares one for the kind — and
3686
+ // none on an identifier list, where a move's address never names the parent.
3687
+ ...(children.movedBy && children.match !== 'identifier' ? { movedBy: children.movedBy } : {}),
3615
3688
  }
3616
3689
  }
3617
3690
 
@@ -3632,23 +3705,105 @@ function childrenFrom(args: {
3632
3705
  manifest: Manifest
3633
3706
  webTemplate?: string
3634
3707
  viaRecommendation: boolean
3708
+ /** What {@link childChangeFilters} asked for; empty when it asked nothing. */
3709
+ childChanges?: SignedEvent[]
3635
3710
  }): ForeignObject[] | undefined {
3636
- const { events, childFilter, manifest, webTemplate, viaRecommendation } = args
3711
+ const { events, childFilter, manifest, webTemplate, viaRecommendation, childChanges = [] } = args
3637
3712
  if (childFilter === undefined) return undefined
3638
3713
  if (childFilter === null) return []
3639
3714
 
3640
3715
  const childProjection = manifest.projections?.[String(childFilter.kind)]
3641
3716
  if (!childProjection) return []
3642
3717
  const records = foldRuleOf(manifest)
3718
+ const { movedBy } = childFilter
3719
+
3720
+ return childRootsOf(events, childFilter).flatMap((event) => {
3721
+ const address = childAddressOf(event)
3722
+ /*
3723
+ The child's own fold — MAN-7. Until this, a card's children were built
3724
+ from their roots alone, so a moved issue was drawn under the project it
3725
+ was created in, and its status was whatever the root said at creation.
3726
+
3727
+ Folded as the object itself is (`foldOf`, the first target tag), and
3728
+ dropped for the reasons the Folder listing drops a file:
3729
+
3730
+ - **moved away** — SPEC §7.2: a `#via` read finds the children created
3731
+ here, including the ones moved since, and a consumer MUST drop a child
3732
+ whose folded `movedBy` names another parent. An empty value, or one
3733
+ that names no parent at all, is not this parent either. Only a folded
3734
+ value counts: without one the `via` tag is the parent, and that is what
3735
+ found the child.
3736
+ - **hidden** by the app's own `hiddenWhen`, or **archived** (FOL-46).
3737
+
3738
+ A child moved *in* is not found here and cannot be: its new parent is in
3739
+ a `value`, which no relay indexes. SPEC §7.2 names the Folder listing as
3740
+ the only read that sees one.
3741
+ */
3742
+ const folded = address ? foldOf(childChanges, address, manifest) : {}
3743
+ if (movedBy && folded[movedBy] && folded[movedBy].value !== childFilter.parent) return []
3744
+ if (records.hiddenWhen && folded[records.hiddenWhen.field]?.value === records.hiddenWhen.equals) return []
3745
+ if (address && manifest.records && archiveOf(childChanges, address, records)) return []
3746
+ return [
3747
+ buildChildObject({ root: event, manifest, projection: childProjection, records, webTemplate, viaRecommendation, folded }),
3748
+ ]
3749
+ })
3750
+ }
3643
3751
 
3752
+ /** The child roots a `list` filter asked for, picked back out of a pooled answer on its own criteria. */
3753
+ function childRootsOf(events: SignedEvent[], childFilter: NonNullable<ReturnType<typeof childFilterFor>>): SignedEvent[] {
3644
3754
  return events
3645
3755
  .filter((e) => e.kind === childFilter.kind && hasTagValue(e, childFilter.via, childFilter.parent))
3646
3756
  .sort(byOrder)
3647
- .map((event) =>
3648
- buildChildObject({ root: event, manifest, projection: childProjection, records, webTemplate, viaRecommendation }),
3649
- )
3757
+ }
3758
+
3759
+ /** A child's address, or undefined for a regular event, which has none. */
3760
+ function childAddressOf(event: SignedEvent): string | undefined {
3761
+ const identifier = tagValue(event, 'd')
3762
+ return identifier === undefined
3763
+ ? undefined
3764
+ : pointerToAddress({ kind: event.kind, pubkey: event.pubkey, identifier, relays: [] })
3650
3765
  }
3651
3766
 
3767
+ /**
3768
+ * The second read a card's children need, or none — MAN-7.
3769
+ *
3770
+ * A child's changes name the child's address, which is not known until the
3771
+ * children are back, so this cannot ride in the object's own request the way
3772
+ * the children do (SHI-13). It is asked **only when there is a fold to read**:
3773
+ * the app declares change events (`records`) and the list holds at least one
3774
+ * addressable child. Peek's Topic lists `kind:9` messages, which nothing can
3775
+ * change by address, so a Topic card stays one request; a Ship project card
3776
+ * with issues is two.
3777
+ *
3778
+ * The alternative on the ticket — folding from a cached Folder read — was not
3779
+ * taken: interop's caches are the caller's (`ProjectionCache` holds manifests,
3780
+ * never objects), a card is pasted into Folders other than its own, and a stale
3781
+ * cached fold is the moved-issue bug again with a delay on it.
3782
+ *
3783
+ * Grouped as the archive reads are ({@link archiveFilters}), but smaller: a
3784
+ * filter's `limit` covers every change naming every address in it, and a relay
3785
+ * answers newest first, so a group whose changes overflow the page loses its
3786
+ * *oldest* — and a move made long ago is exactly what must not fall off. Ten
3787
+ * issues to a page of 1,000 is a hundred changes each; a card of 200 is twenty
3788
+ * filters, still one POST.
3789
+ *
3790
+ * Nothing when the root did not come back: the object is unreachable and its
3791
+ * children are never drawn, so their changes would be a request for nothing.
3792
+ */
3793
+ function childChangeFilters(plan: ObjectPlan, answered: SignedEvent[]): Record<string, unknown>[] {
3794
+ const { childFilter, resolved, pointer } = plan
3795
+ const records = resolved.manifest.records
3796
+ if (!childFilter || !records) return []
3797
+ if (!answered.some((e) => e.kind === pointer.kind && e.pubkey === pointer.pubkey && tagValue(e, 'd') === pointer.identifier)) {
3798
+ return []
3799
+ }
3800
+ const addresses = [...new Set(childRootsOf(answered, childFilter).flatMap((e) => childAddressOf(e) ?? []))]
3801
+ return addresses.length ? archiveFilters(addresses, [records], CHILD_CHANGE_GROUP) : []
3802
+ }
3803
+
3804
+ /** Addresses per filter when reading a card's children's changes — see {@link childChangeFilters}. */
3805
+ const CHILD_CHANGE_GROUP = 10
3806
+
3652
3807
  /**
3653
3808
  * Build a `ForeignObject` from an event that may have no address of its own.
3654
3809
  *
@@ -3664,7 +3819,7 @@ function childrenFrom(args: {
3664
3819
  function buildChildObject(args: {
3665
3820
  root: SignedEvent
3666
3821
  manifest: Manifest
3667
- projection: { widget: string | string[]; slots: Record<string, SlotSpec | SlotSpec[]> }
3822
+ projection: Projection
3668
3823
  records: RecordsRule
3669
3824
  webTemplate?: string
3670
3825
  viaRecommendation: boolean
@@ -3677,8 +3832,13 @@ function buildChildObject(args: {
3677
3832
  * `openUrl` at all, which is PRO-11's "its web link opens that message".
3678
3833
  */
3679
3834
  nevent?: string
3835
+ /**
3836
+ * The child's own fold, when {@link childChangeFilters} read its changes
3837
+ * (MAN-7). Empty for a regular event, which nothing can change by address.
3838
+ */
3839
+ folded?: Record<string, { value: string; format?: ContentFormat }>
3680
3840
  }): ForeignObject {
3681
- const { root, manifest, projection, webTemplate, viaRecommendation, nevent } = args
3841
+ const { root, manifest, projection, webTemplate, viaRecommendation, nevent, folded = {} } = args
3682
3842
  const identifier = tagValue(root, 'd')
3683
3843
  const addressable = identifier !== undefined
3684
3844
  const pointer: AddressPointer = {
@@ -3689,7 +3849,7 @@ function buildChildObject(args: {
3689
3849
  }
3690
3850
  const address = addressable ? pointerToAddress(pointer) : undefined
3691
3851
  const naddr = addressable ? encodeNaddr(pointer) : undefined
3692
- const { slots, meta } = resolveSlots(projection, root, {}, manifest)
3852
+ const { slots, meta } = resolveSlots(projection, root, folded, manifest)
3693
3853
 
3694
3854
  return {
3695
3855
  // A regular event's identity is its id; a replaceable one's is its address,
@@ -3701,6 +3861,7 @@ function buildChildObject(args: {
3701
3861
  kind: root.kind,
3702
3862
  widget: projection.widget,
3703
3863
  appName: manifest.name,
3864
+ ...nounOf(projection),
3704
3865
  slots,
3705
3866
  meta,
3706
3867
  comments: [],
@@ -3709,7 +3870,7 @@ function buildChildObject(args: {
3709
3870
  // way and not the other. A child already knows its parent contextually, but
3710
3871
  // an inconsistent shape is what makes a consumer defensive about a value it
3711
3872
  // should be able to trust.
3712
- parentRef: parentRefOf(manifest, root.kind, root),
3873
+ parentRef: parentRefOf(manifest, root.kind, root, folded),
3713
3874
  ...parentFieldsOf(manifest, root.kind),
3714
3875
  folder: tagValue(root, 'h'),
3715
3876
  /*