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

package/src/methods/flipCoordinates.ts

@@ -0,0 +1,25 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import findGeoColumnFromSchema from "../helpers/findGeoColumnFromSchema.ts";
+import queueOp from "../helpers/queueOp.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+
+export default function flipCoordinates(simpleTable: SimpleTable, column?: string) {
+  queueOp(simpleTable, {
+    kind: "fusable",
+    method: "flipCoordinates()",
+    parameters: { column },
+    needsSchema: true,
+    needsSpatial: true,
+    // The cast pins the geometry column back to its existing type, so the
+    // schema is unchanged.
+    preservesSchema: true,
+    buildSelect: (input, types) => {
+      const col = column ?? findGeoColumnFromSchema(types, "flipCoordinates()", simpleTable.name);
+      // The schema type carries the projection (e.g. GEOMETRY('EPSG:4326')),
+      // so the cast keeps it on the new geometries.
+      return `SELECT * REPLACE (ST_FlipCoordinates(${quoteIdentifier(col)})::${
+        types[col]
+      } AS ${quoteIdentifier(col)}) FROM ${input}`;
+    },
+  });
+}

package/src/methods/fuzzyClean.ts

@@ -0,0 +1,142 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import { DuckDBListValue } from "@duckdb/node-api";
+import type SimpleTable from "../class/SimpleTable.ts";
+import mergeOptions from "../helpers/mergeOptions.ts";
+import queryDB from "../helpers/queryDB.ts";
+import queueOp from "../helpers/queueOp.ts";
+import buildFuzzyMatchSql from "../helpers/buildFuzzyMatchSql.ts";
+import selectFuzzyReplacements, { type FuzzyPair } from "../helpers/selectFuzzyReplacements.ts";
+
+export default function fuzzyClean(
+  table: SimpleTable,
+  column: string,
+  newColumn: string,
+  threshold: number,
+  options: {
+    method?: "ratio" | "partial_ratio" | "token_sort_ratio" | "token_set_ratio";
+    strategy?: "mostCommon" | "longestString" | "shortestString" | "mostCentral" | "maxScore";
+    prefilterPrefixLength?: number;
+  } = {},
+): void {
+  // This implementation clusters fuzzy pairs in JS and writes the mapping
+  // back to DuckDB, so it executes as a barrier.
+  options = structuredClone(options);
+  queueOp(table, {
+    kind: "barrier",
+    method: "fuzzyClean()",
+    parameters: { column, newColumn, threshold, options },
+    execute: () => executeFuzzyClean(table, column, newColumn, threshold, options),
+  });
+}
+
+async function executeFuzzyClean(
+  table: SimpleTable,
+  column: string,
+  newColumn: string,
+  threshold: number,
+  options: {
+    method?: "ratio" | "partial_ratio" | "token_sort_ratio" | "token_set_ratio";
+    strategy?: "mostCommon" | "longestString" | "shortestString" | "mostCentral" | "maxScore";
+    prefilterPrefixLength?: number;
+  } = {},
+): Promise<void> {
+  const method = options.method ?? "ratio";
+  const strategy = options.strategy ?? "mostCommon";
+  const { scoreExpression, condition } = buildFuzzyMatchSql(
+    "a.value",
+    "b.value",
+    method,
+    threshold,
+    { prefilterPrefixLength: options.prefilterPrefixLength },
+  );
+
+  // Compute fuzzy pairs and embed counts for both sides. Only values that
+  // appear in at least one pair above the threshold can be normalized —
+  // singletons need no processing at all.
+  const pairsData = (await queryDB(
+    table,
+    `INSTALL rapidfuzz FROM community; LOAD rapidfuzz;
+     WITH uniques AS (
+       SELECT ${quoteIdentifier(column)} AS value, COUNT(*) AS cnt
+       FROM ${quoteIdentifier(table.name)}
+       WHERE ${quoteIdentifier(column)} IS NOT NULL
+       GROUP BY ${quoteIdentifier(column)}
+     )
+     SELECT
+       a.value AS left_value,
+       b.value AS right_value,
+       a.cnt   AS left_cnt,
+       b.cnt   AS right_cnt,
+       ${scoreExpression} AS score
+     FROM uniques a
+     JOIN uniques b
+       ON ${condition}
+       AND a.value < b.value`,
+    mergeOptions(table, {
+      table: table.name,
+      method: "fuzzyClean()",
+      parameters: { column, newColumn, threshold, options },
+      returnData: true,
+    }),
+  )) as FuzzyPair[] | null;
+
+  const pairs = pairsData ?? [];
+  if (pairs.length === 0) {
+    if (newColumn !== column) {
+      await queryDB(
+        table,
+        `ALTER TABLE ${quoteIdentifier(table.name)} ADD ${quoteIdentifier(newColumn)} VARCHAR;
+         UPDATE ${quoteIdentifier(table.name)}
+           SET ${quoteIdentifier(newColumn)} = ${quoteIdentifier(column)};`,
+        mergeOptions(table, {
+          table: table.name,
+          method: "fuzzyClean()",
+          parameters: { column, newColumn, threshold, options },
+        }),
+      );
+    }
+    return;
+  }
+
+  const replacement = selectFuzzyReplacements(pairs, strategy);
+
+  if (replacement.size === 0) return;
+
+  // Two bound lists keep the SQL and parameter count fixed as the mapping
+  // grows. Side-by-side UNNEST zips the equally sized lists into mapping rows,
+  // which DuckDB can hash-join to the original table.
+  const values = [
+    new DuckDBListValue([...replacement.keys()]),
+    new DuckDBListValue([...replacement.values()]),
+  ];
+  const mapping = `WITH mapping(original, canonical) AS (
+    SELECT UNNEST(?::VARCHAR[]), UNNEST(?::VARCHAR[])
+  )`;
+
+  const query =
+    newColumn !== column
+      ? `ALTER TABLE ${quoteIdentifier(table.name)} ADD ${quoteIdentifier(newColumn)} VARCHAR;
+       UPDATE ${quoteIdentifier(table.name)}
+         SET ${quoteIdentifier(newColumn)} = ${quoteIdentifier(column)};
+       ${mapping}
+       UPDATE ${quoteIdentifier(table.name)}
+         SET ${quoteIdentifier(newColumn)} = m.canonical
+         FROM mapping m
+         WHERE ${quoteIdentifier(table.name)}.${quoteIdentifier(newColumn)} = m.original`
+      : `${mapping}
+       UPDATE ${quoteIdentifier(table.name)}
+         SET ${quoteIdentifier(column)} = m.canonical
+         FROM mapping m
+         WHERE ${quoteIdentifier(table.name)}.${quoteIdentifier(column)} = m.original`;
+
+  await queryDB(
+    table,
+    query,
+    mergeOptions(table, {
+      table: table.name,
+      method: "fuzzyClean()",
+      parameters: { column, newColumn, options },
+      values,
+    }),
+  );
+}

