lakesync 0.1.0

package/dist/analyst.js

@@ -0,0 +1,495 @@
+import {
+  Err,
+  LakeSyncError,
+  Ok
+} from "./chunk-ICNT7I3K.js";
+import "./chunk-7D4SUZUM.js";
+
+// ../analyst/src/duckdb.ts
+var DuckDBClient = class {
+  _config;
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  _db = null;
+  _conn = null;
+  _closed = false;
+  constructor(config) {
+    this._config = config ?? {};
+  }
+  /**
+   * Initialise the DuckDB-Wasm instance and open a connection.
+   *
+   * Uses the blocking Node.js bindings when running in Node/Bun,
+   * which avoids the need for Worker threads.
+   *
+   * @returns A Result indicating success or failure with a LakeSyncError
+   */
+  async init() {
+    try {
+      const duckdb = await import("@duckdb/duckdb-wasm/blocking");
+      const path = await import("path");
+      const { createRequire } = await import("module");
+      const require2 = createRequire(import.meta.url);
+      const blockingEntry = require2.resolve("@duckdb/duckdb-wasm/dist/duckdb-node-blocking.cjs");
+      const duckdbPkgPath = path.dirname(path.dirname(blockingEntry));
+      const bundles = {
+        mvp: {
+          mainModule: path.join(duckdbPkgPath, "dist", "duckdb-mvp.wasm"),
+          mainWorker: path.join(duckdbPkgPath, "dist", "duckdb-node-mvp.worker.cjs")
+        },
+        eh: {
+          mainModule: path.join(duckdbPkgPath, "dist", "duckdb-eh.wasm"),
+          mainWorker: path.join(duckdbPkgPath, "dist", "duckdb-node-eh.worker.cjs")
+        }
+      };
+      const logger = this._config.logger ? new duckdb.ConsoleLogger() : new duckdb.VoidLogger();
+      const db = await duckdb.createDuckDB(bundles, logger, duckdb.NODE_RUNTIME);
+      await db.instantiate(() => {
+      });
+      if (this._config.threads !== void 0) {
+        db.open({ maximumThreads: this._config.threads });
+      }
+      const conn = db.connect();
+      this._db = db;
+      this._conn = conn;
+      this._closed = false;
+      return Ok(void 0);
+    } catch (err) {
+      const cause = err instanceof Error ? err : new Error(String(err));
+      return Err(
+        new LakeSyncError(
+          `Failed to initialise DuckDB-Wasm: ${cause.message}`,
+          "ANALYST_ERROR",
+          cause
+        )
+      );
+    }
+  }
+  /**
+   * Execute a SQL query and return the results as an array of objects.
+   *
+   * @param sql - The SQL statement to execute
+   * @param _params - Reserved for future use (parameterised queries)
+   * @returns A Result containing the query results or a LakeSyncError
+   */
+  async query(sql, _params) {
+    try {
+      if (this._closed || !this._conn) {
+        return Err(
+          new LakeSyncError(
+            "Cannot query: DuckDB connection is closed or not initialised",
+            "ANALYST_ERROR"
+          )
+        );
+      }
+      const arrowTable = this._conn.query(sql);
+      const rows = arrowTable.toArray();
+      const plainRows = rows.map((row) => ({ ...row }));
+      return Ok(plainRows);
+    } catch (err) {
+      const cause = err instanceof Error ? err : new Error(String(err));
+      return Err(
+        new LakeSyncError(`DuckDB query failed: ${cause.message}`, "ANALYST_ERROR", cause)
+      );
+    }
+  }
+  /**
+   * Register an in-memory Parquet file as a named table that can be
+   * queried using `SELECT * FROM '<name>'`.
+   *
+   * @param name - The virtual file name (e.g. "deltas.parquet")
+   * @param data - The Parquet file contents as a Uint8Array
+   * @returns A Result indicating success or failure
+   */
+  async registerParquetBuffer(name, data) {
+    try {
+      if (this._closed || !this._db) {
+        return Err(
+          new LakeSyncError(
+            "Cannot register Parquet buffer: DuckDB is closed or not initialised",
+            "ANALYST_ERROR"
+          )
+        );
+      }
+      this._db.registerFileBuffer(name, data);
+      return Ok(void 0);
+    } catch (err) {
+      const cause = err instanceof Error ? err : new Error(String(err));
+      return Err(
+        new LakeSyncError(
+          `Failed to register Parquet buffer "${name}": ${cause.message}`,
+          "ANALYST_ERROR",
+          cause
+        )
+      );
+    }
+  }
+  /**
+   * Register a remote Parquet file by URL so it can be queried using
+   * `SELECT * FROM '<name>'`.
+   *
+   * @param name - The virtual file name (e.g. "remote.parquet")
+   * @param url - The URL pointing to the Parquet file
+   * @returns A Result indicating success or failure
+   */
+  async registerParquetUrl(name, url) {
+    try {
+      if (this._closed || !this._db) {
+        return Err(
+          new LakeSyncError(
+            "Cannot register Parquet URL: DuckDB is closed or not initialised",
+            "ANALYST_ERROR"
+          )
+        );
+      }
+      const HTTP_PROTOCOL = 1;
+      this._db.registerFileURL(name, url, HTTP_PROTOCOL, false);
+      return Ok(void 0);
+    } catch (err) {
+      const cause = err instanceof Error ? err : new Error(String(err));
+      return Err(
+        new LakeSyncError(
+          `Failed to register Parquet URL "${name}": ${cause.message}`,
+          "ANALYST_ERROR",
+          cause
+        )
+      );
+    }
+  }
+  /**
+   * Tear down the DuckDB connection and database instance.
+   *
+   * After calling close(), any subsequent query or registration calls
+   * will return an error Result.
+   */
+  async close() {
+    if (this._conn) {
+      try {
+        this._conn.close();
+      } catch {
+      }
+      this._conn = null;
+    }
+    this._db = null;
+    this._closed = true;
+  }
+};
+
+// ../analyst/src/time-travel.ts
+var SYSTEM_COLUMNS = /* @__PURE__ */ new Set(["op", "table", "rowId", "clientId", "hlc", "deltaId"]);
+var TimeTraveller = class {
+  _config;
+  _sources = [];
+  constructor(config) {
+    this._config = config;
+  }
+  /**
+   * Register one or more Parquet buffers containing delta data.
+   *
+   * Each buffer is registered with DuckDB and can subsequently be
+   * queried via the time-travel methods.
+   *
+   * @param parquetBuffers - Array of named Parquet file buffers to register
+   * @returns A Result indicating success or a LakeSyncError on failure
+   */
+  async registerDeltas(parquetBuffers) {
+    try {
+      for (const buf of parquetBuffers) {
+        const regResult = await this._config.duckdb.registerParquetBuffer(buf.name, buf.data);
+        if (!regResult.ok) {
+          return regResult;
+        }
+        this._sources.push(buf.name);
+      }
+      return Ok(void 0);
+    } catch (err) {
+      const cause = err instanceof Error ? err : new Error(String(err));
+      return Err(
+        new LakeSyncError(
+          `Failed to register delta data: ${cause.message}`,
+          "ANALYST_ERROR",
+          cause
+        )
+      );
+    }
+  }
+  /**
+   * Query the materialised state as of the given HLC timestamp.
+   *
+   * Filters all deltas where `hlc <= asOfHlc`, then materialises the latest
+   * state per (table, rowId) using column-level LWW (highest HLC wins per
+   * column). The user's SQL is applied on top of the materialised view,
+   * which is exposed as the CTE `_state`.
+   *
+   * Deleted rows (where the latest operation is DELETE) are excluded from
+   * the materialised view.
+   *
+   * @param asOfHlc - The HLC timestamp representing the point in time to query
+   * @param sql - SQL to apply on the materialised view (use `_state` as the table name)
+   * @returns A Result containing the query results or a LakeSyncError
+   */
+  async queryAsOf(asOfHlc, sql) {
+    try {
+      if (this._sources.length === 0) {
+        return Ok([]);
+      }
+      const userColumns = await this._discoverUserColumns();
+      if (!userColumns.ok) {
+        return Err(userColumns.error);
+      }
+      const materialiseSql = this._buildMaterialiseSql(userColumns.value, BigInt(asOfHlc));
+      const finalSql = `WITH _state AS (${materialiseSql}) ${sql}`;
+      const result = await this._config.duckdb.query(finalSql);
+      if (!result.ok) {
+        return Err(result.error);
+      }
+      return Ok(result.value);
+    } catch (err) {
+      const cause = err instanceof Error ? err : new Error(String(err));
+      return Err(
+        new LakeSyncError(`Time-travel queryAsOf failed: ${cause.message}`, "ANALYST_ERROR", cause)
+      );
+    }
+  }
+  /**
+   * Query raw deltas within a time range.
+   *
+   * Filters deltas where `fromHlc < hlc <= toHlc` and returns them as raw
+   * (unmaterialised) rows. Useful for audit trails and changelog views.
+   *
+   * The user's SQL is applied on top of the filtered deltas, which are
+   * exposed as the CTE `_deltas`.
+   *
+   * @param fromHlc - The exclusive lower bound HLC timestamp
+   * @param toHlc - The inclusive upper bound HLC timestamp
+   * @param sql - SQL to apply on the filtered deltas (use `_deltas` as the table name)
+   * @returns A Result containing the query results or a LakeSyncError
+   */
+  async queryBetween(fromHlc, toHlc, sql) {
+    try {
+      if (this._sources.length === 0) {
+        return Ok([]);
+      }
+      const unionSql = this._buildUnionSql();
+      const fromBigint = BigInt(fromHlc);
+      const toBigint = BigInt(toHlc);
+      const filteredSql = `
+				SELECT * FROM (${unionSql}) AS _all
+				WHERE CAST(hlc AS BIGINT) > ${fromBigint}
+				  AND CAST(hlc AS BIGINT) <= ${toBigint}
+			`;
+      const finalSql = `WITH _deltas AS (${filteredSql}) ${sql}`;
+      const result = await this._config.duckdb.query(finalSql);
+      if (!result.ok) {
+        return Err(result.error);
+      }
+      return Ok(result.value);
+    } catch (err) {
+      const cause = err instanceof Error ? err : new Error(String(err));
+      return Err(
+        new LakeSyncError(
+          `Time-travel queryBetween failed: ${cause.message}`,
+          "ANALYST_ERROR",
+          cause
+        )
+      );
+    }
+  }
+  /**
+   * Materialise the full state at a point in time, returning all rows.
+   *
+   * Equivalent to `queryAsOf(asOfHlc, "SELECT * FROM _state")` but provided
+   * as a convenience method.
+   *
+   * @param asOfHlc - The HLC timestamp representing the point in time to materialise
+   * @returns A Result containing all materialised rows or a LakeSyncError
+   */
+  async materialiseAsOf(asOfHlc) {
+    return this.queryAsOf(asOfHlc, "SELECT * FROM _state");
+  }
+  /**
+   * Build a UNION ALL SQL expression covering all registered Parquet sources.
+   */
+  _buildUnionSql() {
+    return this._sources.map((s) => `SELECT * FROM '${s}'`).join(" UNION ALL BY NAME ");
+  }
+  /**
+   * Discover user-defined column names from the registered Parquet data.
+   *
+   * Reads the column names from the first registered source and filters
+   * out system columns to identify user-defined columns.
+   */
+  async _discoverUserColumns() {
+    if (this._sources.length === 0) {
+      return Ok([]);
+    }
+    const result = await this._config.duckdb.query(
+      `SELECT column_name FROM (DESCRIBE SELECT * FROM '${this._sources[0]}')`
+    );
+    if (!result.ok) {
+      return Err(result.error);
+    }
+    const userCols = result.value.map((r) => r.column_name).filter((name) => !SYSTEM_COLUMNS.has(name));
+    return Ok(userCols);
+  }
+  /**
+   * Build the materialisation SQL that reconstructs per-row state using
+   * column-level LWW semantics.
+   *
+   * Strategy:
+   * 1. Filter deltas by HLC <= asOfHlc
+   * 2. For each (table, rowId), determine the latest operation (by max HLC)
+   * 3. For each user column in each row, pick the value from the delta with
+   *    the highest HLC (where that column is not null)
+   * 4. Exclude rows where the latest operation is DELETE
+   *
+   * @param userColumns - Names of user-defined columns
+   * @param asOfHlc - The HLC timestamp cutoff as a bigint
+   * @returns SQL string producing the materialised view
+   */
+  _buildMaterialiseSql(userColumns, asOfHlc) {
+    const unionSql = this._buildUnionSql();
+    if (userColumns.length === 0) {
+      return `
+				SELECT "table", "rowId"
+				FROM (
+					SELECT *,
+						ROW_NUMBER() OVER (
+							PARTITION BY "table", "rowId"
+							ORDER BY CAST(hlc AS BIGINT) DESC
+						) AS _rn
+					FROM (${unionSql}) AS _all
+					WHERE CAST(hlc AS BIGINT) <= ${asOfHlc}
+				) AS _ranked
+				WHERE _rn = 1 AND op != 'DELETE'
+			`;
+    }
+    const columnSelects = userColumns.map((col) => {
+      return `LAST_VALUE("${col}" IGNORE NULLS) OVER (
+				PARTITION BY "table", "rowId"
+				ORDER BY CAST(hlc AS BIGINT) ASC
+				ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+			) AS "${col}"`;
+    });
+    const latestOpExpr = `LAST_VALUE(op) OVER (
+			PARTITION BY "table", "rowId"
+			ORDER BY CAST(hlc AS BIGINT) ASC
+			ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+		) AS _latest_op`;
+    const rowNumExpr = `ROW_NUMBER() OVER (
+			PARTITION BY "table", "rowId"
+			ORDER BY CAST(hlc AS BIGINT) DESC
+		) AS _rn`;
+    return `
+			SELECT "table", "rowId", ${userColumns.map((c) => `"${c}"`).join(", ")}
+			FROM (
+				SELECT
+					"table",
+					"rowId",
+					${columnSelects.join(",\n					")},
+					${latestOpExpr},
+					${rowNumExpr}
+				FROM (${unionSql}) AS _all
+				WHERE CAST(hlc AS BIGINT) <= ${asOfHlc}
+			) AS _materialised
+			WHERE _rn = 1 AND _latest_op != 'DELETE'
+		`;
+  }
+};
+
+// ../analyst/src/union-read.ts
+var UnionReader = class {
+  _config;
+  _coldSources = [];
+  _hotCounter = 0;
+  constructor(config) {
+    this._config = config;
+  }
+  /**
+   * Register one or more Parquet buffers as cold data sources.
+   *
+   * Each buffer is registered with DuckDB and can subsequently be
+   * queried alongside hot data via {@link query}.
+   *
+   * @param parquetBuffers - Array of named Parquet file buffers to register
+   * @returns A Result indicating success or a LakeSyncError on failure
+   */
+  async registerColdData(parquetBuffers) {
+    try {
+      for (const buf of parquetBuffers) {
+        const regResult = await this._config.duckdb.registerParquetBuffer(buf.name, buf.data);
+        if (!regResult.ok) {
+          return regResult;
+        }
+        this._coldSources.push(buf.name);
+      }
+      return Ok(void 0);
+    } catch (err) {
+      const cause = err instanceof Error ? err : new Error(String(err));
+      return Err(
+        new LakeSyncError(`Failed to register cold data: ${cause.message}`, "ANALYST_ERROR", cause)
+      );
+    }
+  }
+  /**
+   * Execute a SQL query that unions hot in-memory rows with cold Parquet data.
+   *
+   * The caller's SQL is wrapped around a UNION ALL of cold and hot sources.
+   * The unioned data is available as `_union` in the SQL statement.
+   *
+   * If `hotRows` is empty or not provided, only cold data is queried.
+   * If no cold sources are registered and `hotRows` is provided, only hot data is queried.
+   *
+   * @param sql - SQL to apply on top of the unioned data (use `_union` as the table name)
+   * @param hotRows - Optional array of in-memory row objects to include in the union
+   * @returns A Result containing the query results or a LakeSyncError
+   */
+  async query(sql, hotRows) {
+    try {
+      const hasHot = hotRows !== void 0 && hotRows.length > 0;
+      const hasCold = this._coldSources.length > 0;
+      if (!hasHot && !hasCold) {
+        return Ok([]);
+      }
+      const unionParts = [];
+      if (hasCold) {
+        for (const source of this._coldSources) {
+          unionParts.push(`SELECT * FROM '${source}'`);
+        }
+      }
+      if (hasHot) {
+        const hotBufferName = `_hot_${this._config.tableName}_${this._hotCounter++}.json`;
+        const jsonBytes = new TextEncoder().encode(JSON.stringify(hotRows));
+        const regResult = await this._config.duckdb.registerParquetBuffer(hotBufferName, jsonBytes);
+        if (!regResult.ok) {
+          return Err(regResult.error);
+        }
+        unionParts.push(`SELECT * FROM read_json_auto('${hotBufferName}')`);
+      }
+      const unionSql = unionParts.join(" UNION ALL BY NAME ");
+      const finalSql = `WITH _union AS (${unionSql}) ${sql}`;
+      const result = await this._config.duckdb.query(finalSql);
+      if (!result.ok) {
+        return Err(result.error);
+      }
+      return Ok(result.value);
+    } catch (err) {
+      const cause = err instanceof Error ? err : new Error(String(err));
+      return Err(new LakeSyncError(`Union query failed: ${cause.message}`, "ANALYST_ERROR", cause));
+    }
+  }
+  /**
+   * Query only cold (Parquet) data without any hot rows.
+   *
+   * @param sql - SQL to execute against cold data (use `_union` as the table name)
+   * @returns A Result containing the query results or a LakeSyncError
+   */
+  async queryColdOnly(sql) {
+    return this.query(sql);
+  }
+};
+export {
+  DuckDBClient,
+  TimeTraveller,
+  UnionReader
+};
+//# sourceMappingURL=analyst.js.map

