stringent 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,108 @@
+# Stringent
+
+A type-safe expression parser for TypeScript with compile-time validation and inference.
+
+> **Warning**
+> This library is under active development and not yet ready for production use. APIs may change.
+
+## Overview
+
+Stringent parses and validates expressions like `values.password == values.confirmPassword` against a schema at both compile-time and runtime, with full TypeScript type inference for expression results.
+
+## Installation
+
+```bash
+npm install stringent
+# or
+pnpm add stringent
+```
+
+## Usage
+
+### Define Your Grammar
+
+Use `defineNode` to create expression nodes with patterns, precedence, and result types:
+
+```typescript
+import { defineNode, number, constVal, lhs, rhs, createParser } from 'stringent';
+
+// Atomic: number literals
+const numberLit = defineNode({
+  name: "number",
+  pattern: [number()],
+  precedence: "atom",
+  resultType: "number",
+});
+
+// Binary operators with precedence
+const add = defineNode({
+  name: "add",
+  pattern: [lhs("number").as("left"), constVal("+"), rhs("number").as("right")],
+  precedence: 1,  // Lower = binds looser
+  resultType: "number",
+});
+
+const mul = defineNode({
+  name: "mul",
+  pattern: [lhs("number").as("left"), constVal("*"), rhs("number").as("right")],
+  precedence: 2,  // Higher = binds tighter
+  resultType: "number",
+});
+```
+
+### Create a Parser
+
+```typescript
+const parser = createParser([numberLit, add, mul] as const);
+
+// Type-safe parsing - result type is inferred at compile-time
+const result = parser.parse("1+2*3", {});
+//    ^? const result: [{ node: "add"; left: { node: "number"; value: "1" }; right: { node: "mul"; left: { node: "number"; value: "2" }; right: { node: "number"; value: "3" } } }, ""]
+```
+
+### Pattern Elements
+
+| Pattern | Description |
+|---------|-------------|
+| `number()` | Matches numeric literals |
+| `string(quotes)` | Matches quoted strings |
+| `ident()` | Matches identifiers, resolves type from context |
+| `constVal(value)` | Matches exact string (operators, keywords) |
+| `lhs(constraint)` | Left operand (higher precedence, avoids left-recursion) |
+| `rhs(constraint)` | Right operand (same precedence, right-associative) |
+| `expr(constraint)` | Full expression (all grammar levels) |
+
+Use `.as(name)` to capture pattern elements as named bindings in the AST:
+
+```typescript
+lhs("number").as("left")  // Captures left operand as "left" in the AST node
+```
+
+### Runtime Evaluation (Coming Soon)
+
+> **Note**
+> Runtime evaluation is not yet implemented.
+
+Add `eval` to compute values at runtime:
+
+```typescript
+const add = defineNode({
+  name: "add",
+  pattern: [lhs("number").as("left"), constVal("+"), rhs("number").as("right")],
+  precedence: 1,
+  resultType: "number",
+  eval: ({ left, right }) => left + right,
+});
+```
+
+## Key Features
+
+- **Compile-time validation**: Invalid expressions fail TypeScript compilation
+- **Type inference**: Expression result types are inferred automatically
+- **Operator precedence**: Correct parsing of complex expressions
+- **Schema-aware**: Validates field references against your schema
+- **Dual API**: Same parsing logic at compile-time (types) and runtime
+
+## License
+
+MIT

