@biolibs/bionet 1.0.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.
- package/README.md +148 -0
- package/dist/discover.d.ts +121 -0
- package/dist/discover.d.ts.map +1 -0
- package/dist/discover.js +143 -0
- package/dist/discover.js.map +1 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +8 -0
- package/dist/index.js.map +1 -1
- package/dist/inventory.d.ts +23 -1
- package/dist/inventory.d.ts.map +1 -1
- package/dist/inventory.js +32 -0
- package/dist/inventory.js.map +1 -1
- package/dist/log.d.ts +196 -0
- package/dist/log.d.ts.map +1 -0
- package/dist/log.js +246 -0
- package/dist/log.js.map +1 -0
- package/dist/merge.d.ts +171 -0
- package/dist/merge.d.ts.map +1 -0
- package/dist/merge.js +520 -0
- package/dist/merge.js.map +1 -0
- package/dist/model.d.ts +40 -0
- package/dist/model.d.ts.map +1 -1
- package/dist/model.js +3 -0
- package/dist/model.js.map +1 -1
- package/dist/sync.d.ts +157 -0
- package/dist/sync.d.ts.map +1 -0
- package/dist/sync.js +203 -0
- package/dist/sync.js.map +1 -0
- package/package.json +1 -1
- package/src/discover.ts +214 -0
- package/src/index.ts +8 -0
- package/src/inventory.ts +40 -1
- package/src/log.ts +325 -0
- package/src/merge.ts +605 -0
- package/src/model.ts +41 -0
- package/src/sync.ts +210 -0
package/src/inventory.ts
CHANGED
|
@@ -10,7 +10,8 @@ import type { Dseqrecord } from "@biolibs/dseqrecord";
|
|
|
10
10
|
import { signUnder, verifyUnder, type SignatureCheck, type SignOptions,
|
|
11
11
|
type SigningKey } from "@biolibs/opencloning";
|
|
12
12
|
import { INVENTORY_VERSION, type InventoryDocument, type InventoryPart, type LabModel,
|
|
13
|
-
type SignedInventory } from "./model.js";
|
|
13
|
+
type PeerModel, type SignedInventory } from "./model.js";
|
|
14
|
+
import { labOrigin } from "./origin.js";
|
|
14
15
|
|
|
15
16
|
/** What the bytes of a signed inventory are for. */
|
|
16
17
|
export const INVENTORY_DOMAIN = "biolibs/bionet signed inventory v1";
|
|
@@ -20,6 +21,9 @@ export const MOST_PARTS = 5_000;
|
|
|
20
21
|
/** The longest an inventory may be, as text. */
|
|
21
22
|
export const LONGEST = 4_000_000;
|
|
22
23
|
|
|
24
|
+
/** How many labs one inventory may point at. */
|
|
25
|
+
export const MOST_PEERS = 200;
|
|
26
|
+
|
|
23
27
|
/** What `inventoryFrom` needs to know that the molecules cannot say. */
|
|
24
28
|
export interface InventoryOptions {
|
|
25
29
|
/** When to say it was published. Defaults to now. */
|
|
@@ -28,6 +32,13 @@ export interface InventoryOptions {
|
|
|
28
32
|
available?: boolean;
|
|
29
33
|
/** A note per part, by the part's name. */
|
|
30
34
|
notes?: Record<string, string>;
|
|
35
|
+
/**
|
|
36
|
+
* Other labs to point at, so that whoever reads this can go on to find them.
|
|
37
|
+
*
|
|
38
|
+
* Left out, the inventory carries no list at all rather than an empty one, which is what every
|
|
39
|
+
* inventory written before there were peers looks like.
|
|
40
|
+
*/
|
|
41
|
+
peers?: readonly PeerModel[];
|
|
31
42
|
}
|
|
32
43
|
|
|
33
44
|
/**
|
|
@@ -66,10 +77,28 @@ export function inventoryFrom(records: readonly Dseqrecord[], lab: LabModel,
|
|
|
66
77
|
bionet_inventory_version: INVENTORY_VERSION,
|
|
67
78
|
lab,
|
|
68
79
|
parts,
|
|
80
|
+
...(options.peers === undefined ? {} : { peers: [...options.peers] }),
|
|
69
81
|
published_at: options.publishedAt ?? new Date().toISOString(),
|
|
70
82
|
};
|
|
71
83
|
}
|
|
72
84
|
|
|
85
|
+
/**
|
|
86
|
+
* Point at another lab, for an inventory's `peers`.
|
|
87
|
+
*
|
|
88
|
+
* @param address - Their address, however it was written.
|
|
89
|
+
* @param about - What to call them, the key you saw, and why you are pointing at them.
|
|
90
|
+
* @returns The pointer.
|
|
91
|
+
* @throws If the address is not one an inventory can be fetched from.
|
|
92
|
+
*/
|
|
93
|
+
export function peer(address: string, about: { name?: string; key?: string; note?: string } = {}): PeerModel {
|
|
94
|
+
return {
|
|
95
|
+
origin: labOrigin(address),
|
|
96
|
+
name: about.name ?? null,
|
|
97
|
+
key: about.key ?? null,
|
|
98
|
+
note: about.note ?? null,
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
|
|
73
102
|
/**
|
|
74
103
|
* Sign an inventory, or add a signature to one already signed.
|
|
75
104
|
*
|
|
@@ -147,6 +176,16 @@ export function readInventory(value: unknown): SignedInventory {
|
|
|
147
176
|
throw new Error("This inventory lists something that is not a part.");
|
|
148
177
|
}
|
|
149
178
|
}
|
|
179
|
+
if (held.peers !== undefined) {
|
|
180
|
+
if (!Array.isArray(held.peers)) throw new Error("This inventory's list of other labs is not a list.");
|
|
181
|
+
if (held.peers.length > MOST_PEERS) throw new Error(`An inventory may point at most ${MOST_PEERS} labs.`);
|
|
182
|
+
for (const one of held.peers as Partial<PeerModel>[]) {
|
|
183
|
+
if (typeof one?.origin !== "string" || one.origin.length > 500
|
|
184
|
+
|| !sayable(one.name, 200) || !sayable(one.key, 120) || !sayable(one.note, 2_000)) {
|
|
185
|
+
throw new Error("This inventory points at something that is not a lab.");
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
}
|
|
150
189
|
if (!sayable(held.published_at, 40)) throw new Error("This inventory's publication time is not a time.");
|
|
151
190
|
return value;
|
|
152
191
|
}
|
package/src/log.ts
ADDED
|
@@ -0,0 +1,325 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One signed change to a lab, and the log it belongs to.
|
|
3
|
+
*
|
|
4
|
+
* A published inventory is what a lab shows the world. This is what happens inside it: every change
|
|
5
|
+
* anybody makes — somebody joined, a tube was added, some of it was used — is one entry, signed by
|
|
6
|
+
* the key of the device it was made on, and appended to that key's own log. Nobody writes to another
|
|
7
|
+
* key's log, so two people working offline cannot overwrite each other; what the lab holds is
|
|
8
|
+
* whatever `merge.ts` makes of all the logs together.
|
|
9
|
+
*
|
|
10
|
+
* An entry says three things beyond the change itself. Which lab it is for, so it cannot be replayed
|
|
11
|
+
* into another. Where it sits in its own key's log, so a missing or substituted entry shows. And what
|
|
12
|
+
* its author had seen of everybody else's logs when they wrote it, which is the only honest way to
|
|
13
|
+
* order changes made on laptops whose clocks agree about nothing.
|
|
14
|
+
*
|
|
15
|
+
* Reading is the careful half here too. An entry arrives from another machine, so `readEntry` checks
|
|
16
|
+
* its shape and its size before anything else looks at it.
|
|
17
|
+
*/
|
|
18
|
+
import { canonicalJson, signUnder, verifyUnder, type DocumentSignature, type SignatureCheck,
|
|
19
|
+
type SignOptions, type SigningKey } from "@biolibs/opencloning";
|
|
20
|
+
|
|
21
|
+
/** The version of the entry format written here. */
|
|
22
|
+
export const LOG_VERSION = 1;
|
|
23
|
+
|
|
24
|
+
/** What the bytes of a signed entry are for. No other kind of document is signed under this. */
|
|
25
|
+
export const LOG_DOMAIN = "biolibs/bionet log entry v1";
|
|
26
|
+
|
|
27
|
+
/** The longest one entry may be, as canonical text. A plasmid's sequence has to fit. */
|
|
28
|
+
export const LONGEST_ENTRY = 600_000;
|
|
29
|
+
|
|
30
|
+
/** How many other logs one entry may say it had seen. */
|
|
31
|
+
export const MOST_SEEN = 1_000;
|
|
32
|
+
|
|
33
|
+
/** What a key on the roster may do: change the inventory, or change the roster as well. */
|
|
34
|
+
export type Role = "member" | "keeper";
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* One change. `type` says which; the rest is whatever that change carries.
|
|
38
|
+
*
|
|
39
|
+
* It is deliberately loose. An entry whose `type` this version does not know is kept and chained
|
|
40
|
+
* like any other and simply not applied, so that an older app survives a newer one writing to the
|
|
41
|
+
* same lab. The operations this version does know are built by the functions at the foot of this
|
|
42
|
+
* file and checked by `merge.ts` when they are applied.
|
|
43
|
+
*/
|
|
44
|
+
export interface Operation {
|
|
45
|
+
/** Which change this is, like `item.adjust`. */
|
|
46
|
+
type: string;
|
|
47
|
+
[field: string]: unknown;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** One entry in one key's log. This is what is signed. */
|
|
51
|
+
export interface LogEntry {
|
|
52
|
+
/** Always `1`. */
|
|
53
|
+
bionet_log_version: number;
|
|
54
|
+
/** The lab this is for: the ID of its founding entry. `null` only in that founding entry. */
|
|
55
|
+
lab: string | null;
|
|
56
|
+
/** The key whose log this is in, 32 bytes in base64url. It must be the key that signs. */
|
|
57
|
+
author: string;
|
|
58
|
+
/** Where this sits in that log, from 0. */
|
|
59
|
+
seq: number;
|
|
60
|
+
/** The ID of the entry before it in the same log, or `null` at 0. */
|
|
61
|
+
prev: string | null;
|
|
62
|
+
/**
|
|
63
|
+
* What the author had of other keys' logs: for each key, the ID of the latest entry they held.
|
|
64
|
+
* Only keys whose latest entry changed since this author's previous entry need be listed.
|
|
65
|
+
*/
|
|
66
|
+
seen: Record<string, string>;
|
|
67
|
+
/** The change. */
|
|
68
|
+
op: Operation;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** An entry with its signature beside it, which is how one travels. */
|
|
72
|
+
export interface SignedEntry {
|
|
73
|
+
/** The entry, exactly as it was signed. */
|
|
74
|
+
entry: LogEntry;
|
|
75
|
+
/** The author's signature over it. */
|
|
76
|
+
signature: DocumentSignature;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const HEX_ID = /^[0-9a-f]{64}$/;
|
|
80
|
+
const KEY = /^[A-Za-z0-9_-]{43}$/;
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The ID of an entry: the SHA-256 of its canonical form, in hex.
|
|
84
|
+
*
|
|
85
|
+
* It covers the entry and not the signature, so it names the change itself. An entry's ID is how the
|
|
86
|
+
* next entry in the log points back at it and how another key says it has seen it.
|
|
87
|
+
*
|
|
88
|
+
* @param entry - The entry.
|
|
89
|
+
* @returns 64 hex characters.
|
|
90
|
+
*/
|
|
91
|
+
export async function entryId(entry: LogEntry): Promise<string> {
|
|
92
|
+
const bytes = new TextEncoder().encode(canonicalJson(entry));
|
|
93
|
+
const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes as unknown as ArrayBuffer);
|
|
94
|
+
return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** What `writeEntry` needs to know about where an entry goes. */
|
|
98
|
+
export interface EntryPlace {
|
|
99
|
+
/** The lab's ID. */
|
|
100
|
+
lab: string;
|
|
101
|
+
/** This key's previous entry, or `null` if this is its first. */
|
|
102
|
+
prev: SignedEntry | null;
|
|
103
|
+
/** The latest entry held from each other key, where that changed since `prev`. */
|
|
104
|
+
seen?: Record<string, string>;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* Write and sign the next entry in a key's log.
|
|
109
|
+
*
|
|
110
|
+
* Most callers want `nextEntry` in `merge.ts`, which works the place out from the lab's merged state.
|
|
111
|
+
* This is the plain form underneath it.
|
|
112
|
+
*
|
|
113
|
+
* @param key - The device's key. Its log is the one written to.
|
|
114
|
+
* @param place - Which lab, what came before in this log, and what had been seen of the others.
|
|
115
|
+
* @param op - The change.
|
|
116
|
+
* @param options - A name to sign under, and when.
|
|
117
|
+
* @returns The signed entry.
|
|
118
|
+
* @throws If `prev` belongs to another key or another lab.
|
|
119
|
+
*/
|
|
120
|
+
export async function writeEntry(key: SigningKey, place: EntryPlace, op: Operation,
|
|
121
|
+
options: SignOptions = {}): Promise<SignedEntry> {
|
|
122
|
+
const before = place.prev?.entry ?? null;
|
|
123
|
+
if (before !== null && before.author !== key.publicKey) {
|
|
124
|
+
throw new Error("The previous entry is from another key's log.");
|
|
125
|
+
}
|
|
126
|
+
if (before !== null && before.lab !== place.lab && !(before.lab === null && before.seq === 0)) {
|
|
127
|
+
throw new Error("The previous entry is from another lab.");
|
|
128
|
+
}
|
|
129
|
+
const entry: LogEntry = {
|
|
130
|
+
bionet_log_version: LOG_VERSION,
|
|
131
|
+
lab: place.lab,
|
|
132
|
+
author: key.publicKey,
|
|
133
|
+
seq: before === null ? 0 : before.seq + 1,
|
|
134
|
+
prev: before === null ? null : await entryId(before),
|
|
135
|
+
seen: { ...(place.seen ?? {}) },
|
|
136
|
+
op,
|
|
137
|
+
};
|
|
138
|
+
return { entry, signature: await sign(entry, key, options) };
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** Sign an entry, saying in this file's own terms why one cannot be signed. */
|
|
142
|
+
async function sign(entry: LogEntry, key: SigningKey, options: SignOptions): Promise<DocumentSignature> {
|
|
143
|
+
try {
|
|
144
|
+
canonicalJson(entry);
|
|
145
|
+
} catch {
|
|
146
|
+
throw new Error("An entry can carry only whole numbers: an amount is a whole number of the item's unit.");
|
|
147
|
+
}
|
|
148
|
+
return signUnder(LOG_DOMAIN, entry, key, options);
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Found a lab: write the entry every other entry in it will point back to.
|
|
153
|
+
*
|
|
154
|
+
* The lab's ID is this entry's ID, so a lab is named by an act — this key, founding this lab, at this
|
|
155
|
+
* claimed moment — and not by an address, which can change, or a name, which anybody can use.
|
|
156
|
+
*
|
|
157
|
+
* @param key - The founder's device key. It becomes the lab's first keeper.
|
|
158
|
+
* @param about - What the lab is called, and who is founding it.
|
|
159
|
+
* @param options - A name to sign under, and when.
|
|
160
|
+
* @returns The founding entry. `entryId` of its `entry` is the lab's ID.
|
|
161
|
+
*
|
|
162
|
+
* @example
|
|
163
|
+
* ```ts
|
|
164
|
+
* import { entryId, foundLab } from "@biolibs/bionet";
|
|
165
|
+
*
|
|
166
|
+
* const founding = await foundLab(key, { name: "The Wren Lab", person: "Ada" });
|
|
167
|
+
* const lab = await entryId(founding.entry);
|
|
168
|
+
* ```
|
|
169
|
+
*/
|
|
170
|
+
export async function foundLab(key: SigningKey, about: { name: string; person: string },
|
|
171
|
+
options: SignOptions = {}): Promise<SignedEntry> {
|
|
172
|
+
const entry: LogEntry = {
|
|
173
|
+
bionet_log_version: LOG_VERSION,
|
|
174
|
+
lab: null,
|
|
175
|
+
author: key.publicKey,
|
|
176
|
+
seq: 0,
|
|
177
|
+
prev: null,
|
|
178
|
+
seen: {},
|
|
179
|
+
op: { type: "roster.found", name: about.name, person: about.person },
|
|
180
|
+
};
|
|
181
|
+
return { entry, signature: await sign(entry, key, { signer: about.person, ...options }) };
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* Whether a value is shaped like a signed entry. Says nothing about whether the signature holds.
|
|
186
|
+
*
|
|
187
|
+
* @param value - Anything.
|
|
188
|
+
* @returns Whether it has an entry and a signature.
|
|
189
|
+
*/
|
|
190
|
+
export function isSignedEntry(value: unknown): value is SignedEntry {
|
|
191
|
+
if (typeof value !== "object" || value === null) return false;
|
|
192
|
+
const held = value as { entry?: unknown; signature?: unknown };
|
|
193
|
+
return typeof held.entry === "object" && held.entry !== null
|
|
194
|
+
&& typeof held.signature === "object" && held.signature !== null;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Read an entry that came from somewhere else.
|
|
199
|
+
*
|
|
200
|
+
* This checks shape and size and nothing more: that it could be an entry. Whether its signature
|
|
201
|
+
* holds is `verifyEntry`'s question, and whether it belongs in the lab is `mergeLog`'s.
|
|
202
|
+
*
|
|
203
|
+
* @param value - What arrived.
|
|
204
|
+
* @returns The same value, known to be shaped like an entry.
|
|
205
|
+
* @throws If it is not one, saying what is wrong.
|
|
206
|
+
*/
|
|
207
|
+
export function readEntry(value: unknown): SignedEntry {
|
|
208
|
+
if (!isSignedEntry(value)) throw new Error("This is not a signed log entry.");
|
|
209
|
+
const entry = value.entry as Partial<LogEntry>;
|
|
210
|
+
if (entry.bionet_log_version !== LOG_VERSION) {
|
|
211
|
+
throw new Error(`This entry is in a format this does not read (version ${String(entry.bionet_log_version)}).`);
|
|
212
|
+
}
|
|
213
|
+
if (typeof entry.author !== "string" || !KEY.test(entry.author)) throw new Error("This entry does not say whose log it is in.");
|
|
214
|
+
if (!Number.isInteger(entry.seq) || entry.seq! < 0 || entry.seq! > 1_000_000_000) {
|
|
215
|
+
throw new Error("This entry does not say where in the log it sits.");
|
|
216
|
+
}
|
|
217
|
+
if (entry.prev !== null && (typeof entry.prev !== "string" || !HEX_ID.test(entry.prev))) {
|
|
218
|
+
throw new Error("This entry's pointer to the one before it is not an entry ID.");
|
|
219
|
+
}
|
|
220
|
+
if ((entry.seq === 0) !== (entry.prev === null)) {
|
|
221
|
+
throw new Error("Only the first entry in a log has nothing before it.");
|
|
222
|
+
}
|
|
223
|
+
if (entry.lab !== null && (typeof entry.lab !== "string" || !HEX_ID.test(entry.lab))) {
|
|
224
|
+
throw new Error("This entry does not say which lab it is for.");
|
|
225
|
+
}
|
|
226
|
+
const op = entry.op as Partial<Operation> | null | undefined;
|
|
227
|
+
if (typeof op !== "object" || op === null || Array.isArray(op) || typeof op.type !== "string"
|
|
228
|
+
|| op.type.length === 0 || op.type.length > 60) {
|
|
229
|
+
throw new Error("This entry carries no change.");
|
|
230
|
+
}
|
|
231
|
+
if (entry.lab === null && !(entry.seq === 0 && op.type === "roster.found")) {
|
|
232
|
+
throw new Error("Only a founding entry may leave out the lab.");
|
|
233
|
+
}
|
|
234
|
+
if (op.type === "roster.found" && entry.lab !== null) {
|
|
235
|
+
throw new Error("A founding entry cannot be written into an existing lab.");
|
|
236
|
+
}
|
|
237
|
+
const seen = entry.seen as unknown;
|
|
238
|
+
if (typeof seen !== "object" || seen === null || Array.isArray(seen)) throw new Error("This entry does not say what it had seen.");
|
|
239
|
+
const others = Object.entries(seen as Record<string, unknown>);
|
|
240
|
+
if (others.length > MOST_SEEN) throw new Error(`An entry may name at most ${MOST_SEEN} other logs.`);
|
|
241
|
+
for (const [key, id] of others) {
|
|
242
|
+
if (!KEY.test(key) || typeof id !== "string" || !HEX_ID.test(id) || key === entry.author) {
|
|
243
|
+
throw new Error("This entry's record of what it had seen is not a list of keys and entry IDs.");
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
const signature = value.signature as Partial<DocumentSignature>;
|
|
247
|
+
if (typeof signature.algorithm !== "string" || typeof signature.public_key !== "string"
|
|
248
|
+
|| typeof signature.signature !== "string" || typeof signature.signed_at !== "string"
|
|
249
|
+
|| signature.signed_at.length > 40 || signature.signature.length > 200
|
|
250
|
+
|| (signature.signer !== null && (typeof signature.signer !== "string" || signature.signer.length > 200))) {
|
|
251
|
+
throw new Error("This entry's signature is not a signature.");
|
|
252
|
+
}
|
|
253
|
+
if (canonicalJson(entry).length > LONGEST_ENTRY) throw new Error("This entry is longer than will be read.");
|
|
254
|
+
return value;
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
/**
|
|
258
|
+
* Check an entry's signature.
|
|
259
|
+
*
|
|
260
|
+
* Two things have to be true: the signature holds over these bytes under the log's own domain, and
|
|
261
|
+
* the key that signed is the key whose log the entry claims to be in. The second matters as much as
|
|
262
|
+
* the first — without it anybody could sign an entry into somebody else's log with their own key.
|
|
263
|
+
*
|
|
264
|
+
* @param signed - The entry.
|
|
265
|
+
* @returns The check. `ok` only if both hold; `problem` says which did not.
|
|
266
|
+
*/
|
|
267
|
+
export async function verifyEntry(signed: SignedEntry): Promise<SignatureCheck> {
|
|
268
|
+
const [check] = await verifyUnder(LOG_DOMAIN, signed.entry, [signed.signature]);
|
|
269
|
+
if (check!.ok && signed.signature.public_key !== signed.entry.author) {
|
|
270
|
+
return { ...check!, ok: false, problem: "This entry was signed by a key other than the one whose log it is in." };
|
|
271
|
+
}
|
|
272
|
+
return check!;
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
/** @returns The change that adds a key to the roster. */
|
|
276
|
+
export const addToRoster = (key: string, person: string, role: Role = "member"): Operation =>
|
|
277
|
+
({ type: "roster.add", key, person, role });
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* @param key - The key to remove.
|
|
281
|
+
* @param cutoff - The last `seq` of that key's log the lab accepts. -1 accepts none of it.
|
|
282
|
+
* @returns The change that removes a key, keeping its entries up to the cutoff.
|
|
283
|
+
*/
|
|
284
|
+
export const removeFromRoster = (key: string, cutoff: number): Operation =>
|
|
285
|
+
({ type: "roster.remove", key, cutoff });
|
|
286
|
+
|
|
287
|
+
/** @returns The change that makes a key a keeper, or an ordinary member again. */
|
|
288
|
+
export const setRole = (key: string, role: Role): Operation => ({ type: "roster.role", key, role });
|
|
289
|
+
|
|
290
|
+
/** @returns The change that adds a part, by its sequence. Its checksum is computed when applied. */
|
|
291
|
+
export const addPart = (part: { sequence: string; circular?: boolean; name: string }): Operation =>
|
|
292
|
+
({ type: "part.add", sequence: part.sequence, circular: part.circular === true, name: part.name });
|
|
293
|
+
|
|
294
|
+
/** @returns The change that says whether a part is on offer to other labs. */
|
|
295
|
+
export const offerPart = (part: string, available: boolean): Operation => ({ type: "part.offer", part, available });
|
|
296
|
+
|
|
297
|
+
/** @returns The change that adds one physical item of a part. `amount` is a whole number of `unit`. */
|
|
298
|
+
export const addItem = (item: { item: string; part: string; amount: number; unit?: string | null }): Operation =>
|
|
299
|
+
({ type: "item.add", item: item.item, part: item.part, amount: item.amount, unit: item.unit ?? null });
|
|
300
|
+
|
|
301
|
+
/** @returns The change that adds to or takes from an item. `by` is a whole-number difference, never a total. */
|
|
302
|
+
export const adjustItem = (item: string, by: number): Operation => ({ type: "item.adjust", item, by });
|
|
303
|
+
|
|
304
|
+
/** @returns The change that says how much of an item is physically there. */
|
|
305
|
+
export const recountItem = (item: string, amount: number): Operation => ({ type: "item.recount", item, amount });
|
|
306
|
+
|
|
307
|
+
/** @returns The change that retires an item. It stays in the history. */
|
|
308
|
+
export const retireItem = (item: string): Operation => ({ type: "item.retire", item });
|
|
309
|
+
|
|
310
|
+
/** @returns The change that sets one field on a part (by checksum) or an item (by ID). */
|
|
311
|
+
export const setField = (on: "part" | "item", id: string, field: string, value: string | number | null): Operation =>
|
|
312
|
+
({ type: "field.set", on, id, field, value });
|
|
313
|
+
|
|
314
|
+
/**
|
|
315
|
+
* A new ID for an item: 16 random bytes in hex.
|
|
316
|
+
*
|
|
317
|
+
* Random, because items are created on laptops that are offline, and two of them counting up from
|
|
318
|
+
* the same number would collide the moment they met.
|
|
319
|
+
*
|
|
320
|
+
* @returns 32 hex characters.
|
|
321
|
+
*/
|
|
322
|
+
export function newItemId(): string {
|
|
323
|
+
const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
|
|
324
|
+
return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
|
|
325
|
+
}
|