@supabase/pg-delta 1.0.0-alpha.3 → 1.0.0-alpha.4

package/src/core/plan/sql-format/wrap.ts

@@ -0,0 +1,196 @@
+import { indentString } from "./format-utils.ts";
+import { isWordChar, walkSql } from "./sql-scanner.ts";
+import type { NormalizedOptions } from "./types.ts";
+
+/**
+ * Keywords that are preferred break points when wrapping long lines.
+ * The wrapper will prefer to break just before one of these keywords
+ * rather than at an arbitrary whitespace position.
+ */
+const WRAP_PREFERRED_KEYWORDS = new Set([
+  "ADD",
+  "CHECK",
+  "CONNECTION",
+  "CONSTRAINT",
+  "DEFERRABLE",
+  "FOREIGN",
+  "HANDLER",
+  "INCLUDE",
+  "INITIALLY",
+  "INLINE",
+  "MATCH",
+  "NOT",
+  "ON",
+  "OPTIONS",
+  "PUBLICATION",
+  "REFERENCES",
+  "REFERENCING",
+  "SET",
+  "USING",
+  "VALIDATOR",
+  "WHERE",
+  "WITH",
+]);
+
+export function wrapStatement(
+  statement: string,
+  options: NormalizedOptions,
+  noWrapPlaceholders: Set<string>,
+): string {
+  const lines = statement.split(/\r?\n/);
+  const wrapped: string[] = [];
+
+  for (const line of lines) {
+    if (line.trim().startsWith("--")) {
+      wrapped.push(line);
+      continue;
+    }
+
+    if (hasNoWrapPlaceholder(line, noWrapPlaceholders)) {
+      wrapped.push(line);
+      continue;
+    }
+
+    wrapped.push(...wrapLine(line, options));
+  }
+
+  return wrapped.join("\n");
+}
+
+function hasNoWrapPlaceholder(
+  line: string,
+  placeholders: Set<string>,
+): boolean {
+  for (const token of placeholders) {
+    if (line.includes(token)) return true;
+  }
+  return false;
+}
+
+function wrapLine(line: string, options: NormalizedOptions): string[] {
+  const maxWidth = options.maxWidth;
+  if (maxWidth <= 0 || line.length <= maxWidth) {
+    return [line];
+  }
+
+  const indentMatch = line.match(/^\s*/);
+  const baseIndent = indentMatch ? indentMatch[0] : "";
+  const continuationIndent = `${baseIndent}${indentString(options.indent)}`;
+
+  let remaining = line;
+  const output: string[] = [];
+
+  while (remaining.length > maxWidth) {
+    const breakpoint = findWrapPosition(remaining, maxWidth);
+    if (breakpoint <= 0) break;
+
+    const head = remaining.slice(0, breakpoint).trimEnd();
+    const tail = remaining.slice(breakpoint).trimStart();
+    output.push(head);
+    const next = `${continuationIndent}${tail}`;
+    if (next.length >= remaining.length) {
+      remaining = next;
+      break;
+    }
+    remaining = next;
+  }
+
+  output.push(remaining);
+  return output;
+}
+
+/** Words that should not be separated from the previous word when wrapping (e.g. CREATE PUBLICATION, COMMENT ON). */
+const KEEP_WITH_PREVIOUS = new Set([
+  "PUBLICATION",
+  "TABLE",
+  "VIEW",
+  "SCHEMA",
+  "INDEX",
+  "OR", // CREATE OR REPLACE
+  "ON", // COMMENT ON
+]);
+
+function getPreviousWord(text: string, beforeIndex: number): string | null {
+  let end = beforeIndex - 1;
+  while (end >= 0 && (text[end] === " " || text[end] === "\t")) {
+    end -= 1;
+  }
+  if (end < 0 || !isWordChar(text[end])) return null;
+  let start = end;
+  while (start > 0 && isWordChar(text[start - 1])) {
+    start -= 1;
+  }
+  return text.slice(start, end + 1).toUpperCase();
+}
+
+function findWrapPosition(text: string, maxWidth: number): number {
+  /** Last whitespace at depth 0 (preferred — avoids splitting parenthesized expressions) */
+  let lastTopLevelWhitespace = -1;
+  /** Last whitespace at any depth (fallback when no depth-0 break exists) */
+  let lastAnyWhitespace = -1;
+  let lastKeywordBoundary = -1;
+  /** First (leftmost) top-level comma within maxWidth — break there so each clause gets its own line */
+  let firstComma = -1;
+
+  // Never break within the leading indent — that would produce an empty head line
+  const contentStart = text.search(/\S/);
+  if (contentStart < 0) return -1; // all whitespace
+
+  walkSql(
+    text,
+    (index, char, depth) => {
+      if (index > maxWidth) return false;
+
+      // Skip positions within leading indent
+      if (index < contentStart) return true;
+
+      // Prefer breaking after the first top-level comma so comma-separated clauses (e.g. publication tables) each get their own line
+      if (char === "," && depth === 0 && firstComma < 0) {
+        firstComma = index + 1; // position after the comma
+      }
+
+      if (char === " " || char === "\t") {
+        lastAnyWhitespace = index;
+        if (depth === 0) {
+          lastTopLevelWhitespace = index;
+        }
+
+        // Check if the next word is a preferred keyword
+        const nextWordStart = index + 1;
+        if (nextWordStart < text.length && isWordChar(text[nextWordStart])) {
+          let wordEnd = nextWordStart + 1;
+          while (wordEnd < text.length && isWordChar(text[wordEnd])) {
+            wordEnd += 1;
+          }
+          const word = text.slice(nextWordStart, wordEnd).toUpperCase();
+          if (WRAP_PREFERRED_KEYWORDS.has(word)) {
+            // Don't break between CREATE and object type, COMMENT and ON, or ALL and ON (GRANT/REVOKE ALL ON)
+            const prev = getPreviousWord(text, index);
+            if (
+              prev !== null &&
+              ((prev === "CREATE" && KEEP_WITH_PREVIOUS.has(word)) ||
+                ((prev === "COMMENT" || prev === "ALL") && word === "ON"))
+            ) {
+              return true;
+            }
+            lastKeywordBoundary = index;
+          }
+        }
+      }
+      return true;
+    },
+    { trackDepth: true },
+  );
+
+  // Prefer: 1) comma, 2) keyword boundary, 3) depth-0 whitespace, 4) any whitespace
+  if (firstComma > 0 && firstComma <= maxWidth) {
+    return firstComma;
+  }
+  if (lastKeywordBoundary > 0 && lastKeywordBoundary <= maxWidth) {
+    return lastKeywordBoundary;
+  }
+  if (lastTopLevelWhitespace > 0) {
+    return lastTopLevelWhitespace;
+  }
+  return lastAnyWhitespace;
+}

