whynot.js Formal Language Matching Framework

Common errors

• Error: Cannot find module 'whynot'

  cause This typically occurs after upgrading to v4.x or v5.x when the module resolution system (e.g., Node.js or a bundler) cannot locate the new ESM or UMD bundles, especially if using CommonJS `require()` directly.
  fix Ensure your environment supports ESM imports (`import ... from 'whynot';`). If you must use CommonJS, ensure your bundler is configured to pick up `whynot.umd.js` or that Node.js is running in an ESM-compatible context for imported modules.

• Argument of type '(...args: any[]) => any' is not assignable to parameter of type 'any[]'.

  cause This TypeScript error indicates you are passing a function to `VM.execute` where an array is expected. This was a breaking change introduced in v3.0.0.
  fix Change your `vm.execute()` call to pass an array of input items, e.g., `vm.execute(['item1', 'item2'])`.

• TypeError: Cannot read properties of null (reading 'forEach') or similar runtime errors when accessing trace.records.

  cause Since v2.0.0, the `records` property on a `Trace` object can be `null` if no records were explicitly generated during execution, instead of an empty array.
  fix Always check if `trace.records` is not `null` before attempting to iterate or access its elements, e.g., `if (trace.records) { trace.records.forEach(...) }`.

• Property 'head' does not exist on type 'Trace'.

  cause The `head` property was removed from `Trace` objects in version 2.0.0.
  fix Remove any code that attempts to access `trace.head`. You will need to find alternative ways to determine the start of a trace if that was its purpose.

Warnings

• breaking Version 5.0.0 renames the UMD module file for older CJS environments to `whynot.umd.js`. While it primarily fixes ESM usage in Node.js, consumers relying on explicit paths for CJS bundles might need updates.
  Fix: Ensure your bundler or environment correctly resolves `whynot` or update any direct import paths to the UMD bundle if you are targeting older CJS environments and not using ESM.
• breaking Version 4.0.0 introduced significant changes to bundle filenames, providing `whynot.umd.js` for UMD/CommonJS and `whynot.esm.js` for ES Modules. Most modern bundlers handle this automatically, but older setups or explicit path configurations may break.
  Fix: Verify your bundler (e.g., Webpack, Rollup) is configured to correctly select the appropriate module entry point. You may need to update `main` or `module` fields in package.json if manually overriding module resolution.
• breaking In version 3.0.0, the `VM.execute` method's input argument changed from a generator-like function to a simple array. This was a breaking change aimed at significant performance and memory improvements for large inputs.
  Fix: Update all calls to `vm.execute()` to pass an array of input items (e.g., `vm.execute(['a', 'b'])`) instead of a function.
• breaking The `Trace.records` array was removed in version 3.0.0 to reduce allocations and improve performance. This property is no longer available directly on the `Trace` instance.
  Fix: Refactor code that accessed `trace.records`. If you need to record progress, ensure your program explicitly uses `Instruction.record` and retrieve trace information through other means if available, or reconsider the design of your program.
• breaking Version 2.0.0 removed the `head` property from returned `Trace` objects. Additionally, the allocation of the `records` array was made lazy, meaning `records` will be `null` instead of an empty array if no records are recorded for a trace.
  Fix: Avoid accessing `trace.head`. For recorded paths, rely on explicit `Instruction.record` and check `trace.records` for `null` before iterating.
• gotcha Since version 3.0.2, whynot bundles target ES2017 for somewhat modern browsers, reducing bundle size. If you need to support very old browser environments (pre-ES2017), you will need to transpile whynot yourself using tools like Babel.
  Fix: For older browser support, integrate a transpilation step (e.g., Babel with appropriate presets) into your build pipeline to down-level whynot's output to your target ECMAScript version.

Install

• npm install whynot npm
• yarn add whynot yarn
• pnpm add whynot pnpm

Imports

• VM
  wrong:

  const { VM } = require('whynot');

  correct:

  import { VM } from 'whynot';

  ESM is the primary module system since v4.0.0 and further solidified in v5.0.0. CommonJS `require` might fail or load an older UMD bundle depending on environment and bundler configuration.
• Program
  wrong:

  import Program from 'whynot'; // Not a default export

  correct:

  import { Program } from 'whynot';

  Key components like `Program`, `VM`, `Trace`, and `Instruction` are all named exports.
• Instruction
  wrong:

  import * as whynot from 'whynot'; const inst = whynot.Instruction.char('a');

  correct:

  import { Instruction } from 'whynot';

  `Instruction` provides static methods for creating VM instructions. It's a namespace-like export.

Quickstart

This quickstart demonstrates defining a basic VM program using `Instruction`s, initializing a `VM` with it, and executing an input array to check for a match. It shows both a matching and non-matching scenario.

import { Program, VM, Instruction, Trace } from 'whynot';

// Define a simple program that matches the sequence 'abc'
const program = new Program([
  Instruction.char('a'),
  Instruction.char('b'),
  Instruction.char('c'),
  Instruction.accept() // Signal successful match
]);

// Initialize the VM with the program
const vm = new VM(program);

// Execute the VM against an input array of characters
const input1 = ['a', 'b', 'c'];
const trace1: Trace | null = vm.execute(input1);

if (trace1) {
  console.log(`Input '${input1.join('')}' matched successfully.`);
  // You can inspect the trace for details on the match path
  // console.log('Trace records:', trace1.records);
} else {
  console.log(`Input '${input1.join('')}' did NOT match.`);
}

const input2 = ['a', 'x', 'c'];
const trace2: Trace | null = vm.execute(input2);

if (trace2) {
  console.log(`Input '${input2.join('')}' matched successfully.`);
} else {
  console.log(`Input '${input2.join('')}' did NOT match.`);
}