Flux Query Builder

A lightweight, fluent, and type-safe query builder for InfluxDB's Flux language, written in TypeScript.

This library helps you construct complex Flux queries programmatically, reducing the risk of syntax errors and making your code more readable and maintainable.

Features

• Fluent, chainable API for building queries step-by-step.
• Type-safe methods and parameters.
• Generates clean, readable Flux script.
• Zero dependencies.

Installation

Install the package using your favorite package manager:

npm install flux-query-builder

or

yarn add flux-query-builder

or

pnpm add flux-query-builder

Usage

Here's how you can use flux-query-builder to create queries.

Basic Query

import { FluxQueryBuilder } from 'flux-query-builder';

const query = new FluxQueryBuilder()
  .from({ bucket: 'my-awesome-bucket' })
  .range({ start: '-1h' })
  .filter({
    fn: (r) => r._measurement === 'cpu' && r._field === 'usage_system' && r.cpu === 'cpu-total',
  })
  .toString();

console.log(query);

This will generate the following Flux script:

from(bucket: "my-awesome-bucket")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system" and r.cpu == "cpu-total")

Advanced Query with Aggregation

You can easily chain more functions to create complex queries, like windowing and aggregations.

import { FluxQueryBuilder } from 'flux-query-builder';

const query = new FluxQueryBuilder()
  .from({ bucket: 'my-awesome-bucket' })
  .range({ start: '-7d', stop: 'now()' })
  .filter({
    fn: (r) => r._measurement === 'system' && r._field === 'uptime',
  })
  .aggregateWindow({
    every: '1d',
    fn: 'last',
    createEmpty: false,
  })
  .toString();

console.log(query);

This will generate:

from(bucket: "my-awesome-bucket")
  |> range(start: -7d, stop: now())
  |> filter(fn: (r) => r._measurement == "system" and r._field == "uptime")
  |> aggregateWindow(every: 1d, fn: last, createEmpty: false)
  |> yield(name: "query_result")

API

The primary export is the FluxQueryBuilder class. Instantiate it and chain methods to build your query. Call .toString() at the end to get the final Flux query string.

For a full list of available methods and their options, please refer to the source code and type definitions.

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page for the repository.

License

This project is licensed under the MIT License.