package/src/core/plan/sql-format.ts

@@ -0,0 +1,2 @@
+export { formatSqlStatements } from "./sql-format/index.ts";
+export type { SqlFormatOptions } from "./sql-format/types.ts";

package/src/core/plan/statements.ts

@@ -0,0 +1,22 @@
+/**
+ * SQL script formatting utilities.
+ */
+
+import { formatSqlStatements, type SqlFormatOptions } from "./sql-format.ts";
+
+const STATEMENT_DELIMITER = ";\n\n";
+
+/**
+ * Format an array of SQL statements into a single script string.
+ * Statements are joined with double newlines and the script ends with a semicolon.
+ */
+export function formatSqlScript(
+  statements: string[],
+  options?: SqlFormatOptions,
+): string {
+  if (statements.length === 0) return "";
+  const formatted = options
+    ? formatSqlStatements(statements, options)
+    : statements;
+  return `${formatted.join(STATEMENT_DELIMITER)};`;
+}

package/src/core/plan/types.ts

@@ -0,0 +1,165 @@
+/**
+ * Type definitions for the Plan module.
+ */
+
+import z from "zod";
+import type { Change } from "../change.types.ts";
+import type { FilterDSL } from "../integrations/filter/dsl.ts";
+import type { ChangeFilter } from "../integrations/filter/filter.types.ts";
+import type { SerializeDSL } from "../integrations/serialize/dsl.ts";
+import type { ChangeSerializer } from "../integrations/serialize/serialize.types.ts";
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+export type PlanRisk =
+  | { level: "safe" }
+  | { level: "data_loss"; statements: string[] };
+
+/**
+ * All supported object types in the system.
+ * Derived from the Change union type's objectType discriminant.
+ */
+type ObjectType = Change["objectType"];
+
+/**
+ * Parent types for child objects.
+ */
+export type ParentType = Extract<
+  ObjectType,
+  "table" | "view" | "materialized_view" | "foreign_table"
+>;
+
+/**
+ * A change entry storing both serialized and original change for instanceof checks.
+ */
+export interface ChangeEntry {
+  original: Change;
+}
+
+/**
+ * A group of changes organized by operation.
+ */
+export interface ChangeGroup {
+  create: ChangeEntry[];
+  alter: ChangeEntry[];
+  drop: ChangeEntry[];
+}
+
+/**
+ * Children objects of a table/view (indexes, triggers, policies, etc.)
+ */
+export interface TableChildren {
+  changes: ChangeGroup;
+  columns: ChangeGroup;
+  indexes: ChangeGroup;
+  triggers: ChangeGroup;
+  rules: ChangeGroup;
+  policies: ChangeGroup;
+  /** Partition tables (only for partitioned tables) */
+  partitions: Record<string, TableChildren>;
+}
+
+/**
+ * Children objects of a materialized view
+ */
+export interface MaterializedViewChildren {
+  changes: ChangeGroup;
+  indexes: ChangeGroup;
+}
+
+/**
+ * Type grouping within a schema
+ */
+export interface TypeGroup {
+  enums: ChangeGroup;
+  composites: ChangeGroup;
+  ranges: ChangeGroup;
+  domains: ChangeGroup;
+}
+
+/**
+ * Schema-level grouping of objects
+ */
+export interface SchemaGroup {
+  changes: ChangeGroup;
+  tables: Record<string, TableChildren>;
+  views: Record<string, TableChildren>;
+  materializedViews: Record<string, MaterializedViewChildren>;
+  functions: ChangeGroup;
+  procedures: ChangeGroup;
+  aggregates: ChangeGroup;
+  sequences: ChangeGroup;
+  types: TypeGroup;
+  collations: ChangeGroup;
+  foreignTables: Record<string, TableChildren>;
+}
+
+/**
+ * Cluster-wide objects (no schema)
+ */
+export interface ClusterGroup {
+  roles: ChangeGroup;
+  extensions: ChangeGroup;
+  eventTriggers: ChangeGroup;
+  publications: ChangeGroup;
+  subscriptions: ChangeGroup;
+  foreignDataWrappers: ChangeGroup;
+  servers: ChangeGroup;
+  userMappings: ChangeGroup;
+}
+
+/**
+ * Fully hierarchical plan structure for tree display.
+ */
+export interface HierarchicalPlan {
+  cluster: ClusterGroup;
+  schemas: Record<string, SchemaGroup>;
+}
+
+/**
+ * Plan schema for serialization/deserialization.
+ */
+export const PlanSchema = z.object({
+  version: z.number(),
+  toolVersion: z.string().optional(),
+  source: z.object({
+    fingerprint: z.string(),
+  }),
+  target: z.object({
+    fingerprint: z.string(),
+  }),
+  statements: z.array(z.string()),
+  role: z.string().optional(),
+  filter: z.any().optional(), // FilterDSL - complex recursive type, validated at compile time
+  serialize: z.any().optional(), // SerializeDSL - complex recursive type, validated at compile time
+  risk: z
+    .discriminatedUnion("level", [
+      z.object({
+        level: z.literal("safe"),
+      }),
+      z.object({
+        level: z.literal("data_loss"),
+        statements: z.array(z.string()),
+      }),
+    ])
+    .optional(),
+});
+
+/**
+ * A migration plan containing all changes to transform one database schema into another.
+ */
+export type Plan = z.infer<typeof PlanSchema>;
+
+/**
+ * Options for creating a plan.
+ */
+export interface CreatePlanOptions {
+  /** Filter - either FilterDSL (stored in plan) or ChangeFilter function (not stored) */
+  filter?: FilterDSL | ChangeFilter;
+  /** Serialize - either SerializeDSL (stored in plan) or ChangeSerializer function (not stored) */
+  serialize?: SerializeDSL | ChangeSerializer;
+  /** Role to use when executing the migration (SET ROLE will be added to statements) */
+  role?: string;
+}

