stringent 0.0.1 → 0.0.4

package/README.md

@@ -0,0 +1,96 @@
+# Stringent
+
+Type-safe expression parser for TypeScript with compile-time validation.
+
+> **Warning:** Under active development. APIs may change.
+
+## Install
+
+```bash
+npm install stringent
+```
+
+## Quick Start
+
+```typescript
+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/`](./examples) for more:
+
+- Basic arithmetic with precedence
+- Comparison operators
+- Ternary expressions
+- Custom domain operators
+- Form validation
+
+## License
+
+MIT

package/dist/context.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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>.
+ */
+/**
+ * Schema value type: either a valid arktype type string or a nested object schema.
+ * This recursive type allows for nested object schemas like `{ x: { y: 'boolean' } }`.
+ */
+export type SchemaValue = string | {
+    readonly [key: string]: SchemaValue;
+};
+/**
+ * A schema record maps variable names to their type specifications.
+ * Values can be arktype type strings or nested object schemas.
+ */
+export type SchemaRecord = {
+    readonly [key: string]: SchemaValue;
+};
+/**
+ * Parse context with schema data.
+ *
+ * @typeParam TData - Schema mapping variable names to their types (strings or nested objects)
+ *
+ * @example
+ * ```ts
+ * type Ctx = Context<{ x: "number"; y: "string" }>;
+ * // x resolves to type "number", y resolves to type "string"
+ *
+ * type NestedCtx = Context<{ user: { name: "string"; age: "number" } }>;
+ * // user resolves to type { name: string; age: number }
+ * ```
+ */
+export interface Context<TData extends SchemaRecord = SchemaRecord> {
+    /** 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<{}>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAAA;CAAE,CAAC;AAE3E;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAAA;CAAE,CAAC;AAMnE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,OAAO,CAAC,KAAK,SAAS,YAAY,GAAG,YAAY;IAChE,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;CACtB;AAMD,0CAA0C;AAC1C,eAAO,MAAM,YAAY,EAAE,OAAO,CAAC,EAAE,CAAgB,CAAC;AAEtD,mCAAmC;AACnC,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC"}

package/dist/context.js

@@ -0,0 +1,14 @@
+/**
+ * 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: {} };
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyCH,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF,0CAA0C;AAC1C,MAAM,CAAC,MAAM,YAAY,GAAgB,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC"}

package/dist/createParser.d.ts

@@ -0,0 +1,159 @@
+/**
+ * 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
+ *   - Bound evaluator with type-safe data requirements
+ */
+import type { NodeSchema, SchemaToType } from './schema/index.js';
+import type { ComputeGrammar, Grammar } from './grammar/index.js';
+import type { Parse } from './parse/index.js';
+import type { Context, SchemaRecord } from './context.js';
+import { type } from 'arktype';
+export type { SchemaValue, SchemaRecord } from './context.js';
+/**
+ * Extract the outputSchema from an AST node type.
+ * Returns the literal schema string if present, otherwise 'unknown'.
+ */
+type ExtractOutputSchema<T> = T extends {
+    outputSchema: infer S;
+} ? S : 'unknown';
+/**
+ * Convert a SchemaRecord to its corresponding TypeScript data type.
+ * Maps each schema value to its runtime type using arktype.
+ *
+ * @example
+ * type Data = SchemaRecordToData<{ x: 'number'; y: 'string' }>;
+ * // { x: number; y: string }
+ */
+export type SchemaRecordToData<TSchema extends SchemaRecord> = {
+    [K in keyof TSchema]: TSchema[K] extends string ? SchemaToType<TSchema[K]> : TSchema[K] extends SchemaRecord ? SchemaRecordToData<TSchema[K]> : unknown;
+};
+/**
+ * A bound evaluator function returned by parser.parse().
+ *
+ * The evaluator:
+ * - Has the nodes pre-bound from the parser
+ * - Has the schema captured from the parse call
+ * - Requires data that matches the schema types
+ * - Returns a value with the type inferred from the AST's outputSchema
+ *
+ * @typeParam TAST - The parsed AST type
+ * @typeParam TSchema - The schema record type
+ *
+ * @example
+ * ```ts
+ * const [evaluator, err] = parser.parse('x + 1', { x: 'number' });
+ * if (!err) {
+ *   const value = evaluator({ x: 5 }); // value is number
+ *   const ast = evaluator.ast; // Access the parsed AST
+ * }
+ * ```
+ */
+export interface Evaluator<TAST, TSchema extends SchemaRecord> {
+    /**
+     * Evaluate the parsed expression with the given data.
+     *
+     * @param data - Variable values matching the schema types
+     * @returns The evaluated result with type inferred from outputSchema
+     */
+    (data: SchemaRecordToData<TSchema>): SchemaToType<ExtractOutputSchema<TAST>>;
+    /** The parsed AST */
+    readonly ast: TAST;
+    /** The schema used during parsing */
+    readonly schema: TSchema;
+}
+/**
+ * Result of parsing an expression.
+ *
+ * Returns a tuple of [evaluator, null] on success, or [null, error] on failure.
+ *
+ * @typeParam TAST - The parsed AST type
+ * @typeParam TSchema - The schema record type
+ */
+export type ParseResult<TAST, TSchema extends SchemaRecord> = [Evaluator<TAST, TSchema>, null] | [null, Error];
+/**
+ * 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 and return a bound evaluator.
+     *
+     * Schema values are validated at compile time using arktype.
+     * Invalid type strings like 'garbage' will cause TypeScript errors.
+     *
+     * @param input - The input string to parse
+     * @param schema - Schema mapping field names to valid arktype type strings or nested object schemas
+     * @returns A tuple of [evaluator, null] on success, or [null, error] on failure
+     *
+     * @example
+     * ```ts
+     * const [evaluator, err] = parser.parse("x + 1", { x: 'number' });
+     * if (!err) {
+     *   const value = evaluator({ x: 5 }); // value is number
+     *   const ast = evaluator.ast;
+     * }
+     *
+     * // Valid schema types:
+     * parser.parse("x + 1", { x: 'number' });        // primitive
+     * parser.parse("x + 1", { x: 'string.email' });  // subtype
+     * parser.parse("x + 1", { x: 'number >= 0' });   // constraint
+     * parser.parse("x + 1", { x: 'string | number' }); // union
+     *
+     * // Nested object schemas:
+     * parser.parse("user", { user: { name: 'string', age: 'number' } });
+     *
+     * // Invalid - causes compile error:
+     * // parser.parse("x + 1", { x: 'garbage' });
+     * ```
+     */
+    parse<TInput extends string, const TSchema extends SchemaRecord>(input: ValidatedInput<TGrammar, TInput, Context<TSchema>>, schema: type.validate<TSchema>): ParseResult<ExtractAST<Parse<TGrammar, TInput, Context<TSchema>>>, TSchema>;
+    /** The node schemas used to create this parser */
+    readonly nodes: TNodes;
+}
+/**
+ * Extract the AST from a Parse result type.
+ * Parse returns [AST, remaining] where remaining is '' on success.
+ */
+type ExtractAST<T> = T extends [infer AST, ''] ? AST : never;
+type ValidatedInput<TGrammar extends Grammar, TInput extends string, $ extends Context> = Parse<TGrammar, TInput, $> extends [unknown, ''] ? 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
+ * - Bound evaluator with type-safe data requirements
+ *
+ * @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";
+ *
+ * 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 parser = createParser([add] as const);
+ *
+ * // Type-safe parsing with bound evaluator!
+ * const [evaluator, err] = parser.parse("x + 1", { x: 'number' });
+ * if (!err) {
+ *   const value = evaluator({ x: 5 }); // value is number, equals 6
+ *   const ast = evaluator.ast;
+ * }
+ * ```
+ */
+export declare function createParser<const TNodes extends readonly NodeSchema[]>(nodes: TNodes): Parser<ComputeGrammar<TNodes>, TNodes>;
+//# sourceMappingURL=createParser.d.ts.map

package/dist/createParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createParser.d.ts","sourceRoot":"","sources":["../src/createParser.ts"],"names":[],"mappings":"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"}

package/dist/createParser.js

@@ -0,0 +1,118 @@
+/**
+ * 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
+ *   - Bound evaluator with type-safe data requirements
+ */
+import { parse as runtimeParse } from './runtime/parser.js';
+import { type } from 'arktype';
+import { evaluate } from './runtime/eval.js';
+// =============================================================================
+// Runtime Validation
+// =============================================================================
+/**
+ * Cache for arktype validators to avoid re-creating them for each validation.
+ */
+const validatorCache = new Map();
+/**
+ * Get or create an arktype validator for a schema.
+ */
+function getValidator(schema) {
+    // For nested objects, create a composite key
+    const key = typeof schema === 'string' ? schema : JSON.stringify(schema);
+    let validator = validatorCache.get(key);
+    if (!validator) {
+        validator = type(schema);
+        validatorCache.set(key, validator);
+    }
+    return validator;
+}
+/**
+ * Validate data against a schema at runtime.
+ * Throws an error if validation fails.
+ */
+function validateData(data, schema) {
+    const validator = getValidator(schema);
+    const result = validator(data);
+    if (result instanceof type.errors) {
+        throw new Error(`Data validation failed: ${result.summary}`);
+    }
+}
+// =============================================================================
+// 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
+ * - Bound evaluator with type-safe data requirements
+ *
+ * @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";
+ *
+ * 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 parser = createParser([add] as const);
+ *
+ * // Type-safe parsing with bound evaluator!
+ * const [evaluator, err] = parser.parse("x + 1", { x: 'number' });
+ * if (!err) {
+ *   const value = evaluator({ x: 5 }); // value is number, equals 6
+ *   const ast = evaluator.ast;
+ * }
+ * ```
+ */
+export function createParser(nodes) {
+    // Implementation function with explicit typing to avoid deep instantiation
+    const parse = (input, schema) => {
+        try {
+            // type.validate ensures all string values are valid arktype types
+            const context = { data: schema };
+            const result = runtimeParse(nodes, input, context);
+            // Check for parse failure (empty result or non-empty remaining)
+            if (!Array.isArray(result) || result.length !== 2) {
+                return [null, new Error(`Parse failed: unexpected result format`)];
+            }
+            const [ast, remaining] = result;
+            if (remaining !== '') {
+                return [null, new Error(`Parse failed: unexpected input at '${remaining}'`)];
+            }
+            // Create the bound evaluator
+            const evaluatorFn = (data) => {
+                // Validate data against schema at runtime
+                validateData(data, schema);
+                // Evaluate with the bound nodes - cast for internal use
+                // The type system ensures data matches the schema at compile time
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return evaluate(ast, { data, nodes });
+            };
+            // Create the evaluator object with call signature and properties
+            const evaluator = Object.assign(evaluatorFn, {
+                ast: ast,
+                schema: schema,
+            });
+            return [evaluator, null];
+        }
+        catch (error) {
+            return [null, error instanceof Error ? error : new Error(String(error))];
+        }
+    };
+    // Return the parser object - cast to avoid deep type checking
+    return { parse, nodes };
+}
+//# sourceMappingURL=createParser.js.map