package/dist/analyst.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../analyst/src/duckdb.ts","../../analyst/src/time-travel.ts","../../analyst/src/union-read.ts"],"sourcesContent":["import { Err, LakeSyncError, Ok, type Result } from \"@lakesync/core\";\n\n/**\n * Configuration options for the DuckDB-Wasm client.\n */\nexport interface DuckDBClientConfig {\n\t/** Whether to enable console logging from DuckDB. Defaults to false. */\n\tlogger?: boolean;\n\t/** Maximum number of threads for DuckDB. Defaults to 1. */\n\tthreads?: number;\n}\n\n/**\n * Wrapper around DuckDB-Wasm that provides a simplified, Result-based API\n * for executing SQL queries and registering Parquet data sources.\n *\n * Works in both Node.js/Bun (using the blocking bindings) and browser\n * environments (using the async worker-based bindings).\n *\n * @example\n * ```ts\n * const client = new DuckDBClient({ logger: false });\n * const initResult = await client.init();\n * if (!initResult.ok) { console.error(initResult.error); return; }\n *\n * const result = await client.query<{ answer: number }>(\"SELECT 42 AS answer\");\n * if (result.ok) console.log(result.value); // [{ answer: 42 }]\n *\n * await client.close();\n * ```\n */\nexport class DuckDBClient {\n\tprivate readonly _config: DuckDBClientConfig;\n\t/* eslint-disable @typescript-eslint/no-explicit-any */\n\tprivate _db: {\n\t\tregisterFileBuffer(name: string, buffer: Uint8Array): void;\n\t\tregisterFileURL(name: string, url: string, proto: number, directIO: boolean): void;\n\t} | null = null;\n\tprivate _conn: {\n\t\tquery<T>(text: string): { toArray(): T[] };\n\t\tclose(): void;\n\t} | null = null;\n\tprivate _closed = false;\n\n\tconstructor(config?: DuckDBClientConfig) {\n\t\tthis._config = config ?? {};\n\t}\n\n\t/**\n\t * Initialise the DuckDB-Wasm instance and open a connection.\n\t *\n\t * Uses the blocking Node.js bindings when running in Node/Bun,\n\t * which avoids the need for Worker threads.\n\t *\n\t * @returns A Result indicating success or failure with a LakeSyncError\n\t */\n\tasync init(): Promise<Result<void, LakeSyncError>> {\n\t\ttry {\n\t\t\t// Dynamic import of the blocking Node bindings\n\t\t\tconst duckdb = await import(\"@duckdb/duckdb-wasm/blocking\");\n\t\t\tconst path = await import(\"node:path\");\n\t\t\tconst { createRequire } = await import(\"node:module\");\n\t\t\t// Resolve WASM bundle paths relative to the duckdb-wasm package.\n\t\t\t// We resolve via the exported blocking entry point and walk up to the\n\t\t\t// package root, since `./package.json` is not in the exports map.\n\t\t\tconst require = createRequire(import.meta.url);\n\t\t\tconst blockingEntry = require.resolve(\"@duckdb/duckdb-wasm/dist/duckdb-node-blocking.cjs\");\n\t\t\tconst duckdbPkgPath = path.dirname(path.dirname(blockingEntry));\n\n\t\t\tconst bundles: {\n\t\t\t\tmvp: { mainModule: string; mainWorker: string };\n\t\t\t\teh?: { mainModule: string; mainWorker: string };\n\t\t\t} = {\n\t\t\t\tmvp: {\n\t\t\t\t\tmainModule: path.join(duckdbPkgPath, \"dist\", \"duckdb-mvp.wasm\"),\n\t\t\t\t\tmainWorker: path.join(duckdbPkgPath, \"dist\", \"duckdb-node-mvp.worker.cjs\"),\n\t\t\t\t},\n\t\t\t\teh: {\n\t\t\t\t\tmainModule: path.join(duckdbPkgPath, \"dist\", \"duckdb-eh.wasm\"),\n\t\t\t\t\tmainWorker: path.join(duckdbPkgPath, \"dist\", \"duckdb-node-eh.worker.cjs\"),\n\t\t\t\t},\n\t\t\t};\n\n\t\t\tconst logger = this._config.logger ? new duckdb.ConsoleLogger() : new duckdb.VoidLogger();\n\n\t\t\tconst db = await duckdb.createDuckDB(bundles, logger, duckdb.NODE_RUNTIME);\n\t\t\tawait db.instantiate(() => {});\n\n\t\t\tif (this._config.threads !== undefined) {\n\t\t\t\tdb.open({ maximumThreads: this._config.threads });\n\t\t\t}\n\n\t\t\tconst conn = db.connect();\n\n\t\t\t// Store references using structural typing (avoids importing concrete types)\n\t\t\tthis._db = db as unknown as typeof this._db;\n\t\t\tthis._conn = conn as unknown as typeof this._conn;\n\t\t\tthis._closed = false;\n\n\t\t\treturn Ok(undefined);\n\t\t} catch (err) {\n\t\t\tconst cause = err instanceof Error ? err : new Error(String(err));\n\t\t\treturn Err(\n\t\t\t\tnew LakeSyncError(\n\t\t\t\t\t`Failed to initialise DuckDB-Wasm: ${cause.message}`,\n\t\t\t\t\t\"ANALYST_ERROR\",\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Execute a SQL query and return the results as an array of objects.\n\t *\n\t * @param sql - The SQL statement to execute\n\t * @param _params - Reserved for future use (parameterised queries)\n\t * @returns A Result containing the query results or a LakeSyncError\n\t */\n\tasync query<T>(sql: string, _params?: unknown[]): Promise<Result<T[], LakeSyncError>> {\n\t\ttry {\n\t\t\tif (this._closed || !this._conn) {\n\t\t\t\treturn Err(\n\t\t\t\t\tnew LakeSyncError(\n\t\t\t\t\t\t\"Cannot query: DuckDB connection is closed or not initialised\",\n\t\t\t\t\t\t\"ANALYST_ERROR\",\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst arrowTable = this._conn.query<T>(sql);\n\t\t\tconst rows = arrowTable.toArray();\n\n\t\t\t// Convert Arrow StructRow proxies to plain JS objects\n\t\t\tconst plainRows = rows.map((row) => ({ ...row })) as T[];\n\t\t\treturn Ok(plainRows);\n\t\t} catch (err) {\n\t\t\tconst cause = err instanceof Error ? err : new Error(String(err));\n\t\t\treturn Err(\n\t\t\t\tnew LakeSyncError(`DuckDB query failed: ${cause.message}`, \"ANALYST_ERROR\", cause),\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Register an in-memory Parquet file as a named table that can be\n\t * queried using `SELECT * FROM '<name>'`.\n\t *\n\t * @param name - The virtual file name (e.g. \"deltas.parquet\")\n\t * @param data - The Parquet file contents as a Uint8Array\n\t * @returns A Result indicating success or failure\n\t */\n\tasync registerParquetBuffer(\n\t\tname: string,\n\t\tdata: Uint8Array,\n\t): Promise<Result<void, LakeSyncError>> {\n\t\ttry {\n\t\t\tif (this._closed || !this._db) {\n\t\t\t\treturn Err(\n\t\t\t\t\tnew LakeSyncError(\n\t\t\t\t\t\t\"Cannot register Parquet buffer: DuckDB is closed or not initialised\",\n\t\t\t\t\t\t\"ANALYST_ERROR\",\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tthis._db.registerFileBuffer(name, data);\n\t\t\treturn Ok(undefined);\n\t\t} catch (err) {\n\t\t\tconst cause = err instanceof Error ? err : new Error(String(err));\n\t\t\treturn Err(\n\t\t\t\tnew LakeSyncError(\n\t\t\t\t\t`Failed to register Parquet buffer \"${name}\": ${cause.message}`,\n\t\t\t\t\t\"ANALYST_ERROR\",\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Register a remote Parquet file by URL so it can be queried using\n\t * `SELECT * FROM '<name>'`.\n\t *\n\t * @param name - The virtual file name (e.g. \"remote.parquet\")\n\t * @param url - The URL pointing to the Parquet file\n\t * @returns A Result indicating success or failure\n\t */\n\tasync registerParquetUrl(name: string, url: string): Promise<Result<void, LakeSyncError>> {\n\t\ttry {\n\t\t\tif (this._closed || !this._db) {\n\t\t\t\treturn Err(\n\t\t\t\t\tnew LakeSyncError(\n\t\t\t\t\t\t\"Cannot register Parquet URL: DuckDB is closed or not initialised\",\n\t\t\t\t\t\t\"ANALYST_ERROR\",\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\t// DuckDBDataProtocol.HTTP = 1\n\t\t\tconst HTTP_PROTOCOL = 1;\n\t\t\tthis._db.registerFileURL(name, url, HTTP_PROTOCOL, false);\n\t\t\treturn Ok(undefined);\n\t\t} catch (err) {\n\t\t\tconst cause = err instanceof Error ? err : new Error(String(err));\n\t\t\treturn Err(\n\t\t\t\tnew LakeSyncError(\n\t\t\t\t\t`Failed to register Parquet URL \"${name}\": ${cause.message}`,\n\t\t\t\t\t\"ANALYST_ERROR\",\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Tear down the DuckDB connection and database instance.\n\t *\n\t * After calling close(), any subsequent query or registration calls\n\t * will return an error Result.\n\t */\n\tasync close(): Promise<void> {\n\t\tif (this._conn) {\n\t\t\ttry {\n\t\t\t\tthis._conn.close();\n\t\t\t} catch {\n\t\t\t\t// Ignore errors during cleanup\n\t\t\t}\n\t\t\tthis._conn = null;\n\t\t}\n\t\tthis._db = null;\n\t\tthis._closed = true;\n\t}\n}\n","import type { HLCTimestamp } from \"@lakesync/core\";\nimport { Err, LakeSyncError, Ok, type Result } from \"@lakesync/core\";\nimport type { DuckDBClient } from \"./duckdb\";\n\n/** System columns present in every delta Parquet file. */\nconst SYSTEM_COLUMNS = new Set([\"op\", \"table\", \"rowId\", \"clientId\", \"hlc\", \"deltaId\"]);\n\n/**\n * Configuration for the TimeTraveller.\n */\nexport interface TimeTravelConfig {\n\t/** The DuckDB client used for executing time-travel queries. */\n\tduckdb: DuckDBClient;\n}\n\n/**\n * Provides time-travel query capabilities over delta Parquet files.\n *\n * Allows querying the materialised state of data as it existed at a specific\n * HLC timestamp, or inspecting raw deltas within a time range. Uses DuckDB\n * SQL with window functions to perform column-level LWW materialisation\n * entirely in-engine.\n *\n * Delta Parquet files contain flattened rows with system columns (`op`, `table`,\n * `rowId`, `clientId`, `hlc`, `deltaId`) and user-defined columns (e.g. `title`,\n * `completed`). The materialisation reconstructs per-row state by selecting the\n * latest value for each column based on HLC ordering, then excluding deleted rows.\n *\n * @example\n * ```ts\n * const traveller = new TimeTraveller({ duckdb: client });\n * await traveller.registerDeltas([{ name: \"batch-1.parquet\", data: bytes }]);\n *\n * const result = await traveller.queryAsOf(hlcTimestamp, \"SELECT * FROM _state WHERE completed = true\");\n * if (result.ok) console.log(result.value);\n * ```\n */\nexport class TimeTraveller {\n\tprivate readonly _config: TimeTravelConfig;\n\tprivate readonly _sources: string[] = [];\n\n\tconstructor(config: TimeTravelConfig) {\n\t\tthis._config = config;\n\t}\n\n\t/**\n\t * Register one or more Parquet buffers containing delta data.\n\t *\n\t * Each buffer is registered with DuckDB and can subsequently be\n\t * queried via the time-travel methods.\n\t *\n\t * @param parquetBuffers - Array of named Parquet file buffers to register\n\t * @returns A Result indicating success or a LakeSyncError on failure\n\t */\n\tasync registerDeltas(\n\t\tparquetBuffers: Array<{ name: string; data: Uint8Array }>,\n\t): Promise<Result<void, LakeSyncError>> {\n\t\ttry {\n\t\t\tfor (const buf of parquetBuffers) {\n\t\t\t\tconst regResult = await this._config.duckdb.registerParquetBuffer(buf.name, buf.data);\n\t\t\t\tif (!regResult.ok) {\n\t\t\t\t\treturn regResult;\n\t\t\t\t}\n\t\t\t\tthis._sources.push(buf.name);\n\t\t\t}\n\t\t\treturn Ok(undefined);\n\t\t} catch (err) {\n\t\t\tconst cause = err instanceof Error ? err : new Error(String(err));\n\t\t\treturn Err(\n\t\t\t\tnew LakeSyncError(\n\t\t\t\t\t`Failed to register delta data: ${cause.message}`,\n\t\t\t\t\t\"ANALYST_ERROR\",\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Query the materialised state as of the given HLC timestamp.\n\t *\n\t * Filters all deltas where `hlc <= asOfHlc`, then materialises the latest\n\t * state per (table, rowId) using column-level LWW (highest HLC wins per\n\t * column). The user's SQL is applied on top of the materialised view,\n\t * which is exposed as the CTE `_state`.\n\t *\n\t * Deleted rows (where the latest operation is DELETE) are excluded from\n\t * the materialised view.\n\t *\n\t * @param asOfHlc - The HLC timestamp representing the point in time to query\n\t * @param sql - SQL to apply on the materialised view (use `_state` as the table name)\n\t * @returns A Result containing the query results or a LakeSyncError\n\t */\n\tasync queryAsOf(\n\t\tasOfHlc: HLCTimestamp,\n\t\tsql: string,\n\t): Promise<Result<Record<string, unknown>[], LakeSyncError>> {\n\t\ttry {\n\t\t\tif (this._sources.length === 0) {\n\t\t\t\treturn Ok([]);\n\t\t\t}\n\n\t\t\tconst userColumns = await this._discoverUserColumns();\n\t\t\tif (!userColumns.ok) {\n\t\t\t\treturn Err(userColumns.error);\n\t\t\t}\n\n\t\t\tconst materialiseSql = this._buildMaterialiseSql(userColumns.value, BigInt(asOfHlc));\n\t\t\tconst finalSql = `WITH _state AS (${materialiseSql}) ${sql}`;\n\n\t\t\tconst result = await this._config.duckdb.query<Record<string, unknown>>(finalSql);\n\t\t\tif (!result.ok) {\n\t\t\t\treturn Err(result.error);\n\t\t\t}\n\t\t\treturn Ok(result.value);\n\t\t} catch (err) {\n\t\t\tconst cause = err instanceof Error ? err : new Error(String(err));\n\t\t\treturn Err(\n\t\t\t\tnew LakeSyncError(`Time-travel queryAsOf failed: ${cause.message}`, \"ANALYST_ERROR\", cause),\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Query raw deltas within a time range.\n\t *\n\t * Filters deltas where `fromHlc < hlc <= toHlc` and returns them as raw\n\t * (unmaterialised) rows. Useful for audit trails and changelog views.\n\t *\n\t * The user's SQL is applied on top of the filtered deltas, which are\n\t * exposed as the CTE `_deltas`.\n\t *\n\t * @param fromHlc - The exclusive lower bound HLC timestamp\n\t * @param toHlc - The inclusive upper bound HLC timestamp\n\t * @param sql - SQL to apply on the filtered deltas (use `_deltas` as the table name)\n\t * @returns A Result containing the query results or a LakeSyncError\n\t */\n\tasync queryBetween(\n\t\tfromHlc: HLCTimestamp,\n\t\ttoHlc: HLCTimestamp,\n\t\tsql: string,\n\t): Promise<Result<Record<string, unknown>[], LakeSyncError>> {\n\t\ttry {\n\t\t\tif (this._sources.length === 0) {\n\t\t\t\treturn Ok([]);\n\t\t\t}\n\n\t\t\tconst unionSql = this._buildUnionSql();\n\t\t\tconst fromBigint = BigInt(fromHlc);\n\t\t\tconst toBigint = BigInt(toHlc);\n\n\t\t\tconst filteredSql = `\n\t\t\t\tSELECT * FROM (${unionSql}) AS _all\n\t\t\t\tWHERE CAST(hlc AS BIGINT) > ${fromBigint}\n\t\t\t\t  AND CAST(hlc AS BIGINT) <= ${toBigint}\n\t\t\t`;\n\n\t\t\tconst finalSql = `WITH _deltas AS (${filteredSql}) ${sql}`;\n\n\t\t\tconst result = await this._config.duckdb.query<Record<string, unknown>>(finalSql);\n\t\t\tif (!result.ok) {\n\t\t\t\treturn Err(result.error);\n\t\t\t}\n\t\t\treturn Ok(result.value);\n\t\t} catch (err) {\n\t\t\tconst cause = err instanceof Error ? err : new Error(String(err));\n\t\t\treturn Err(\n\t\t\t\tnew LakeSyncError(\n\t\t\t\t\t`Time-travel queryBetween failed: ${cause.message}`,\n\t\t\t\t\t\"ANALYST_ERROR\",\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Materialise the full state at a point in time, returning all rows.\n\t *\n\t * Equivalent to `queryAsOf(asOfHlc, \"SELECT * FROM _state\")` but provided\n\t * as a convenience method.\n\t *\n\t * @param asOfHlc - The HLC timestamp representing the point in time to materialise\n\t * @returns A Result containing all materialised rows or a LakeSyncError\n\t */\n\tasync materialiseAsOf(\n\t\tasOfHlc: HLCTimestamp,\n\t): Promise<Result<Record<string, unknown>[], LakeSyncError>> {\n\t\treturn this.queryAsOf(asOfHlc, \"SELECT * FROM _state\");\n\t}\n\n\t/**\n\t * Build a UNION ALL SQL expression covering all registered Parquet sources.\n\t */\n\tprivate _buildUnionSql(): string {\n\t\treturn this._sources.map((s) => `SELECT * FROM '${s}'`).join(\" UNION ALL BY NAME \");\n\t}\n\n\t/**\n\t * Discover user-defined column names from the registered Parquet data.\n\t *\n\t * Reads the column names from the first registered source and filters\n\t * out system columns to identify user-defined columns.\n\t */\n\tprivate async _discoverUserColumns(): Promise<Result<string[], LakeSyncError>> {\n\t\tif (this._sources.length === 0) {\n\t\t\treturn Ok([]);\n\t\t}\n\n\t\tconst result = await this._config.duckdb.query<{ column_name: string }>(\n\t\t\t`SELECT column_name FROM (DESCRIBE SELECT * FROM '${this._sources[0]}')`,\n\t\t);\n\t\tif (!result.ok) {\n\t\t\treturn Err(result.error);\n\t\t}\n\n\t\tconst userCols = result.value\n\t\t\t.map((r) => r.column_name)\n\t\t\t.filter((name) => !SYSTEM_COLUMNS.has(name));\n\n\t\treturn Ok(userCols);\n\t}\n\n\t/**\n\t * Build the materialisation SQL that reconstructs per-row state using\n\t * column-level LWW semantics.\n\t *\n\t * Strategy:\n\t * 1. Filter deltas by HLC <= asOfHlc\n\t * 2. For each (table, rowId), determine the latest operation (by max HLC)\n\t * 3. For each user column in each row, pick the value from the delta with\n\t *    the highest HLC (where that column is not null)\n\t * 4. Exclude rows where the latest operation is DELETE\n\t *\n\t * @param userColumns - Names of user-defined columns\n\t * @param asOfHlc - The HLC timestamp cutoff as a bigint\n\t * @returns SQL string producing the materialised view\n\t */\n\tprivate _buildMaterialiseSql(userColumns: string[], asOfHlc: bigint): string {\n\t\tconst unionSql = this._buildUnionSql();\n\n\t\t// If there are no user columns, we still need to return rowId and table\n\t\tif (userColumns.length === 0) {\n\t\t\treturn `\n\t\t\t\tSELECT \"table\", \"rowId\"\n\t\t\t\tFROM (\n\t\t\t\t\tSELECT *,\n\t\t\t\t\t\tROW_NUMBER() OVER (\n\t\t\t\t\t\t\tPARTITION BY \"table\", \"rowId\"\n\t\t\t\t\t\t\tORDER BY CAST(hlc AS BIGINT) DESC\n\t\t\t\t\t\t) AS _rn\n\t\t\t\t\tFROM (${unionSql}) AS _all\n\t\t\t\t\tWHERE CAST(hlc AS BIGINT) <= ${asOfHlc}\n\t\t\t\t) AS _ranked\n\t\t\t\tWHERE _rn = 1 AND op != 'DELETE'\n\t\t\t`;\n\t\t}\n\n\t\t// Build per-column LAST_VALUE expressions.\n\t\t// For each user column, we want the value from the row with the highest HLC\n\t\t// where that column is NOT NULL. We use LAST_VALUE with IGNORE NULLS over\n\t\t// an HLC-ordered window partition.\n\t\tconst columnSelects = userColumns.map((col) => {\n\t\t\treturn `LAST_VALUE(\"${col}\" IGNORE NULLS) OVER (\n\t\t\t\tPARTITION BY \"table\", \"rowId\"\n\t\t\t\tORDER BY CAST(hlc AS BIGINT) ASC\n\t\t\t\tROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING\n\t\t\t) AS \"${col}\"`;\n\t\t});\n\n\t\t// We need the latest op per (table, rowId) to filter out DELETEs.\n\t\t// Use LAST_VALUE on op ordered by HLC to get the most recent operation.\n\t\tconst latestOpExpr = `LAST_VALUE(op) OVER (\n\t\t\tPARTITION BY \"table\", \"rowId\"\n\t\t\tORDER BY CAST(hlc AS BIGINT) ASC\n\t\t\tROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING\n\t\t) AS _latest_op`;\n\n\t\t// Use ROW_NUMBER to deduplicate — we only need one output row per (table, rowId).\n\t\tconst rowNumExpr = `ROW_NUMBER() OVER (\n\t\t\tPARTITION BY \"table\", \"rowId\"\n\t\t\tORDER BY CAST(hlc AS BIGINT) DESC\n\t\t) AS _rn`;\n\n\t\treturn `\n\t\t\tSELECT \"table\", \"rowId\", ${userColumns.map((c) => `\"${c}\"`).join(\", \")}\n\t\t\tFROM (\n\t\t\t\tSELECT\n\t\t\t\t\t\"table\",\n\t\t\t\t\t\"rowId\",\n\t\t\t\t\t${columnSelects.join(\",\\n\\t\\t\\t\\t\\t\")},\n\t\t\t\t\t${latestOpExpr},\n\t\t\t\t\t${rowNumExpr}\n\t\t\t\tFROM (${unionSql}) AS _all\n\t\t\t\tWHERE CAST(hlc AS BIGINT) <= ${asOfHlc}\n\t\t\t) AS _materialised\n\t\t\tWHERE _rn = 1 AND _latest_op != 'DELETE'\n\t\t`;\n\t}\n}\n","import { Err, LakeSyncError, Ok, type Result } from \"@lakesync/core\";\nimport type { DuckDBClient } from \"./duckdb\";\n\n/**\n * Configuration for the UnionReader.\n */\nexport interface UnionReadConfig {\n\t/** The DuckDB client used to query cold (Parquet) data. */\n\tduckdb: DuckDBClient;\n\t/** The logical table name being queried. */\n\ttableName: string;\n}\n\n/**\n * Merges \"hot\" in-memory rows with \"cold\" Parquet data via DuckDB.\n *\n * Cold data is registered as Parquet file buffers in DuckDB. Hot data is\n * serialised to JSON and loaded via `read_json_auto`. The two sources are\n * combined with `UNION ALL` and the caller's SQL is applied on top.\n *\n * The union is exposed as a CTE named `_union`, so the caller's SQL should\n * reference `_union` as the table name.\n *\n * @example\n * ```ts\n * const reader = new UnionReader({ duckdb: client, tableName: \"todos\" });\n * await reader.registerColdData([{ name: \"batch-1.parquet\", data: parquetBytes }]);\n *\n * const result = await reader.query(\n *   \"SELECT * FROM _union WHERE completed = true\",\n *   [{ id: \"row-3\", title: \"New task\", completed: false }],\n * );\n * ```\n */\nexport class UnionReader {\n\tprivate readonly _config: UnionReadConfig;\n\tprivate readonly _coldSources: string[] = [];\n\tprivate _hotCounter = 0;\n\n\tconstructor(config: UnionReadConfig) {\n\t\tthis._config = config;\n\t}\n\n\t/**\n\t * Register one or more Parquet buffers as cold data sources.\n\t *\n\t * Each buffer is registered with DuckDB and can subsequently be\n\t * queried alongside hot data via {@link query}.\n\t *\n\t * @param parquetBuffers - Array of named Parquet file buffers to register\n\t * @returns A Result indicating success or a LakeSyncError on failure\n\t */\n\tasync registerColdData(\n\t\tparquetBuffers: Array<{ name: string; data: Uint8Array }>,\n\t): Promise<Result<void, LakeSyncError>> {\n\t\ttry {\n\t\t\tfor (const buf of parquetBuffers) {\n\t\t\t\tconst regResult = await this._config.duckdb.registerParquetBuffer(buf.name, buf.data);\n\t\t\t\tif (!regResult.ok) {\n\t\t\t\t\treturn regResult;\n\t\t\t\t}\n\t\t\t\tthis._coldSources.push(buf.name);\n\t\t\t}\n\t\t\treturn Ok(undefined);\n\t\t} catch (err) {\n\t\t\tconst cause = err instanceof Error ? err : new Error(String(err));\n\t\t\treturn Err(\n\t\t\t\tnew LakeSyncError(`Failed to register cold data: ${cause.message}`, \"ANALYST_ERROR\", cause),\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Execute a SQL query that unions hot in-memory rows with cold Parquet data.\n\t *\n\t * The caller's SQL is wrapped around a UNION ALL of cold and hot sources.\n\t * The unioned data is available as `_union` in the SQL statement.\n\t *\n\t * If `hotRows` is empty or not provided, only cold data is queried.\n\t * If no cold sources are registered and `hotRows` is provided, only hot data is queried.\n\t *\n\t * @param sql - SQL to apply on top of the unioned data (use `_union` as the table name)\n\t * @param hotRows - Optional array of in-memory row objects to include in the union\n\t * @returns A Result containing the query results or a LakeSyncError\n\t */\n\tasync query(\n\t\tsql: string,\n\t\thotRows?: Record<string, unknown>[],\n\t): Promise<Result<Record<string, unknown>[], LakeSyncError>> {\n\t\ttry {\n\t\t\tconst hasHot = hotRows !== undefined && hotRows.length > 0;\n\t\t\tconst hasCold = this._coldSources.length > 0;\n\n\t\t\tif (!hasHot && !hasCold) {\n\t\t\t\treturn Ok([]);\n\t\t\t}\n\n\t\t\t// Build the inner union query parts\n\t\t\tconst unionParts: string[] = [];\n\n\t\t\t// Add cold sources (each Parquet file is a separate SELECT)\n\t\t\tif (hasCold) {\n\t\t\t\tfor (const source of this._coldSources) {\n\t\t\t\t\tunionParts.push(`SELECT * FROM '${source}'`);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Add hot source via JSON buffer registered with DuckDB\n\t\t\tif (hasHot) {\n\t\t\t\tconst hotBufferName = `_hot_${this._config.tableName}_${this._hotCounter++}.json`;\n\t\t\t\tconst jsonBytes = new TextEncoder().encode(JSON.stringify(hotRows));\n\n\t\t\t\tconst regResult = await this._config.duckdb.registerParquetBuffer(hotBufferName, jsonBytes);\n\t\t\t\tif (!regResult.ok) {\n\t\t\t\t\treturn Err(regResult.error);\n\t\t\t\t}\n\n\t\t\t\tunionParts.push(`SELECT * FROM read_json_auto('${hotBufferName}')`);\n\t\t\t}\n\n\t\t\t// Combine all parts with UNION ALL and expose as CTE named `_union`\n\t\t\t// Use UNION ALL BY NAME so columns are matched by name, not position.\n\t\t\t// This handles differing column orders between Parquet and JSON sources.\n\t\t\tconst unionSql = unionParts.join(\" UNION ALL BY NAME \");\n\t\t\tconst finalSql = `WITH _union AS (${unionSql}) ${sql}`;\n\n\t\t\tconst result = await this._config.duckdb.query<Record<string, unknown>>(finalSql);\n\t\t\tif (!result.ok) {\n\t\t\t\treturn Err(result.error);\n\t\t\t}\n\n\t\t\treturn Ok(result.value);\n\t\t} catch (err) {\n\t\t\tconst cause = err instanceof Error ? err : new Error(String(err));\n\t\t\treturn Err(new LakeSyncError(`Union query failed: ${cause.message}`, \"ANALYST_ERROR\", cause));\n\t\t}\n\t}\n\n\t/**\n\t * Query only cold (Parquet) data without any hot rows.\n\t *\n\t * @param sql - SQL to execute against cold data (use `_union` as the table name)\n\t * @returns A Result containing the query results or a LakeSyncError\n\t */\n\tasync queryColdOnly(sql: string): Promise<Result<Record<string, unknown>[], LakeSyncError>> {\n\t\treturn this.query(sql);\n\t}\n}\n"],"mappings":"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","names":["require"]}

