@supabase/pg-delta 1.0.0-alpha.2 → 1.0.0-alpha.21

package/src/core/export/index.ts

@@ -0,0 +1,138 @@
+/**
+ * Declarative schema export.
+ */
+
+import type { Change } from "../change.types.ts";
+import { buildPlanScopeFingerprint, hashStableIds } from "../fingerprint.ts";
+import {
+  type Integration,
+  type ResolvedIntegration,
+  resolveIntegration,
+} from "../integrations/integration.types.ts";
+import type { createPlan } from "../plan/create.ts";
+import { DEFAULT_OPTIONS } from "../plan/sql-format/constants.ts";
+import type { SqlFormatOptions } from "../plan/sql-format/types.ts";
+import { formatSqlScript } from "../plan/statements.ts";
+import { createFileMapper } from "./file-mapper.ts";
+import { groupChangesByFile } from "./grouper.ts";
+import type { DeclarativeSchemaOutput, FileEntry, Grouping } from "./types.ts";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * The result of createPlan, containing the plan, sorted changes, and context.
+ * Use this type when you have already confirmed createPlan returned non-null.
+ */
+type PlanResult = NonNullable<Awaited<ReturnType<typeof createPlan>>>;
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export interface ExportOptions {
+  /** Integration for custom serialization */
+  integration?: Pick<Integration, "serialize">;
+  /**
+   * SQL formatter options to control the output style.
+   * Merged on top of the default export options (maxWidth: 180, keywordCase: "upper").
+   * See `SqlFormatOptions` for available keys.
+   */
+  formatOptions?: SqlFormatOptions | null;
+  /**
+   * Group entities by name prefix into consolidated files or subdirectories.
+   * Supports automatic partition detection and/or explicit prefix lists.
+   */
+  grouping?: Grouping;
+  /** Callback for non-fatal warnings (e.g. invalid grouping regex patterns). */
+  onWarning?: (message: string) => void;
+}
+
+/**
+ * Export a declarative schema from a plan result.
+ *
+ * Takes the output of `createPlan()` and generates a declarative schema output
+ * with files grouped by object type. Drop operations are excluded since
+ * declarative mode targets the final desired state.
+ *
+ * Dependency-based filtering (cascading exclusions) is handled by `createPlan`,
+ * so this function only needs to filter out drop operations.
+ *
+ * @param planResult - The result from createPlan() containing plan, sortedChanges, and ctx
+ * @param options - Optional integration for custom serialization
+ * @returns Declarative schema output with grouped files
+ */
+export function exportDeclarativeSchema(
+  planResult: PlanResult,
+  options?: ExportOptions,
+): DeclarativeSchemaOutput {
+  const { ctx, sortedChanges } = planResult;
+  const integration = options?.integration
+    ? resolveIntegration(options?.integration)
+    : {};
+  const formatOptions: SqlFormatOptions | undefined =
+    options?.formatOptions === null
+      ? undefined
+      : {
+          ...DEFAULT_OPTIONS,
+          maxWidth: 180,
+          keywordCase: "upper",
+          ...options?.formatOptions,
+        };
+
+  // Drop filtering and dependency cascading are handled upstream by createPlan.
+
+  const { hash: sourceFingerprint, stableIds } = buildPlanScopeFingerprint(
+    ctx.mainCatalog,
+    sortedChanges,
+  );
+  const targetFingerprint = hashStableIds(ctx.branchCatalog, stableIds);
+
+  const mapper = createFileMapper(options?.grouping, options?.onWarning);
+  const groups = groupChangesByFile(sortedChanges, mapper);
+  const files = groups.map((group, index) => {
+    const statements = group.changes.map((change) =>
+      serializeChange(change, integration),
+    );
+    return buildFileEntry(
+      group.path,
+      group.metadata,
+      statements,
+      index,
+      formatOptions,
+    );
+  });
+
+  return {
+    version: 1,
+    mode: "declarative",
+    generatedAt: new Date().toISOString(),
+    source: { fingerprint: sourceFingerprint },
+    target: { fingerprint: targetFingerprint },
+    files,
+  };
+}
+
+function serializeChange(
+  change: Change,
+  integration?: ResolvedIntegration,
+): string {
+  return integration?.serialize?.(change) ?? change.serialize();
+}
+
+function buildFileEntry(
+  path: string,
+  metadata: FileEntry["metadata"],
+  statements: string[],
+  order: number,
+  formatOptions?: SqlFormatOptions,
+): FileEntry {
+  return {
+    path,
+    order,
+    statements: statements.length,
+    sql: formatSqlScript(statements, formatOptions),
+    metadata,
+  };
+}

