@starci/seed 0.0.0-stage → 0.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/CHANGELOG.md +16 -0
- package/LICENSE +21 -0
- package/README.md +55 -2
- package/dist/copies.d.ts +83 -0
- package/dist/copies.js +146 -0
- package/dist/driver.d.ts +145 -0
- package/dist/driver.js +21 -0
- package/dist/git/driver.d.ts +53 -0
- package/dist/git/driver.js +309 -0
- package/dist/git/files.d.ts +48 -0
- package/dist/git/files.js +78 -0
- package/dist/git/index.d.ts +6 -0
- package/dist/git/index.js +3 -0
- package/dist/git/standard.d.ts +60 -0
- package/dist/git/standard.js +105 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.js +6 -0
- package/dist/manifest.d.ts +108 -0
- package/dist/manifest.js +131 -0
- package/dist/postgres/index.d.ts +2 -0
- package/dist/postgres/index.js +1 -0
- package/dist/postgres/pipe.d.ts +11 -0
- package/dist/postgres/pipe.js +60 -0
- package/dist/postgres/sql.d.ts +42 -0
- package/dist/postgres/sql.js +54 -0
- package/dist/postgres/store.d.ts +33 -0
- package/dist/postgres/store.js +231 -0
- package/dist/protocol.d.ts +52 -0
- package/dist/protocol.js +101 -0
- package/dist/store.d.ts +97 -0
- package/dist/store.js +6 -0
- package/dist/testing/contract.d.ts +26 -0
- package/dist/testing/contract.js +219 -0
- package/dist/testing/index.d.ts +5 -0
- package/dist/testing/index.js +3 -0
- package/dist/testing/memory.d.ts +53 -0
- package/dist/testing/memory.js +0 -0
- package/dist/words.d.ts +33 -0
- package/dist/words.js +16 -0
- package/package.json +85 -4
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
import { causeLabel } from "../copies.js";
|
|
2
|
+
import { DataRefusal } from "../driver.js";
|
|
3
|
+
import { byteOrder, canonicalJson, recordEntry, recordValue } from "../manifest.js";
|
|
4
|
+
import { importOutcome } from "../store.js";
|
|
5
|
+
import { Cancelled, streamed } from "./pipe.js";
|
|
6
|
+
import * as sql from "./sql.js";
|
|
7
|
+
const SET_NAME = /^[A-Za-z0-9_$.-]+$/u;
|
|
8
|
+
/** A dry run's result, thrown out of the transaction so it rolls back. */
|
|
9
|
+
class DryRun extends Error {
|
|
10
|
+
report;
|
|
11
|
+
constructor(report) {
|
|
12
|
+
super("dry run");
|
|
13
|
+
this.report = report;
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
const text = (value) => value;
|
|
17
|
+
/** The store that copies the whole relational database behind the `StoreAdapter` port (kind `database`, level `physical`). */
|
|
18
|
+
export function postgresStore(options) {
|
|
19
|
+
const { id, run } = options;
|
|
20
|
+
const schemas = options.schemas ?? ["public"];
|
|
21
|
+
const exclude = options.exclude ?? [];
|
|
22
|
+
const pageRows = options.pageRows ?? 5000;
|
|
23
|
+
if (!Number.isInteger(pageRows) || pageRows < 1)
|
|
24
|
+
throw new TypeError("pageRows is a whole number of at least 1");
|
|
25
|
+
const refuse = (cause, table) => {
|
|
26
|
+
if (cause instanceof DataRefusal || cause instanceof Cancelled)
|
|
27
|
+
return cause;
|
|
28
|
+
const params = table === undefined ? { store: id, cause: causeLabel(cause) } : { store: id, table, cause: causeLabel(cause) };
|
|
29
|
+
return new DataRefusal("DATA_STORE_FAILED", "configuration", params, cause);
|
|
30
|
+
};
|
|
31
|
+
async function loadCatalog(from) {
|
|
32
|
+
const excluded = new Set(exclude.map((item) => item.table));
|
|
33
|
+
const cannot = exclude.map((item) => ({ what: `export and import of table ${item.table}`, reason: `excluded by the app: ${item.reason}` }));
|
|
34
|
+
const held = [];
|
|
35
|
+
const rows = [...(await from.query(sql.CATALOG, [schemas]))].map((row) => ({ schema: text(row.schema), table: text(row.table), row }));
|
|
36
|
+
for (const { schema, table, row } of rows.sort((left, right) => byteOrder(`${left.schema}.${left.table}`, `${right.schema}.${right.table}`))) {
|
|
37
|
+
const set = `${schema}.${table}`;
|
|
38
|
+
const skip = (reason) => {
|
|
39
|
+
cannot.push({ what: `export and import of table ${set}`, reason });
|
|
40
|
+
};
|
|
41
|
+
if (excluded.has(set))
|
|
42
|
+
continue;
|
|
43
|
+
if (!SET_NAME.test(set)) {
|
|
44
|
+
skip("its name has characters a set name cannot hold (only letters, digits, _ $ . and -)");
|
|
45
|
+
continue;
|
|
46
|
+
}
|
|
47
|
+
if (row.pk === null) {
|
|
48
|
+
skip("it has no primary key, so a row cannot keep its identity");
|
|
49
|
+
continue;
|
|
50
|
+
}
|
|
51
|
+
const columns = JSON.parse(text(row.columns));
|
|
52
|
+
const names = JSON.parse(text(row.pk));
|
|
53
|
+
const pk = names.flatMap((name) => columns.filter((column) => column.name === name));
|
|
54
|
+
if (pk.length !== names.length) {
|
|
55
|
+
skip("its primary key holds a generated column");
|
|
56
|
+
continue;
|
|
57
|
+
}
|
|
58
|
+
held.push({ schema, table, set, columns, pk });
|
|
59
|
+
}
|
|
60
|
+
return { held, cannot: cannot.sort((left, right) => byteOrder(left.what, right.what)) };
|
|
61
|
+
}
|
|
62
|
+
/** The key's primary key column texts, or null when the key is not one of this table's. */
|
|
63
|
+
function partsOf(table, key) {
|
|
64
|
+
if (table.pk.length === 1)
|
|
65
|
+
return [key];
|
|
66
|
+
try {
|
|
67
|
+
const parts = JSON.parse(key);
|
|
68
|
+
return Array.isArray(parts) && parts.length === table.pk.length && parts.every((part) => typeof part === "string") ? parts : null;
|
|
69
|
+
}
|
|
70
|
+
catch {
|
|
71
|
+
return null;
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
/** The row object of an entry when it is a whole row of this table under this key, else null. */
|
|
75
|
+
function rowOf(table, entry) {
|
|
76
|
+
let value;
|
|
77
|
+
try {
|
|
78
|
+
value = recordValue(entry);
|
|
79
|
+
}
|
|
80
|
+
catch {
|
|
81
|
+
return null;
|
|
82
|
+
}
|
|
83
|
+
if (typeof value !== "object" || value === null || Array.isArray(value))
|
|
84
|
+
return null;
|
|
85
|
+
const row = value;
|
|
86
|
+
const names = Object.keys(row).sort(byteOrder);
|
|
87
|
+
const wanted = table.columns.map((column) => column.name).sort(byteOrder);
|
|
88
|
+
if (names.length !== wanted.length || names.some((name, at) => name !== wanted[at]))
|
|
89
|
+
return null;
|
|
90
|
+
if (!Object.values(row).every((item) => item === null || typeof item === "string"))
|
|
91
|
+
return null;
|
|
92
|
+
const parts = partsOf(table, entry.key);
|
|
93
|
+
if (parts === null || table.pk.some((column, at) => row[column.name] !== parts[at]))
|
|
94
|
+
return null;
|
|
95
|
+
return row;
|
|
96
|
+
}
|
|
97
|
+
async function* exportEntries(selection) {
|
|
98
|
+
const batches = streamed(async (send) => {
|
|
99
|
+
let current;
|
|
100
|
+
try {
|
|
101
|
+
await run.transaction("repeatable read", async (tx) => {
|
|
102
|
+
await tx.query(sql.SESSION);
|
|
103
|
+
for (const table of (await loadCatalog(tx)).held) {
|
|
104
|
+
if (selection.sets !== undefined && !selection.sets.includes(table.set))
|
|
105
|
+
continue;
|
|
106
|
+
current = table.set;
|
|
107
|
+
let after = null;
|
|
108
|
+
for (;;) {
|
|
109
|
+
const rows = await tx.query(sql.page(table, pageRows, after !== null), after === null ? [] : [after]);
|
|
110
|
+
const entries = rows.map((row) => recordEntry(table.set, text(row.k), JSON.parse(text(row.r)))).sort((left, right) => byteOrder(left.key, right.key));
|
|
111
|
+
if (entries.length > 0)
|
|
112
|
+
await send(entries);
|
|
113
|
+
if (rows.length < pageRows)
|
|
114
|
+
break;
|
|
115
|
+
after = entries.reduce((_, entry) => entry.key, "");
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
});
|
|
119
|
+
}
|
|
120
|
+
catch (cause) {
|
|
121
|
+
throw refuse(cause, current);
|
|
122
|
+
}
|
|
123
|
+
});
|
|
124
|
+
for await (const batch of batches)
|
|
125
|
+
yield* batch;
|
|
126
|
+
}
|
|
127
|
+
async function importEntries(entries, options) {
|
|
128
|
+
const tallies = new Map();
|
|
129
|
+
let current;
|
|
130
|
+
try {
|
|
131
|
+
return await run.transaction("read committed", async (tx) => {
|
|
132
|
+
await tx.query(sql.SESSION);
|
|
133
|
+
await tx.query(sql.REPLICA);
|
|
134
|
+
const byName = new Map((await loadCatalog(tx)).held.map((table) => [table.set, table]));
|
|
135
|
+
for await (const entry of entries) {
|
|
136
|
+
const tally = tallies.get(entry.set) ?? { created: 0, updated: 0, unchanged: 0, removed: 0, refused: [], seen: new Set() };
|
|
137
|
+
tallies.set(entry.set, tally);
|
|
138
|
+
tally.seen.add(entry.key);
|
|
139
|
+
const table = byName.get(entry.set);
|
|
140
|
+
if (table === undefined) {
|
|
141
|
+
tally.refused.push({ key: entry.key, code: "DATA_TABLE_NOT_HELD" });
|
|
142
|
+
continue;
|
|
143
|
+
}
|
|
144
|
+
current = table.set;
|
|
145
|
+
const row = rowOf(table, entry);
|
|
146
|
+
if (row === null) {
|
|
147
|
+
tally.refused.push({ key: entry.key, code: "DATA_ROW_INVALID" });
|
|
148
|
+
continue;
|
|
149
|
+
}
|
|
150
|
+
const [stored] = await tx.query(sql.get(table), table.pk.map((column) => row[column.name]));
|
|
151
|
+
if (stored === undefined)
|
|
152
|
+
tally.created += 1;
|
|
153
|
+
else if (canonicalJson(JSON.parse(text(stored.r))) === canonicalJson(row)) {
|
|
154
|
+
tally.unchanged += 1;
|
|
155
|
+
continue;
|
|
156
|
+
}
|
|
157
|
+
else
|
|
158
|
+
tally.updated += 1;
|
|
159
|
+
await tx.query(sql.upsert(table), [JSON.stringify(row)]);
|
|
160
|
+
}
|
|
161
|
+
const held = [...tallies].flatMap(([set, tally]) => {
|
|
162
|
+
const table = byName.get(set);
|
|
163
|
+
return table === undefined ? [] : [{ table, tally }];
|
|
164
|
+
});
|
|
165
|
+
for (const { table, tally } of held) {
|
|
166
|
+
current = table.set;
|
|
167
|
+
if (options.mode === "mirror") {
|
|
168
|
+
for (const row of await tx.query(sql.keys(table))) {
|
|
169
|
+
if (tally.seen.has(text(row.k)))
|
|
170
|
+
continue;
|
|
171
|
+
await tx.query(sql.remove(table), table.pk.map((_, at) => row[`p${String(at)}`]));
|
|
172
|
+
tally.removed += 1;
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
// setval is not transactional: a dry run must not move a sequence.
|
|
176
|
+
if (options.dryRun)
|
|
177
|
+
continue;
|
|
178
|
+
for (const owned of await tx.query(sql.SEQUENCES, [sql.qualified(table)]))
|
|
179
|
+
await tx.query(sql.setval(table, text(owned.column)), [text(owned.sequence)]);
|
|
180
|
+
}
|
|
181
|
+
const sets = [...tallies]
|
|
182
|
+
.map(([set, tally]) => ({ set, created: tally.created, updated: tally.updated, unchanged: tally.unchanged, removed: tally.removed, refused: [...tally.refused].sort((left, right) => byteOrder(left.key, right.key)) }))
|
|
183
|
+
.sort((left, right) => byteOrder(left.set, right.set));
|
|
184
|
+
const report = { sets, outcome: importOutcome(sets) };
|
|
185
|
+
// A dry run did every write above, counted it, and now rolls the transaction back.
|
|
186
|
+
if (options.dryRun)
|
|
187
|
+
throw new DryRun(report);
|
|
188
|
+
return report;
|
|
189
|
+
});
|
|
190
|
+
}
|
|
191
|
+
catch (cause) {
|
|
192
|
+
if (cause instanceof DryRun)
|
|
193
|
+
return cause.report;
|
|
194
|
+
throw refuse(cause, current);
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
return {
|
|
198
|
+
id,
|
|
199
|
+
kind: "database",
|
|
200
|
+
level: "physical",
|
|
201
|
+
async describe() {
|
|
202
|
+
try {
|
|
203
|
+
const catalog = await loadCatalog(run);
|
|
204
|
+
return {
|
|
205
|
+
sets: catalog.held.map((table) => ({ set: table.set, schema: `postgres/${table.set}@1`, form: "record" })),
|
|
206
|
+
purposes: ["seed-backup"],
|
|
207
|
+
canExport: true,
|
|
208
|
+
canImport: true,
|
|
209
|
+
cannot: catalog.cannot,
|
|
210
|
+
};
|
|
211
|
+
}
|
|
212
|
+
catch (cause) {
|
|
213
|
+
throw refuse(cause);
|
|
214
|
+
}
|
|
215
|
+
},
|
|
216
|
+
export: (selection) => exportEntries(selection),
|
|
217
|
+
import: importEntries,
|
|
218
|
+
async identityOf(set, key) {
|
|
219
|
+
try {
|
|
220
|
+
const table = (await loadCatalog(run)).held.find((item) => item.set === set);
|
|
221
|
+
const parts = table === undefined ? null : partsOf(table, key);
|
|
222
|
+
if (table === undefined || parts === null)
|
|
223
|
+
return null;
|
|
224
|
+
return (await run.query(sql.exists(table), parts)).length > 0 ? key : null;
|
|
225
|
+
}
|
|
226
|
+
catch (cause) {
|
|
227
|
+
throw refuse(cause, set);
|
|
228
|
+
}
|
|
229
|
+
},
|
|
230
|
+
};
|
|
231
|
+
}
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import type { DataEntry } from "./manifest.js";
|
|
2
|
+
import type { StoreAdapter } from "./store.js";
|
|
3
|
+
import type { StoreKind, StoreLevel } from "./words.js";
|
|
4
|
+
/**
|
|
5
|
+
* The line protocol `starci/data-entries@1` between the harness and an app's store command: newline-delimited JSON.
|
|
6
|
+
*
|
|
7
|
+
* <argv> describe -> one line: StoreDescription
|
|
8
|
+
* <argv> export <Selection JSON> -> one line per entry, then {"end": true, "items": n}
|
|
9
|
+
* <argv> import <ImportOptions> <- entry lines on stdin; -> last line: ImportReport
|
|
10
|
+
* <argv> identity <set> <key> -> one line: {"identity": string | null}
|
|
11
|
+
*
|
|
12
|
+
* A record's body travels as its canonical JSON text, a blob's as base64. A value never reaches argv or a log.
|
|
13
|
+
*/
|
|
14
|
+
export declare const DATA_PROTOCOL = "starci/data-entries@1";
|
|
15
|
+
/** One entry as a protocol line. */
|
|
16
|
+
export interface EntryLine {
|
|
17
|
+
/** The set. */
|
|
18
|
+
readonly set: string;
|
|
19
|
+
/** The natural key. */
|
|
20
|
+
readonly key: string;
|
|
21
|
+
/** record or blob. */
|
|
22
|
+
readonly form: DataEntry["form"];
|
|
23
|
+
/** The media type. */
|
|
24
|
+
readonly media: string;
|
|
25
|
+
/** sha256 of the body. */
|
|
26
|
+
readonly sha256: string;
|
|
27
|
+
/** The canonical JSON text of a record, the base64 of a blob. */
|
|
28
|
+
readonly body: string;
|
|
29
|
+
}
|
|
30
|
+
/** The protocol line of an entry. */
|
|
31
|
+
export declare function encodeEntry(entry: DataEntry): string;
|
|
32
|
+
/** The entry of a protocol line; a body that does not match its sha256 is refused. */
|
|
33
|
+
export declare function decodeEntry(text: string): DataEntry;
|
|
34
|
+
/** What the app's command reads and writes. */
|
|
35
|
+
export interface ServeIo {
|
|
36
|
+
/** The arguments after the command's own: `describe`, `export <json>` or `import <json>`. */
|
|
37
|
+
readonly args: readonly string[];
|
|
38
|
+
/** stdin, line by line (only `import` reads it). */
|
|
39
|
+
readonly lines: AsyncIterable<string>;
|
|
40
|
+
/** Writes one line to stdout. */
|
|
41
|
+
readonly write: (line: string) => void;
|
|
42
|
+
}
|
|
43
|
+
/** Serves one store over the protocol from an app's command; answers the exit code. */
|
|
44
|
+
export declare function serveStore(store: StoreAdapter, io: ServeIo): Promise<number>;
|
|
45
|
+
/** Runs the app's command with extra arguments and optional stdin lines; yields its stdout lines. */
|
|
46
|
+
export type CommandRunner = (args: readonly string[], input?: AsyncIterable<string>) => AsyncIterable<string>;
|
|
47
|
+
/** A store reached through an app's command: the harness side of the protocol. */
|
|
48
|
+
export declare function commandStore(declared: {
|
|
49
|
+
readonly id: string;
|
|
50
|
+
readonly kind: StoreKind;
|
|
51
|
+
readonly level: StoreLevel;
|
|
52
|
+
}, run: CommandRunner): StoreAdapter;
|
package/dist/protocol.js
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import { sha256Hex } from "./manifest.js";
|
|
2
|
+
/**
|
|
3
|
+
* The line protocol `starci/data-entries@1` between the harness and an app's store command: newline-delimited JSON.
|
|
4
|
+
*
|
|
5
|
+
* <argv> describe -> one line: StoreDescription
|
|
6
|
+
* <argv> export <Selection JSON> -> one line per entry, then {"end": true, "items": n}
|
|
7
|
+
* <argv> import <ImportOptions> <- entry lines on stdin; -> last line: ImportReport
|
|
8
|
+
* <argv> identity <set> <key> -> one line: {"identity": string | null}
|
|
9
|
+
*
|
|
10
|
+
* A record's body travels as its canonical JSON text, a blob's as base64. A value never reaches argv or a log.
|
|
11
|
+
*/
|
|
12
|
+
export const DATA_PROTOCOL = "starci/data-entries@1";
|
|
13
|
+
const encoder = new TextEncoder();
|
|
14
|
+
const decoder = new TextDecoder("utf-8", { fatal: true });
|
|
15
|
+
/** The protocol line of an entry. */
|
|
16
|
+
export function encodeEntry(entry) {
|
|
17
|
+
const body = entry.form === "record" ? decoder.decode(entry.body) : Buffer.from(entry.body).toString("base64");
|
|
18
|
+
const line = { set: entry.set, key: entry.key, form: entry.form, media: entry.media, sha256: entry.sha256, body };
|
|
19
|
+
return JSON.stringify(line);
|
|
20
|
+
}
|
|
21
|
+
/** The entry of a protocol line; a body that does not match its sha256 is refused. */
|
|
22
|
+
export function decodeEntry(text) {
|
|
23
|
+
const line = JSON.parse(text);
|
|
24
|
+
const body = line.form === "record" ? encoder.encode(line.body) : new Uint8Array(Buffer.from(line.body, "base64"));
|
|
25
|
+
if (sha256Hex(body) !== line.sha256)
|
|
26
|
+
throw new TypeError(`${line.set}/${line.key}: the body does not match its sha256`);
|
|
27
|
+
return { set: line.set, key: line.key, form: line.form, media: line.media, body, sha256: line.sha256 };
|
|
28
|
+
}
|
|
29
|
+
async function* entriesFromLines(lines) {
|
|
30
|
+
for await (const line of lines)
|
|
31
|
+
if (line.trim() !== "")
|
|
32
|
+
yield decodeEntry(line);
|
|
33
|
+
}
|
|
34
|
+
/** Serves one store over the protocol from an app's command; answers the exit code. */
|
|
35
|
+
export async function serveStore(store, io) {
|
|
36
|
+
const [verb, argument] = io.args;
|
|
37
|
+
if (verb === "describe") {
|
|
38
|
+
io.write(JSON.stringify(await store.describe()));
|
|
39
|
+
return 0;
|
|
40
|
+
}
|
|
41
|
+
if (verb === "export") {
|
|
42
|
+
const selection = JSON.parse(argument ?? "{}");
|
|
43
|
+
let items = 0;
|
|
44
|
+
for await (const entry of store.export(selection)) {
|
|
45
|
+
io.write(encodeEntry(entry));
|
|
46
|
+
items += 1;
|
|
47
|
+
}
|
|
48
|
+
io.write(JSON.stringify({ end: true, items }));
|
|
49
|
+
return 0;
|
|
50
|
+
}
|
|
51
|
+
if (verb === "import") {
|
|
52
|
+
const options = JSON.parse(argument ?? '{"dryRun":true,"mode":"merge"}');
|
|
53
|
+
io.write(JSON.stringify(await store.import(entriesFromLines(io.lines), options)));
|
|
54
|
+
return 0;
|
|
55
|
+
}
|
|
56
|
+
if (verb === "identity") {
|
|
57
|
+
io.write(JSON.stringify({ identity: await store.identityOf(argument ?? "", io.args[2] ?? "") }));
|
|
58
|
+
return 0;
|
|
59
|
+
}
|
|
60
|
+
io.write(JSON.stringify({ error: "DATA_PROTOCOL_USAGE", usage: "describe | export <selection> | import <options> | identity <set> <key>" }));
|
|
61
|
+
return 2;
|
|
62
|
+
}
|
|
63
|
+
async function lastLine(lines) {
|
|
64
|
+
let last = "";
|
|
65
|
+
for await (const line of lines)
|
|
66
|
+
if (line.trim() !== "")
|
|
67
|
+
last = line;
|
|
68
|
+
return last;
|
|
69
|
+
}
|
|
70
|
+
async function* linesOf(entries) {
|
|
71
|
+
for await (const entry of entries)
|
|
72
|
+
yield encodeEntry(entry);
|
|
73
|
+
}
|
|
74
|
+
/** A store reached through an app's command: the harness side of the protocol. */
|
|
75
|
+
export function commandStore(declared, run) {
|
|
76
|
+
return {
|
|
77
|
+
...declared,
|
|
78
|
+
describe: async () => JSON.parse(await lastLine(run(["describe"]))),
|
|
79
|
+
async *export(selection) {
|
|
80
|
+
let items = 0;
|
|
81
|
+
let ended = false;
|
|
82
|
+
for await (const line of run(["export", JSON.stringify(selection)])) {
|
|
83
|
+
if (line.trim() === "")
|
|
84
|
+
continue;
|
|
85
|
+
const parsed = JSON.parse(line);
|
|
86
|
+
if (parsed.end === true) {
|
|
87
|
+
if (parsed.items !== items)
|
|
88
|
+
throw new TypeError(`${declared.id}: the command counted ${String(parsed.items)} entries, ${String(items)} arrived`);
|
|
89
|
+
ended = true;
|
|
90
|
+
continue;
|
|
91
|
+
}
|
|
92
|
+
yield decodeEntry(line);
|
|
93
|
+
items += 1;
|
|
94
|
+
}
|
|
95
|
+
if (!ended)
|
|
96
|
+
throw new TypeError(`${declared.id}: the export ended without its end line`);
|
|
97
|
+
},
|
|
98
|
+
identityOf: async (set, key) => JSON.parse(await lastLine(run(["identity", set, key]))).identity,
|
|
99
|
+
import: async (entries, options) => JSON.parse(await lastLine(run(["import", JSON.stringify(options)], linesOf(entries)))),
|
|
100
|
+
};
|
|
101
|
+
}
|
package/dist/store.d.ts
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import type { DataEntry, Selection } from "./manifest.js";
|
|
2
|
+
import type { DataPurpose, EntryForm, StoreKind, StoreLevel } from "./words.js";
|
|
3
|
+
/** One thing a store cannot do, said with its reason, never left silent. */
|
|
4
|
+
export interface Inability {
|
|
5
|
+
/** What it cannot do, e.g. `import of set audit-log`. */
|
|
6
|
+
readonly what: string;
|
|
7
|
+
/** Why. */
|
|
8
|
+
readonly reason: string;
|
|
9
|
+
}
|
|
10
|
+
/** One set a store holds. */
|
|
11
|
+
export interface StoreSet {
|
|
12
|
+
/** The set name (kebab-case). */
|
|
13
|
+
readonly set: string;
|
|
14
|
+
/** `<format>/<set>@<major>` of a record set, `blob@1` of a blob set. */
|
|
15
|
+
readonly schema: string;
|
|
16
|
+
/** The form of its entries. */
|
|
17
|
+
readonly form: EntryForm;
|
|
18
|
+
}
|
|
19
|
+
/** What a store holds and can do. */
|
|
20
|
+
export interface StoreDescription {
|
|
21
|
+
/** Every set, sorted by name. */
|
|
22
|
+
readonly sets: readonly StoreSet[];
|
|
23
|
+
/** The purposes it serves. */
|
|
24
|
+
readonly purposes: readonly DataPurpose[];
|
|
25
|
+
/** Whether `export` reads anything. */
|
|
26
|
+
readonly canExport: boolean;
|
|
27
|
+
/** Whether `import` writes anything. */
|
|
28
|
+
readonly canImport: boolean;
|
|
29
|
+
/** What it cannot do, each with its reason. */
|
|
30
|
+
readonly cannot: readonly Inability[];
|
|
31
|
+
}
|
|
32
|
+
/** How an import treats what the entries do not name. */
|
|
33
|
+
export interface ImportOptions {
|
|
34
|
+
/** Count what would change and write nothing. */
|
|
35
|
+
readonly dryRun: boolean;
|
|
36
|
+
/**
|
|
37
|
+
* `merge`: create and update by natural key, remove nothing. `mirror`: also remove the keys of the selected sets the
|
|
38
|
+
* entries lack. A mirror is destructive: its caller refuses it without a verified copy of the target younger than the
|
|
39
|
+
* declared maximum age (the reset rule of PROJECT-STACKS-6).
|
|
40
|
+
*/
|
|
41
|
+
readonly mode: "merge" | "mirror";
|
|
42
|
+
/** The narrowing the import writes into, e.g. the workspace a seed is applied to. */
|
|
43
|
+
readonly scope?: Readonly<Record<string, string>>;
|
|
44
|
+
}
|
|
45
|
+
/** A key a door refused, with its code; never a value. */
|
|
46
|
+
export interface RefusedKey {
|
|
47
|
+
/** The natural key. */
|
|
48
|
+
readonly key: string;
|
|
49
|
+
/** The refusal's code. */
|
|
50
|
+
readonly code: string;
|
|
51
|
+
}
|
|
52
|
+
/** What an import did to one set. */
|
|
53
|
+
export interface SetImport {
|
|
54
|
+
/** The set. */
|
|
55
|
+
readonly set: string;
|
|
56
|
+
/** Keys created. */
|
|
57
|
+
readonly created: number;
|
|
58
|
+
/** Keys whose content changed. */
|
|
59
|
+
readonly updated: number;
|
|
60
|
+
/** Keys already equal. */
|
|
61
|
+
readonly unchanged: number;
|
|
62
|
+
/** Keys removed by a mirror. */
|
|
63
|
+
readonly removed: number;
|
|
64
|
+
/** Keys a door refused. */
|
|
65
|
+
readonly refused: readonly RefusedKey[];
|
|
66
|
+
}
|
|
67
|
+
/** What an import did. `unchanged` when nothing moved: the second run of the same import answers it. */
|
|
68
|
+
export interface ImportReport {
|
|
69
|
+
/** Per set, sorted by name. */
|
|
70
|
+
readonly sets: readonly SetImport[];
|
|
71
|
+
/** `unchanged`, `applied`, or `partial` when a door refused a key. */
|
|
72
|
+
readonly outcome: "unchanged" | "applied" | "partial";
|
|
73
|
+
}
|
|
74
|
+
/** A thing that must be kept: one per declared store of `application-stacks.yaml` `data.stores`. */
|
|
75
|
+
export interface StoreAdapter {
|
|
76
|
+
/** The store id the stack manifest declares. */
|
|
77
|
+
readonly id: string;
|
|
78
|
+
/** Its kind, from the closed list. */
|
|
79
|
+
readonly kind: StoreKind;
|
|
80
|
+
/** logical or physical. */
|
|
81
|
+
readonly level: StoreLevel;
|
|
82
|
+
/** What it holds and can do. */
|
|
83
|
+
describe(): Promise<StoreDescription>;
|
|
84
|
+
/** Every entry of the selection, in (set, key) byte order; the same content yields the same stream. */
|
|
85
|
+
export(selection: Selection): AsyncIterable<DataEntry>;
|
|
86
|
+
/**
|
|
87
|
+
* An upsert by natural key through the app's own doors that KEEPS RELATIONS: a key already held is updated in place and
|
|
88
|
+
* keeps its identity (never deleted and re-created), so every reference to it stays valid; the same entries imported
|
|
89
|
+
* twice change nothing the second time; a key the entries do not name is left alone (reported by a mirror, removed
|
|
90
|
+
* only by it); operational data the entries do not carry is never overwritten.
|
|
91
|
+
*/
|
|
92
|
+
import(entries: AsyncIterable<DataEntry>, options: ImportOptions): Promise<ImportReport>;
|
|
93
|
+
/** The store's own identity of the row or object a natural key names (a database id, an object version), or null. The contract suite proves imports keep it. */
|
|
94
|
+
identityOf(set: string, key: string): Promise<string | null>;
|
|
95
|
+
}
|
|
96
|
+
/** The outcome of an import from its per-set counts. */
|
|
97
|
+
export declare function importOutcome(sets: readonly SetImport[]): ImportReport["outcome"];
|
package/dist/store.js
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/** The outcome of an import from its per-set counts. */
|
|
2
|
+
export function importOutcome(sets) {
|
|
3
|
+
if (sets.some((set) => set.refused.length > 0))
|
|
4
|
+
return "partial";
|
|
5
|
+
return sets.some((set) => set.created + set.updated + set.removed > 0) ? "applied" : "unchanged";
|
|
6
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { DriverAdapter, OpenContext, WriteContext } from "../driver.js";
|
|
2
|
+
import type { DataEntry } from "../manifest.js";
|
|
3
|
+
import type { StoreAdapter } from "../store.js";
|
|
4
|
+
/** One case of a contract suite: a name and a body that throws on a broken promise. Run it in any test runner. */
|
|
5
|
+
export interface ContractCase {
|
|
6
|
+
/** What the case proves. */
|
|
7
|
+
readonly name: string;
|
|
8
|
+
/** Throws when the adapter breaks the contract. */
|
|
9
|
+
readonly run: () => Promise<void>;
|
|
10
|
+
}
|
|
11
|
+
/** What a store may state about itself for the suite. */
|
|
12
|
+
export interface StoreContractOptions {
|
|
13
|
+
/** Answers a changed copy of an entry that is still valid for the store; by default a record gains a field and a blob a byte. */
|
|
14
|
+
readonly change?: (entry: DataEntry) => DataEntry;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* The promises every store adapter keeps. `make` builds a fresh store holding at least one entry; `empty` a fresh store of
|
|
18
|
+
* the same kind holding nothing, the target of an import. A real adapter runs this suite against its fakes. A store that
|
|
19
|
+
* holds only typed rows (a database) says in `change` how one of its entries becomes another valid one.
|
|
20
|
+
*/
|
|
21
|
+
export declare function storeContract(make: () => Promise<StoreAdapter>, empty: () => Promise<StoreAdapter>, options?: StoreContractOptions): readonly ContractCase[];
|
|
22
|
+
/**
|
|
23
|
+
* The promises every driver adapter keeps. `make` builds a fresh driver; `store` a store with content to export; `open`
|
|
24
|
+
* the identity a sealed copy is read with (a throwaway test key in a driver's own specs, never a real one).
|
|
25
|
+
*/
|
|
26
|
+
export declare function driverContract(make: () => Promise<DriverAdapter>, store: () => Promise<StoreAdapter>, context: WriteContext, open?: OpenContext): readonly ContractCase[];
|