@peridotvault/peridotbase-sdk 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.
@@ -0,0 +1,68 @@
1
+ import { PeridotBase } from "./client";
2
+ import { ColumnSpec } from "./values";
3
+ import { Statement } from "./sql";
4
+ export interface MigrationFile {
5
+ version: bigint;
6
+ name: string;
7
+ path: string;
8
+ sql: string;
9
+ checksum: string;
10
+ }
11
+ export interface MigrationResult {
12
+ version: string;
13
+ name: string;
14
+ checksum: string;
15
+ applied: boolean;
16
+ signature?: string;
17
+ }
18
+ /**
19
+ * Applies every unapplied `NNNN_name.sql` file in version order and records
20
+ * its SHA-256 in an on-chain journal table. Reapplying an applied version with
21
+ * different contents fails instead of silently diverging.
22
+ */
23
+ export declare function runMigrations(client: PeridotBase, input: string | string[], options?: {
24
+ dryRun?: boolean;
25
+ now?: () => number;
26
+ }): Promise<MigrationResult[]>;
27
+ export interface SchemaDiff {
28
+ createTables: Statement[];
29
+ addColumns: {
30
+ table: string;
31
+ columns: ColumnSpec[];
32
+ }[];
33
+ createIndexes: Statement[];
34
+ unchanged: string[];
35
+ destructive: {
36
+ table: string;
37
+ reason: string;
38
+ }[];
39
+ conflicts: {
40
+ table: string;
41
+ reason: string;
42
+ }[];
43
+ }
44
+ /** Compares a declarative SQL file against the live database (read-only). */
45
+ export declare function diffSchema(client: PeridotBase, sql: string): Promise<SchemaDiff>;
46
+ /**
47
+ * Applies the additive part of a schema diff. Destructive entries are reported,
48
+ * never executed: dropping a table or column is an explicit operator action.
49
+ */
50
+ export declare function applySchemaDiff(client: PeridotBase, diff: SchemaDiff): Promise<{
51
+ created: string[];
52
+ altered: string[];
53
+ indexed: string[];
54
+ skipped: string[];
55
+ }>;
56
+ /** Renders the parsed subset back to SQL for re-execution. */
57
+ export declare function renderStatement(statement: Statement): string;
58
+ /** Restores a `dumpDatabase()` document into an empty database. */
59
+ export declare function restoreDatabase(client: PeridotBase, dump: any, options?: {
60
+ allowExistingEmpty?: boolean;
61
+ }): Promise<{
62
+ restored: string[];
63
+ skipped: string[];
64
+ }>;
65
+ /** Generates TypeScript row interfaces and a table-name map from live schema. */
66
+ export declare function generateTypes(client: PeridotBase): Promise<string>;
67
+ /** Mermaid ER diagram of the live schema and supported FKs. */
68
+ export declare function schemaDiagram(client: PeridotBase): Promise<string>;
@@ -0,0 +1,432 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.runMigrations = runMigrations;
4
+ exports.diffSchema = diffSchema;
5
+ exports.applySchemaDiff = applySchemaDiff;
6
+ exports.renderStatement = renderStatement;
7
+ exports.restoreDatabase = restoreDatabase;
8
+ exports.generateTypes = generateTypes;
9
+ exports.schemaDiagram = schemaDiagram;
10
+ /**
11
+ * Developer tooling layered on top of the SDK: versioned SQL migrations,
12
+ * schema diff/declarative apply, dump restore and TypeScript type generation.
13
+ *
14
+ * These helpers never weaken on-chain constraints: diff refuses destructive
15
+ * changes, restore refuses a non-empty target table, and migrations are
16
+ * checksum-locked after they are applied.
17
+ */
18
+ const crypto_1 = require("crypto");
19
+ const fs_1 = require("fs");
20
+ const path_1 = require("path");
21
+ const sql_1 = require("./sql");
22
+ const MIGRATION_TABLE = "_peridotbase_migrations";
23
+ const MIGRATION_COLUMNS = [
24
+ { name: "version", type: "i64", nullable: false },
25
+ { name: "name", type: "text", nullable: false },
26
+ { name: "checksum", type: "text", nullable: false },
27
+ { name: "applied_at", type: "i64", nullable: false },
28
+ ];
29
+ function checksumOf(text) {
30
+ return (0, crypto_1.createHash)("sha256").update(text, "utf8").digest("hex");
31
+ }
32
+ function loadMigrationFiles(input) {
33
+ const paths = Array.isArray(input)
34
+ ? input
35
+ : (0, fs_1.statSync)(input).isDirectory()
36
+ ? (0, fs_1.readdirSync)(input)
37
+ .filter((name) => name.endsWith(".sql"))
38
+ .sort()
39
+ .map((name) => (0, path_1.join)(input, name))
40
+ : [input];
41
+ const files = [];
42
+ for (const path of paths) {
43
+ const base = path.split("/").pop() ?? path;
44
+ const match = /^(\d+)[_-](.+)\.sql$/i.exec(base);
45
+ if (!match) {
46
+ throw new Error(`migration filename must look like 0001_name.sql (got ${base})`);
47
+ }
48
+ const sql = (0, fs_1.readFileSync)(path, "utf8");
49
+ files.push({
50
+ version: BigInt(match[1]),
51
+ name: match[2],
52
+ path,
53
+ sql,
54
+ checksum: checksumOf(sql),
55
+ });
56
+ }
57
+ files.sort((a, b) => (a.version < b.version ? -1 : a.version > b.version ? 1 : 0));
58
+ for (let index = 1; index < files.length; index += 1) {
59
+ if (files[index].version === files[index - 1].version) {
60
+ throw new Error(`duplicate migration version ${files[index].version}`);
61
+ }
62
+ }
63
+ return files;
64
+ }
65
+ async function migrationTable(client) {
66
+ const tables = await client.loadTables();
67
+ if (!tables.some((table) => table.name === MIGRATION_TABLE)) {
68
+ await client.createTable({
69
+ tableId: await client.nextTableId(),
70
+ name: MIGRATION_TABLE,
71
+ columns: MIGRATION_COLUMNS,
72
+ constraints: [{ kind: "primaryKey", column: "version" }],
73
+ });
74
+ }
75
+ return client.table(MIGRATION_TABLE);
76
+ }
77
+ /**
78
+ * Applies every unapplied `NNNN_name.sql` file in version order and records
79
+ * its SHA-256 in an on-chain journal table. Reapplying an applied version with
80
+ * different contents fails instead of silently diverging.
81
+ */
82
+ async function runMigrations(client, input, options = {}) {
83
+ const files = loadMigrationFiles(input);
84
+ const journal = await migrationTable(client);
85
+ const appliedRows = await journal.selectObjects();
86
+ const applied = new Map();
87
+ for (const row of appliedRows) {
88
+ applied.set(String(row.version), {
89
+ checksum: String(row.checksum),
90
+ name: String(row.name),
91
+ });
92
+ }
93
+ const results = [];
94
+ for (const file of files) {
95
+ const prior = applied.get(file.version.toString());
96
+ if (prior) {
97
+ if (prior.checksum !== file.checksum) {
98
+ throw new Error(`migration ${file.version} (${file.name}) was already applied with checksum ${prior.checksum}; refusing changed contents ${file.checksum}`);
99
+ }
100
+ results.push({
101
+ version: file.version.toString(),
102
+ name: file.name,
103
+ checksum: file.checksum,
104
+ applied: false,
105
+ });
106
+ continue;
107
+ }
108
+ if (options.dryRun) {
109
+ results.push({
110
+ version: file.version.toString(),
111
+ name: file.name,
112
+ checksum: file.checksum,
113
+ applied: false,
114
+ });
115
+ continue;
116
+ }
117
+ // Run the migration body and journal row in one SDK batch. If any statement
118
+ // fails, the unflushed writes are discarded by `execute` before landing.
119
+ const body = await client.execute(file.sql);
120
+ const journalWrite = await client.execute(`INSERT INTO ${MIGRATION_TABLE} (version, name, checksum, applied_at) VALUES ($1, $2, $3, $4)`, [
121
+ file.version,
122
+ file.name,
123
+ file.checksum,
124
+ BigInt(Math.floor((options.now?.() ?? Date.now()) / 1000)),
125
+ ]);
126
+ const signature = (Array.isArray(body) ? body.find((entry) => entry?.signature)?.signature : body?.signature) ??
127
+ (Array.isArray(journalWrite)
128
+ ? journalWrite.find((entry) => entry?.signature)?.signature
129
+ : journalWrite?.signature);
130
+ results.push({
131
+ version: file.version.toString(),
132
+ name: file.name,
133
+ checksum: file.checksum,
134
+ applied: true,
135
+ signature,
136
+ });
137
+ }
138
+ return results;
139
+ }
140
+ function columnMatches(live, wanted) {
141
+ return (live.type === wanted.type &&
142
+ (live.scale ?? 0) === (wanted.scale ?? 0) &&
143
+ (live.maxLen ?? 0) === (wanted.maxLen ?? 0));
144
+ }
145
+ /** Compares a declarative SQL file against the live database (read-only). */
146
+ async function diffSchema(client, sql) {
147
+ const desired = (0, sql_1.parseSql)(sql).filter((statement) => statement.kind === "createTable" || statement.kind === "createIndex");
148
+ const live = await client.loadTables();
149
+ const byName = new Map(live.map((table) => [table.name, table]));
150
+ const wantedTables = new Set(desired.filter((statement) => statement.kind === "createTable").map((statement) => statement.name));
151
+ const planned = new Set();
152
+ const diff = {
153
+ createTables: [],
154
+ addColumns: [],
155
+ createIndexes: [],
156
+ unchanged: [],
157
+ destructive: [],
158
+ conflicts: [],
159
+ };
160
+ for (const statement of desired) {
161
+ if (statement.kind === "createTable") {
162
+ const table = byName.get(statement.name);
163
+ if (!table) {
164
+ diff.createTables.push(statement);
165
+ planned.add(statement.name);
166
+ continue;
167
+ }
168
+ const missing = [];
169
+ for (const column of statement.columns) {
170
+ const current = table.columns.find((candidate) => candidate.name === column.name);
171
+ if (!current)
172
+ missing.push(column);
173
+ else if (!columnMatches(current, column)) {
174
+ diff.conflicts.push({
175
+ table: statement.name,
176
+ reason: `column ${column.name} is ${current.type}(${current.scale ?? 0}) on-chain, ${column.type}(${column.scale ?? 0}) declared`,
177
+ });
178
+ }
179
+ }
180
+ if (missing.length > 0)
181
+ diff.addColumns.push({ table: statement.name, columns: missing });
182
+ diff.unchanged.push(statement.name);
183
+ }
184
+ else {
185
+ const table = byName.get(statement.table);
186
+ if (!table) {
187
+ if (planned.has(statement.table)) {
188
+ diff.createIndexes.push(statement);
189
+ continue;
190
+ }
191
+ diff.conflicts.push({
192
+ table: statement.table,
193
+ reason: `cannot create index ${statement.name} before its table exists`,
194
+ });
195
+ continue;
196
+ }
197
+ const exists = table.indexes.some((index) => index.name === statement.name);
198
+ if (exists)
199
+ continue;
200
+ if (table.rowCount > 0n) {
201
+ diff.conflicts.push({
202
+ table: statement.table,
203
+ reason: `index ${statement.name} cannot be created on a table with ${table.rowCount} rows; on-chain indexes are built at table creation and have no backfill path`,
204
+ });
205
+ continue;
206
+ }
207
+ diff.createIndexes.push(statement);
208
+ }
209
+ }
210
+ for (const table of live) {
211
+ if (table.name.startsWith("_peridotbase_"))
212
+ continue;
213
+ if (!wantedTables.has(table.name)) {
214
+ diff.destructive.push({
215
+ table: table.name,
216
+ reason: "table exists on-chain but is absent from the declarative schema; DROP TABLE is not supported",
217
+ });
218
+ }
219
+ }
220
+ if (diff.conflicts.length > 0) {
221
+ throw new Error(`declarative schema conflicts with on-chain state:\n${diff.conflicts
222
+ .map((entry) => `- ${entry.table}: ${entry.reason}`)
223
+ .join("\n")}`);
224
+ }
225
+ return diff;
226
+ }
227
+ /**
228
+ * Applies the additive part of a schema diff. Destructive entries are reported,
229
+ * never executed: dropping a table or column is an explicit operator action.
230
+ */
231
+ async function applySchemaDiff(client, diff) {
232
+ const created = [];
233
+ const altered = [];
234
+ const indexed = [];
235
+ for (const statement of diff.createTables) {
236
+ const result = await client.execute(renderStatement(statement));
237
+ created.push(result?.name ?? statement.name);
238
+ }
239
+ for (const change of diff.addColumns) {
240
+ const table = await client.table(change.table);
241
+ await client.alterTable(table.model.tableId, change.columns);
242
+ altered.push(change.table);
243
+ }
244
+ for (const statement of diff.createIndexes) {
245
+ await client.execute(renderStatement(statement));
246
+ indexed.push(statement.name);
247
+ }
248
+ return { created, altered, indexed, skipped: diff.destructive.map((entry) => entry.table) };
249
+ }
250
+ function renderColumn(column) {
251
+ let type = column.type.toUpperCase();
252
+ if (column.type === "decimal")
253
+ type = `DECIMAL(38, ${column.scale ?? 0})`;
254
+ else if (["text", "bit", "varbit"].includes(column.type) && column.maxLen !== undefined) {
255
+ type = `${type}(${column.maxLen})`;
256
+ }
257
+ const nullable = column.nullable === false ? " NOT NULL" : "";
258
+ return `${column.name} ${type}${nullable}`;
259
+ }
260
+ /** Renders the parsed subset back to SQL for re-execution. */
261
+ function renderStatement(statement) {
262
+ switch (statement.kind) {
263
+ case "createTable": {
264
+ const parts = statement.columns.map(renderColumn);
265
+ for (const constraint of statement.constraints) {
266
+ if (constraint.kind === "primaryKey")
267
+ parts.push(`PRIMARY KEY (${constraint.column})`);
268
+ else if (constraint.kind === "unique")
269
+ parts.push(`UNIQUE (${constraint.column})`);
270
+ else if (constraint.kind === "compositePrimaryKey") {
271
+ parts.push(`PRIMARY KEY (${constraint.columns.join(", ")})`);
272
+ }
273
+ else if (constraint.kind === "compositeUnique") {
274
+ parts.push(`UNIQUE (${constraint.columns.join(", ")})`);
275
+ }
276
+ else {
277
+ throw new Error("CHECK constraints cannot be rendered; apply them through createTable");
278
+ }
279
+ }
280
+ return `CREATE TABLE ${statement.name} (${parts.join(", ")})`;
281
+ }
282
+ case "createIndex":
283
+ return `CREATE ${statement.unique ? "UNIQUE " : ""}INDEX ${statement.name} ON ${statement.table} (${statement.columns.join(", ")})`;
284
+ default:
285
+ throw new Error(`cannot render ${statement.kind} from a declarative schema`);
286
+ }
287
+ }
288
+ /** Restores a `dumpDatabase()` document into an empty database. */
289
+ async function restoreDatabase(client, dump, options = {}) {
290
+ if (!dump || dump.version !== 1 || !Array.isArray(dump.tables)) {
291
+ throw new Error("unsupported dump format (expected version 1)");
292
+ }
293
+ const live = new Map((await client.loadTables()).map((table) => [table.name, table]));
294
+ const restored = [];
295
+ const skipped = [];
296
+ for (const table of dump.tables) {
297
+ const existing = live.get(table.name);
298
+ if (existing) {
299
+ if (existing.rowCount > 0n || !options.allowExistingEmpty) {
300
+ throw new Error(`restore target table ${table.name} already exists with ${existing.rowCount} rows; refusing to merge`);
301
+ }
302
+ skipped.push(table.name);
303
+ continue;
304
+ }
305
+ const columns = table.columns.map((column) => ({
306
+ name: column.name,
307
+ type: column.type,
308
+ nullable: column.nullable,
309
+ scale: column.scale,
310
+ maxLen: column.maxLen,
311
+ default: column.default,
312
+ }));
313
+ const target = await client.createTable({
314
+ tableId: await client.nextTableId(),
315
+ name: table.name,
316
+ columns,
317
+ constraintDefs: (table.constraints ?? [])
318
+ .filter((constraint) => [
319
+ "primaryKey",
320
+ "notNull",
321
+ "unique",
322
+ "check",
323
+ "generatedStored",
324
+ "generatedVirtual",
325
+ "compositePrimaryKey",
326
+ "appendOnly",
327
+ "denyDelete",
328
+ "denyUpdate",
329
+ "immutable",
330
+ "freezePolicies",
331
+ "policyTimelock",
332
+ ].includes(constraint.kind))
333
+ .map((constraint) => ({
334
+ kind: constraint.kind,
335
+ column: constraint.column,
336
+ expr: Buffer.from(constraint.expr ?? "", "hex"),
337
+ })),
338
+ indexes: (table.indexes ?? []).map((index) => {
339
+ const keyColumns = (index.columns?.length ? index.columns : [index.column]).map((position) => columns[position]?.name ?? table.columns[position]?.name);
340
+ return {
341
+ indexId: BigInt(index.indexId),
342
+ name: index.name,
343
+ columns: keyColumns,
344
+ include: (index.includes ?? []).map((position) => columns[position]?.name ?? table.columns[position]?.name),
345
+ unique: index.unique,
346
+ bucketCount: index.bucketCount,
347
+ nullsNotDistinct: index.nullsNotDistinct,
348
+ };
349
+ }),
350
+ });
351
+ if (Array.isArray(table.rows) && table.rows.length > 0) {
352
+ await target.insert(table.rows);
353
+ }
354
+ restored.push(table.name);
355
+ }
356
+ return { restored, skipped };
357
+ }
358
+ const TS_TYPES = {
359
+ bool: "boolean",
360
+ i64: "bigint | number",
361
+ decimal: "string",
362
+ text: "string",
363
+ uuid: "string",
364
+ date: "string",
365
+ timestamp: "string",
366
+ interval: "string",
367
+ address: "string",
368
+ inet: "string",
369
+ cidr: "string",
370
+ macaddr: "string",
371
+ bit: "string",
372
+ varbit: "string",
373
+ range: "string",
374
+ numrange: "string",
375
+ tsrange: "string",
376
+ daterange: "string",
377
+ time: "string",
378
+ };
379
+ function pascal(name) {
380
+ return name
381
+ .split(/[^A-Za-z0-9]+/)
382
+ .filter(Boolean)
383
+ .map((part) => part[0].toUpperCase() + part.slice(1))
384
+ .join("");
385
+ }
386
+ /** Generates TypeScript row interfaces and a table-name map from live schema. */
387
+ async function generateTypes(client) {
388
+ const tables = (await client.loadTables()).filter((table) => !table.name.startsWith("_peridotbase_"));
389
+ const lines = [
390
+ "// Generated by @peridotvault/peridotbase-sdk. Do not edit by hand.",
391
+ "",
392
+ ];
393
+ for (const table of tables) {
394
+ lines.push(`export interface ${pascal(table.name)}Row {`);
395
+ for (const column of table.columns) {
396
+ const optional = column.nullable === false ? "" : " | null";
397
+ lines.push(` ${column.name}: ${TS_TYPES[column.type]}${optional};`);
398
+ }
399
+ lines.push("}", "");
400
+ }
401
+ lines.push("export interface PeridotbaseTables {");
402
+ for (const table of tables) {
403
+ lines.push(` ${table.name}: ${pascal(table.name)}Row;`);
404
+ }
405
+ lines.push("}", "");
406
+ return lines.join("\n");
407
+ }
408
+ /** Mermaid ER diagram of the live schema and supported FKs. */
409
+ async function schemaDiagram(client) {
410
+ const tables = (await client.loadTables()).filter((table) => !table.name.startsWith("_peridotbase_"));
411
+ const byAddress = new Map(tables.map((table) => [Buffer.from(table.address.toBytes()).toString("hex"), table]));
412
+ const lines = ["erDiagram"];
413
+ for (const table of tables) {
414
+ lines.push(` ${table.name} {`);
415
+ for (const column of table.columns) {
416
+ lines.push(` ${column.type} ${column.name}`);
417
+ }
418
+ lines.push(" }");
419
+ }
420
+ for (const table of tables) {
421
+ for (const constraint of table.constraints) {
422
+ if (constraint.kind !== "foreignKey" || constraint.expr.length < 32)
423
+ continue;
424
+ const parent = byAddress.get(constraint.expr.subarray(0, 32).toString("hex"));
425
+ if (!parent)
426
+ continue;
427
+ const childColumn = table.columns[constraint.column]?.name ?? `column_${constraint.column}`;
428
+ lines.push(` ${parent.name} ||--o{ ${table.name} : "${childColumn}"`);
429
+ }
430
+ }
431
+ return lines.join("\n");
432
+ }