@omgbase/core 0.15.0 → 0.21.0

package/dist/src/mutate/select.d.ts

@@ -0,0 +1,78 @@
+import { type Query } from "@omgbase/oqx";
+import type { Store } from "../core/store/store.js";
+import { type Effect } from "./effects.js";
+import { MutationError } from "./tree.js";
+import { type FixRequest } from "./canonical.js";
+/** The implicit bound on a selection without `expect.max` (hits beyond it are `selection_too_large`). */
+export declare const SELECTION_CEILING = 1000;
+export interface SelectionExpect {
+    max: number;
+}
+/** The seventh digested member of a plan's core (§11.4): the selector and its templates AS GIVEN, the hits it bound. */
+export interface Selection {
+    query: string;
+    expect?: SelectionExpect;
+    templates: unknown[];
+    cardinality: number;
+    /** the hit ids, result order */
+    identities: string[];
+}
+/** Where an expanded effect came from (every error from one carries both, §11.8); a plain effect's
+ *  expressions (3.2) have a row but no template. */
+export interface EffectOrigin {
+    template_index?: number;
+    row: {
+        id: string;
+        path: string;
+    };
+}
+export interface CompiledSelection {
+    /** the concrete, validated effects: hits × templates */
+    effects: Effect[];
+    selection: Selection;
+    /** expanded index → its origin */
+    origins: EffectOrigin[];
+}
+/** (3.2) A plain request compiled: the concrete effects and, when any effect carried an expression, the list as written. */
+export interface CompiledPlain {
+    effects: Effect[];
+    /** the effects AS WRITTEN — present only when at least one slot was an expression (the intent record's `templates`) */
+    templates?: unknown[];
+    /** effect index → the row its expressions were read from (sparse; literal effects have none) */
+    origins: (EffectOrigin | undefined)[];
+}
+/** The admission pass's refusal: `filter_invalid { reason, hint: "selection" }`. */
+export declare function selectionInvalid(message: string, data?: Record<string, unknown>): MutationError;
+/**
+ * `"-> <expr>"` → `{ oqx: "<expr>" }` — or, when the expression is a bare
+ * string literal or a template literal without interpolation, the literal
+ * itself (constant folding: `-> "x"` and `"x"` plan identically, and
+ * `-> "-> note"` is how a literal that begins with the leader is spelled).
+ * A parse error is `filter_invalid { hint: "selection" }` with its offset
+ * counted from the start of the written string (past the leader).
+ */
+export declare function desugarLeader(v: string, here: string): unknown;
+/**
+ * Desugar one effect or template as written (§11.8 "Sugar"), before the shape
+ * check and the admission: in every slot that admits an expression — the
+ * strings `markdown`, `to`, `path`, `separator`, `at.before` / `at.after`,
+ * the JSON `value`, each top-level `create.frontmatter` value, a target's `id`
+ * / `path`, and a whole target (`into`, `target`, `targets[k]`) — a string
+ * beginning `-> ` becomes `{ oqx }` (or folds to its literal); a `-> ` string
+ * anywhere else (`expect`, `field`, `op`, a section's `heading_id`, …) is
+ * refused. Every other string is literal data, with no escaping and no `${`
+ * scanning; a string nested inside a `value` or a frontmatter value is data
+ * (the slot is the top-level value, as for `{ oqx }`). Shape problems are the
+ * shape check's.
+ */
+export declare function desugarEffect(raw: unknown, index: number, request?: FixRequest): unknown;
+/**
+ * Compile `{ select, expect?, effects: templates }` into the concrete effects
+ * (§11.8): admit statically, rewrite, run once over one snapshot with
+ * `limit = bound + 1`, refuse a selection beyond the bound, bind every hit to
+ * every template. Reads only.
+ */
+export declare function compileSelection(store: Store, repoId: string, select: unknown, expectRaw: unknown, templatesRaw: unknown): CompiledSelection;
+/** The query a selector request compiles to (admission + rewrite, before any row is read) — `print` it to see what runs. */
+export declare function selectionQuery(select: unknown, templates: unknown): Query;
+export declare function compilePlain(store: Store, repoId: string, raw: unknown): CompiledPlain;