@powersync/service-sync-rules 0.0.0-dev-20240708103353

package/dist/sql_filters.d.ts

@@ -0,0 +1,125 @@
+import { Expr, ExprRef, NodeLocation, SelectedColumn } from 'pgsql-ast-parser';
+import { nil } from 'pgsql-ast-parser/src/utils.js';
+import { SqlRuleError } from './errors.js';
+import { SqlFunction } from './sql_functions.js';
+import { ClauseError, CompiledClause, ParameterMatchClause, ParameterValueClause, QuerySchema, RowValueClause, StaticValueClause, TrueIfParametersMatch } from './types.js';
+export declare const MATCH_CONST_FALSE: TrueIfParametersMatch;
+export declare const MATCH_CONST_TRUE: TrueIfParametersMatch;
+export interface SqlToolsOptions {
+    /**
+     * Default table name, if any. I.e. SELECT FROM <table>.
+     *
+     * Used for to determine the table when using bare column names.
+     */
+    table?: string;
+    /**
+     * Set of tables used for FilterParameters.
+     *
+     * This is tables that can be used to filter the data on, e.g.:
+     *   "bucket" (bucket parameters for data query)
+     *   "token_parameters" (token parameters for parameter query)
+     */
+    parameter_tables?: string[];
+    /**
+     * Set of tables used in QueryParameters.
+     *
+     * If not specified, defaults to [table].
+     */
+    value_tables?: string[];
+    /**
+     * For debugging / error messages.
+     */
+    sql: string;
+    /**
+     * true if values in parameter tables can be expanded, i.e. `WHERE value IN parameters.something`.
+     *
+     * Only one parameter may be expanded.
+     */
+    supports_expanding_parameters?: boolean;
+    /**
+     * true if expressions on parameters are supported, e.g. upper(token_parameters.user_id)
+     */
+    supports_parameter_expressions?: boolean;
+    /**
+     * Schema for validations.
+     */
+    schema?: QuerySchema;
+}
+export declare class SqlTools {
+    default_table?: string;
+    value_tables: string[];
+    /**
+     * ['bucket'] for data queries
+     * ['token_parameters', 'user_parameters'] for parameter queries
+     */
+    parameter_tables: string[];
+    sql: string;
+    errors: SqlRuleError[];
+    supports_expanding_parameters: boolean;
+    supports_parameter_expressions: boolean;
+    schema?: QuerySchema;
+    constructor(options: SqlToolsOptions);
+    error(message: string, expr: NodeLocation | Expr | undefined): ClauseError;
+    warn(message: string, expr: NodeLocation | Expr | undefined): void;
+    /**
+     * Compile the where clause into a ParameterMatchClause.
+     *
+     * A ParameterMatchClause takes a data row, and returns filter values that
+     * would make the expression true for the row.
+     */
+    compileWhereClause(where: Expr | nil): ParameterMatchClause;
+    compileRowValueExtractor(expr: Expr | nil): RowValueClause | ClauseError;
+    compileParameterValueExtractor(expr: Expr | nil): ParameterValueClause | StaticValueClause | ClauseError;
+    /**
+     * Given an expression, return a compiled clause.
+     */
+    compileClause(expr: Expr | nil): CompiledClause;
+    /**
+     * "some_column" => "some_column"
+     * "table.some_column" => "some_column".
+     * "some_function() AS some_column" => "some_column"
+     * "some_function() some_column" => "some_column"
+     * "some_function()" => error
+     */
+    getOutputName(column: SelectedColumn): string;
+    getSpecificOutputName(column: SelectedColumn): string;
+    /**
+     * Check if an expression is a parameter_table reference.
+     */
+    isParameterRef(expr: Expr): expr is ExprRef;
+    /**
+     * Check if an expression is a value_tables reference.
+     *
+     * This means the expression can be evaluated directly on a value row.
+     */
+    isTableRef(expr: Expr): expr is ExprRef;
+    private checkRef;
+    getParameterRefClause(expr: ExprRef): ParameterValueClause;
+    refHasSchema(ref: ExprRef): boolean;
+    /**
+     * Get the table name from an expression.
+     *
+     * Only "value" tables are supported here, not parameter values.
+     */
+    getTableName(ref: ExprRef): string;
+    /**
+     * Given a function, compile a clause with the function over compiled arguments.
+     *
+     * For functions with multiple arguments, the following combinations are supported:
+     * fn(StaticValueClause, StaticValueClause) => StaticValueClause
+     * fn(ParameterValueClause, ParameterValueClause) => ParameterValueClause
+     * fn(RowValueClause, RowValueClause) => RowValueClause
+     * fn(ParameterValueClause, StaticValueClause) => ParameterValueClause
+     * fn(RowValueClause, StaticValueClause) => RowValueClause
+     *
+     * This is not supported, and will likely never be supported:
+     * fn(ParameterValueClause, RowValueClause) => error
+     *
+     * @param fnImpl The function or operator implementation
+     * @param argClauses The compiled argument clauses
+     * @param debugArgExpressions The original parsed expressions, for debug info only
+     * @returns a compiled function clause
+     */
+    composeFunction(fnImpl: SqlFunction, argClauses: CompiledClause[], debugArgExpressions: Expr[]): CompiledClause;
+    parameterFunction(): void;
+}