@nshiab/simple-data-analysis-core 2.1.12 → 2.1.14

package/dist/helpers/index.d.mts

@@ -0,0 +1,324 @@
+import { n as SimpleDB, t as SimpleTable } from "../SimpleTable-BdiLf6k7.mjs";
+import { DuckDBValue } from "@duckdb/node-api";
+//#region src/helpers/createDirectory.d.ts
+/**
+ * Creates missing directories in an output path, including parent directories.
+ * Non-hidden path segments containing a dot are treated as filenames and omitted.
+ *
+ * @example
+ * ```ts
+ * import { createDirectory } from "@nshiab/simple-data-analysis-core/helpers";
+ * createDirectory("output/tables/results.csv"); // Creates output/tables.
+ * ```
+ *
+ * @param path - An output file path or a directory path without dotted segments.
+ *
+ * @returns Nothing. Existing directories are left unchanged.
+ */
+declare function createDirectory(path: string): void;
+//#endregion
+//#region src/helpers/mergeOptions.d.ts
+/** @internal DuckDB owns this type; retain its exact binding contract without re-exporting it. */
+type DuckDBValue$2 = DuckDBValue;
+/**
+ * Combines a table or database's logging defaults with query-specific options.
+ * Use this helper with `queryDB()` when implementing an extension.
+ *
+ * @example
+ * ```ts
+ * import { mergeOptions } from "@nshiab/simple-data-analysis-core/helpers";
+ *
+ * const options = mergeOptions(sdb, {
+ *   table: null,
+ *   method: "example()",
+ *   parameters: null,
+ *   returnData: true,
+ * });
+ * console.log(options.rowsToLog, options.returnData);
+ * ```
+ *
+ * @param simple - The logging defaults from a table or database.
+ *
+ * @param simple.rowsToLog - The default number of rows to display.
+ *
+ * @param simple.charsToLog - The default maximum characters to display per cell.
+ *
+ * @param options - Query-specific settings, which take precedence over defaults.
+ *
+ * @param options.table - The table name used for diagnostics, or `null`.
+ *
+ * @param options.method - The calling method used for diagnostics, or `null`.
+ *
+ * @param options.parameters - Arguments included in error diagnostics, or `null`.
+ *
+ * @param options.rowsToLog - Overrides the default number of displayed rows.
+ *
+ * @param options.returnData - Whether to return converted rows. Defaults to false.
+ *
+ * @param options.values - DuckDB-native values bound to SQL placeholders, in order.
+ *
+ * @param options.noClean - Whether to preserve the SQL text without cleaning it.
+ *
+ * @returns The merged query options without modifying either argument.
+ */
+declare function mergeOptions(simple: {
+  rowsToLog: number;
+  charsToLog: number | undefined;
+}, options: {
+  table: string | null;
+  method: string | null;
+  parameters: {
+    [key: string]: unknown;
+  } | null;
+  rowsToLog?: number;
+  returnData?: boolean;
+  values?: DuckDBValue$2[];
+  noClean?: boolean;
+}): {
+  table: string | null;
+  method: string | null;
+  parameters: {
+    [key: string]: unknown;
+  } | null;
+  rowsToLog: number;
+  charsToLog: number | undefined;
+  returnData: boolean;
+  values?: DuckDBValue$2[];
+  noClean?: boolean;
+};
+//#endregion
+//#region src/helpers/parseValue.d.ts
+/**
+ * Converts a JavaScript value to a SQL literal. Strings are quoted with embedded
+ * quotes escaped, dates become quoted ISO strings, and null, undefined, or NaN
+ * become `"NULL"`. Numbers and booleans are returned unchanged.
+ *
+ * @example
+ * ```ts
+ * import { parseValue } from "@nshiab/simple-data-analysis-core/helpers";
+ * console.log(parseValue("O'Brien")); // "'O''Brien'"
+ * console.log(parseValue(null)); // "NULL"
+ * ```
+ *
+ * @param value - A string, number, boolean, Date, null, or undefined.
+ *
+ * @returns A SQL literal, or the original number or boolean.
+ *
+ * @throws If the value has an unsupported type.
+ */
+declare function parseValue(value: unknown): string | boolean | number;
+//#endregion
+//#region src/helpers/queryDB.d.ts
+/** @internal DuckDB owns this type; retain its exact binding contract without re-exporting it. */
+type DuckDBValue$1 = DuckDBValue;
+/**
+ * Executes SQL for a table or database after flushing all queued operations.
+ * Starts the database on first use and applies its SQL logging settings.
+ * Extension authors can construct `options` with `mergeOptions()`.
+ *
+ * @example
+ * ```ts
+ * import { mergeOptions, queryDB, quoteIdentifier } from "@nshiab/simple-data-analysis-core/helpers";
+ *
+ * await table.loadArray([{ answer: 0 }]).run();
+ * const query = `UPDATE ${quoteIdentifier(table.name)} SET answer = ?`;
+ * await queryDB(table, query, mergeOptions(table, {
+ *   table: table.name,
+ *   method: "example()",
+ *   parameters: null,
+ *   values: [42],
+ * }));
+ * await table.log();
+ * ```
+ *
+ * @param simple - The table or database that owns the query.
+ *
+ * @param query - The SQL statement to execute.
+ *
+ * @param options - Query execution and diagnostic settings.
+ *
+ * @param options.table - The table name used for diagnostics, or `null`.
+ *
+ * @param options.method - The calling method used for diagnostics, or `null`.
+ *
+ * @param options.parameters - Arguments included in error diagnostics, or `null`.
+ *
+ * @param options.rowsToLog - The caller's row-display limit, retained for compatibility.
+ *
+ * @param options.charsToLog - The caller's per-cell display limit, retained for compatibility.
+ *
+ * @param options.returnData - Whether to convert and return the result rows.
+ *
+ * @param options.values - DuckDB-native values bound to SQL placeholders, in order.
+ *
+ * @param options.noClean - Whether to preserve the SQL text without cleaning it.
+ *
+ * @returns Converted rows when `returnData` is true, otherwise `null`.
+ */
+declare function queryDB(simple: SimpleTable | SimpleDB, query: string, options: {
+  table: string | null;
+  method: string | null;
+  parameters: {
+    [key: string]: unknown;
+  } | null;
+  rowsToLog: number;
+  charsToLog: number | undefined;
+  returnData: boolean;
+  values?: DuckDBValue$1[];
+  noClean?: boolean;
+}): Promise<{
+  [key: string]: unknown;
+}[] | null>;
+//#endregion
+//#region src/helpers/queueAsyncBarrier.d.ts
+/**
+ * Queues asynchronous extension work as one ordered table-builder step.
+ * Builder operations queued by `execute` are scoped to the barrier and drain
+ * before its observer queries and before later chained operations.
+ *
+ * `execute` must await all asynchronous work that can queue table operations.
+ * Detached work is outside the barrier's program-order scope.
+ *
+ * If `execute` rejects, captured builder operations that have not already
+ * drained are discarded. Operations drained by an observer inside `execute`
+ * remain applied; an asynchronous barrier does not provide database rollback.
+ *
+ * This differs from a failure while executing queued builders: during replay,
+ * the failing table's remaining chain is aborted, but unexecuted work for other
+ * tables is requeued for their next observation.
+ *
+ * @example
+ * ```ts
+ * import type { SimpleTable } from "@nshiab/simple-data-analysis-core";
+ * import { queueAsyncBarrier } from "@nshiab/simple-data-analysis-core/helpers";
+ *
+ * function loadRemote(table: SimpleTable, url: string): SimpleTable {
+ *   queueAsyncBarrier(table, {
+ *     method: "loadRemote()",
+ *     parameters: { url },
+ *     execute: async () => {
+ *       const rows = await fetch(url).then((response) => response.json()) as
+ *         { [key: string]: unknown }[];
+ *       table.loadArray(rows);
+ *     },
+ *   });
+ *   return table;
+ * }
+ * ```
+ *
+ * @param simpleTable - The table whose chain owns the asynchronous work.
+ *
+ * @param operation - The asynchronous extension operation to queue.
+ *
+ * @param operation.method - The public method name used for diagnostics.
+ *
+ * @param operation.parameters - A snapshot of the public method parameters used for diagnostics.
+ *
+ * @param operation.execute - The asynchronous work to run at the barrier's position in the chain.
+ *
+ * @returns Nothing. The public builder should return its target table.
+ */
+declare function queueAsyncBarrier(simpleTable: SimpleTable, operation: {
+  method: string;
+  parameters: {
+    [key: string]: unknown;
+  } | null;
+  execute: () => Promise<void>;
+}): void;
+//#endregion
+//#region src/helpers/quoteIdentifier.d.ts
+/**
+ * Quotes one SQL identifier and escapes embedded double quotes.
+ * Use this for library-generated table, column, schema, database, and alias
+ * names. User-authored SQL expressions must remain unmodified.
+ *
+ * @example
+ * ```ts
+ * quoteIdentifier('people "archive"');
+ * // '"people ""archive"""'
+ * ```
+ *
+ * @param identifier - The identifier to quote.
+ *
+ * @returns The identifier wrapped in double quotes with embedded quotes doubled.
+ */
+declare function quoteIdentifier(identifier: string): string;
+//#endregion
+//#region src/helpers/stringToArray.d.ts
+/**
+ * Normalizes a string or array of strings to a new array.
+ * Existing arrays are copied so callers can change the result independently.
+ *
+ * @example
+ * ```ts
+ * import { stringToArray } from "@nshiab/simple-data-analysis-core/helpers";
+ * console.log(stringToArray("name")); // ["name"]
+ * console.log(stringToArray(["name", "age"])); // ["name", "age"]
+ * ```
+ *
+ * @param argument - One string or an array of strings.
+ *
+ * @returns A new array containing the supplied strings.
+ */
+declare function stringToArray(argument: string | string[]): string[];
+//#endregion
+//#region src/helpers/updateColumnsWithJS.d.ts
+/**
+ * Generates columns from selected input columns, keeping other SQL values in
+ * DuckDB. Call from an asynchronous extension barrier. The callback must return
+ * one row per input row in the same order; only the declared output columns are
+ * stored. Existing output columns are replaced, with types inferred from the
+ * generated values. Generation runs sequentially in bounded batches (1,000 rows
+ * by default); callbacks must not depend on receiving the whole table. Non-null
+ * output types must agree across batches. All-null batches defer type inference.
+ * Only one batch of inputs and outputs is retained by this helper in JavaScript;
+ * callers must also bound their own buffering. Reads finish before callbacks or
+ * writes use the shared connection. The original table is replaced only after
+ * staging succeeds. Empty tables are unchanged and do not invoke the callback;
+ * outputs that remain null in every batch use VARCHAR.
+ *
+ * Untouched geometry columns remain in DuckDB, preserving their values, types
+ * and CRS without GeoJSON conversion. Geometry columns cannot be selected as
+ * inputs or overwritten as outputs; use updateWithJS() for editable GeoJSON.
+ * This SQL-only preservation path accepts any source CRS.
+ *
+ * @example
+ * ```ts
+ * queueAsyncBarrier(table, {
+ *   method: "label()",
+ *   parameters: null,
+ *   execute: () => updateColumnsWithJS(table, ["name"], ["label"], async (rows) =>
+ *     rows.map((row) => ({ label: String(row.name).toUpperCase() })),
+ *     { batchSize: 500 }),
+ * });
+ * await table.log();
+ * ```
+ *
+ * @param table - Table to enrich.
+ *
+ * @param inputColumns - Columns available to the callback.
+ *
+ * @param outputColumns - Generated columns to add or replace.
+ *
+ * @param generate - Produces one result per input row, in input order.
+ *
+ * @param options - Controls the maximum rows read, generated, and staged at once.
+ *
+ * @returns Resolves after merging the generated columns into the table.
+ */
+declare function updateColumnsWithJS(table: SimpleTable, inputColumns: string[], outputColumns: string[], generate: (rows: {
+  [key: string]: unknown;
+}[]) => Promise<{
+  [key: string]: unknown;
+}[]>, options?: {
+  /** Maximum rows per callback and transfer batch. Defaults to 1,000.
+   * @example
+   * ```ts
+   * { batchSize: 500 }
+   * ```
+   */
+  batchSize?: number;
+}): Promise<void>;
+//#endregion
+export { createDirectory, mergeOptions, parseValue, queryDB, queueAsyncBarrier, quoteIdentifier, stringToArray, updateColumnsWithJS };
+//# sourceMappingURL=index.d.mts.map

