React-Awesome-Query-Builder

React-Awesome-Query-Builder is a highly configurable, user-friendly React component designed to build complex queries (filters). It is inspired by jQuery QueryBuilder and supports various UI frameworks including Ant Design, Material-UI (MUI), Bootstrap, and Fluent UI.

Key capabilities include:

• Complex Data Types: Supports simple types (string, number, bool, date/time, list) and complex types (structs, arrays).
• Advanced Query Logic: Supports aggregation (e.g., COUNT OF users WHERE ... > 5), field-to-field comparisons, and nested functions.
• Flexible Operators: Supports binary, unary, 'between', and complex operators like 'proximity'.
• Ternary Mode: Supports if-then-else logic.
• Multi-format Export/Import: Export to MongoDB, SQL, JsonLogic, SpEL, or ElasticSearch; Import from JsonLogic, SpEL, or SQL.
• UI Features: Drag-and-drop reordering for rules and groups, and support for saving/loading query values and configurations from a server.

The config.ctx (Context) is a collection of JavaScript functions and React components used to isolate non-serializable parts of your configuration. This is essential when you want to serialize your configuration to JSON (creating a zipConfig).

The Pattern:

1. Instead of importing modules directly into your fields or widgets config, add them to ctx.
2. In your configuration, refer to these items by their string name.
3. Use Utils.ConfigUtils.decompressConfig(zipConfig, BaseConfig, ctx) to reconstruct the full configuration.

Example Workflow:

import { BasicConfig } from '@react-awesome-query-builder/ui';

// 1. Define the serializable part (zipConfig)
const zipConfig = {
  fields: {
    firstName: {
      type: "text",
      fieldSettings: {
        validateValue: "validateFirstName", // Reference by name
      }
    },
  },
  settings: {
    useConfigCompress: true,
  },
};

// 2. Define the non-serializable part (ctx)
const ctx = {
  ...BasicConfig.ctx,
  validateFirstName: (val: string) => val.length < 10,
};

// 3. Reconstruct
const config = Utils.ConfigUtils.decompressConfig(zipConfig, BasicConfig, ctx);

import {BasicConfig} from '@react-awesome-query-builder/ui';

const fields = {
  firstName: {
    type: "text",
    fieldSettings: {
      // use function `validateFirstName` from `ctx` by name
      validateValue: "validateFirstName",
    }
  },
};

const ctx = {
  ...BasicConfig.ctx,
  validateFirstName: (val: string) => {
    return (val.length < 10);
  },
};

// `zipConfig` can be passed to backend as JSON
const zipConfig = {
  fields,
  settings: {
    useConfigCompress: true, // this is required to use Utils.ConfigUtils.decompressConfig()
  },
  // you can add here other sections like `widgets` or `types`, but don't add `ctx`
};

// Config can be loaded from backend with providing `ctx`
const config = Utils.ConfigUtils.decompressConfig(zipConfig, BasicConfig, ctx);

The library is modularized into several packages to allow for different use cases (frontend vs. backend) and UI preferences:

• @react-awesome-query-builder/core: Contains core functionality for importing/exporting and storing queries, along with utility functions. Use this on the server-side (Node.js) to perform exports (e.g., to SQL) for security.
• @react-awesome-query-builder/ui: Provides core React components like <Query> and <Builder>, CSS, and basic (vanilla) widgets. It re-exports from core.
• Framework-specific packages: These provide configurations with specific UI widgets and re-export from ui. Use these on the frontend:
  • @react-awesome-query-builder/antd: Ant Design widgets.
  • @react-awesome-query-builder/mui: MUI widgets.
  • @react-awesome-query-builder/bootstrap: Bootstrap widgets.
  • @react-awesome-query-builder/fluent: Fluent UI widgets.
  • @react-awesome-query-builder/material: Material-UI v4 widgets (deprecated).

Dependency Flow: core $\rightarrow$ ui $\rightarrow$ [framework-specific packages]

The sandbox-next package is a Next.js demo application designed to demonstrate Server-Side Rendering (SSR) capabilities with @react-awesome-query-builder.

Key Concepts

SSR with Session Data

To enable SSR, the application saves and loads two primary pieces of data from a session (using Redis or a local JSON file via lib/withSession.ts):

• jsonTree: The query value in JSON format (obtained via Utils.getTree()).
• zipConfig: A compressed query configuration in JSON format (obtained via Utils.ConfigUtils.compressConfig()).

Server-Side API Endpoints

The application uses several Next.js API routes to manage state and data conversion:

• /api/tree: Manages the jsonTree. It can save the tree to the session via POST and load it via GET. It also performs server-side conversion of the tree into formats like JsonLogic, SQL, MongoDB, and SpEL.
• /api/config: Manages the zipConfig. It can save the compressed config via POST and load it via GET.
• /api/autocomplete: Provides autocomplete functionality (used by asyncFetch).

Configuration Lifecycle

The configuration (zipConfig) is generated on the server-side by:

1. Starting with CoreConfig from @react-awesome-query-builder/core.
2. Adding fields, functions, and overrides in lib/config_base.ts.
3. Adding UI mixins (like asyncFetch, custom React components, and factory overrides) in lib/config.tsx.
4. Compressing the result using Utils.ConfigUtils.compressConfig().