@hypequery/clickhouse 2.0.0 → 2.0.2

package/dist/migrations/schema/column.js

@@ -0,0 +1,123 @@
+import { isSQLExpression } from '../../dataset/sql-tag.js';
+/**
+ * Immutable builder for ClickHouse column definitions.
+ *
+ * Each modifier returns a new builder so reusable column fragments can be shared
+ * safely without later calls mutating earlier definitions.
+ */
+export class ClickHouseColumnBuilder {
+    columnType;
+    defaultExpression;
+    constructor(columnType, defaultExpression) {
+        this.columnType = columnType;
+        this.defaultExpression = defaultExpression;
+    }
+    /**
+     * Adds a column default.
+     *
+     * Primitive values are rendered as SQL literals. Use the `sql` template tag for
+     * database expressions such as `sql\`now()\``.
+     */
+    default(expression) {
+        return new ClickHouseColumnBuilder(this.columnType, toDefaultValue(expression));
+    }
+    /**
+     * Wraps this column type in `Nullable(...)`.
+     */
+    nullable() {
+        return new ClickHouseColumnBuilder({ kind: 'nullable', inner: this.columnType }, this.defaultExpression);
+    }
+    /**
+     * Wraps this column type in `LowCardinality(...)`.
+     */
+    lowCardinality() {
+        return new ClickHouseColumnBuilder({ kind: 'low_cardinality', inner: this.columnType }, this.defaultExpression);
+    }
+    /**
+     * Materializes the builder into a named column definition for a table AST.
+     */
+    build(name) {
+        return {
+            name,
+            type: this.columnType,
+            ...(this.defaultExpression !== undefined ? { default: this.defaultExpression } : {}),
+        };
+    }
+    /**
+     * Returns the underlying type AST for nested type builders.
+     */
+    toColumnType() {
+        return this.columnType;
+    }
+}
+/**
+ * Factory helpers for common ClickHouse column types.
+ *
+ * Examples:
+ * `column.String().default('pending')`, `column.Nullable('String')`,
+ * `column.DateTime('UTC')`.
+ */
+export const column = {
+    Int8: () => named('Int8'),
+    Int16: () => named('Int16'),
+    Int32: () => named('Int32'),
+    Int64: () => named('Int64'),
+    Int128: () => named('Int128'),
+    Int256: () => named('Int256'),
+    UInt8: () => named('UInt8'),
+    UInt16: () => named('UInt16'),
+    UInt32: () => named('UInt32'),
+    UInt64: () => named('UInt64'),
+    UInt128: () => named('UInt128'),
+    UInt256: () => named('UInt256'),
+    Float32: () => named('Float32'),
+    Float64: () => named('Float64'),
+    Decimal: (precision, scale) => named('Decimal', precision, scale),
+    String: () => named('String'),
+    FixedString: (length) => named('FixedString', length),
+    Date: () => named('Date'),
+    DateTime: (timezone) => timezone ? named('DateTime', timezone) : named('DateTime'),
+    DateTime64: (precision, timezone) => timezone ? named('DateTime64', precision, timezone) : named('DateTime64', precision),
+    UUID: () => named('UUID'),
+    JSON: () => named('JSON'),
+    LowCardinality: (inner) => new ClickHouseColumnBuilder({
+        kind: 'low_cardinality',
+        inner: normalizeNestedColumnType(inner),
+    }),
+    Nullable: (inner) => new ClickHouseColumnBuilder({
+        kind: 'nullable',
+        inner: normalizeNestedColumnType(inner),
+    }),
+};
+function named(name, ...argumentsList) {
+    const type = {
+        kind: 'named',
+        name,
+        ...(argumentsList.length > 0 ? { arguments: argumentsList } : {}),
+    };
+    return new ClickHouseColumnBuilder(type);
+}
+function normalizeNestedColumnType(input) {
+    if (typeof input === 'string') {
+        return {
+            kind: 'named',
+            name: input,
+        };
+    }
+    if (input instanceof ClickHouseColumnBuilder) {
+        return input.toColumnType();
+    }
+    return input;
+}
+function toDefaultValue(input) {
+    if (isSQLExpression(input)) {
+        return {
+            kind: 'sql',
+            value: input,
+        };
+    }
+    return {
+        kind: 'literal',
+        value: input,
+    };
+}

