@nshiab/simple-data-analysis-core 1.0.1 → 2.0.0

package/esm/methods/renameColumns.js

@@ -0,0 +1,27 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import assertColumnsExist from "../helpers/assertColumnsExist.js";
+import queueOp from "../helpers/queueOp.js";
+export default function renameColumns(simpleTable, names, options = {}) {
+    const oldNames = Object.keys(names);
+    const newNames = Object.values(names);
+    // DuckDB's SELECT * RENAME silently drops a rename whose source column is
+    // absent, so a typo would pass unnoticed. Validating requires the schema;
+    // strict: false skips both the check and its DESCRIBE round-trip.
+    const strict = options.strict !== false;
+    names = { ...names };
+    options = { ...options };
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "renameColumns()",
+        parameters: { names, options },
+        needsSchema: strict,
+        buildSelect: (input, schema) => {
+            if (strict) {
+                assertColumnsExist(schema, oldNames, "renameColumns()");
+            }
+            return `SELECT * RENAME (${oldNames
+                .map((d, i) => `${quoteIdentifier(d)} AS ${quoteIdentifier(newNames[i])}`)
+                .join(", ")}) FROM ${input}`;
+        },
+    });
+}

package/esm/methods/renameTable.d.ts

@@ -0,0 +1,3 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function renameTable(simpleTable: SimpleTable, name: string): Promise<void>;
+//# sourceMappingURL=renameTable.d.ts.map

package/esm/methods/renameTable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renameTable.d.ts","sourceRoot":"","sources":["../../src/methods/renameTable.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAGvD,wBAA8B,WAAW,CACvC,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE,MAAM,iBAcb"}

package/esm/methods/renameTable.js

@@ -0,0 +1,12 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import mergeOptions from "../helpers/mergeOptions.js";
+import queryDB from "../helpers/queryDB.js";
+import { markTableChanged } from "../helpers/tableGeneration.js";
+export default async function renameTable(simpleTable, name) {
+    await queryDB(simpleTable, `ALTER TABLE ${quoteIdentifier(simpleTable.name)} RENAME TO ${quoteIdentifier(name)};`, mergeOptions(simpleTable, {
+        table: simpleTable.name,
+        method: "renameTable()",
+        parameters: { name },
+    }));
+    markTableChanged(simpleTable);
+}

package/esm/methods/repeatRows.d.ts

@@ -0,0 +1,5 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function repeatRows(simpleTable: SimpleTable, column: string, options?: {
+    index?: string;
+}): void;
+//# sourceMappingURL=repeatRows.d.ts.map

package/esm/methods/repeatRows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repeatRows.d.ts","sourceRoot":"","sources":["../../src/methods/repeatRows.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,UAAU,CAChC,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,QAoBjC"}

package/esm/methods/repeatRows.js

@@ -0,0 +1,19 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import assertNewColumns from "../helpers/assertNewColumns.js";
+import queueOp from "../helpers/queueOp.js";
+export default function repeatRows(simpleTable, column, options = {}) {
+    options = { ...options };
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "repeatRows()",
+        parameters: { column, options },
+        needsSchema: options.index !== undefined,
+        buildSelect: (input, schema) => {
+            if (options.index) {
+                assertNewColumns(schema, [options.index], "repeatRows()");
+                return `SELECT *, UNNEST(range(CAST(${quoteIdentifier(column)} AS BIGINT))) AS ${quoteIdentifier(options.index)} FROM ${input}`;
+            }
+            return `SELECT * EXCLUDE (_index) FROM (SELECT *, UNNEST(range(CAST(${quoteIdentifier(column)} AS BIGINT))) AS _index FROM ${input})`;
+        },
+    });
+}

package/esm/methods/replace.d.ts

@@ -0,0 +1,8 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function replace(simpleTable: SimpleTable, columns: "all" | string | string[], replacements: {
+    [key: string]: string;
+}, options?: {
+    entireString?: boolean;
+    regex?: boolean;
+}): void;
+//# sourceMappingURL=replace.d.ts.map

package/esm/methods/replace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace.d.ts","sourceRoot":"","sources":["../../src/methods/replace.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,OAAO,CAC7B,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,EAAE,EAClC,YAAY,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,EACvC,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;CACZ,QAuDP"}

package/esm/methods/replace.js

