@biolibs/bionet 1.1.0 → 1.2.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.
@@ -0,0 +1,171 @@
1
+ import type { SignOptions, SigningKey } from "@biolibs/opencloning";
2
+ import { type Operation, type Role, type SignedEntry } from "./log.js";
3
+ import { type InventoryDocument, type LabModel, type PeerModel } from "./model.js";
4
+ /** The longest sequence one part may have. */
5
+ export declare const LONGEST_SEQUENCE = 500000;
6
+ /** One key on the roster, now or once. */
7
+ export interface RosterKey {
8
+ /** The key, 32 bytes in base64url. */
9
+ key: string;
10
+ /** Whose device it is. A claim made by whoever added it. */
11
+ person: string;
12
+ /** What it may do. */
13
+ role: Role;
14
+ /** Whether this is the key that founded the lab. */
15
+ founder: boolean;
16
+ /** The entry that put it on the roster. */
17
+ added: string;
18
+ /** If it was removed: by which entry, and the last `seq` of its log the lab accepts. */
19
+ removed: {
20
+ by: string;
21
+ cutoff: number;
22
+ } | null;
23
+ }
24
+ /** One part the lab knows of. */
25
+ export interface PartState {
26
+ /** Its checksum, which is its identity. */
27
+ checksum: string;
28
+ /** Its bases. */
29
+ sequence: string;
30
+ /** Whether it is a circle. */
31
+ circular: boolean;
32
+ /** How long it is. */
33
+ length: number;
34
+ /** What the lab calls it. */
35
+ name: string;
36
+ /** Whether it is on offer to other labs. Nothing is until somebody says so. */
37
+ offered: boolean;
38
+ /** Anything else set on it. */
39
+ fields: Record<string, string | number | null>;
40
+ /** The entry that added it. */
41
+ added: string;
42
+ }
43
+ /** One physical item: a tube, a prep. */
44
+ export interface ItemState {
45
+ /** Its ID. */
46
+ item: string;
47
+ /** The checksum of the part it is an item of. */
48
+ part: string;
49
+ /** What one of its amount is, if anybody said: a tube, a microlitre. */
50
+ unit: string | null;
51
+ /** How much there is, by the log. Always a whole number of the unit. */
52
+ amount: number;
53
+ /** Whether it has been retired. */
54
+ retired: boolean;
55
+ /** Whether the log has lost track: the amount went below zero, or two recounts overlapped. */
56
+ needsRecount: boolean;
57
+ /** Anything else set on it. */
58
+ fields: Record<string, string | number | null>;
59
+ /** The entry that added it. */
60
+ added: string;
61
+ }
62
+ /** What became of one entry. */
63
+ export type EntryStatus = "applied" | "set aside" | "refused" | "not understood";
64
+ /** One entry, in the order the merge settled on, with what became of it. */
65
+ export interface Placed {
66
+ /** Its ID. */
67
+ id: string;
68
+ /** The entry. */
69
+ signed: SignedEntry;
70
+ /** Whether it counted. */
71
+ status: EntryStatus;
72
+ /** Why not, if not. */
73
+ reason: string | null;
74
+ }
75
+ /** An entry that could not be placed, or was not looked at further. */
76
+ export interface Unplaced {
77
+ /** What arrived. */
78
+ signed: unknown;
79
+ /** Why it is not in the lab. */
80
+ reason: string;
81
+ }
82
+ /** Two changes made without knowledge of each other, where only one could stand. */
83
+ export interface Overlap {
84
+ /** What they were both about. */
85
+ what: string;
86
+ /** The entry that stood. */
87
+ kept: string;
88
+ /** The entry that did not. */
89
+ dropped: string;
90
+ }
91
+ /** A lab, as its logs describe it. */
92
+ export interface LabState {
93
+ /** The lab's ID, or `null` if no founding entry was among the entries. */
94
+ lab: string | null;
95
+ /** What its founder called it. */
96
+ name: string | null;
97
+ /** Every key that is or was on the roster. */
98
+ roster: RosterKey[];
99
+ /** Every part. */
100
+ parts: PartState[];
101
+ /** Every item. */
102
+ items: ItemState[];
103
+ /** Every entry that could be placed, in order, with what became of it. */
104
+ entries: Placed[];
105
+ /** Entries that are waiting on others that have not arrived. */
106
+ waiting: Unplaced[];
107
+ /** Entries that were thrown out before they were placed: unreadable, badly signed, another lab's. */
108
+ discarded: Unplaced[];
109
+ /** Changes that overlapped. */
110
+ overlaps: Overlap[];
111
+ /** The latest placed entry in each key's log. */
112
+ heads: Record<string, {
113
+ seq: number;
114
+ id: string;
115
+ }>;
116
+ /** For each key, how far into every log its latest entry had seen. */
117
+ knows: Record<string, Record<string, number>>;
118
+ }
119
+ /**
120
+ * Work a lab out from its entries.
121
+ *
122
+ * @param entries - Every entry held, from every key, in any order. Duplicates are harmless.
123
+ * @param options - `lab` says which lab to build, when entries from more than one may be present.
124
+ * @returns The lab. It is the same for the same set of entries, whatever order they came in.
125
+ * @throws If the entries found more than one lab and `options.lab` does not say which is meant.
126
+ *
127
+ * @example
128
+ * ```ts
129
+ * import { adjustItem, mergeLog, nextEntry } from "@biolibs/bionet";
130
+ *
131
+ * const lab = await mergeLog(everyEntryHeld);
132
+ * lab.items.find((one) => one.item === tube)?.amount; // 9
133
+ *
134
+ * const used = await nextEntry(lab, key, adjustItem(tube, -1));
135
+ * (await mergeLog([...everyEntryHeld, used])).items.find((one) => one.item === tube)?.amount; // 8
136
+ * ```
137
+ */
138
+ export declare function mergeLog(entries: readonly unknown[], options?: {
139
+ lab?: string;
140
+ }): Promise<LabState>;
141
+ /**
142
+ * Write the next entry in a key's log, given the lab as it stands.
143
+ *
144
+ * It works out the three things an entry has to say about its place: which lab, what came before it
145
+ * in this key's log, and which other logs have moved on since this key last wrote.
146
+ *
147
+ * @param state - The lab, from `mergeLog` over everything held.
148
+ * @param key - The device's key.
149
+ * @param op - The change.
150
+ * @param options - A name to sign under, and when.
151
+ * @returns The signed entry, to be added to what is held and sent to the others.
152
+ * @throws If `state` has no lab.
153
+ */
154
+ export declare function nextEntry(state: LabState, key: SigningKey, op: Operation, options?: SignOptions): Promise<SignedEntry>;
155
+ /**
156
+ * What a lab shows the world: the parts it has in stock, and whether each is on offer.
157
+ *
158
+ * The logs hold everything — every tube, every amount, who took what. None of that leaves. A part is
159
+ * listed if some item of it that has not been retired has anything left, it is on offer only if a
160
+ * member said so, and the only note that travels is one written to be public (`public_note`).
161
+ *
162
+ * @param state - The lab.
163
+ * @param lab - Who is publishing, and from where.
164
+ * @param options - Other labs to point at, and when to say it was published.
165
+ * @returns An inventory, ready for a member to sign with `signInventory`.
166
+ */
167
+ export declare function publicInventory(state: LabState, lab: LabModel, options?: {
168
+ peers?: readonly PeerModel[];
169
+ publishedAt?: string;
170
+ }): InventoryDocument;
171
+ //# sourceMappingURL=merge.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"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"}