@sedrino/db-schema 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -379,6 +379,19 @@ type MigrationMeta = {
     name: string;
     description?: string;
 };
+type MigrationSqlExpression = {
+    sql: string;
+};
+type AlterFieldPatch = {
+    logical?: LogicalTypeSpec;
+    storage?: StorageSpec;
+    column?: string;
+    nullable?: boolean;
+    default?: DefaultSpec | null;
+    unique?: boolean;
+    description?: string | null;
+    references?: FieldReferenceSpec | null;
+};
 type MigrationOperation = {
     kind: "createTable";
     table: TableSpec;
@@ -393,6 +406,7 @@ type MigrationOperation = {
     kind: "addField";
     tableName: string;
     field: FieldSpec;
+    backfill?: MigrationSqlExpression;
 } | {
     kind: "dropField";
     tableName: string;
@@ -402,6 +416,12 @@ type MigrationOperation = {
     tableName: string;
     from: string;
     to: string;
+} | {
+    kind: "alterField";
+    tableName: string;
+    fieldName: string;
+    patch: AlterFieldPatch;
+    transform?: MigrationSqlExpression;
 } | {
     kind: "addIndex";
     tableName: string;
@@ -429,9 +449,39 @@ type FieldOptions = {
     storage?: StorageSpec;
     references?: FieldReferenceSpec;
 };
+type BelongsToOptions = Omit<FieldOptions, "references"> & {
+    fieldName?: string;
+    referencesField?: string;
+    required?: boolean;
+    unique?: boolean;
+    index?: boolean;
+    indexName?: string;
+    onDelete?: FieldReferenceSpec["onDelete"];
+    onUpdate?: FieldReferenceSpec["onUpdate"];
+};
+type JunctionSideOptions = {
+    table: string;
+    fieldName?: string;
+    referencesField?: string;
+    description?: string;
+    onDelete?: FieldReferenceSpec["onDelete"];
+    onUpdate?: FieldReferenceSpec["onUpdate"];
+};
+type CreateJunctionTableOptions = {
+    description?: string;
+    left: JunctionSideOptions;
+    right: JunctionSideOptions;
+    unique?: boolean;
+    uniqueName?: string;
+    indexes?: boolean;
+};
+type FieldBuilderHooks = {
+    setBackfillSql?: (sql: string) => void;
+};
 declare class MutableFieldBuilder {
     private field;
-    constructor(field: FieldSpec);
+    private readonly hooks;
+    constructor(field: FieldSpec, hooks?: FieldBuilderHooks);
     required(): this;
     nullable(): this;
     unique(): this;
@@ -440,6 +490,8 @@ declare class MutableFieldBuilder {
     references(reference: FieldReferenceSpec): this;
     description(description: string): this;
     column(column: string): this;
+    backfillSql(expression: string | MigrationSqlExpression): this;
+    backfill(expression: string | MigrationSqlExpression): this;
     build(): {
         id: string;
         name: string;
@@ -505,6 +557,44 @@ declare class MutableFieldBuilder {
         } | undefined;
     };
 }
+type AlterFieldOptions = {
+    column?: string;
+    storage?: StorageSpec;
+};
+declare class AlterFieldBuilder {
+    readonly patch: AlterFieldPatch;
+    transform?: MigrationSqlExpression;
+    required(): this;
+    nullable(): this;
+    unique(): this;
+    notUnique(): this;
+    default(value: string | number | boolean | null): this;
+    defaultNow(): this;
+    dropDefault(): this;
+    references(reference: FieldReferenceSpec): this;
+    dropReferences(): this;
+    description(description: string): this;
+    dropDescription(): this;
+    column(column: string): this;
+    storage(storage: StorageSpec): this;
+    usingSql(expression: string | MigrationSqlExpression): this;
+    using(expression: string | MigrationSqlExpression): this;
+    logical(logical: LogicalTypeSpec, options?: AlterFieldOptions): this;
+    string(options?: AlterFieldOptions & {
+        format?: "email" | "url" | "slug";
+    }): this;
+    text(options?: AlterFieldOptions): this;
+    boolean(options?: AlterFieldOptions): this;
+    integer(options?: AlterFieldOptions): this;
+    number(options?: AlterFieldOptions): this;
+    enum(values: string[], options?: AlterFieldOptions): this;
+    json(tsType: string, options?: AlterFieldOptions): this;
+    temporalInstant(options?: AlterFieldOptions): this;
+    temporalPlainDate(options?: AlterFieldOptions): this;
+    reference(options: AlterFieldOptions & {
+        references: FieldReferenceSpec;
+    }): this;
+}
 declare class TableCreateBuilder {
     private readonly tableName;
     private readonly fields;
@@ -531,6 +621,7 @@ declare class TableCreateBuilder {
     reference(fieldName: string, options: Omit<FieldOptions, "references"> & {
         references: FieldReferenceSpec;
     }): MutableFieldBuilder;
+    belongsTo(targetTable: string, options?: BelongsToOptions): MutableFieldBuilder;
     index(fields: string[], options?: {
         name?: string;
     }): this;
@@ -558,8 +649,10 @@ declare class TableAlterBuilder {
     reference(fieldName: string, options: Omit<FieldOptions, "references"> & {
         references: FieldReferenceSpec;
     }): MutableFieldBuilder;
+    belongsTo(targetTable: string, options?: BelongsToOptions): MutableFieldBuilder;
     dropField(fieldName: string): this;
     renameField(from: string, to: string): this;
+    alterField(fieldName: string, callback: (field: AlterFieldBuilder) => void): this;
     addIndex(fields: string[], options?: {
         name?: string;
     }): this;
@@ -572,12 +665,96 @@ declare class TableAlterBuilder {
 declare class MigrationBuilderImpl {
     readonly operations: MigrationOperation[];
     createTable(name: string, callback: (table: TableCreateBuilder) => void): this;
+    createJunctionTable(name: string, options: CreateJunctionTableOptions): this;
     dropTable(tableName: string): this;
     renameTable(from: string, to: string): this;
     alterTable(tableName: string, callback: (table: TableAlterBuilder) => void): this;
 }
 declare function createMigration(meta: MigrationMeta, callback: (migration: MigrationBuilderImpl) => void): MigrationDefinition;
 
+declare function applyOperationsToSchema(schemaInput: DatabaseSchemaDocument, operations: MigrationOperation[]): {
+    version: 1;
+    dialect: "sqlite";
+    schemaId: string;
+    tables: {
+        id: string;
+        name: string;
+        fields: {
+            id: string;
+            name: string;
+            logical: {
+                kind: "id";
+                prefix: string;
+            } | {
+                kind: "string";
+                format?: "email" | "url" | "slug" | undefined;
+            } | {
+                kind: "text";
+            } | {
+                kind: "boolean";
+            } | {
+                kind: "integer";
+            } | {
+                kind: "number";
+            } | {
+                kind: "enum";
+                values: string[];
+            } | {
+                kind: "json";
+                tsType: string;
+            } | {
+                kind: "temporal.instant";
+            } | {
+                kind: "temporal.plainDate";
+            };
+            storage: {
+                strategy: "sqlite.text";
+                column: string;
+            } | {
+                strategy: "sqlite.integer";
+                column: string;
+            } | {
+                strategy: "sqlite.real";
+                column: string;
+            } | {
+                strategy: "sqlite.temporalInstantEpochMs";
+                column: string;
+            } | {
+                strategy: "sqlite.temporalPlainDateText";
+                column: string;
+            };
+            nullable: boolean;
+            primaryKey: boolean;
+            unique: boolean;
+            default?: {
+                kind: "literal";
+                value: string | number | boolean | null;
+            } | {
+                kind: "now";
+            } | {
+                kind: "generatedId";
+                prefix: string;
+            } | undefined;
+            description?: string | undefined;
+            references?: {
+                table: string;
+                field: string;
+                onDelete?: "cascade" | "restrict" | "set null" | "set default" | "no action" | undefined;
+                onUpdate?: "cascade" | "restrict" | "set null" | "set default" | "no action" | undefined;
+            } | undefined;
+        }[];
+        indexes: {
+            fields: string[];
+            name?: string | undefined;
+        }[];
+        uniques: {
+            fields: string[];
+            name?: string | undefined;
+        }[];
+        description?: string | undefined;
+    }[];
+};
+
 type PlannedMigration = {
     migrationId: string;
     migrationName: string;
@@ -682,97 +859,76 @@ declare function materializeSchema(args: {
     };
     plans: PlannedMigration[];
 };
-declare function applyOperationsToSchema(schemaInput: DatabaseSchemaDocument, operations: MigrationOperation[]): {
-    version: 1;
-    dialect: "sqlite";
-    schemaId: string;
-    tables: {
-        id: string;
-        name: string;
-        fields: {
-            id: string;
-            name: string;
-            logical: {
-                kind: "id";
-                prefix: string;
-            } | {
-                kind: "string";
-                format?: "email" | "url" | "slug" | undefined;
-            } | {
-                kind: "text";
-            } | {
-                kind: "boolean";
-            } | {
-                kind: "integer";
-            } | {
-                kind: "number";
-            } | {
-                kind: "enum";
-                values: string[];
-            } | {
-                kind: "json";
-                tsType: string;
-            } | {
-                kind: "temporal.instant";
-            } | {
-                kind: "temporal.plainDate";
-            };
-            storage: {
-                strategy: "sqlite.text";
-                column: string;
-            } | {
-                strategy: "sqlite.integer";
-                column: string;
-            } | {
-                strategy: "sqlite.real";
-                column: string;
-            } | {
-                strategy: "sqlite.temporalInstantEpochMs";
-                column: string;
-            } | {
-                strategy: "sqlite.temporalPlainDateText";
-                column: string;
-            };
-            nullable: boolean;
-            primaryKey: boolean;
-            unique: boolean;
-            default?: {
-                kind: "literal";
-                value: string | number | boolean | null;
-            } | {
-                kind: "now";
-            } | {
-                kind: "generatedId";
-                prefix: string;
-            } | undefined;
-            description?: string | undefined;
-            references?: {
-                table: string;
-                field: string;
-                onDelete?: "cascade" | "restrict" | "set null" | "set default" | "no action" | undefined;
-                onUpdate?: "cascade" | "restrict" | "set null" | "set default" | "no action" | undefined;
-            } | undefined;
-        }[];
-        indexes: {
-            fields: string[];
-            name?: string | undefined;
-        }[];
-        uniques: {
-            fields: string[];
-            name?: string | undefined;
-        }[];
-        description?: string | undefined;
-    }[];
-};
 
 declare function compileSchemaToDrizzle(schema: DatabaseSchemaDocument): string;
+declare function compileSchemaToDrizzleRelations(schema: DatabaseSchemaDocument): string;
 
 declare function compileSchemaToSqlite(schema: DatabaseSchemaDocument): string;
-declare function renderSqliteMigration(operations: MigrationOperation[]): {
+declare function renderSqliteMigration(operations: MigrationOperation[], options?: {
+    currentSchema?: DatabaseSchemaDocument;
+}): {
     statements: string[];
     warnings: string[];
 };
 
+declare function sqlExpression(sql: string): MigrationSqlExpression;
+declare function column(fieldName: string): MigrationSqlExpression;
+declare function raw(sql: string): MigrationSqlExpression;
+declare function literal(value: string | number | boolean | null): MigrationSqlExpression;
+declare function lower(expression: MigrationSqlExpression | string): MigrationSqlExpression;
+declare function trim(expression: MigrationSqlExpression | string): MigrationSqlExpression;
+declare function replace(expression: MigrationSqlExpression | string, search: string, replacement: string): MigrationSqlExpression;
+declare function cast(expression: MigrationSqlExpression | string, sqlType: "INTEGER" | "REAL" | "TEXT"): MigrationSqlExpression;
+declare function unixepoch(expression: MigrationSqlExpression | string): MigrationSqlExpression;
+declare function date(expression: MigrationSqlExpression | string): MigrationSqlExpression;
+declare function multiply(expression: MigrationSqlExpression | string, factor: number): MigrationSqlExpression;
+declare function coalesce(...expressions: Array<MigrationSqlExpression | string>): MigrationSqlExpression;
+declare function concat(...expressions: Array<MigrationSqlExpression | string>): MigrationSqlExpression;
+declare const sqlExpr: {
+    raw: typeof raw;
+    column: typeof column;
+    literal: typeof literal;
+    lower: typeof lower;
+    trim: typeof trim;
+    replace: typeof replace;
+    cast: typeof cast;
+    unixepoch: typeof unixepoch;
+    date: typeof date;
+    multiply: typeof multiply;
+    coalesce: typeof coalesce;
+    concat: typeof concat;
+    build(sql: string): MigrationSqlExpression;
+};
+
+type Source = string | MigrationSqlExpression;
+type Fallback = string | number | boolean | null | MigrationSqlExpression;
+declare function copy(fieldName: string): MigrationSqlExpression;
+declare function lowercase(source: Source): MigrationSqlExpression;
+declare function trimmed(source: Source): MigrationSqlExpression;
+declare function slugFrom(source: Source, options?: {
+    separator?: string;
+}): MigrationSqlExpression;
+declare function concatFields(fieldNames: string[], options?: {
+    separator?: string;
+}): MigrationSqlExpression;
+declare function coalesceFields(fieldNames: string[], fallback?: Fallback): MigrationSqlExpression;
+declare function epochMsFromIsoString(source: Source): MigrationSqlExpression;
+declare function plainDateFromIsoString(source: Source): MigrationSqlExpression;
+declare function integerFromText(source: Source): MigrationSqlExpression;
+declare function realFromText(source: Source): MigrationSqlExpression;
+declare const transforms: {
+    copy: typeof copy;
+    lowercase: typeof lowercase;
+    trimmed: typeof trimmed;
+    slugFrom: typeof slugFrom;
+    concatFields: typeof concatFields;
+    coalesceFields: typeof coalesceFields;
+    epochMsFromIsoString: typeof epochMsFromIsoString;
+    plainDateFromIsoString: typeof plainDateFromIsoString;
+    integerFromText: typeof integerFromText;
+    realFromText: typeof realFromText;
+};
+
 type SchemaStateRow = {
     schemaHash: string;
     schemaJson: string;
@@ -783,6 +939,18 @@ type ApplyMigrationsResult = {
     currentSchema: DatabaseSchemaDocument;
     currentSchemaHash: string;
 };
+type MigrationStatusResult = {
+    localMigrationIds: string[];
+    appliedMigrationIds: string[];
+    pendingMigrationIds: string[];
+    unexpectedDatabaseMigrationIds: string[];
+    schemaHash: {
+        local: string;
+        database: string | null;
+        driftDetected: boolean;
+    };
+    metadataTablesPresent: boolean;
+};
 type LibsqlConnectionOptions = {
     url: string;
     authToken?: string;
@@ -886,6 +1054,23 @@ declare function listAppliedMigrations(client: Client): Promise<{
     schemaHash: string;
     appliedAt: number;
 }[]>;
+declare function inspectMigrationStatus(args: {
+    client?: Client;
+    connection?: LibsqlConnectionOptions;
+    migrations: MigrationDefinition[];
+    baseSchema?: DatabaseSchemaDocument;
+}): Promise<{
+    localMigrationIds: string[];
+    appliedMigrationIds: string[];
+    pendingMigrationIds: string[];
+    unexpectedDatabaseMigrationIds: string[];
+    schemaHash: {
+        local: string;
+        database: string | null;
+        driftDetected: boolean;
+    };
+    metadataTablesPresent: boolean;
+}>;
 declare function getSchemaState(client: Client): Promise<SchemaStateRow | null>;
 
 type DbProjectLayout = {
@@ -983,6 +1168,101 @@ declare function materializeProjectMigrations(layout: DbProjectLayout): Promise<
     };
     plans: PlannedMigration[];
 }>;
+declare function validateDbProject(layout: DbProjectLayout): Promise<{
+    warnings: string[];
+    expectedSnapshot: string;
+    expectedDrizzle: string;
+    artifacts: {
+        snapshotExists: boolean;
+        drizzleExists: boolean;
+        snapshotUpToDate: boolean;
+        drizzleUpToDate: boolean;
+    };
+    migrations: MigrationDefinition[];
+    schema: {
+        version: 1;
+        dialect: "sqlite";
+        schemaId: string;
+        tables: {
+            id: string;
+            name: string;
+            fields: {
+                id: string;
+                name: string;
+                logical: {
+                    kind: "id";
+                    prefix: string;
+                } | {
+                    kind: "string";
+                    format?: "email" | "url" | "slug" | undefined;
+                } | {
+                    kind: "text";
+                } | {
+                    kind: "boolean";
+                } | {
+                    kind: "integer";
+                } | {
+                    kind: "number";
+                } | {
+                    kind: "enum";
+                    values: string[];
+                } | {
+                    kind: "json";
+                    tsType: string;
+                } | {
+                    kind: "temporal.instant";
+                } | {
+                    kind: "temporal.plainDate";
+                };
+                storage: {
+                    strategy: "sqlite.text";
+                    column: string;
+                } | {
+                    strategy: "sqlite.integer";
+                    column: string;
+                } | {
+                    strategy: "sqlite.real";
+                    column: string;
+                } | {
+                    strategy: "sqlite.temporalInstantEpochMs";
+                    column: string;
+                } | {
+                    strategy: "sqlite.temporalPlainDateText";
+                    column: string;
+                };
+                nullable: boolean;
+                primaryKey: boolean;
+                unique: boolean;
+                default?: {
+                    kind: "literal";
+                    value: string | number | boolean | null;
+                } | {
+                    kind: "now";
+                } | {
+                    kind: "generatedId";
+                    prefix: string;
+                } | undefined;
+                description?: string | undefined;
+                references?: {
+                    table: string;
+                    field: string;
+                    onDelete?: "cascade" | "restrict" | "set null" | "set default" | "no action" | undefined;
+                    onUpdate?: "cascade" | "restrict" | "set null" | "set default" | "no action" | undefined;
+                } | undefined;
+            }[];
+            indexes: {
+                fields: string[];
+                name?: string | undefined;
+            }[];
+            uniques: {
+                fields: string[];
+                name?: string | undefined;
+            }[];
+            description?: string | undefined;
+        }[];
+    };
+    plans: PlannedMigration[];
+}>;
 declare function writeSchemaSnapshot(schema: DatabaseSchemaDocument, snapshotPath: string): Promise<void>;
 declare function writeDrizzleSchema(schema: DatabaseSchemaDocument, drizzlePath: string): Promise<void>;
 
@@ -1219,4 +1499,4 @@ declare function findField(table: {
     } | undefined;
 } | null;
 
-export { type ApplyMigrationsResult, type DatabaseSchemaDocument, type DbProjectLayout, type DefaultSpec, type FieldReferenceSpec, type FieldSpec, type ForeignKeyAction, type IndexSpec, type LibsqlConnectionOptions, type LogicalTypeSpec, type MigrationDefinition, type MigrationMeta, type MigrationOperation, type PlannedMigration, type SchemaValidationIssue, type StorageSpec, type TableSpec, type UniqueSpec, applyMigrations, applyOperationsToSchema, assertValidSchemaDocument, compileSchemaToDrizzle, compileSchemaToSqlite, createEmptySchema, createLibsqlClient, createMigration, defaultSpecSchema, fieldReferenceSpecSchema, fieldSpecSchema, findField, findTable, foreignKeyActionSchema, getSchemaState, indexSpecSchema, listAppliedMigrations, loadMigrationDefinitionsFromDirectory, logicalTypeSpecSchema, materializeProjectMigrations, materializeSchema, parseSchemaDocument, planMigration, renderSqliteMigration, resolveDbProjectLayout, schemaDocumentSchema, schemaHash, storageSpecSchema, tableSpecSchema, uniqueSpecSchema, validateSchemaDocument, writeDrizzleSchema, writeSchemaSnapshot };
+export { type AlterFieldPatch, type ApplyMigrationsResult, type BelongsToOptions, type CreateJunctionTableOptions, type DatabaseSchemaDocument, type DbProjectLayout, type DefaultSpec, type FieldReferenceSpec, type FieldSpec, type ForeignKeyAction, type IndexSpec, type JunctionSideOptions, type LibsqlConnectionOptions, type LogicalTypeSpec, type MigrationDefinition, type MigrationMeta, type MigrationOperation, type MigrationSqlExpression, type MigrationStatusResult, type PlannedMigration, type SchemaValidationIssue, type StorageSpec, type TableSpec, type UniqueSpec, applyMigrations, applyOperationsToSchema, assertValidSchemaDocument, cast, coalesce, coalesceFields, column, compileSchemaToDrizzle, compileSchemaToDrizzleRelations, compileSchemaToSqlite, concat, concatFields, copy, createEmptySchema, createLibsqlClient, createMigration, date, defaultSpecSchema, epochMsFromIsoString, fieldReferenceSpecSchema, fieldSpecSchema, findField, findTable, foreignKeyActionSchema, getSchemaState, indexSpecSchema, inspectMigrationStatus, integerFromText, listAppliedMigrations, literal, loadMigrationDefinitionsFromDirectory, logicalTypeSpecSchema, lower, lowercase, materializeProjectMigrations, materializeSchema, multiply, parseSchemaDocument, plainDateFromIsoString, planMigration, raw, realFromText, renderSqliteMigration, replace, resolveDbProjectLayout, schemaDocumentSchema, schemaHash, slugFrom, sqlExpr, sqlExpression, storageSpecSchema, tableSpecSchema, transforms, trim, trimmed, uniqueSpecSchema, unixepoch, validateDbProject, validateSchemaDocument, writeDrizzleSchema, writeSchemaSnapshot };