@@ -0,0 +1,69 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import queueOp from "../helpers/queueOp.js";
+import stringToArray from "../helpers/stringToArray.js";
+export default function replace(simpleTable, columns, replacements, options = {}) {
+    columns = Array.isArray(columns) ? [...columns] : columns;
+    replacements = { ...replacements };
+    options = { ...options };
+    options.entireString = options.entireString ?? false;
+    options.regex = options.regex ?? false;
+    const entries = Object.entries(replacements);
+    const replacementEntries = options.entireString
+        ? entries.map(([oldText]) => {
+            let newText = oldText;
+            for (const [candidate, replacement] of entries) {
+                if (newText === candidate) {
+                    newText = replacement;
+                }
+            }
+            return [oldText, newText];
+        })
+        : entries;
+    // This validation doesn't need the database, so it stays at call time.
+    if (options.entireString === true && options.regex === true) {
+        throw new Error("You can't have entireString to true and regex to true at the same time. Pick one.");
+    }
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "replace()",
+        parameters: { columns, replacements, options },
+        // The schema is only needed to resolve "all" to the column list.
+        needsSchema: columns === "all",
+        values: (schema) => {
+            const columnList = columns === "all"
+                ? Object.keys(schema)
+                : stringToArray(columns);
+            return columnList.flatMap(() => replacementEntries.flatMap(([oldText, newText]) => [
+                oldText,
+                newText,
+            ]));
+        },
+        buildSelect: (input, schema) => {
+            const columnList = columns === "all"
+                ? Object.keys(schema)
+                : stringToArray(columns);
+            return replaceSelect(input, columnList, replacementEntries.length, options);
+        },
+    });
+}
+function replaceSelect(input, columns, replacementCount, options = {}) {
+    // The sequential UPDATEs become nested expressions: each replacement
+    // applies to the result of the previous one.
+    const replacements = columns.map((column) => {
+        let expression = `${quoteIdentifier(column)}`;
+        if (options.entireString) {
+            const branches = Array.from({ length: replacementCount }, () => "WHEN ? THEN ?").join(" ");
+            return `CASE ${expression} ${branches} ELSE ${expression} END AS ${quoteIdentifier(column)}`;
+        }
+        for (let i = 0; i < replacementCount; i++) {
+            if (options.regex) {
+                expression = `REGEXP_REPLACE(${expression}, ?, ?, 'g')`;
+            }
+            else {
+                expression = `REPLACE(${expression}, ?, ?)`;
+            }
+        }
+        return `${expression} AS ${quoteIdentifier(column)}`;
+    });
+    return `SELECT * REPLACE (${replacements.join(", ")}) FROM ${input}`;
+}

package/esm/methods/replaceNulls.d.ts

@@ -0,0 +1,3 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function replaceNulls(simpleTable: SimpleTable, columns: "all" | string | string[], value: unknown): void;
+//# sourceMappingURL=replaceNulls.d.ts.map

package/esm/methods/replaceNulls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replaceNulls.d.ts","sourceRoot":"","sources":["../../src/methods/replaceNulls.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAIvD,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,EAAE,EAClC,KAAK,EAAE,OAAO,QAsCf"}

package/esm/methods/replaceNulls.js

@@ -0,0 +1,36 @@
+import queueOp from "../helpers/queueOp.js";
+import stringToArray from "../helpers/stringToArray.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import toDuckDBValue from "../helpers/toDuckDBValue.js";
+export default function replaceNulls(simpleTable, columns, value) {
+    columns = Array.isArray(columns) ? [...columns] : columns;
+    const capturedValue = value instanceof Date
+        ? new Date(value.getTime())
+        : value;
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "replaceNulls()",
+        // The schema resolves "all" to the column list and gives each column's
+        // type: v1 replaced nulls with an UPDATE, which assignment-casts the
+        // value to the column's type (e.g. 0 into a VARCHAR column becomes '0').
+        // COALESCE can't mix types, so the value is cast to the column's type to
+        // reproduce that.
+        needsSchema: true,
+        preservesSchema: true,
+        parameters: { columns, value: capturedValue },
+        values: (schema) => {
+            const columnList = columns === "all"
+                ? Object.keys(schema)
+                : stringToArray(columns);
+            return columnList.map(() => toDuckDBValue(capturedValue));
+        },
+        buildSelect: (input, schema) => {
+            const columnList = columns === "all"
+                ? Object.keys(schema)
+                : stringToArray(columns);
+            return `SELECT * REPLACE (${columnList
+                .map((column) => `COALESCE(${quoteIdentifier(column)}, CAST(? AS ${schema[column]})) AS ${quoteIdentifier(column)}`)
+                .join(", ")}) FROM ${input}`;
+        },
+    });
+}

