pdf2sheets-helper 1.0.0

package/README.md

@@ -0,0 +1,143 @@
+# pdf2sheets-helper
+
+Utility helpers for working with PDF table data in spreadsheet workflows. Clean, detect headers, normalize numbers, and export to CSV -- everything you need after extracting a table from a PDF.
+
+## Install
+
+```bash
+npm install pdf2sheets-helper
+```
+
+## Usage
+
+```js
+const {
+  cleanTable,
+  detectHeaders,
+  toCSV,
+  normalizeNumbers,
+} = require("pdf2sheets-helper");
+```
+
+### cleanTable(rows)
+
+Trims whitespace from every cell and removes rows that are entirely empty. Useful for cleaning up raw data after extracting a table from a PDF to Excel or Google Sheets.
+
+```js
+const raw = [
+  ["  Name ", " Revenue "],
+  ["", "   "],
+  [" Acme Corp", " $1,200 "],
+];
+
+const cleaned = cleanTable(raw);
+// [
+//   ["Name", "Revenue"],
+//   ["Acme Corp", "$1,200"]
+// ]
+```
+
+### detectHeaders(rows)
+
+Checks whether the first row looks like a header row (all non-numeric strings). Returns an object with `hasHeaders` and `headers` fields.
+
+```js
+const result = detectHeaders([
+  ["Product", "Price", "Quantity"],
+  ["Widget", "9.99", "50"],
+]);
+// { hasHeaders: true, headers: ["Product", "Price", "Quantity"] }
+
+const noHeaders = detectHeaders([
+  ["100", "200"],
+  ["300", "400"],
+]);
+// { hasHeaders: false, headers: null }
+```
+
+### toCSV(rows, delimiter?)
+
+Converts a 2D array to a CSV string with proper escaping (RFC 4180). Cells containing the delimiter, double-quotes, or newlines are automatically quoted.
+
+```js
+const csv = toCSV([
+  ["Name", "City"],
+  ["Alice", "New York"],
+  ['Bob "Builder"', "LA"],
+]);
+// Name,City
+// Alice,New York
+// "Bob ""Builder""",LA
+
+// Tab-separated output
+const tsv = toCSV([["A", "B"], ["1", "2"]], "\t");
+// A\tB\n1\t2
+```
+
+### normalizeNumbers(rows, columns?)
+
+Strips currency symbols (`$`, `EUR`, `GBP`, etc.), thousands separators, and percent signs from specified columns, converting the values to JavaScript numbers. Handles both US (`1,234.56`) and European (`1.234,56`) formats.
+
+If `columns` is omitted, all columns are processed.
+
+```js
+const data = [
+  ["Item", "$1,200.50", "15%"],
+  ["Widget", "EUR 300", "8%"],
+];
+
+const normalized = normalizeNumbers(data, [1, 2]);
+// [
+//   ["Item", 1200.5, 15],
+//   ["Widget", 300, 8]
+// ]
+```
+
+## Putting It All Together
+
+A typical workflow for processing a PDF table to Google Sheets or Excel:
+
+```js
+const { cleanTable, detectHeaders, normalizeNumbers, toCSV } = require("pdf2sheets-helper");
+
+// Raw data extracted from a PDF
+const raw = [
+  ["  Product ", " Price ", " Qty "],
+  ["", "", ""],
+  [" Widget A", " $1,499.00 ", " 25 "],
+  [" Widget B", " $320.50 ", " 100 "],
+];
+
+// Step 1: Clean whitespace and empty rows
+const cleaned = cleanTable(raw);
+
+// Step 2: Check for headers
+const { hasHeaders, headers } = detectHeaders(cleaned);
+console.log("Headers:", headers);
+// ["Product", "Price", "Qty"]
+
+// Step 3: Normalize numeric columns
+const dataRows = hasHeaders ? cleaned.slice(1) : cleaned;
+const normalized = normalizeNumbers(dataRows, [1, 2]);
+
+// Step 4: Export to CSV
+const output = hasHeaders ? [headers, ...normalized] : normalized;
+console.log(toCSV(output));
+// Product,Price,Qty
+// Widget A,1499,25
+// Widget B,320.5,100
+```
+
+## Browser-Based PDF Table Extraction
+
+These helpers assume you already have table data as a 2D array. If you need to extract tables from PDFs first, try [pdf2sheets](https://pdf2sheets.app) -- a browser extension that lets you extract tables from any PDF directly into Google Sheets or Excel. No uploads, no server processing; everything runs locally in your browser.
+
+It handles multi-page tables, merged cells, and messy PDF layouts so you can skip the manual copy-paste step entirely.
+
+## Keywords
+
+extract table from pdf to excel, pdf table to google sheets, pdf table extraction, convert pdf table to csv, pdf to spreadsheet, pdf data extraction
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,185 @@
+/**
+ * pdf2sheets-helper
+ *
+ * Utility helpers for working with PDF table data in spreadsheet workflows.
+ * Use these functions to clean, transform, and export 2D arrays of table data
+ * extracted from PDFs.
+ *
+ * https://pdf2sheets.app
+ */
+
+/**
+ * Clean a 2D table array by trimming whitespace from every cell
+ * and removing rows that are entirely empty.
+ *
+ * @param {string[][]} rows - 2D array of table data
+ * @returns {string[][]} Cleaned table with trimmed cells and no empty rows
+ *
+ * @example
+ *   cleanTable([["  Name ", " Age"], ["", "  "], ["Alice", "30"]])
+ *   // => [["Name", "Age"], ["Alice", "30"]]
+ */
+function cleanTable(rows) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError("cleanTable expects a 2D array of rows");
+  }
+
+  return rows
+    .map((row) => row.map((cell) => String(cell).trim()))
+    .filter((row) => row.some((cell) => cell.length > 0));
+}
+
+/**
+ * Detect whether the first row of a table looks like a header row.
+ *
+ * A row is considered a header when every cell is a non-numeric string
+ * (i.e. none of the cells parse as a finite number). This is a simple
+ * heuristic that works well for most PDF-extracted tables.
+ *
+ * @param {string[][]} rows - 2D array of table data (at least one row)
+ * @returns {{ hasHeaders: boolean, headers: string[] | null }}
+ *
+ * @example
+ *   detectHeaders([["Product", "Price"], ["Widget", "9.99"]])
+ *   // => { hasHeaders: true, headers: ["Product", "Price"] }
+ *
+ *   detectHeaders([["100", "200"], ["300", "400"]])
+ *   // => { hasHeaders: false, headers: null }
+ */
+function detectHeaders(rows) {
+  if (!Array.isArray(rows) || rows.length === 0) {
+    return { hasHeaders: false, headers: null };
+  }
+
+  const firstRow = rows[0];
+
+  // If every cell in the first row is non-empty and non-numeric, treat it
+  // as a header row.
+  const looksLikeHeaders = firstRow.every((cell) => {
+    const trimmed = String(cell).trim();
+    return trimmed.length > 0 && !isFinite(Number(trimmed));
+  });
+
+  return {
+    hasHeaders: looksLikeHeaders,
+    headers: looksLikeHeaders ? firstRow.map((c) => String(c).trim()) : null,
+  };
+}
+
+/**
+ * Convert a 2D array to a CSV string.
+ *
+ * Cells that contain the delimiter, a double-quote, or a newline are
+ * wrapped in double-quotes. Existing double-quotes inside cells are
+ * escaped by doubling them (RFC 4180).
+ *
+ * @param {string[][]} rows - 2D array of table data
+ * @param {string} [delimiter=","] - Column delimiter (e.g. "," or "\t")
+ * @returns {string} CSV-formatted string
+ *
+ * @example
+ *   toCSV([["Name", "City"], ["Alice", "New York"]])
+ *   // => 'Name,City\nAlice,New York'
+ *
+ *   toCSV([["A", "B"], ["1", "2"]], "\t")
+ *   // => 'A\tB\n1\t2'
+ */
+function toCSV(rows, delimiter) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError("toCSV expects a 2D array of rows");
+  }
+
+  const sep = delimiter != null ? delimiter : ",";
+
+  return rows
+    .map((row) =>
+      row
+        .map((cell) => {
+          const value = String(cell);
+
+          // Wrap in quotes if the value contains the delimiter, a quote, or a newline
+          if (
+            value.includes(sep) ||
+            value.includes('"') ||
+            value.includes("\n") ||
+            value.includes("\r")
+          ) {
+            return '"' + value.replace(/"/g, '""') + '"';
+          }
+
+          return value;
+        })
+        .join(sep)
+    )
+    .join("\n");
+}
+
+/**
+ * Strip currency symbols and thousands separators from numeric-looking cells,
+ * converting them to actual numbers.
+ *
+ * Only the columns listed in the `columns` array are processed. All other
+ * columns are left untouched. If `columns` is omitted, every column is
+ * processed.
+ *
+ * Recognized formats: "$1,234.56", "1.234,56" (European), "USD 100", "100%".
+ *
+ * @param {string[][]} rows - 2D array of table data
+ * @param {number[]} [columns] - Zero-based column indices to normalize.
+ *   If omitted, all columns are processed.
+ * @returns {(string|number)[][]} New table with normalized numeric values
+ *
+ * @example
+ *   normalizeNumbers([["Item", "$1,200.50"], ["Widget", "$300"]], [1])
+ *   // => [["Item", 1200.5], ["Widget", 300]]
+ */
+function normalizeNumbers(rows, columns) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError("normalizeNumbers expects a 2D array of rows");
+  }
+
+  // Currency symbols and prefixes/suffixes to strip
+  const currencyPattern = /^[\s$\u20AC\u00A3\u00A5]*(.*?)[\s%]*$/; // $, EUR, GBP, JPY
+  const prefixPattern = /^(?:USD|EUR|GBP|JPY|CAD|AUD)[\s]*/i;
+
+  return rows.map((row) =>
+    row.map((cell, colIndex) => {
+      // Skip columns not in the target list
+      if (columns != null && !columns.includes(colIndex)) {
+        return cell;
+      }
+
+      let value = String(cell).trim();
+
+      // Remove common currency prefixes like "USD "
+      value = value.replace(prefixPattern, "");
+
+      // Remove currency symbols and surrounding whitespace
+      const symbolMatch = value.match(currencyPattern);
+      if (symbolMatch) {
+        value = symbolMatch[1];
+      }
+
+      // Detect European format: "1.234,56" (dot as thousands, comma as decimal)
+      if (/^\d{1,3}(\.\d{3})+(,\d+)?$/.test(value)) {
+        value = value.replace(/\./g, "").replace(",", ".");
+      } else {
+        // Standard format: remove commas used as thousands separators
+        value = value.replace(/,/g, "");
+      }
+
+      // Remove trailing percent sign
+      value = value.replace(/%$/, "");
+
+      const num = Number(value);
+      return isFinite(num) && value.length > 0 ? num : cell;
+    })
+  );
+}
+
+module.exports = {
+  cleanTable,
+  detectHeaders,
+  toCSV,
+  normalizeNumbers,
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "pdf2sheets-helper",
+  "version": "1.0.0",
+  "description": "Utility helpers for working with PDF table data in spreadsheet workflows",
+  "main": "index.js",
+  "homepage": "https://pdf2sheets.app",
+  "keywords": [
+    "pdf",
+    "google-sheets",
+    "excel",
+    "table-extraction",
+    "spreadsheet",
+    "pdf-to-excel",
+    "csv"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sgcaptainworks-arch/pdf2sheets-helper"
+  },
+  "author": "pdf2sheets",
+  "files": [
+    "index.js"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}