@ricsam/excel-to-formula-engine 0.1.0 → 0.2.0

package/dist/types/src/csv/parse.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Delimited-text parsing: CSV, TSV, and the semicolon-separated files a
+ * comma-decimal locale produces.
+ *
+ * Follows RFC 4180 for quoting — a field wrapped in double quotes may contain
+ * the delimiter, line breaks, and doubled quotes standing for one — because that
+ * is what every spreadsheet writes and the naive `split(",")` gets wrong on the
+ * first address field it meets.
+ */
+/** Delimiters worth guessing between. */
+export declare const CANDIDATE_DELIMITERS: readonly [",", "\t", ";", "|"];
+export type Delimiter = string;
+/**
+ * Split delimited text into rows of raw string fields.
+ *
+ * Values keep the exact text they had: trimming and type conversion are separate
+ * decisions made later, where the caller's options are in scope.
+ */
+export declare function parseDelimitedText(text: string, delimiter: Delimiter): string[][];
+/**
+ * Guess the delimiter from the text itself.
+ *
+ * Scores each candidate on how *consistently* it splits the first several lines
+ * rather than on how often it appears: prose full of commas scores badly because
+ * its lines disagree about the field count, while a two-column TSV scores
+ * perfectly on one tab per line. Quoted sections are skipped, so a comma inside
+ * `"Smith, J"` never votes for comma.
+ *
+ * Falls back to comma, which is both the commonest and the least surprising
+ * thing to be wrong about.
+ */
+export declare function detectDelimiter(text: string, candidates?: readonly string[]): Delimiter;
+/**
+ * Strip a UTF-8 byte-order mark.
+ *
+ * Excel writes one on every CSV it exports, and left in place it becomes part of
+ * the first header cell — where it is invisible, so the column looks right and
+ * every lookup against its name silently misses.
+ */
+export declare function stripBom(text: string): string;

package/dist/types/src/translate/formula.d.ts

@@ -12,6 +12,15 @@ import type { Diagnostic } from "../types";
 export interface TranslateFormulaOptions {
     sheetName?: string;
     cellReference?: string;
+    /**
+     * The table the formula's own cell sits inside, when it sits inside one.
+     *
+     * Excel drops the table name from a current-row reference that points at the
+     * table the formula is already in, so `[@Payload]` is what the author sees.
+     * Supplying it here reproduces that, and leaving it out keeps the name — which
+     * is still correct, just more verbose than Excel would be.
+     */
+    containingTableName?: string;
 }
 export interface TranslatedFormula {
     /** Engine formula text, including the leading `=`. */
@@ -35,3 +44,8 @@ export declare function findUnsupportedFunctions(formulaBody: string): string[];
  * (`$A$1`) stay put.
  */
 export declare function offsetFormulaReferences(formulaBody: string, deltaCols: number, deltaRows: number): string;
+/**
+ * `Table[[#This Row],[Col]]` → `Table[@Col]`, or `[@Col]` when the formula is
+ * already inside that table.
+ */
+export declare function contractThisRowReferences(formulaBody: string, containingTableName?: string): string;

package/dist/types/src/types.d.ts

@@ -21,7 +21,9 @@ export type DiagnosticCode =
 /** A table could not be created. */
  | "skipped-table"
 /** A sheet was skipped, for example a chart sheet. */
- | "skipped-sheet";
+ | "skipped-sheet"
+/** A delimiter had to be guessed from the text. */
+ | "guessed-delimiter";
 export interface Diagnostic {
     severity: DiagnosticSeverity;
     code: DiagnosticCode;
@@ -113,6 +115,45 @@ export interface ConvertOptions {
      */
     sheets?: string[];
 }
+/**
+ * Options for reading delimited text (CSV, TSV).
+ *
+ * The parsing defaults match what a spreadsheet does with the same file, on the
+ * grounds that the file usually came out of one.
+ *
+ * There is deliberately no option to keep `=`-leading fields as text. The engine
+ * stores a formula as a string beginning with `=` and has no escape for text
+ * that merely looks like one, so such an option could only be honoured by
+ * altering the value — which is worse than not offering it.
+ */
+export interface CsvConvertOptions {
+    /** Name for the single sheet the file becomes. @default "Sheet1" */
+    sheetName?: string;
+    /** Recorded in workbook metadata. */
+    fileName?: string;
+    /**
+     * Field separator. Detected from the text when omitted, which is the right
+     * choice for `.csv` — the extension says nothing about the separator, and a
+     * comma-decimal locale writes semicolons.
+     */
+    delimiter?: string;
+    /**
+     * Convert plain decimals to numbers. Leading-zero strings and integers too
+     * long to survive as floats are kept as text either way.
+     * @default true
+     */
+    parseNumbers?: boolean;
+    /** Convert `TRUE` / `FALSE` (any case) to booleans. @default true */
+    parseBooleans?: boolean;
+    /**
+     * Strip surrounding whitespace from every field.
+     *
+     * Off by default because the whitespace may be data, and a quoted field that
+     * carries it meant to.
+     * @default false
+     */
+    trimFields?: boolean;
+}
 export interface ConvertResult {
     data: ExcelWorkbookData;
     diagnostics: Diagnostic[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/excel-to-formula-engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Convert an Excel .xlsx file into FormulaEngine WorkbookData, in the browser",
   "type": "module",
   "module": "./dist/index.mjs",