package/dist/helpers/index.mjs

@@ -0,0 +1,166 @@
+import { a as parseDuckDBType, c as stringToArray, d as retainRegisteredTables, f as queryDB, h as quoteIdentifier, i as prepareArray, l as appendColumnBatches, o as parseValue, p as mergeOptions, r as readMutationRows, s as createDirectory, u as queueOp } from "../SimpleDB-d3LMXBzY.mjs";
+//#region src/helpers/queueAsyncBarrier.ts
+/**
+* Queues asynchronous extension work as one ordered table-builder step.
+* Builder operations queued by `execute` are scoped to the barrier and drain
+* before its observer queries and before later chained operations.
+*
+* `execute` must await all asynchronous work that can queue table operations.
+* Detached work is outside the barrier's program-order scope.
+*
+* If `execute` rejects, captured builder operations that have not already
+* drained are discarded. Operations drained by an observer inside `execute`
+* remain applied; an asynchronous barrier does not provide database rollback.
+*
+* This differs from a failure while executing queued builders: during replay,
+* the failing table's remaining chain is aborted, but unexecuted work for other
+* tables is requeued for their next observation.
+*
+* @example
+* ```ts
+* import type { SimpleTable } from "@nshiab/simple-data-analysis-core";
+* import { queueAsyncBarrier } from "@nshiab/simple-data-analysis-core/helpers";
+*
+* function loadRemote(table: SimpleTable, url: string): SimpleTable {
+*   queueAsyncBarrier(table, {
+*     method: "loadRemote()",
+*     parameters: { url },
+*     execute: async () => {
+*       const rows = await fetch(url).then((response) => response.json()) as
+*         { [key: string]: unknown }[];
+*       table.loadArray(rows);
+*     },
+*   });
+*   return table;
+* }
+* ```
+*
+* @param simpleTable - The table whose chain owns the asynchronous work.
+*
+* @param operation - The asynchronous extension operation to queue.
+*
+* @param operation.method - The public method name used for diagnostics.
+*
+* @param operation.parameters - A snapshot of the public method parameters used for diagnostics.
+*
+* @param operation.execute - The asynchronous work to run at the barrier's position in the chain.
+*
+* @returns Nothing. The public builder should return its target table.
+*/
+function queueAsyncBarrier(simpleTable, operation) {
+	queueOp(simpleTable, {
+		kind: "asyncBarrier",
+		...operation
+	});
+}
+//#endregion
+//#region src/helpers/updateColumnsWithJS.ts
+/**
+* Generates columns from selected input columns, keeping other SQL values in
+* DuckDB. Call from an asynchronous extension barrier. The callback must return
+* one row per input row in the same order; only the declared output columns are
+* stored. Existing output columns are replaced, with types inferred from the
+* generated values. Generation runs sequentially in bounded batches (1,000 rows
+* by default); callbacks must not depend on receiving the whole table. Non-null
+* output types must agree across batches. All-null batches defer type inference.
+* Only one batch of inputs and outputs is retained by this helper in JavaScript;
+* callers must also bound their own buffering. Reads finish before callbacks or
+* writes use the shared connection. The original table is replaced only after
+* staging succeeds. Empty tables are unchanged and do not invoke the callback;
+* outputs that remain null in every batch use VARCHAR.
+*
+* Untouched geometry columns remain in DuckDB, preserving their values, types
+* and CRS without GeoJSON conversion. Geometry columns cannot be selected as
+* inputs or overwritten as outputs; use updateWithJS() for editable GeoJSON.
+* This SQL-only preservation path accepts any source CRS.
+*
+* @example
+* ```ts
+* queueAsyncBarrier(table, {
+*   method: "label()",
+*   parameters: null,
+*   execute: () => updateColumnsWithJS(table, ["name"], ["label"], async (rows) =>
+*     rows.map((row) => ({ label: String(row.name).toUpperCase() })),
+*     { batchSize: 500 }),
+* });
+* await table.log();
+* ```
+*
+* @param table - Table to enrich.
+*
+* @param inputColumns - Columns available to the callback.
+*
+* @param outputColumns - Generated columns to add or replace.
+*
+* @param generate - Produces one result per input row, in input order.
+*
+* @param options - Controls the maximum rows read, generated, and staged at once.
+*
+* @returns Resolves after merging the generated columns into the table.
+*/
+async function updateColumnsWithJS(table, inputColumns, outputColumns, generate, options = {}) {
+	const batchSize = options.batchSize ?? 1e3;
+	if (!Number.isSafeInteger(batchSize) || batchSize < 1) throw new Error("batchSize must be a positive safe integer.");
+	if (inputColumns.length === 0 || outputColumns.length === 0) throw new Error("Input and output columns must not be empty.");
+	if (new Set(outputColumns.map((name) => name.toLowerCase())).size !== outputColumns.length) throw new Error("Output columns must be unique.");
+	const types = await table.getTypes();
+	for (const [name, type] of Object.entries(types)) if (type.toUpperCase().startsWith("GEOMETRY") && [...inputColumns, ...outputColumns].some((column) => column.toLowerCase() === name.toLowerCase())) throw new Error(`Geometry column ${JSON.stringify(name)} cannot be an input or output of updateColumnsWithJS(); use updateWithJS() for editable GeoJSON.`);
+	const suffix = crypto.randomUUID().replaceAll("-", "");
+	const id = `__sda_id_${suffix}`;
+	const snapshot = `__sda_source_${suffix}`;
+	const staged = table.sdb.newTable(`__sda_generated_${suffix}`);
+	const q = quoteIdentifier;
+	try {
+		await table.sdb.customQuery(`CREATE TEMP TABLE ${q(snapshot)} AS SELECT *, row_number() OVER () AS ${q(id)} FROM ${q(table.name)}`);
+		const knownTypes = /* @__PURE__ */ new Map();
+		let lastId = "0";
+		let hasRows = false;
+		while (true) {
+			const upperId = BigInt(lastId) + BigInt(batchSize);
+			const { rows } = await readMutationRows(table.connection, `SELECT ${q(id)}, ${inputColumns.map(q).join(", ")} FROM ${q(snapshot)} WHERE ${q(id)} > ${lastId} AND ${q(id)} <= ${upperId}
+        ORDER BY ${q(id)} LIMIT ${batchSize}`);
+			if (rows.length === 0) break;
+			const ids = rows.map((row) => String(row[id]));
+			lastId = ids[ids.length - 1];
+			for (const row of rows) delete row[id];
+			const generated = await generate(rows);
+			if (generated.length !== ids.length) throw new Error("Column generation must return one row per input row.");
+			const prepared = prepareArray(generated.map((row, i) => ({
+				...Object.fromEntries(outputColumns.map((name) => [name, row[name]])),
+				[id]: ids[i]
+			})));
+			const batchTypes = new Map(prepared.keys.map((name, i) => [name, prepared.types[i]]));
+			for (const name of outputColumns) {
+				if (!generated.some((row) => row[name] !== null && row[name] !== void 0)) continue;
+				const previous = knownTypes.get(name);
+				const current = batchTypes.get(name);
+				if (previous !== void 0 && previous !== current) throw new Error(`Generated column ${JSON.stringify(name)} changed type from ${previous} to ${current}.`);
+				if (previous === void 0) {
+					knownTypes.set(name, current);
+					if (hasRows) await table.sdb.customQuery(`ALTER TABLE ${q(staged.name)} ALTER COLUMN ${q(name)} TYPE ${current} USING NULL`);
+				}
+			}
+			if (!hasRows) {
+				await table.sdb.customQuery(`CREATE TEMP TABLE ${q(staged.name)} (${prepared.keys.map((name, i) => `${q(name)} ${prepared.types[i]}`).join(", ")})`);
+				hasRows = true;
+			}
+			await appendColumnBatches(table.connection, staged.name, prepared.keys.map((name, i) => parseDuckDBType(knownTypes.get(name) ?? prepared.types[i])), prepared.rowCount, (column, start, end) => prepared.columnsData[column].slice(start, end));
+		}
+		if (!hasRows) return;
+		const outputs = new Map(outputColumns.map((name) => [name.toLowerCase(), name]));
+		const columns = Object.keys(types).map((name) => {
+			const replacement = outputs.get(name.toLowerCase());
+			return replacement === void 0 ? `original.${q(name)}` : `generated.${q(replacement)} AS ${q(name)}`;
+		});
+		const existing = new Set(Object.keys(types).map((name) => name.toLowerCase()));
+		for (const name of outputColumns) if (!existing.has(name.toLowerCase())) columns.push(`generated.${q(name)}`);
+		await table.sdb.customQuery(`CREATE OR REPLACE TABLE ${q(table.name)} AS SELECT ${columns.join(", ")} FROM ${q(snapshot)} original JOIN ${q(staged.name)} generated ON original.${q(id)} = CAST(generated.${q(id)} AS BIGINT) ORDER BY original.${q(id)}`);
+	} finally {
+		await table.sdb.customQuery(`DROP TABLE IF EXISTS ${q(snapshot)}; DROP TABLE IF EXISTS ${q(staged.name)};`);
+		retainRegisteredTables(table.sdb, (item) => item !== staged);
+	}
+}
+//#endregion
+export { createDirectory, mergeOptions, parseValue, queryDB, queueAsyncBarrier, quoteIdentifier, stringToArray, updateColumnsWithJS };
+
+//# sourceMappingURL=index.mjs.map

