API reference

function parse(query: string, options?: ParseOptions): ParseResult;

const result = parse('age > 18 AND status = "active"');
if (result.success) {
  console.log(result.ast);
} else {
  console.error(result.message);
}

function parseOrThrow(query: string, options?: ParseOptions): ASTNode;

try {
  const ast = parseOrThrow('age > 18');
  console.log(ast);
} catch (error) {
  if (error instanceof FiltronParseError) {
    console.error('Parse failed at position', error.position, ':', error.message);
  }
}

class FiltronParseError extends Error {
  constructor(message: string, position?: number);
  position: number | undefined;
}

interface ParseOptions {
  maxLength?: number;
  maxDepth?: number;
}

type ParseResult = ParseSuccess | ParseFailure;

interface ParseSuccess {
  success: true;
  ast: ASTNode;
}

interface ParseFailure {
  success: false;
  message: string;
  position?: number;
}

function walk(node: ASTNode, visitor: (node: ASTNode) => boolean | undefined): void;

import { parseOrThrow, walk } from "@filtron/core";

const ast = parseOrThrow('age > 18 AND status = "active"');
const fields: string[] = [];
walk(ast, (node) => {
  if ("field" in node) {
    fields.push(node.field);
  }
});
// fields: ["age", "status"]

function print(node: ASTNode): string;

import { parseOrThrow, print } from "@filtron/core";

print(parseOrThrow("(a AND (b OR c))"));
// "a AND (b OR c)"

function validateFields(node: ASTNode, allowedFields: readonly string[]): void;

import { parseOrThrow, validateFields } from "@filtron/core";

const ast = parseOrThrow("password = \"hunter2\"");
validateFields(ast, ["name", "age"]);
// Error: Field "password" is not allowed. Allowed fields: name, age

class Lexer {
  constructor(input: string);
  next(): Token;
}

type Token = StringToken | NumberToken | BooleanToken | TemporalToken | SymbolToken;

type TokenType = "LPAREN" | "RPAREN" | "LBRACKET" | "RBRACKET" | "COMMA" | "QUESTION" | "DOT" | "DOTDOT" | "MINUS" | "AND" | "OR" | "NOT" | "TRUE" | "FALSE" | "EQ" | "NEQ" | "GT" | "GTE" | "LT" | "LTE" | "LIKE" | "COLON" | "NOT_COLON" | "STRING" | "NUMBER" | "IDENT" | "TEMPORAL" | "EOF";

interface StringToken extends TokenBase {
  type: "STRING" | "IDENT";
  value: string;
}

interface NumberToken extends TokenBase {
  type: "NUMBER";
  value: number;
}

interface BooleanToken extends TokenBase {
  type: "TRUE" | "FALSE";
  value: boolean;
}

interface SymbolToken extends TokenBase {
  type: "LPAREN" | "RPAREN" | "LBRACKET" | "RBRACKET" | "COMMA" | "QUESTION" | "DOT" | "DOTDOT" | "MINUS" | "AND" | "OR" | "NOT" | "EQ" | "NEQ" | "GT" | "GTE" | "LT" | "LTE" | "LIKE" | "COLON" | "NOT_COLON" | "EOF";
}

type ASTNode = OrExpression | AndExpression | NotExpression | ComparisonExpression | OneOfExpression | ExistsExpression | BooleanFieldExpression;

type Value = StringValue | NumberValue | BooleanValue | IdentifierValue | RangeValue | DateValue | NowValue;

type ComparisonOperator = "=" | "!=" | "~" | ">" | ">=" | "<" | "<=" | ":";

interface OrExpression {
  type: "or";
  children: ASTNode[];
}

interface AndExpression {
  type: "and";
  children: ASTNode[];
}

interface NotExpression {
  type: "not";
  expression: ASTNode;
}

interface ComparisonExpression {
  type: "comparison";
  field: string;
  operator: ComparisonOperator;
  value: Value;
}

interface OneOfExpression {
  type: "oneOf";
  field: string;
  values: Value[];
  negated: boolean;
}

interface ExistsExpression {
  type: "exists";
  field: string;
  negated: boolean;
}

interface BooleanFieldExpression {
  type: "booleanField";
  field: string;
}

interface StringValue {
  type: "string";
  value: string;
}

interface NumberValue {
  type: "number";
  value: number;
}

interface BooleanValue {
  type: "boolean";
  value: boolean;
}

interface IdentifierValue {
  type: "identifier";
  value: string;
}

type RangeValue = NumberRangeValue | TemporalRangeValue;

interface NumberRangeValue {
  type: "range";
  kind: "number";
  min: number;
  max: number;
}

interface TemporalRangeValue {
  type: "range";
  kind: "temporal";
  min: TemporalPoint;
  max: TemporalPoint;
}

interface DateValue {
  type: "date";
  value: string;
}

interface NowValue {
  type: "now";
  offset: {
    amount: number;
    unit: DurationUnit;
  } | null;
}

type TemporalPoint = DateValue | NowValue;

type DurationUnit = "s" | "m" | "h" | "d" | "w" | "M" | "y";

function toSQL(ast: ASTNode, options?: SQLOptions): SQLResult;

import { parse } from '@filtron/core';
import { toSQL } from '@filtron/sql';

const ast = parse('age > 18 AND status = "active"');
if (ast.success) {
  const { sql, params } = toSQL(ast.ast);
  console.log(sql);    // "age > $1 AND status = $2"
  console.log(params); // [18, "active"]
}

function escapeLike(value: string): string;

escapeLike("admin%") // "admin\\%"
escapeLike("test_user") // "test\\_user"

function contains(value: string | number | boolean): string;

contains("foo") // "%foo%"

function prefix(value: string | number | boolean): string;

toSQL(ast, { valueMapper: prefix })
// "admin" becomes "admin%"

function suffix(value: string | number | boolean): string;

toSQL(ast, { valueMapper: suffix })
// ".pdf" becomes "%.pdf"

interface SQLResult {
  sql: string;
  params: unknown[];
}

interface SQLOptions {
  dialect?: "postgres" | "mysql" | "sqlite";
  parameterStyle?: "numbered" | "question";
  fieldMapper?: (field: string) => string;
  valueMapper?: (value: string | number | boolean) => string | number | boolean;
  likeMode?: "contains" | "raw";
  startIndex?: number;
  allowedFields?: string[];
}