goldenmatch 0.1.0

package/src/node/db/postgres.ts

@@ -0,0 +1,173 @@
+/**
+ * postgres.ts -- Optional Postgres connector for Node.
+ *
+ * Mirrors `goldenmatch.db.connector.PostgresConnector` from Python.
+ *
+ * Peer dependency (NOT in package.json -- install on demand):
+ *   npm install pg
+ *
+ * The dep is loaded via `createRequire` so the package stays importable
+ * on edge runtimes and in environments without Postgres.
+ */
+
+import { createRequire } from "node:module";
+import type { Row } from "../../core/types.js";
+
+export interface PostgresConfig {
+  readonly connectionString?: string;
+  readonly host?: string;
+  readonly port?: number;
+  readonly database?: string;
+  readonly user?: string;
+  readonly password?: string;
+  readonly ssl?: boolean;
+}
+
+export interface PostgresWriteOptions {
+  readonly upsert?: boolean;
+  readonly primaryKey?: string;
+}
+
+export interface PostgresConnector {
+  connect(): Promise<void>;
+  query<T = Row>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+  readTable(table: string): Promise<Row[]>;
+  writeTable(
+    table: string,
+    rows: readonly Row[],
+    options?: PostgresWriteOptions,
+  ): Promise<void>;
+  listTables(schema?: string): Promise<string[]>;
+  close(): Promise<void>;
+}
+
+/** Minimal shape of `pg.Client` we use. */
+interface PgClient {
+  connect(): Promise<void>;
+  query(sql: string, params?: readonly unknown[]): Promise<{ rows: unknown[] }>;
+  end(): Promise<void>;
+}
+
+interface PgModule {
+  Client: new (config: unknown) => PgClient;
+}
+
+/**
+ * Create a Postgres connector. Throws if `pg` isn't installed.
+ *
+ * The returned connector requires `connect()` before any query. Inserts
+ * are batched in chunks of 1000 rows. When `options.upsert` is set, the
+ * write uses `INSERT ... ON CONFLICT (primaryKey) DO UPDATE`.
+ */
+export function createPostgresConnector(
+  config: PostgresConfig,
+): PostgresConnector {
+  const require = createRequire(import.meta.url);
+  let pg: PgModule;
+  try {
+    pg = require("pg") as PgModule;
+  } catch {
+    throw new Error(
+      "'pg' is required for Postgres support. Install: npm install pg",
+    );
+  }
+
+  const clientConfig: Record<string, unknown> = {};
+  if (config.connectionString !== undefined) {
+    clientConfig["connectionString"] = config.connectionString;
+  }
+  if (config.host !== undefined) clientConfig["host"] = config.host;
+  if (config.port !== undefined) clientConfig["port"] = config.port;
+  if (config.database !== undefined) clientConfig["database"] = config.database;
+  if (config.user !== undefined) clientConfig["user"] = config.user;
+  if (config.password !== undefined) clientConfig["password"] = config.password;
+  if (config.ssl !== undefined) clientConfig["ssl"] = config.ssl;
+
+  const client = new pg.Client(clientConfig);
+
+  const escapeIdent = (s: string): string => `"${s.replace(/"/g, '""')}"`;
+
+  const writeTable = async (
+    table: string,
+    rows: readonly Row[],
+    options: PostgresWriteOptions = {},
+  ): Promise<void> => {
+    if (rows.length === 0) return;
+
+    const first = rows[0]!;
+    const cols = Object.keys(first);
+    const tableIdent = escapeIdent(table);
+    const colNames = cols.map(escapeIdent).join(", ");
+
+    const BATCH_SIZE = 1000;
+    for (let i = 0; i < rows.length; i += BATCH_SIZE) {
+      const batch = rows.slice(i, i + BATCH_SIZE);
+
+      const valueClauses = batch
+        .map((_row, idx) => {
+          const offset = idx * cols.length;
+          return `(${cols.map((_, j) => `$${offset + j + 1}`).join(", ")})`;
+        })
+        .join(", ");
+
+      const params: unknown[] = [];
+      for (const row of batch) {
+        for (const c of cols) {
+          params.push((row as Record<string, unknown>)[c]);
+        }
+      }
+
+      let sql = `INSERT INTO ${tableIdent} (${colNames}) VALUES ${valueClauses}`;
+
+      if (options.upsert === true && options.primaryKey !== undefined) {
+        const pk = options.primaryKey;
+        const updates = cols
+          .filter((c) => c !== pk)
+          .map((c) => `${escapeIdent(c)} = EXCLUDED.${escapeIdent(c)}`)
+          .join(", ");
+        if (updates.length > 0) {
+          sql += ` ON CONFLICT (${escapeIdent(pk)}) DO UPDATE SET ${updates}`;
+        } else {
+          sql += ` ON CONFLICT (${escapeIdent(pk)}) DO NOTHING`;
+        }
+      }
+
+      await client.query(sql, params);
+    }
+  };
+
+  return {
+    async connect(): Promise<void> {
+      await client.connect();
+    },
+
+    async query<T = Row>(
+      sql: string,
+      params: readonly unknown[] = [],
+    ): Promise<T[]> {
+      const result = await client.query(sql, params);
+      return result.rows as T[];
+    },
+
+    async readTable(table: string): Promise<Row[]> {
+      const result = await client.query(`SELECT * FROM ${escapeIdent(table)}`);
+      return result.rows as Row[];
+    },
+
+    writeTable,
+
+    async listTables(schema: string = "public"): Promise<string[]> {
+      const result = await client.query(
+        "SELECT table_name FROM information_schema.tables WHERE table_schema = $1",
+        [schema],
+      );
+      return (result.rows as Array<Record<string, unknown>>).map((r) =>
+        String(r["table_name"] ?? ""),
+      );
+    },
+
+    async close(): Promise<void> {
+      await client.end();
+    },
+  };
+}

