@nshiab/simple-data-analysis 5.21.1 → 6.0.1

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/index.js

@@ -0,0 +1,21 @@
+/**
+ * Helper utilities for Simple Data Analysis Core.
+ *
+ * These helpers are exported for reuse by `simple-data-analysis` and other
+ * consumers, removing the need to duplicate their implementations.
+ *
+ * @example
+ * ```ts
+ * import { parseValue, stringToArray } from "@nshiab/simple-data-analysis-core/helpers";
+ *
+ * const literal = parseValue("hello");
+ * const arr = stringToArray("single");
+ * ```
+ */
+export { default as createDirectory } from "./createDirectory.js";
+export { default as mergeOptions } from "./mergeOptions.js";
+export { default as parseValue } from "./parseValue.js";
+export { default as queryDB } from "./queryDB.js";
+export { default as queueAsyncBarrier } from "./queueAsyncBarrier.js";
+export { default as quoteIdentifier } from "./quoteIdentifier.js";
+export { default as stringToArray } from "./stringToArray.js";

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/indexDefinitions.d.ts

@@ -0,0 +1,30 @@
+/** The metadata required to identify and recreate a DuckDB HNSW index. */
+export type VssIndexDefinition = {
+    kind: "vss";
+    name: string;
+    column: string;
+    options: {
+        efConstruction?: number;
+        efSearch?: number;
+        M?: number;
+    };
+};
+/** The metadata required to identify and recreate a DuckDB full-text index. */
+export type FtsIndexDefinition = {
+    kind: "fts";
+    name: string;
+    idColumn: string;
+    textColumn: string;
+    options: {
+        stemmer?: string;
+        stopwords?: string;
+        ignore?: string;
+        stripAccents?: boolean;
+        lower?: boolean;
+    };
+};
+/** A complete index definition stored by a SimpleTable. */
+export type IndexDefinition = VssIndexDefinition | FtsIndexDefinition;
+export type IndexCacheStrategy = "persist" | "rebuild";
+export declare function getIndexCacheStrategy(index: IndexDefinition): IndexCacheStrategy;
+//# sourceMappingURL=indexDefinitions.d.ts.map

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/indexDefinitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexDefinitions.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/indexDefinitions.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,CAAC,CAAC,EAAE,MAAM,CAAC;KACZ,CAAC;CACH,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC;CACH,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAEtE,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,CAAC;AAUvD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,eAAe,GACrB,kBAAkB,CAEpB"}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/indexDefinitions.js

@@ -0,0 +1,7 @@
+const INDEX_CACHE_STRATEGIES = {
+    fts: "persist",
+    vss: "rebuild",
+};
+export function getIndexCacheStrategy(index) {
+    return INDEX_CACHE_STRATEGIES[index.kind];
+}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/indexQueries.d.ts

@@ -0,0 +1,3 @@
+import type { IndexDefinition } from "./indexDefinitions.js";
+export default function buildCreateIndexQuery(table: string, index: IndexDefinition): string;
+//# sourceMappingURL=indexQueries.d.ts.map

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/indexQueries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexQueries.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/indexQueries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAI7D,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAC3C,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,eAAe,GACrB,MAAM,CASR"}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/indexQueries.js

@@ -0,0 +1,36 @@
+import parseValue from "./parseValue.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+export default function buildCreateIndexQuery(table, index) {
+    switch (index.kind) {
+        case "fts":
+            return buildFtsIndexQuery(table, index);
+        case "vss":
+            return buildVssIndexQuery(table, index);
+        default:
+            return assertNever(index);
+    }
+}
+function assertNever(value) {
+    throw new Error(`Unsupported index definition: ${JSON.stringify(value)}`);
+}
+function buildVssIndexQuery(table, index) {
+    const withOptions = ["metric = 'cosine'"];
+    if (index.options.efConstruction !== undefined) {
+        withOptions.push(`ef_construction = ${index.options.efConstruction}`);
+    }
+    if (index.options.efSearch !== undefined) {
+        withOptions.push(`ef_search = ${index.options.efSearch}`);
+    }
+    if (index.options.M !== undefined) {
+        withOptions.push(`M = ${index.options.M}`);
+    }
+    return `CREATE INDEX ${quoteIdentifier(index.name)} ON ${quoteIdentifier(table)}
+    USING HNSW (${quoteIdentifier(index.column)})
+    WITH (${withOptions.join(", ")});`;
+}
+function buildFtsIndexQuery(table, index) {
+    const options = index.options;
+    return `PRAGMA create_fts_index(${quoteIdentifier(table)}, ${quoteIdentifier(index.idColumn)}, ${quoteIdentifier(index.textColumn)}${options.stemmer ? `, stemmer = ${parseValue(options.stemmer)}` : ""}${options.stopwords ? `, stopwords = ${parseValue(options.stopwords)}` : ""}${options.ignore ? `, ignore = ${parseValue(options.ignore)}` : ""}${options.stripAccents !== undefined
+        ? `, strip_accents = ${options.stripAccents ? 1 : 0}`
+        : ""}${options.lower !== undefined ? `, lower = ${options.lower ? 1 : 0}` : ""});`;
+}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/keepNumericalColumns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keepNumericalColumns.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/keepNumericalColumns.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,oBAAoB,CAAC,KAAK,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,YAa5E"}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/keepNumericalColumns.js

