Stringent

Type-safe expression parser for TypeScript with compile-time validation.

Warning: Under active development. APIs may change.

Install

npm install stringent

Quick Start

import { createParser, defineNode, constVal, lhs, rhs } from 'stringent';

// Define operators
const add = defineNode({
  name: 'add',
  pattern: [lhs('number').as('left'), constVal('+'), rhs('number').as('right')],
  precedence: 1,
  resultType: 'number',
  eval: ({ left, right }) => left + right,
});

const mul = defineNode({
  name: 'mul',
  pattern: [lhs('number').as('left'), constVal('*'), rhs('number').as('right')],
  precedence: 2,
  resultType: 'number',
  eval: ({ left, right }) => left * right,
});

// Create parser
const parser = createParser([add, mul]);

// Parse and evaluate
const [evaluator, err] = parser.parse('x + 2 * 3', { x: 'number' });
if (!err) {
  const result = evaluator({ x: 1 }); // 7
  //    ^? number
}

Key Features

• Compile-time validation - Invalid expressions fail TypeScript compilation
• Type inference - Return types flow through parsing to evaluation
• ArkType integration - Schema types validated at compile-time and runtime
• Operator precedence - Configurable precedence for correct parsing

Pattern Elements

Element	Description
lhs(type?)	Left operand (higher precedence)
rhs(type?)	Right operand (same precedence)
expr(type?)	Full expression (resets precedence)
constVal(str)	Exact string match

API

createParser(nodes)

Creates a parser from node definitions.

defineNode(config)

Defines a grammar node:

• name - Unique identifier
• pattern - Array of pattern elements
• precedence - Lower binds looser
• resultType - Output type (e.g., 'number', 'boolean')
• eval - Evaluation function

parser.parse(input, schema)

Returns [evaluator, null] on success or [null, error] on failure.

The evaluator is callable with data matching the schema and has ast and schema properties.

Examples

See examples/ for more:

• Basic arithmetic with precedence
• Comparison operators
• Ternary expressions
• Custom domain operators
• Form validation

License

MIT