package/dist/combinators/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Parser Combinators
+ *
+ * Composable parsers that work at both runtime and compile-time.
+ * Parse methods are generic - return types computed from input literals.
+ * All combinators thread context ($) through to child parsers.
+ *
+ * IMPORTANT: All parse methods MUST be generic in context:
+ *   parse<TInput extends string, $ extends Context>(input: TInput, $: $)
+ */
+import type { Context } from "../context.js";
+import type { IParser, ParseNumber, ParseString, ParseIdent, ParseConst, _Number, _String, _Ident, _Const } from "../primitive/index.js";
+/** Static type for parsing any parser */
+export type Parse<P, TInput extends string, $ extends Context> = P extends _Number ? ParseNumber<TInput> : P extends _String<infer Q> ? ParseString<Q, TInput> : P extends _Const<infer V> ? ParseConst<V, TInput> : P extends _Ident ? ParseIdent<TInput, $> : P extends _Union<infer Parsers> ? ParseUnion<Parsers, TInput, $> : P extends _Tuple<infer Parsers> ? ParseTuple<Parsers, TInput, $> : P extends _Optional<infer Parser> ? ParseOptional<Parser, TInput, $> : P extends _Many<infer Parser> ? ParseMany<Parser, TInput, $> : never;
+/** Static type for Union parsing */
+export type ParseUnion<TParsers extends IParser[], TInput extends string, $ extends Context> = TParsers extends [
+    infer First extends IParser,
+    ...infer Rest extends IParser[]
+] ? Parse<First, TInput, $> extends [infer R, infer Remaining extends string] ? [R, Remaining] : ParseUnion<Rest, TInput, $> : [];
+/** Static type for Tuple parsing */
+export type ParseTuple<TParsers extends IParser[], TInput extends string, $ extends Context, TAcc extends unknown[] = []> = TParsers extends [
+    infer First extends IParser,
+    ...infer Rest extends IParser[]
+] ? Parse<First, TInput, $> extends [infer R, infer Remaining extends string] ? ParseTuple<Rest, Remaining, $, [...TAcc, R]> : [] : [TAcc, TInput];
+/** Static type for Optional parsing */
+export type ParseOptional<TParser extends IParser, TInput extends string, $ extends Context> = Parse<TParser, TInput, $> extends [infer R, infer Remaining extends string] ? [R, Remaining] : [undefined, TInput];
+/** Static type for Many parsing */
+export type ParseMany<TParser extends IParser, TInput extends string, $ extends Context, TAcc extends unknown[] = []> = Parse<TParser, TInput, $> extends [infer R, infer Remaining extends string] ? Remaining extends TInput ? [TAcc, TInput] : ParseMany<TParser, Remaining, $, [...TAcc, R]> : [TAcc, TInput];
+declare class _Union<TParsers extends IParser[]> {
+    readonly __combinator: "union";
+    readonly parsers: TParsers;
+    constructor(parsers: TParsers);
+    parse<TInput extends string, $ extends Context>(input: TInput, $: $): ParseUnion<TParsers, TInput, $>;
+}
+declare class _Tuple<TParsers extends IParser[]> {
+    readonly __combinator: "tuple";
+    readonly parsers: TParsers;
+    constructor(parsers: TParsers);
+    parse<TInput extends string, $ extends Context>(input: TInput, $: $): ParseTuple<TParsers, TInput, $>;
+}
+declare class _Optional<TParser extends IParser> {
+    readonly __combinator: "optional";
+    readonly parser: TParser;
+    constructor(parser: TParser);
+    parse<TInput extends string, $ extends Context>(input: TInput, $: $): ParseOptional<TParser, TInput, $>;
+}
+declare class _Many<TParser extends IParser> {
+    readonly __combinator: "many";
+    readonly parser: TParser;
+    constructor(parser: TParser);
+    parse<TInput extends string, $ extends Context>(input: TInput, $: $): ParseMany<TParser, TInput, $>;
+}
+export declare const Union: <TParsers extends IParser[]>(parsers: [...TParsers]) => _Union<TParsers>;
+export declare const Tuple: <TParsers extends IParser[]>(parsers: [...TParsers]) => _Tuple<TParsers>;
+export declare const Optional: <TParser extends IParser>(parser: TParser) => _Optional<TParser>;
+export declare const Many: <TParser extends IParser>(parser: TParser) => _Many<TParser>;
+export type { _Union, _Tuple, _Optional, _Many };

package/dist/combinators/index.js

