docs: add JSDoc for exported API

Author: ClaudiuCeia

mod.ts

@@ -1,4 +1,4 @@
-export type { Expr, NodeBase, Span } from "./src/ast/mod.ts";
+export type { BinaryOp, Expr, NodeBase, Span, UnaryOp } from "./src/ast/mod.ts";
 export {
   formatCaret,
   type FormatCaretOptions,
@@ -24,5 +24,9 @@ export {
   evaluateExpression,
   type EvaluateExpressionOptions,
   ExpEvalError,
+  type RuntimeArray,
+  type RuntimeFunction,
+  type RuntimeObject,
+  type RuntimePrimitive,
   type RuntimeValue,
 } from "./src/eval.ts";

src/ast/mod.ts

@@ -1,14 +1,23 @@
+/**
+ * Byte span (half-open) into the original input.
+ *
+ * - `start` is inclusive
+ * - `end` is exclusive
+ */
 export type Span = Readonly<{
   start: number;
   end: number;
 }>;
 
+/** Base fields common to all AST nodes. */
 export type NodeBase = Readonly<{
   span: Span;
 }>;
 
+/** Unary operator tokens supported by the expression language. */
 export type UnaryOp = "!" | "-" | "+";
 
+/** Binary operator tokens supported by the expression language. */
 export type BinaryOp =
   | "+"
   | "-"
@@ -24,6 +33,11 @@ export type BinaryOp =
   | "&&"
   | "||";
 
+/**
+ * Expression AST node.
+ *
+ * Every node includes a `span` into the original input for diagnostics.
+ */
 export type Expr =
   | (NodeBase & { kind: "number"; value: number })
   | (NodeBase & { kind: "string"; value: string })
@@ -42,6 +56,7 @@ export type Expr =
     alternate: Expr;
   });
 
