@estiva-app/interop 0.70.2 → 0.72.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 +39 -0
- package/README.md +26 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -0
- package/dist/index.js.map +1 -1
- package/dist/topics.d.ts +143 -0
- package/dist/topics.d.ts.map +1 -0
- package/dist/topics.js +269 -0
- package/dist/topics.js.map +1 -0
- package/package.json +1 -1
- package/src/index.ts +22 -0
- package/src/topics.ts +326 -0
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,45 @@ how a declaration is read, is a MAJOR — in `0.x`, a MINOR — even when no
|
|
|
6
6
|
TypeScript signature moved. A consumer upgrading must be able to tell whether
|
|
7
7
|
manifests already published still mean what they meant.
|
|
8
8
|
|
|
9
|
+
## 0.72.0 — 2026-11-02
|
|
10
|
+
|
|
11
|
+
**Manifest: nothing.** Many topics' lists in one go, for Peek's Topics screen
|
|
12
|
+
(TOP-4). New API only; `topicList` answers as before.
|
|
13
|
+
|
|
14
|
+
- `topicLists(query, topicAddresses)` returns a `Map` from every address asked
|
|
15
|
+
to its listed files, by `topicList`'s rules, in three reads whatever the
|
|
16
|
+
number of topics: the roots, every topic's changes (`#O`, at most 20 topics
|
|
17
|
+
per filter) and one batched `#d` resolve. One `topicList` per topic is three
|
|
18
|
+
reads each, and at Miky's 32 topics the relay answered "rate-limited: quota
|
|
19
|
+
exceeded" (2 Nov). A topic that lists nothing, or that the reader cannot
|
|
20
|
+
read, maps to `[]`.
|
|
21
|
+
- `topicList` is now `topicLists` of one topic.
|
|
22
|
+
|
|
23
|
+
## 0.71.0 — 2026-10-30
|
|
24
|
+
|
|
25
|
+
**Manifest: nothing.** A topic keeps a list of files from any Folder, and any
|
|
26
|
+
app can ask which topics list a file (SPEC §6.14; record
|
|
27
|
+
a-topic-keeps-its-own-list-of-files). New API only; every read that existed is
|
|
28
|
+
unchanged.
|
|
29
|
+
|
|
30
|
+
- `planListInTopic` and `planRemoveFromTopic` write one `kind:1851` entry on
|
|
31
|
+
the topic: `a`, `O` (the topic's `d`), `field` `lists:<d>`, `value`
|
|
32
|
+
`true`/`false`, `h` (the topic's Folder), `ts`, `["o", <d>]`. No `p`: a
|
|
33
|
+
listing adds nobody to the file.
|
|
34
|
+
- `topicsOfFile(query, d)` asks `{kinds:[1851], "#o":[d]}` and returns the
|
|
35
|
+
topics whose newest entry lists the file, each with its root; an entry filed
|
|
36
|
+
outside its topic's Folder, on a topic the reader cannot read, or on any
|
|
37
|
+
other type is left out. `topicList(query, topicAddress)` reads the topic's
|
|
38
|
+
root for its Folder and returns its listed
|
|
39
|
+
files, in no promised order, each id resolved over `LISTED_FILE_KINDS` (or
|
|
40
|
+
`fileKinds`), never a Folder's `39000`; an id held by two files or by none
|
|
41
|
+
resolves to `null`, not drawn and not counted.
|
|
42
|
+
- `listEntries` is the fold both use: newest per topic and file, listed only
|
|
43
|
+
by exactly `true`; an entry is skipped when none of its `o` is the field's
|
|
44
|
+
`<d>`, its `O` is not its `a`'s `d`, it lists the topic itself, or it names
|
|
45
|
+
no Folder. `topicsOfFileFilter`, `topicListFilter` and `listsField` are the
|
|
46
|
+
filters and the field name.
|
|
47
|
+
|
|
9
48
|
## 0.70.2 — 2026-10-30
|
|
10
49
|
|
|
11
50
|
**Manifest: nothing.** A reader may ask for a file's archived children too
|
package/README.md
CHANGED
|
@@ -740,6 +740,32 @@ Its wording is the relay's. Take the count and say it in your app's words
|
|
|
740
740
|
("This Folder still has 2 files. Move or delete them first."), as you would
|
|
741
741
|
for `target-is-private`.
|
|
742
742
|
|
|
743
|
+
### A topic's list of files (0.71.0)
|
|
744
|
+
|
|
745
|
+
A topic lists files from any Folder, one `kind:1851` entry per file, by the
|
|
746
|
+
file's id (SPEC §6.14). The file stays where it is filed; a listing grants,
|
|
747
|
+
moves and archives nothing.
|
|
748
|
+
|
|
749
|
+
```ts
|
|
750
|
+
import { planListInTopic, planRemoveFromTopic, topicList, topicsOfFile, folderOf } from '@estiva-app/interop'
|
|
751
|
+
|
|
752
|
+
const topic = { address: topicAddress, folder: folderOf(topicRoot)! } // the Folder its root names
|
|
753
|
+
const [entry] = planListInTopic(me, Date.now(), { topic, file: projectId }) // or planRemoveFromTopic
|
|
754
|
+
await publish(await sign(entry))
|
|
755
|
+
|
|
756
|
+
const files = await topicList(query, topicAddress) // [{ file, address, entry }], in no promised order: sort as your design says
|
|
757
|
+
const shown = files.filter((f) => f.address) // address null: unreadable, or two files hold the id
|
|
758
|
+
const topics = await topicsOfFile(query, projectId) // [{ address, root, entry }]: which topics list it
|
|
759
|
+
const lists = await topicLists(query, myTopics) // Map<topicAddress, files>: a whole column of topics in three reads
|
|
760
|
+
```
|
|
761
|
+
|
|
762
|
+
`topicsOfFile` asks `{kinds:[1851], "#o":[id]}`; a file's own changes, by `#O`
|
|
763
|
+
or `#a`, never hold an entry that lists it. Only topics' lists are read, an
|
|
764
|
+
entry filed outside its topic's Folder is ignored, and an id held by two files
|
|
765
|
+
or only by a Folder resolves to nothing: draw and count only the resolved ones.
|
|
766
|
+
`topicList` resolves ids over `LISTED_FILE_KINDS`; pass `fileKinds` for kinds
|
|
767
|
+
you know from manifests.
|
|
768
|
+
|
|
743
769
|
### Archiving anything (0.37.0)
|
|
744
770
|
|
|
745
771
|
```ts
|
package/dist/index.d.ts
CHANGED
|
@@ -43,6 +43,12 @@ export { fileCandidates, REFERENCE_FILE_TYPES, searchFileReferences, type FileCa
|
|
|
43
43
|
* empties it. No signing, no requests.
|
|
44
44
|
*/
|
|
45
45
|
export { planCreateFolder, planRenameFolder, planDeleteFolder, planPlaceFile, planUnlistFile, planMoveFile, planMoveFromFolders, planArchiveFolder, listedBeneath, type FolderRef, type MovableFile, type MovePlan, type MoveFromFoldersPlan, type MoveRefusal, } from './folders.js';
|
|
46
|
+
/**
|
|
47
|
+
* SPEC §6.14: a topic's list of files from any Folder, one `kind:1851` entry
|
|
48
|
+
* per file by its id. Plan an entry, read a topic's list, and ask which topics
|
|
49
|
+
* list a file (`#o`); a file's own changes (`#O`) never hold an entry.
|
|
50
|
+
*/
|
|
51
|
+
export { planListInTopic, planRemoveFromTopic, topicsOfFile, topicList, topicLists, topicsOfFileFilter, topicListFilter, listEntries, listsField, LISTED_FILE_KINDS, type ListHolder, type ListEntry, type FileTopic, type ListedFile, } from './topics.js';
|
|
46
52
|
/**
|
|
47
53
|
* What an app link names, and where a file is mentioned — once for every app
|
|
48
54
|
* (SPEC §7.7, §13.1, §6.8; PEEKM-7). Each app passes its relay read; none
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/dist/index.js
CHANGED
|
@@ -43,6 +43,12 @@ export { fileCandidates, REFERENCE_FILE_TYPES, searchFileReferences, } from './r
|
|
|
43
43
|
* empties it. No signing, no requests.
|
|
44
44
|
*/
|
|
45
45
|
export { planCreateFolder, planRenameFolder, planDeleteFolder, planPlaceFile, planUnlistFile, planMoveFile, planMoveFromFolders, planArchiveFolder, listedBeneath, } from './folders.js';
|
|
46
|
+
/**
|
|
47
|
+
* SPEC §6.14: a topic's list of files from any Folder, one `kind:1851` entry
|
|
48
|
+
* per file by its id. Plan an entry, read a topic's list, and ask which topics
|
|
49
|
+
* list a file (`#o`); a file's own changes (`#O`) never hold an entry.
|
|
50
|
+
*/
|
|
51
|
+
export { planListInTopic, planRemoveFromTopic, topicsOfFile, topicList, topicLists, topicsOfFileFilter, topicListFilter, listEntries, listsField, LISTED_FILE_KINDS, } from './topics.js';
|
|
46
52
|
/**
|
|
47
53
|
* What an app link names, and where a file is mentioned — once for every app
|
|
48
54
|
* (SPEC §7.7, §13.1, §6.8; PEEKM-7). Each app passes its relay read; none
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,aAAa,EAIb,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,0BAA0B,EAC1B,sBAAsB,EACtB,OAAO,EAEP,cAAc,EACd,oBAAoB,EACpB,eAAe,EAEf,SAAS,EAET,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EAEjB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EAErB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EAmBnB,cAAc,GAEf,MAAM,iBAAiB,CAAA;AAExB;;;GAGG;AACH,OAAO,EAAE,SAAS,EAA+B,MAAM,cAAc,CAAA;AACrE,OAAO,EAAE,eAAe,EAAyB,MAAM,gBAAgB,CAAA;AAEvE;;;GAGG;AACH,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,oBAAoB,GAGrB,MAAM,iBAAiB,CAAA;AAExB;;;;;GAKG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,GAMd,MAAM,cAAc,CAAA;AAErB;;;;GAIG;AACH,OAAO,EACL,UAAU,EACV,UAAU,EACV,OAAO,EACP,eAAe,EACf,MAAM,EACN,eAAe,GAKhB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,4BAA4B,GAE7B,MAAM,eAAe,CAAA;AAEtB;;;;;;;GAOG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,UAAU,GAGX,MAAM,gBAAgB,CAAA"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,aAAa,EAIb,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,0BAA0B,EAC1B,sBAAsB,EACtB,OAAO,EAEP,cAAc,EACd,oBAAoB,EACpB,eAAe,EAEf,SAAS,EAET,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EAEjB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EAErB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EAmBnB,cAAc,GAEf,MAAM,iBAAiB,CAAA;AAExB;;;GAGG;AACH,OAAO,EAAE,SAAS,EAA+B,MAAM,cAAc,CAAA;AACrE,OAAO,EAAE,eAAe,EAAyB,MAAM,gBAAgB,CAAA;AAEvE;;;GAGG;AACH,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,oBAAoB,GAGrB,MAAM,iBAAiB,CAAA;AAExB;;;;;GAKG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,GAMd,MAAM,cAAc,CAAA;AAErB;;;;GAIG;AACH,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,SAAS,EACT,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,UAAU,EACV,iBAAiB,GAKlB,MAAM,aAAa,CAAA;AAEpB;;;;GAIG;AACH,OAAO,EACL,UAAU,EACV,UAAU,EACV,OAAO,EACP,eAAe,EACf,MAAM,EACN,eAAe,GAKhB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,4BAA4B,GAE7B,MAAM,eAAe,CAAA;AAEtB;;;;;;;GAOG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,UAAU,GAGX,MAAM,gBAAgB,CAAA"}
|
package/dist/topics.d.ts
ADDED
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A topic's list of files — SPEC §6.14 "A file's list of other files"; record
|
|
3
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-topic-keeps-its-own-list-of-files.md
|
|
4
|
+
*
|
|
5
|
+
* A topic lists files from any Folder, one entry per file, by the file's id.
|
|
6
|
+
* An entry is a `kind:1851` change on the topic: `a` and `O` name the topic,
|
|
7
|
+
* `field` is `lists:<d>`, `value` is `true` or `false`, `h` is the topic's
|
|
8
|
+
* Folder, then `ts`, then `["o", <d>]` naming the listed file. The newest
|
|
9
|
+
* entry per topic and file counts (§6.3).
|
|
10
|
+
*
|
|
11
|
+
* `O` is the file the change is about and `o` another file it points at
|
|
12
|
+
* (why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-change-is-about-its-file-as-a-comment-is.md),
|
|
13
|
+
* so `#o` asks which topics list a file and `#O` asks what changed on a topic,
|
|
14
|
+
* and a file's own changes never include a topic's entry about it.
|
|
15
|
+
*
|
|
16
|
+
* Here rather than in each app because Peek, Ship and Leaf all add, remove
|
|
17
|
+
* and read entries, and a reader rule kept in one of them only is a list that
|
|
18
|
+
* reads differently in the next.
|
|
19
|
+
*
|
|
20
|
+
* ## What a listing is not
|
|
21
|
+
*
|
|
22
|
+
* It grants nothing: who reads the listed file is its own Folder's rule. It is
|
|
23
|
+
* not a mention, not a parent and not a Folder's listing, so Mentioned in, the
|
|
24
|
+
* archive chain and a Folder move all ignore it. It carries no `p`, so it adds
|
|
25
|
+
* nobody to the file (§11.8).
|
|
26
|
+
*/
|
|
27
|
+
import { type SignedEvent, type UnsignedEvent } from '@estiva-app/protocol';
|
|
28
|
+
import { type QueryFn } from './projection.js';
|
|
29
|
+
/**
|
|
30
|
+
* The file kinds a listed id is looked for under by default: topic, document,
|
|
31
|
+
* project, issue. Never a bare `#d`, since a Folder's `kind:39000` shares its
|
|
32
|
+
* uuid (§11.1). An app that knows more kinds from manifests passes them.
|
|
33
|
+
*/
|
|
34
|
+
export declare const LISTED_FILE_KINDS: readonly number[];
|
|
35
|
+
/** The field an entry for `file` sets: `lists:<d>`. */
|
|
36
|
+
export declare function listsField(file: string): string;
|
|
37
|
+
/** The file a list carries entries on, as a write needs it. */
|
|
38
|
+
export interface ListHolder {
|
|
39
|
+
/** Its address, `<kind>:<pubkey>:<d>`. */
|
|
40
|
+
address: string;
|
|
41
|
+
/** Its Folder, read from its root (`folderOf`), never the Folder it was opened from (§6.2). */
|
|
42
|
+
folder: string;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Put a file on a topic's list: `[kind:1851 lists:<d> = true]`, signed by
|
|
46
|
+
* whoever adds it. `file` is the listed file's id (its `d`), from any Folder.
|
|
47
|
+
*/
|
|
48
|
+
export declare function planListInTopic(pubkey: string, createdAtMs: number, args: {
|
|
49
|
+
topic: ListHolder;
|
|
50
|
+
file: string;
|
|
51
|
+
note?: string;
|
|
52
|
+
}): UnsignedEvent[];
|
|
53
|
+
/** Take a file off a topic's list: `[kind:1851 lists:<d> = false]`. {@link planListInTopic} in reverse. */
|
|
54
|
+
export declare function planRemoveFromTopic(pubkey: string, createdAtMs: number, args: {
|
|
55
|
+
topic: ListHolder;
|
|
56
|
+
file: string;
|
|
57
|
+
note?: string;
|
|
58
|
+
}): UnsignedEvent[];
|
|
59
|
+
/** Which topics list a file: every entry naming its id in `o`. Fold with {@link listEntries}. */
|
|
60
|
+
export declare function topicsOfFileFilter(file: string): Record<string, unknown>;
|
|
61
|
+
/** A topic's changes, its list entries among them: `#O` on its id. Fold with {@link listEntries}. */
|
|
62
|
+
export declare function topicListFilter(topic: string): Record<string, unknown>;
|
|
63
|
+
/** The newest entry for one list and one file. */
|
|
64
|
+
export interface ListEntry {
|
|
65
|
+
/** The address of the file keeping the list (a topic). */
|
|
66
|
+
list: string;
|
|
67
|
+
/** The listed file's id. */
|
|
68
|
+
file: string;
|
|
69
|
+
/** The entry's Folder: its first `h` with a value. */
|
|
70
|
+
folder: string;
|
|
71
|
+
/** `true` when the newest entry lists the file. */
|
|
72
|
+
listed: boolean;
|
|
73
|
+
event: SignedEvent;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* The newest entry per list and file, from any mix of changes: the reader
|
|
77
|
+
* rules of §6.14. A change counts as an entry only when its field is
|
|
78
|
+
* `lists:<d>`, one of its `o` tags is that same `<d>` (an `o` the field does
|
|
79
|
+
* not name is some other relation, a move's new parent for one), its `a`
|
|
80
|
+
* names a file whose `d` is its `O`, `<d>` is not that file itself, and it
|
|
81
|
+
* names a Folder. Anything else is skipped, not folded, so a malformed entry
|
|
82
|
+
* never hides a good one. A `value` other than exactly `true` does not list
|
|
83
|
+
* the file.
|
|
84
|
+
*
|
|
85
|
+
* `folderOfList` is §6.2's Folder check against each list's root, applied
|
|
86
|
+
* before the fold: an entry filed in any other Folder must not become the
|
|
87
|
+
* newest and hide the good one before it. A list it answers no Folder for (an
|
|
88
|
+
* unread root, or one naming none) keeps no entry. Without it the check is the
|
|
89
|
+
* caller's; {@link topicsOfFile} and {@link topicList} pass it.
|
|
90
|
+
*/
|
|
91
|
+
export declare function listEntries(events: readonly SignedEvent[], folderOfList?: (list: string) => string | null | undefined): ListEntry[];
|
|
92
|
+
/** A topic that lists a file. */
|
|
93
|
+
export interface FileTopic {
|
|
94
|
+
/** The topic's address. */
|
|
95
|
+
address: string;
|
|
96
|
+
/** The topic's root, as the reader read it. */
|
|
97
|
+
root: SignedEvent;
|
|
98
|
+
entry: ListEntry;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Which topics list a file — `{kinds:[1851], "#o":[<d>]}`, folded per topic.
|
|
102
|
+
*
|
|
103
|
+
* Keeps an entry only when its newest value lists the file, it is on a topic
|
|
104
|
+
* (only topics' lists are read, Miky 2026-10-30), the topic's root is one the
|
|
105
|
+
* reader can read (a deleted or unreadable topic drops out), and the entry is
|
|
106
|
+
* filed in the topic's own Folder (§6.2). Two reads: the entries, then the
|
|
107
|
+
* topics' roots.
|
|
108
|
+
*/
|
|
109
|
+
export declare function topicsOfFile(query: QueryFn, file: string): Promise<FileTopic[]>;
|
|
110
|
+
/** A file on a topic's list. */
|
|
111
|
+
export interface ListedFile {
|
|
112
|
+
/** The listed file's id. */
|
|
113
|
+
file: string;
|
|
114
|
+
/** Its address when exactly one file the reader can read holds the id, else `null`: not drawn, not counted. */
|
|
115
|
+
address: string | null;
|
|
116
|
+
entry: ListEntry;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* A topic's list, by the topic's address: its entries whose newest value
|
|
120
|
+
* lists the file, filed in the Folder the topic's root names (§6.2; read here,
|
|
121
|
+
* never taken from the caller), in no promised order (sort as the design
|
|
122
|
+
* says; `entry.event` carries the time), each id resolved over `fileKinds` by
|
|
123
|
+
* `#d`. A topic the reader cannot read, or whose root names no Folder, lists
|
|
124
|
+
* nothing. An id held by none the reader can read, or by two, resolves to
|
|
125
|
+
* `null`: a consumer draws and counts only the resolved ones (§3.2, the count
|
|
126
|
+
* is the disclosure).
|
|
127
|
+
*/
|
|
128
|
+
export declare function topicList(query: QueryFn, topic: string, options?: {
|
|
129
|
+
fileKinds?: readonly number[];
|
|
130
|
+
}): Promise<ListedFile[]>;
|
|
131
|
+
/**
|
|
132
|
+
* Many topics' lists at once, by address (TOP-4, Peek's Topics screen): the
|
|
133
|
+
* rules of {@link topicList} for each, in three requests whatever the number
|
|
134
|
+
* of topics (one more per 100 listed files): the roots, every topic's changes
|
|
135
|
+
* (one `#O` filter per topic) and the batched `#d` resolve, where one
|
|
136
|
+
* `topicList` per topic would be three requests each and trips a relay's rate
|
|
137
|
+
* limit at a few dozen topics. Every address asked for is a key; one that
|
|
138
|
+
* lists nothing, or that the reader cannot read, maps to `[]`.
|
|
139
|
+
*/
|
|
140
|
+
export declare function topicLists(query: QueryFn, topics: readonly string[], options?: {
|
|
141
|
+
fileKinds?: readonly number[];
|
|
142
|
+
}): Promise<Map<string, ListedFile[]>>;
|
|
143
|
+
//# sourceMappingURL=topics.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"topics.d.ts","sourceRoot":"","sources":["../src/topics.ts"],"names":[],"mappings":"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"}
|
package/dist/topics.js
ADDED
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A topic's list of files — SPEC §6.14 "A file's list of other files"; record
|
|
3
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-topic-keeps-its-own-list-of-files.md
|
|
4
|
+
*
|
|
5
|
+
* A topic lists files from any Folder, one entry per file, by the file's id.
|
|
6
|
+
* An entry is a `kind:1851` change on the topic: `a` and `O` name the topic,
|
|
7
|
+
* `field` is `lists:<d>`, `value` is `true` or `false`, `h` is the topic's
|
|
8
|
+
* Folder, then `ts`, then `["o", <d>]` naming the listed file. The newest
|
|
9
|
+
* entry per topic and file counts (§6.3).
|
|
10
|
+
*
|
|
11
|
+
* `O` is the file the change is about and `o` another file it points at
|
|
12
|
+
* (why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-change-is-about-its-file-as-a-comment-is.md),
|
|
13
|
+
* so `#o` asks which topics list a file and `#O` asks what changed on a topic,
|
|
14
|
+
* and a file's own changes never include a topic's entry about it.
|
|
15
|
+
*
|
|
16
|
+
* Here rather than in each app because Peek, Ship and Leaf all add, remove
|
|
17
|
+
* and read entries, and a reader rule kept in one of them only is a list that
|
|
18
|
+
* reads differently in the next.
|
|
19
|
+
*
|
|
20
|
+
* ## What a listing is not
|
|
21
|
+
*
|
|
22
|
+
* It grants nothing: who reads the listed file is its own Folder's rule. It is
|
|
23
|
+
* not a mention, not a parent and not a Folder's listing, so Mentioned in, the
|
|
24
|
+
* archive chain and a Folder move all ignore it. It carries no `p`, so it adds
|
|
25
|
+
* nobody to the file (§11.8).
|
|
26
|
+
*/
|
|
27
|
+
import {} from '@estiva-app/protocol';
|
|
28
|
+
import { byOrder } from '@estiva-app/conversation';
|
|
29
|
+
import { folderOf } from './projection.js';
|
|
30
|
+
const KIND_CHANGE = 1851;
|
|
31
|
+
/** The topic (bare file) kind: the only lists this stage reads (Miky, 2026-10-30). */
|
|
32
|
+
const KIND_TOPIC = 30840;
|
|
33
|
+
const KIND_FOLDER = 39000;
|
|
34
|
+
/** Listed ids resolved per request: 2 × this stays under a relay's usual `limit` cap. */
|
|
35
|
+
const RESOLVE_BATCH = 100;
|
|
36
|
+
/**
|
|
37
|
+
* The file kinds a listed id is looked for under by default: topic, document,
|
|
38
|
+
* project, issue. Never a bare `#d`, since a Folder's `kind:39000` shares its
|
|
39
|
+
* uuid (§11.1). An app that knows more kinds from manifests passes them.
|
|
40
|
+
*/
|
|
41
|
+
export const LISTED_FILE_KINDS = [30840, 30842, 30850, 30851];
|
|
42
|
+
const ADDRESS = /^(\d+):([0-9a-f]{64}):(.+)$/;
|
|
43
|
+
const FIELD_PREFIX = 'lists:';
|
|
44
|
+
/** The field an entry for `file` sets: `lists:<d>`. */
|
|
45
|
+
export function listsField(file) {
|
|
46
|
+
return `${FIELD_PREFIX}${file}`;
|
|
47
|
+
}
|
|
48
|
+
function entry(pubkey, createdAtMs, args) {
|
|
49
|
+
const holder = ADDRESS.exec(args.list.address);
|
|
50
|
+
if (!holder)
|
|
51
|
+
throw new Error(`not a file address: ${JSON.stringify(args.list.address)}`);
|
|
52
|
+
if (!args.list.folder)
|
|
53
|
+
throw new Error('a list entry names the Folder of the file that keeps the list');
|
|
54
|
+
if (!args.file || /\s/.test(args.file))
|
|
55
|
+
throw new Error(`not a file id: ${JSON.stringify(args.file)}`);
|
|
56
|
+
// A reader ignores a file on its own list (§6.14): refuse it here rather than publish an entry that shows nothing.
|
|
57
|
+
if (args.file === holder[3])
|
|
58
|
+
throw new Error('a file is not on its own list');
|
|
59
|
+
if (!Number.isSafeInteger(createdAtMs) || createdAtMs < 0)
|
|
60
|
+
throw new Error(`not epoch milliseconds: ${createdAtMs}`);
|
|
61
|
+
return {
|
|
62
|
+
pubkey,
|
|
63
|
+
created_at: Math.floor(createdAtMs / 1000),
|
|
64
|
+
kind: KIND_CHANGE,
|
|
65
|
+
tags: [
|
|
66
|
+
['a', args.list.address],
|
|
67
|
+
['O', holder[3]],
|
|
68
|
+
['field', listsField(args.file)],
|
|
69
|
+
['value', args.listed ? 'true' : 'false'],
|
|
70
|
+
['h', args.list.folder],
|
|
71
|
+
['ts', String(createdAtMs)],
|
|
72
|
+
['o', args.file],
|
|
73
|
+
],
|
|
74
|
+
// Empty unless the person wrote a note: each app says "added" and "removed" in its own words (§6.14).
|
|
75
|
+
content: args.note ?? '',
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Put a file on a topic's list: `[kind:1851 lists:<d> = true]`, signed by
|
|
80
|
+
* whoever adds it. `file` is the listed file's id (its `d`), from any Folder.
|
|
81
|
+
*/
|
|
82
|
+
export function planListInTopic(pubkey, createdAtMs, args) {
|
|
83
|
+
return [entry(pubkey, createdAtMs, { list: args.topic, file: args.file, listed: true, note: args.note })];
|
|
84
|
+
}
|
|
85
|
+
/** Take a file off a topic's list: `[kind:1851 lists:<d> = false]`. {@link planListInTopic} in reverse. */
|
|
86
|
+
export function planRemoveFromTopic(pubkey, createdAtMs, args) {
|
|
87
|
+
return [entry(pubkey, createdAtMs, { list: args.topic, file: args.file, listed: false, note: args.note })];
|
|
88
|
+
}
|
|
89
|
+
/** Which topics list a file: every entry naming its id in `o`. Fold with {@link listEntries}. */
|
|
90
|
+
export function topicsOfFileFilter(file) {
|
|
91
|
+
return { kinds: [KIND_CHANGE], '#o': [file] };
|
|
92
|
+
}
|
|
93
|
+
/** A topic's changes, its list entries among them: `#O` on its id. Fold with {@link listEntries}. */
|
|
94
|
+
export function topicListFilter(topic) {
|
|
95
|
+
const holder = ADDRESS.exec(topic);
|
|
96
|
+
return { kinds: [KIND_CHANGE], '#O': [holder ? holder[3] : topic] };
|
|
97
|
+
}
|
|
98
|
+
const tagOf = (event, name) => event.tags.find((t) => t[0] === name && t[1])?.[1];
|
|
99
|
+
/** The file an entry lists: the `<d>` of its `lists:<d>` field, or `null` for any other change. */
|
|
100
|
+
const listedIn = (event) => {
|
|
101
|
+
const field = tagOf(event, 'field');
|
|
102
|
+
return field?.startsWith(FIELD_PREFIX) ? field.slice(FIELD_PREFIX.length) || null : null;
|
|
103
|
+
};
|
|
104
|
+
/**
|
|
105
|
+
* The newest entry per list and file, from any mix of changes: the reader
|
|
106
|
+
* rules of §6.14. A change counts as an entry only when its field is
|
|
107
|
+
* `lists:<d>`, one of its `o` tags is that same `<d>` (an `o` the field does
|
|
108
|
+
* not name is some other relation, a move's new parent for one), its `a`
|
|
109
|
+
* names a file whose `d` is its `O`, `<d>` is not that file itself, and it
|
|
110
|
+
* names a Folder. Anything else is skipped, not folded, so a malformed entry
|
|
111
|
+
* never hides a good one. A `value` other than exactly `true` does not list
|
|
112
|
+
* the file.
|
|
113
|
+
*
|
|
114
|
+
* `folderOfList` is §6.2's Folder check against each list's root, applied
|
|
115
|
+
* before the fold: an entry filed in any other Folder must not become the
|
|
116
|
+
* newest and hide the good one before it. A list it answers no Folder for (an
|
|
117
|
+
* unread root, or one naming none) keeps no entry. Without it the check is the
|
|
118
|
+
* caller's; {@link topicsOfFile} and {@link topicList} pass it.
|
|
119
|
+
*/
|
|
120
|
+
export function listEntries(events, folderOfList) {
|
|
121
|
+
const newest = new Map();
|
|
122
|
+
for (const event of events) {
|
|
123
|
+
if (event.kind !== KIND_CHANGE)
|
|
124
|
+
continue;
|
|
125
|
+
const file = listedIn(event);
|
|
126
|
+
if (!file || !event.tags.some((t) => t[0] === 'o' && t[1] === file))
|
|
127
|
+
continue;
|
|
128
|
+
const list = tagOf(event, 'a');
|
|
129
|
+
const holder = list ? ADDRESS.exec(list) : null;
|
|
130
|
+
const folder = tagOf(event, 'h');
|
|
131
|
+
if (!holder || tagOf(event, 'O') !== holder[3] || file === holder[3] || !folder)
|
|
132
|
+
continue;
|
|
133
|
+
if (folderOfList && folderOfList(list) !== folder)
|
|
134
|
+
continue;
|
|
135
|
+
const key = `${list}\n${file}`;
|
|
136
|
+
const seen = newest.get(key);
|
|
137
|
+
if (!seen || byOrder(seen.event, event) < 0)
|
|
138
|
+
newest.set(key, { event, file });
|
|
139
|
+
}
|
|
140
|
+
return [...newest.values()].map(({ event, file }) => ({
|
|
141
|
+
list: tagOf(event, 'a'),
|
|
142
|
+
file,
|
|
143
|
+
folder: tagOf(event, 'h'),
|
|
144
|
+
listed: event.tags.find((t) => t[0] === 'value')?.[1] === 'true',
|
|
145
|
+
event,
|
|
146
|
+
}));
|
|
147
|
+
}
|
|
148
|
+
/** The roots of the given list addresses that the reader can read, by address. */
|
|
149
|
+
async function rootsOf(query, addresses) {
|
|
150
|
+
const byKindAuthor = new Map();
|
|
151
|
+
for (const address of addresses) {
|
|
152
|
+
const [, kind, pubkey, d] = ADDRESS.exec(address) ?? [];
|
|
153
|
+
if (!d)
|
|
154
|
+
continue;
|
|
155
|
+
const key = `${kind}:${pubkey}`;
|
|
156
|
+
const group = byKindAuthor.get(key) ?? { kind: Number(kind), pubkey, ds: [] };
|
|
157
|
+
group.ds.push(d);
|
|
158
|
+
byKindAuthor.set(key, group);
|
|
159
|
+
}
|
|
160
|
+
if (byKindAuthor.size === 0)
|
|
161
|
+
return new Map();
|
|
162
|
+
const filters = [...byKindAuthor.values()].map(({ kind, pubkey, ds }) => ({ kinds: [kind], authors: [pubkey], '#d': ds, limit: ds.length }));
|
|
163
|
+
const roots = new Map();
|
|
164
|
+
for (const root of await query(filters)) {
|
|
165
|
+
const address = `${root.kind}:${root.pubkey}:${tagOf(root, 'd') ?? ''}`;
|
|
166
|
+
const held = roots.get(address);
|
|
167
|
+
// Two versions of one record: NIP-01's later created_at, then the lower id (§6.3).
|
|
168
|
+
if (!held || root.created_at > held.created_at || (root.created_at === held.created_at && root.id < held.id))
|
|
169
|
+
roots.set(address, root);
|
|
170
|
+
}
|
|
171
|
+
return roots;
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Which topics list a file — `{kinds:[1851], "#o":[<d>]}`, folded per topic.
|
|
175
|
+
*
|
|
176
|
+
* Keeps an entry only when its newest value lists the file, it is on a topic
|
|
177
|
+
* (only topics' lists are read, Miky 2026-10-30), the topic's root is one the
|
|
178
|
+
* reader can read (a deleted or unreadable topic drops out), and the entry is
|
|
179
|
+
* filed in the topic's own Folder (§6.2). Two reads: the entries, then the
|
|
180
|
+
* topics' roots.
|
|
181
|
+
*/
|
|
182
|
+
export async function topicsOfFile(query, file) {
|
|
183
|
+
const isTopic = (entry) => entry.file === file && entry.list.startsWith(`${KIND_TOPIC}:`);
|
|
184
|
+
const events = await query([topicsOfFileFilter(file)]);
|
|
185
|
+
const lists = [...new Set(listEntries(events).filter(isTopic).map((entry) => entry.list))];
|
|
186
|
+
if (lists.length === 0)
|
|
187
|
+
return [];
|
|
188
|
+
const roots = await rootsOf(query, lists);
|
|
189
|
+
const folderOfList = (list) => {
|
|
190
|
+
const root = roots.get(list);
|
|
191
|
+
return root ? folderOf(root) : null;
|
|
192
|
+
};
|
|
193
|
+
return listEntries(events, folderOfList)
|
|
194
|
+
.filter((entry) => entry.listed && isTopic(entry))
|
|
195
|
+
.map((entry) => ({ address: entry.list, root: roots.get(entry.list), entry }));
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* A topic's list, by the topic's address: its entries whose newest value
|
|
199
|
+
* lists the file, filed in the Folder the topic's root names (§6.2; read here,
|
|
200
|
+
* never taken from the caller), in no promised order (sort as the design
|
|
201
|
+
* says; `entry.event` carries the time), each id resolved over `fileKinds` by
|
|
202
|
+
* `#d`. A topic the reader cannot read, or whose root names no Folder, lists
|
|
203
|
+
* nothing. An id held by none the reader can read, or by two, resolves to
|
|
204
|
+
* `null`: a consumer draws and counts only the resolved ones (§3.2, the count
|
|
205
|
+
* is the disclosure).
|
|
206
|
+
*/
|
|
207
|
+
export async function topicList(query, topic, options = {}) {
|
|
208
|
+
return (await topicLists(query, [topic], options)).get(topic) ?? [];
|
|
209
|
+
}
|
|
210
|
+
/**
|
|
211
|
+
* Many topics' lists at once, by address (TOP-4, Peek's Topics screen): the
|
|
212
|
+
* rules of {@link topicList} for each, in three requests whatever the number
|
|
213
|
+
* of topics (one more per 100 listed files): the roots, every topic's changes
|
|
214
|
+
* (one `#O` filter per topic) and the batched `#d` resolve, where one
|
|
215
|
+
* `topicList` per topic would be three requests each and trips a relay's rate
|
|
216
|
+
* limit at a few dozen topics. Every address asked for is a key; one that
|
|
217
|
+
* lists nothing, or that the reader cannot read, maps to `[]`.
|
|
218
|
+
*/
|
|
219
|
+
export async function topicLists(query, topics, options = {}) {
|
|
220
|
+
const asked = [...new Set(topics)];
|
|
221
|
+
const out = new Map(asked.map((topic) => [topic, []]));
|
|
222
|
+
if (asked.length === 0)
|
|
223
|
+
return out;
|
|
224
|
+
// One filter per topic in one request, so a relay's cap on an answer cuts no more than it would for that topic alone.
|
|
225
|
+
const [roots, events] = await Promise.all([rootsOf(query, asked), query(asked.map(topicListFilter))]);
|
|
226
|
+
const folderOfList = (list) => {
|
|
227
|
+
const root = out.has(list) ? roots.get(list) : undefined;
|
|
228
|
+
return root ? folderOf(root) : null;
|
|
229
|
+
};
|
|
230
|
+
const entries = listEntries(events, folderOfList)
|
|
231
|
+
.filter((entry) => entry.listed)
|
|
232
|
+
.sort((a, b) => byOrder(a.event, b.event));
|
|
233
|
+
if (entries.length === 0)
|
|
234
|
+
return out;
|
|
235
|
+
const resolved = await resolveIds(query, [...new Set(entries.map((entry) => entry.file))], options.fileKinds);
|
|
236
|
+
for (const entry of entries)
|
|
237
|
+
out.get(entry.list).push({ file: entry.file, address: resolved.get(entry.file) ?? null, entry });
|
|
238
|
+
return out;
|
|
239
|
+
}
|
|
240
|
+
/** Each id's address when exactly one file of `fileKinds` the reader can read holds it; an id held by none or by two is left out. */
|
|
241
|
+
async function resolveIds(query, ids, fileKinds) {
|
|
242
|
+
// Never a Folder's `39000`, which shares its uuid (§11.1): an id only a Folder holds resolves to nothing.
|
|
243
|
+
const kinds = (fileKinds ?? LISTED_FILE_KINDS).filter((kind) => kind !== KIND_FOLDER);
|
|
244
|
+
// Room for a second holder of every id, so two holders are seen as two; in
|
|
245
|
+
// batches, so a relay's cap on `limit` cannot cut a long list short.
|
|
246
|
+
const batches = [];
|
|
247
|
+
for (let i = 0; i < ids.length; i += RESOLVE_BATCH)
|
|
248
|
+
batches.push(ids.slice(i, i + RESOLVE_BATCH));
|
|
249
|
+
const answers = await Promise.all(batches.map((batch) => query([{ kinds, '#d': batch, limit: batch.length * 2 }])));
|
|
250
|
+
// An answer that filled its limit may have cut a second holder (newest
|
|
251
|
+
// first), and one holder would then pass for the only one: every id of that
|
|
252
|
+
// batch stays unresolved rather than drawn as somebody else's file.
|
|
253
|
+
const unsure = new Set(batches.flatMap((batch, i) => (answers[i].length >= batch.length * 2 ? batch : [])));
|
|
254
|
+
const holders = new Map();
|
|
255
|
+
for (const event of answers.flat()) {
|
|
256
|
+
const d = tagOf(event, 'd');
|
|
257
|
+
if (!d || !kinds.includes(event.kind))
|
|
258
|
+
continue;
|
|
259
|
+
const set = holders.get(d) ?? new Set();
|
|
260
|
+
set.add(`${event.kind}:${event.pubkey}`);
|
|
261
|
+
holders.set(d, set);
|
|
262
|
+
}
|
|
263
|
+
const out = new Map();
|
|
264
|
+
for (const [d, set] of holders)
|
|
265
|
+
if (set.size === 1 && !unsure.has(d))
|
|
266
|
+
out.set(d, `${[...set][0]}:${d}`);
|
|
267
|
+
return out;
|
|
268
|
+
}
|
|
269
|
+
//# sourceMappingURL=topics.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"topics.js","sourceRoot":"","sources":["../src/topics.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@estiva-app/interop",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.72.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
|
@@ -147,6 +147,28 @@ export {
|
|
|
147
147
|
type MoveRefusal,
|
|
148
148
|
} from './folders.js'
|
|
149
149
|
|
|
150
|
+
/**
|
|
151
|
+
* SPEC §6.14: a topic's list of files from any Folder, one `kind:1851` entry
|
|
152
|
+
* per file by its id. Plan an entry, read a topic's list, and ask which topics
|
|
153
|
+
* list a file (`#o`); a file's own changes (`#O`) never hold an entry.
|
|
154
|
+
*/
|
|
155
|
+
export {
|
|
156
|
+
planListInTopic,
|
|
157
|
+
planRemoveFromTopic,
|
|
158
|
+
topicsOfFile,
|
|
159
|
+
topicList,
|
|
160
|
+
topicLists,
|
|
161
|
+
topicsOfFileFilter,
|
|
162
|
+
topicListFilter,
|
|
163
|
+
listEntries,
|
|
164
|
+
listsField,
|
|
165
|
+
LISTED_FILE_KINDS,
|
|
166
|
+
type ListHolder,
|
|
167
|
+
type ListEntry,
|
|
168
|
+
type FileTopic,
|
|
169
|
+
type ListedFile,
|
|
170
|
+
} from './topics.js'
|
|
171
|
+
|
|
150
172
|
/**
|
|
151
173
|
* What an app link names, and where a file is mentioned — once for every app
|
|
152
174
|
* (SPEC §7.7, §13.1, §6.8; PEEKM-7). Each app passes its relay read; none
|
package/src/topics.ts
ADDED
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A topic's list of files — SPEC §6.14 "A file's list of other files"; record
|
|
3
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-topic-keeps-its-own-list-of-files.md
|
|
4
|
+
*
|
|
5
|
+
* A topic lists files from any Folder, one entry per file, by the file's id.
|
|
6
|
+
* An entry is a `kind:1851` change on the topic: `a` and `O` name the topic,
|
|
7
|
+
* `field` is `lists:<d>`, `value` is `true` or `false`, `h` is the topic's
|
|
8
|
+
* Folder, then `ts`, then `["o", <d>]` naming the listed file. The newest
|
|
9
|
+
* entry per topic and file counts (§6.3).
|
|
10
|
+
*
|
|
11
|
+
* `O` is the file the change is about and `o` another file it points at
|
|
12
|
+
* (why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-change-is-about-its-file-as-a-comment-is.md),
|
|
13
|
+
* so `#o` asks which topics list a file and `#O` asks what changed on a topic,
|
|
14
|
+
* and a file's own changes never include a topic's entry about it.
|
|
15
|
+
*
|
|
16
|
+
* Here rather than in each app because Peek, Ship and Leaf all add, remove
|
|
17
|
+
* and read entries, and a reader rule kept in one of them only is a list that
|
|
18
|
+
* reads differently in the next.
|
|
19
|
+
*
|
|
20
|
+
* ## What a listing is not
|
|
21
|
+
*
|
|
22
|
+
* It grants nothing: who reads the listed file is its own Folder's rule. It is
|
|
23
|
+
* not a mention, not a parent and not a Folder's listing, so Mentioned in, the
|
|
24
|
+
* archive chain and a Folder move all ignore it. It carries no `p`, so it adds
|
|
25
|
+
* nobody to the file (§11.8).
|
|
26
|
+
*/
|
|
27
|
+
import { type SignedEvent, type UnsignedEvent } from '@estiva-app/protocol'
|
|
28
|
+
import { byOrder } from '@estiva-app/conversation'
|
|
29
|
+
import { folderOf, type QueryFn } from './projection.js'
|
|
30
|
+
|
|
31
|
+
const KIND_CHANGE = 1851
|
|
32
|
+
/** The topic (bare file) kind: the only lists this stage reads (Miky, 2026-10-30). */
|
|
33
|
+
const KIND_TOPIC = 30840
|
|
34
|
+
const KIND_FOLDER = 39000
|
|
35
|
+
/** Listed ids resolved per request: 2 × this stays under a relay's usual `limit` cap. */
|
|
36
|
+
const RESOLVE_BATCH = 100
|
|
37
|
+
/**
|
|
38
|
+
* The file kinds a listed id is looked for under by default: topic, document,
|
|
39
|
+
* project, issue. Never a bare `#d`, since a Folder's `kind:39000` shares its
|
|
40
|
+
* uuid (§11.1). An app that knows more kinds from manifests passes them.
|
|
41
|
+
*/
|
|
42
|
+
export const LISTED_FILE_KINDS: readonly number[] = [30840, 30842, 30850, 30851]
|
|
43
|
+
|
|
44
|
+
const ADDRESS = /^(\d+):([0-9a-f]{64}):(.+)$/
|
|
45
|
+
const FIELD_PREFIX = 'lists:'
|
|
46
|
+
|
|
47
|
+
/** The field an entry for `file` sets: `lists:<d>`. */
|
|
48
|
+
export function listsField(file: string): string {
|
|
49
|
+
return `${FIELD_PREFIX}${file}`
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** The file a list carries entries on, as a write needs it. */
|
|
53
|
+
export interface ListHolder {
|
|
54
|
+
/** Its address, `<kind>:<pubkey>:<d>`. */
|
|
55
|
+
address: string
|
|
56
|
+
/** Its Folder, read from its root (`folderOf`), never the Folder it was opened from (§6.2). */
|
|
57
|
+
folder: string
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function entry(
|
|
61
|
+
pubkey: string,
|
|
62
|
+
createdAtMs: number,
|
|
63
|
+
args: { list: ListHolder; file: string; listed: boolean; note?: string },
|
|
64
|
+
): UnsignedEvent {
|
|
65
|
+
const holder = ADDRESS.exec(args.list.address)
|
|
66
|
+
if (!holder) throw new Error(`not a file address: ${JSON.stringify(args.list.address)}`)
|
|
67
|
+
if (!args.list.folder) throw new Error('a list entry names the Folder of the file that keeps the list')
|
|
68
|
+
if (!args.file || /\s/.test(args.file)) throw new Error(`not a file id: ${JSON.stringify(args.file)}`)
|
|
69
|
+
// A reader ignores a file on its own list (§6.14): refuse it here rather than publish an entry that shows nothing.
|
|
70
|
+
if (args.file === holder[3]) throw new Error('a file is not on its own list')
|
|
71
|
+
if (!Number.isSafeInteger(createdAtMs) || createdAtMs < 0) throw new Error(`not epoch milliseconds: ${createdAtMs}`)
|
|
72
|
+
return {
|
|
73
|
+
pubkey,
|
|
74
|
+
created_at: Math.floor(createdAtMs / 1000),
|
|
75
|
+
kind: KIND_CHANGE,
|
|
76
|
+
tags: [
|
|
77
|
+
['a', args.list.address],
|
|
78
|
+
['O', holder[3]],
|
|
79
|
+
['field', listsField(args.file)],
|
|
80
|
+
['value', args.listed ? 'true' : 'false'],
|
|
81
|
+
['h', args.list.folder],
|
|
82
|
+
['ts', String(createdAtMs)],
|
|
83
|
+
['o', args.file],
|
|
84
|
+
],
|
|
85
|
+
// Empty unless the person wrote a note: each app says "added" and "removed" in its own words (§6.14).
|
|
86
|
+
content: args.note ?? '',
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Put a file on a topic's list: `[kind:1851 lists:<d> = true]`, signed by
|
|
92
|
+
* whoever adds it. `file` is the listed file's id (its `d`), from any Folder.
|
|
93
|
+
*/
|
|
94
|
+
export function planListInTopic(
|
|
95
|
+
pubkey: string,
|
|
96
|
+
createdAtMs: number,
|
|
97
|
+
args: { topic: ListHolder; file: string; note?: string },
|
|
98
|
+
): UnsignedEvent[] {
|
|
99
|
+
return [entry(pubkey, createdAtMs, { list: args.topic, file: args.file, listed: true, note: args.note })]
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** Take a file off a topic's list: `[kind:1851 lists:<d> = false]`. {@link planListInTopic} in reverse. */
|
|
103
|
+
export function planRemoveFromTopic(
|
|
104
|
+
pubkey: string,
|
|
105
|
+
createdAtMs: number,
|
|
106
|
+
args: { topic: ListHolder; file: string; note?: string },
|
|
107
|
+
): UnsignedEvent[] {
|
|
108
|
+
return [entry(pubkey, createdAtMs, { list: args.topic, file: args.file, listed: false, note: args.note })]
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** Which topics list a file: every entry naming its id in `o`. Fold with {@link listEntries}. */
|
|
112
|
+
export function topicsOfFileFilter(file: string): Record<string, unknown> {
|
|
113
|
+
return { kinds: [KIND_CHANGE], '#o': [file] }
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** A topic's changes, its list entries among them: `#O` on its id. Fold with {@link listEntries}. */
|
|
117
|
+
export function topicListFilter(topic: string): Record<string, unknown> {
|
|
118
|
+
const holder = ADDRESS.exec(topic)
|
|
119
|
+
return { kinds: [KIND_CHANGE], '#O': [holder ? holder[3] : topic] }
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/** The newest entry for one list and one file. */
|
|
123
|
+
export interface ListEntry {
|
|
124
|
+
/** The address of the file keeping the list (a topic). */
|
|
125
|
+
list: string
|
|
126
|
+
/** The listed file's id. */
|
|
127
|
+
file: string
|
|
128
|
+
/** The entry's Folder: its first `h` with a value. */
|
|
129
|
+
folder: string
|
|
130
|
+
/** `true` when the newest entry lists the file. */
|
|
131
|
+
listed: boolean
|
|
132
|
+
event: SignedEvent
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
const tagOf = (event: Pick<SignedEvent, 'tags'>, name: string): string | undefined =>
|
|
136
|
+
event.tags.find((t) => t[0] === name && t[1])?.[1]
|
|
137
|
+
|
|
138
|
+
/** The file an entry lists: the `<d>` of its `lists:<d>` field, or `null` for any other change. */
|
|
139
|
+
const listedIn = (event: Pick<SignedEvent, 'tags'>): string | null => {
|
|
140
|
+
const field = tagOf(event, 'field')
|
|
141
|
+
return field?.startsWith(FIELD_PREFIX) ? field.slice(FIELD_PREFIX.length) || null : null
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* The newest entry per list and file, from any mix of changes: the reader
|
|
146
|
+
* rules of §6.14. A change counts as an entry only when its field is
|
|
147
|
+
* `lists:<d>`, one of its `o` tags is that same `<d>` (an `o` the field does
|
|
148
|
+
* not name is some other relation, a move's new parent for one), its `a`
|
|
149
|
+
* names a file whose `d` is its `O`, `<d>` is not that file itself, and it
|
|
150
|
+
* names a Folder. Anything else is skipped, not folded, so a malformed entry
|
|
151
|
+
* never hides a good one. A `value` other than exactly `true` does not list
|
|
152
|
+
* the file.
|
|
153
|
+
*
|
|
154
|
+
* `folderOfList` is §6.2's Folder check against each list's root, applied
|
|
155
|
+
* before the fold: an entry filed in any other Folder must not become the
|
|
156
|
+
* newest and hide the good one before it. A list it answers no Folder for (an
|
|
157
|
+
* unread root, or one naming none) keeps no entry. Without it the check is the
|
|
158
|
+
* caller's; {@link topicsOfFile} and {@link topicList} pass it.
|
|
159
|
+
*/
|
|
160
|
+
export function listEntries(
|
|
161
|
+
events: readonly SignedEvent[],
|
|
162
|
+
folderOfList?: (list: string) => string | null | undefined,
|
|
163
|
+
): ListEntry[] {
|
|
164
|
+
const newest = new Map<string, { event: SignedEvent; file: string }>()
|
|
165
|
+
for (const event of events) {
|
|
166
|
+
if (event.kind !== KIND_CHANGE) continue
|
|
167
|
+
const file = listedIn(event)
|
|
168
|
+
if (!file || !event.tags.some((t) => t[0] === 'o' && t[1] === file)) continue
|
|
169
|
+
const list = tagOf(event, 'a')
|
|
170
|
+
const holder = list ? ADDRESS.exec(list) : null
|
|
171
|
+
const folder = tagOf(event, 'h')
|
|
172
|
+
if (!holder || tagOf(event, 'O') !== holder[3] || file === holder[3] || !folder) continue
|
|
173
|
+
if (folderOfList && folderOfList(list!) !== folder) continue
|
|
174
|
+
const key = `${list}\n${file}`
|
|
175
|
+
const seen = newest.get(key)
|
|
176
|
+
if (!seen || byOrder(seen.event, event) < 0) newest.set(key, { event, file })
|
|
177
|
+
}
|
|
178
|
+
return [...newest.values()].map(({ event, file }) => ({
|
|
179
|
+
list: tagOf(event, 'a')!,
|
|
180
|
+
file,
|
|
181
|
+
folder: tagOf(event, 'h')!,
|
|
182
|
+
listed: event.tags.find((t) => t[0] === 'value')?.[1] === 'true',
|
|
183
|
+
event,
|
|
184
|
+
}))
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** The roots of the given list addresses that the reader can read, by address. */
|
|
188
|
+
async function rootsOf(query: QueryFn, addresses: readonly string[]): Promise<Map<string, SignedEvent>> {
|
|
189
|
+
const byKindAuthor = new Map<string, { kind: number; pubkey: string; ds: string[] }>()
|
|
190
|
+
for (const address of addresses) {
|
|
191
|
+
const [, kind, pubkey, d] = ADDRESS.exec(address) ?? []
|
|
192
|
+
if (!d) continue
|
|
193
|
+
const key = `${kind}:${pubkey}`
|
|
194
|
+
const group = byKindAuthor.get(key) ?? { kind: Number(kind), pubkey, ds: [] }
|
|
195
|
+
group.ds.push(d)
|
|
196
|
+
byKindAuthor.set(key, group)
|
|
197
|
+
}
|
|
198
|
+
if (byKindAuthor.size === 0) return new Map()
|
|
199
|
+
const filters = [...byKindAuthor.values()].map(({ kind, pubkey, ds }) => ({ kinds: [kind], authors: [pubkey], '#d': ds, limit: ds.length }))
|
|
200
|
+
const roots = new Map<string, SignedEvent>()
|
|
201
|
+
for (const root of await query(filters)) {
|
|
202
|
+
const address = `${root.kind}:${root.pubkey}:${tagOf(root, 'd') ?? ''}`
|
|
203
|
+
const held = roots.get(address)
|
|
204
|
+
// Two versions of one record: NIP-01's later created_at, then the lower id (§6.3).
|
|
205
|
+
if (!held || root.created_at > held.created_at || (root.created_at === held.created_at && root.id < held.id)) roots.set(address, root)
|
|
206
|
+
}
|
|
207
|
+
return roots
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/** A topic that lists a file. */
|
|
211
|
+
export interface FileTopic {
|
|
212
|
+
/** The topic's address. */
|
|
213
|
+
address: string
|
|
214
|
+
/** The topic's root, as the reader read it. */
|
|
215
|
+
root: SignedEvent
|
|
216
|
+
entry: ListEntry
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* Which topics list a file — `{kinds:[1851], "#o":[<d>]}`, folded per topic.
|
|
221
|
+
*
|
|
222
|
+
* Keeps an entry only when its newest value lists the file, it is on a topic
|
|
223
|
+
* (only topics' lists are read, Miky 2026-10-30), the topic's root is one the
|
|
224
|
+
* reader can read (a deleted or unreadable topic drops out), and the entry is
|
|
225
|
+
* filed in the topic's own Folder (§6.2). Two reads: the entries, then the
|
|
226
|
+
* topics' roots.
|
|
227
|
+
*/
|
|
228
|
+
export async function topicsOfFile(query: QueryFn, file: string): Promise<FileTopic[]> {
|
|
229
|
+
const isTopic = (entry: ListEntry) => entry.file === file && entry.list.startsWith(`${KIND_TOPIC}:`)
|
|
230
|
+
const events = await query([topicsOfFileFilter(file)])
|
|
231
|
+
const lists = [...new Set(listEntries(events).filter(isTopic).map((entry) => entry.list))]
|
|
232
|
+
if (lists.length === 0) return []
|
|
233
|
+
const roots = await rootsOf(query, lists)
|
|
234
|
+
const folderOfList = (list: string) => {
|
|
235
|
+
const root = roots.get(list)
|
|
236
|
+
return root ? folderOf(root) : null
|
|
237
|
+
}
|
|
238
|
+
return listEntries(events, folderOfList)
|
|
239
|
+
.filter((entry) => entry.listed && isTopic(entry))
|
|
240
|
+
.map((entry) => ({ address: entry.list, root: roots.get(entry.list)!, entry }))
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/** A file on a topic's list. */
|
|
244
|
+
export interface ListedFile {
|
|
245
|
+
/** The listed file's id. */
|
|
246
|
+
file: string
|
|
247
|
+
/** Its address when exactly one file the reader can read holds the id, else `null`: not drawn, not counted. */
|
|
248
|
+
address: string | null
|
|
249
|
+
entry: ListEntry
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* A topic's list, by the topic's address: its entries whose newest value
|
|
254
|
+
* lists the file, filed in the Folder the topic's root names (§6.2; read here,
|
|
255
|
+
* never taken from the caller), in no promised order (sort as the design
|
|
256
|
+
* says; `entry.event` carries the time), each id resolved over `fileKinds` by
|
|
257
|
+
* `#d`. A topic the reader cannot read, or whose root names no Folder, lists
|
|
258
|
+
* nothing. An id held by none the reader can read, or by two, resolves to
|
|
259
|
+
* `null`: a consumer draws and counts only the resolved ones (§3.2, the count
|
|
260
|
+
* is the disclosure).
|
|
261
|
+
*/
|
|
262
|
+
export async function topicList(
|
|
263
|
+
query: QueryFn,
|
|
264
|
+
topic: string,
|
|
265
|
+
options: { fileKinds?: readonly number[] } = {},
|
|
266
|
+
): Promise<ListedFile[]> {
|
|
267
|
+
return (await topicLists(query, [topic], options)).get(topic) ?? []
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
/**
|
|
271
|
+
* Many topics' lists at once, by address (TOP-4, Peek's Topics screen): the
|
|
272
|
+
* rules of {@link topicList} for each, in three requests whatever the number
|
|
273
|
+
* of topics (one more per 100 listed files): the roots, every topic's changes
|
|
274
|
+
* (one `#O` filter per topic) and the batched `#d` resolve, where one
|
|
275
|
+
* `topicList` per topic would be three requests each and trips a relay's rate
|
|
276
|
+
* limit at a few dozen topics. Every address asked for is a key; one that
|
|
277
|
+
* lists nothing, or that the reader cannot read, maps to `[]`.
|
|
278
|
+
*/
|
|
279
|
+
export async function topicLists(
|
|
280
|
+
query: QueryFn,
|
|
281
|
+
topics: readonly string[],
|
|
282
|
+
options: { fileKinds?: readonly number[] } = {},
|
|
283
|
+
): Promise<Map<string, ListedFile[]>> {
|
|
284
|
+
const asked = [...new Set(topics)]
|
|
285
|
+
const out = new Map<string, ListedFile[]>(asked.map((topic) => [topic, []]))
|
|
286
|
+
if (asked.length === 0) return out
|
|
287
|
+
// One filter per topic in one request, so a relay's cap on an answer cuts no more than it would for that topic alone.
|
|
288
|
+
const [roots, events] = await Promise.all([rootsOf(query, asked), query(asked.map(topicListFilter))])
|
|
289
|
+
const folderOfList = (list: string) => {
|
|
290
|
+
const root = out.has(list) ? roots.get(list) : undefined
|
|
291
|
+
return root ? folderOf(root) : null
|
|
292
|
+
}
|
|
293
|
+
const entries = listEntries(events, folderOfList)
|
|
294
|
+
.filter((entry) => entry.listed)
|
|
295
|
+
.sort((a, b) => byOrder(a.event, b.event))
|
|
296
|
+
if (entries.length === 0) return out
|
|
297
|
+
const resolved = await resolveIds(query, [...new Set(entries.map((entry) => entry.file))], options.fileKinds)
|
|
298
|
+
for (const entry of entries) out.get(entry.list)!.push({ file: entry.file, address: resolved.get(entry.file) ?? null, entry })
|
|
299
|
+
return out
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
/** Each id's address when exactly one file of `fileKinds` the reader can read holds it; an id held by none or by two is left out. */
|
|
303
|
+
async function resolveIds(query: QueryFn, ids: readonly string[], fileKinds?: readonly number[]): Promise<Map<string, string>> {
|
|
304
|
+
// Never a Folder's `39000`, which shares its uuid (§11.1): an id only a Folder holds resolves to nothing.
|
|
305
|
+
const kinds = (fileKinds ?? LISTED_FILE_KINDS).filter((kind) => kind !== KIND_FOLDER)
|
|
306
|
+
// Room for a second holder of every id, so two holders are seen as two; in
|
|
307
|
+
// batches, so a relay's cap on `limit` cannot cut a long list short.
|
|
308
|
+
const batches: string[][] = []
|
|
309
|
+
for (let i = 0; i < ids.length; i += RESOLVE_BATCH) batches.push(ids.slice(i, i + RESOLVE_BATCH))
|
|
310
|
+
const answers = await Promise.all(batches.map((batch) => query([{ kinds, '#d': batch, limit: batch.length * 2 }])))
|
|
311
|
+
// An answer that filled its limit may have cut a second holder (newest
|
|
312
|
+
// first), and one holder would then pass for the only one: every id of that
|
|
313
|
+
// batch stays unresolved rather than drawn as somebody else's file.
|
|
314
|
+
const unsure = new Set(batches.flatMap((batch, i) => (answers[i].length >= batch.length * 2 ? batch : [])))
|
|
315
|
+
const holders = new Map<string, Set<string>>()
|
|
316
|
+
for (const event of answers.flat()) {
|
|
317
|
+
const d = tagOf(event, 'd')
|
|
318
|
+
if (!d || !kinds.includes(event.kind)) continue
|
|
319
|
+
const set = holders.get(d) ?? new Set<string>()
|
|
320
|
+
set.add(`${event.kind}:${event.pubkey}`)
|
|
321
|
+
holders.set(d, set)
|
|
322
|
+
}
|
|
323
|
+
const out = new Map<string, string>()
|
|
324
|
+
for (const [d, set] of holders) if (set.size === 1 && !unsure.has(d)) out.set(d, `${[...set][0]}:${d}`)
|
|
325
|
+
return out
|
|
326
|
+
}
|