@@ -0,0 +1,104 @@
+/**
+ * Parser Combinators
+ *
+ * Composable parsers that work at both runtime and compile-time.
+ * Parse methods are generic - return types computed from input literals.
+ * All combinators thread context ($) through to child parsers.
+ *
+ * IMPORTANT: All parse methods MUST be generic in context:
+ *   parse<TInput extends string, $ extends Context>(input: TInput, $: $)
+ */
+// =============================================================================
+// Union Combinator
+// =============================================================================
+class _Union {
+    __combinator = "union";
+    parsers;
+    constructor(parsers) {
+        this.parsers = parsers;
+    }
+    parse(input, $) {
+        for (const parser of this.parsers) {
+            const result = parser.parse(input, $);
+            if (result.length === 2) {
+                return result;
+            }
+        }
+        return [];
+    }
+}
+// =============================================================================
+// Tuple Combinator
+// =============================================================================
+class _Tuple {
+    __combinator = "tuple";
+    parsers;
+    constructor(parsers) {
+        this.parsers = parsers;
+    }
+    parse(input, $) {
+        const results = [];
+        let remaining = input;
+        for (const parser of this.parsers) {
+            const result = parser.parse(remaining, $);
+            if (result.length !== 2) {
+                return [];
+            }
+            results.push(result[0]);
+            remaining = result[1];
+        }
+        return [results, remaining];
+    }
+}
+// =============================================================================
+// Optional Combinator
+// =============================================================================
+class _Optional {
+    __combinator = "optional";
+    parser;
+    constructor(parser) {
+        this.parser = parser;
+    }
+    parse(input, $) {
+        const result = this.parser.parse(input, $);
+        if (result.length === 2) {
+            return result;
+        }
+        return [undefined, input];
+    }
+}
+// =============================================================================
+// Many Combinator
+// =============================================================================
+class _Many {
+    __combinator = "many";
+    parser;
+    constructor(parser) {
+        this.parser = parser;
+    }
+    parse(input, $) {
+        const results = [];
+        let remaining = input;
+        while (true) {
+            const result = this.parser.parse(remaining, $);
+            if (result.length !== 2) {
+                break;
+            }
+            results.push(result[0]);
+            const newRemaining = result[1];
+            // Prevent infinite loop on zero-width matches
+            if (newRemaining === remaining) {
+                break;
+            }
+            remaining = newRemaining;
+        }
+        return [results, remaining];
+    }
+}
+// =============================================================================
+// Exported Factories
+// =============================================================================
+export const Union = (parsers) => new _Union(parsers);
+export const Tuple = (parsers) => new _Tuple(parsers);
+export const Optional = (parser) => new _Optional(parser);
+export const Many = (parser) => new _Many(parser);

package/dist/context.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Context - carries schema data for identifier type resolution
+ *
+ * The context maps variable names to their types, enabling type-safe
+ * parsing of expressions like `x + y` where x and y come from a schema.
+ *
+ * Grammar is now computed from node schemas via ComputeGrammar<Nodes>.
+ */
+/**
+ * Parse context with schema data.
+ *
+ * @typeParam TData - Schema mapping variable names to their types
+ *
+ * @example
+ * ```ts
+ * type Ctx = Context<{ x: "number"; y: "string" }>;
+ * // x resolves to type "number", y resolves to type "string"
+ * ```
+ */
+export interface Context<TData extends Record<string, string> = Record<string, string>> {
+    /** Schema types for identifier resolution */
+    readonly data: TData;
+}
+/** Empty context (no schema variables) */
+export declare const emptyContext: Context<{}>;
+/** Type alias for empty context */
+export type EmptyContext = Context<{}>;

package/dist/context.js

@@ -0,0 +1,13 @@
+/**
+ * Context - carries schema data for identifier type resolution
+ *
+ * The context maps variable names to their types, enabling type-safe
+ * parsing of expressions like `x + y` where x and y come from a schema.
+ *
+ * Grammar is now computed from node schemas via ComputeGrammar<Nodes>.
+ */
+// =============================================================================
+// Default Context
+// =============================================================================
+/** Empty context (no schema variables) */
+export const emptyContext = { data: {} };

package/dist/createParser.d.ts