package/esm/methods/reproject.d.ts

@@ -0,0 +1,5 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function reproject(simpleTable: SimpleTable, crs: string, options?: {
+    column?: string;
+}): void;
+//# sourceMappingURL=reproject.d.ts.map

package/esm/methods/reproject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reproject.d.ts","sourceRoot":"","sources":["../../src/methods/reproject.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,WAAW,EAAE,WAAW,EACxB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,QAsBlC"}

package/esm/methods/reproject.js

@@ -0,0 +1,21 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import findGeoColumnFromSchema from "../helpers/findGeoColumnFromSchema.js";
+import parseValue from "../helpers/parseValue.js";
+import queueOp from "../helpers/queueOp.js";
+export default function reproject(simpleTable, crs, options = {}) {
+    const targetGeoType = `GEOMETRY${crs !== "null" ? `(${parseValue(crs)})` : ""}`;
+    options = structuredClone(options);
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "reproject()",
+        parameters: { crs, options },
+        needsSchema: true,
+        needsSpatial: true,
+        buildSelect: (input, types) => {
+            const column = typeof options.column === "string"
+                ? options.column
+                : findGeoColumnFromSchema(types, "reproject()", simpleTable.name);
+            return `SELECT * REPLACE (ST_Transform(${quoteIdentifier(column)}, ${parseValue(crs)})::${targetGeoType} AS ${quoteIdentifier(column)}) FROM ${input}`;
+        },
+    });
+}

package/esm/methods/rolling.d.ts

@@ -0,0 +1,6 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function rolling(simpleTable: SimpleTable, column: string, newColumn: string, stat: "min" | "max" | "mean" | "median" | "sum", preceding: number, following: number, options?: {
+    by?: string | string[];
+    decimals?: number;
+}): void;
+//# sourceMappingURL=rolling.d.ts.map

package/esm/methods/rolling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rolling.d.ts","sourceRoot":"","sources":["../../src/methods/rolling.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,OAAO,CAC7B,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,EAC/C,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IACP,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACd,QAoBP"}

package/esm/methods/rolling.js

@@ -0,0 +1,42 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import assertNewColumns from "../helpers/assertNewColumns.js";
+import queueOp from "../helpers/queueOp.js";
+import stringToArray from "../helpers/stringToArray.js";
+export default function rolling(simpleTable, column, newColumn, stat, preceding, following, options = {}) {
+    options = structuredClone(options);
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "rolling()",
+        parameters: { column, newColumn, stat, preceding, following, options },
+        needsSchema: true,
+        buildSelect: (input, schema) => rollingSelect(input, schema, column, newColumn, stat, preceding, following, options),
+    });
+}
+function rollingSelect(input, schema, column, newColumn, stat, preceding, following, options = {}) {
+    assertNewColumns(schema, [newColumn], "rolling()");
+    const aggregates = {
+        count: "COUNT",
+        min: "MIN",
+        max: "MAX",
+        mean: "AVG",
+        median: "MEDIAN",
+        sum: "SUM",
+    };
+    const by = options.by ? stringToArray(options.by) : [];
+    const partition = by.length > 0
+        ? `PARTITION BY ${by.map((d) => `${quoteIdentifier(d)}`).join(", ")}`
+        : "";
+    const window = `OVER (${partition}
+                ROWS BETWEEN ${preceding} PRECEDING AND ${following} FOLLOWING)`;
+    const tempQuery = `${aggregates[stat]}(${quoteIdentifier(column)}) ${window}`;
+    // Windows touching the edges of the frame (or of their category) have
+    // fewer values than requested, so their result is NULL.
+    return `SELECT *,
+    CASE
+        WHEN COUNT(${quoteIdentifier(column)}) ${window} != ${preceding + following + 1} THEN NULL
+        ELSE ${typeof options.decimals === "number"
+        ? `ROUND(${tempQuery}, ${options.decimals})`
+        : tempQuery}
+    END AS ${quoteIdentifier(newColumn)}
+        FROM ${input}`;
+}

package/esm/methods/round.d.ts

@@ -0,0 +1,6 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function round(simpleTable: SimpleTable, columns: string | string[], options?: number | {
+    decimals?: number;
+    method?: "round" | "ceiling" | "floor";
+}): void;
+//# sourceMappingURL=round.d.ts.map

package/esm/methods/round.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round.d.ts","sourceRoot":"","sources":["../../src/methods/round.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,KAAK,CAC3B,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,EAC1B,OAAO,GACH,MAAM,GACN;IACA,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;CACnC,QA2BT"}