package/dist/migrations/schema/define.d.ts

@@ -0,0 +1,24 @@
+import type { ClickHouseMaterializedViewDefinition, ClickHouseMaterializedViewInputDefinition, ClickHouseSchemaAst, ClickHouseSchemaDefinition, ClickHouseTableDefinition, ClickHouseTableInputDefinition } from './types.js';
+/**
+ * Creates a schema AST from the tables and materialized views declared in code.
+ *
+ * The returned AST is intentionally not SQL yet. It is serialized into a stable
+ * snapshot first, then diffed against a previous snapshot to generate migrations.
+ */
+export declare function defineSchema(definition: ClickHouseSchemaDefinition): ClickHouseSchemaAst;
+/**
+ * Defines a ClickHouse table for the migration DSL.
+ *
+ * Column builders are keyed by their final column names, which keeps the schema
+ * definition compact while preserving enough structure for snapshot diffing.
+ */
+export declare function defineTable(name: string, definition: ClickHouseTableInputDefinition): ClickHouseTableDefinition;
+/**
+ * Defines a ClickHouse materialized view and records its source-table dependency.
+ *
+ * The `from` and `to` fields may reference table definitions directly or use table
+ * names. Dependencies are used by the renderer to drop and recreate views around
+ * table mutations that could otherwise break stored SELECT definitions.
+ */
+export declare function defineMaterializedView(name: string, definition: ClickHouseMaterializedViewInputDefinition): ClickHouseMaterializedViewDefinition;
+//# sourceMappingURL=define.d.ts.map

package/dist/migrations/schema/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/migrations/schema/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oCAAoC,EACpC,yCAAyC,EACzC,mBAAmB,EACnB,0BAA0B,EAC1B,yBAAyB,EACzB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,0BAA0B,GAAG,mBAAmB,CAOxF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,8BAA8B,GACzC,yBAAyB,CAQ3B;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,yCAAyC,GACpD,oCAAoC,CAUtC"}

package/dist/migrations/schema/define.js

@@ -0,0 +1,47 @@
+/**
+ * Creates a schema AST from the tables and materialized views declared in code.
+ *
+ * The returned AST is intentionally not SQL yet. It is serialized into a stable
+ * snapshot first, then diffed against a previous snapshot to generate migrations.
+ */
+export function defineSchema(definition) {
+    return {
+        tables: [...definition.tables],
+        ...(definition.materializedViews !== undefined
+            ? { materializedViews: [...definition.materializedViews] }
+            : {}),
+    };
+}
+/**
+ * Defines a ClickHouse table for the migration DSL.
+ *
+ * Column builders are keyed by their final column names, which keeps the schema
+ * definition compact while preserving enough structure for snapshot diffing.
+ */
+export function defineTable(name, definition) {
+    return {
+        kind: 'table',
+        name,
+        columns: Object.entries(definition.columns).map(([columnName, builder]) => builder.build(columnName)),
+        engine: definition.engine,
+        ...(definition.settings !== undefined ? { settings: definition.settings } : {}),
+    };
+}
+/**
+ * Defines a ClickHouse materialized view and records its source-table dependency.
+ *
+ * The `from` and `to` fields may reference table definitions directly or use table
+ * names. Dependencies are used by the renderer to drop and recreate views around
+ * table mutations that could otherwise break stored SELECT definitions.
+ */
+export function defineMaterializedView(name, definition) {
+    return {
+        kind: 'materialized_view',
+        name,
+        from: typeof definition.from === 'string' ? definition.from : definition.from.name,
+        ...(definition.to !== undefined
+            ? { to: typeof definition.to === 'string' ? definition.to : definition.to.name }
+            : {}),
+        select: definition.select,
+    };
+}