package/src/core/export/types.ts

@@ -0,0 +1,104 @@
+/**
+ * Type definitions for declarative schema export.
+ */
+
+// ============================================================================
+// File Categories
+// ============================================================================
+
+export const CATEGORY_PRIORITY = {
+  cluster: 0,
+  schema: 1,
+  extensions: 2,
+  types: 3,
+  sequences: 4,
+  tables: 5,
+  foreign_tables: 6,
+  views: 7,
+  matviews: 8,
+  functions: 9,
+  procedures: 10,
+  aggregates: 11,
+  domains: 12,
+  collations: 13,
+  publications: 14,
+  subscriptions: 15,
+  event_triggers: 16,
+} as const;
+
+export type FileCategory = keyof typeof CATEGORY_PRIORITY;
+
+// ============================================================================
+// Output Types
+// ============================================================================
+
+export interface FileMetadata {
+  objectType: string;
+  schemaName?: string;
+  objectName?: string;
+}
+
+export interface FileEntry {
+  path: string;
+  order: number;
+  statements: number;
+  sql: string;
+  metadata: FileMetadata;
+}
+
+export interface DeclarativeSchemaOutput {
+  version: 1;
+  mode: "declarative";
+  generatedAt: string;
+  source: { fingerprint: string };
+  target: { fingerprint: string };
+  files: FileEntry[];
+}
+
+// ============================================================================
+// Entity Grouping
+// ============================================================================
+
+/** A regex pattern with a group name used as the directory or file name. */
+export interface GroupingPattern {
+  /** Regex to test against the object name. Strings are compiled to RegExp. */
+  pattern: string | RegExp;
+  /** Group name used as the directory or file name. */
+  name: string;
+}
+
+export interface Grouping {
+  /** How grouped entities are organized on disk. */
+  mode: "single-file" | "subdirectory";
+  /**
+   * Regex-based patterns to match object names.
+   * First matching pattern wins -- ordering controls priority.
+   *
+   * Examples:
+   * - `{ pattern: /^project/, name: "project" }`  – prefix
+   * - `{ pattern: /organization/, name: "organization" }` – contains
+   * - `{ pattern: /tokens$/, name: "tokens" }` – suffix
+   */
+  groupPatterns?: GroupingPattern[];
+  /**
+   * Automatically detect partitioned tables and group partitions with
+   * their parent table.  Defaults to `true`.
+   */
+  autoGroupPartitions?: boolean;
+  /**
+   * Schemas to flatten: all objects are merged into one file per category.
+   * e.g. `schemas/partman/tables.sql` instead of `schemas/partman/tables/foo.sql`.
+   * Useful for small or extension schemas that don't need per-object files.
+   */
+  flatSchemas?: string[];
+}
+
+// ============================================================================
+// Internal Types
+// ============================================================================
+
+export interface FilePath {
+  path: string;
+  category: FileCategory;
+  metadata: FileMetadata;
+}

package/src/core/fingerprint.ts