package/dist/createParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createParser.js","sourceRoot":"","sources":["../src/createParser.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Error Types and Utilities
+ *
+ * Provides rich error information for parse failures including:
+ * - Position tracking (offset, line, column)
+ * - Source snippets showing where errors occurred
+ * - Descriptive messages for different error types
+ */
+/**
+ * Source position in the input string.
+ */
+export interface SourcePosition {
+    /** Zero-based character offset from start of input */
+    readonly offset: number;
+    /** One-based line number */
+    readonly line: number;
+    /** One-based column number (characters from start of line) */
+    readonly column: number;
+}
+/**
+ * Calculate position information from input and current offset.
+ *
+ * @param input - The original input string
+ * @param offset - Character offset into the input
+ * @returns Position with line and column numbers
+ */
+export declare function calculatePosition(input: string, offset: number): SourcePosition;
+/** Error kinds for categorization */
+export type ParseErrorKind = 'no_match' | 'type_mismatch' | 'unterminated_string' | 'unclosed_paren' | 'unexpected_token' | 'empty_input';
+/**
+ * Rich parse error with position and context information.
+ */
+export interface RichParseError {
+    /** Error marker for type discrimination */
+    readonly __error: true;
+    /** Error kind for categorization */
+    readonly kind: ParseErrorKind;
+    /** Human-readable error message */
+    readonly message: string;
+    /** Position where the error occurred */
+    readonly position: SourcePosition;
+    /** The problematic input snippet */
+    readonly snippet: string;
+    /** The full original input */
+    readonly input: string;
+    /** Additional context (e.g., expected type, actual type) */
+    readonly context?: ErrorContext;
+}
+/**
+ * Additional error context for specific error types.
+ */
+export interface ErrorContext {
+    /** Expected type for type mismatch errors */
+    expected?: string;
+    /** Actual type for type mismatch errors */
+    actual?: string;
+    /** What was being parsed when error occurred */
+    parsing?: string;
+}
+/**
+ * Create a snippet of the input around the error position.
+ *
+ * @param input - The full input string
+ * @param offset - Character offset where error occurred
+ * @param contextChars - Number of characters to show around the error
+ * @returns A snippet with error position marker
+ */
+export declare function createSnippet(input: string, offset: number, contextChars?: number): string;
+/**
+ * Create a RichParseError.
+ */
+export declare function createParseError(kind: ParseErrorKind, message: string, input: string, offset: number, context?: ErrorContext): RichParseError;
+/**
+ * Create a "no match" error.
+ */
+export declare function noMatchError(input: string, offset: number): RichParseError;
+/**
+ * Create a "type mismatch" error.
+ */
+export declare function typeMismatchError(input: string, offset: number, expected: string, actual: string, parsing?: string): RichParseError;
+/**
+ * Create an "unterminated string" error.
+ */
+export declare function unterminatedStringError(input: string, offset: number, quote: string): RichParseError;
+/**
+ * Create an "unclosed parenthesis" error.
+ */
+export declare function unclosedParenError(input: string, offset: number): RichParseError;
+/**
+ * Create an "unexpected token" error.
+ */
+export declare function unexpectedTokenError(input: string, offset: number, found: string, expected?: string): RichParseError;
+/**
+ * Create an "empty input" error.
+ */
+export declare function emptyInputError(input: string): RichParseError;
+import type { ASTNode } from './primitive/index.js';
+/**
+ * Extended parse result that can include error information.
+ * - Empty array: no match (backward compatible)
+ * - [node, remaining]: successful parse
+ * - [node, remaining, errors]: successful parse with collected errors
+ */
+export type ParseResultWithErrors<T extends ASTNode<string, unknown> = ASTNode<string, unknown>> = [] | [T & {}, string] | [T & {}, string, RichParseError[]];
+/**
+ * Check if a result includes errors.
+ */
+export declare function hasErrors(result: ParseResultWithErrors): boolean;
+/**
+ * Get errors from a result, or empty array if none.
+ */
+export declare function getErrors(result: ParseResultWithErrors): RichParseError[];
+/**
+ * Format an error for display with source context.
+ */
+export declare function formatError(error: RichParseError): string;
+/**
+ * Format multiple errors for display.
+ */
+export declare function formatErrors(errors: RichParseError[]): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}