@gabrielbryk/jq-ts 1.1.0

package/dist/index.d.cts

@@ -0,0 +1,324 @@
+//#region src/span.d.ts
+interface Span {
+  start: number;
+  end: number;
+}
+//#endregion
+//#region src/ast.d.ts
+type LiteralValue = null | boolean | number | string;
+interface IdentityNode {
+  kind: 'Identity';
+  span: Span;
+}
+interface LiteralNode {
+  kind: 'Literal';
+  value: LiteralValue;
+  span: Span;
+}
+interface VarNode {
+  kind: 'Var';
+  name: string;
+  span: Span;
+}
+interface FieldAccessNode {
+  kind: 'FieldAccess';
+  target: FilterNode;
+  field: string;
+  span: Span;
+}
+interface IndexAccessNode {
+  kind: 'IndexAccess';
+  target: FilterNode;
+  index: FilterNode;
+  span: Span;
+}
+interface IterateNode {
+  kind: 'Iterate';
+  target: FilterNode;
+  span: Span;
+}
+interface ArrayNode {
+  kind: 'Array';
+  items: FilterNode[];
+  span: Span;
+}
+interface ObjectEntry {
+  key: ObjectKey;
+  value: FilterNode;
+}
+interface ObjectNode {
+  kind: 'Object';
+  entries: ObjectEntry[];
+  span: Span;
+}
+type ObjectKey = {
+  kind: 'KeyIdentifier';
+  name: string;
+  span: Span;
+} | {
+  kind: 'KeyString';
+  value: string;
+  span: Span;
+} | {
+  kind: 'KeyExpr';
+  expr: FilterNode;
+  span: Span;
+};
+interface PipeNode {
+  kind: 'Pipe';
+  left: FilterNode;
+  right: FilterNode;
+  span: Span;
+}
+interface CommaNode {
+  kind: 'Comma';
+  left: FilterNode;
+  right: FilterNode;
+  span: Span;
+}
+interface AltNode {
+  kind: 'Alt';
+  left: FilterNode;
+  right: FilterNode;
+  span: Span;
+}
+interface UnaryNode {
+  kind: 'Unary';
+  op: 'Neg' | 'Not';
+  expr: FilterNode;
+  span: Span;
+}
+interface BinaryNode {
+  kind: 'Binary';
+  op: '+' | '-' | '*' | '/' | '%' | 'Eq' | 'Neq' | 'Lt' | 'Lte' | 'Gt' | 'Gte';
+  left: FilterNode;
+  right: FilterNode;
+  span: Span;
+}
+interface BoolNode {
+  kind: 'Bool';
+  op: 'And' | 'Or';
+  left: FilterNode;
+  right: FilterNode;
+  span: Span;
+}
+interface IfBranch {
+  cond: FilterNode;
+  then: FilterNode;
+}
+interface IfNode {
+  kind: 'If';
+  branches: IfBranch[];
+  else: FilterNode;
+  span: Span;
+}
+interface AsNode {
+  kind: 'As';
+  bind: FilterNode;
+  name: string;
+  body: FilterNode;
+  span: Span;
+}
+interface CallNode {
+  kind: 'Call';
+  name: string;
+  args: FilterNode[];
+  span: Span;
+}
+interface ReduceNode {
+  kind: 'Reduce';
+  source: FilterNode;
+  var: string;
+  init: FilterNode;
+  update: FilterNode;
+  span: Span;
+}
+interface ForeachNode {
+  kind: 'Foreach';
+  source: FilterNode;
+  var: string;
+  init: FilterNode;
+  update: FilterNode;
+  extract?: FilterNode;
+  span: Span;
+}
+interface TryNode {
+  kind: 'Try';
+  body: FilterNode;
+  handler?: FilterNode;
+  span: Span;
+}
+interface RecurseNode {
+  kind: 'Recurse';
+  span: Span;
+}
+type FilterNode = IdentityNode | LiteralNode | VarNode | FieldAccessNode | IndexAccessNode | IterateNode | ArrayNode | ObjectNode | PipeNode | CommaNode | AltNode | UnaryNode | BinaryNode | BoolNode | IfNode | AsNode | CallNode | ReduceNode | ForeachNode | TryNode | RecurseNode;
+//#endregion
+//#region src/parser.d.ts
+/**
+ * Parses a jq source string into an Abstract Syntax Tree (AST).
+ *
+ * @param source - The input jq query string.
+ * @returns The root {@link FilterNode} of the AST.
+ * @throws {LexError} If the source contains invalid characters.
+ * @throws {ParseError} If the syntax is invalid.
+ */
+declare const parse: (source: string) => FilterNode;
+//#endregion
+//#region src/validate.d.ts
+/**
+ * Validates the AST for correctness and supported features.
+ * Checks for unknown function calls and arity mismatches.
+ *
+ * @param node - The root AST node to validate.
+ * @throws {ValidationError} If validation fails.
+ */
+declare const validate: (node: FilterNode) => void;
+//#endregion
+//#region src/limits.d.ts
+/**
+ * Configuration options for execution limits.
+ * All fields are optional and default to safe values if strictly undefined.
+ */
+interface LimitsConfig {
+  /** Maximum number of AST nodes to visit during execution. Default: 100,000. */
+  maxSteps?: number;
+  /** Maximum recursion depth for execution and parsing. Default: 200. */
+  maxDepth?: number;
+  /** Maximum number of values to yield from a single output emitter. Default: 10,000. */
+  maxOutputs?: number;
+}
+/**
+ * Fully resolved limits with defaults applied.
+ */
+interface ResolvedLimits {
+  maxSteps: number;
+  maxDepth: number;
+  maxOutputs: number;
+}
+/**
+ * Resolves a partial limits configuration into a complete one with defaults.
+ *
+ * @param config - The user-provided configuration.
+ * @returns The resolved limits.
+ */
+declare const resolveLimits: (config?: LimitsConfig) => ResolvedLimits;
+/**
+ * Tracks execution usage against defined limits.
+ * Throws {@link RuntimeError} if any limit is exceeded.
+ */
+declare class LimitTracker {
+  private readonly limits;
+  private steps;
+  private depth;
+  private outputs;
+  constructor(limits: ResolvedLimits);
+  /**
+   * Records a single execution step (AST node visit).
+   * @param span - The source span for error reporting.
+   */
+  step(span: Span): void;
+  /**
+   * Enters a new scope/stack frame, incrementing the depth counter.
+   * @param span - The source span for error reporting.
+   */
+  enter(span: Span): void;
+  /**
+   * Exits the current scope, decrementing the depth counter.
+   */
+  exit(): void;
+  /**
+   * Records an output value being emitted.
+   * @param span - The source span for error reporting.
+   */
+  emit(span: Span): void;
+}
+//#endregion
+//#region src/value.d.ts
+/**
+ * Represents any valid JSON value supported by the jq-ts runtime.
+ * This is a recursive type definition that matches the structure of JSON data.
+ */
+type Value = null | boolean | number | string | ValueArray | ValueObject;
+/**
+ * Represents a JSON array containing {@link Value} items.
+ */
+interface ValueArray extends Array<Value> {}
+/**
+ * Represents a JSON object with string keys and {@link Value} values.
+ */
+interface ValueObject {
+  [key: string]: Value;
+}
+//#endregion
+//#region src/eval.d.ts
+interface EvalOptions {
+  limits?: LimitsConfig;
+}
+declare const runAst: (ast: FilterNode, input: Value, options?: EvalOptions) => Value[];
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Categories of errors that can occur during processing.
+ * - `lex`: Errors during lexical analysis (invalid characters).
+ * - `parse`: Errors during parsing (syntax errors).
+ * - `validate`: Errors during semantics checking (unsupported features).
+ * - `runtime`: Errors during execution (type errors, limits).
+ */
+type ErrorKind = 'lex' | 'parse' | 'validate' | 'runtime';
+/**
+ * Common interface for all errors thrown by the jq-ts library.
+ */
+interface JqTsError extends Error {
+  /** The category of the error. */
+  kind: ErrorKind;
+  /** The source code span where the error occurred. */
+  span: Span;
+}
+declare class BaseError extends Error implements JqTsError {
+  kind: ErrorKind;
+  span: Span;
+  constructor(kind: ErrorKind, message: string, span: Span);
+}
+/**
+ * Thrown when the lexer encounters invalid input characters.
+ */
+declare class LexError extends BaseError {
+  constructor(message: string, span: Span);
+}
+/**
+ * Thrown when the parser encounters invalid syntax.
+ */
+declare class ParseError extends BaseError {
+  constructor(message: string, span: Span);
+}
+/**
+ * Thrown when the AST contains unsupported or invalid features (e.g., restricted operators).
+ */
+declare class ValidationError extends BaseError {
+  constructor(message: string, span: Span);
+}
+/**
+ * Thrown during execution for runtime issues (type errors, limits exceeded, user-raised errors).
+ */
+declare class RuntimeError extends BaseError {
+  constructor(message: string, span: Span);
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Runs a jq query against a JSON input.
+ *
+ * @param source - The jq query string (e.g., `.foo | .bar`).
+ * @param input - The JSON input value (object, array, string, number, boolean, or null).
+ * @param options - Execution options including limits.
+ * @returns An array of results. jq queries always produce zero or more values.
+ * @throws {LexError} If the query contains invalid characters.
+ * @throws {ParseError} If the query syntax is invalid.
+ * @throws {ValidationError} If the query uses unsupported features.
+ * @throws {RuntimeError} If execution fails (e.g., type error) or exceeds limits.
+ */
+declare const run: (source: string, input: Value, options?: EvalOptions) => Value[];
+//#endregion
+export { type EvalOptions, LexError, LimitTracker, type LimitsConfig, ParseError, type ResolvedLimits, RuntimeError, ValidationError, type Value, parse, resolveLimits, run, runAst, validate };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/span.ts","../src/ast.ts","../src/parser.ts","../src/validate.ts","../src/limits.ts","../src/value.ts","../src/eval.ts","../src/errors.ts","../src/index.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/index.d.mts

@@ -0,0 +1,324 @@
+//#region src/span.d.ts
+interface Span {
+  start: number;
+  end: number;
+}
+//#endregion
+//#region src/ast.d.ts
+type LiteralValue = null | boolean | number | string;
+interface IdentityNode {
+  kind: 'Identity';
+  span: Span;
+}
+interface LiteralNode {
+  kind: 'Literal';
+  value: LiteralValue;
+  span: Span;
+}
+interface VarNode {
+  kind: 'Var';
+  name: string;
+  span: Span;
+}
+interface FieldAccessNode {
+  kind: 'FieldAccess';
+  target: FilterNode;
+  field: string;
+  span: Span;
+}
+interface IndexAccessNode {
+  kind: 'IndexAccess';
+  target: FilterNode;
+  index: FilterNode;
+  span: Span;
+}
+interface IterateNode {
+  kind: 'Iterate';
+  target: FilterNode;
+  span: Span;
+}
+interface ArrayNode {
+  kind: 'Array';
+  items: FilterNode[];
+  span: Span;
+}
+interface ObjectEntry {
+  key: ObjectKey;
+  value: FilterNode;
+}
+interface ObjectNode {
+  kind: 'Object';
+  entries: ObjectEntry[];
+  span: Span;
+}
+type ObjectKey = {
+  kind: 'KeyIdentifier';
+  name: string;
+  span: Span;
+} | {
+  kind: 'KeyString';
+  value: string;
+  span: Span;
+} | {
+  kind: 'KeyExpr';
+  expr: FilterNode;
+  span: Span;
+};
+interface PipeNode {
+  kind: 'Pipe';
+  left: FilterNode;
+  right: FilterNode;
+  span: Span;
+}
+interface CommaNode {
+  kind: 'Comma';
+  left: FilterNode;
+  right: FilterNode;
+  span: Span;
+}
+interface AltNode {
+  kind: 'Alt';
+  left: FilterNode;
+  right: FilterNode;
+  span: Span;
+}
+interface UnaryNode {
+  kind: 'Unary';
+  op: 'Neg' | 'Not';
+  expr: FilterNode;
+  span: Span;
+}
+interface BinaryNode {
+  kind: 'Binary';
+  op: '+' | '-' | '*' | '/' | '%' | 'Eq' | 'Neq' | 'Lt' | 'Lte' | 'Gt' | 'Gte';
+  left: FilterNode;
+  right: FilterNode;
+  span: Span;
+}
+interface BoolNode {
+  kind: 'Bool';
+  op: 'And' | 'Or';
+  left: FilterNode;
+  right: FilterNode;
+  span: Span;
+}
+interface IfBranch {
+  cond: FilterNode;
+  then: FilterNode;
+}
+interface IfNode {
+  kind: 'If';
+  branches: IfBranch[];
+  else: FilterNode;
+  span: Span;
+}
+interface AsNode {
+  kind: 'As';
+  bind: FilterNode;
+  name: string;
+  body: FilterNode;
+  span: Span;
+}
+interface CallNode {
+  kind: 'Call';
+  name: string;
+  args: FilterNode[];
+  span: Span;
+}
+interface ReduceNode {
+  kind: 'Reduce';
+  source: FilterNode;
+  var: string;
+  init: FilterNode;
+  update: FilterNode;
+  span: Span;
+}
+interface ForeachNode {
+  kind: 'Foreach';
+  source: FilterNode;
+  var: string;
+  init: FilterNode;
+  update: FilterNode;
+  extract?: FilterNode;
+  span: Span;
+}
+interface TryNode {
+  kind: 'Try';
+  body: FilterNode;
+  handler?: FilterNode;
+  span: Span;
+}
+interface RecurseNode {
+  kind: 'Recurse';
+  span: Span;
+}
+type FilterNode = IdentityNode | LiteralNode | VarNode | FieldAccessNode | IndexAccessNode | IterateNode | ArrayNode | ObjectNode | PipeNode | CommaNode | AltNode | UnaryNode | BinaryNode | BoolNode | IfNode | AsNode | CallNode | ReduceNode | ForeachNode | TryNode | RecurseNode;
+//#endregion
+//#region src/parser.d.ts
+/**
+ * Parses a jq source string into an Abstract Syntax Tree (AST).
+ *
+ * @param source - The input jq query string.
+ * @returns The root {@link FilterNode} of the AST.
+ * @throws {LexError} If the source contains invalid characters.
+ * @throws {ParseError} If the syntax is invalid.
+ */
+declare const parse: (source: string) => FilterNode;
+//#endregion
+//#region src/validate.d.ts
+/**
+ * Validates the AST for correctness and supported features.
+ * Checks for unknown function calls and arity mismatches.
+ *
+ * @param node - The root AST node to validate.
+ * @throws {ValidationError} If validation fails.
+ */
+declare const validate: (node: FilterNode) => void;
+//#endregion
+//#region src/limits.d.ts
+/**
+ * Configuration options for execution limits.
+ * All fields are optional and default to safe values if strictly undefined.
+ */
+interface LimitsConfig {
+  /** Maximum number of AST nodes to visit during execution. Default: 100,000. */
+  maxSteps?: number;
+  /** Maximum recursion depth for execution and parsing. Default: 200. */
+  maxDepth?: number;
+  /** Maximum number of values to yield from a single output emitter. Default: 10,000. */
+  maxOutputs?: number;
+}
+/**
+ * Fully resolved limits with defaults applied.
+ */
+interface ResolvedLimits {
+  maxSteps: number;
+  maxDepth: number;
+  maxOutputs: number;
+}
+/**
+ * Resolves a partial limits configuration into a complete one with defaults.
+ *
+ * @param config - The user-provided configuration.
+ * @returns The resolved limits.
+ */
+declare const resolveLimits: (config?: LimitsConfig) => ResolvedLimits;
+/**
+ * Tracks execution usage against defined limits.
+ * Throws {@link RuntimeError} if any limit is exceeded.
+ */
+declare class LimitTracker {
+  private readonly limits;
+  private steps;
+  private depth;
+  private outputs;
+  constructor(limits: ResolvedLimits);
+  /**
+   * Records a single execution step (AST node visit).
+   * @param span - The source span for error reporting.
+   */
+  step(span: Span): void;
+  /**
+   * Enters a new scope/stack frame, incrementing the depth counter.
+   * @param span - The source span for error reporting.
+   */
+  enter(span: Span): void;
+  /**
+   * Exits the current scope, decrementing the depth counter.
+   */
+  exit(): void;
+  /**
+   * Records an output value being emitted.
+   * @param span - The source span for error reporting.
+   */
+  emit(span: Span): void;
+}
+//#endregion
+//#region src/value.d.ts
+/**
+ * Represents any valid JSON value supported by the jq-ts runtime.
+ * This is a recursive type definition that matches the structure of JSON data.
+ */
+type Value = null | boolean | number | string | ValueArray | ValueObject;
+/**
+ * Represents a JSON array containing {@link Value} items.
+ */
+interface ValueArray extends Array<Value> {}
+/**
+ * Represents a JSON object with string keys and {@link Value} values.
+ */
+interface ValueObject {
+  [key: string]: Value;
+}
+//#endregion
+//#region src/eval.d.ts
+interface EvalOptions {
+  limits?: LimitsConfig;
+}
+declare const runAst: (ast: FilterNode, input: Value, options?: EvalOptions) => Value[];
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Categories of errors that can occur during processing.
+ * - `lex`: Errors during lexical analysis (invalid characters).
+ * - `parse`: Errors during parsing (syntax errors).
+ * - `validate`: Errors during semantics checking (unsupported features).
+ * - `runtime`: Errors during execution (type errors, limits).
+ */
+type ErrorKind = 'lex' | 'parse' | 'validate' | 'runtime';
+/**
+ * Common interface for all errors thrown by the jq-ts library.
+ */
+interface JqTsError extends Error {
+  /** The category of the error. */
+  kind: ErrorKind;
+  /** The source code span where the error occurred. */
+  span: Span;
+}
+declare class BaseError extends Error implements JqTsError {
+  kind: ErrorKind;
+  span: Span;
+  constructor(kind: ErrorKind, message: string, span: Span);
+}
+/**
+ * Thrown when the lexer encounters invalid input characters.
+ */
+declare class LexError extends BaseError {
+  constructor(message: string, span: Span);
+}
+/**
+ * Thrown when the parser encounters invalid syntax.
+ */
+declare class ParseError extends BaseError {
+  constructor(message: string, span: Span);
+}
+/**
+ * Thrown when the AST contains unsupported or invalid features (e.g., restricted operators).
+ */
+declare class ValidationError extends BaseError {
+  constructor(message: string, span: Span);
+}
+/**
+ * Thrown during execution for runtime issues (type errors, limits exceeded, user-raised errors).
+ */
+declare class RuntimeError extends BaseError {
+  constructor(message: string, span: Span);
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Runs a jq query against a JSON input.
+ *
+ * @param source - The jq query string (e.g., `.foo | .bar`).
+ * @param input - The JSON input value (object, array, string, number, boolean, or null).
+ * @param options - Execution options including limits.
+ * @returns An array of results. jq queries always produce zero or more values.
+ * @throws {LexError} If the query contains invalid characters.
+ * @throws {ParseError} If the query syntax is invalid.
+ * @throws {ValidationError} If the query uses unsupported features.
+ * @throws {RuntimeError} If execution fails (e.g., type error) or exceeds limits.
+ */
+declare const run: (source: string, input: Value, options?: EvalOptions) => Value[];
+//#endregion
+export { type EvalOptions, LexError, LimitTracker, type LimitsConfig, ParseError, type ResolvedLimits, RuntimeError, ValidationError, type Value, parse, resolveLimits, run, runAst, validate };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/span.ts","../src/ast.ts","../src/parser.ts","../src/validate.ts","../src/limits.ts","../src/value.ts","../src/eval.ts","../src/errors.ts","../src/index.ts"],"sourcesContent":[],"mappings":"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"}