Getting Started

Stringent is a type-safe expression parser and evaluator for TypeScript. One grammar definition drives two engines:

• a type-level parser — expressions in string literals are validated and fully typed at compile time, and
• a runtime parser — dynamic strings get structured errors and evaluation.

Installation

npm

npm install stringent

pnpm

pnpm add stringent

yarn

yarn add stringent

Stringent is ESM-only, ships its own type definitions, and depends on arktype — constraints, result types, and schemas are all arktype definitions.

Quickstart

1. Define your grammar. Each defineNode call declares one grammar rule: a pattern of elements, a precedence, and (usually) a result type and an evaluation function.

   import { defineNode, overlapping, createParser } from "stringent";
   
   // Leaf nodes live at the HIGHEST precedence level.
   // Single-element passthrough patterns take no resultType.
   const numberLit = defineNode({
     name: "num",
     precedence: 4,
     pattern: (p) => p.number(),
   });
   const stringLit = defineNode({
     name: "str",
     precedence: 4,
     pattern: (p) => p.string(['"', "'"]),
   });
   // Keyword literals must come before path() in the level, or `true`
   // would parse as an identifier.
   // ONE node for both booleans: const ALTERNATION binds the matched text
   const booleanLit = defineNode({
     name: "bool",
     precedence: 4,
     pattern: (p) =>
       p
         .constVal("true", "false").as("word")
         .result("boolean")
         .eval(({ word }) => word() === "true"),
   });
   const variable  = defineNode({
     name: "var",
     precedence: 4,
     pattern: (p) => p.path(),
   });
   // path() matches identifiers and dotted paths: x, values.password
   
   // Polymorphic parens: the result type is whatever is inside
   const parens = defineNode({
     name: "parens",
     precedence: 4,
     pattern: (p) =>
       p
         .constVal("(")
         .expr().as("inner")
         .constVal(")")
         .result("inner")
         .eval(({ inner }) => inner()),
   });
   
   // Overlap-typed equality: 1 == 'a' is a parse-time type error,
   // but operand order never matters (x == 1 and 1 == x both parse)
   const eq = defineNode({
     name: "eq",
     precedence: 1,
     pattern: (p) =>
       p
         .operand().as("left")
         .constVal("==")
         .rest(overlapping("left")).as("right")
         .result("boolean")
         .eval(({ left, right }) => left() === right()),
   });
   
   // ONE overloaded add: number+number → number, string+string → string.
   // "number | string" is an arktype def; "left" is a binding reference.
   // The operand() tail makes the level LEFT-associative: 1+2+3 = (1+2)+3.
   const add = defineNode({
     name: "add",
     precedence: 2,
     pattern: (p) =>
       p
         .operand("number | string").as("left")
         .constVal("+")
         .operand("left").as("right")
         .result("left")
         .eval((b) => {
       const l = b.left(), r = b.right();
       return typeof l === "string" ? `${l}${String(r)}` : Number(l) + Number(r);
     }),
   });
   
   const mul = defineNode({
     name: "mul",
     precedence: 3,
     pattern: (p) =>
       p
         .operand("number").as("left")
         .constVal("*")
         .operand("number").as("right")
         .result("number")
         .eval(({ left, right }) => left() * right()),
   });
   
   // A short-circuiting polymorphic ternary. The rest() tail makes the
   // level RIGHT-associative.
   const ternary = defineNode({
     name: "ternary",
     precedence: 0,
     pattern: (p) =>
       p
         .operand("boolean").as("cond")
         .constVal("?")
         .expr().as("then")
         .constVal(":")
         .rest("then").as("else")
         .result("then")
         .eval(({ cond, then, else: alt }) => (cond() ? then() : alt())),
   });
   
   const parser = createParser(
     [numberLit, stringLit, booleanLit, variable, parens, ternary, eq, add, mul] as const
   );

2. Parse string literals (compile-time checked). parse() only accepts literals that fully parse against the grammar — an invalid expression is a compile-time error, and the AST type is fully inferred. Hover ast below to see it:

   const [ast] = parser.parse("1+2*3", {});
   const ast: {
       readonly node: "add";
       readonly outputSchema: "number";
   } & {
       left: NumberNode<"1">;
       right: {
           readonly node: "mul";
           readonly outputSchema: "number";
       } & {
           left: NumberNode<"2">;
           right: NumberNode<"3">;
       };
   }
   
   

   Invalid expressions don’t compile:

   parser.parse("1+", {});                  // ✗ compile error
   parser.parse("1+'a'", {});               // ✗ compile error: 'a' ⊄ number (type of 'left')
   parser.parse("1+x", { x: "number" });    // ✓
   parser.safeParse("1+x", { x: "numbr" }); // ✗ compile error AT THE SCHEMA LEAF

   Schema leaves are arktype definitions, validated by type.validate — a typo’d { x: "numbr" } errors right at the leaf on safeParse (and every entry point rejects bad schemas at runtime). Grammar constraints are validated even earlier: a typo’d operand("numbr") throws at createParser time.

3. Parse dynamic strings (runtime checked). Runtime-provided input goes through safeParse(), which requires full consumption and returns structured errors instead of throwing:

   const result = parser.safeParse(userInput, { x: "number" });
   if (result.success) {
     console.log(result.ast);
   } else {
     console.error(result.error.message);
     // e.g. Expected a number expression at position 2, got unknown ('zz' is not in the schema)
     // e.g. Expected a number (type of 'left') expression at position 4, got string
     // e.g. Unexpected input at position 6: found "junk!!" (expected "*", "+" or "==")
     result.error.position; // 0-based offset
     result.error.expected; // tokens that would have been valid there
   }

4. Evaluate. evaluate() parses and evaluates in one step; the result type is inferred from the expression — including through polymorphic nodes:

   const seven = parser.evaluate("1+2*3", {}, {});
   const seven: number
   
   const ab = parser.evaluate("'a'+'b'", {}, {});
   const ab: string
   
   const answer = parser.evaluate("x*2", { x: "number" }, { x: 21 });
   const answer: number
   
   

   For dynamic input, combine safeParse with evaluateAst:

   const parsed = parser.safeParse(userInput, schema);
   if (parsed.success) {
     const value = parser.evaluateAst(parsed.ast, values);
   }

Where to next?

• Defining a grammar — pattern elements, precedence, associativity by tail shape, and grammar validation.
• Schemas & types — arktype definitions, binding references, and polymorphic nodes.
• Parsing & evaluation — the entry points, compile(), and the lazy evaluation model.
• Error handling — structured errors and what throws when.
• Playground — try the runtime engine live in your browser.