@origints/xlsx

XLSX workbook parsing with cell predicates, cursor-based iteration, and header-relative column lookup.

Installation

npm install @origints/xlsx @origints/core

Features

• Parse XLSX from streams, buffers, or file paths
• Navigate workbooks, sheets, ranges, and cells
• Cell predicates for conditional extraction
• eachSlice iteration with header-relative column access
• Range-based row extraction
• Cursor-based sequential processing
• Full source location tracking for every cell

Usage with Planner

Extract cell values

import { Planner, loadFile, run } from '@origints/core'
import { parseXlsx } from '@origints/xlsx'

const plan = new Planner()
  .in(loadFile('data.xlsx'))
  .mapIn(parseXlsx())
  .emit((out, $) => out
    .add('title', $.firstSheet().cell('A1').string())
    .add('revenue', $.firstSheet().cell('B2').number())
  )
  .compile()

const result = await run(plan, { readFile, registry })

Extract from specific sheets

const plan = new Planner()
  .in(loadFile('report.xlsx'))
  .mapIn(parseXlsx())
  .emit((out, $) => out
    .add('totalSales', $.sheet('Sales').cell('B10').number())
    .add('totalExpenses', $.sheet('Expenses').cell('B10').number())
  )
  .compile()

Extract rows from a range

const plan = new Planner()
  .in(loadFile('employees.xlsx'))
  .mapIn(parseXlsx())
  .emit((out, $) => out
    .add('employees', $.firstSheet().range('A2:C4').rows(row => ({
      kind: 'object',
      properties: {
        name: row.col(1).string(),
        age: row.col(2).number(),
        dept: row.col(3).string(),
      },
    })))
  )
  .compile()

eachSlice with predicates

Iterate rows from a starting cell while a predicate holds, with header-relative column access:

import { cell, rowCol } from '@origints/xlsx'

const hasData = rowCol(0, cell.isNotEmpty())
  .and(rowCol(0, cell.startsWith('Total').not()))

const plan = new Planner()
  .in(loadFile('report.xlsx'))
  .mapIn(parseXlsx())
  .emit((out, $) => {
    const header = $.firstSheet().find(cell.equals('Name'))

    return out.add('people',
      header.down().eachSlice('down', hasData, row => ({
        kind: 'object',
        properties: {
          name: row.colWhere(header, cell.equals('Name')).string(),
          role: row.colWhere(header, cell.equals('Role')).string(),
        },
      }))
    )
  })
  .compile()

eachCell

Gather cells in a direction while a predicate matches:

import { cell } from '@origints/xlsx'

$.firstSheet()
  .cell('B2')
  .eachCell('down', cell.isNotEmpty(), c => c.number())
// [100, 200, 300, 400]

Dynamic range corners

const topLeft = $.firstSheet().find(cell.equals('Name'))
const bottomRight = $.firstSheet().find(cell.equals('Total')).left()
$.firstSheet().range(topLeft, bottomRight).rows(row => ({ /* ... */ }))

Cell predicates

import { cell } from '@origints/xlsx'

cell.equals('Total')
cell.contains('Revenue')
cell.startsWith('Q')
cell.isNotEmpty()
cell.gt(100)

// Composition
cell.isNotEmpty().and(cell.startsWith('Total').not())

Standalone usage

import { parseXlsxAsyncImpl, XlsxWorkbook } from '@origints/xlsx'

const workbook = (await parseXlsxAsyncImpl.execute(buffer)) as XlsxWorkbook

const sheet = workbook.sheet('Sheet1')
if (sheet.ok) {
  const cellVal = sheet.value.cell('A1')
  if (cellVal.ok) console.log(cellVal.value.string().value)
}

API

Export	Description
parseXlsx(options?)	Transform AST for Planner.mapIn()
registerXlsxTransforms(registry)	Register XLSX transforms
XlsxWorkbook	Workbook navigation
XlsxSheet	Sheet with cell/range access
XlsxRange	Range operations
XlsxCell	Cell value extraction
XlsxCursor	Sequential cursor-based iteration
cell	Cell predicate factory
rowCol	Row predicate factory

License

MIT