package/esm/methods/round.js

@@ -0,0 +1,22 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import queueOp from "../helpers/queueOp.js";
+import stringToArray from "../helpers/stringToArray.js";
+export default function round(simpleTable, columns, options = {}) {
+    const optionsNormalized = typeof options === "number"
+        ? { decimals: options }
+        : options;
+    const cols = stringToArray(columns);
+    const method = optionsNormalized.method?.toUpperCase() ?? "ROUND";
+    const decimals = optionsNormalized.decimals ?? 0;
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "round()",
+        parameters: { columns, options },
+        needsSchema: false,
+        buildSelect: (input) => `SELECT * REPLACE (${cols
+            .map((c) => method === "ROUND"
+            ? `${method}(${quoteIdentifier(c)}, ${decimals}) AS ${quoteIdentifier(c)}`
+            : `${method}(${quoteIdentifier(c)}) AS ${quoteIdentifier(c)}`)
+            .join(", ")}) FROM ${input}`,
+    });
+}

package/esm/methods/rowProportions.d.ts

@@ -0,0 +1,6 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function rowProportions(simpleTable: SimpleTable, columns: string[], options?: {
+    suffix?: string;
+    decimals?: number;
+}): void;
+//# sourceMappingURL=rowProportions.d.ts.map

package/esm/methods/rowProportions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowProportions.d.ts","sourceRoot":"","sources":["../../src/methods/rowProportions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,cAAc,CACpC,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACd,QAoCP"}

package/esm/methods/rowProportions.js

@@ -0,0 +1,30 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import assertNewColumns from "../helpers/assertNewColumns.js";
+import queueOp from "../helpers/queueOp.js";
+export default function rowProportions(simpleTable, columns, options = {}) {
+    columns = [...columns];
+    options = structuredClone(options);
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "rowProportions()",
+        parameters: { columns, options },
+        needsSchema: true,
+        buildSelect: (input, schema) => {
+            const suffix = options.suffix ?? "Perc";
+            assertNewColumns(schema, columns.map((col) => `${col}${suffix}`), "rowProportions()");
+            let query = `SELECT *,`;
+            for (const col of columns) {
+                const tempQuery = `${quoteIdentifier(col)} / (${columns.map((d) => `${quoteIdentifier(d)}`).join(" + ")})`;
+                if (typeof options.decimals === "number") {
+                    query += ` ROUND(${tempQuery}, ${options.decimals})`;
+                }
+                else {
+                    query += ` ${tempQuery}`;
+                }
+                query += ` AS ${quoteIdentifier(`${col}${suffix}`)},`;
+            }
+            query += `FROM ${input}`;
+            return query;
+        },
+    });
+}

package/esm/methods/rowRanks.d.ts

@@ -0,0 +1,9 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function rowRanks(simpleTable: SimpleTable, columns: string[], options: {
+    nameColumn?: string;
+    valueColumn?: string;
+    rank?: number;
+    order?: "asc" | "desc";
+    ties?: "strict" | "first" | "all";
+}): void;
+//# sourceMappingURL=rowRanks.d.ts.map

package/esm/methods/rowRanks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowRanks.d.ts","sourceRoot":"","sources":["../../src/methods/rowRanks.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC9B,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE;IACP,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,KAAK,CAAC;CACnC,QAwEF"}

package/esm/methods/rowRanks.js