@@ -0,0 +1,76 @@
+/**
+ * createParser Entry Point
+ *
+ * Creates a type-safe parser from node schemas.
+ * The returned parser has:
+ *   - Type-level parsing via Parse<Grammar, Input, Context>
+ *   - Runtime parsing that mirrors the type structure
+ */
+import type { NodeSchema } from "./schema/index.js";
+import type { ComputeGrammar, Grammar } from "./grammar/index.js";
+import type { Parse } from "./parse/index.js";
+import type { Context } from "./context.js";
+/**
+ * Parser interface with type-safe parse method.
+ *
+ * TGrammar: The computed grammar type from node schemas
+ * TNodes: The tuple of node schemas
+ */
+export interface Parser<TGrammar extends Grammar, TNodes extends readonly NodeSchema[]> {
+    /**
+     * Parse an input string.
+     *
+     * @param input - The input string to parse
+     * @param schema - Schema mapping field names to their types
+     * @returns Parse result with computed type
+     *
+     * @example
+     * ```ts
+     * const result = parser.parse("1+2", {});
+     * // Type: Parse<Grammar, "1+2", Context<{}>>
+     * // Value: [{ type: "binary", name: "add", left: {...}, right: {...} }, ""]
+     * ```
+     */
+    parse<TInput extends string, TSchema extends Record<string, string>>(input: ValidatedInput<TGrammar, TInput, Context<TSchema>>, schema: TSchema): Parse<TGrammar, TInput, Context<TSchema>>;
+    /** The node schemas used to create this parser */
+    readonly nodes: TNodes;
+}
+type ValidatedInput<TGrammar extends Grammar, TInput extends string, $ extends Context> = Parse<TGrammar, TInput, $> extends [any, any] ? TInput : never;
+/**
+ * Create a type-safe parser from node schemas.
+ *
+ * The returned parser has both:
+ * - Compile-time type inference via Parse<Grammar, Input, Context>
+ * - Runtime parsing that matches the type structure
+ *
+ * @param nodes - Tuple of node schemas defining the grammar
+ * @returns Parser instance with type-safe parse method
+ *
+ * @example
+ * ```ts
+ * import { defineNode, number, expr, constVal, createParser } from "stringent";
+import { Validate } from '../dist/static/parser';
+ *
+ * const numberLit = defineNode({
+ *   name: "number",
+ *   pattern: [number()],
+ *   precedence: "atom",
+ *   resultType: "number",
+ * });
+ *
+ * const add = defineNode({
+ *   name: "add",
+ *   pattern: [expr("number"), constVal("+"), expr("number")],
+ *   precedence: 1,
+ *   resultType: "number",
+ * });
+ *
+ * const parser = createParser([numberLit, add] as const);
+ *
+ * // Type-safe parsing!
+ * const result = parser.parse("1+2", {});
+ * // Type: [BinaryNode<"add", NumberNode<"1">, NumberNode<"2">, "number">, ""]
+ * ```
+ */
+export declare function createParser<const TNodes extends readonly NodeSchema[]>(nodes: TNodes): Parser<ComputeGrammar<TNodes>, TNodes>;
+export {};

package/dist/createParser.js

@@ -0,0 +1,57 @@
+/**
+ * createParser Entry Point
+ *
+ * Creates a type-safe parser from node schemas.
+ * The returned parser has:
+ *   - Type-level parsing via Parse<Grammar, Input, Context>
+ *   - Runtime parsing that mirrors the type structure
+ */
+import { parse as runtimeParse } from "./runtime/parser.js";
+// =============================================================================
+// createParser Factory
+// =============================================================================
+/**
+ * Create a type-safe parser from node schemas.
+ *
+ * The returned parser has both:
+ * - Compile-time type inference via Parse<Grammar, Input, Context>
+ * - Runtime parsing that matches the type structure
+ *
+ * @param nodes - Tuple of node schemas defining the grammar
+ * @returns Parser instance with type-safe parse method
+ *
+ * @example
+ * ```ts
+ * import { defineNode, number, expr, constVal, createParser } from "stringent";
+import { Validate } from '../dist/static/parser';
+ *
+ * const numberLit = defineNode({
+ *   name: "number",
+ *   pattern: [number()],
+ *   precedence: "atom",
+ *   resultType: "number",
+ * });
+ *
+ * const add = defineNode({
+ *   name: "add",
+ *   pattern: [expr("number"), constVal("+"), expr("number")],
+ *   precedence: 1,
+ *   resultType: "number",
+ * });
+ *
+ * const parser = createParser([numberLit, add] as const);
+ *
+ * // Type-safe parsing!
+ * const result = parser.parse("1+2", {});
+ * // Type: [BinaryNode<"add", NumberNode<"1">, NumberNode<"2">, "number">, ""]
+ * ```
+ */
+export function createParser(nodes) {
+    return {
+        parse(input, schema) {
+            const context = { data: schema };
+            return runtimeParse(nodes, input, context);
+        },
+        nodes,
+    };
+}