package/src/methods/fuzzyJoin.ts

@@ -0,0 +1,267 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+import getIdenticalColumns from "../helpers/getIdenticalColumns.ts";
+import mergeOptions from "../helpers/mergeOptions.ts";
+import queryDB from "../helpers/queryDB.ts";
+import queueOp from "../helpers/queueOp.ts";
+import assertSameDatabase from "../helpers/assertSameDatabase.ts";
+import buildFuzzyMatchSql, { type FuzzyMethod } from "../helpers/buildFuzzyMatchSql.ts";
+
+export default function fuzzyJoin(
+  leftTable: SimpleTable,
+  rightTable: SimpleTable,
+  leftColumn: string,
+  rightColumn: string,
+  threshold: number,
+  options: {
+    method?: "ratio" | "partial_ratio" | "token_sort_ratio" | "token_set_ratio";
+    similarityColumn?: string;
+    outputTable?: string | boolean;
+    prefilterPrefixLength?: number;
+  } = {},
+): SimpleTable {
+  assertSameDatabase(leftTable.sdb, [rightTable], "fuzzyJoin()");
+  options = structuredClone(options);
+  // This validation doesn't need the database, so it stays at call time.
+  if (leftColumn === rightColumn) {
+    throw new Error(
+      `The leftColumn and rightColumn have the same name ${quoteIdentifier(
+        leftColumn,
+      )}. Rename one of them before doing the fuzzy join.`,
+    );
+  }
+
+  // The output table instance is created at call time so it can be returned
+  // synchronously and chained on right away.
+  const outputTable =
+    typeof options.outputTable === "string"
+      ? leftTable.sdb.newTable(options.outputTable)
+      : leftTable;
+
+  queueOp(outputTable, {
+    kind: "barrier",
+    method: "fuzzyJoin()",
+    parameters: {
+      leftColumn,
+      rightColumn,
+      rightTable: rightTable.name,
+      threshold,
+      options,
+    },
+    execute: () =>
+      executeFuzzyJoin(
+        leftTable,
+        rightTable,
+        outputTable,
+        leftColumn,
+        rightColumn,
+        threshold,
+        options,
+      ),
+  });
+
+  return outputTable;
+}
+
+async function executeFuzzyJoin(
+  leftTable: SimpleTable,
+  rightTable: SimpleTable,
+  outputTable: SimpleTable,
+  leftColumn: string,
+  rightColumn: string,
+  threshold: number,
+  options: {
+    method?: "ratio" | "partial_ratio" | "token_sort_ratio" | "token_set_ratio";
+    similarityColumn?: string;
+    prefilterPrefixLength?: number;
+  },
+): Promise<void> {
+  const leftCols = await leftTable.getColumns();
+  const rightCols = await rightTable.getColumns();
+  const identicalColumns = getIdenticalColumns(leftCols, rightCols);
+
+  // Any column shared between both tables — other than rightColumn (whose
+  // potential _1 duplicate we clean up) — would produce ambiguous output.
+  const identicalColumnsForError = identicalColumns.filter((d) => d !== rightColumn);
+  if (identicalColumnsForError.length > 0) {
+    if (identicalColumnsForError.length === 1) {
+      throw new Error(
+        `The tables have columns with identical names. Rename or remove "${
+          identicalColumnsForError[0]
+        }" in one of the two tables before doing the fuzzy join.`,
+      );
+    } else {
+      throw new Error(
+        `The tables have columns with identical names. Rename or remove ${identicalColumnsForError
+          .map((d) => `${quoteIdentifier(d)}`)
+          .join(", ")} in one of the two tables before doing the fuzzy join.`,
+      );
+    }
+  }
+
+  const method = options.method ?? "ratio";
+  const similarityColumn = options.similarityColumn;
+  const queryOptions = mergeOptions(leftTable, {
+    table: outputTable.name,
+    method: "fuzzyJoin()",
+    parameters: {
+      leftColumn,
+      rightColumn,
+      rightTable: rightTable.name,
+      threshold,
+      options,
+    },
+  });
+  const deduplicate = await shouldDeduplicateFuzzyJoin(
+    leftTable,
+    rightTable,
+    leftColumn,
+    rightColumn,
+    queryOptions,
+  );
+
+  // The right table's copy of a column shared with the left table (only
+  // rightColumn can be shared, checked above) is excluded from the SELECT
+  // directly, instead of dropping its _1 duplicate with a rewrite after the
+  // join.
+  const rightSelect = rightCols
+    .filter((d) => !leftCols.includes(d))
+    .map((d) => `${quoteIdentifier(rightTable.name)}.${quoteIdentifier(d)}`)
+    .join(", ");
+
+  const sql =
+    `INSTALL rapidfuzz FROM community; LOAD rapidfuzz;\n` +
+    fuzzyJoinQuery(
+      leftTable.name,
+      leftColumn,
+      rightTable.name,
+      rightColumn,
+      method,
+      threshold,
+      outputTable.name,
+      similarityColumn,
+      rightSelect,
+      options.prefilterPrefixLength,
+      deduplicate,
+    );
+
+  await queryDB(leftTable, sql, queryOptions);
+}
+
+async function shouldDeduplicateFuzzyJoin(
+  leftTable: SimpleTable,
+  rightTable: SimpleTable,
+  leftColumn: string,
+  rightColumn: string,
+  queryOptions: Parameters<typeof queryDB>[2],
+): Promise<boolean> {
+  const left = quoteIdentifier(leftTable.name);
+  const right = quoteIdentifier(rightTable.name);
+  const counts = (await queryDB(
+    leftTable,
+    `SELECT (SELECT COUNT(*) FROM ${left}) AS left_count,
+      (SELECT COUNT(*) FROM ${right}) AS right_count`,
+    { ...queryOptions, returnData: true },
+  ))![0];
+  const leftCount = Number(counts.left_count);
+  const rightCount = Number(counts.right_count);
+  const comparisons = leftCount * rightCount;
+  // Avoid distinct scans for small joins and short lookup tables. For larger
+  // joins, require at least a twofold reduction to pay for grouping and rejoining.
+  if (comparisons < 100_000 || Math.min(leftCount, rightCount) < 32) {
+    return false;
+  }
+  const distinct = (await queryDB(
+    leftTable,
+    `SELECT
+      (SELECT COUNT(DISTINCT ENCODE(${quoteIdentifier(leftColumn)})) FROM ${left}) AS left_count,
+      (SELECT COUNT(DISTINCT ENCODE(${quoteIdentifier(
+        rightColumn,
+      )})) FROM ${right}) AS right_count`,
+    { ...queryOptions, returnData: true },
+  ))![0];
+  return Number(distinct.left_count) * Number(distinct.right_count) <= comparisons / 2;
+}
+
+function fuzzyJoinQuery(
+  leftTable: string,
+  leftColumn: string,
+  rightTable: string,
+  rightColumn: string,
+  method: FuzzyMethod,
+  threshold: number,
+  outputTable: string,
+  similarityColumn: string | undefined,
+  rightSelect: string,
+  prefilterPrefixLength?: number,
+  deduplicate = false,
+) {
+  const leftExpression = `${quoteIdentifier(leftTable)}.${quoteIdentifier(leftColumn)}`;
+  const rightExpression = `${quoteIdentifier(rightTable)}.${quoteIdentifier(rightColumn)}`;
+  const { scoreExpression, condition } = buildFuzzyMatchSql(
+    leftExpression,
+    rightExpression,
+    method,
+    threshold,
+    { decimals: 2, prefilterPrefixLength },
+  );
+
+  let cte = "";
+  let from = `FROM ${quoteIdentifier(leftTable)} LEFT JOIN ${quoteIdentifier(
+    rightTable,
+  )} ON ${condition}`;
+  let score = scoreExpression;
+  if (deduplicate) {
+    const matches = quoteIdentifier(
+      `__sda_fuzzy_matches_${crypto.randomUUID().replaceAll("-", "")}`,
+    );
+    const match = buildFuzzyMatchSql("l.value", "r.value", method, threshold, {
+      decimals: 2,
+      prefilterPrefixLength,
+    });
+    // Keep the original value's collation for prefix matching, but use byte
+    // keys for deduplication and expansion: fuzzy scores distinguish case even
+    // when an input column has a case-insensitive collation.
+    cte = `WITH ${matches} AS MATERIALIZED (
+      SELECT l.key AS left_key, r.key AS right_key,
+        ${match.scoreExpression} AS score
+      FROM (
+        SELECT DISTINCT ${quoteIdentifier(leftColumn)} AS value,
+          ENCODE(${quoteIdentifier(leftColumn)}) AS key
+        FROM ${quoteIdentifier(leftTable)}
+        WHERE ${quoteIdentifier(leftColumn)} IS NOT NULL
+      ) l
+      INNER JOIN (
+        SELECT DISTINCT ${quoteIdentifier(rightColumn)} AS value,
+          ENCODE(${quoteIdentifier(rightColumn)}) AS key
+        FROM ${quoteIdentifier(rightTable)}
+        WHERE ${quoteIdentifier(rightColumn)} IS NOT NULL
+      ) r ON ${match.condition}
+    )`;
+    from = `FROM ${quoteIdentifier(leftTable)}
+      LEFT JOIN ${matches} ON ENCODE(${leftExpression}) = ${matches}.left_key
+      LEFT JOIN ${quoteIdentifier(rightTable)}
+        ON ENCODE(${rightExpression}) = ${matches}.right_key`;
+    score = `${matches}.score`;
+  }
+
+  if (similarityColumn) {
+    return `CREATE OR REPLACE TABLE ${quoteIdentifier(outputTable)} AS
+${cte}
+SELECT * EXCLUDE ("_sda_score"), "_sda_score" AS ${quoteIdentifier(similarityColumn)}
+FROM (
+  SELECT ${quoteIdentifier(leftTable)}.*, ${rightSelect}, ${score} AS "_sda_score"
+  ${from}
+) _sda
+ORDER BY ${quoteIdentifier(leftColumn)}, "_sda_score" DESC;\n`;
+  }
+
+  return `CREATE OR REPLACE TABLE ${quoteIdentifier(outputTable)} AS
+${cte}
+SELECT *
+FROM (
+  SELECT ${quoteIdentifier(leftTable)}.*, ${rightSelect}
+  ${from}
+) _sda
+ORDER BY ${quoteIdentifier(leftColumn)}, ${quoteIdentifier(rightColumn)};\n`;
+}

