@routier/core 0.2.0 → 0.3.0

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

@@ -13,10 +13,32 @@ export declare class QueryOptionsCollection<T> {
     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>;
     };
+    hasTransformations(): boolean;
     has<K extends QueryOptionName>(name: K): boolean;
     get<K extends QueryOptionName>(name: K): QueryCollectionItem<T, K>[];
     getLast<K extends QueryOptionName>(name: K): QueryOption<T, K> | null;

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

@@ -1,3 +1,5 @@
+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"
@@ -29,6 +31,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 +47,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;
 }

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

@@ -1,6 +1,8 @@
 import { ITranslatedValue } from './types';
 export declare class TranslatedArrayValue<T> implements ITranslatedValue<T> {
     readonly value: T;
-    constructor(value: unknown);
+    readonly isTransformed: boolean;
+    readonly isEmpty: boolean;
+    constructor(value: unknown, isTransformed: boolean);
     forEach(callback: (item: unknown) => unknown): void;
 }

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

@@ -1,6 +1,8 @@
 import { ITranslatedValue } from './types';
 export declare class TranslatedGroupValue<T> implements ITranslatedValue<T> {
     readonly value: T;
-    constructor(value: unknown);
+    readonly isTransformed: boolean;
+    readonly isEmpty: boolean;
+    constructor(value: unknown, isTransformed: boolean);
     forEach(callback: (item: unknown) => unknown): void;
 }

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

@@ -1,6 +1,8 @@
 import { ITranslatedValue } from './types';
 export declare class TranslatedSingleValue<T> implements ITranslatedValue<T> {
     value: T;
-    constructor(value: unknown);
+    readonly isTransformed: boolean;
+    readonly isEmpty: boolean;
+    constructor(value: unknown, isTransformed: boolean);
     forEach(callback: (item: unknown) => unknown): void;
 }

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

@@ -0,0 +1,45 @@
+import { DataTranslator } from "./DataTranslator";
+import { QueryOption } from "../query/types";
+/**
+ * The memory half's pass over JOIN TUPLES.
+ *
+ * `JsonTranslator` cannot do this job, and the reason is one line of it: `map` and `group` walk
+ * `option.value.fields` and deserialize each field through its `PropertyInfo`. A tuple has no
+ * schema and no fields — `getFields` over `([p, m]) => ({ ... })` extracts nothing meaningful —
+ * so that loop would either no-op or write properties onto a two-element array.
+ *
+ * Everything a join query is allowed to do after the join is expressible as a plain closure
+ * over the tuple, and that is all this does. The lambdas the caller wrote (`([p, m]) => ...`)
+ * are applied as-is, which is also why the result is identical whichever backend produced the
+ * pairs.
+ *
+ * Both halves are already in entity shape when the tuples arrive here (the wire contract), so
+ * there is nothing left to deserialize — the reason the missing field loop costs nothing.
+ *
+ * The absent operations are absent by design, not by omission: `sum`/`min`/`max`/`distinct` and
+ * `group` are not declared on the tuple queryable's type, so reaching them means something
+ * built an option this API cannot express, and a throw naming it is the honest answer.
+ */
+export declare class TupleTranslator<TRoot extends {}, TShape> extends DataTranslator<TRoot, TShape> {
+    filter<TResult>(data: unknown, option: QueryOption<TShape, "filter">): TResult;
+    map<TResult>(data: unknown, option: QueryOption<TShape, "map">): TResult;
+    sort<TResult>(data: unknown, option: QueryOption<TShape, "sort">): TResult;
+    skip<TResult>(data: unknown, option: QueryOption<TShape, "skip">): TResult;
+    take<TResult>(data: unknown, option: QueryOption<TShape, "take">): TResult;
+    count<TResult extends number>(data: unknown, _: QueryOption<TShape, "count">): TResult;
+    /**
+     * Already joined by the time anything reaches here.
+     *
+     * The pairs were produced either by the plugin (its translator's `join`) or by the datastore
+     * before this pass ran, so the option is a record of what happened rather than work to do.
+     */
+    join(data: unknown, _: QueryOption<TShape, "join">): TShape;
+    group<TResult>(_: unknown, __: QueryOption<TShape, "group">): TResult;
+    sum<TResult extends number>(_: unknown, __: QueryOption<TShape, "sum">): TResult;
+    min<TResult extends string | number | Date>(_: unknown, __: QueryOption<TShape, "min">): TResult;
+    max<TResult extends string | number | Date>(_: unknown, __: QueryOption<TShape, "max">): TResult;
+    distinct<TResult>(_: unknown, __: QueryOption<TShape, "distinct">): TResult;
+    nearest(_: unknown, __: QueryOption<TShape, "nearest">): TShape;
+    private notSupported;
+    private notAnArray;
+}

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

@@ -1,6 +1,7 @@
 export * from './DataTranslator';
 export * from './JsonTranslator';
 export * from './SqlTranslator';
+export * from './TupleTranslator';
 export * from './types';
 export * from './TranslatedArrayValue';
 export * from './TranslatedGroupValue';

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

@@ -2,9 +2,16 @@ export interface ITranslatedValue<T> {
     readonly value: T;
     /**
      * Iterates over items in the collection, calling the callback for each item.
-     * If the callback returns a value, that value will replace the original item in the collection.
+     * If the callback returns a value, that value replaces the original item (e.g. so
+     * changeTracker.resolve() can swap in attached/merged entities).
      *
      * @param callback Function called for each item. If it returns a value, that value replaces the original item.
      */
     forEach(callback: (item: unknown) => unknown): void;
+    /**
+     * True if the translator remapped or transformed the data from the database shape;
+     * false if the data is unchanged and in the same shape as the database.
+     */
+    readonly isTransformed: boolean;
+    readonly isEmpty: boolean;
 }