@@ -0,0 +1,12 @@
+export default function keepNumericalColumns(types) {
+    const columns = [];
+    for (const col of Object.keys(types)) {
+        const type = types[col];
+        if (["FLOAT", "DOUBLE", "REAL"].includes(type) ||
+            type.startsWith("DECIMAL") ||
+            type.includes("INT")) {
+            columns.push(col);
+        }
+    }
+    return columns;
+}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/loadOsmFile.d.ts

@@ -0,0 +1,10 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function loadOsmFile(table: SimpleTable, file: string, context: {
+    method: "loadGeoData()" | "loadOSM()";
+    parameters: {
+        [key: string]: unknown;
+    };
+    columns?: string[];
+    conditions?: string;
+}): Promise<void>;
+//# sourceMappingURL=loadOsmFile.d.ts.map

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/loadOsmFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadOsmFile.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/loadOsmFile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAMvD,wBAA8B,WAAW,CACvC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IACP,MAAM,EAAE,eAAe,GAAG,WAAW,CAAC;IACtC,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACvC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,OAAO,CAAC,IAAI,CAAC,CA2Bf"}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/loadOsmFile.js

@@ -0,0 +1,28 @@
+import mergeOptions from "./mergeOptions.js";
+import parseValue from "./parseValue.js";
+import queryDB from "./queryDB.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+export default async function loadOsmFile(table, file, context) {
+    const selectColumns = context.columns !== undefined &&
+        context.columns.length > 0
+        ? context.columns.map(quoteIdentifier).join(", ")
+        : "* EXCLUDE (geometry)";
+    const conditions = context.conditions ? ` WHERE ${context.conditions}` : "";
+    // Expose geom before filtering, even when it is not selected for output.
+    await queryDB(table, `INSTALL spatial;
+    LOAD spatial;
+    INSTALL osmium FROM community;
+    LOAD osmium;
+    SET geometry_always_xy = true;
+    CREATE OR REPLACE TABLE ${quoteIdentifier(table.name)} AS
+    SELECT ${selectColumns}
+    FROM (
+      SELECT *, geometry::GEOMETRY('EPSG:4326') AS geom
+      FROM osmium_read(${parseValue(file)})
+    )${conditions};`, mergeOptions(table, {
+        table: table.name,
+        method: context.method,
+        parameters: context.parameters,
+    }));
+    table.sdb.spatialLoaded = true;
+}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/logData.d.ts

@@ -0,0 +1,6 @@
+export default function logData(types: {
+    [key: string]: string;
+} | null, data: {
+    [key: string]: unknown;
+}[] | null, charsToLog?: number): void;
+//# sourceMappingURL=logData.d.ts.map

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/logData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logData.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/logData.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,UAAU,OAAO,CAC7B,KAAK,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG,IAAI,EACvC,IAAI,EACA;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,EAAE,GACD,IAAI,EACR,UAAU,CAAC,EAAE,MAAM,QA4DpB"}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/logData.js