package/dist/auth-CAVutXzx.d.ts

@@ -0,0 +1,30 @@
+import { R as Result } from './result-CojzlFE2.js';
+
+/** Claims extracted from a verified JWT token */
+interface AuthClaims {
+    /** Client identifier (from JWT `sub` claim) */
+    clientId: string;
+    /** Authorised gateway ID (from JWT `gw` claim) */
+    gatewayId: string;
+    /** Role for route-level access control (from JWT `role` claim, defaults to "client") */
+    role: string;
+    /** Non-standard JWT claims for sync rule evaluation */
+    customClaims: Record<string, string | string[]>;
+}
+/** Authentication error returned when JWT verification fails */
+declare class AuthError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify a JWT token signed with HMAC-SHA256 and extract authentication claims.
+ *
+ * Uses the Web Crypto API exclusively (no external dependencies), making it
+ * suitable for Cloudflare Workers and other edge runtimes.
+ *
+ * @param token - The raw JWT string (header.payload.signature)
+ * @param secret - The HMAC-SHA256 secret key
+ * @returns A Result containing AuthClaims on success, or AuthError on failure
+ */
+declare function verifyToken(token: string, secret: string): Promise<Result<AuthClaims, AuthError>>;
+
+export { type AuthClaims as A, AuthError as a, verifyToken as v };

