IF Commons GitHub

logical/query

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-estate-query-run FR-001, 0003-estate-query-run FR-002, 0003-estate-query-run FR-003, 0003-estate-query-run FR-004

Asking the estate a question in SQL: one statement that only reads, refused with every reason before anything runs, bound to the catalog of the relations (an unknown table or column is said with the nearest), run by the engine of lang-sql over the relations built as the query names them, within a budget of rows, and given back as a table, JSON or CSV. Nothing here reads a file or the network: what an estate holds is given.

import { openEstateQuery } from "./query.ts";
const q = openEstateQuery({ assets: [], now: "2026-12-01T00:00:00Z" });
q.query("select count(*) as n from asset").kind; // "ok"

Source: commons/estate-query/src/logical/query.ts

3 of 16 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

logical.CATALOGconstno test imports it
const CATALOG: Catalog

The catalog of the relations, made from the one list of them.

logical.DEFAULT_BUDGETconstno test imports it
const DEFAULT_BUDGET: { readonly maxRows: 10000; readonly maxNodes: 2000; }

The defaults: ten thousand rows and a statement of at most two thousand nodes.

logical.formatTablefunctionno test imports it
function formatTable(t: Table, format: "csv" | "json" | "table"): string

A table as the text of one of its formats.

logical.openEstateQueryfunctionno test imports it
function openEstateQuery(data: EstateData, budget?: Budget, live?: Live | undefined): EstateQuery

The estate, openable for questions.

logical.Budgettypeno test imports it
type Budget = { readonly maxRows?: number; readonly maxNodes?: number };

What a question may cost.

logical.EstateQuerytypeno test imports it
type EstateQuery = {
  /** One read-only statement, with `?` or `$1` for values given apart. */
  readonly query: (sql: string, params?: readonly Value[]) => Result<Table, QueryProblem>;
};

An estate that can be asked.

logical.Livetypeno test imports it
type Live = { readonly tables: Readonly<Record<string, Table>>; readonly status: Table };

What the machines said, gathered before the question is asked: the live relations by name and the status of each machine and table.

logical.QueryProblemtypeno test imports it
type QueryProblem =
  | { readonly kind: "refused"; readonly reasons: readonly string[] }
  | { readonly kind: "failed"; readonly message: string }
  | { readonly kind: "budget"; readonly message: string };

Why a question was not answered.

CATALOGconst
const CATALOG: Catalog

The catalog of the relations, made from the one list of them.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

DEFAULT_BUDGETconstno test imports it
const DEFAULT_BUDGET: { readonly maxRows: 10000; readonly maxNodes: 2000; }

The defaults: ten thousand rows and a statement of at most two thousand nodes.

formatTablefunction
function formatTable(t: Table, format: "csv" | "json" | "table"): string

A table as the text of one of its formats.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

openEstateQueryfunction
function openEstateQuery(data: EstateData, budget?: Budget, live?: Live | undefined): EstateQuery

The estate, openable for questions.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

Budgettypeno test imports it
type Budget = { readonly maxRows?: number; readonly maxNodes?: number };

What a question may cost.

EstateQuerytypeno test imports it
type EstateQuery = {
  /** One read-only statement, with `?` or `$1` for values given apart. */
  readonly query: (sql: string, params?: readonly Value[]) => Result<Table, QueryProblem>;
};

An estate that can be asked.

Livetypeno test imports it
type Live = { readonly tables: Readonly<Record<string, Table>>; readonly status: Table };

What the machines said, gathered before the question is asked: the live relations by name and the status of each machine and table.

QueryProblemtypeno test imports it
type QueryProblem =
  | { readonly kind: "refused"; readonly reasons: readonly string[] }
  | { readonly kind: "failed"; readonly message: string }
  | { readonly kind: "budget"; readonly message: string };

Why a question was not answered.

Titles, headings, exports, tables, columns and requirements. Esc closes.