add a sheetjs adaptor #1718

Request

We want to build a sheetjs utility adaptor that wraps the SheetJS (xlsx) library to make it easy to work with Excel and other spreadsheet files inside OpenFn jobs.

Unlike most adaptors, this is not an HTTP client for an external API. It's a data-transformation utility adaptor (similar in spirit to common) that operates on spreadsheet content already available on state (e.g., a base64 string or buffer fetched by another adaptor, a webhook payload).

To start, this adaptor should:

1. Parse .xlsx/.xls/.csv file content (buffer or base64 string) into a SheetJS workbook and expose the sheet names.
2. Convert a worksheet into an array of JSON objects (XLSX.utils.sheet_to_json), with options for header rows, ranges, raw values, and date handling.
3. Convert a worksheet into a CSV string (XLSX.utils.sheet_to_csv).
4. Go the other way: build a worksheet/workbook from JSON data (XLSX.utils.json_to_sheet, XLSX.write) and output it as a buffer or base64 string so downstream steps (e.g., http, sftp, googledrive) can upload or send the file.

Implementation note: SheetJS no longer publishes current versions to the public npm registry. The dependency must be installed from the official SheetJS CDN tarball:

https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz

i.e., in package.json:

"dependencies": {
  "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
}

Sample Code

// Parse an xlsx file (base64 from a previous step) into JSON rows
parse($.data.fileContent, { type: 'base64' });

// Convert a specific sheet to an array of JSON objects
sheetToJson($.workbook, { sheetName: 'Sheet1', header: 1, raw: false });

// Convert a sheet to a CSV string
sheetToCsv($.workbook, { sheetName: 'Orders' });

// Build an xlsx file from JSON records and return it as base64 for upload
jsonToSheet($.data.records, {
  sheetName: 'Export',
  output: 'base64',
});

(Function names/signatures to be finalized during design; these illustrate the intended developer experience.)

Important

• Login credentials: N/A. This adaptor performs local data transformation only and does not connect to any external system, so no configuration/credential is required.
• Test record(s): We can create sample .xlsx and .csv fixture files (multi-sheet, with headers, dates, numbers, and empty cells) in the test/fixtures folder for unit tests.
• SheetJS docs: https://docs.sheetjs.com/
• Utility functions API (sheet_to_json, sheet_to_csv, json_to_sheet): https://docs.sheetjs.com/docs/api/utilities/
• Reading/writing files API: https://docs.sheetjs.com/docs/api/parse-options
• SheetJS logo (SVG): https://docs.sheetjs.com/img/logo.svg
• Note: we'll need to prepare a 512x190px rectangle.png and 256x256px square.png with transparent backgrounds per the adaptor requirements.