+/** Create a unary expression node. */
 export const mkUnary = (op: UnaryOp, start: number, expr: Expr): Expr => {
   return {
     kind: "unary",
@@ -51,6 +66,7 @@ export const mkUnary = (op: UnaryOp, start: number, expr: Expr): Expr => {
   };
 };
 
+/** Create a binary expression node. */
 export const mkBinary = (left: Expr, op: BinaryOp, right: Expr): Expr => {
   return {
     kind: "binary",
@@ -61,6 +77,7 @@ export const mkBinary = (left: Expr, op: BinaryOp, right: Expr): Expr => {
   };
 };
 
+/** Create a member access node (`object.property`). */
 export const mkMember = (
   object: Expr,
   property: { value: string; end: number },
@@ -73,6 +90,7 @@ export const mkMember = (
   };
 };
 
+/** Create a call node (`callee(args...)`). */
 export const mkCall = (callee: Expr, args: Expr[], end: number): Expr => {
   return {
     kind: "call",

src/diagnostics.ts

@@ -1,12 +1,14 @@
 import type { Span } from "./ast/mod.ts";
 
+/** Options for `formatCaret` / `formatSpanCaret`. */
 export type FormatCaretOptions = Readonly<{
   /** Max characters to include before the index. Default: 40 */
   before?: number;
   /** Max characters to include after the index. Default: 40 */
   after?: number;
 }>;
 
+/** Options for `formatDiagnosticReport`. */
 export type FormatReportOptions = Readonly<{
   /** Include N lines before/after the error line. Default: 0 */
   contextLines?: number;
@@ -74,6 +76,7 @@ export const formatCaret = (
   return `${snippet}\n${" ".repeat(caretPos)}^`;
 };
 
+/** Format a caret snippet from an AST `span` (uses `span.start`). */
 export const formatSpanCaret = (
   input: string,
   span: Span,
@@ -82,6 +85,7 @@ export const formatSpanCaret = (
   return formatCaret(input, span.start, opts);
 };
 
+/** Input for `formatDiagnosticCaret`. */
 export type FormatDiagnosticCaretSource = Readonly<{
   index?: number;
   span?: Span;
@@ -103,6 +107,7 @@ export const formatDiagnosticCaret = (
   return formatCaret(input, 0, opts);
 };
 
+/** Input for `formatDiagnosticReport`. */
 export type FormatDiagnosticReportSource = Readonly<{
   index?: number;
   span?: Span;

src/eval.ts

@@ -1,22 +1,34 @@
 import type { Expr, Span } from "./ast/mod.ts";
 import { parseExpression } from "./parse.ts";
 
+/** Primitive runtime values supported by the evaluator. */
 export type RuntimePrimitive = undefined | null | boolean | number | string;
 
+/** A function callable from expressions (must accept/return `RuntimeValue`). */
 export type RuntimeFunction = (...args: RuntimeValue[]) => RuntimeValue;
 
+/** A `RuntimeValue` array. */
 export interface RuntimeArray extends Array<RuntimeValue> {}
 
+/** A plain object mapping string keys to `RuntimeValue`. */
 export interface RuntimeObject {
+  /** Own enumerable properties (prototype is ignored by the evaluator). */
   [key: string]: RuntimeValue;
 }
 
+/**
+ * Allowed runtime data model for evaluation.
+ *
+ * Values are validated at runtime when present in `env`, and function return
+ * values are also validated.
+ */
 export type RuntimeValue =
   | RuntimePrimitive
   | RuntimeArray
   | RuntimeObject
   | RuntimeFunction;
 
+/** Options for `evaluateAst` and `evaluateExpression`. */
 export type EvalOptions = Readonly<{
   /**
    * Identifier bindings available to the expression.
@@ -50,6 +62,12 @@ export type EvalOptions = Readonly<{
   throwOnError?: boolean;
 }>;
 
+/**
+ * An evaluation failure.
+ *
+ * - `span` is present for errors tied to a specific AST node.
+ * - `index` is present when evaluation failed because parsing failed.
+ */
 export type EvalError = Readonly<{
   message: string;
   span?: Span;
@@ -58,11 +76,20 @@ export type EvalError = Readonly<{
   index?: number;
 }>;
 
+/**
+ * Thrown evaluation error (default mode).
+ *
+ * Carries either `span` (eval failures) and/or `index` (parse failures).
+ */
 export class ExpEvalError extends Error {
+  /** AST span for eval errors tied to a node. */
   readonly span?: Span;
+  /** Step counter at the time of failure (useful with budgets). */
   readonly steps?: number;
+  /** Byte index into input when the failure originated from parsing. */
   readonly index?: number;
 
+  /** Create an `ExpEvalError` from an `EvalError` payload. */
   constructor(error: EvalError) {
     super(error.message);
     this.name = "ExpEvalError";
@@ -72,6 +99,7 @@ export class ExpEvalError extends Error {
   }
 }
 
+/** Result returned by `evaluateAst` / `evaluateExpression` in non-throwing mode. */
 export type EvalResult =
   | Readonly<{ success: true; value: RuntimeValue }>
   | Readonly<{ success: false; error: EvalError }>;
@@ -416,6 +444,7 @@ const evalExpr = (expr: Expr, ctx: Ctx): EvalResult => {
   }
 };
 
+/** Evaluate a pre-parsed AST. */
 export function evaluateAst(expr: Expr, opts: EvalOptions = {}): EvalResult {
   const throwOnError = opts.throwOnError ?? true;
 
@@ -442,14 +471,20 @@ export function evaluateAst(expr: Expr, opts: EvalOptions = {}): EvalResult {
   return res;
 }
 
+/** Options for `evaluateExpression` (includes all `EvalOptions`). */
 export type EvaluateExpressionOptions =
   & EvalOptions
   & Readonly<{
     /** When true, throw on parse failure. Default: true */
     throwOnParseError?: boolean;
   }>;
 
-/** Parse + evaluate a single expression. */
+/**
+ * Parse + evaluate a single expression.
+ *
+ * If `throwOnParseError: false`, parse failures return an `EvalError` that
+ * includes `index` so callers can render diagnostics.
+ */
 export function evaluateExpression(
   input: string,
   opts: EvaluateExpressionOptions = {},

src/parse.ts

@@ -30,23 +30,37 @@ import {
 } from "./ast/mod.ts";
 import { createStringSpan } from "./string_literal.ts";
 
+/** Options for `parseExpression`. */
 export type ParseOptions = Readonly<{
   /** When true, throw on parse failure. Default: true */
   throwOnError?: boolean;
 }>;
 
+/**
+ * A parse failure.
+ *
+ * `index` is a byte index into the input string.
+ */
 export type ParseError = Readonly<{
   message: string;
   index: number;
 }>;
 
+/** Result of `parseExpression`. */
 export type ParseResult =
   | Readonly<{ success: true; value: Expr }>
   | Readonly<{ success: false; error: ParseError }>;
 
+/**
+ * Thrown parse error (default mode).
+ *
+ * Carries the byte `index` into the original input.
+ */
 export class ExpParseError extends Error {
+  /** Byte index into the input string where parsing failed. */
   readonly index: number;
 
+  /** Create an `ExpParseError` from a `ParseError` payload. */
   constructor(error: ParseError) {
     super(error.message);
     this.name = "ExpParseError";
@@ -370,7 +384,13 @@ const ExpressionLang: ExprLang = createLanguage<ExprLang>({
   File: (s) => map(seq(lx.trivia, s.Expression, eof()), ([, e]) => e),
 });
 
-/** Parse a single expression. */
+/**
+ * Parse a single expression into an AST.
+ *
+ * - On success: returns `{ success: true, value }`.
+ * - On failure: throws `ExpParseError` by default.
+ *   Set `throwOnError: false` to get `{ success: false, error }`.
+ */
 export function parseExpression(
   input: string,
   opts: ParseOptions = {},