package/src/methods/getBottom.ts

@@ -0,0 +1,42 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import mergeOptions from "../helpers/mergeOptions.ts";
+import queryDB from "../helpers/queryDB.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+
+export default async function getBottom(
+  simpleTable: SimpleTable,
+  count: number,
+  options: {
+    originalOrder?: boolean;
+    conditions?: string;
+  } = {},
+  method: "getBottom()" | "logBottom()" = "getBottom()",
+) {
+  const queryResult = await queryDB(
+    simpleTable,
+    `WITH "numberedRowsForGetBottom" AS (
+                SELECT *, row_number() OVER () as "rowNumberForGetBottom" FROM ${quoteIdentifier(
+                  simpleTable.name,
+                )}${options.conditions ? ` WHERE ${options.conditions}` : ""}
+            )
+            SELECT * FROM "numberedRowsForGetBottom" ORDER BY "rowNumberForGetBottom" DESC LIMIT ${count};`,
+    mergeOptions(simpleTable, {
+      table: simpleTable.name,
+      returnData: true,
+      method,
+      parameters: { count, options },
+    }),
+  );
+
+  if (!queryResult) {
+    throw new Error("The query did not return a result.");
+  }
+
+  const rowsRaw = queryResult.map((d) => {
+    delete d.rowNumberForGetBottom;
+    return d;
+  });
+  const rows = options.originalOrder ? rowsRaw.reverse() : rowsRaw;
+
+  return rows;
+}

