okmodel 0.7.0 → 0.9.0

package/dist/dialects/pg/index.js

@@ -1,3 +1,7 @@
+import"../../shared/12z7aznj.js";
+import {
+  quoteIdent2
+} from "../../shared/fk9vef30.js";
 import {
   searchValue
 } from "../../shared/dzj09cye.js";
@@ -11,7 +15,7 @@ import {
   jsonReplacer2,
   json2,
   jsonb2
-} from "../../shared/9628a9xt.js";
+} from "../../shared/vk7rag46.js";
 import {
   bucket2
 } from "../../shared/nbw1z4yd.js";
@@ -36,13 +40,14 @@ import {
   time2,
   timetz2,
   interval2
-} from "../../shared/vqrjpcqn.js";
+} from "../../shared/nmnsgj7x.js";
 import {
-  schema2
-} from "../../shared/xnxsed62.js";
+  id2,
+  uuid2
+} from "../../shared/ecn8mfdq.js";
 import {
-  domainType
-} from "../../shared/ywspezzx.js";
+  schema2
+} from "../../shared/9dr2qnx7.js";
 import {
   one2,
   many2,
@@ -51,10 +56,6 @@ import {
   morphMany2,
   morphTo2
 } from "../../shared/exn3sd90.js";
-import {
-  id2,
-  uuid2
-} from "../../shared/hyh73qk6.js";
 import {
   text2,
   varchar2,
@@ -62,17 +63,25 @@ import {
   citext2,
   encodeText,
   decodeText
-} from "../../shared/ed0b8k4s.js";
+} from "../../shared/typ3vy7t.js";
 import {
   table2,
   index2,
   sql2
-} from "../../shared/rpycarcr.js";
+} from "../../shared/gcefca6p.js";
 import {
   ColumnBuilder2,
   required,
   formatType
-} from "../../shared/ywr8hmey.js";
+} from "../../shared/606g0nbf.js";
+import {
+  isFragmentParts,
+  fragment2,
+  ident2
+} from "../../shared/bsek72fg.js";
+import {
+  domainType
+} from "../../shared/ywspezzx.js";
 import {
   definition,
   rejected
@@ -82,11 +91,15 @@ import {
   compareText
 } from "../../shared/358zsv4r.js";
 import {
+  isOperator,
+  operatorName,
+  operatorValue,
   tag
 } from "../../shared/cn0n68ft.js";
 import {
   OkmError2,
-  catalogError2
+  catalogError2,
+  throwNamed2
 } from "../../shared/52szzakm.js";
 var __defProp = Object.defineProperty;
 var __returnValue = (v) => v;
@@ -102,6 +115,10 @@ var __export = (target, all) => {
       set: __exportSetter.bind(all, name)
     });
 };