package/dist/helpers/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/helpers/queueAsyncBarrier.ts","../../src/helpers/updateColumnsWithJS.ts"],"sourcesContent":["import type SimpleTable from \"../class/SimpleTable.ts\";\nimport queueOp from \"./queueOp.ts\";\n\n/**\n * Queues asynchronous extension work as one ordered table-builder step.\n * Builder operations queued by `execute` are scoped to the barrier and drain\n * before its observer queries and before later chained operations.\n *\n * `execute` must await all asynchronous work that can queue table operations.\n * Detached work is outside the barrier's program-order scope.\n *\n * If `execute` rejects, captured builder operations that have not already\n * drained are discarded. Operations drained by an observer inside `execute`\n * remain applied; an asynchronous barrier does not provide database rollback.\n *\n * This differs from a failure while executing queued builders: during replay,\n * the failing table's remaining chain is aborted, but unexecuted work for other\n * tables is requeued for their next observation.\n *\n * @example\n * ```ts\n * import type { SimpleTable } from \"@nshiab/simple-data-analysis-core\";\n * import { queueAsyncBarrier } from \"@nshiab/simple-data-analysis-core/helpers\";\n *\n * function loadRemote(table: SimpleTable, url: string): SimpleTable {\n *   queueAsyncBarrier(table, {\n *     method: \"loadRemote()\",\n *     parameters: { url },\n *     execute: async () => {\n *       const rows = await fetch(url).then((response) => response.json()) as\n *         { [key: string]: unknown }[];\n *       table.loadArray(rows);\n *     },\n *   });\n *   return table;\n * }\n * ```\n *\n * @param simpleTable - The table whose chain owns the asynchronous work.\n *\n * @param operation - The asynchronous extension operation to queue.\n *\n * @param operation.method - The public method name used for diagnostics.\n *\n * @param operation.parameters - A snapshot of the public method parameters used for diagnostics.\n *\n * @param operation.execute - The asynchronous work to run at the barrier's position in the chain.\n *\n * @returns Nothing. The public builder should return its target table.\n */\nexport default function queueAsyncBarrier(\n  simpleTable: SimpleTable,\n  operation: {\n    method: string;\n    parameters: { [key: string]: unknown } | null;\n    execute: () => Promise<void>;\n  },\n): void {\n  queueOp(simpleTable, {\n    kind: \"asyncBarrier\",\n    ...operation,\n  });\n}\n","import type SimpleTable from \"../class/SimpleTable.ts\";\nimport quoteIdentifier from \"./quoteIdentifier.ts\";\nimport readMutationRows from \"./readMutationRows.ts\";\nimport { retainRegisteredTables } from \"./tableRegistry.ts\";\nimport { prepareArray } from \"../methods/loadArray.ts\";\nimport appendColumnBatches from \"./appendColumnBatches.ts\";\nimport parseDuckDBType from \"./parseDuckDBType.ts\";\n\n/**\n * Generates columns from selected input columns, keeping other SQL values in\n * DuckDB. Call from an asynchronous extension barrier. The callback must return\n * one row per input row in the same order; only the declared output columns are\n * stored. Existing output columns are replaced, with types inferred from the\n * generated values. Generation runs sequentially in bounded batches (1,000 rows\n * by default); callbacks must not depend on receiving the whole table. Non-null\n * output types must agree across batches. All-null batches defer type inference.\n * Only one batch of inputs and outputs is retained by this helper in JavaScript;\n * callers must also bound their own buffering. Reads finish before callbacks or\n * writes use the shared connection. The original table is replaced only after\n * staging succeeds. Empty tables are unchanged and do not invoke the callback;\n * outputs that remain null in every batch use VARCHAR.\n *\n * Untouched geometry columns remain in DuckDB, preserving their values, types\n * and CRS without GeoJSON conversion. Geometry columns cannot be selected as\n * inputs or overwritten as outputs; use updateWithJS() for editable GeoJSON.\n * This SQL-only preservation path accepts any source CRS.\n *\n * @example\n * ```ts\n * queueAsyncBarrier(table, {\n *   method: \"label()\",\n *   parameters: null,\n *   execute: () => updateColumnsWithJS(table, [\"name\"], [\"label\"], async (rows) =>\n *     rows.map((row) => ({ label: String(row.name).toUpperCase() })),\n *     { batchSize: 500 }),\n * });\n * await table.log();\n * ```\n *\n * @param table - Table to enrich.\n *\n * @param inputColumns - Columns available to the callback.\n *\n * @param outputColumns - Generated columns to add or replace.\n *\n * @param generate - Produces one result per input row, in input order.\n *\n * @param options - Controls the maximum rows read, generated, and staged at once.\n *\n * @returns Resolves after merging the generated columns into the table.\n */\nexport default async function updateColumnsWithJS(\n  table: SimpleTable,\n  inputColumns: string[],\n  outputColumns: string[],\n  generate: (rows: { [key: string]: unknown }[]) => Promise<{ [key: string]: unknown }[]>,\n  options: {\n    /** Maximum rows per callback and transfer batch. Defaults to 1,000.\n     * @example\n     * ```ts\n     * { batchSize: 500 }\n     * ```\n     */\n    batchSize?: number;\n  } = {},\n): Promise<void> {\n  const batchSize = options.batchSize ?? 1000;\n  if (!Number.isSafeInteger(batchSize) || batchSize < 1) {\n    throw new Error(\"batchSize must be a positive safe integer.\");\n  }\n  if (inputColumns.length === 0 || outputColumns.length === 0) {\n    throw new Error(\"Input and output columns must not be empty.\");\n  }\n  if (new Set(outputColumns.map((name) => name.toLowerCase())).size !== outputColumns.length) {\n    throw new Error(\"Output columns must be unique.\");\n  }\n  const types = await table.getTypes();\n  for (const [name, type] of Object.entries(types)) {\n    if (\n      type.toUpperCase().startsWith(\"GEOMETRY\") &&\n      [...inputColumns, ...outputColumns].some(\n        (column) => column.toLowerCase() === name.toLowerCase(),\n      )\n    ) {\n      throw new Error(\n        `Geometry column ${JSON.stringify(\n          name,\n        )} cannot be an input or output of updateColumnsWithJS(); use updateWithJS() for editable GeoJSON.`,\n      );\n    }\n  }\n  const suffix = crypto.randomUUID().replaceAll(\"-\", \"\");\n  const id = `__sda_id_${suffix}`;\n  const snapshot = `__sda_source_${suffix}`;\n  const staged = table.sdb.newTable(`__sda_generated_${suffix}`);\n  const q = quoteIdentifier;\n  try {\n    // A SQL snapshot gives every row a stable identity, including duplicate rows\n    // and user columns named rowid. No untouched values cross the JS boundary.\n    await table.sdb.customQuery(\n      `CREATE TEMP TABLE ${q(snapshot)} AS SELECT *, row_number() OVER () AS ${q(\n        id,\n      )} FROM ${q(table.name)}`,\n    );\n    const knownTypes = new Map<string, string>();\n    let lastId = \"0\";\n    let hasRows = false;\n    while (true) {\n      const upperId = BigInt(lastId) + BigInt(batchSize);\n      const { rows } = await readMutationRows(\n        table.connection!,\n        `SELECT ${q(id)}, ${inputColumns.map(q).join(\", \")} FROM ${q(\n          snapshot,\n        )} WHERE ${q(id)} > ${lastId} AND ${q(id)} <= ${upperId}\n        ORDER BY ${q(id)} LIMIT ${batchSize}`,\n      );\n      if (rows.length === 0) break;\n      const ids = rows.map((row) => String(row[id]));\n      lastId = ids[ids.length - 1];\n      for (const row of rows) delete row[id];\n      const generated = await generate(rows);\n      if (generated.length !== ids.length) {\n        throw new Error(\"Column generation must return one row per input row.\");\n      }\n      // Generated vectors retain this helper's existing inference contract.\n      const prepared = prepareArray(\n        generated.map((row, i) => ({\n          ...Object.fromEntries(outputColumns.map((name) => [name, row[name]])),\n          [id]: ids[i],\n        })),\n      );\n      const batchTypes = new Map(prepared.keys.map((name, i) => [name, prepared.types[i]]));\n      for (const name of outputColumns) {\n        const nonNull = generated.some((row) => row[name] !== null && row[name] !== undefined);\n        if (!nonNull) continue;\n        const previous = knownTypes.get(name);\n        const current = batchTypes.get(name)!;\n        if (previous !== undefined && previous !== current) {\n          throw new Error(\n            `Generated column ${JSON.stringify(name)} changed type from ${previous} to ${current}.`,\n          );\n        }\n        if (previous === undefined) {\n          knownTypes.set(name, current);\n          if (hasRows) {\n            await table.sdb.customQuery(\n              `ALTER TABLE ${q(staged.name)} ALTER COLUMN ${q(name)} TYPE ${current} USING NULL`,\n            );\n          }\n        }\n      }\n      if (!hasRows) {\n        await table.sdb.customQuery(\n          `CREATE TEMP TABLE ${q(staged.name)} (${prepared.keys\n            .map((name, i) => `${q(name)} ${prepared.types[i]}`)\n            .join(\", \")})`,\n        );\n        hasRows = true;\n      }\n      // All-null batches use the column's established type, avoiding a separate\n      // batch table and SQL copy just to cast nulls into the staged schema.\n      await appendColumnBatches(\n        table.connection!,\n        staged.name,\n        prepared.keys.map((name, i) => parseDuckDBType(knownTypes.get(name) ?? prepared.types[i])),\n        prepared.rowCount,\n        (column, start, end) => prepared.columnsData[column].slice(start, end),\n      );\n    }\n    if (!hasRows) return;\n    const outputs = new Map(outputColumns.map((name) => [name.toLowerCase(), name]));\n    const columns = Object.keys(types).map((name) => {\n      const replacement = outputs.get(name.toLowerCase());\n      return replacement === undefined\n        ? `original.${q(name)}`\n        : `generated.${q(replacement)} AS ${q(name)}`;\n    });\n    const existing = new Set(Object.keys(types).map((name) => name.toLowerCase()));\n    for (const name of outputColumns) {\n      if (!existing.has(name.toLowerCase())) {\n        columns.push(`generated.${q(name)}`);\n      }\n    }\n    await table.sdb.customQuery(\n      `CREATE OR REPLACE TABLE ${q(table.name)} AS SELECT ${columns.join(\n        \", \",\n      )} FROM ${q(snapshot)} original JOIN ${q(\n        staged.name,\n      )} generated ON original.${q(id)} = CAST(generated.${q(\n        id,\n      )} AS BIGINT) ORDER BY original.${q(id)}`,\n    );\n  } finally {\n    await table.sdb.customQuery(\n      `DROP TABLE IF EXISTS ${q(snapshot)}; DROP TABLE IF EXISTS ${q(staged.name)};`,\n    );\n    retainRegisteredTables(table.sdb, (item) => item !== staged);\n  }\n}\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -0,0 +1,67 @@
+import { n as SimpleDB, t as SimpleTable } from "./SimpleTable-BdiLf6k7.mjs";
+//#region src/class/SDAError.d.ts
+/**
+ * An error thrown when a SQL query fails. It carries the SDA method that
+ * triggered the query, the parameters passed to it, the SQL query itself,
+ * and the original error as `cause`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await table.selectColumns("aColumnThatDoesNotExist").run();
+ * } catch (error) {
+ *   if (error instanceof SDAError) {
+ *     console.log(error.method); // "selectColumns()"
+ *     console.log(error.query); // The SQL query that failed
+ *     console.log(error.cause); // The original DuckDB error
+ *   }
+ * }
+ * ```
+ */
+declare class SDAError extends Error {
+  /**
+   * The SDA method that triggered the failing query.
+   */
+  method: string | null;
+  /**
+   * The parameters passed to the method.
+   */
+  parameters: {
+    [key: string]: unknown;
+  } | null;
+  /**
+   * The SQL query that failed.
+   */
+  query: string;
+  /**
+   * Creates an error that preserves the failing query and its original cause.
+   *
+   * @example
+   * ```ts
+   * const error = new SDAError({
+   *   method: "example()",
+   *   parameters: { column: "missing" },
+   *   query: "SELECT missing FROM data",
+   *   cause: new Error("Column not found"),
+   * });
+   * console.log(error.method, error.cause);
+   * ```
+   *
+   * @param options - Details of the failed query.
+   * @param options.method - The SDA method that triggered the query, or `null`.
+   * @param options.parameters - The method's arguments, or `null`.
+   * @param options.query - The SQL statement that failed.
+   * @param options.cause - The original error thrown while executing the query.
+   */
+  constructor(options: {
+    method: string | null;
+    parameters: {
+      [key: string]: unknown;
+    } | null;
+    query: string;
+    cause: unknown;
+  });
+}
+//#endregion
+export { SDAError, SimpleDB, SimpleTable };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1 @@
+export { m as SDAError, t as SimpleDB, n as SimpleTable } from "./SimpleDB-d3LMXBzY.mjs";