package/src/methods/getBoundingBox.ts

@@ -0,0 +1,28 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import findGeoColumn from "../helpers/findGeoColumn.ts";
+import mergeOptions from "../helpers/mergeOptions.ts";
+import queryDB from "../helpers/queryDB.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+
+export default async function getBoundingBox(
+  simpleTable: SimpleTable,
+  column?: string,
+): Promise<[number, number, number, number]> {
+  const col = column ?? (await findGeoColumn(simpleTable, "getBoundingBox()"));
+  const result = (await queryDB(
+    simpleTable,
+    `SELECT
+                MIN(ST_YMin(${quoteIdentifier(col)})) AS minX,
+                MIN(ST_XMin(${quoteIdentifier(col)})) AS minY,
+                MAX(ST_YMax(${quoteIdentifier(col)})) AS maxX,
+                MAX(ST_XMax(${quoteIdentifier(col)})) AS maxY,
+            from ${quoteIdentifier(simpleTable.name)};`,
+    mergeOptions(simpleTable, {
+      table: simpleTable.name,
+      method: "getBoundingBox()",
+      parameters: { column },
+      returnData: true,
+    }),
+  )) as { minX: number; minY: number; maxX: number; maxY: number }[];
+  return [result[0].minY, result[0].minX, result[0].maxY, result[0].maxX];
+}