@@ -0,0 +1,113 @@
+import assertColumnsExist from "../helpers/assertColumnsExist.js";
+import assertNewColumns from "../helpers/assertNewColumns.js";
+import keepNumericalColumns from "../helpers/keepNumericalColumns.js";
+import queueOp from "../helpers/queueOp.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+export default function rowRanks(simpleTable, columns, options) {
+    columns = [...columns];
+    options = structuredClone(options);
+    const rank = options.rank ?? 1;
+    const order = options.order ?? "desc";
+    const ties = options.ties ?? "strict";
+    if (columns.length === 0) {
+        throw new Error("rowRanks() requires at least one column.");
+    }
+    const duplicateColumns = columns.filter((column, index) => columns.indexOf(column) !== index);
+    if (duplicateColumns.length > 0) {
+        const duplicates = [...new Set(duplicateColumns)];
+        throw new Error(`rowRanks() received duplicate column${duplicates.length === 1 ? "" : "s"} ${duplicates.map(quoteIdentifier).join(", ")}. Include each column only once.`);
+    }
+    if (options.nameColumn === undefined && options.valueColumn === undefined) {
+        throw new Error("rowRanks() requires nameColumn, valueColumn, or both.");
+    }
+    if (options.nameColumn !== undefined &&
+        options.nameColumn === options.valueColumn) {
+        throw new Error(`rowRanks() cannot use ${quoteIdentifier(options.nameColumn)} for both output columns.`);
+    }
+    if (!Number.isInteger(rank) || rank < 1) {
+        throw new Error("rowRanks() options.rank must be a positive integer.");
+    }
+    if (rank > columns.length) {
+        throw new Error(`rowRanks() options.rank is ${rank}, but only ${columns.length} column${columns.length === 1 ? " was" : "s were"} provided. Use a rank between 1 and ${columns.length}.`);
+    }
+    if (order !== "asc" && order !== "desc") {
+        throw new Error('rowRanks() options.order must be "asc" or "desc".');
+    }
+    if (ties !== "strict" && ties !== "first" && ties !== "all") {
+        throw new Error('rowRanks() options.ties must be "strict", "first", or "all".');
+    }
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "rowRanks()",
+        parameters: { columns, options },
+        needsSchema: true,
+        values: columns,
+        buildSelect: (input, schema) => rowRanksSelect(input, schema, columns, options, rank, order, ties),
+    });
+}
+function rowRanksSelect(input, schema, columns, options, rank, order, ties) {
+    assertColumnsExist(schema, columns, "rowRanks()");
+    const outputColumns = [options.nameColumn, options.valueColumn].filter((column) => column !== undefined);
+    assertNewColumns(schema, outputColumns, "rowRanks()");
+    const numericalColumns = new Set(keepNumericalColumns(schema));
+    const nonNumericalColumns = columns.filter((column) => !numericalColumns.has(column));
+    if (nonNumericalColumns.length > 0) {
+        throw new Error(`rowRanks() requires numeric columns, but ${nonNumericalColumns.map((column) => `${quoteIdentifier(column)} has type ${schema[column]}`).join(", ")}. Convert ${nonNumericalColumns.length === 1 ? "it" : "them"} to a numeric type first.`);
+    }
+    const candidates = columns.map((column, index) => `(?, ${quoteIdentifier(column)}, ${index})`).join(",\n      ");
+    const selections = [];
+    if (options.nameColumn !== undefined) {
+        selections.push(`selected.selected_name AS ${quoteIdentifier(options.nameColumn)}`);
+    }
+    if (options.valueColumn !== undefined) {
+        selections.push(`selected.selected_value AS ${quoteIdentifier(options.valueColumn)}`);
+    }
+    const tied = `WITH candidates(name, value, position) AS (
+    VALUES ${candidates}
+  ),
+  selected_value AS (
+    SELECT value
+    FROM candidates
+    WHERE value IS NOT NULL
+    ORDER BY value ${order.toUpperCase()}, position
+    LIMIT 1 OFFSET ${rank - 1}
+  ),
+  tied AS (
+    SELECT name, value, position
+    FROM candidates
+    WHERE value = (SELECT value FROM selected_value)
+  )`;
+    let selection;
+    if (ties === "all") {
+        selection = `${tied}
+  SELECT name AS selected_name, value AS selected_value
+  FROM tied
+  ORDER BY position`;
+    }
+    else if (ties === "strict") {
+        selection = `${tied}
+  SELECT FIRST(name ORDER BY position) AS selected_name,
+  FIRST(value ORDER BY position) AS selected_value
+  FROM tied
+  HAVING CASE
+    WHEN COUNT(*) > 1 THEN error(CONCAT(
+      'rowRanks() found a tie at rank ${rank} between columns ',
+      STRING_AGG(CONCAT('"', REPLACE(name, '"', '""'), '"'), ', ' ORDER BY position),
+      '. Use { ties: "first" } to select the first tied column, or { ties: "all" } to produce one row for each tied column.'
+    ))
+    ELSE TRUE
+  END`;
+    }
+    else {
+        selection = `${tied}
+  SELECT name AS selected_name, value AS selected_value
+  FROM tied
+  ORDER BY position
+  LIMIT 1`;
+    }
+    return `SELECT source.*, ${selections.join(", ")}
+FROM ${input} AS source
+LEFT JOIN LATERAL (
+  ${selection}
+) AS selected ON TRUE`;
+}

package/esm/methods/rowToText.d.ts

@@ -0,0 +1,3 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function rowToText(simpleTable: SimpleTable, columns: string[], newColumn: string): void;
+//# sourceMappingURL=rowToText.d.ts.map

