Function API: inspect, check, readRows

Input is File | Blob | ArrayBuffer | Uint8Array (Node's Buffer included). File path strings are not accepted. The names are the same on the CDN global Excel82.… and from import { … } from '82excel'.

import { check, readRows, rulesFromTemplate, makeTemplate } from '82excel';

const rules = await rulesFromTemplate(templateBytes);          // { headers: [...], columns: 3 }
const result = await check(file, { ...rules, rows: { min: 1 } });
const { rows } = await readRows(file);
const blob = makeTemplate(['Name', 'Phone', 'Amount'], 'xlsx');

inspect(file, opts?)

inspect(file, { headerRow?, previewRows?, locale?, telemetry?, delimiter?, maxUncompressedSize? }) walks every sheet and returns { file, meta?, csv?, sheets[], definedNames, issues }. Each sheet has name, index, hidden, protected, range, columnCount, rowCount, columns, columnTypes, emptyCells, errorCells, mergedCells, hiddenRows, hiddenColumns, formulaCount, personalData?, preview. Password-protected and corrupted files fill issues instead of throwing. A column holding only error cells (#DIV/0! …) has the column type 'empty'; error cells are counted in errorCells.

const info = await Excel82.inspect(file);
info.file;          // { name, size, format, extension, encrypted, hasMacros }
info.sheets[0];     // { name, columns, columnTypes, rowCount, preview, … }
info.issues;        // [{ code: 'PASSWORD_PROTECTED', severity: 'error', message }]

check(file, rules)

Returns { ok, errors, warnings, info, rows? }. Rules: headers, columns, rows: { min, max }, sheet, headerRow, maxSize, maxUncompressedSize, delimiter, accept, locale, readRows, maxCells, previewRows, failOn, telemetry.

• Checks the first sheet by default and collects every problem (unless the file cannot be read at all).
• Headers are compared NFC-normalized and in order; a hint is added when only spacing or case differs.
• Warnings do not affect ok; warnings listed in failOn, e.g. failOn: ['PERSONAL_DATA'], become errors.
• It throws only for invalid arguments.

readRows(file, opts?)

readRows(file, { sheet?, headerRow?, locale?, delimiter?, maxUncompressedSize?, maxCells? }) returns { rows, columns, issues }. Rows are {header: value} objects without a prototype (a __proto__ header is safe). Repeated headers get numbered (Name_2) with a DUPLICATE_HEADER warning. Lines with no values are skipped (but counted in rowCount).

rulesFromTemplate, makeTemplate

• rulesFromTemplate(file, { sheet?, headerRow?, delimiter?, maxUncompressedSize? }): builds { headers, columns } from the header row of a template file.
• makeTemplate(headers, 'csv' | 'xlsx', sheetName?): an empty template with just the headers, as a Blob (CSV with a UTF-8 BOM).
• registerLocale(name, messages) registers a message set; VERSION is the library version.

Shared options and limits

Cells outside Excel's grid (xlsx 1,048,576 rows × 16,384 columns, xls 65,536 × 256) are ignored. CSV encodings UTF-8 (with or without BOM), UTF-16 and EUC-KR (CP949) are detected automatically.

Codes and messages are in Error codes.