package/src/node/db/sync.ts

@@ -0,0 +1,103 @@
+/**
+ * sync.ts -- Postgres-backed dedupe sync + watch helpers.
+ *
+ * Mirrors `goldenmatch.db.sync` from Python: read source table, run
+ * dedupe, write golden + cluster tables back to Postgres.
+ */
+
+import { dedupe } from "../../core/api.js";
+import type { DedupeResult, GoldenMatchConfig } from "../../core/types.js";
+import {
+  createPostgresConnector,
+  type PostgresConfig,
+} from "./postgres.js";
+
+export interface SyncOptions {
+  readonly pg: PostgresConfig;
+  readonly sourceTable: string;
+  readonly goldenTable: string;
+  /** Optional table to write cluster summaries (cluster_id, members, size, ...). */
+  readonly clustersTable?: string;
+  readonly config: GoldenMatchConfig;
+}
+
+/**
+ * Run a single dedupe pass against Postgres.
+ *
+ * 1. Read all rows from `sourceTable`.
+ * 2. Dedupe via the core pipeline.
+ * 3. Write golden records to `goldenTable`.
+ * 4. Optionally write cluster summaries to `clustersTable`.
+ *
+ * Always closes the connection on the way out.
+ */
+export async function syncDedupe(options: SyncOptions): Promise<DedupeResult> {
+  const conn = createPostgresConnector(options.pg);
+  try {
+    await conn.connect();
+    const rows = await conn.readTable(options.sourceTable);
+    const result = dedupe(rows, { config: options.config });
+
+    await conn.writeTable(options.goldenTable, result.goldenRecords);
+
+    if (options.clustersTable !== undefined && result.clusters.size > 0) {
+      const clusterRows = Array.from(result.clusters.entries()).map(
+        ([id, c]) => ({
+          cluster_id: id,
+          members: JSON.stringify(c.members),
+          size: c.size,
+          confidence: c.confidence,
+          quality: c.clusterQuality,
+        }),
+      );
+      await conn.writeTable(options.clustersTable, clusterRows);
+    }
+
+    return result;
+  } finally {
+    await conn.close();
+  }
+}
+
+export interface WatchSyncOptions extends SyncOptions {
+  /** Polling interval in ms. Defaults to 60_000 (1 minute). */
+  readonly intervalMs?: number;
+}
+
+/**
+ * Run `syncDedupe` on a recurring interval.
+ *
+ * Returns a `stop` function. Errors in any iteration are logged via
+ * `console.warn` so the loop keeps running; callers should monitor
+ * `onResult` to confirm forward progress.
+ */
+export async function watchSync(
+  options: WatchSyncOptions,
+  onResult?: (result: DedupeResult) => void,
+): Promise<() => void> {
+  const intervalMs = options.intervalMs ?? 60_000;
+  let stopped = false;
+
+  const loop = async (): Promise<void> => {
+    while (!stopped) {
+      try {
+        const result = await syncDedupe(options);
+        onResult?.(result);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn("syncDedupe failed:", msg);
+      }
+      if (stopped) break;
+      await new Promise<void>((resolve) => setTimeout(resolve, intervalMs));
+    }
+  };
+
+  loop().catch((err: unknown) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn("watchSync loop error:", msg);
+  });
+
+  return (): void => {
+    stopped = true;
+  };
+}