@@ -0,0 +1,53 @@
+import printTable from "./printTable.js";
+export default function logData(types, data, charsToLog) {
+    if (data === null) {
+        console.log("Data is null");
+    }
+    else {
+        if (data.length === 0) {
+            console.log(data);
+        }
+        else {
+            const dataToBeLogged = [];
+            const keys = Object.keys(data[0]);
+            for (let i = 0; i < data.length; i++) {
+                const newItem = {};
+                for (const key of keys) {
+                    if (typeof charsToLog === "number" &&
+                        typeof data[i][key] === "string" &&
+                        data[i][key].length > charsToLog) {
+                        newItem[key] = data[i][key].slice(0, charsToLog) + "...";
+                    }
+                    else {
+                        newItem[key] = data[i][key];
+                    }
+                }
+                dataToBeLogged.push(newItem);
+            }
+            let hasTypesRow = false;
+            if (types !== null) {
+                const columns = Object.keys(types);
+                if (columns.length > 0) {
+                    for (const col of columns) {
+                        if (data[0][col] === "<Geometry>") {
+                            continue;
+                        }
+                        else {
+                            types[col] = types[col] + "/" +
+                                (data[0][col] === null ? null : typeof data[0][col]);
+                        }
+                    }
+                    // Add types as the first row
+                    dataToBeLogged.unshift(types);
+                    hasTypesRow = true;
+                }
+            }
+            printTable(dataToBeLogged, {
+                ...(typeof charsToLog === "number"
+                    ? { maxColumnWidth: charsToLog }
+                    : {}),
+                ...(hasTypesRow ? { typesRowIndex: 0 } : {}),
+            });
+        }
+    }
+}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/mergeOptions.d.ts

@@ -0,0 +1,60 @@
+import type { DuckDBValue as NativeDuckDBValue } from "@duckdb/node-api";
+/** @internal DuckDB owns this type; retain its exact binding contract without re-exporting it. */
+type DuckDBValue = NativeDuckDBValue;
+/**
+ * Combines a table or database's logging defaults with query-specific options.
+ * Use this helper with `queryDB()` when implementing an extension.
+ *
+ * @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.
+ *
+ * @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);
+ * ```
+ */
+export default 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[];
+    noClean?: boolean;
+}): {
+    table: string | null;
+    method: string | null;
+    parameters: {
+        [key: string]: unknown;
+    } | null;
+    rowsToLog: number;
+    charsToLog: number | undefined;
+    returnData: boolean;
+    values?: DuckDBValue[];
+    noClean?: boolean;
+};
+export {};
+//# sourceMappingURL=mergeOptions.d.ts.map

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/mergeOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mergeOptions.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/mergeOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,IAAI,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEzE,kGAAkG;AAClG,KAAK,WAAW,GAAG,iBAAiB,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAC7D,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA;IACD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAWA"}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/mergeOptions.js

@@ -0,0 +1,42 @@
+/**
+ * Combines a table or database's logging defaults with query-specific options.
+ * Use this helper with `queryDB()` when implementing an extension.
+ *
+ * @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.
+ *
+ * @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);
+ * ```
+ */
+export default function mergeOptions(simple, options) {
+    return {
+        table: options.table,
+        method: options.method,
+        parameters: options.parameters,
+        rowsToLog: options.rowsToLog ?? simple.rowsToLog,
+        charsToLog: simple.charsToLog,
+        returnData: options.returnData ?? false,
+        values: options.values,
+        noClean: options.noClean,
+    };
+}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/observeQuery.d.ts

@@ -0,0 +1,9 @@
+import type { DuckDBConnection, DuckDBValue } from "@duckdb/node-api";
+/**
+ * Logs optional SQL diagnostics without changing the statement that will run.
+ */
+export default function observeQuery(connection: DuckDBConnection, query: string, values: DuckDBValue[], options: {
+    logSQL: boolean;
+    explainSQL: boolean;
+}): Promise<void>;
+//# sourceMappingURL=observeQuery.d.ts.map

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/observeQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observeQuery.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/observeQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAatE;;GAEG;AACH,wBAA8B,YAAY,CACxC,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,EAAE;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,GAChD,OAAO,CAAC,IAAI,CAAC,CA2Bf"}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/observeQuery.js