+// src/dialects/pg/external.ts
+function external(table) {
+  return withOwner2(table, "external");
+}
 // src/dialects/pg/custom.ts
 function custom(spec) {
   if (spec.sqlType.length === 0) {
@@ -815,6 +832,364 @@ function path(segments, op) {
 function startsWith(value) {
   return tag("startsWith", value);
 }
+// src/dialects/pg/ops/lane.ts
+var LANE = Symbol.for("okm.lane");
+var READ = "read";
+var WRITE = "write";
+var BLOCKED = new Set(["__proto__", "constructor", "toString", "hasOwnProperty"]);
+async function raw(handle, cls, statement, source) {
+  const lane = readLane(handle);
+  const kind = readClass(statement);
+  const indexed = openTable(lane);
+  const parts = readParts(source);
+  const compiled = compile(indexed, parts);
+  const word = verb(compiled.text);
+  if (kind === READ && word !== "select") {
+    bad("A raw read starts with select.", 'Pass "read" and a single select. A leading with is a write.');
+  }
+  if (kind === WRITE && word !== "insert" && word !== "update" && word !== "delete") {
+    bad("A raw write starts with insert, update, or delete.", 'Pass "write" and one insert, update, or delete.');
+  }
+  const tenancy = predicateOf(lane.session, indexed);
+  if (kind === WRITE && tenancy !== undefined) {
+    unverifiable("A raw write on a tenant table cannot keep the tenant predicate.", 'Use update or delete. unscoped("reason") is the reviewed hatch.');
+  }
+  const guard = kind === READ ? guardOf(indexed, tenancy, compiled.params.length) : undefined;
+  if (guard !== undefined)
+    requireKey(indexed, lane.session.schema.tenancy?.key, parts);
+  const text = guard === undefined ? compiled.text : wrap(indexed, lane.session.schema.tenancy?.key, compiled.text, guard.text);
+  const params = guard === undefined ? compiled.params : [...compiled.params, ...guard.params];
+  await lane.session.connected;
+  try {
+    const result = await lane.session.pool.execute(text, params, kind === WRITE ? { route: "primary" } : undefined);
+    return decodeRows(cls, result.rows, indexed);
+  } catch (error) {
+    return raise(lane, error);
+  }
+}
+async function explain(handle, query) {
+  const lane = readLane(handle);
+  const got = readPlanned(await readSql(query));
+  if (production())
+    return { text: got.text, params: [], plan: null };
+  await lane.session.connected;
+  let rows;
+  try {
+    const result = await lane.session.pool.execute(`explain ${got.text}`, got.params);
+    rows = result.rows;
+  } catch (error) {
+    return raise(lane, error);
+  }
+  const plan = [];
+  for (const row of rows) {
+    const line = row[0];
+    if (typeof line === "string")
+      plan.push(line);
+  }
+  return { text: got.text, params: got.params, plan };
+}
+async function raise(lane, error) {
+  const mapped = await lane.fail(lane.session, error);
+  lane.session.logger?.error?.({ code: mapped.code, summary: mapped.summary });
+  throw mapped;
+}
+function production() {
+  const proc = Reflect.get(globalThis, "process");
+  if (typeof proc !== "object" || proc === null)
+    return false;
+  const env = Reflect.get(proc, "env");
+  if (typeof env !== "object" || env === null)
+    return false;
+  return Reflect.get(env, "NODE_ENV") === "production";
+}
+function readLane(handle) {
+  const value = Reflect.get(handle, LANE);
+  if (!Array.isArray(value)) {
+    bad("Pass the table handle.", "raw and explain take the table, such as db.notes, including a table from for().");
+  }
+  const session = value[0];
+  const table = value[1];
+  const fail = value[2];
+  if (typeof table !== "string" || typeof fail !== "function" || !isSession(session)) {
+    bad("Pass the table handle.", "raw and explain take the table, such as db.notes, including a table from for().");
+  }
+  return { session, table, fail };
+}
+function isSession(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const schema = Reflect.get(value, "schema");
+  const connected = Reflect.get(value, "connected");
+  const pool = Reflect.get(value, "pool");
+  if (typeof schema !== "object" || schema === null)
+    return false;
+  if (typeof Reflect.get(schema, "model") !== "object")
+    return false;
+  if (typeof connected !== "object" || connected === null || typeof Reflect.get(connected, "then") !== "function") {
+    return false;
+  }
+  return typeof pool === "object" && pool !== null && typeof Reflect.get(pool, "execute") === "function";
+}
+function readSql(query) {
+  const sql = Reflect.get(query, "sql");
+  if (typeof sql !== "function") {
+    bad("Pass a query.", "explain takes the table and a query from that table, such as notes.find({ limit: 1 }).");
+  }
+  return sql.call(query);
+}
+function readPlanned(value) {
+  if (typeof value !== "object" || value === null) {
+    bad("The statement has no text.", "Call explain on a query.");
+  }
+  const text = Reflect.get(value, "text");
+  const params = Reflect.get(value, "params");
+  if (typeof text !== "string" || !Array.isArray(params)) {
+    bad("The statement has no text.", "Call explain on a query.");
+  }
+  const bound = [];
+  for (const param of params) {
+    if (typeof param !== "string" && param !== null) {
+      bad("A statement parameter was not text.", "Parameters are bound text.");
+    }
+    bound.push(param);
+  }
+  return { text, params: bound };
+}
+function openTable(lane) {
+  const model = lane.session.schema.model[lane.table];
+  if (model === undefined) {
+    bad(`Table ${lane.table} is not in the schema.`, "Call raw on a table this schema declares.");
+  }
+  const columns = new Map;
+  const names = [];
+  for (const column of model.columns) {
+    columns.set(column.field, column);
+    names.push(column.field);
+  }
+  names.sort();
+  return { model, columns, names };
+}
+function compile(table, parts) {
+  const params = [];
+  const chunks = [];
+  let count = 0;
+  const sink = {
+    text(value) {
+      chunks.push(value);
+    },
+    param(encoded) {
+      params.push(encoded);
+      count += 1;
+      chunks.push(`$${String(count)}`);
+    },
+    mark() {}
+  };
+  for (const part of parts)
+    writePart(part, sink, table);
+  return { text: chunks.join(""), params };
+}
+function writePart(part, sink, table) {
+  if (part.k === "t") {
+    sink.text(part.s);
+    return;
+  }
+  if (part.k === "p") {
+    sink.param(part.v);
+    return;
+  }
+  if (part.k === "n") {
+    sink.text("null");
+    return;
+  }
+  if (part.k === "i") {
+    writeIdent(part.n, sink, table);
+    return;
+  }
+  if (part.k === "c") {
+    throw new OkmError2("OKM1125", "fragment.column belongs on a where field.", {
+      fix: { summary: "Use ident(name) in a raw statement." }
+    });
+  }
+  sink.text("(");
+  for (const nested of part.parts)
+    writePart(nested, sink, table);
+  sink.text(")");
+}
+function writeIdent(name, sink, table) {
+  const column = table.columns.get(name);
+  if (column === undefined) {
+    throwNamed2("OKM1120", name, table.names, `Field ${name} is not on ${table.model.name}. Accepted names: ${table.names.join(", ")}.`);
+  }
+  if (column.hidden) {
+    throw new OkmError2("OKM1120", `Field ${column.field} is hidden.`, {
+      fix: { summary: "A raw statement cannot name a hidden field." }
+    });
+  }
+  sink.text(quoteIdent2(column.sql));
+}
+function readClass(statement) {
+  if (statement === READ || statement === WRITE)
+    return statement;
+  bad('The statement class is "read" or "write".', 'Pass "read" or "write".');
+}
+function readParts(source) {
+  if (typeof source !== "object" || source === null) {
+    bad("Pass fragment`...`.", "Identifiers are ident(name). A string, number, boolean, or null is a parameter.");
+  }
+  if (typeof Reflect.get(source, "as") === "string") {
+    bad("Pass the fragment, not .as(name).", "The class names the row. Drop .as().");
+  }
+  if (!isOperator(source) || operatorName(source) !== "sql") {
+    bad("Pass fragment`...`.", "Identifiers are ident(name). A string, number, boolean, or null is a parameter.");
+  }
+  const stored = operatorValue(source);
+  if (!isFragmentParts(stored)) {
+    bad("Pass fragment`...`.", "Call fragment`...`. Do not build the parts yourself.");
+  }
+  return stored;
+}
+function verb(text) {
+  return /^[a-z]+/i.exec(text.trimStart())?.[0]?.toLowerCase() ?? "";
+}
+function predicateOf(session, table) {
+  const tenancy = session.schema.tenancy;
+  if (tenancy === undefined)
+    return;
+  const chunks = [];
+  const params = [];
+  let count = 0;
+  const wrote = tenancy.predicate({
+    table: table.model.name,
+    fieldSql: (field) => table.columns.get(field)?.sql,
+    encode: table.columns.get(tenancy.key)?.encode,
+    alias: "okm_tenant",
+    appended: false,
+    scope: session.scope,
+    sink: {
+      text(value) {
+        chunks.push(value);
+      },
+      param(encoded) {
+        params.push(encoded);
+        count += 1;
+        chunks.push(`$${String(count)}`);
+      },
+      mark() {}
+    }
+  });
+  if (!wrote)
+    return;
+  return { text: chunks.join("").replace(/^\s*where\s+/i, ""), params };
+}
+function guardOf(table, tenancy, userCount) {
+  const archive = table.model.archive?.at;
+  if (tenancy === undefined && archive === undefined)
+    return;
+  const parts = [];
+  if (tenancy !== undefined)
+    parts.push(shift(tenancy.text, userCount));
+  if (archive !== undefined)
+    parts.push(`okm_tenant.${quoteIdent2(archive)} is null`);
+  return { text: parts.join(" and "), params: tenancy?.params ?? [] };
+}
+function requireKey(table, tenantKey, parts) {
+  const key = rowKey(table, tenantKey);
+  if (key === undefined) {
+    unverifiable("A raw read needs one primary key column besides the tenant key.", "Declare one primary key. The tenant predicate binds that column.");
+  }
+  if (!namesIdent(parts, key)) {
+    unverifiable(`A raw read must select ${key} with ident.`, `Put ident("${key}") in the select list. Do not alias it. The tenant predicate is added outside the statement.`);
+  }
+}
+function rowKey(table, tenantKey) {
+  const keys = table.model.primary.filter((field) => field !== tenantKey);
+  return keys.length === 1 ? keys[0] : undefined;
+}
+function namesIdent(parts, name) {
+  for (const part of parts) {
+    if (part.k === "i" && part.n === name)
+      return true;
+    if (part.k === "f" && namesIdent(part.parts, name))
+      return true;
+  }
+  return false;
+}
+function wrap(table, tenantKey, text, where) {
+  const key = rowKey(table, tenantKey);
+  const column = key === undefined ? undefined : table.columns.get(key);
+  if (column === undefined) {
+    unverifiable("A raw read needs one primary key column besides the tenant key.", "Declare one primary key. The tenant predicate binds that column.");
+  }
+  const quoted = quoteIdent2(column.sql);
+  return `select okm_raw.* from (${text}) as okm_raw where okm_raw.${quoted} in (select ${quoted} from ${quoteIdent2(table.model.sql)} as okm_tenant where ${where})`;
+}
+function shift(text, by) {
+  if (by === 0)
+    return text;
+  return text.replace(/\$(\d+)/g, (_match, digits) => `$${String(Number(digits) + by)}`);
+}
+function decodeRows(cls, rows, table) {
+  const ctor = readClassCtor(cls);
+  const sample = construct(ctor);
+  const keys = Object.keys(sample);
+  if (keys.length === 0) {
+    bad("The class needs an initializer on every result column.", 'Write `id = ""` or `n = 0`. The initializer selects the decode, and the order is the select list.');
+  }
+  for (const key of keys) {
+    if (BLOCKED.has(key))
+      bad(`Field ${key} is reserved.`, "Rename the class field.");
+  }
+  return rows.map((wire) => {
+    const row = construct(ctor);
+    for (let index = 0;index < keys.length; index += 1) {
+      const key = keys[index];
+      if (key === undefined)
+        continue;
+      Reflect.set(row, key, decodeWire(wire[index], Reflect.get(sample, key), table.columns.get(key)));
+    }
+    return row;
+  });
+}
+function readClassCtor(cls) {
+  if (typeof cls !== "function") {
+    bad("Pass a class.", "The result of raw is one instance of that class per row.");
+  }
+  return cls;
+}
+function construct(ctor) {
+  try {
+    return new ctor;
+  } catch {
+    bad("The class must construct with no arguments.", "Give each field an initializer and no constructor arguments.");
+  }
+}
+function decodeWire(wire, sample, column) {
+  if (wire === null || wire === undefined)
+    return null;
+  if (column !== undefined)
+    return column.decode === undefined ? wire : column.decode(wire);
+  if (typeof sample === "number") {
+    const parsed = Number(wire);
+    if (!Number.isFinite(parsed)) {
+      bad("A class field initialized with a number received a non-numeric value.", "Use a numeric expression, or initialize the field with a string.");
+    }
+    return parsed;
+  }
+  if (typeof sample === "boolean") {
+    if (wire === "t" || wire === "true" || wire === "1")
+      return true;
+    if (wire === "f" || wire === "false" || wire === "0")
+      return false;
+    bad("A class field initialized with a boolean received another value.", "Use a boolean expression, or initialize the field with a string.");
+  }
+  return wire;
+}
+function bad(message, fix) {
+  throw new OkmError2("OKM1602", message, { fix: { summary: fix } });
+}
+function unverifiable(message, fix) {
+  throw new OkmError2("OKM1702", message, { fix: { summary: fix } });
+}
 export {
   ColumnBuilder2 as ColumnBuilder,
   exports_arr_ns as arr,
@@ -838,12 +1213,16 @@ export {
   enumColumn as enum,
   eq,
   every,
+  explain,
+  external,
+  fragment2 as fragment,
   gt,
   gte,
   has,
   hasAnyKey,
   hasKey,
   id2 as id,
+  ident2 as ident,
   identity2 as identity,
   ilike,
   inList,
@@ -881,6 +1260,7 @@ export {
   path,
   point,
   rank2 as rank,
+  raw,
   real,
   relevance,
   rowNumber2 as rowNumber,

package/dist/dialects/pg/introspect.d.ts

@@ -52,6 +52,17 @@ export declare function introspectSchema(runner: CatalogQuery, concrete: string,
  * Types only, comma-separated, no spaces. Argument names are left out.
  */
 export declare const FUNCTION_ARG_TYPES = "replace(oidvectortypes(p.proargtypes), ' ', '')";
+/**
+ * The `BEGIN ATOMIC` block inside `pg_get_functiondef`.
+ *
+ * A definition that does not contain that block is returned whole. The slice
+ * stops at the last `END`, which is the block closer. A `CASE` closer earlier
+ * in the reprint stays inside the block.
+ *
+ * @param definition - `pg_get_functiondef` text
+ * @returns The body introspection stores
+ */
+export declare function atomicBody(definition: string): string;
 /**
  * Applies one expression as a check and reads Postgres's reprint.
  *

package/dist/dialects/pg/operators.d.ts

@@ -7,7 +7,7 @@
 declare const brand: unique symbol;
 declare const RUNTIME: unique symbol;
 /** Operator names the read path compiles. */
-export type OperatorName = "eq" | "lt" | "lte" | "gt" | "gte" | "between" | "startsWith" | "contains" | "endsWith" | "like" | "ilike" | "inList" | "notIn" | "not" | "or" | "and" | "has" | "none" | "every" | "inc" | "containedBy" | "overlaps" | "hasKey" | "hasAnyKey" | "path" | "matches" | "relevance" | "similar" | "wordSimilar" | "json.set" | "arr.append" | "arr.remove";
+export type OperatorName = "eq" | "lt" | "lte" | "gt" | "gte" | "between" | "startsWith" | "contains" | "endsWith" | "like" | "ilike" | "inList" | "notIn" | "not" | "or" | "and" | "has" | "none" | "every" | "inc" | "containedBy" | "overlaps" | "hasKey" | "hasAnyKey" | "path" | "matches" | "relevance" | "similar" | "wordSimilar" | "sql" | "json.set" | "arr.append" | "arr.remove";
 /** A tagged operator. `value` is the operand the helper stored. */
 export type Tagged<Name extends OperatorName, V> = {
     readonly [brand]: Name;

package/dist/dialects/pg/ops/fragment.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Composed SQL fragments (rule 15, D266).
+ *
+ * The check-constraint `sql` tag stays a string. A query fragment is a tagged
+ * operator named `sql`, so the planner compiles it on the existing lazy
+ * operator path. Values are parameters. `ident` stores a name the compiler
+ * quotes. `fragment.column` is the where field the fragment is attached to.
+ */
+import { type Eq } from "../operators.js";
+import type { Window } from "./window.js";
+declare const identBrand: unique symbol;
+declare const columnBrand: unique symbol;
+/** One piece of a fragment. The compiler walks this list. */
+export type FragmentPart = {
+    readonly k: "t";
+    readonly s: string;
+} | {
+    readonly k: "p";
+    readonly v: string;
+} | {
+    readonly k: "n";
+} | {
+    readonly k: "i";
+    readonly n: string;
+} | {
+    readonly k: "c";
+} | {
+    readonly k: "f";
+    readonly parts: readonly FragmentPart[];
+};
+/** A name `ident` stored. The compiler quotes it. */
+export type FragmentIdent = {
+    readonly [identBrand]: string;
+};
+/** The where field a fragment is attached to. */
+export type FragmentColumn = {
+    readonly [columnBrand]: true;
+};
+/**
+ * A composed fragment.
+ *
+ * It is a where operand. `.as(name)` is the select form, and that result is a
+ * number.
+ */
+export type Fragment = Eq<never> & {
+    /**
+     * Names the select result.
+     *
+     * @typeParam A - Result key
+     * @param name - Result key. Not a column name
+     * @returns A select entry
+     */
+    as<const A extends string>(name: A): Window<A, number>;
+};
+/**
+ * Reports whether `value` is the part list `fragment` stored.
+ *
+ * @param value - Operator operand
+ * @returns `true` when every part has a known kind
+ */
+export declare function isFragmentParts(value: unknown): value is readonly FragmentPart[];
+/**
+ * Reads a select fragment.
+ *
+ * @param value - One `select` entry
+ * @returns The result name and the parts, or `undefined` when it is not a fragment
+ */
+export declare function readSelectFragment(value: unknown): {
+    readonly as: string;
+    readonly parts: readonly FragmentPart[];
+    readonly textual?: true;
+} | undefined;
+/**
+ * A function call stored as a `sql` fragment.
+ *
+ * The planner compiles it on the same path as {@link fragment}. `textual`
+ * makes `.as(name)` keep the wire string. A numeric call parses a number.
+ *
+ * @param parts - Expression parts, including the function name
+ * @param textual - When true, a select result stays text
+ * @returns A where operand. Call `.as(name)` to use it in `select`
+ */
+export declare function sqlExpression(parts: readonly FragmentPart[], textual?: boolean): Fragment;
+/**
+ * Reads the field name `ident` stored.
+ *
+ * @param value - A fragment interpolation
+ * @returns The field name, or `undefined` when `value` is not an ident
+ */
+export declare function identName(value: unknown): string | undefined;
+/**
+ * A composed SQL fragment.
+ *
+ * `column` is the where field this fragment is attached to.
+ */
+export declare const fragment: {
+    /**
+     * Builds a composed SQL fragment.
+     *
+     * @param strings - Literal SQL
+     * @param values - Parameters, identifiers, the column, or nested fragments
+     * @returns A where operand
+     */
+    (strings: TemplateStringsArray, ...values: readonly unknown[]): Fragment;
+    /** The where field this fragment is attached to, quoted by the compiler. */
+    readonly column: FragmentColumn;
+};
+/**
+ * Stores a field name for a fragment to resolve.
+ *
+ * The name is the TypeScript field, the same name `where` uses. Casing and
+ * `sqlName` are applied when the compiler quotes the column. A hidden field
+ * is OKM1120 at planning. Empty names and control characters are OKM1122.
+ *
+ * @param name - Field name
+ * @returns A value `fragment` resolves against the table
+ */
+export declare function ident(name: string): FragmentIdent;
+export {};

package/dist/dialects/pg/ops/lane.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Typed raw SQL and `explain()` (P103, P104, D268).
+ *
+ * Exported from `okmodel/pg`. An app that does not import them drops this
+ * module. The table handle carries the session under `Symbol.for("okm.lane")`.
+ * The statement class is explicit. Parameters come from the fragment. The
+ * tenant predicate, when it applies, is written outside the fragment.
+ */
+/**
+ * What `explain()` returns.
+ *
+ * `plan` is null in production, and `params` is empty there.
+ */
+export type ExplainResult = {
+    /** The statement `explain` describes. */
+    readonly text: string;
+    /** Bound parameters. Empty in production. */
+    readonly params: readonly (string | null)[];
+    /** `EXPLAIN` lines, or null when the statement was not sent. */
+    readonly plan: readonly string[] | null;
+};
+/**
+ * Runs one typed raw statement on a table handle.
+ *
+ * `cls` is constructed once per row. Own enumerable keys of that instance, in
+ * order, are the result columns. A key that is a field of the table uses that
+ * field's decode. Any other key uses the initializer: a number, a boolean, or
+ * driver text. `null` stays `null`.
+ *
+ * @typeParam C - Result class. Each row is an instance
+ * @param handle - Table handle (`db.notes`, including one from `for()`)
+ * @param cls - Class with an initializer on every result column
+ * @param statement - `"read"` or `"write"`
+ * @param source - A `fragment` template. Identifiers are `ident(name)`
+ * @returns One instance per row
+ */
+export declare function raw<C extends new () => object>(handle: object, cls: C, statement: "read" | "write", source: unknown): Promise<InstanceType<C>[]>;
+/**
+ * Describes a query.
+ *
+ * Outside production this sends `EXPLAIN` and returns the lines. In production
+ * (`NODE_ENV` is `"production"`) it does not send the statement. `plan` is
+ * null and `params` is empty.
+ *
+ * @param handle - Table handle that owns the query's session
+ * @param query - A query from that table. `sql()` is the statement
+ * @returns The statement and, outside production, the plan lines
+ */
+export declare function explain(handle: object, query: object): Promise<ExplainResult>;