package/src/core/postgres-config.ts

@@ -0,0 +1,169 @@
+/**
+ * PostgreSQL connection configuration with custom type handlers.
+ */
+
+import type { PoolClient, PoolConfig } from "pg";
+import { Pool, types } from "pg";
+
+// ============================================================================
+// Array Parser
+// ============================================================================
+
+/**
+ * Parse PostgreSQL array string into JavaScript array.
+ * Handles: {val1,val2}, {NULL,val}, {"quoted,val"}, nested arrays.
+ */
+function parseArray(
+  value: string,
+  parseElement: (val: string) => unknown = (v) => v,
+): unknown[] {
+  if (!value || value === "{}") return [];
+
+  // Remove outer braces
+  const inner = value.slice(1, -1);
+  if (inner === "") return [];
+
+  const result: unknown[] = [];
+  let current = "";
+  let inQuotes = false;
+  let depth = 0;
+
+  for (let i = 0; i < inner.length; i++) {
+    const char = inner[i];
+
+    if (char === '"' && inner[i - 1] !== "\\") {
+      inQuotes = !inQuotes;
+      current += char;
+    } else if (char === "{" && !inQuotes) {
+      depth++;
+      current += char;
+    } else if (char === "}" && !inQuotes) {
+      depth--;
+      current += char;
+    } else if (char === "," && !inQuotes && depth === 0) {
+      result.push(parseElement(current));
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+
+  if (current !== "") {
+    result.push(parseElement(current));
+  }
+
+  return result;
+}
+
+/**
+ * Parse element, handling NULL, quoted strings, and unquoted values.
+ */
+function parseStringElement(val: string): string | null {
+  if (val === "NULL") return null;
+  if (val.startsWith('"') && val.endsWith('"')) {
+    // Unescape quoted string
+    return val.slice(1, -1).replace(/\\(.)/g, "$1");
+  }
+  return val;
+}
+
+function parseIntElement(val: string): number | null {
+  if (val === "NULL") return null;
+  return Number.parseInt(val, 10);
+}
+
+// ============================================================================
+// Type Parsers
+// ============================================================================
+
+// int2vector: "1 2 3" -> [1, 2, 3]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(22, (val: string) => {
+  if (!val || val === "") return [];
+  return val
+    .split(" ")
+    .map(Number)
+    .filter((n: number) => !Number.isNaN(n));
+});
+
+// bigint: string -> BigInt
+types.setTypeParser(20, (val: string) => BigInt(val));
+
+// PostgreSQL array types
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1002, (val: string) => parseArray(val, parseStringElement)); // "char"[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1009, (val: string) => parseArray(val, parseStringElement)); // text[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1015, (val: string) => parseArray(val, parseStringElement)); // varchar[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1005, (val: string) => parseArray(val, parseIntElement)); // int2[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1007, (val: string) => parseArray(val, parseIntElement)); // int4[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1016, (val: string) => parseArray(val, parseIntElement)); // int8[]
+
+/**
+ * Options for creating a Pool with event listeners.
+ */
+interface CreatePoolOptions extends Partial<PoolConfig> {
+  /** Called when a new client connects to the pool */
+  onConnect?: (client: PoolClient) => void | Promise<void>;
+  /** Called when an idle client emits an error */
+  onError?: (err: Error, client: PoolClient) => void;
+  /** Called when a client is acquired from the pool */
+  onAcquire?: (client: PoolClient) => void;
+  /** Called when a client is removed from the pool */
+  onRemove?: (client: PoolClient) => void;
+}
+
+/**
+ * Create a Pool with custom type handlers and optional event listeners.
+ */
+export function createPool(
+  connectionString: string,
+  options?: CreatePoolOptions,
+): Pool {
+  const { onConnect, onError, onAcquire, onRemove, ...config } = options ?? {};
+  const pool = new Pool({ connectionString, ...config });
+
+  if (onConnect) pool.on("connect", onConnect);
+  if (onError) pool.on("error", onError);
+  if (onAcquire) pool.on("acquire", onAcquire);
+  if (onRemove) pool.on("remove", onRemove);
+
+  return pool;
+}
+
+/**
+ * End a pool and wait for all client sockets to fully close.
+ *
+ * pg-pool's `pool.end()` resolves once clients are removed from its
+ * internal bookkeeping, but the underlying `client.end()` calls (which
+ * close the TCP/TLS sockets) are fired asynchronously *after* that.
+ * If the server (e.g. a test container) is stopped right after
+ * `pool.end()` resolves, the still-open sockets receive an unexpected
+ * RST and emit unhandled "Connection terminated unexpectedly" errors.
+ *
+ * This helper waits for every `remove` event — which pg-pool emits
+ * inside each `client.end()` callback — ensuring all sockets are
+ * truly closed before it resolves.
+ */
+export function endPool(pool: Pool): Promise<void> {
+  const clientCount = pool.totalCount;
+
+  if (clientCount === 0) {
+    return pool.end();
+  }
+
+  return new Promise<void>((resolve, reject) => {
+    let removed = 0;
+    pool.on("remove", function onRemove() {
+      if (++removed >= clientCount) {
+        pool.removeListener("remove", onRemove);
+        resolve();
+      }
+    });
+    pool.end().catch(reject);
+  });
+}