@@ -0,0 +1,49 @@
+const explainableStatements = new Set([
+    "CREATE",
+    "DELETE",
+    "FROM",
+    "INSERT",
+    "MERGE",
+    "SELECT",
+    "UPDATE",
+    "WITH",
+]);
+/**
+ * Logs optional SQL diagnostics without changing the statement that will run.
+ */
+export default async function observeQuery(connection, query, values, options) {
+    if (options.explainSQL && await canExplain(connection, query)) {
+        try {
+            const explain = `EXPLAIN ${query}`;
+            const result = values.length === 0
+                ? await connection.run(explain)
+                : await connection.run(explain, values);
+            const rows = await result.getRowsJS();
+            const plan = rows.map((row) => String(row[1] ?? row[0] ?? "")).join("\n");
+            console.log(`EXPLAIN ${query}\n${plan}`);
+        }
+        catch (error) {
+            console.warn(`SDA: Could not explain the following SQL; executing it normally.\n${query}\n${String(error)}`);
+        }
+    }
+    // Keep this immediately before connection.run()/stream() so the last SQL
+    // diagnostic identifies the statement responsible for an execution error.
+    if (options.logSQL) {
+        console.log(query);
+        if (values.length > 0) {
+            console.log("Bound values:", values);
+        }
+    }
+}
+async function canExplain(connection, query) {
+    const keyword = query.trimStart().match(/^([A-Za-z]+)/)?.[1].toUpperCase();
+    if (keyword === undefined || !explainableStatements.has(keyword)) {
+        return false;
+    }
+    try {
+        return (await connection.extractStatements(query)).count === 1;
+    }
+    catch {
+        return false;
+    }
+}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/osmCache.d.ts

@@ -0,0 +1,16 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export declare function createOsmCacheId(identity: {
+    endpoint: string;
+    bbox: {
+        west: number;
+        south: number;
+        east: number;
+        north: number;
+    };
+    query: string;
+    queryGeneratorVersion: string;
+}): string;
+export declare function useProcessedOsmCache(table: SimpleTable, id: string, enabled: boolean, parameters: {
+    [key: string]: unknown;
+}, compute: () => Promise<void>): Promise<void>;
+//# sourceMappingURL=osmCache.d.ts.map

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/osmCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"osmCache.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/osmCache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAUvD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB,EAAE,MAAM,CAAC;CAC/B,GAAG,MAAM,CAET;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EACtC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CAsCf"}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/osmCache.js

@@ -0,0 +1,41 @@
+import fileCache, { createFileCacheId } from "./fileCache.js";
+import mergeOptions from "./mergeOptions.js";
+import parseValue from "./parseValue.js";
+import queryDB from "./queryDB.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+const CACHE_DIRECTORY = ".sda-cache/osm";
+const OSM_CACHE_FORMAT_VERSION = "osm-geoparquet-v1";
+export function createOsmCacheId(identity) {
+    return createFileCacheId("osm", identity);
+}
+export async function useProcessedOsmCache(table, id, enabled, parameters, compute) {
+    await fileCache(table, {
+        directory: CACHE_DIRECTORY,
+        enabled,
+        extension: "geoparquet",
+        formatVersion: OSM_CACHE_FORMAT_VERSION,
+        id,
+        method: "loadOSM()",
+        load: async (file) => {
+            await queryDB(table, `INSTALL spatial;
+        LOAD spatial;
+        SET geometry_always_xy = true;
+        CREATE OR REPLACE TABLE ${quoteIdentifier(table.name)} AS
+        SELECT * FROM read_parquet(${parseValue(file)});`, mergeOptions(table, {
+                table: table.name,
+                method: "loadOSM()",
+                parameters,
+            }));
+            table.sdb.spatialLoaded = true;
+        },
+        compute,
+        write: async (file) => {
+            await queryDB(table, `COPY ${quoteIdentifier(table.name)} TO ${parseValue(file)}
+        WITH (FORMAT PARQUET);`, mergeOptions(table, {
+                table: table.name,
+                method: "loadOSM()",
+                parameters,
+            }));
+        },
+    });
+}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/osmFiles.d.ts

@@ -0,0 +1,9 @@
+export type OsmFileSuffix = ".osm" | ".osm.pbf";
+export declare function getOsmFileSuffix(file: string): OsmFileSuffix | null;
+export declare function isRemoteOsmUrl(file: string): boolean;
+export declare function downloadOsmToTemporaryFile(url: string, options: {
+    suffix: OsmFileSuffix;
+    prefix?: string;
+    request?: RequestInit;
+}): Promise<string>;
+//# sourceMappingURL=osmFiles.d.ts.map

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/osmFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"osmFiles.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/osmFiles.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,UAAU,CAAC;AAEhD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAUnE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOpD;AAED,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IACP,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB,GACA,OAAO,CAAC,MAAM,CAAC,CAyCjB"}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/osmFiles.js

