@smartput/query

A sentence to a database query, in SQL or Mongo.

QueryEngine reads a schema and a phrase; the dialect compilers are separate subpaths so a Postgres app never bundles the Mongo one. The grammar knows about ranges, places and units because it reads the same kinds the engine does.

Setup

npm add @smartput/query

Example

import { composeLocale, createEngine } from "@smartput/core";
import { english } from "@smartput/core/locale/en";
import { BUILTIN_KINDS } from "@smartput/kinds";
import BUILTIN_EN from "@smartput/kinds/locale/en";
import { defineSchema, QueryEngine } from "@smartput/query";
import { SqlCompiler } from "@smartput/query/sql";

const engine = createEngine({
  locales: [composeLocale(english, BUILTIN_EN)],
  kinds: BUILTIN_KINDS,
});

const schema = defineSchema({
  tables: [
    {
      name: "orders",
      key: "id",
      columns: [
        { name: "id" },
        { name: "weight", kind: "mass" },
        { name: "total", kind: "number" },
      ],
    },
  ],
});

const query = new QueryEngine({ schema, engine });
const sql = new SqlCompiler();

query.compile("orders heavier than 2 kg", sql).text           // "SELECT \"orders\".* FROM \"orders\" WHERE \"orders\".\"weight\" > $1"
query.compile("orders heavier than 2 kg", sql).params.join()  // "2 kg"
query.compile("orders with total over 100", sql).text         // "SELECT \"orders\".* FROM \"orders\" WHERE \"orders\".\"total\" > $1"

A column declares the kind it holds, so "heavier than 2 kg" reaches the same mass parser everything else in this repo uses, and the quantity leaves as a bound parameter rather than as string-interpolated SQL. The dialect is a subpath — /sql and /mongo — so the grammar is shared and only the rendering is not.

Entry points

| Import | Contents | | --- | --- | | @smartput/query | The package root. | | @smartput/query/sql | SqlCompiler — parameterised SQL, never string-concatenated. | | @smartput/query/mongo | MongoCompiler — a filter document. |

Runtime exports

Type-only exports are erased and do not appear here.

AmbiguousJoinError · AmbiguousQueryError · MAX_PHRASE_WORDS · OperandReader · QueryEngine · QueryParseError · QueryParser · Schema · SchemaError · UnknownColumnError · UnsupportedQueryError · bindingOf · defineSchema · geoOf · lex · queryEn · rangeOf

Dependencies

• @smartput/core
• @smartput/kind

What it costs

Ceilings, not measurements. bun run check-size bundles each entry with bun build --minify and fails if a row crosses its ceiling or drops more than 30 % below it — a budget that is only an upper bound reports a vanished graph as a triumph.

| Import | Minified | Gzipped | | --- | --- | --- | | query root (grammar + schema, no dialect) | ≤ 59.7 kB | ≤ 22.1 kB | | query/sql | ≤ 3.3 kB | ≤ 1.4 kB | | query/mongo | ≤ 4.6 kB | ≤ 1.9 kB |

Generated by scripts/gen-readmes.ts — run bun run docs:readmes. Every output above was produced by running the line beside it. The full page, with live demos, is docs/packages/query.md.