File processor

Generated on 2026-10-03 from docs/api/file-processor.md in the repository (commit f26b8022e0f8 of 2026-10-03) by tools/build-api-v3.py. The text is the repository's, not edited here. The samples with imports type-check against the published package 3.3.1; no known deviations.

The file processor module handles loading spreadsheet files and parsing their sheets into table models. It includes the importer abstraction, individual parsers for each table type, and the specification-to-decision converter with its rule converter plugin system.

import {
  ImporterXlsx,
  FileProcessor,
  ParserDecision,
  ParserMatrix,
  ParserSpecification,
  ParserSpecificationConverter,
  RuleConverterRegistry,
  createDefaultConverterRegistry
} from '@xhubio/nanook-table'
import type {
  ImporterInterface,
  ParserInterface,
  ParserParseRequest
} from '@xhubio/nanook-table'

ImporterInterface

The interface for spreadsheet readers (a type). An importer loads a file and provides cell-level access to its content. The FileProcessor depends on this interface, so you can replace the XLSX importer with one for a different file format.

Methods

async loadFile(fileName: string): Promise<void>

Opens and loads the given file. After this call, the importer's sheet data is available for reading.

sheetNames: string[] (property)

The sheet names of the loaded file, in the order they appear. In ImporterXlsx it is a getter: read it, do not call it.

const importer = new ImporterXlsx()
await importer.loadFile('tests.xlsx')
const sheets = importer.sheetNames
// ['LoginTests', 'RegistrationTests', 'PaymentMatrix']

cellValue(sheetName: string, columnNumber: number, rowNumber: number): number | string | undefined

Returns the value of a single cell. Column and row indices are zero-based.

Returns undefined if the cell is empty.

cellValueString(sheetName: string, columnNumber: number, rowNumber: number): string | undefined

Like cellValue(), but returns the value as a string. The parsers use this one.

logger: LoggerInterface (property)

The logger of the importer.

clear(): void

Releases the loaded file data to free memory. Call this after parsing is complete.

ImporterXlsx

XLSX implementation of ImporterInterface. Uses the xlsx library to read Excel files (.xlsx, .xls). The constructor takes { logger? }.

Properties

Example

import { ImporterXlsx } from '@xhubio/nanook-table'

const importer = new ImporterXlsx()
await importer.loadFile('resources/tests.xlsx')

for (const name of importer.sheetNames) {
  const firstCell = importer.cellValue(name, 0, 0)
  console.log(`Sheet "${name}" starts with: ${firstCell}`)
}

importer.clear()

FileProcessor

Orchestrates the loading and parsing of spreadsheet files. It uses an importer to read cells and delegates to registered parsers based on the table type marker found in each sheet's first cell.

Constructor

new FileProcessor(options?: { logger?: LoggerInterface; tableTypeKeys?: string[] })

The FileProcessor requires an importer and parsers to be registered before calling load(). Use createDefaultFileProcessor() to get a pre-configured instance with all standard parsers.

Properties

Methods

async load(fileNames: string | string[]): Promise<void>

Loads the given file or files, iterates over all sheets, and parses each one into a table model. The importer is selected by the file extension, the parser by the table type marker in cell (0, 0) of each sheet.

After this call, the tables property contains all parsed table models. load() does not throw: a file it cannot read or a sheet it cannot parse is logged as an error, so check logger.entries.error.

import { createDefaultFileProcessor, LoggerMemory } from '@xhubio/nanook-table'

const logger = new LoggerMemory()
const fp = createDefaultFileProcessor(logger)
await fp.load('resources/tests.xlsx')

console.log(`Loaded ${fp.tables.length} tables`)
for (const table of fp.tables) {
  console.log(`- ${table.tableName} (${table.tableType})`)
}

registerImporter(extension: string, importer: ImporterInterface): void

Registers the importer for files with the given extension, without the dot ('xlsx', 'xls').

registerParser(tableType: string, parser: ParserInterface): void

Registers a parser for the given table type marker. When a sheet's first cell matches the marker, this parser is used.

ParserInterface

The interface for table parsers (a type). Each concrete parser knows how to read a specific table type from raw spreadsheet cells and produce a table model. Besides parse() it has the properties startRow, startColumn, endKey and logger. The built-in parsers extend ParserBase, whose constructor requires { logger }: new ParserDecision({ logger }).

Methods

parse(request: ParserParseRequest): TableInterface | undefined

Parses one sheet and returns a table model, or undefined if the sheet could not be parsed (the errors are logged).

Returns: A TableInterface implementation (e.g., TableDecision, TableMatrix), or undefined.

ParserDecision

Parser for sheets marked with <DECISION_TABLE>. Reads the sheet structure -- sections, sub-sections, field definitions, and test case columns -- and produces a TableDecision model.

Sheet Structure

A decision table sheet has the following structure:

Row 0:  <DECISION_TABLE>   |  tc1  |  tc2  |  tc3  | ...
        ─────────────────────────────────────────────────
        FieldSection: "Login Data"
          userId            |  x    |       |  x    |
          password          |       |  x    |  x    |
        TagSection: "Tags"
          smoke             |  x    |       |  x    |
        FilterSection: "Filter"
          myFilter          |  val  |       |  val  |
        ExecuteSection
        NeverExecuteSection
        MultiplicitySection
        SummarySection: "Summary"
          expected result   |  err  |  err  |  ok   |
        <END>

Recognized Section Types

Methods

parse(request: ParserParseRequest): TableInterface | undefined

