whynot

library0.12.0jsnpmunverified

whynot.js is a generic, VM-based framework for matching formal languages, drawing inspiration from systems like Russ Cox's regular expression engine. It operates by considering all possible branches of a program in parallel, enabling efficient implementation of various language matching tasks, including regular expressions and XML schemas. A key differentiator is its ability to record program progress through input and grammar, providing detailed feedback on *why* an input might not match a given grammar. The current stable version is 5.0.0, with releases focusing on performance, memory optimization, and module compatibility (ESM/CJS). While there isn't a strict release cadence, updates address bug fixes, dependency bumps, and significant architectural improvements.

serialization

npm install whynot

github ↗package ↗

INSTALL

IMPORT

SIG · WHYNOT

whynot

serializationjavascriptv0.12.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import { VM } from 'whynot';

✗ const { VM } = require('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

✓ import { Program } from 'whynot';

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

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

Instruction

✓ import { Instruction } from 'whynot';

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

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

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.`); }

Debug

Known issues

breakingVersion 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.

affects: >=5.0.0

breakingVersion 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.

affects: >=4.0.0

breakingIn 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.

affects: >=3.0.0

breakingThe `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.

affects: >=3.0.0

breakingVersion 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.

affects: >=2.0.0

gotchaSince 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.

affects: >=3.0.2

Errors

Common errors & fixes

Error: Cannot find module 'whynot'

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[]'.

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.

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'.

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.

Upgrade

Version history

0.12.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bwrrp/whynot.js ↗

packagehttps://www.npmjs.com/package/whynot ↗