@routier/core 0.2.1 → 0.4.0

package/dist/plugins/query/QueryOptionsCollection.d.ts

@@ -6,13 +6,47 @@ export type QueryCollectionItem<T, K extends QueryOptionName> = {
 export declare class QueryOptionsCollection<T> {
     private options;
     private nextExecutionTarget;
+    private nextExecutionReason;
     private nextIndex;
     private enumeratedItems;
+    /** Cuts over to memory execution, keeping the first cause. See `MemoryExecutionReason`. */
+    private cutOverToMemory;
+    /**
+     * True when `split()` or `splitAt()` produced this collection.
+     *
+     * Those rebuild each half by re-adding its options, which re-derives execution targets
+     * without the options that caused them — a post-join filter alone in the memory half
+     * derives back to `"database"`. Anything reading `target` as a report of where work runs
+     * has to reject a derived collection; see `explainQuery`.
+     */
+    private derived;
+    get isDerived(): boolean;
     get items(): Map<keyof QueryOptionValueMap<unknown>, QueryCollectionItem<any, any>[]>;
     get isEmpty(): boolean;
     static EMPTY<R>(): QueryOptionsCollection<R>;
     static isEmpty<T>(options: QueryOptionsCollection<T>): boolean;
     add<K extends QueryOptionName>(name: K, value: QueryOption<T, K>["value"]): void;
+    /**
+     * Splits the collection around the FIRST occurrence of `name`, preserving order.
+     *
+     * For a join: the options recorded before it operate on entity rows, the option itself
+     * produces tuples, and the ones after it operate on tuples. Three different shapes, so the
+     * caller has to run them in three steps rather than one pass.
+     */
+    splitAt<K extends QueryOptionName>(name: K): {
+        before: QueryOptionsCollection<T>;
+        at: QueryOption<T, K> | null;
+        after: QueryOptionsCollection<T>;
+    };
+    /**
+     * Captures the collection's current state and returns a function that restores it.
+     *
+     * Terminal queryable operations (count, first, aggregates, …) record their option on
+     * the shared collection before executing. Without restoring, a re-executed terminal —
+     * the whole point of a subscribed queryable — stacks its option a second time and
+     * runs it over the first execution's scalar result.
+     */
+    snapshot(): () => void;
     split(): {
         memory: QueryOptionsCollection<T>;
         database: QueryOptionsCollection<T>;

package/dist/plugins/query/explain.d.ts

@@ -0,0 +1,82 @@
+import { MemoryExecutionReason, QueryOptionExecutionTarget, QueryOptionName } from "./types";
+import { QueryOptionsCollection } from "./QueryOptionsCollection";
+/**
+ * One sentence per reason code, written for someone meeting pushdown for the first time.
+ *
+ * Beside the codes rather than in the formatter, so console output, a failing test and the
+ * docs all say the same thing.
+ */
+export declare const MEMORY_EXECUTION_EXPLANATIONS: Record<MemoryExecutionReason, string>;
+/**
+ * One thing a backend actually executed, in the backend's own language.
+ *
+ * A plugin pushes these onto `DbPluginQueryEvent.executedQueries` as it runs them, so a join —
+ * which reads twice — reports both, in execution order. `text` is not required to be SQL: a
+ * key-value store describes what it did in whatever terms it has.
+ */
+export type ExecutedQuery = {
+    text: string;
+    parameters?: unknown[];
+};
+export type ExplainedOption = {
+    index: number;
+    name: QueryOptionName;
+    detail?: Record<string, unknown>;
+};
+export declare const EXECUTED_QUERIES_UNSUPPORTED = "This plugin did not report what it executed. It may not support explain.";
+export type ExecutionStep = {
+    step: number;
+    of: number;
+    executedIn: QueryOptionExecutionTarget;
+    description: string;
+    options: ExplainedOption[];
+    /** Set on database steps once the plugin has reported. */
+    executedQueries?: ExecutedQuery[];
+    /** Set on the first database step instead, when the plugin reported nothing. */
+    executedQueriesUnsupported?: string;
+    /** Set on memory steps only. */
+    reason?: MemoryExecutionReason;
+    explanation?: string;
+};
+export type QueryExplanationSummary = {
+    database: number;
+    memory: number;
+    /** Deduped, in first-seen order. Empty when the whole query pushed down. */
+    reasons: MemoryExecutionReason[];
+    explanation: string;
+};
+export type QueryExplanation = {
+    collection: string;
+    database: string;
+    summary: QueryExplanationSummary;
+    executionSteps: ExecutionStep[];
+    plugin: {
+        kind: string;
+    };
+};
+export type ExplainContext = {
+    collection: string;
+    database: string;
+    pluginKind: string;
+};
+/**
+ * Builds the explanation from the resolved options, with no plugin involvement.
+ *
+ * Takes the collection BEFORE `split()`, and throws otherwise. Splitting re-adds each half
+ * into a fresh collection, which re-derives targets without the options that caused them — a
+ * post-join filter alone in the memory half derives back to `"database"`, and the document
+ * would report memory work as having run in the database.
+ */
+export declare const explainQuery: (options: QueryOptionsCollection<any>, context: ExplainContext) => QueryExplanation;
+/**
+ * Attaches what the backend reported to the step that was sent to it.
+ *
+ * Reporting is optional for a plugin, so an empty report is not an error: the step is marked
+ * `executedQueriesUnsupported` instead, and the rest of the explanation stands — the pushdown
+ * analysis comes from the options and is correct with or without the plugin's statements.
+ *
+ * Copies the steps rather than writing into them, so the explanation a caller already holds
+ * does not gain statements after the fact. Options and their details are shared with the
+ * original — nothing mutates them, and copying deeper would only look safer than it is.
+ */
+export declare const withExecutedQueries: (explanation: QueryExplanation, executedQueries: ExecutedQuery[]) => QueryExplanation;

package/dist/plugins/query/formatExplanation.d.ts

@@ -0,0 +1,9 @@
+import { QueryExplanation } from "./explain";
+/**
+ * Renders an explanation for a terminal.
+ *
+ * The STEP headers carry the whole lesson: a reader who has never heard of pushdown still sees
+ * that the statement in step 1 is not the entire query. Nobody should have to notice a missing
+ * ORDER BY to work that out.
+ */
+export declare const formatExplanation: (explanation: QueryExplanation) => string;

package/dist/plugins/query/index.d.ts

@@ -1,3 +1,7 @@
+export * from './explain';
+export * from './formatExplanation';
+export * from './join';
 export * from './Query';
 export * from './QueryOptionsCollection';
 export * from './types';
+export * from './similarity';

package/dist/plugins/query/join.d.ts

@@ -0,0 +1,210 @@
+import { CompiledSchemaCore, PropertyInfo } from "../../schema";
+import { UnknownRecord } from "../../utilities";
+import { PluginEventCallbackResult } from "../../results";
+import type { DbPluginQueryEvent } from "../types";
+import type { ITranslatedValue } from "../translators/types";
+import { QueryOptionsCollection } from "./QueryOptionsCollection";
+import { QueryOptionValueMap } from "./types";
+export type JoinKind = "inner" | "left";
+/**
+ * One side's join key, as a property path plus the resolved property.
+ *
+ * The path is what survives serialization; the `PropertyInfo` is the live handle that reads
+ * the value and resolves a `from`-renamed storage name. Both, because a key read has to work
+ * on either side of the wire.
+ */
+export type JoinKeyReference = {
+    propertyName: string;
+    property: PropertyInfo<any> | null;
+};
+export type JoinQueryOptionValue = QueryOptionValueMap<any>["join"];
+/**
+ * The inner side of a join, as the PLUGIN sees it.
+ *
+ * Supplied by the plugin rather than fetched by the translator, because loading rows is the one
+ * part of a join that is backend-specific: a memory plugin resolves a collection, Dexie opens a
+ * store, Mongo reads a collection. Everything after that — deserializing, applying the inner
+ * scopes, pairing — is identical, so it lives here and runs once.
+ *
+ * Rows arrive in STORAGE shape, exactly as the plugin holds them; the translator deserializes
+ * them with `innerSchema`, which the outer query's own deserialization would never do.
+ */
+export type JoinInnerSide = {
+    innerSchema: CompiledSchemaCore<any>;
+    innerRows: readonly unknown[];
+};
+/**
+ * `undefined` when the query has no join at all, which is the common case and not an error.
+ */
+export type JoinInnerSideResult = {
+    ok: "success";
+    innerSide?: JoinInnerSide;
+} | {
+    ok: "error";
+    error: unknown;
+};
+/**
+ * A joined pair, each half fully deserialized into its own schema's ENTITY shape.
+ *
+ * The wire contract for every interpretation of a join: a native SQL join, an in-plugin hash
+ * join, and the datastore's cross-plugin join all produce exactly this. Flat combined rows
+ * never leave a translator — see `specs/joins.md`.
+ */
+export type JoinTuple = [UnknownRecord, UnknownRecord | undefined];
+/**
+ * Turns storage-shape records into entity-shape values, one side of a join at a time.
+ *
+ * The inner side does NOT pass through the outer query's normal deserialization —
+ * `DatabaseDataAccessStrategy.query` transforms against the outer schema only — so each side
+ * is deserialized with its own schema here, which is what makes the two halves of a tuple
+ * readable by the same property names the caller wrote in the selectors.
+ *
+ * `"diff"` rather than `"proxy"`: join results are read-only projections and never attach to
+ * the change tracker, so there is nothing for a tracking proxy to record.
+ */
+export declare const toEntityShape: (schema: CompiledSchemaCore<any>, rows: readonly unknown[]) => UnknownRecord[];
+/**
+ * Reads a join key off an entity-shape row.
+ *
+ * Through the `PropertyInfo` when there is one, so a nested path (`a.b.id`) resolves the same
+ * way every other option resolves it. The string fallback exists for an option that crossed a
+ * wire without its schema; it walks the same path by name.
+ */
+export declare const readJoinKey: (row: UnknownRecord | undefined, reference: JoinKeyReference) => unknown;
+/**
+ * Applies an inner side's own filters to its rows.
+ *
+ * **This is the correctness trap of the whole feature.** Every interpretation of a join
+ * bypasses the inner collection's normal datastore read path, so the inner side's soft-delete
+ * scope and `.scope()` filters exist ONLY because `innerOptions` carries them. An interpreter
+ * that skips this returns soft-deleted rows.
+ *
+ * Filters only. Nothing else reaches `innerOptions` today — scopes are filters — and applying
+ * a `skip`/`take` recorded against the inner collection to the rows feeding a join would
+ * change which pairs exist rather than which rows are visible.
+ */
+export declare const applyInnerOptions: (rows: UnknownRecord[], innerOptions: QueryOptionsCollection<any>) => UnknownRecord[];
+/**
+ * The join itself: one hash join, written once, called from every interpreter.
+ *
+ * O(n + m) rather than a nested loop, which is the whole reason the API takes explicit key
+ * selectors instead of a free-form predicate. Both key properties are `string` or `number` by
+ * a build-time rule, so the keys are hashable and compare the same way in JS and in SQL.
+ *
+ * Semantics, exactly as `specs/joins.md` states them:
+ *
+ *  - **Null keys** never match. Under `left` the outer row still appears, paired with
+ *    `undefined`.
+ *  - **Duplicates** produce every pair: the full cross product per key group.
+ *  - **Ordering** is outer order, then inner order within a key group. Undefined by contract —
+ *    a caller who cares sorts.
+ */
+export declare const hashJoin: (options: {
+    kind: JoinKind;
+    outerRows: UnknownRecord[];
+    innerRows: UnknownRecord[];
+    outerKey: JoinKeyReference;
+    innerKey: JoinKeyReference;
+}) => JoinTuple[];
+/**
+ * How many distinct outer keys are still worth turning into an `IN (...)` prefilter.
+ *
+ * A cost decision, never a correctness one: above the threshold the inner side is read under its
+ * own scopes and the hash join discards the surplus, which is the same answer by a slower route.
+ * 500 because a bound-parameter list is cheap in the hundreds and starts costing more than the
+ * scan it saves in the thousands — and some engines refuse a list that long outright.
+ */
+export declare const DEFAULT_SEMI_JOIN_KEY_THRESHOLD = 500;
+/**
+ * The distinct join keys of the outer rows, or `null` when there are too many to be worth sending.
+ *
+ * `null` means "do not prefilter", not "no keys" — an empty SET is a real answer meaning the inner
+ * side cannot match anything.
+ *
+ * @param column The key's STORAGE column name when `rows` are storage-shaped, or its property name
+ * when they are entity-shaped. The caller knows which it holds.
+ */
+export declare const distinctJoinKeys: (rows: readonly UnknownRecord[], reference: JoinKeyReference, threshold?: number, options?: {
+    storageShape?: boolean;
+}) => Set<unknown> | null;
+/**
+ * A filter restricting the inner side to rows whose key is one the outer side actually has.
+ *
+ * Built as an expression tree by hand rather than parsed from generated source, for the reason
+ * `softDeleteScope` gives: generating source needs `new Function`, which a Content-Security-Policy
+ * blocks, and the shape is known here so there is nothing to parse. An `includes` comparator over
+ * an array value is what every translator already turns into `IN (...)` or `$in`, so this pushes
+ * down on the backends that can take it and runs as the closure on the ones that cannot.
+ *
+ * Cost only. Every pair it removes from the inner read is one the hash join would have discarded.
+ */
+export declare const semiJoinFilter: (reference: JoinKeyReference, keys: ReadonlySet<unknown>) => QueryOptionValueMap<any>["filter"];
+/**
+ * Loads a join's inner side by asking the plugin to run an ORDINARY query for it.
+ *
+ * The generic way for a plugin to interpret a join — one call, no join-specific reading code.
+ * The inner side is just "this collection, under these filters", which is a query every plugin
+ * already knows how to answer, through whatever indexes and scoping it normally applies.
+ *
+ * Only the DATABASE half of `innerOptions` is sent. The memory half would mean nothing to the
+ * plugin, and `executeJoin` re-applies every filter regardless — filters are pure, so the second
+ * pass costs a walk over the survivors and guarantees the inner scopes are honoured even if the
+ * plugin silently ignored them.
+ *
+ * The inner query carries no `join` option of its own, so this cannot recurse.
+ *
+ * @param query How this plugin runs a query. **Not necessarily `plugin.query`**: a plugin that
+ * serializes queries through a work queue must pass its UN-QUEUED path, or this call waits behind
+ * the outer query that is still holding the queue and the plugin deadlocks.
+ */
+export declare const loadJoinInnerSide: <TRoot extends {}, TShape>(event: DbPluginQueryEvent<TRoot, TShape>, query: (innerEvent: DbPluginQueryEvent<UnknownRecord, UnknownRecord>, done: PluginEventCallbackResult<ITranslatedValue<UnknownRecord>>) => void, done: (result: JoinInnerSideResult) => void, 
+/**
+ * The outer side's distinct keys, when the caller already has them.
+ *
+ * Only a plugin that runs its outer query FIRST can supply these, and most run this loader
+ * before anything else — so it is optional, and its absence costs a wider inner read rather
+ * than a wrong one.
+ */
+outerKeys?: ReadonlySet<unknown> | null) => void;
+/**
+ * Interprets a join by running TWO ordinary queries through the plugin's own read path.
+ *
+ * The whole of interpretation 2 for a plugin that has no reason to do anything cleverer, and the
+ * shape every non-SQL backend should prefer:
+ *
+ * ```ts
+ * query(event, done) {
+ *     if (event.operation.options.has("join")) {
+ *         joinInPlugin(event, (e, d) => this.query(e, d), done);
+ *         return;
+ *     }
+ *     // ...the ordinary single-collection path
+ * }
+ * ```
+ *
+ * **The outer side runs FIRST, and that ordering is the optimization.** Its keys are what narrow
+ * the inner read to rows that can actually pair — and they do not exist until the outer filters
+ * have run. Loading the inner side first, which is what a naive implementation does, means reading
+ * and materializing a whole collection to pair it with three rows.
+ *
+ * Neither query carries the join option, so both take the plugin's normal path: its indexes, its
+ * pushdown decisions, its retries. Nothing recurses, because the option is stripped before either
+ * goes out.
+ *
+ * @param query How this plugin runs a query. NOT necessarily `plugin.query` — a plugin that
+ * serializes queries through a work queue must pass its UN-QUEUED path, or the two reads below
+ * wait on the slot this one is holding.
+ */
+export declare const joinInPlugin: <TRoot extends {}, TShape>(event: DbPluginQueryEvent<TRoot, TShape>, query: (innerEvent: DbPluginQueryEvent<UnknownRecord, UnknownRecord>, done: PluginEventCallbackResult<ITranslatedValue<UnknownRecord>>) => void, done: PluginEventCallbackResult<ITranslatedValue<TShape>>) => void;
+/**
+ * A join over rows both sides have already deserialized, with the inner side's scopes applied.
+ *
+ * The one entry point every interpreter uses: `JsonTranslator.join` inside a plugin, and the
+ * datastore's own memory half for a cross-plugin join. Callers hand over ENTITY-shape rows —
+ * `toEntityShape` is separate because a caller may already have paid for it.
+ */
+export declare const executeJoin: (options: {
+    option: JoinQueryOptionValue;
+    outerRows: UnknownRecord[];
+    innerRows: UnknownRecord[];
+}) => JoinTuple[];

package/dist/plugins/query/similarity.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cosine distance, and the ordering rules that go with it.
+ *
+ * One implementation, shared by every in-memory path, because the promise the feature makes
+ * is that a backend with no vector support returns the SAME ROWS IN THE SAME ORDER as one
+ * that pushes the search down. Two copies of this arithmetic would drift, and the drift would
+ * only ever show up as a conformance failure nobody could localise.
+ *
+ * The tie-breaking and degenerate cases below are chosen to match pgvector rather than to be
+ * independently reasonable — parity is the point.
+ */
+/**
+ * Distance in `[0, 2]`, or `Infinity` for a value that cannot be compared.
+ *
+ * `Infinity` covers three cases, and they all sort LAST, which is what PostgreSQL does too:
+ * a missing value (`NULL` sorts last under `ASC` by default), a zero-magnitude vector
+ * (pgvector's `<=>` yields `NaN`, which PostgreSQL orders after every real number), and a
+ * stored vector of the wrong width.
+ *
+ * The width case cannot happen on a native `vector(n)` column — the engine rejects the write —
+ * so it only arises on a backend storing JSON, where the data was written by something other
+ * than this schema. Sorting it last rather than throwing keeps one corrupt row from failing a
+ * query that is otherwise answerable.
+ */
+export declare const cosineDistance: (left: readonly number[] | null | undefined, right: readonly number[]) => number;
+/**
+ * The `count` rows closest to `vector`, nearest first.
+ *
+ * Distances are computed once per row rather than inside the comparator: a comparison-time
+ * computation runs O(n log n) times over vectors that are commonly 1536 wide, which turns an
+ * ordering into the dominant cost of the query.
+ *
+ * The sort is stable, so rows at equal distance keep the order the backend returned them in.
+ * That is not a guarantee worth relying on across backends — two engines can hand back the
+ * same rows in different orders — but it does mean this function never introduces a
+ * difference of its own.
+ */
+export declare const nearestBy: <T>(rows: readonly T[], vector: number[], count: number, select: (row: T) => readonly number[] | null | undefined) => T[];

package/dist/plugins/query/types.d.ts

@@ -1,6 +1,8 @@
 import { Expression, Filter, ParamsFilter } from "../../expressions";
-import { PropertyInfo } from "../../schema";
+import { PropertyInfo, SchemaId } from "../../schema";
 import { GenericFunction } from "../../types";
+import type { JoinKeyReference, JoinKind } from "./join";
+import type { QueryOptionsCollection } from "./QueryOptionsCollection";
 export declare enum QueryOrdering {
     Descending = "desc",
     Ascending = "asc"
@@ -17,10 +19,21 @@ export type QueryField = {
 };
 export type QueryOptionExecutionTarget = "database" | "memory";
 export type QueryOptionName = keyof QueryOptionValueMap<unknown>;
+/**
+ * Why an option runs in memory rather than in the database.
+ *
+ * A code rather than a sentence, so a test can assert on it — the sentences live in
+ * `MEMORY_EXECUTION_EXPLANATIONS`. Every cause is a ratchet, because `nextExecutionTarget`
+ * never returns to `"database"`, so the code recorded is the FIRST cause and it stays on every
+ * option after it. Reporting a later one would name a symptom of this one.
+ */
+export type MemoryExecutionReason = "not-parsable" | "unmapped-property" | "renamed-property" | "map-rename" | "after-nearest" | "after-join" | "cross-plugin-join";
 export type QueryOption<T, K extends QueryOptionName> = {
     name: QueryOptionName;
     value: QueryOptionValueMap<T>[K];
     target: QueryOptionExecutionTarget;
+    /** Set only when `target` is `"memory"`. */
+    reason?: MemoryExecutionReason;
 };
 export type QueryOptionValueMap<T extends {}> = {
     skip: number;
@@ -29,6 +42,7 @@ export type QueryOptionValueMap<T extends {}> = {
         selector: GenericFunction<T, T[keyof T]>;
         direction: QueryOrdering;
         propertyName: string;
+        property?: PropertyInfo<T> | null;
     };
     map: {
         selector: GenericFunction<T, any>;
@@ -44,6 +58,66 @@ export type QueryOptionValueMap<T extends {}> = {
         filter: ParamsFilter<T, {}> | Filter<T>;
         expression: Expression;
     };
+    /**
+     * Similarity search: an ordering plus a limit, never a filter.
+     *
+     * `count` is part of the option rather than a separate `take` because the two are one
+     * operation to a backend that can push this down — `ORDER BY ... LIMIT n` is what makes an
+     * approximate index usable, and splitting them would order every row before limiting.
+     */
+    nearest: {
+        selector: GenericFunction<T, T[keyof T]>;
+        propertyName: string;
+        property?: PropertyInfo<T> | null;
+        vector: number[];
+        count: number;
+    };
+    /**
+     * An equi-join against a second collection, interpreted by whoever receives it.
+     *
+     * A first-class query option rather than a datastore side-path: a SQL backend emits a real
+     * `INNER JOIN`/`LEFT JOIN`, every other backend loads the rows it needs and the shared hash
+     * join runs inside the plugin, and a cross-plugin join runs in the datastore's memory half.
+     * All three produce the same pairs — see `specs/joins.md`.
+     *
+     * Serializable by construction: property paths and a schema id, never live rows, with any
+     * filter's values travelling in its params object. That is what lets the whole option be
+     * forwarded to a server once expression-tree serialization lands.
+     */
+    join: {
+        kind: JoinKind;
+        /** Resolved through `event.schemas`, which already carries every schema in the store. */
+        innerSchemaId: SchemaId;
+        outerKey: JoinKeyReference;
+        innerKey: JoinKeyReference;
+        /**
+         * The inner side's own filters — INCLUDING its soft-delete scope and `.scope()`
+         * filters. Every interpreter must apply these: it is the only place they exist, because
+         * a join bypasses the inner collection's normal read path.
+         */
+        innerOptions: QueryOptionsCollection<any>;
+        /**
+         * Whether the two sides live on DIFFERENT plugin instances, in which case no plugin can
+         * receive the option and the datastore is the interpreter.
+         *
+         * Decided by plugin instance identity at build time, never by comparing database names —
+         * two plugins over one database are still two interpreters, and one name can front two
+         * databases.
+         */
+        crossPlugin: boolean;
+        /**
+         * How many distinct outer keys are still worth turning into an `IN (...)` prefilter on the
+         * inner read — the datastore's `semiJoinKeyThreshold`, default 500.
+         *
+         * Carried in the option because the decision is made where the join executes, which is
+         * usually inside a plugin, and a plugin cannot see a datastore's configuration. A number
+         * serializes; a reference to the store would not.
+         *
+         * Cost only. Above the threshold the inner side is read under its own scopes and the hash
+         * join discards the surplus — the same answer by a slower route.
+         */
+        semiJoinKeyThreshold: number;
+    };
     min: true;
     max: true;
     count: true;

package/dist/plugins/translators/DataTranslator.d.ts

@@ -16,5 +16,33 @@ export declare abstract class DataTranslator<TRoot extends {}, TShape> {
     abstract sort(data: unknown, option: QueryOption<TShape, "sort">): TShape;
     abstract map(data: unknown, option: QueryOption<TShape, "map">): TShape;
     abstract group(data: unknown, option: QueryOption<TShape, "group">): TShape;
+    /**
+     * Abstract on purpose, unlike the pass-throughs a storage translator can usually inherit.
+     *
+     * Every other shaper degrades safely when a backend ignores it — an unsorted result is
+     * still the right rows. A similarity search is not: it is the only option whose value is
+     * ENTIRELY in the ordering and the limit, so a translator that quietly passes the data
+     * through returns every row in insertion order and calls it the ten nearest.
+     *
+     * Requiring an answer here means a new translator cannot be written without deciding
+     * whether its backend performed the search, and the compiler asks the question.
+     */
+    abstract nearest(data: unknown, option: QueryOption<TShape, "nearest">): TShape;
+    /**
+     * Abstract for the same reason as `nearest`, one step further.
+     *
+     * A translator that quietly passed a join through would not return an unsorted or unlimited
+     * result — it would return the OUTER rows, one object each where the contract says tuples,
+     * and every `([outer, inner]) => ...` lambda downstream would destructure the outer entity
+     * instead. Nothing errors; the answer is simply a different query's answer.
+     *
+     * So the compiler asks the question. Every translator must state how its backend joins:
+     * natively (pass through the rows the SQL already paired), in memory (the shared hash join
+     * over rows the plugin supplies), or not at all (throw, loudly, naming the backend).
+     *
+     * The output contract, whichever answer: an array of `[outer, inner]` tuples, each half
+     * fully deserialized into its OWN schema's entity shape.
+     */
+    abstract join(data: unknown, option: QueryOption<TShape, "join">): TShape;
     translate(data: unknown): ITranslatedValue<TShape>;
 }

package/dist/plugins/translators/JsonTranslator.d.ts

@@ -1,6 +1,24 @@
 import { DataTranslator } from "./DataTranslator";
 import { QueryOption } from "../query/types";
+import { JoinInnerSide } from "../query/join";
+import { IQuery } from "../types";
 export declare class JsonTranslator<TRoot extends {}, TShape> extends DataTranslator<TRoot, TShape> {
+    private readonly innerSide?;
+    /**
+     * @param innerSide The inner collection's rows, when this query carries a `join` option.
+     * A plugin that omits it for a query that HAS a join gets a throw from `join()` rather than
+     * a silently un-joined result.
+     */
+    constructor(query: IQuery<TRoot, TShape>, innerSide?: JoinInnerSide);
+    /**
+     * The hash join itself, over rows already in memory — the floor every non-SQL backend
+     * stands on.
+     *
+     * Both halves are deserialized here, each with its own schema, because that is where the
+     * `===` on key values is specified to happen: in entity shape, by the property names the
+     * caller wrote in the key selectors. A `from`-renamed column reads correctly for free.
+     */
+    join<TResult>(data: unknown, option: QueryOption<TShape, "join">): TResult;
     filter<TResult>(data: unknown, option: QueryOption<TShape, "filter">): TResult;
     map<T>(data: unknown, option: QueryOption<T, "map">): T;
     group<T>(data: unknown, option: QueryOption<T, "group">): T;
@@ -8,6 +26,15 @@ export declare class JsonTranslator<TRoot extends {}, TShape> extends DataTransl
     min<TResult extends string | number | Date>(data: unknown, _: QueryOption<TShape, "min">): TResult;
     max<TResult extends string | number | Date>(data: unknown, _: QueryOption<TShape, "max">): TResult;
     sort<TResult>(data: unknown, option: QueryOption<TShape, "sort">): TResult;
+    /**
+     * The similarity search itself, over values already in memory.
+     *
+     * This is the floor the whole feature stands on: it is reached whenever the backend did
+     * not do the search, which is every backend except the ones with a native vector index.
+     * It reads the property through the option's selector, so it works on any shape the rows
+     * arrive in.
+     */
+    nearest<TResult>(data: unknown, option: QueryOption<TShape, "nearest">): TResult;
     sum<TResult extends number>(data: unknown, _: QueryOption<TShape, "sum">): TResult;
     distinct<TResult>(data: unknown, _: QueryOption<TShape, "distinct">): TResult;
     skip<TResult>(data: unknown, option: QueryOption<TShape, "skip">): TResult;

package/dist/plugins/translators/SqlTranslator.d.ts

@@ -1,6 +1,21 @@
 import { QueryOption } from "../query/types";
+import { IQuery } from "../types";
 import { DataTranslator } from "./DataTranslator";
+/**
+ * What the statement that produced these rows actually did.
+ *
+ * Supplied by the plugin because only its query builder knows: an extension may be missing, a
+ * window may have made a pushdown unsafe, an inner filter may have had no column to compare
+ * against. Every flag defaults to false — the safe direction, since doing the work twice is slow
+ * and skipping it is wrong.
+ */
+export type SqlPushdown = {
+    /** The statement contained a real `INNER JOIN`/`LEFT JOIN` and its rows are already tuples. */
+    join?: boolean;
+};
 export declare class SqlTranslator<TRoot extends {}, TShape> extends DataTranslator<TRoot, TShape> {
+    protected readonly pushedDown: SqlPushdown;
+    constructor(query: IQuery<TRoot, TShape>, pushedDown?: SqlPushdown);
     count<TResult extends number>(data: unknown, _: QueryOption<TShape, "count">): TResult;
     min<TResult extends string | number | Date>(data: unknown, _: QueryOption<TShape, "min">): TResult;
     max<TResult extends string | number | Date>(data: unknown, _: QueryOption<TShape, "max">): TResult;
@@ -11,6 +26,36 @@ export declare class SqlTranslator<TRoot extends {}, TShape> extends DataTransla
     skip(data: unknown, _: QueryOption<TShape, "skip">): TShape;
     take(data: unknown, _: QueryOption<TShape, "take">): TShape;
     sort(data: unknown, _: QueryOption<TShape, "sort">): TShape;
+    /**
+     * Scores in memory, unlike every other shaper here.
+     *
+     * The pass-throughs above are safe because the SQL that produced these rows contained the
+     * corresponding clause. No `sql-core` statement contains a similarity ordering — engines
+     * that can express one are the exception, not the rule — so passing the data through
+     * would return whatever order the engine happened to produce.
+     *
+     * A plugin whose engine DID push the search down overrides this with a pass-through,
+     * gated on `option.target`. Postgres is the only one today.
+     *
+     * Rows arrive keyed by storage column name and are read that way rather than through the
+     * option's selector, because the selector is written against the entity shape and these
+     * rows have not been deserialized into it yet.
+     */
+    nearest(data: unknown, option: QueryOption<TShape, "nearest">): TShape;
+    /**
+     * Passes through only when the statement really did contain the `JOIN`, and refuses otherwise.
+     *
+     * The pass-throughs above are safe unconditionally because the SQL that produced these rows
+     * contained the corresponding clause. A join is not like that: if the plugin did not emit one,
+     * these rows are the outer side alone, and passing them through hands the caller entities
+     * where the contract says tuples — every `([outer, inner]) => ...` lambda downstream then
+     * destructures the wrong object, and nothing errors.
+     *
+     * So the plugin has to say, and the default is to refuse. A plugin that DID emit the join has
+     * already split each flat row into its two deserialized halves (`splitJoinRows` in
+     * `@routier/sql-plugin-core`), so by the time the option is walked the work is done.
+     */
+    join(data: unknown, option: QueryOption<TShape, "join">): TShape;
     group<T>(data: unknown, option: QueryOption<T, "group">): T;
     map(data: unknown, option: QueryOption<TShape, "map">): TShape;
 }