package/dist/migrations/schema/index.d.ts

@@ -0,0 +1,4 @@
+export { column, ClickHouseColumnBuilder } from './column.js';
+export { defineMaterializedView, defineSchema, defineTable } from './define.js';
+export type { ClickHouseColumnBuilderLike, ClickHouseColumnDefaultValue, ClickHouseColumnDefinition, ClickHouseColumnType, ClickHouseDefaultInput, ClickHouseLowCardinalityColumnType, ClickHouseLiteralDefaultValue, ClickHouseMaterializedViewDefinition, ClickHouseMaterializedViewInputDefinition, ClickHouseNamedColumnType, ClickHouseNullableColumnType, ClickHouseSqlDefaultValue, ClickHouseSchemaAst, ClickHouseSchemaDefinition, ClickHouseSqlExpression, ClickHouseTableDefinition, ClickHouseTableInputDefinition, ClickHouseTableEngine, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/migrations/schema/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEhF,YAAY,EACV,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,EAC1B,oBAAoB,EACpB,sBAAsB,EACtB,kCAAkC,EAClC,6BAA6B,EAC7B,oCAAoC,EACpC,yCAAyC,EACzC,yBAAyB,EACzB,4BAA4B,EAC5B,yBAAyB,EACzB,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,EACvB,yBAAyB,EACzB,8BAA8B,EAC9B,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/migrations/schema/index.js

@@ -0,0 +1,2 @@
+export { column, ClickHouseColumnBuilder } from './column.js';
+export { defineMaterializedView, defineSchema, defineTable } from './define.js';

package/dist/migrations/schema/types.d.ts

@@ -0,0 +1,74 @@
+import type { SQLExpression } from '../../dataset/sql-tag.js';
+export type ClickHouseSqlExpression = string | SQLExpression;
+export type ClickHouseDefaultInput = string | number | boolean | null | SQLExpression;
+export interface ClickHouseSchemaAst {
+    tables: ClickHouseTableDefinition[];
+    materializedViews?: ClickHouseMaterializedViewDefinition[];
+}
+export interface ClickHouseSchemaDefinition {
+    tables: ClickHouseTableDefinition[];
+    materializedViews?: ClickHouseMaterializedViewDefinition[];
+}
+export interface ClickHouseTableDefinition {
+    kind: 'table';
+    name: string;
+    columns: ClickHouseColumnDefinition[];
+    engine: ClickHouseTableEngine;
+    settings?: Record<string, string | number | boolean>;
+}
+export interface ClickHouseTableInputDefinition {
+    columns: Record<string, ClickHouseColumnBuilderLike>;
+    engine: ClickHouseTableEngine;
+    settings?: Record<string, string | number | boolean>;
+}
+export interface ClickHouseColumnDefinition {
+    name: string;
+    type: ClickHouseColumnType;
+    default?: ClickHouseColumnDefaultValue;
+}
+export interface ClickHouseColumnBuilderLike {
+    build(name: string): ClickHouseColumnDefinition;
+}
+export type ClickHouseColumnDefaultValue = ClickHouseLiteralDefaultValue | ClickHouseSqlDefaultValue;
+export interface ClickHouseLiteralDefaultValue {
+    kind: 'literal';
+    value: string | number | boolean | null;
+}
+export interface ClickHouseSqlDefaultValue {
+    kind: 'sql';
+    value: ClickHouseSqlExpression;
+}
+export type ClickHouseColumnType = ClickHouseNamedColumnType | ClickHouseNullableColumnType | ClickHouseLowCardinalityColumnType;
+export interface ClickHouseNamedColumnType {
+    kind: 'named';
+    name: string;
+    arguments?: Array<string | number>;
+}
+export interface ClickHouseNullableColumnType {
+    kind: 'nullable';
+    inner: ClickHouseColumnType;
+}
+export interface ClickHouseLowCardinalityColumnType {
+    kind: 'low_cardinality';
+    inner: ClickHouseColumnType;
+}
+export interface ClickHouseTableEngine {
+    type: string;
+    orderBy?: ClickHouseSqlExpression[];
+    partitionBy?: ClickHouseSqlExpression;
+    primaryKey?: ClickHouseSqlExpression[];
+    sampleBy?: ClickHouseSqlExpression;
+}
+export interface ClickHouseMaterializedViewDefinition {
+    kind: 'materialized_view';
+    name: string;
+    from: string;
+    to?: string;
+    select: ClickHouseSqlExpression;
+}
+export interface ClickHouseMaterializedViewInputDefinition {
+    from: string | ClickHouseTableDefinition;
+    to?: string | ClickHouseTableDefinition;
+    select: ClickHouseSqlExpression;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/migrations/schema/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/migrations/schema/types.ts"],"names":[],"mappings":"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"}

package/dist/migrations/schema/types.js

@@ -0,0 +1 @@
+export {};

package/dist/migrations/snapshot/index.d.ts

@@ -0,0 +1,3 @@
+export { hashSnapshot, serializeSchemaToSnapshot, snapshotToStableJson, } from './serialize.js';
+export type { Snapshot, SnapshotColumn, SnapshotColumnDefault, SnapshotDependencyEdge, SnapshotMaterializedView, SnapshotTable, SnapshotTableEngine, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/snapshot/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/migrations/snapshot/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,QAAQ,EACR,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/migrations/snapshot/index.js

@@ -0,0 +1 @@
+export { hashSnapshot, serializeSchemaToSnapshot, snapshotToStableJson, } from './serialize.js';

package/dist/migrations/snapshot/serialize.d.ts

@@ -0,0 +1,21 @@
+import type { ClickHouseSchemaAst } from '../schema/types.js';
+import type { Snapshot } from './types.js';
+type SnapshotWithoutHash = Omit<Snapshot, 'contentHash'>;
+/**
+ * Converts a schema AST into a deterministic ClickHouse snapshot.
+ *
+ * Snapshot serialization normalizes ordering, SQL-expression whitespace, type
+ * wrappers, settings, and materialized-view dependencies before computing the
+ * content hash used by migration metadata.
+ */
+export declare function serializeSchemaToSnapshot(schema: ClickHouseSchemaAst): Snapshot;
+/**
+ * Serializes a snapshot with stable formatting for writing to disk and hashing.
+ */
+export declare function snapshotToStableJson(snapshot: Snapshot | SnapshotWithoutHash): string;
+/**
+ * Computes the SHA-256 content hash for a normalized snapshot.
+ */
+export declare function hashSnapshot(snapshot: Snapshot | SnapshotWithoutHash): string;
+export {};
+//# sourceMappingURL=serialize.d.ts.map

package/dist/migrations/snapshot/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/migrations/snapshot/serialize.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,mBAAmB,EAEpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,QAAQ,EAMT,MAAM,YAAY,CAAC;AAEpB,KAAK,mBAAmB,GAAG,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,GAAG,QAAQ,CA6D/E;AAgBD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,mBAAmB,GAAG,MAAM,CAErF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,mBAAmB,GAAG,MAAM,CAE7E"}

package/dist/migrations/snapshot/serialize.js

@@ -0,0 +1,127 @@
+import { createHash } from 'node:crypto';
+import { isSQLExpression } from '../../dataset/sql-tag.js';
+/**
+ * Converts a schema AST into a deterministic ClickHouse snapshot.
+ *
+ * Snapshot serialization normalizes ordering, SQL-expression whitespace, type
+ * wrappers, settings, and materialized-view dependencies before computing the
+ * content hash used by migration metadata.
+ */
+export function serializeSchemaToSnapshot(schema) {
+    const snapshot = {
+        version: 1,
+        dialect: 'clickhouse',
+        tables: [...schema.tables]
+            .sort((left, right) => left.name.localeCompare(right.name))
+            .map((table) => ({
+            name: table.name,
+            columns: [...table.columns]
+                .sort((left, right) => left.name.localeCompare(right.name))
+                .map((column) => ({
+                name: column.name,
+                type: normalizeColumnType(column.type),
+                ...(column.default !== undefined
+                    ? { default: normalizeColumnDefault(column.default) }
+                    : {}),
+            })),
+            engine: {
+                type: table.engine.type,
+                orderBy: (table.engine.orderBy ?? []).map(normalizeSqlExpression),
+                ...(table.engine.partitionBy !== undefined
+                    ? { partitionBy: normalizeSqlExpression(table.engine.partitionBy) }
+                    : {}),
+                primaryKey: (table.engine.primaryKey ?? []).map(normalizeSqlExpression),
+                ...(table.engine.sampleBy !== undefined
+                    ? { sampleBy: normalizeSqlExpression(table.engine.sampleBy) }
+                    : {}),
+            },
+            settings: Object.fromEntries(Object.entries(table.settings ?? {})
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([key, value]) => [key, String(value)])),
+        })),
+        materializedViews: [...(schema.materializedViews ?? [])]
+            .sort((left, right) => left.name.localeCompare(right.name))
+            .map((view) => ({
+            name: view.name,
+            from: view.from,
+            ...(view.to !== undefined ? { to: view.to } : {}),
+            select: normalizeSqlExpression(view.select),
+        })),
+        dependencies: [...(schema.materializedViews ?? [])]
+            .sort((left, right) => left.name.localeCompare(right.name))
+            .map((view) => ({
+            from: view.from,
+            to: view.name,
+            kind: 'table_to_materialized_view',
+        })),
+    };
+    return {
+        ...snapshot,
+        contentHash: hashSnapshot(snapshot),
+    };
+}
+function normalizeColumnDefault(defaultValue) {
+    if (defaultValue.kind === 'literal') {
+        return {
+            kind: 'literal',
+            value: defaultValue.value,
+        };
+    }
+    return {
+        kind: 'sql',
+        value: normalizeSqlExpression(defaultValue.value),
+    };
+}
+/**
+ * Serializes a snapshot with stable formatting for writing to disk and hashing.
+ */
+export function snapshotToStableJson(snapshot) {
+    return JSON.stringify(snapshot, null, 2);
+}
+/**
+ * Computes the SHA-256 content hash for a normalized snapshot.
+ */
+export function hashSnapshot(snapshot) {
+    return createHash('sha256').update(snapshotToStableJson(snapshot)).digest('hex');
+}
+function normalizeColumnType(type) {
+    switch (type.kind) {
+        case 'named': {
+            const args = type.arguments?.length ? `(${type.arguments.join(', ')})` : '';
+            return `${type.name}${args}`;
+        }
+        case 'nullable':
+            return `Nullable(${normalizeColumnType(type.inner)})`;
+        case 'low_cardinality':
+            return `LowCardinality(${normalizeColumnType(type.inner)})`;
+        default: {
+            const exhaustiveCheck = type;
+            return exhaustiveCheck;
+        }
+    }
+}
+function normalizeSqlExpression(expression) {
+    const sql = typeof expression === 'string'
+        ? expression
+        : isSQLExpression(expression)
+            ? expression.sql
+            : String(expression);
+    const lines = sql
+        .replace(/\r\n/g, '\n')
+        .split('\n')
+        .map(line => line.replace(/\s+$/g, ''));
+    while (lines.length > 0 && lines[0].trim() === '') {
+        lines.shift();
+    }
+    while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
+        lines.pop();
+    }
+    const indents = lines
+        .filter(line => line.trim().length > 0)
+        .map(line => line.match(/^\s*/)?.[0].length ?? 0);
+    const minIndent = indents.length > 0 ? Math.min(...indents) : 0;
+    return lines
+        .map(line => line.slice(minIndent))
+        .join('\n')
+        .trim();
+}

package/dist/migrations/snapshot/types.d.ts

@@ -0,0 +1,47 @@
+export interface Snapshot {
+    version: 1;
+    dialect: 'clickhouse';
+    tables: SnapshotTable[];
+    materializedViews: SnapshotMaterializedView[];
+    dependencies: SnapshotDependencyEdge[];
+    contentHash: string;
+}
+export interface SnapshotTable {
+    name: string;
+    columns: SnapshotColumn[];
+    engine: SnapshotTableEngine;
+    settings: Record<string, string>;
+}
+export interface SnapshotColumn {
+    name: string;
+    type: string;
+    default?: SnapshotColumnDefault;
+}
+export type SnapshotColumnDefault = SnapshotLiteralColumnDefault | SnapshotSqlColumnDefault;
+export interface SnapshotLiteralColumnDefault {
+    kind: 'literal';
+    value: string | number | boolean | null;
+}
+export interface SnapshotSqlColumnDefault {
+    kind: 'sql';
+    value: string;
+}
+export interface SnapshotTableEngine {
+    type: string;
+    orderBy: string[];
+    partitionBy?: string;
+    primaryKey: string[];
+    sampleBy?: string;
+}
+export interface SnapshotMaterializedView {
+    name: string;
+    from: string;
+    to?: string;
+    select: string;
+}
+export interface SnapshotDependencyEdge {
+    from: string;
+    to: string;
+    kind: 'table_to_materialized_view';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/migrations/snapshot/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/migrations/snapshot/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,iBAAiB,EAAE,wBAAwB,EAAE,CAAC;IAC9C,YAAY,EAAE,sBAAsB,EAAE,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED,MAAM,MAAM,qBAAqB,GAAG,4BAA4B,GAAG,wBAAwB,CAAC;AAE5F,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,4BAA4B,CAAC;CACpC"}

package/dist/migrations/snapshot/types.js

@@ -0,0 +1 @@
+export {};

package/dist/migrations/sql/index.d.ts

@@ -0,0 +1,4 @@
+export { renderMigrationArtifacts } from './render.js';
+export { writeMigrationArtifacts } from './write.js';
+export type { MigrationMeta, RenderMigrationArtifactsInput, RenderMigrationArtifactsOptions, RenderMigrationArtifactsResult, WriteMigrationArtifactsOptions, WriteMigrationArtifactsResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/sql/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/migrations/sql/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAErD,YAAY,EACV,aAAa,EACb,6BAA6B,EAC7B,+BAA+B,EAC/B,8BAA8B,EAC9B,8BAA8B,EAC9B,6BAA6B,GAC9B,MAAM,YAAY,CAAC"}

package/dist/migrations/sql/index.js

@@ -0,0 +1,2 @@
+export { renderMigrationArtifacts } from './render.js';
+export { writeMigrationArtifacts } from './write.js';

package/dist/migrations/sql/render.d.ts

@@ -0,0 +1,10 @@
+import type { RenderMigrationArtifactsInput, RenderMigrationArtifactsOptions, RenderMigrationArtifactsResult } from './types.js';
+/**
+ * Renders a snapshot diff into reviewable migration artifacts.
+ *
+ * The renderer produces forward SQL, best-effort reverse SQL, and metadata. It
+ * also sequences dependent materialized views around table mutations so stored
+ * view SELECT definitions are dropped and recreated with the target snapshot.
+ */
+export declare function renderMigrationArtifacts(input: RenderMigrationArtifactsInput, options: RenderMigrationArtifactsOptions): RenderMigrationArtifactsResult;
+//# sourceMappingURL=render.d.ts.map

package/dist/migrations/sql/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/migrations/sql/render.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAEV,6BAA6B,EAC7B,+BAA+B,EAC/B,8BAA8B,EAG/B,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,6BAA6B,EACpC,OAAO,EAAE,+BAA+B,GACvC,8BAA8B,CAkDhC"}