package/src/methods/getCharacterCount.ts

@@ -0,0 +1,29 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import mergeOptions from "../helpers/mergeOptions.ts";
+import queryDB from "../helpers/queryDB.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+import quoteQualifiedIdentifier from "../helpers/quoteQualifiedIdentifier.ts";
+
+export default async function getCharacterCount(SimpleTable: SimpleTable, column: string) {
+  const queryResult = await queryDB(
+    SimpleTable,
+    `SELECT CAST(SUM(LENGTH(${quoteQualifiedIdentifier(
+      SimpleTable.name,
+      column,
+    )})) AS BIGINT) AS total_chars FROM ${quoteIdentifier(SimpleTable.name)}`,
+    mergeOptions(SimpleTable, {
+      table: SimpleTable.name,
+      returnData: true,
+      method: "getCharacterCount()",
+      parameters: { column },
+    }),
+  );
+
+  if (!queryResult) {
+    throw new Error("The query did not return a result.");
+  }
+
+  const result = Number(queryResult[0].total_chars);
+
+  return result;
+}

package/src/methods/getColumns.ts

@@ -0,0 +1,25 @@
+import mergeOptions from "../helpers/mergeOptions.ts";
+import queryDB from "../helpers/queryDB.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+
+export default async function getColumns(simpleTable: SimpleTable) {
+  const queryResult = await queryDB(
+    simpleTable,
+    `DESCRIBE ${quoteIdentifier(simpleTable.name)}`,
+    mergeOptions(simpleTable, {
+      table: simpleTable.name,
+      returnData: true,
+      method: "getColumns()",
+      parameters: {},
+    }),
+  );
+
+  if (!queryResult) {
+    throw new Error("The query did not return a result.");
+  }
+
+  const columns = queryResult.map((d) => d.column_name) as string[];
+
+  return columns;
+}