package/dist/base-poller-Qo_SmCZs.d.ts

@@ -0,0 +1,82 @@
+import { b as SyncPush, R as RowDelta } from './types-V_jVu2sA.js';
+import { H as HLC } from './hlc-DiD8QNG3.js';
+import { R as Result, F as FlushError } from './result-CojzlFE2.js';
+
+/** Minimal interface for a push target (avoids depending on @lakesync/gateway). */
+interface PushTarget {
+    handlePush(push: SyncPush): unknown;
+}
+/**
+ * Extended push target that supports flush and buffer inspection.
+ * Implemented by SyncGateway so pollers can trigger flushes to relieve memory pressure.
+ */
+interface IngestTarget extends PushTarget {
+    flush(): Promise<Result<void, FlushError>>;
+    shouldFlush(): boolean;
+    readonly bufferStats: {
+        logSize: number;
+        indexSize: number;
+        byteSize: number;
+    };
+}
+/** Type guard: returns true if the target supports flush/shouldFlush/bufferStats. */
+declare function isIngestTarget(target: PushTarget): target is IngestTarget;
+/** Memory configuration for the streaming accumulator. */
+interface PollerMemoryConfig {
+    /** Number of deltas per push chunk (default 500). */
+    chunkSize?: number;
+    /** Approximate memory budget in bytes — triggers flush at 70% (default: no limit). */
+    memoryBudgetBytes?: number;
+    /** Proportion of memoryBudgetBytes at which to trigger a flush (default 0.7). */
+    flushThreshold?: number;
+}
+/**
+ * Base class for source pollers that poll an external API and push deltas
+ * to a SyncGateway. Handles lifecycle (start/stop/schedule), and push.
+ */
+declare abstract class BaseSourcePoller {
+    protected readonly gateway: PushTarget;
+    protected readonly hlc: HLC;
+    protected readonly clientId: string;
+    private readonly intervalMs;
+    private timer;
+    private running;
+    private readonly chunkSize;
+    private readonly memoryBudgetBytes;
+    private readonly flushThreshold;
+    private pendingDeltas;
+    constructor(config: {
+        name: string;
+        intervalMs: number;
+        gateway: PushTarget;
+        memory?: PollerMemoryConfig;
+    });
+    /** Start the polling loop. */
+    start(): void;
+    /** Stop the polling loop. */
+    stop(): void;
+    /** Whether the poller is currently running. */
+    get isRunning(): boolean;
+    /** Execute a single poll cycle. Subclasses implement their specific polling logic. */
+    abstract poll(): Promise<void>;
+    /** Push collected deltas to the gateway (single-shot, backward compat). */
+    protected pushDeltas(deltas: RowDelta[]): void;
+    /**
+     * Accumulate a single delta. When `chunkSize` is reached, the pending
+     * deltas are automatically pushed (and flushed if needed).
+     */
+    protected accumulateDelta(delta: RowDelta): Promise<void>;
+    /** Flush any remaining accumulated deltas. Call at the end of `poll()`. */
+    protected flushAccumulator(): Promise<void>;
+    /**
+     * Push a chunk of pending deltas. If the gateway is an IngestTarget,
+     * checks memory pressure and flushes before/after push when needed.
+     * On backpressure, flushes once and retries.
+     */
+    private pushPendingChunk;
+    private pushChunkWithFlush;
+    private shouldFlushTarget;
+    private schedulePoll;
+}
+
+export { BaseSourcePoller as B, type IngestTarget as I, type PollerMemoryConfig as P, type PushTarget as a, isIngestTarget as i };