@@ -0,0 +1,52 @@
+import crypto from "node:crypto";
+import { createWriteStream, mkdirSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+export function getOsmFileSuffix(file) {
+    const comparable = isRemoteOsmUrl(file) ? new URL(file).pathname : file;
+    const lower = comparable.toLowerCase();
+    if (lower.endsWith(".osm.pbf")) {
+        return ".osm.pbf";
+    }
+    if (lower.endsWith(".osm")) {
+        return ".osm";
+    }
+    return null;
+}
+export function isRemoteOsmUrl(file) {
+    try {
+        const protocol = new URL(file).protocol;
+        return protocol === "http:" || protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+export async function downloadOsmToTemporaryFile(url, options) {
+    const temporaryDirectory = ".sda-cache/tmp";
+    mkdirSync(temporaryDirectory, { recursive: true });
+    const prefix = options.prefix === undefined ? "remote" : options.prefix;
+    const temporaryFile = `${temporaryDirectory}/${prefix}.${crypto.randomUUID()}${options.suffix}`;
+    const response = await fetch(url, options.request);
+    if (!response.ok) {
+        const responseText = (await response.text()).slice(0, 500).trim();
+        throw new Error(`Could not download OSM data from ${JSON.stringify(url)}: HTTP ${response.status} ${response.statusText}${responseText.length > 0 ? `\n${responseText}` : ""}`);
+    }
+    if (response.body === null) {
+        throw new Error(`Could not download OSM data from ${JSON.stringify(url)}: the response body is empty.`);
+    }
+    try {
+        await pipeline(Readable.fromWeb(response.body), createWriteStream(temporaryFile, { flags: "wx" }));
+    }
+    catch (error) {
+        try {
+            await rm(temporaryFile, { force: true });
+        }
+        catch {
+            // Preserve the download error.
+        }
+        throw error;
+    }
+    return temporaryFile;
+}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/parseDuckDBType.d.ts

@@ -0,0 +1,2 @@
+export default function parseDuckDBType(type: string): import("@duckdb/node-api").DuckDBBooleanType | import("@duckdb/node-api").DuckDBIntegerType | import("@duckdb/node-api").DuckDBBigIntType | import("@duckdb/node-api").DuckDBDoubleType | import("@duckdb/node-api").DuckDBTimestampType | import("@duckdb/node-api").DuckDBDateType | import("@duckdb/node-api").DuckDBTimeType | import("@duckdb/node-api").DuckDBVarCharType | import("@duckdb/node-api").DuckDBArrayType | import("@duckdb/node-api").DuckDBTimestampTZType;
+//# sourceMappingURL=parseDuckDBType.d.ts.map

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/parseDuckDBType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseDuckDBType.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/parseDuckDBType.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,IAAI,EAAE,MAAM,mdA0BnD"}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/parseTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseTypes.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/parseTypes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,IAAI,EACA,SAAS,GACT,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,MAAM,GACN,UAAU,GACV,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,GACX,0BAA0B,GAC1B,SAAS,GACT,aAAa,MAAM,IAAI,GACvB,aAAa,MAAM,IAAI,UAgC5B"}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/parseValue.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import { parseValue } from "@nshiab/simple-data-analysis-core/helpers";
+ * console.log(parseValue("O'Brien")); // "'O''Brien'"
+ * console.log(parseValue(null)); // "NULL"
+ * ```
+ */
+export default function parseValue(value: unknown): string | boolean | number;
+//# sourceMappingURL=parseValue.d.ts.map

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/parseValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseValue.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/parseValue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAc5E"}

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/helpers/parseValue.js

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import { parseValue } from "@nshiab/simple-data-analysis-core/helpers";
+ * console.log(parseValue("O'Brien")); // "'O''Brien'"
+ * console.log(parseValue(null)); // "NULL"
+ * ```
+ */
+export default function parseValue(value) {
+    if (Number.isNaN(value) || value === undefined || value === null) {
+        return "NULL";
+    }
+    else if (value instanceof Date) {
+        return `'${value.toISOString()}'`;
+    }
+    else if (typeof value === "string") {
+        return `'${value.replaceAll("'", "''")}'`;
+    }
+    else if (typeof value === "boolean") {
+        return value;
+    }
+    else if (typeof value === "number") {
+        return value;
+    }
+    else {
+        throw new Error(`Unknown type ${typeof value} of ${value}.`);
+    }
+}