package/src/methods/getData.ts

@@ -0,0 +1,42 @@
+import mergeOptions from "../helpers/mergeOptions.ts";
+import queryDB from "../helpers/queryDB.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import quoteQualifiedIdentifier from "../helpers/quoteQualifiedIdentifier.ts";
+
+export default async function getData(
+  simpleTable: SimpleTable,
+  options: {
+    columns?: string | string[];
+    conditions?: string;
+    limit?: number;
+  } = {},
+  method: "getData()" | "log()" = "getData()",
+) {
+  if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 0)) {
+    throw new Error("getData() limit must be an integer greater than or equal to 0.");
+  }
+  const columns = options.columns
+    ? typeof options.columns === "string"
+      ? [options.columns]
+      : options.columns
+    : undefined;
+  return (await queryDB(
+    simpleTable,
+    `SELECT ${
+      columns
+        ? columns.map((column) => quoteQualifiedIdentifier(simpleTable.name, column)).join(", ")
+        : "*"
+    } from ${quoteIdentifier(simpleTable.name)}${
+      options.conditions ? ` WHERE ${options.conditions}` : ""
+    }${options.limit === undefined ? "" : ` LIMIT ${options.limit}`}`,
+    mergeOptions(simpleTable, {
+      returnData: true,
+      table: simpleTable.name,
+      method,
+      parameters: { options },
+    }),
+  )) as {
+    [key: string]: unknown;
+  }[];
+}

package/src/methods/getDescription.ts

@@ -0,0 +1,30 @@
+import type SimpleTable from "../class/SimpleTable.ts";
+
+export default async function getDescription(simpleTable: SimpleTable) {
+  const types = await simpleTable.getTypes();
+  const columns = await simpleTable.getColumns();
+  const summaryForGetDescription = simpleTable.summarize({
+    columns: columns,
+    stats: ["count", "countDistinct", "countNull"],
+    datesToMs: true,
+    outputTable: "summaryForGetDescription",
+  });
+  const summaryData = await summaryForGetDescription.getData();
+
+  await summaryForGetDescription.removeTable();
+
+  // summarize adds the `column` output column only when it summarizes more than one
+  // column; for a single-column table the column name is already known.
+  const description = summaryData.map((d) => {
+    const column = columns.length > 1 ? (d.column as string) : columns[0];
+    return {
+      column,
+      type: types[column],
+      count: d["count"] as number,
+      unique: d["countDistinct"] as number,
+      null: d["countNull"] as number,
+    };
+  });
+
+  return description;
+}

package/src/methods/getFirstRow.ts

@@ -0,0 +1,31 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import mergeOptions from "../helpers/mergeOptions.ts";
+import queryDB from "../helpers/queryDB.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+
+export default async function getFirstRow(
+  simpleTable: SimpleTable,
+  options: {
+    conditions?: string;
+  } = {},
+) {
+  const queryResult = await queryDB(
+    simpleTable,
+    `SELECT * FROM ${quoteIdentifier(simpleTable.name)}${
+      options.conditions ? ` WHERE ${options.conditions}` : ""
+    } LIMIT 1`,
+    mergeOptions(simpleTable, {
+      table: simpleTable.name,
+      returnData: true,
+      method: "getFirstRow()",
+      parameters: { options },
+    }),
+  );
+  if (!queryResult) {
+    throw new Error("The query did not return a result.");
+  }
+
+  const result = queryResult[0];
+
+  return result ?? null;
+}