Parses the decision table and returns a TableDecision model.

ParserMatrix

Parser for sheets marked with <MATRIX_TABLE>. Reads a two-dimensional matrix of test parameters and produces a TableMatrix model.

Sheet Structure

A matrix table has row headers on the left, column headers on top, and data values at their intersections. Each non-empty intersection becomes a test case.

Methods

parse(request: ParserParseRequest): TableInterface | undefined

Parses the matrix table and returns a TableMatrix model.

ParserSpecification

Parser for sheets marked with <SPECIFICATION> (the legacy marker <SPECIFICATION_TABLE> works too). Reads a high-level specification of fields, rules, and severities into a SpecificationModel; parse() converts that into a TableDecision right away, so a specification sheet arrives in FileProcessor.tables as a decision table.

Sheet Structure

A specification table has three sections:

1. Fields -- listed vertically with their applicable rules marked per column
2. Severities -- defines severity levels for rule violations
3. Rules -- defines the available rules and their descriptions

Methods

parse(request: ParserParseRequest): TableInterface | undefined

Parses the specification sheet and returns the converted TableDecision.

parseSpecification(sheetName: string, importer: ImporterInterface): SpecificationModel | undefined

Parses the specification sheet and returns the SpecificationModel, without converting it.

ParserSpecificationConverter

Converts a SpecificationModel into a TableDecision. This is the bridge between the high-level specification format and the concrete decision table that the processor can execute.

The converter creates:

• A primary data section with equivalence classes derived from the field rules
• An execution section
• A severity section
• A secondary data section (if a primary key rule is present)
• A summary section

Constructor

new ParserSpecificationConverter(options?: { registry?: RuleConverterRegistry })

Methods

convert(request: { specification: SpecificationInterface; logger: LoggerInterface; fileName: string }): TableDecision

Converts the specification model into a decision table.

import {
  LoggerMemory,
  ParserSpecification,
  ParserSpecificationConverter,
  ImporterXlsx
} from '@xhubio/nanook-table'

const logger = new LoggerMemory()
const importer = new ImporterXlsx({ logger })
await importer.loadFile('spec.xlsx')

const parser = new ParserSpecification({ logger })
const spec = parser.parseSpecification('MySpec', importer)

if (spec !== undefined) {
  const converter = new ParserSpecificationConverter()
  const decisionTable = converter.convert({ specification: spec, logger, fileName: 'spec.xlsx' })
}

RuleConverterPlugin

Interface for plugins that convert specification rules into equivalence classes. Each plugin handles one type of rule.

interface RuleConverterPlugin {
  /** Unique name identifying this converter */
  name: string

  /** Human-readable description of what this converter does */
  description: string

  /** Convert a rule into equivalence classes */
  convert(context: RuleConversionContext): EquivalenceClassResult
}

RuleConversionContext

Context object passed to RuleConverterPlugin.convert(). Contains all information needed to derive equivalence classes from a rule.

interface RuleConversionContext {
  /** The field definition being processed */
  field: SpecificationFieldInterface

  /** The specific rule being converted */
  rule: SpecificationFieldRuleInterface

  /** All rules that apply to this field */
  allFieldRules: SpecificationFieldRuleInterface[]

  /** The full specification model */
  specification: SpecificationInterface
}

EquivalenceClassResult

The return type of a rule converter plugin. Contains the valid and error equivalence classes derived from a rule.

interface EquivalenceClassResult {
  validClasses: EquivalenceClassEntry[]
  errorClasses: EquivalenceClassEntry[]
}

EquivalenceClassEntry

A single equivalence class within a result.

interface EquivalenceClassEntry {
  /** Display name of the equivalence class */
  name: string

  /** Explanatory comment (required; may be an empty string) */
  comment: string

  /** Optional severity level for error classes */
  severity?: string
}

RuleConverterRegistry

Registry for rule converter plugins. Used by ParserSpecificationConverter to look up the appropriate converter for each rule type.

Methods

register(plugin: RuleConverterPlugin): void

Registers a converter plugin. The plugin's name property is used as the key. Throws if a plugin with that name is already registered.

get(name: string): RuleConverterPlugin | undefined

Returns the plugin registered under the given name, or undefined.

has(name: string): boolean

Returns true if a plugin with the given name is registered.

names(): string[]

Returns an array of all registered plugin names.

Custom Rule Converter Example

import { RuleConverterRegistry } from '@xhubio/nanook-table'
import type {
  RuleConverterPlugin,
  RuleConversionContext,
  EquivalenceClassResult
} from '@xhubio/nanook-table'

const myPlugin: RuleConverterPlugin = {
  name: 'maxLength',
  description: 'Generates classes for maximum length validation',
  convert(context: RuleConversionContext): EquivalenceClassResult {
    return {
      validClasses: [
        { name: 'within limit', comment: 'Value within max length' }
      ],
      errorClasses: [
        { name: 'exceeds limit', comment: 'Value exceeds max length' }
      ]
    }
  }
}

const registry = new RuleConverterRegistry()
registry.register(myPlugin)

createDefaultConverterRegistry()

Factory function that creates a RuleConverterRegistry pre-populated with all built-in rule converter plugins.

import { createDefaultConverterRegistry } from '@xhubio/nanook-table'

const registry = createDefaultConverterRegistry()
console.log(registry.names()) // list of all built-in converter names

Parser Constants

The parsers use the following internal constants when reading spreadsheet data. They are not exported; they are listed so you know how a sheet is read: