@guren/orm 2.14.0 → 2.15.1

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,158 @@
1
+ //#region src/migration-guard.d.ts
2
+ /**
3
+ * The destructive-migration guard (RFC 0034): what a migration does that can
4
+ * lose data or break the deploy still running, and whether its file
5
+ * acknowledges that with `-- guren:allow-destructive`. Pure up to
6
+ * `readMigrationSources()`, which is the only part that touches the disk.
7
+ */
8
+ type DestructiveKind = 'drop-table' | 'drop-column' | 'alter-column-type' | 'table-rebuild' | 'rename' | 'truncate' | 'delete-all' | 'drop-schema' | 'drop-partition' | 'drop-cascade' | 'unreadable';
9
+ interface DestructiveStatement {
10
+ kind: DestructiveKind;
11
+ /** 1-based line of the statement's first token in `migration.sql`. */
12
+ line: number;
13
+ /** Normalized as written, schema-qualified when the SQL qualifies it. */
14
+ table?: string;
15
+ column?: string;
16
+ /** One line describing what the statement does. */
17
+ message: string;
18
+ /** A rebuild's `INSERT INTO __new_x(cols) SELECT cols FROM x`, when it copies each column to itself and nothing else touches the copy. */
19
+ copiedColumns?: string[];
20
+ /** A type change's target type as the SQL spells it, when it converts by a plain cast to that type and nothing else. */
21
+ targetType?: string;
22
+ /** A rebuild's copy, each column's type as its `CREATE TABLE __new_x` spells it: what runs, whatever the snapshot says. */
23
+ copiedColumnTypes?: Record<string, string>;
24
+ }
25
+ interface MigrationAcknowledgement {
26
+ line: number;
27
+ /** The text after `guren:allow-destructive:`, absent when none was given. */
28
+ reason?: string;
29
+ }
30
+ interface MigrationScan {
31
+ statements: DestructiveStatement[];
32
+ acknowledged: MigrationAcknowledgement | null;
33
+ /** Tables a `CREATE TABLE` creates, with the line of each, in file order. */
34
+ creates: Array<{
35
+ table: string;
36
+ line: number;
37
+ }>;
38
+ /** Tables a `REFERENCES` in the SQL names with `ON DELETE CASCADE`, `SET NULL` or `SET DEFAULT`. */
39
+ cascadeTargets: string[];
40
+ }
41
+ /** How a migration's SQL is lexed: strings, comments and quoting differ by dialect. */
42
+ type MigrationDialect = 'postgres' | 'mysql' | 'sqlite';
43
+ interface ScanOptions {
44
+ /** Unknown: the SQL is read as each dialect would read it, and every reading's findings count. */
45
+ dialect?: MigrationDialect;
46
+ }
47
+ declare const ALLOW_DESTRUCTIVE_MARKER = "guren:allow-destructive";
48
+ /** One-run override of `destructiveMigrations: 'refuse'`, which `guren db:migrate --allow-destructive` sets. */
49
+ declare const ALLOW_DESTRUCTIVE_ENV = "GUREN_ALLOW_DESTRUCTIVE_MIGRATIONS";
50
+ /**
51
+ * Every destructive statement in one migration file, and its acknowledgement.
52
+ * Every way the dialect's server may read the SQL (each dialect's, when none is
53
+ * named) is taken and merged so that none can hide a statement: every finding
54
+ * counts, while exemption evidence, a create and the marker count only when
55
+ * every reading has them.
56
+ */
57
+ declare function scanMigrationSql(sql: string, { dialect }?: ScanOptions): MigrationScan;
58
+ /**
59
+ * Column types from a drizzle-kit 1.x `snapshot.json`, keyed by schema, table and
60
+ * column exactly as the snapshot names them (no case folding), so `archive.posts`
61
+ * never borrows `public.posts`'s evidence. Read through `columnType()`.
62
+ */
63
+ type ColumnTypes = ReadonlyMap<string, string>;
64
+ declare function readSnapshotColumnTypes(snapshot: unknown): ColumnTypes | undefined;
65
+ /**
66
+ * Whether `after` holds every value `before` holds: a closed list, so a pair
67
+ * it does not name is not widening. Equal types (a MySQL `MODIFY` that only
68
+ * changes nullability) count, since no value changes.
69
+ */
70
+ declare function isWideningTypeChange(before: string, after: string, dialect?: MigrationDialect): boolean;
71
+ interface MigrationSource {
72
+ /** The migration folder's name, as the tracker records it. */
73
+ name: string;
74
+ /** How a finding names the file: `db/migrations/<name>/migration.sql`. */
75
+ file: string;
76
+ scan: MigrationScan;
77
+ /** Column types after this migration, and before it, when its snapshots read. */
78
+ columnTypes?: {
79
+ before?: ColumnTypes;
80
+ after?: ColumnTypes;
81
+ };
82
+ /** Foreign keys after this migration, and before it, when its snapshots read. */
83
+ foreignKeys?: {
84
+ before?: ForeignKeyReference[];
85
+ after?: ForeignKeyReference[];
86
+ };
87
+ /** The dialect the SQL was read in, when the driver or the snapshot names one. */
88
+ dialect?: MigrationDialect;
89
+ }
90
+ interface ForeignKeyReference {
91
+ tableTo: string;
92
+ /** As the snapshot spells it: `CASCADE`, `SET NULL`, `NO ACTION`, … */
93
+ onDelete: string;
94
+ }
95
+ interface DestructiveFinding extends DestructiveStatement {
96
+ migration: string;
97
+ file: string;
98
+ }
99
+ interface MigrationGuardReport {
100
+ /** Findings in migrations that carry no marker; the ones a guard refuses on. */
101
+ unacknowledged: DestructiveFinding[];
102
+ /** Migrations whose findings the marker covers, with its reason. */
103
+ acknowledged: Array<{
104
+ migration: string;
105
+ file: string;
106
+ reason?: string;
107
+ findings: DestructiveFinding[];
108
+ }>;
109
+ }
110
+ interface JudgeOptions {
111
+ /**
112
+ * Exempt a finding against a table an earlier statement of the run creates.
113
+ * Sound only when `sources` are exactly the pending migrations: over a
114
+ * superset (pending unknown), an applied `CREATE` would exempt a new `DROP`.
115
+ */
116
+ exemptCreatedInRun?: boolean;
117
+ /**
118
+ * Whether a rebuild's `DROP TABLE` fires the `ON DELETE` of the tables
119
+ * referencing it. Only a runner that turns foreign keys off around the
120
+ * migration (bun:sqlite's) may say no; Cloudflare D1 keeps them on.
121
+ */
122
+ foreignKeysEnforced?: boolean;
123
+ }
124
+ /**
125
+ * Judges migrations in the order they would be applied. A finding against a
126
+ * table an earlier statement of the run creates is dropped (a fresh database
127
+ * loses nothing), and so is a type change the snapshots show widening.
128
+ */
129
+ declare function judgeMigrations(sources: readonly MigrationSource[], { exemptCreatedInRun, foreignKeysEnforced }?: JudgeOptions): MigrationGuardReport;
130
+ /**
131
+ * Reads `<folder>/<name>/migration.sql` for each name, plus the snapshots a
132
+ * type change needs. Throws when a migration file cannot be read: a guard that
133
+ * skipped it would pass exactly the file it could not judge.
134
+ */
135
+ declare function readMigrationSources(migrationsFolder: string, names: readonly string[], displayFolder?: string, { dialect }?: ScanOptions): MigrationSource[];
136
+ /** One finding as `file:line: message`, the form every guard prints. */
137
+ declare function formatDestructiveFinding(finding: DestructiveFinding): string;
138
+ /** What a factory does with a pending destructive statement no marker covers (RFC 0034). */
139
+ type DestructiveMigrationMode = 'warn' | 'refuse';
140
+ declare class DestructiveMigrationError extends Error {
141
+ readonly findings: DestructiveFinding[];
142
+ /** `trackerError`: why the tracker could not be read, kept as the `cause` so a connection failure is not hidden behind the findings. */
143
+ constructor(findings: DestructiveFinding[], pendingKnown?: boolean, trackerError?: unknown);
144
+ }
145
+ /**
146
+ * The boot-path guard: judges the pending migrations before the migrator runs.
147
+ * `refuse` throws unless `GUREN_ALLOW_DESTRUCTIVE_MIGRATIONS=1`; `warn`, and an
148
+ * allowed `refuse`, print the findings and return.
149
+ */
150
+ declare function guardPendingMigrations(migrationsFolder: string, pending: readonly string[], mode: DestructiveMigrationMode, { pendingKnown, trackerError, dialect, foreignKeysEnforced }?: {
151
+ pendingKnown?: boolean;
152
+ /** Why the tracker could not be read, when `pendingKnown` is false. */
153
+ trackerError?: unknown;
154
+ dialect?: MigrationDialect;
155
+ foreignKeysEnforced?: boolean;
156
+ }): void;
157
+ //#endregion
158
+ export { ALLOW_DESTRUCTIVE_ENV, ALLOW_DESTRUCTIVE_MARKER, ColumnTypes, DestructiveFinding, DestructiveKind, DestructiveMigrationError, DestructiveMigrationMode, DestructiveStatement, ForeignKeyReference, JudgeOptions, MigrationAcknowledgement, MigrationDialect, MigrationGuardReport, MigrationScan, MigrationSource, ScanOptions, formatDestructiveFinding, guardPendingMigrations, isWideningTypeChange, judgeMigrations, readMigrationSources, readSnapshotColumnTypes, scanMigrationSql };