@voltro/data-transfer 0.33.0 → 0.35.0

package/dist/index.d.ts

@@ -20,15 +20,25 @@ import { YieldableError } from 'effect/Cause';
 export declare const applyAction: (action: MaskAction, input: MaskInput) => unknown;
 
 /**
- * Refuse a direct/native import when a live instance is detected, unless the
- * operator passed `--allow-live`. `liveInstance` is a human label (url/name) of
- * the detected instance, or `null` when none was found (or detection was
- * inconclusive — the CLI treats "can't tell" as "not detected" so the common
- * import-into-a-stopped-target case isn't blocked).
+ * Refuse a direct/native import when a live instance is writing to the SAME
+ * database, unless the operator passed `--allow-live`.
+ *
+ * @param liveInstance human label (url/name) of a detected instance, or `null`
+ *   when none answered — detection is best-effort, and "can't tell" is treated
+ *   as "not detected" so importing into a stopped target is not blocked.
+ * @param sameTarget whether that instance is connected to the database being
+ *   written. `'unknown'` when either side could not be identified (an older
+ *   instance, an unparseable connection) — and it must behave like `'same'`,
+ *   because the alternative is a guard that steps aside whenever it is unsure.
+ * @param targetLabel what the CLI resolved as the target, for the message. A
+ *   refusal that names only one of the two things it is comparing is why
+ *   `--allow-live` became a reflex.
  */
 export declare const assessLiveImport: (opts: {
     readonly liveInstance: string | null;
     readonly allowLive: boolean;
+    readonly sameTarget?: "same" | "different" | "unknown";
+    readonly targetLabel?: string;
 }) => LiveGuardResult;
 
 export declare const ASSET_INDEX_FILE = "assets/index.ndjson";
@@ -499,6 +509,28 @@ export declare const formatIssue: (i: PortabilityIssue) => string;
 /** True when this Node build exposes the native zstd streams (Node ≥ 22.15). */
 export declare const hasZstd: () => boolean;
 
+/**
+ * A dialect-native bulk loader the CALLER wires in (PERF-13). The importer
+ * never imports a dialect package; the CLI hands it `@voltro/sql-postgres`'s
+ * `makePgCopySession(...)` when the target is postgres, and the importer uses
+ * it ONLY where plain-INSERT semantics provably hold (see `tablePhase`).
+ *
+ * Contract the fast path relies on: `copyInto` is atomic per call — a failed
+ * batch applied NOTHING, so the importer can replay exactly that batch through
+ * the per-row path (held-row / deferred-FK semantics intact) without
+ * double-writing a prefix.
+ */
+export declare interface ImportCopyLoader {
+    /** Dialect this loader serves; the importer only engages it for `postgres`. */
+    readonly dialect: string;
+    readonly copyInto: (batch: {
+        readonly table: string;
+        readonly columns: ReadonlyArray<string>;
+        readonly columnTypes?: Readonly<Record<string, string>>;
+        readonly rows: ReadonlyArray<Row>;
+    }) => Promise<number>;
+}
+
 export declare type ImportError = BundleError | CodecError | IntegrityError | CrossDialectError | ImportModeError | DanglingReferenceError | SchemaDriftError | StorageError;
 
 /**
@@ -580,6 +612,19 @@ export declare interface ImportOptions {
      *  event per table — off the per-row hot path. Independent of the always-on
      *  `Effect.withSpan` + metrics per table. */
     readonly onProgress?: OnProgress;
+    /**
+     * Optional dialect-native bulk loader (postgres `COPY … FROM STDIN`). Used
+     * per table only when plain-INSERT semantics hold: `replace` mode (tables
+     * pre-truncated) or `upsert` into a table that is EMPTY at import time — and
+     * never under `atomic` (the loader runs on its own connection, outside the
+     * transaction). Everything else keeps the per-row `DataStore` writes. A
+     * failed COPY batch falls back to the per-row path for exactly that batch,
+     * so held-row / deferred-FK semantics are preserved.
+     */
+    readonly copyLoader?: ImportCopyLoader;
+    /** Rows per COPY statement on the fast path. Default 5000 — bounds the
+     *  batch the importer holds in memory AND the batch a fallback replays. */
+    readonly copyBatchSize?: number;
 }
 
 /** An integrity check failed — a table's content checksum or row count did not