package/dist/grammar/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Grammar Type Computation
+ *
+ * Computes a grammar TYPE from node schemas. The grammar is a flat tuple
+ * of precedence levels, sorted from lowest to highest precedence, with
+ * atoms as the final element.
+ *
+ * Example:
+ *   [[AddOps], [MulOps], [Atoms]]
+ *   // level 0 (lowest prec) → level 1 → atoms (last)
+ */
+import type { Pipe, Numbers, Objects, Tuples, Fn, Unions, Call } from "hotscript";
+import type { NodeSchema } from "../schema/index.js";
+/**
+ * A grammar is a tuple of levels, where each level is an array of node schemas.
+ * Sorted by precedence (lowest first), atoms last.
+ */
+export type Grammar = readonly (readonly NodeSchema[])[];
+/**
+ * Compare precedence entries: numbers sort ascending, "atom" always comes last.
+ * Entry format: [precedence, nodes[]]
+ */
+interface SortByPrecedence extends Fn {
+    return: this["arg0"][0] extends "atom" ? false : this["arg1"][0] extends "atom" ? true : Call<Numbers.LessThanOrEqual, this["arg0"][0], this["arg1"][0]>;
+}
+/**
+ * Compute the grammar tuple from node schemas.
+ *
+ * 1. Group nodes by precedence
+ * 2. Convert to entries and sort (numbers ascending, "atom" last)
+ * 3. Extract just the node arrays
+ */
+type ComputeGrammarImpl<TNodes extends readonly NodeSchema[]> = Pipe<[
+    ...TNodes
+], [
+    Tuples.GroupBy<Objects.Get<"precedence">>,
+    Objects.Entries,
+    Unions.ToTuple,
+    Tuples.Sort<SortByPrecedence>,
+    Tuples.Map<Tuples.At<1>>
+]>;
+export type ComputeGrammar<TNodes extends readonly NodeSchema[]> = ComputeGrammarImpl<TNodes> extends infer G extends Grammar ? G : never;
+export {};

package/dist/grammar/index.js

@@ -0,0 +1,12 @@
+/**
+ * Grammar Type Computation
+ *
+ * Computes a grammar TYPE from node schemas. The grammar is a flat tuple
+ * of precedence levels, sorted from lowest to highest precedence, with
+ * atoms as the final element.
+ *
+ * Example:
+ *   [[AddOps], [MulOps], [Atoms]]
+ *   // level 0 (lowest prec) → level 1 → atoms (last)
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Stringent - Type-safe Expression Parser
+ *
+ * Main entry points:
+ * - defineNode: Create grammar node schemas
+ * - createParser: Build a type-safe parser from nodes
+ * - Parse<Grammar, Input, Context>: Type-level parsing
+ */
+export { defineNode, number, string, ident, constVal, lhs, rhs, expr } from "./schema/index.js";
+export type { NodeSchema, PatternSchema, NumberSchema, StringSchema, IdentSchema, ConstSchema, ExprSchema, ExprRole, Precedence, ConfigureFn, EvalFn, SchemaToType, InferBindings, InferEvaluatedBindings, } from "./schema/index.js";
+export { createParser } from "./createParser.js";
+export type { Parser } from "./createParser.js";
+export type { Parse, BinaryNode, ParseError, TypeMismatchError, NoMatchError } from "./parse/index.js";
+export type { ComputeGrammar, Grammar } from "./grammar/index.js";
+export type { Context, EmptyContext } from "./context.js";
+export { emptyContext } from "./context.js";
+export type { ASTNode, LiteralNode, NumberNode, StringNode, IdentNode, ConstNode, } from "./primitive/index.js";
+export { Number, String, Ident, Const, type IParser, type ParseResult, } from "./primitive/index.js";
+export { Union, Tuple, Optional, Many } from "./combinators/index.js";

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * Stringent - Type-safe Expression Parser
+ *
+ * Main entry points:
+ * - defineNode: Create grammar node schemas
+ * - createParser: Build a type-safe parser from nodes
+ * - Parse<Grammar, Input, Context>: Type-level parsing
+ */
+// =============================================================================
+// Main API: defineNode & createParser
+// =============================================================================
+export { defineNode, number, string, ident, constVal, lhs, rhs, expr } from "./schema/index.js";
+export { createParser } from "./createParser.js";
+export { emptyContext } from "./context.js";
+// =============================================================================
+// Legacy Primitives (for backwards compatibility)
+// =============================================================================
+export { Number, String, Ident, Const, } from "./primitive/index.js";
+// =============================================================================
+// Legacy Combinators (for backwards compatibility)
+// =============================================================================
+export { Union, Tuple, Optional, Many } from "./combinators/index.js";