@estiva-app/interop 0.46.0 → 0.48.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 +49 -0
- package/README.md +43 -15
- package/dist/folders.d.ts +144 -67
- package/dist/folders.d.ts.map +1 -1
- package/dist/folders.js +162 -62
- package/dist/folders.js.map +1 -1
- package/dist/index.d.ts +6 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -5
- package/dist/index.js.map +1 -1
- package/dist/projection.d.ts +23 -7
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +148 -45
- package/dist/projection.js.map +1 -1
- package/package.json +1 -1
- package/src/folders.ts +197 -72
- package/src/index.ts +8 -4
- package/src/projection.ts +175 -46
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,55 @@ 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.48.0 — 2026-10-05
|
|
10
|
+
|
|
11
|
+
**Manifests: how `input.type: "pubkey"` is read changes** (SPEC §7.3, SHA-28).
|
|
12
|
+
It names a person, so the events built from it now carry `["p", <key>]`, which
|
|
13
|
+
is what makes that person a member of the file (§11.8). Ship's published `assign`
|
|
14
|
+
and `set-lead` declare it already: built here, they now carry the `p` that
|
|
15
|
+
Ship's own writer always added. No signature moved; needs protocol 0.24.0 and
|
|
16
|
+
conversation 0.5.0, unchanged.
|
|
17
|
+
|
|
18
|
+
- **Changed: a change whose input is `pubkey`** adds `["p", value]` after `ts`.
|
|
19
|
+
`''` (clearing it) adds none.
|
|
20
|
+
- **Changed: a creation** adds one `["p", key]` per distinct non-empty property
|
|
21
|
+
of `type: "pubkey"`, beside the property's own tag.
|
|
22
|
+
- **New refusal:** a `pubkey` value that is neither `''` nor 64 lowercase hex,
|
|
23
|
+
such as an npub or upper-case hex, returns a string naming the action instead
|
|
24
|
+
of being written without the `p`.
|
|
25
|
+
|
|
26
|
+
## 0.47.0 — 2026-10-03
|
|
27
|
+
|
|
28
|
+
**Manifests: nothing changes.** Every published manifest means what it meant.
|
|
29
|
+
**Folder writes and reads change to SPEC §3.3 / §3.2** (MAN-17), and three
|
|
30
|
+
planner signatures moved. Needs protocol 0.24.0 and conversation 0.5.0,
|
|
31
|
+
unchanged.
|
|
32
|
+
|
|
33
|
+
- **New: `planDeleteFolder(pubkey, ms, { folder })`** = `[kind:9008]`. The
|
|
34
|
+
relay refuses it while the Folder holds a file, naming the count; show that.
|
|
35
|
+
- **Changed: `planMoveFile` moves a subtree, and refuses a private move.** It
|
|
36
|
+
takes `{ file, from, to, listing }` instead of `{ address, … }`: `file` is a
|
|
37
|
+
`MovableFile` (any `ForeignObject`), `listing` the source's
|
|
38
|
+
`FolderContents.files` — required, `null` only for a file nothing can sit
|
|
39
|
+
beneath. The plan is one `kind:1852 add` in the target naming
|
|
40
|
+
the file and every file listed beneath it, then one `remove` naming the same
|
|
41
|
+
set in the source (Miky, 2026-10-03), and returns `moved`. New refusal
|
|
42
|
+
`target-is-private`: the target's `kind:39000` is private and a moved file's
|
|
43
|
+
`h` is another channel or absent. New export `listedBeneath(listing, file)`.
|
|
44
|
+
- **Changed: no `kind:1852` carries a `name`.** `planCreateFolder` sends a bare
|
|
45
|
+
`add`; `planRenameFolder` is the `kind:9002` alone and no longer takes
|
|
46
|
+
`hasState`.
|
|
47
|
+
- **Changed: `planArchiveFolder` always publishes into the Folder's own `h`**;
|
|
48
|
+
`into` is gone.
|
|
49
|
+
- **Changed: a Folder's title is its `kind:39000` name** in `listFolders` and
|
|
50
|
+
`resolveFolderContents`; a `name` on the state is no longer read.
|
|
51
|
+
- **Changed: a Folder's own archive counts only from an owner or admin** on its
|
|
52
|
+
relay-signed `kind:39001`, published in its own `h`. `FolderSummary` gains
|
|
53
|
+
`admins` (offer Archive only to them) and `private`. `listFolders` and
|
|
54
|
+
`resolveFolderContents` each ask for the `kind:39001` in the request they
|
|
55
|
+
already make.
|
|
56
|
+
- The bare file's action descriptions say "Folder", not "team".
|
|
57
|
+
|
|
9
58
|
## 0.46.0 — 2026-10-03
|
|
10
59
|
|
|
11
60
|
**Manifests: nothing changes.** Every published manifest means what it meant,
|
package/README.md
CHANGED
|
@@ -191,7 +191,10 @@ and such an action carries `declaredBy`. Build it with
|
|
|
191
191
|
|
|
192
192
|
**Check the string.** `buildActionEvent` returns `UnsignedActionEvent | string`,
|
|
193
193
|
and the string is why it refused — an undeclared field, a required one left
|
|
194
|
-
empty, a value outside the declared vocabulary
|
|
194
|
+
empty, a value outside the declared vocabulary, a person (`type: "pubkey"`)
|
|
195
|
+
that is not `''` or 64 lowercase hex. A person it accepts is also written as
|
|
196
|
+
`["p", <key>]`, which is what makes them a member of the file (SPEC §7.3,
|
|
197
|
+
§11.8). Treat the result as an event
|
|
195
198
|
without checking and you will sign the refusal.
|
|
196
199
|
|
|
197
200
|
Everything it needs is passed in rather than reached for: this package opens no
|
|
@@ -583,7 +586,7 @@ explaining a short list should read this field.
|
|
|
583
586
|
```ts
|
|
584
587
|
import { listFolders, topLevelFolders } from '@estiva-app/interop'
|
|
585
588
|
|
|
586
|
-
const folders = await listFolders(query) // { id, name, hasState, listedIn?, addresses?, channel?, archived? }[]
|
|
589
|
+
const folders = await listFolders(query) // { id, name, hasState, private?, admins?, listedIn?, addresses?, channel?, archived? }[]
|
|
587
590
|
const teams = topLevelFolders(folders) // state, nothing lists it, not archived
|
|
588
591
|
```
|
|
589
592
|
|
|
@@ -612,26 +615,48 @@ A channel with state of its own is a Folder, and only states place it.
|
|
|
612
615
|
```ts
|
|
613
616
|
import { planMoveFile } from '@estiva-app/interop'
|
|
614
617
|
|
|
618
|
+
const here = await resolveFolderContents(from.id, query)
|
|
615
619
|
const plan = planMoveFile(me, Date.now(), {
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
620
|
+
file, // a ForeignObject from `here.files`
|
|
621
|
+
listing: here.files, // what is listed beneath `file` moves with it
|
|
622
|
+
from: { id: here.id, hasState: here.hasState }, // from a read, never a guess
|
|
623
|
+
to: { id: there.id, hasState: there.hasState, private: there.private },
|
|
619
624
|
})
|
|
620
|
-
if (!plan.ok) return plan.reason
|
|
621
|
-
for (const event of plan.events) {
|
|
625
|
+
if (!plan.ok) return plan.reason // 'source-has-no-state' | 'target-has-no-state' | 'target-is-private'
|
|
626
|
+
for (const event of plan.events) { // publish in order; stop at the first refusal
|
|
622
627
|
if (!(await publish(await sign(event))).ok) break
|
|
623
628
|
}
|
|
624
629
|
```
|
|
625
630
|
|
|
626
|
-
|
|
627
|
-
`
|
|
628
|
-
|
|
631
|
+
The planners are SPEC §3.3's operations — `planCreateFolder`,
|
|
632
|
+
`planRenameFolder`, `planArchiveFolder`, `planDeleteFolder`, `planPlaceFile`,
|
|
633
|
+
`planUnlistFile` and `planMoveFile` — and return **unsigned** events in publish
|
|
634
|
+
order. Signing and publishing stay yours.
|
|
629
635
|
|
|
630
|
-
|
|
631
|
-
|
|
636
|
+
A move is one `kind:1852 add` in the target naming the file and every file
|
|
637
|
+
listed beneath it (`listedBeneath`), then one `remove` naming the same set in
|
|
638
|
+
the source, so a failure between the two leaves the whole subtree in both
|
|
639
|
+
Folders and never splits it. Into a private Folder it is refused when any moved
|
|
640
|
+
file's `h` is another channel, or absent: a listing never changes who can read
|
|
641
|
+
a file (§3.1).
|
|
642
|
+
|
|
643
|
+
No command carries a name: the title is the `kind:39000`'s, so a rename is the
|
|
644
|
+
`kind:9002` alone and `listFolders` reads the title from the channel.
|
|
645
|
+
|
|
646
|
+
Place, unlist and move take `hasState`, because the relay computes a folder's
|
|
647
|
+
next state from its current one and a group with no `kind:30890` has none: a
|
|
632
648
|
`kind:1852` against it emits state listing only what the command named, and
|
|
633
|
-
everything filed in it by `h` stops being listed. So
|
|
634
|
-
|
|
649
|
+
everything filed in it by `h` stops being listed. So place and unlist send no
|
|
650
|
+
command to such a group, and a move into or out of one is refused.
|
|
651
|
+
|
|
652
|
+
`listing` is required; pass `null` only for a file nothing can sit beneath, so
|
|
653
|
+
a move that leaves sub-files behind is never an accident.
|
|
654
|
+
|
|
655
|
+
Delete is for an empty Folder. The relay refuses a `kind:9008` while the Folder
|
|
656
|
+
holds a file, with a reason naming the count (`folder holds 2 file(s) …`).
|
|
657
|
+
Its wording is the relay's. Take the count and say it in your app's words
|
|
658
|
+
("This Folder still has 2 files. Move or delete them first."), as you would
|
|
659
|
+
for `target-is-private`.
|
|
635
660
|
|
|
636
661
|
### Archiving anything (0.37.0)
|
|
637
662
|
|
|
@@ -650,7 +675,10 @@ if (isArchived(opened)) showBanner(opened.archived) // { by, at, resolutio
|
|
|
650
675
|
One field for every file, whatever its kind: a change setting `archived` to
|
|
651
676
|
`'true'` on the file's address archives it and an empty value restores it. It
|
|
652
677
|
is a change, so anyone who may write in the Folder may, and the change's
|
|
653
|
-
`content` is the resolution a person gave.
|
|
678
|
+
`content` is the resolution a person gave. **A Folder itself is the
|
|
679
|
+
exception** (SPEC §3.2): its archive counts only from an owner or admin on its
|
|
680
|
+
`kind:39001`, published in its own `h` — offer Archive on a Folder only to
|
|
681
|
+
`folder.admins`.
|
|
654
682
|
|
|
655
683
|
**The cascade is read, never written.** A Folder's contents leave out an
|
|
656
684
|
archived file and everything under it — an issue with its project, a sub-topic
|
package/dist/folders.d.ts
CHANGED
|
@@ -1,13 +1,21 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Folder writes, planned —
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
2
|
+
* Folder writes, planned — SPEC §3.3. Every app gets exactly these operations,
|
|
3
|
+
* and these planners are the reference implementation: an app that does not
|
|
4
|
+
* call them MUST produce the same events in the same order.
|
|
5
|
+
*
|
|
6
|
+
* Every change to a Folder is one or more events published in order. Where a
|
|
7
|
+
* planner lists a file, it depends on one fact the relay will not check for
|
|
8
|
+
* you: **whether the Folder has a `kind:30890` yet.** `handle_folder_command`
|
|
9
|
+
* computes the next state from the existing one, and a group with no state has
|
|
10
|
+
* none — so any `kind:1852` against it emits state listing only what that
|
|
11
|
+
* command named, and everything filed there by `h` stops being listed on every
|
|
12
|
+
* surface (peek#192). Nothing fails; the group just looks emptied.
|
|
13
|
+
*
|
|
14
|
+
* A group with no state is not a Folder (SPEC §3), and §3.3's operations are
|
|
15
|
+
* not run on one. The `hasState: false` branches below are kept for §7.3's
|
|
16
|
+
* `listed` rule, which still applies to an object filed in such a group: a
|
|
17
|
+
* file placed or unlisted there is reached by containment and needs no
|
|
18
|
+
* command.
|
|
11
19
|
*
|
|
12
20
|
* That is why these are here rather than in each app. Peek learned it once per
|
|
13
21
|
* writer — rename, start a topic, delete a file — and its move never learned it
|
|
@@ -27,23 +35,40 @@
|
|
|
27
35
|
* assumes the earlier ones were accepted. What a refusal part-way through
|
|
28
36
|
* *means* — "created but not listed", "added but still in the old one" — is
|
|
29
37
|
* each app's to say, and the index of the refused event is enough to say it.
|
|
38
|
+
*
|
|
39
|
+
* ## A command never carries a name
|
|
40
|
+
*
|
|
41
|
+
* A Folder's title is the `name` of its `kind:39000` and only that (§3.2). The
|
|
42
|
+
* relay lets only the channel's owners and admins change that, while any
|
|
43
|
+
* member may send a `kind:1852` — so a name on a command would let anyone
|
|
44
|
+
* retitle the Folder for every reader that believed it.
|
|
30
45
|
*/
|
|
31
46
|
import { type ChannelVisibility, type UnsignedEvent } from '@estiva-app/protocol';
|
|
32
|
-
/** A Folder as a write needs it: which one, and
|
|
47
|
+
/** A Folder as a write needs it: which one, and what a read said about it. */
|
|
33
48
|
export interface FolderRef {
|
|
34
49
|
id: string;
|
|
35
50
|
/** `FolderSummary.hasState` / `FolderContents.hasState`, from a read — never a guess. */
|
|
36
51
|
hasState: boolean;
|
|
52
|
+
/**
|
|
53
|
+
* `FolderSummary.private`: the Folder's relay-signed `kind:39000` carries
|
|
54
|
+
* `["private"]`. Only a move *into* the Folder reads it.
|
|
55
|
+
*/
|
|
56
|
+
private?: boolean;
|
|
37
57
|
}
|
|
38
58
|
/**
|
|
39
|
-
* Create a Folder: `[kind:9007, kind:1852 add
|
|
59
|
+
* Create a Folder: `[kind:9007 + name, kind:1852 add]`.
|
|
40
60
|
*
|
|
41
|
-
* The channel first, because a Folder *is* one (
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
* and a stateless Folder is indistinguishable from a bare channel. Safe here
|
|
61
|
+
* The channel first, because a Folder *is* one (§3). Then a command listing
|
|
62
|
+
* nothing, so the Folder **has state from birth** — a group without a
|
|
63
|
+
* `kind:30890` is not a Folder, and a listing would never show it. Safe here
|
|
45
64
|
* and nowhere else without `hasState`: the channel was created by the first
|
|
46
|
-
* event, so nothing is filed in it to hide.
|
|
65
|
+
* event, so nothing is filed in it to hide. The relay emits state for an `add`
|
|
66
|
+
* with no addresses and no name.
|
|
67
|
+
*
|
|
68
|
+
* `folder` MUST be a uuid nobody has used. The relay answers a `kind:9007` for
|
|
69
|
+
* an existing channel with `duplicate:`, which the bridge reports as accepted,
|
|
70
|
+
* so a reused id would send the `add` to a group that may hold files and no
|
|
71
|
+
* state — and empty it on every surface.
|
|
47
72
|
*/
|
|
48
73
|
export declare function planCreateFolder(pubkey: string, createdAtMs: number, args: {
|
|
49
74
|
folder: string;
|
|
@@ -51,27 +76,41 @@ export declare function planCreateFolder(pubkey: string, createdAtMs: number, ar
|
|
|
51
76
|
visibility?: ChannelVisibility;
|
|
52
77
|
}): UnsignedEvent[];
|
|
53
78
|
/**
|
|
54
|
-
* Rename a Folder: `[kind:9002
|
|
79
|
+
* Rename a Folder: `[kind:9002]`, and nothing else.
|
|
55
80
|
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
* changes; `set` would empty it and there is no `rename` op. With no state
|
|
60
|
-
* there is only the channel to rename, and a command would empty the Folder.
|
|
81
|
+
* The title is the channel's name (§3.2), so the channel is the only home to
|
|
82
|
+
* write. The relay refuses it to anybody but the channel's owners and admins.
|
|
83
|
+
* A name left on an older state by a command is never shown.
|
|
61
84
|
*/
|
|
62
85
|
export declare function planRenameFolder(pubkey: string, createdAtMs: number, args: {
|
|
63
86
|
folder: string;
|
|
64
87
|
name: string;
|
|
65
|
-
|
|
88
|
+
}): UnsignedEvent[];
|
|
89
|
+
/**
|
|
90
|
+
* Delete a Folder: `[kind:9008]`.
|
|
91
|
+
*
|
|
92
|
+
* **For an empty Folder.** The relay refuses while the Folder holds a file —
|
|
93
|
+
* a `30840`, `30850` or `30851` under its `h`, or any address its listing
|
|
94
|
+
* names — with a reason naming the count ("folder holds N file(s) … remove
|
|
95
|
+
* them first"), and a consumer shows that reason. A file moved out keeps its
|
|
96
|
+
* `h`, so a Folder whose listing looks empty can still refuse.
|
|
97
|
+
*
|
|
98
|
+
* An accepted delete hides **every** event under the `h`, its conversation
|
|
99
|
+
* included, for good. Archive ({@link planArchiveFolder}) is the reversible way
|
|
100
|
+
* to put a Folder away. Folders never nest, so there is no container to unlist
|
|
101
|
+
* it from.
|
|
102
|
+
*/
|
|
103
|
+
export declare function planDeleteFolder(pubkey: string, createdAtMs: number, args: {
|
|
104
|
+
folder: string;
|
|
66
105
|
}): UnsignedEvent[];
|
|
67
106
|
/**
|
|
68
107
|
* List a file that was just published into a Folder: `[kind:1852 add]` if the
|
|
69
108
|
* Folder has state, otherwise nothing.
|
|
70
109
|
*
|
|
71
|
-
* A Folder
|
|
72
|
-
*
|
|
73
|
-
* Publish the file first: a refused `add` then leaves a file
|
|
74
|
-
* is reachable, rather than a listing that points at nothing.
|
|
110
|
+
* A Folder with state lists only what its state names, so it needs the `add`.
|
|
111
|
+
* A group with no state lists the file by containment the moment its `h` is
|
|
112
|
+
* stored (§7.3). Publish the file first: a refused `add` then leaves a file
|
|
113
|
+
* that exists and is reachable, rather than a listing that points at nothing.
|
|
75
114
|
*/
|
|
76
115
|
export declare function planPlaceFile(pubkey: string, createdAtMs: number, args: {
|
|
77
116
|
folder: string;
|
|
@@ -83,7 +122,7 @@ export declare function planPlaceFile(pubkey: string, createdAtMs: number, args:
|
|
|
83
122
|
* the Folder has state, otherwise nothing.
|
|
84
123
|
*
|
|
85
124
|
* {@link planPlaceFile} in reverse. A Folder with state lists what it names,
|
|
86
|
-
* deleted or not, so the row would stay pointing at nothing; a
|
|
125
|
+
* deleted or not, so the row would stay pointing at nothing; a group read by
|
|
87
126
|
* containment stops listing the file once the relay hides it. Delete first: a
|
|
88
127
|
* refused `remove` then leaves a stale row, where the other order would unlist
|
|
89
128
|
* a file the relay kept.
|
|
@@ -93,67 +132,105 @@ export declare function planUnlistFile(pubkey: string, createdAtMs: number, args
|
|
|
93
132
|
address: string;
|
|
94
133
|
hasState: boolean;
|
|
95
134
|
}): UnsignedEvent[];
|
|
135
|
+
/**
|
|
136
|
+
* Archive a Folder, or restore it: `[kind:1851 archived]` — FOL-46, SPEC §3.3.
|
|
137
|
+
*
|
|
138
|
+
* **Not a Folder command.** A Folder is archived the way any file is: a change
|
|
139
|
+
* setting `archived` on its address — its channel's, `FolderSummary.channel` —
|
|
140
|
+
* to `'true'`, or to an empty value to restore it. Its state, its contents and
|
|
141
|
+
* its channel are untouched, which is what makes it reversible: a `kind:9008`
|
|
142
|
+
* hides everything under the Folder's `h` for good, and a `kind:1852` would
|
|
143
|
+
* unlist a file from somewhere a person would have to remember.
|
|
144
|
+
*
|
|
145
|
+
* **Always in the Folder's own `h`**, and readers count it only from an owner
|
|
146
|
+
* or admin on the Folder's `kind:39001` (§3.2) — the people who may rename it.
|
|
147
|
+
* So offer Archive only to them (`FolderSummary.admins`): from anybody else the
|
|
148
|
+
* relay accepts the event and every reader ignores it.
|
|
149
|
+
*
|
|
150
|
+
* `resolution` is what the person archiving said about it, carried as the
|
|
151
|
+
* change's `content`; readers show it first when the archived Folder is
|
|
152
|
+
* opened. Restoring takes none.
|
|
153
|
+
*/
|
|
154
|
+
export declare function planArchiveFolder(pubkey: string, createdAtMs: number, args: {
|
|
155
|
+
folder: string;
|
|
156
|
+
channel: string;
|
|
157
|
+
archived: boolean;
|
|
158
|
+
resolution?: string;
|
|
159
|
+
}): UnsignedEvent[];
|
|
160
|
+
/**
|
|
161
|
+
* A file as a move needs it. A `ForeignObject` from `resolveFolderContents` is
|
|
162
|
+
* one: `ref` is its identity, `parentRef` the file it is drawn beneath, and
|
|
163
|
+
* `folder` the `h` of its root — absent for a root placed by `buzz-channel`.
|
|
164
|
+
*/
|
|
165
|
+
export interface MovableFile {
|
|
166
|
+
ref: string;
|
|
167
|
+
address?: string;
|
|
168
|
+
parentRef?: string;
|
|
169
|
+
folder?: string;
|
|
170
|
+
}
|
|
96
171
|
/**
|
|
97
172
|
* Why a move was refused. The source is checked first: no choice of target
|
|
98
173
|
* fixes it, so a consumer can stop offering Move for that file at all.
|
|
174
|
+
*
|
|
175
|
+
* `target-is-private`: the target's `kind:39000` is private and a moved file's
|
|
176
|
+
* `h` names any other channel, or none. A listing never changes who can read a
|
|
177
|
+
* file (§3.1), so the file would look private in the target and not be.
|
|
99
178
|
*/
|
|
100
|
-
export type MoveRefusal = 'source-has-no-state' | 'target-has-no-state';
|
|
179
|
+
export type MoveRefusal = 'source-has-no-state' | 'target-has-no-state' | 'target-is-private';
|
|
101
180
|
export type MovePlan = {
|
|
102
181
|
ok: true;
|
|
103
182
|
events: UnsignedEvent[];
|
|
183
|
+
/** The addresses the plan moves — the file, when the source lists it, and every file listed beneath it. */
|
|
184
|
+
moved: string[];
|
|
104
185
|
} | {
|
|
105
186
|
ok: false;
|
|
106
187
|
reason: MoveRefusal;
|
|
107
188
|
};
|
|
108
189
|
/**
|
|
109
|
-
*
|
|
190
|
+
* The files `listing` draws beneath `file`, at any depth, in listing order.
|
|
191
|
+
*
|
|
192
|
+
* Walked by `parentRef` — the bare file's folded `parent` (§6.7) and every
|
|
193
|
+
* other kind's declared children (§7.2) alike. A file on a cycle is drawn at
|
|
194
|
+
* the top (§6.7), so nothing is beneath it through the cycle: two files each
|
|
195
|
+
* moved under the other are neither's sub-file.
|
|
196
|
+
*/
|
|
197
|
+
export declare function listedBeneath<T extends MovableFile>(listing: readonly T[], file: Pick<MovableFile, 'ref' | 'parentRef'>): T[];
|
|
198
|
+
/**
|
|
199
|
+
* Move a file to another Folder, with everything listed beneath it:
|
|
200
|
+
* `[kind:1852 add to target, kind:1852 remove from source]` — SPEC §3.3.
|
|
201
|
+
*
|
|
202
|
+
* **One command each way, naming the whole set.** `listing` is the source
|
|
203
|
+
* Folder's files (`FolderContents.files`); the file moves with every file
|
|
204
|
+
* listed beneath it ({@link listedBeneath}), so a subtree moves whole. The
|
|
205
|
+
* relay applies every address on a command in one state write, so a failure
|
|
206
|
+
* can never split the subtree between the two Folders. The file itself is
|
|
207
|
+
* moved only when the source lists it — a Ship issue is listed by no Folder,
|
|
208
|
+
* its project is. The file's `h` does not change.
|
|
209
|
+
*
|
|
210
|
+
* `listing` is required, and `null` says "nothing can be listed beneath this
|
|
211
|
+
* file", making the file the whole set. A move that silently left its
|
|
212
|
+
* sub-files behind is the bug this planner exists to end, so omitting the
|
|
213
|
+
* listing is a type error rather than a quiet single-file move.
|
|
110
214
|
*
|
|
111
215
|
* **Add first.** There is no atomic move — state is per Folder — so something
|
|
112
|
-
* can fail between the two. After the add, a failure leaves the
|
|
216
|
+
* can fail between the two. After the add, a failure leaves the set in both
|
|
113
217
|
* Folders: visible, obviously wrong, fixed by moving again. Removing first and
|
|
114
|
-
* failing would leave it in neither, which looks like
|
|
218
|
+
* failing would leave it in neither, which looks like files that never were.
|
|
115
219
|
*
|
|
116
220
|
* **Refused unless both Folders have state.** An `add` to a Folder with none
|
|
117
|
-
* emits state listing only the moved
|
|
118
|
-
* disappears; a `remove` from one emits state listing nothing, and the
|
|
119
|
-
* source disappears.
|
|
120
|
-
* a stateless Folder holds is whatever its `h` implies to *this* reader, and a
|
|
121
|
-
* planner that enumerated it would be deciding on everyone's behalf.
|
|
122
|
-
*
|
|
123
|
-
* A move to the same Folder plans nothing.
|
|
124
|
-
*/
|
|
125
|
-
/**
|
|
126
|
-
* Archive a Folder, or restore it: `[kind:1851 archived]` — FOL-46.
|
|
127
|
-
*
|
|
128
|
-
* **Not a Folder command.** A Folder is archived the way any file is: a change
|
|
129
|
-
* setting `archived` on its address — its channel's, `FolderSummary.channel` —
|
|
130
|
-
* to `'true'`, or to an empty value to restore it. Its state, its contents and
|
|
131
|
-
* its channel are untouched, which is what makes it reversible: a `kind:9008`
|
|
132
|
-
* hides everything under the Folder's `h` for good (FOL-9), and a `kind:1852`
|
|
133
|
-
* would unlist the Folder from somewhere a person would have to remember.
|
|
221
|
+
* emits state listing only the moved files, and everything already filed in
|
|
222
|
+
* it disappears; a `remove` from one emits state listing nothing, and the
|
|
223
|
+
* whole source disappears.
|
|
134
224
|
*
|
|
135
|
-
* **
|
|
136
|
-
*
|
|
137
|
-
* one (`FolderSummary.listedIn`), when there is one: everyone reading that
|
|
138
|
-
* Folder then reads the archive, and a private sub-Folder is hidden from its
|
|
139
|
-
* team for the team's members too, not only for its own. A top-level Folder has
|
|
140
|
-
* no container, so it defaults to the Folder itself — anyone who may write
|
|
141
|
-
* there, a member and not only an admin, may archive it.
|
|
225
|
+
* **Refused into a private Folder** when any moved file's `h` is another
|
|
226
|
+
* channel or absent (`target-is-private`, §3.1).
|
|
142
227
|
*
|
|
143
|
-
*
|
|
144
|
-
* change's `content`; readers show it first when the archived Folder is
|
|
145
|
-
* opened. Restoring takes none.
|
|
228
|
+
* A move to the same Folder, or of a set the source does not list, plans nothing.
|
|
146
229
|
*/
|
|
147
|
-
export declare function planArchiveFolder(pubkey: string, createdAtMs: number, args: {
|
|
148
|
-
folder: string;
|
|
149
|
-
channel: string;
|
|
150
|
-
archived: boolean;
|
|
151
|
-
resolution?: string;
|
|
152
|
-
into?: string;
|
|
153
|
-
}): UnsignedEvent[];
|
|
154
230
|
export declare function planMoveFile(pubkey: string, createdAtMs: number, args: {
|
|
155
|
-
|
|
231
|
+
file: MovableFile;
|
|
156
232
|
from: FolderRef;
|
|
157
233
|
to: FolderRef;
|
|
234
|
+
listing: readonly MovableFile[] | null;
|
|
158
235
|
}): MovePlan;
|
|
159
236
|
//# sourceMappingURL=folders.d.ts.map
|
package/dist/folders.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"folders.d.ts","sourceRoot":"","sources":["../src/folders.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"folders.d.ts","sourceRoot":"","sources":["../src/folders.ts"],"names":[],"mappings":"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"}
|