package/esm/methods/rowToText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowToText.d.ts","sourceRoot":"","sources":["../../src/methods/rowToText.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,MAAM,QAkClB"}

package/esm/methods/rowToText.js

@@ -0,0 +1,27 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import assertNewColumns from "../helpers/assertNewColumns.js";
+import queueOp from "../helpers/queueOp.js";
+export default function rowToText(simpleTable, columns, newColumn) {
+    columns = [...columns];
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "rowToText()",
+        parameters: { columns, newColumn },
+        needsSchema: true,
+        values: columns.flatMap((col, i) => [
+            `${i === 0 ? "" : "\n\n"}${col}:\n`,
+            "Unknown",
+        ]),
+        buildSelect: (input, allTypes) => {
+            assertNewColumns(allTypes, [newColumn], "rowToText()");
+            for (const col of columns) {
+                if (allTypes[col] !== "VARCHAR") {
+                    throw new Error(`The column ${col} is of type ${allTypes[col]}. The rowToText() method only works with string columns. Please convert the column to string first with the .convert() method.`);
+                }
+            }
+            const parts = columns.map((col) => `? || COALESCE(${quoteIdentifier(col)}, ?)`);
+            const concatenatedExpression = parts.join(" || ");
+            return `SELECT *, CAST(${concatenatedExpression} AS VARCHAR) AS ${quoteIdentifier(newColumn)} FROM ${input}`;
+        },
+    });
+}

package/esm/methods/sample.d.ts

@@ -0,0 +1,5 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function sample(simpleTable: SimpleTable, count: number | string, options?: {
+    seed?: number;
+}): void;
+//# sourceMappingURL=sample.d.ts.map

package/esm/methods/sample.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample.d.ts","sourceRoot":"","sources":["../../src/methods/sample.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,MAAM,CAC5B,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,GAAE;IACP,IAAI,CAAC,EAAE,MAAM,CAAC;CACV,QAoBP"}

package/esm/methods/sample.js

@@ -0,0 +1,16 @@
+import queueOp from "../helpers/queueOp.js";
+export default function sample(simpleTable, count, options = {}) {
+    options = { ...options };
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "sample()",
+        parameters: { count, options },
+        needsSchema: false,
+        // Seeded reservoir sampling returns a stable row order from a materialized
+        // table, but DuckDB can emit those rows in a different order when the
+        // sampler consumes a file scan directly.
+        requiresMaterializedInput: typeof options.seed === "number",
+        preservesSchema: true,
+        buildSelect: (input) => `SELECT * FROM ${input} USING SAMPLE RESERVOIR(${typeof count === "number" ? `${count} ROWS` : count})${typeof options.seed === "number" ? ` REPEATABLE(${options.seed})` : ""}`,
+    });
+}

package/esm/methods/selectColumns.d.ts

@@ -0,0 +1,3 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function selectColumns(simpleTable: SimpleTable, columns: string | string[]): void;
+//# sourceMappingURL=selectColumns.d.ts.map

package/esm/methods/selectColumns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectColumns.d.ts","sourceRoot":"","sources":["../../src/methods/selectColumns.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,aAAa,CACnC,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,QAsB3B"}

package/esm/methods/selectColumns.js

@@ -0,0 +1,19 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import stringToArray from "../helpers/stringToArray.js";
+import queueOp from "../helpers/queueOp.js";
+export default function selectColumns(simpleTable, columns) {
+    columns = Array.isArray(columns) ? [...columns] : columns;
+    const selectedColumns = stringToArray(columns);
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "selectColumns()",
+        parameters: { columns },
+        needsSchema: false,
+        outputSchema: (types) => Object.fromEntries(selectedColumns
+            .filter((column) => types[column] !== undefined)
+            .map((column) => [column, types[column]])),
+        buildSelect: (input) => `SELECT ${selectedColumns
+            .map((d) => `${quoteIdentifier(d)}`)
+            .join(", ")} FROM ${input}`,
+    });
+}

package/esm/methods/selectRows.d.ts

@@ -0,0 +1,6 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function selectRows(simpleTable: SimpleTable, count: number | string, options?: {
+    offset?: number;
+    outputTable?: string | boolean;
+}): SimpleTable;
+//# sourceMappingURL=selectRows.d.ts.map

package/esm/methods/selectRows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectRows.d.ts","sourceRoot":"","sources":["../../src/methods/selectRows.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,UAAU,CAChC,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAO,GAChE,WAAW,CAoCb"}