package/src/node/dedupe-file.ts

@@ -0,0 +1,156 @@
+/**
+ * dedupe-file.ts -- File-based convenience wrappers around dedupe() / match().
+ *
+ * Node-only: reads from disk, tags rows with __source__, delegates to the
+ * edge-safe core API.
+ */
+
+import { readFile, writeCsv, writeJson } from "./connectors/file.js";
+import { dedupe, match } from "../core/api.js";
+import type {
+  Row,
+  DedupeResult,
+  MatchResult,
+  GoldenMatchConfig,
+} from "../core/types.js";
+import { extname, basename } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/**
+ * File specification. Either a bare path (source name is derived from the
+ * file's basename without extension) or a tuple `[path, sourceName]`.
+ */
+export type FileSpec = string | readonly [string, string];
+
+export interface FileDedupeOptions {
+  /** Input files. Required when calling `dedupeFile(opts)`. */
+  readonly files?: readonly FileSpec[];
+  /** Full config -- takes precedence over shorthand fields below. */
+  readonly config?: GoldenMatchConfig;
+  readonly exact?: readonly string[];
+  readonly fuzzy?: Readonly<Record<string, number>>;
+  readonly blocking?: readonly string[];
+  readonly threshold?: number;
+  /** Enable LLM scorer for borderline pairs (not yet implemented in JS). */
+  readonly llmScorer?: boolean;
+  /** Write golden records to this path (.csv or .json). */
+  readonly outputPath?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function defaultSourceName(path: string, index: number): string {
+  const base = basename(path, extname(path));
+  return base && base.length > 0 ? base : `file_${index}`;
+}
+
+function resolveFileSpec(
+  spec: FileSpec,
+  index: number,
+): { path: string; sourceName: string } {
+  if (typeof spec === "string") {
+    return { path: spec, sourceName: defaultSourceName(spec, index) };
+  }
+  const [path, sourceName] = spec;
+  return { path, sourceName };
+}
+
+function loadRowsWithSource(files: readonly FileSpec[]): Row[] {
+  const all: Row[] = [];
+  for (let i = 0; i < files.length; i++) {
+    const { path, sourceName } = resolveFileSpec(files[i]!, i);
+    const rows = readFile(path);
+    for (const row of rows) {
+      all.push({ ...row, __source__: sourceName });
+    }
+  }
+  return all;
+}
+
+function buildCoreOptions(opts: FileDedupeOptions) {
+  const core: {
+    config?: GoldenMatchConfig;
+    exact?: readonly string[];
+    fuzzy?: Readonly<Record<string, number>>;
+    blocking?: readonly string[];
+    threshold?: number;
+    llmScorer?: boolean;
+  } = {};
+  if (opts.config !== undefined) core.config = opts.config;
+  if (opts.exact !== undefined) core.exact = opts.exact;
+  if (opts.fuzzy !== undefined) core.fuzzy = opts.fuzzy;
+  if (opts.blocking !== undefined) core.blocking = opts.blocking;
+  if (opts.threshold !== undefined) core.threshold = opts.threshold;
+  if (opts.llmScorer !== undefined) core.llmScorer = opts.llmScorer;
+  return core;
+}
+
+function writeGoldenRecords(
+  outputPath: string,
+  rows: readonly Row[],
+): void {
+  const ext = extname(outputPath).toLowerCase();
+  if (ext === ".json" || ext === ".jsonl" || ext === ".ndjson") {
+    writeJson(outputPath, rows);
+  } else {
+    // Default to CSV (includes `.csv`, `.tsv`, or unknown extensions).
+    const delimiter = ext === ".tsv" ? "\t" : ",";
+    writeCsv(outputPath, rows, { delimiter });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Deduplicate records across one or more files.
+ *
+ * Each file's rows are tagged with `__source__ = <sourceName>` before being
+ * concatenated and passed to `dedupe()`.
+ *
+ * @throws if no files are provided or any file cannot be read.
+ */
+export function dedupeFile(opts: FileDedupeOptions): DedupeResult {
+  if (!opts.files || opts.files.length === 0) {
+    throw new Error("dedupeFile: at least one input file is required");
+  }
+  const rows = loadRowsWithSource(opts.files);
+  const result = dedupe(rows, buildCoreOptions(opts));
+  if (opts.outputPath) {
+    writeGoldenRecords(opts.outputPath, result.goldenRecords);
+  }
+  return result;
+}
+
+/**
+ * Match target records against a reference file.
+ *
+ * Reads both files, tags with `__source__`, and delegates to `match()`.
+ * `opts.files` (if provided) is ignored in favor of the explicit paths.
+ */
+export function matchFiles(
+  targetPath: string,
+  referencePath: string,
+  opts?: FileDedupeOptions,
+): MatchResult {
+  const targetRows = readFile(targetPath).map((row) => ({
+    ...row,
+    __source__: "target",
+  }));
+  const referenceRows = readFile(referencePath).map((row) => ({
+    ...row,
+    __source__: "reference",
+  }));
+
+  const result = match(targetRows, referenceRows, buildCoreOptions(opts ?? {}));
+  if (opts?.outputPath) {
+    writeGoldenRecords(opts.outputPath, result.matched);
+  }
+  return result;
+}

package/src/node/index.ts

@@ -0,0 +1,89 @@
+/**
+ * index.ts -- Node.js entry point for GoldenMatch.
+ *
+ * Re-exports the edge-safe core API plus Node-only helpers that use
+ * `node:fs`, `node:path`, and the optional `yaml` peer dependency.
+ */
+
+// Re-export everything from the edge-safe core
+export * from "../core/index.js";
+
+// Node-only file I/O
+export {
+  readCsv,
+  readJson,
+  readFile,
+  writeCsv,
+  writeJson,
+} from "./connectors/file.js";
+export type {
+  ReadCsvOptions,
+  WriteCsvOptions,
+} from "./connectors/file.js";
+
+// File-based dedupe / match
+export { dedupeFile, matchFiles } from "./dedupe-file.js";
+export type { FileDedupeOptions, FileSpec } from "./dedupe-file.js";
+
+// YAML config file I/O
+export { loadConfigFile, writeConfigFile } from "./config-file.js";
+
+// Cloud connectors (registers built-in connectors as a side-effect)
+export {
+  createSnowflakeConnector,
+  createBigQueryConnector,
+  createDatabricksConnector,
+  createSalesforceConnector,
+  createHubSpotConnector,
+  registerConnector,
+  loadConnector,
+  listConnectors,
+} from "./connectors/index.js";
+export type {
+  BaseConnector,
+  ConnectorConfig,
+  ConnectorFactory,
+  ConnectorQuery,
+  SnowflakeConfig,
+  BigQueryConfig,
+  DatabricksConfig,
+  SalesforceConfig,
+  HubSpotConfig,
+} from "./connectors/index.js";
+
+// Servers (MCP / REST / A2A)
+export { startMcpServer, handleTool, TOOLS } from "./mcp/server.js";
+export { startApiServer, ReviewQueue } from "./api/server.js";
+export type { StartApiOptions } from "./api/server.js";
+export { startA2aServer, AGENT_CARD } from "./a2a/server.js";
+export type { StartA2aOptions, AgentSkill } from "./a2a/server.js";
+
+// Concurrent / parallel block scoring (Node-only; uses dynamic import of core scorer).
+// `scoreBlocksParallel` uses piscina for true worker-thread parallelism when the
+// optional `piscina` peer dep is installed; falls back to `scoreBlocksConcurrent`.
+export {
+  scoreBlocksConcurrent,
+  scoreBlocksParallel,
+} from "./backends/workers.js";
+export type {
+  WorkerPoolOptions,
+  ParallelWorkerOptions,
+} from "./backends/workers.js";
+
+// Optional DuckDB connector (peer dep: @duckdb/node-api -- install on demand)
+export { createDuckDBConnector } from "./backends/duckdb.js";
+export type { DuckDBConfig, DuckDBConnector } from "./backends/duckdb.js";
+
+// Optional Postgres connector + sync helpers (peer dep: pg -- install on demand)
+export { createPostgresConnector } from "./db/postgres.js";
+export type {
+  PostgresConfig,
+  PostgresConnector,
+  PostgresWriteOptions,
+} from "./db/postgres.js";
+export { syncDedupe, watchSync } from "./db/sync.js";
+export type { SyncOptions, WatchSyncOptions } from "./db/sync.js";
+
+// Interactive TUI (optional peer deps: ink + react)
+export { startTui } from "./tui/app.js";
+export type { TuiOptions } from "./tui/app.js";