@@ -0,0 +1,204 @@
+import crypto from "node:crypto";
+import type { Catalog } from "./catalog.model.ts";
+import type { Change } from "./change.types.ts";
+import type { BasePgModel } from "./objects/base.model.ts";
+
+/**
+ * Build a deterministic fingerprint for the objects actually touched by a plan.
+ * Uses the stableIds declared by the changes (creates/requires/drops) and snapshots
+ * only the catalog entities that exist for those stableIds (parent objects, no virtuals).
+ */
+export function buildPlanScopeFingerprint(
+  catalog: Catalog,
+  changes: Change[],
+): { hash: string; stableIds: string[] } {
+  const stableIds = collectStableIds(changes);
+  const hash = hashStableIds(catalog, stableIds);
+  return { hash, stableIds };
+}
+
+/**
+ * Compute a fingerprint from a catalog and a set of stableIds.
+ */
+export function hashStableIds(catalog: Catalog, stableIds: string[]): string {
+  const catalogLookup = buildCatalogLookup(catalog);
+
+  const projection: Array<{
+    stableId: string;
+    snapshot: { identity: unknown; data: unknown };
+  }> = [];
+
+  for (const stableId of stableIds) {
+    const record = catalogLookup[stableId];
+    if (!record) {
+      continue;
+    }
+    projection.push({
+      stableId,
+      snapshot: record.stableSnapshot(),
+    });
+  }
+
+  const canonical = stableStringify(projection);
+  return sha256(canonical);
+}
+
+/**
+ * Hash a string to hex SHA256.
+ */
+function sha256(input: string): string {
+  return crypto.createHash("sha256").update(input).digest("hex");
+}
+
+/**
+ * Collect the union of stableIds referenced by all changes.
+ */
+function collectStableIds(changes: Change[]): string[] {
+  const ids = new Set<string>();
+
+  for (const change of changes) {
+    for (const id of getChangeStableIds(change)) {
+      ids.add(id);
+    }
+  }
+
+  return Array.from(ids).sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Gather the stableIds a change touches (creates/requires/drops) and, when the
+ * change has a primary entity with a stableId, include it as well.
+ */
+function getChangeStableIds(change: Change): string[] {
+  const ids: string[] = [];
+
+  // Dependencies declared on the change.
+  ids.push(...change.creates, ...change.requires, ...change.drops);
+
+  // Best-effort primary entity stableId, when available.
+  const primary = getPrimaryStableId(change);
+  if (primary) ids.push(primary);
+
+  return ids;
+}
+
+/**
+ * Extract the primary entity stableId for a change, when it exists.
+ */
+function getPrimaryStableId(change: Change): string | null {
+  switch (change.objectType) {
+    case "aggregate":
+      return change.aggregate.stableId;
+    case "collation":
+      return change.collation.stableId;
+    case "composite_type":
+      return change.compositeType.stableId;
+    case "domain":
+      return change.domain.stableId;
+    case "enum":
+      return change.enum.stableId;
+    case "event_trigger":
+      return change.eventTrigger.stableId;
+    case "extension":
+      return change.extension.stableId;
+    case "foreign_data_wrapper":
+      return change.foreignDataWrapper.stableId;
+    case "foreign_table":
+      return change.foreignTable.stableId;
+    case "index":
+      return change.index.stableId;
+    case "language":
+      return change.language.stableId;
+    case "materialized_view":
+      return change.materializedView.stableId;
+    case "procedure":
+      return change.procedure.stableId;
+    case "publication":
+      return change.publication.stableId;
+    case "range":
+      return change.range.stableId;
+    case "role":
+      return change.role.stableId;
+    case "schema":
+      return change.schema.stableId;
+    case "sequence":
+      return change.sequence.stableId;
+    case "server":
+      return change.server.stableId;
+    case "subscription":
+      return change.subscription.stableId;
+    case "table":
+      return change.table.stableId;
+    case "trigger":
+      return change.trigger.stableId;
+    case "rls_policy":
+      return change.policy.stableId;
+    case "rule":
+      return change.rule.stableId;
+    case "view":
+      return change.view.stableId;
+    case "user_mapping":
+      return change.userMapping.stableId;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Build a flat lookup of catalog objects keyed by stableId.
+ */
+function buildCatalogLookup(catalog: Catalog): Record<string, BasePgModel> {
+  return {
+    ...catalog.aggregates,
+    ...catalog.collations,
+    ...catalog.compositeTypes,
+    ...catalog.domains,
+    ...catalog.enums,
+    ...catalog.extensions,
+    ...catalog.procedures,
+    ...catalog.indexes,
+    ...catalog.materializedViews,
+    ...catalog.subscriptions,
+    ...catalog.publications,
+    ...catalog.rlsPolicies,
+    ...catalog.roles,
+    ...catalog.schemas,
+    ...catalog.sequences,
+    ...catalog.tables,
+    ...catalog.triggers,
+    ...catalog.eventTriggers,
+    ...catalog.rules,
+    ...catalog.ranges,
+    ...catalog.views,
+    ...catalog.foreignDataWrappers,
+    ...catalog.servers,
+    ...catalog.userMappings,
+    ...catalog.foreignTables,
+  };
+}
+
+/**
+ * Deterministic stringify with sorted object keys.
+ */
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "bigint") {
+      return JSON.stringify(value.toString());
+    }
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(",")}]`;
+  }
+
+  const entries = Object.entries(value as Record<string, unknown>).sort(
+    ([a], [b]) => a.localeCompare(b),
+  );
+
+  const inner = entries
+    .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)
+    .join(",");
+
+  return `{${inner}}`;
+}