@davidtkramer/convex-relations 0.1.0 → 0.4.0

package/README.md

@@ -1,49 +1,12 @@
-# `@davidtkramer/convex-relations`
+<div align="center">
+  <img width="120" height="120" alt="image" src="https://github.com/user-attachments/assets/05619751-ea3a-4dd9-9bd7-3c231bd11d83" />
 
-Typed relations and query composition for Convex backends.
+  <h1>Convex Relations</h1>
+</div>
 
-`convex-relations` is a server-side query facade for Convex. It gives you typed
-table namespaces from your generated `DataModel`, strongly typed index lookups,
-relation expansion with `with(...)`, join-table traversal with `via(...)`,
-batch loading with `.in(...)`, and arbitrary computed fields with `compute(...)`.
-
-It is designed for Convex query and mutation code, not frontend query clients.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Example](#example)
-- [Equivalent Convex Code](#equivalent-convex-code)
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-- [API](#api)
-- [Table Access Patterns](#table-access-patterns)
-- [Relation Expansion with `with(...)`](#relation-expansion-with-with)
-- [Join Table Traversal with `via(...)`](#join-table-traversal-with-via)
-- [Terminals](#terminals)
-- [Error Semantics](#error-semantics)
-- [Performance Characteristics](#performance-characteristics)
-- [Comparison to `convex-helpers/server/relationships`](#comparison-to-convex-helpersserverrelationships)
-- [Type Notes](#type-notes)
-- [License](#license)
-
-## Installation
-
-```bash
-npm install @davidtkramer/convex-relations
-```
-
-```bash
-pnpm add @davidtkramer/convex-relations
-```
-
-```bash
-bun add @davidtkramer/convex-relations
-```
-
-```bash
-yarn add @davidtkramer/convex-relations
-```
+`convex-relations` is a server-side query facade for Convex. It lets you write
+data loading code as a typed result tree instead of manually coordinating
+lookups, parallelization, and response shaping by hand.
 
 ## Example
 
@@ -67,8 +30,7 @@ export const getPost = query({
           }))
           .take(10),
         categories: ctx.q.categories
-          .via("postCategories", "categoryId")
-          .byPostId(post._id)
+          .through(ctx.q.postCategories.byPostId(post._id), "categoryId")
           .many(),
       }))
       .unique();
@@ -87,18 +49,18 @@ export const getPost = query({
 });
 ```
 
-This example shows most of the value proposition in one place:
+This example shows the core model:
 
-- table-scoped access through `q.posts`, `q.comments`, `q.categories`
-- typed index lookup with `.bySlug(...)` and `.byPostId(...)`
+- table-scoped access through `q.posts`, `q.comments`, and `q.categories`
+- indexes as first-class query methods like `.bySlug(...)` and `.byPostId(...)`
 - nested relation expansion with `.with(...)` inside `.with(...)`
-- typed join traversal with `.via(...)`
-- parallel nested loading inside one `with(...)`
-- a final strongly typed result from one expression
+- reference traversal with `.through(...)`
+- parallel nested loading within each `with(...)`
+- a final strongly typed, API-ready result from one expression
 
 ## Equivalent Convex Code
 
-Without `convex-relations`, you end up assembling the same result shape by hand:
+Without `convex-relations`, you end up assembling the same result shape by hand (or by agent 😉):
 
 ```ts
 const post = await ctx.db
@@ -150,7 +112,38 @@ That works, but you are responsible for:
 - remembering to manually `Promise.all(...)` nested relationships
 - traversing join tables by hand
 - assembling the final tree shape yourself for API responses
-- keeping the whole thing type-safe as it grows
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [API](#api)
+- [Table Access Patterns](#table-access-patterns)
+- [Relation Expansion with `with(...)`](#relation-expansion-with-with)
+- [Reference Traversal with `through(...)`](#reference-traversal-with-through)
+- [Terminals](#terminals)
+- [Error Semantics](#error-semantics)
+- [Performance Characteristics](#performance-characteristics)
+- [Comparison to `convex-helpers/server/relationships`](#comparison-to-convex-helpersserverrelationships)
+
+## Installation
+
+```bash
+npm install @davidtkramer/convex-relations
+```
+
+```bash
+pnpm add @davidtkramer/convex-relations
+```
+
+```bash
+bun add @davidtkramer/convex-relations
+```
+
+```bash
+yarn add @davidtkramer/convex-relations
+```
 
 ## Quick Start
 
@@ -162,12 +155,13 @@ wrappers. A minimal setup looks like this:
 import { customCtx, customQuery } from "convex-helpers/server/customFunctions";
 import { query as baseQuery } from "./_generated/server";
 import type { DataModel } from "./_generated/dataModel";
+import schema from "../schema";
 import { createQueryFacade } from "@davidtkramer/convex-relations";
 
 export const query = customQuery(
   baseQuery,
   customCtx((ctx: { db: any }) => ({
-    q: createQueryFacade<DataModel>(ctx.db),
+    q: createQueryFacade<DataModel>(ctx.db, schema),
   })),
 );
 ```
@@ -220,36 +214,82 @@ comments: defineTable({
 const author = await ctx.q.authors.bySlug("ada-lovelace").unique();
 const comments = await ctx.q.comments.byPostId(postId).many();
 const approvedComments = await ctx.q.comments
-  .byPostIdAndStatus({ postId, status: "approved" })
+  .byPostIdAndStatus(postId, "approved")
   .many();
 ```
 
-Single-field indexes accept a scalar. Compound indexes accept an object that
-matches a leading slice of the index definition. Zero-argument calls give you
-the indexed range so you can filter, sort, paginate, or take a subset.
+Single-field indexes accept a scalar. Compound indexes accept positional
+arguments in index order. Zero-argument calls give you the indexed range so you
+can filter, sort, paginate, or take a subset.
+
+Because shorthand index methods like `.bySlug("...")` and
+`.byPostIdAndStatus(...)` need the real indexed field names at runtime,
+`createQueryFacade(...)` must be constructed with your Convex schema.
+
+### `with(...)` builds nested result shapes
+
+`with(...)` lets you attach additional fields to every document in a query. The
+callback receives the current document plus a small helper context, and returns
+an object whose values can be plain sync values, other query nodes, or deferred
+work via `defer(...)`.
+
+```ts
+const post = await ctx.q.posts
+  .bySlug("hello-world")
+  .with((post, { defer }) => ({
+    author: ctx.q.authors.find(post.authorId),
+    comments: ctx.q.comments.byPostId(post._id).take(10),
+    readingTimeMinutes: defer(() =>
+      Math.ceil(post.body.split(/\s+/).length / 200),
+    ),
+  }))
+  .unique();
+```
+
+That returns a single object shaped like:
+
+```ts
+{
+  ...post,
+  author,
+  comments,
+}
+```
+
+This is the core idea behind the library: compose the data you want as a tree,
+and `convex-relations` resolves and assembles that tree for you.
+
+Within a single `with(...)`, sibling fields are resolved in parallel. If you
+attach both `author` and `comments`, those branches start loading at the same
+time. Nested `with(...)` calls preserve that behavior recursively, so each level
+of the result tree parallelizes across its sibling fields.
 
 ## API
 
-### `createQueryFacade<DataModel>(db)`
+### `createQueryFacade<DataModel>(db, schema)`
 
-Creates a typed facade over your Convex `db`.
+Creates a typed facade over your Convex `db`. Pass the runtime schema from
+`defineSchema(...)` so indexed shorthand methods can map scalar and tuple
+arguments onto the correct Convex index fields.
 
 ```ts
 import { createQueryFacade } from "@davidtkramer/convex-relations";
 import type { DataModel } from "./_generated/dataModel";
+import schema from "../schema";
 
-const q = createQueryFacade<DataModel>(ctx.db);
+const q = createQueryFacade<DataModel>(ctx.db, schema);
 ```
 
-### `compute(load)`
+### `with(..., { defer })`
 
-Wraps arbitrary async or sync work so it can be used inside `with(...)`.
+The `with(...)` callback context includes `defer`, which wraps arbitrary async
+or sync work into the same lazy result tree as your relation queries.
 
 ```ts
 const post = await q.posts
   .bySlug("hello-world")
-  .with((post) => ({
-    readingTimeMinutes: compute(() =>
+  .with((post, { defer }) => ({
+    readingTimeMinutes: defer(() =>
       Math.ceil(post.body.split(/\s+/).length / 200),
     ),
   }))
@@ -291,16 +331,16 @@ Single-field indexes accept a scalar:
 const author = await q.authors.bySlug("ada-lovelace").unique();
 ```
 
-Compound indexes accept an object containing a valid prefix:
+Compound indexes accept leading positional arguments:
 
 ```ts
 const comments = await q.comments
-  .byPostIdAndCreatedAt({ postId })
+  .byPostIdAndStatus(postId)
   .order("desc")
   .take(20);
 
 const exactOrPrefix = await q.comments
-  .byPostIdAndCreatedAt({ postId, createdAt: 1700000000000 })
+  .byPostIdAndStatus(postId, "approved")
   .many();
 ```
 
@@ -309,8 +349,8 @@ const exactOrPrefix = await q.comments
 You can also pass Convex's index selector callback:
 
 ```ts
-const recentComments = await q.comments
-  .byPostIdAndCreatedAt((q) => q.eq("postId", postId).gt("createdAt", cutoff))
+const approvedComments = await q.comments
+  .byPostIdAndStatus((q) => q.eq("postId", postId).eq("status", "approved"))
   .many();
 ```
 
@@ -335,10 +375,10 @@ Batch lookups skip missing rows.
 ```ts
 const post = await q.posts
   .bySlug("hello-world")
-  .with((post) => ({
+  .with((post, { defer }) => ({
     author: q.authors.find(post.authorId),
     comments: q.comments.byPostId(post._id).order("desc").take(10),
-    commentCount: compute(async () => {
+    commentCount: defer(async () => {
       const comments = await q.comments.byPostId(post._id).many();
       return comments.length;
     }),
@@ -362,33 +402,66 @@ const post = await q.posts
 
 Each `with(...)` stage sees fields added by earlier stages.
 
-## Join Table Traversal with `via(...)`
+## Reference Traversal with `through(...)`
 
-Use `via(joinTable, targetField)` for many-to-many relationships.
+Use `through(sourceQuery, foreignKeyField)` when another query already produces
+rows that point at the table you want.
 
 Given `postCategories { postId, categoryId }`, you can fetch categories for a post:
 
 ```ts
 const categories = await q.categories
-  .via("postCategories", "categoryId")
-  .byPostId(postId)
+  .through(q.postCategories.byPostId(postId), "categoryId")
   .many();
 ```
 
-You can also attach the join row with `withSource(...)`:
+This is essentially syntactic sugar for "run the source query, extract ids from
+that field, then load the target rows for you."
+
+You can also attach the source row through the normal `with(...)` callback:
 
 ```ts
 const categories = await q.categories
-  .via("postCategories", "categoryId")
-  .byPostId(postId)
-  .withSource("link")
+  .through(q.postCategories.byPostId(postId).order("desc"), "categoryId")
+  .with((category, { source }) => ({ link: source }))
   .many();
 
 categories[0]?.link.postId;
 categories[0]?.link.categoryId;
 ```
 
-This is useful when the join table stores metadata like ordering, role, or timestamps.
+This is useful when the source table stores metadata like ordering, role, or
+timestamps.
+
+`through(...)` is not limited to join tables. Any compatible source query works:
+
+```ts
+const author = await q.authors
+  .through(q.posts.bySlug("hello-world"), "authorId")
+  .with((author, { source }) => ({ post: source }))
+  .unique();
+
+author.post.slug;
+```
+
+Source-query shaping lives inside the `through(...)` argument:
+
+```ts
+const tags = await q.tags
+  .through(
+    q.postTags
+      .byPostId(postId)
+      .filter((query) => query.eq(query.field("kind"), "primary"))
+      .order("desc")
+      .take(10),
+    "tagId",
+  )
+  .with((tag, { source }) => ({ link: source }))
+  .many();
+```
+
+After `through(...)`, you can keep shaping the target result with `with(...)`
+and then choose a terminal like `many()` or `first()`.
 
 ## Terminals
 
@@ -447,7 +520,6 @@ const page = await q.posts.byAuthorId(authorId).paginate({
 - `unique()` also throws if there are multiple matches
 - `first()` throws if there is no match
 - `findOrNull()`, `uniqueOrNull()`, and `firstOrNull()` return `null` instead
-- `via(...).unique()` normalizes its duplicate error to include the target table and join index
 
 ## Performance Characteristics
 
@@ -456,13 +528,12 @@ const page = await q.posts.byAuthorId(authorId).paginate({
 Within a single `with(...)` stage, every field in the returned object runs in parallel.
 
 ```ts
-const post = await q.posts.find(postId).with((post) => ({
+const post = await q.posts.find(postId).with((post, { defer }) => ({
   author: q.authors.find(post.authorId),
   comments: q.comments.byPostId(post._id).take(10),
-  categoryCount: compute(async () => {
+  categoryCount: defer(async () => {
     const categories = await q.categories
-      .via("postCategories", "categoryId")
-      .byPostId(post._id)
+      .through(q.postCategories.byPostId(post._id), "categoryId")
       .many();
     return categories.length;
   }),
@@ -489,7 +560,9 @@ q.posts
 
 The second stage waits for the first stage, because it depends on fields added earlier.
 
-`via(...)` currently resolves target documents by fetching join rows first, then loading each target document individually. This is correct and predictable, but it is not a single batched join at the database level.
+`through(...)` currently resolves target documents by fetching the source rows
+first, then loading each target document individually. This is correct and
+predictable, but it is not a single batched join at the database level.
 
 ### Practical guidance
 
@@ -507,8 +580,7 @@ This:
 
 ```ts
 const categories = await q.categories
-  .via("postCategories", "categoryId")
-  .byPostId(postId)
+  .through(q.postCategories.byPostId(postId), "categoryId")
   .many();
 ```
 
@@ -525,15 +597,3 @@ const categories = await getManyVia(
 ```
 
 but also composes naturally with `with(...)`, `take(...)`, `firstOrNull()`, and typed nested traversal.
-
-## Type Notes
-
-- The facade is generic over your generated `DataModel`
-- Table names, `_id` types, index names, and compound index prefixes are inferred
-- Invalid table names and invalid index names are rejected at compile time
-- Scalar shorthand is only allowed for single-field indexes
-- Compound indexes require a valid prefix object
-
-## License
-
-MIT

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { GenericDataModel, TableNamesInDataModel, DocumentByName, IndexNames, NamedTableInfo, NamedIndex, GenericDatabaseReader } from 'convex/server';
+import { GenericDataModel, TableNamesInDataModel, DocumentByName, GenericTableInfo, FilterBuilder, ExpressionOrValue, NamedTableInfo, IndexNames, IndexRangeBuilder, NamedIndex, IndexRange, GenericDatabaseReader } from 'convex/server';
 import { GenericId } from 'convex/values';
 
 type Simplify<T> = {
@@ -8,38 +8,55 @@ type AppTable<DataModel extends GenericDataModel> = TableNamesInDataModel<DataMo
 type AppDoc<DataModel extends GenericDataModel, Table extends AppTable<DataModel>> = DocumentByName<DataModel, Table>;
 type UserIndex<DataModel extends GenericDataModel, Table extends AppTable<DataModel>> = Exclude<IndexNames<NamedTableInfo<DataModel, Table>>, 'by_creation_time'> & string;
 type RawIndexFields<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = NamedIndex<NamedTableInfo<DataModel, Table>, IndexName>;
-type IndexFields<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = Exclude<RawIndexFields<DataModel, Table, IndexName>[number], '_creationTime'>;
-type SingleIndexField<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = RawIndexFields<DataModel, Table, IndexName> extends [
-    infer Field extends string,
+type StripCreationTime<Fields extends readonly string[]> = Fields extends readonly [
+    ...infer Rest extends readonly string[],
     '_creationTime'
+] ? Rest : Fields;
+type UserIndexFields<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = StripCreationTime<RawIndexFields<DataModel, Table, IndexName>>;
+type SingleIndexField<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = UserIndexFields<DataModel, Table, IndexName> extends readonly [
+    infer Field extends string
 ] ? Field : never;
-type TuplePrefixValues<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, Fields extends readonly string[], Seen extends readonly string[] = []> = Fields extends readonly [
+type TuplePrefixArgs<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, Fields extends readonly string[], Seen extends readonly string[] = [], SeenValues extends readonly unknown[] = []> = Fields extends readonly [
     infer Head extends string,
     ...infer Tail extends readonly string[]
-] ? Simplify<{
-    [FieldName in [...Seen, Head][number]]: AppDoc<DataModel, Table>[FieldName];
-}> | TuplePrefixValues<DataModel, Table, Tail, [...Seen, Head]> : never;
-type PrefixIndexValues<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = TuplePrefixValues<DataModel, Table, RawIndexFields<DataModel, Table, IndexName>>;
-type RootIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = PrefixIndexValues<DataModel, Table, IndexName> | (SingleIndexField<DataModel, Table, IndexName> extends never ? never : AppDoc<DataModel, Table>[SingleIndexField<DataModel, Table, IndexName>]);
-type StrictRootIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>, Value extends RootIndexValueArg<DataModel, Table, IndexName>> = Value extends PrefixIndexValues<DataModel, Table, IndexName> ? Value & Record<Exclude<keyof Value, IndexFields<DataModel, Table, IndexName>>, never> : Value;
+] ? [...SeenValues, AppDoc<DataModel, Table>[Head]] | TuplePrefixArgs<DataModel, Table, Tail, [
+    ...Seen,
+    Head
+], [
+    ...SeenValues,
+    AppDoc<DataModel, Table>[Head]
+]> : never;
+type PositionalIndexArgs<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = TuplePrefixArgs<DataModel, Table, UserIndexFields<DataModel, Table, IndexName>>;
+type RootIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = PositionalIndexArgs<DataModel, Table, IndexName> | (SingleIndexField<DataModel, Table, IndexName> extends never ? never : AppDoc<DataModel, Table>[SingleIndexField<DataModel, Table, IndexName>]);
+type StrictRootIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>, Value extends RootIndexValueArg<DataModel, Table, IndexName>> = Value;
 type TableIndexName<DataModel extends GenericDataModel, Table extends AppTable<DataModel>> = UserIndex<DataModel, Table> | 'by_id';
-type TableIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends TableIndexName<DataModel, Table>> = IndexName extends 'by_id' ? GenericId<Table> : IndexName extends UserIndex<DataModel, Table> ? RootIndexValueArg<DataModel, Table, IndexName> : never;
-type StrictTableIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends TableIndexName<DataModel, Table>, Value extends TableIndexValueArg<DataModel, Table, IndexName>> = IndexName extends 'by_id' ? Value : IndexName extends UserIndex<DataModel, Table> ? StrictRootIndexValueArg<DataModel, Table, IndexName, Extract<Value, RootIndexValueArg<DataModel, Table, IndexName>>> : never;
+type UserIndexArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = SingleIndexField<DataModel, Table, IndexName> extends never ? PositionalIndexArgs<DataModel, Table, IndexName> : AppDoc<DataModel, Table>[SingleIndexField<DataModel, Table, IndexName>];
+type TableIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends TableIndexName<DataModel, Table>> = IndexName extends 'by_id' ? GenericId<Table> : IndexName extends UserIndex<DataModel, Table> ? UserIndexArg<DataModel, Table, IndexName> : never;
+type StrictTableIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends TableIndexName<DataModel, Table>, Value extends TableIndexValueArg<DataModel, Table, IndexName>> = Value;
+type TableIndexInvocationArgs<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends TableIndexName<DataModel, Table>> = IndexName extends 'by_id' ? [GenericId<Table>] : IndexName extends UserIndex<DataModel, Table> ? PositionalIndexArgs<DataModel, Table, IndexName> : never;
 type IdTargetTable<DataModel extends GenericDataModel, Value> = Value extends GenericId<infer Table extends AppTable<DataModel>> ? Table : never;
-type JoinTargetTable<DataModel extends GenericDataModel, JoinTable extends AppTable<DataModel>, TargetField extends Extract<keyof AppDoc<DataModel, JoinTable>, string>> = IdTargetTable<DataModel, AppDoc<DataModel, JoinTable>[TargetField]>;
 type QueryNode<Output> = PromiseLike<Output> & {
     readonly _executeRoot: () => Promise<Output>;
 };
-type WithSpec = Record<string, QueryNode<any>>;
-type WithBuilder<ParentItem, Spec extends WithSpec | undefined = WithSpec | undefined> = (parent: ParentItem) => Spec;
-type AnyWithBuilder<ParentItem> = WithBuilder<ParentItem, WithSpec | undefined>;
+type TableInfo<DataModel extends GenericDataModel, Table extends AppTable<DataModel>> = NamedTableInfo<DataModel, Table>;
+type QueryPlanHandle<DataModel extends GenericDataModel, Table extends AppTable<DataModel>> = {
+    readonly _plan: QueryPlan;
+    readonly _table: Table;
+};
+type WithSpec = Record<string, unknown>;
+type DeferredBuilder = <Output>(load: () => Promise<Output> | Output) => QueryNode<Output>;
+type BaseWithContext = {
+    defer: DeferredBuilder;
+};
+type WithContext<SourceItem = never> = BaseWithContext & ([SourceItem] extends [never] ? {} : {
+    source: SourceItem;
+});
+type WithBuilder<ParentItem, Context = BaseWithContext, Spec extends WithSpec | undefined = WithSpec | undefined> = (parent: ParentItem, context: Context) => Spec;
+type AnyWithBuilder<ParentItem, Context = BaseWithContext> = WithBuilder<ParentItem, Context, WithSpec | undefined>;
 type BuiltWithSpec<Builder> = Builder extends (...args: any[]) => infer Spec ? Spec : never;
 type ExpandWith<ParentItem, Builder> = Simplify<ParentItem & (BuiltWithSpec<Builder> extends Record<string, unknown> ? {
-    [K in keyof BuiltWithSpec<Builder>]: BuiltWithSpec<Builder>[K] extends QueryNode<infer Output> ? Output : never;
+    [K in keyof BuiltWithSpec<Builder>]: BuiltWithSpec<Builder>[K] extends QueryNode<infer Output> ? Output : BuiltWithSpec<Builder>[K];
 } : {})>;
-type AttachSource<ParentItem, SourceItem, SourceKey extends string> = Simplify<ParentItem & {
-    [K in SourceKey]: SourceItem;
-}>;
 type PaginationOptions = {
     numItems: number;
     cursor: string | null;
@@ -49,81 +66,89 @@ type PaginatedResult<Item> = {
     isDone: boolean;
     continueCursor: string;
 };
-type QueryFilter = (q: any) => any;
-type IndexSelector = (q: any) => any;
-type ExpandableSingleQueryBuilder<Item, Nullable extends boolean> = QueryNode<Nullable extends true ? Item | null : Item> & {
+type QueryFilter<TableInfo extends GenericTableInfo> = (q: FilterBuilder<TableInfo>) => ExpressionOrValue<boolean>;
+type QueryModifier = (query: any) => any;
+type IndexSelector<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = (q: IndexRangeBuilder<AppDoc<DataModel, Table>, NamedIndex<TableInfo<DataModel, Table>, IndexName>>) => IndexRange;
+type SingleNodeKind<Nullable extends boolean> = Nullable extends true ? 'nullableSingle' : 'single';
+type SingleQueryBuilder<Item, Nullable extends boolean> = QueryNode<Nullable extends true ? Item | null : Item> & ThroughNodeHandle<Item, SingleNodeKind<Nullable>>;
+type ExpandableSingleQueryBuilder<Item, Nullable extends boolean> = SingleQueryBuilder<Item, Nullable> & {
     with<Builder extends AnyWithBuilder<Item>>(withBuilder: Builder): ExpandableSingleQueryBuilder<ExpandWith<Item, Builder>, Nullable>;
 };
-type SingleQueryBuilder<Item, Nullable extends boolean> = QueryNode<Nullable extends true ? Item | null : Item>;
 type UniqueQueryBuilder<Item> = SingleQueryBuilder<Item, false>;
 type UniqueOrNullQueryBuilder<Item> = SingleQueryBuilder<Item, true>;
 type FirstQueryBuilder<Item> = SingleQueryBuilder<Item, false>;
 type FirstOrNullQueryBuilder<Item> = SingleQueryBuilder<Item, true>;
 type FindQueryBuilder<Item> = ExpandableSingleQueryBuilder<Item, false>;
 type FindOrNullQueryBuilder<Item> = ExpandableSingleQueryBuilder<Item, true>;
-type ManyQueryBuilder<Item> = QueryNode<Item[]>;
-type BatchQueryBuilder<Item> = QueryNode<Item[]>;
-type ManyViaQueryBuilder<Item> = QueryNode<Item[]>;
+type ManyQueryBuilder<Item> = QueryNode<Item[]> & ThroughNodeHandle<Item, 'many'>;
+type BatchQueryBuilder<Item> = ManyQueryBuilder<Item>;
+type ThroughSourceNodeKind = 'many' | 'single' | 'nullableSingle';
+type ThroughNodeHandle<SourceItem, Kind extends ThroughSourceNodeKind> = {
+    readonly _throughSourceKind: Kind;
+    readonly _throughSourceType?: SourceItem;
+};
+type AnyManySourceNode<SourceItem> = QueryNode<SourceItem[]> & ThroughNodeHandle<SourceItem, 'many'>;
+type AnySingleSourceNode<SourceItem, Nullable extends boolean> = QueryNode<Nullable extends true ? SourceItem | null : SourceItem> & ThroughNodeHandle<SourceItem, SingleNodeKind<Nullable>>;
+type ThroughSourceField<DataModel extends GenericDataModel, TargetTable extends AppTable<DataModel>, SourceItem> = {
+    [Field in Extract<keyof SourceItem, string>]: IdTargetTable<DataModel, SourceItem[Field]> extends TargetTable ? Field : never;
+}[Extract<keyof SourceItem, string>];
+type ManyThroughQueryBuilder<Item, SourceItem = unknown> = QueryNode<Item[]> & ThroughNodeHandle<SourceItem, 'many'> & {
+    with<Builder extends AnyWithBuilder<Item, WithContext<SourceItem>>>(withBuilder: Builder): ManyThroughQueryBuilder<ExpandWith<Item, Builder>, SourceItem>;
+};
+type SingleThroughQueryBuilder<Item, SourceItem, Nullable extends boolean> = QueryNode<Nullable extends true ? Item | null : Item> & ThroughNodeHandle<SourceItem, Nullable extends true ? 'nullableSingle' : 'single'> & {
+    with<Builder extends AnyWithBuilder<Item, WithContext<SourceItem>>>(withBuilder: Builder): SingleThroughQueryBuilder<ExpandWith<Item, Builder>, SourceItem, Nullable>;
+};
 type TableQueryFacade<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, Item = AppDoc<DataModel, Table>> = {
     with<Builder extends AnyWithBuilder<Item>>(withBuilder: Builder): TableQueryFacade<DataModel, Table, ExpandWith<Item, Builder>>;
     order(direction: 'asc' | 'desc'): TableQueryFacade<DataModel, Table, Item>;
-    filter(filterer: QueryFilter): TableQueryFacade<DataModel, Table, Item>;
+    filter(filterer: QueryFilter<TableInfo<DataModel, Table>>): TableQueryFacade<DataModel, Table, Item>;
     unique(): UniqueQueryBuilder<Item>;
     uniqueOrNull(): UniqueOrNullQueryBuilder<Item>;
     first(): FirstQueryBuilder<Item>;
     firstOrNull(): FirstOrNullQueryBuilder<Item>;
-    take(count: number): Promise<Item[]>;
+    take(count: number): ManyQueryBuilder<Item>;
     paginate(opts: PaginationOptions): Promise<PaginatedResult<Item>>;
     many(): ManyQueryBuilder<Item>;
-};
+} & QueryPlanHandle<DataModel, Table>;
 type TableRangeQueryFacade<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, Item = AppDoc<DataModel, Table>> = {
     with<Builder extends AnyWithBuilder<Item>>(withBuilder: Builder): TableRangeQueryFacade<DataModel, Table, ExpandWith<Item, Builder>>;
     order(direction: 'asc' | 'desc'): TableRangeQueryFacade<DataModel, Table, Item>;
-    filter(filterer: QueryFilter): TableRangeQueryFacade<DataModel, Table, Item>;
+    filter(filterer: QueryFilter<TableInfo<DataModel, Table>>): TableRangeQueryFacade<DataModel, Table, Item>;
     unique(): UniqueQueryBuilder<Item>;
     uniqueOrNull(): UniqueOrNullQueryBuilder<Item>;
     first(): FirstQueryBuilder<Item>;
     firstOrNull(): FirstOrNullQueryBuilder<Item>;
-    take(count: number): Promise<Item[]>;
+    take(count: number): ManyQueryBuilder<Item>;
     paginate(opts: PaginationOptions): Promise<PaginatedResult<Item>>;
     many(): ManyQueryBuilder<Item>;
-};
+} & QueryPlanHandle<DataModel, Table>;
 type TableBatchQueryFacade<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, Item = AppDoc<DataModel, Table>> = {
     with<Builder extends AnyWithBuilder<Item>>(withBuilder: Builder): TableBatchQueryFacade<DataModel, Table, ExpandWith<Item, Builder>>;
     many(): BatchQueryBuilder<Item>;
 };
-type ViaQueryFacade<DataModel extends GenericDataModel, TargetTable extends AppTable<DataModel>, JoinTable extends AppTable<DataModel>, Item = AppDoc<DataModel, TargetTable>> = {
-    with<Builder extends AnyWithBuilder<Item>>(withBuilder: Builder): ViaQueryFacade<DataModel, TargetTable, JoinTable, ExpandWith<Item, Builder>>;
-    order(direction: 'asc' | 'desc'): ViaQueryFacade<DataModel, TargetTable, JoinTable, Item>;
-    filter(filterer: QueryFilter): ViaQueryFacade<DataModel, TargetTable, JoinTable, Item>;
-    withSource<const SourceKey extends string>(key: SourceKey): ViaQueryFacade<DataModel, TargetTable, JoinTable, AttachSource<Item, AppDoc<DataModel, JoinTable>, SourceKey>>;
+type ThroughQueryFacade<DataModel extends GenericDataModel, TargetTable extends AppTable<DataModel>, SourceItem, Item = AppDoc<DataModel, TargetTable>> = {
+    with<Builder extends AnyWithBuilder<Item, WithContext<SourceItem>>>(withBuilder: Builder): ThroughQueryFacade<DataModel, TargetTable, SourceItem, ExpandWith<Item, Builder>>;
     unique(): UniqueQueryBuilder<Item>;
     uniqueOrNull(): UniqueOrNullQueryBuilder<Item>;
     first(): FirstQueryBuilder<Item>;
     firstOrNull(): FirstOrNullQueryBuilder<Item>;
-    take(count: number): Promise<Item[]>;
-    paginate(opts: PaginationOptions): Promise<PaginatedResult<Item>>;
-    many(): ManyViaQueryBuilder<Item>;
-};
-type ValidViaTargetField<DataModel extends GenericDataModel, JoinTable extends AppTable<DataModel>, TargetTable extends AppTable<DataModel>> = {
-    [Field in Extract<keyof AppDoc<DataModel, JoinTable>, string>]: JoinTargetTable<DataModel, JoinTable, Field> extends TargetTable ? Field : never;
-}[Extract<keyof AppDoc<DataModel, JoinTable>, string>];
-type ViaIndexNamespace<DataModel extends GenericDataModel, TargetTable extends AppTable<DataModel>, JoinTable extends AppTable<DataModel>> = {
-    [IndexName in UserIndex<DataModel, JoinTable>]: {
-        (): ViaQueryFacade<DataModel, TargetTable, JoinTable>;
-        <const Value extends RootIndexValueArg<DataModel, JoinTable, IndexName>>(value: StrictRootIndexValueArg<DataModel, JoinTable, IndexName, Value>): ViaQueryFacade<DataModel, TargetTable, JoinTable>;
-        (selector: IndexSelector): ViaQueryFacade<DataModel, TargetTable, JoinTable>;
-    };
+    many(): ManyQueryBuilder<Item>;
 };
+type ThroughCollectionSource<DataModel extends GenericDataModel, SourceTable extends AppTable<DataModel>, SourceItem = AppDoc<DataModel, SourceTable>> = TableQueryFacade<DataModel, SourceTable, SourceItem> | TableRangeQueryFacade<DataModel, SourceTable, SourceItem>;
 type TableNamespace<DataModel extends GenericDataModel, Table extends AppTable<DataModel>> = {
     find<const Id extends GenericId<Table>>(id: Id): FindQueryBuilder<AppDoc<DataModel, Table>>;
     findOrNull<const Id extends GenericId<Table>>(id: Id): FindOrNullQueryBuilder<AppDoc<DataModel, Table>>;
     in<const Id extends GenericId<Table>>(ids: Id[]): TableBatchQueryFacade<DataModel, Table>;
-    via: <const JoinTable extends AppTable<DataModel>, const TargetField extends ValidViaTargetField<DataModel, JoinTable, Table>>(joinTable: JoinTable, targetField: TargetField) => ViaIndexNamespace<DataModel, Table, JoinTable>;
+    through: {
+        <const SourceTable extends AppTable<DataModel>, SourceItem, const TargetField extends ThroughSourceField<DataModel, Table, SourceItem>>(sourceQuery: ThroughCollectionSource<DataModel, SourceTable, SourceItem>, targetField: TargetField): ThroughQueryFacade<DataModel, Table, SourceItem>;
+        <SourceItem, const TargetField extends ThroughSourceField<DataModel, Table, SourceItem>>(sourceQuery: AnyManySourceNode<SourceItem>, targetField: TargetField): ManyThroughQueryBuilder<AppDoc<DataModel, Table>, SourceItem>;
+        <SourceItem, const TargetField extends ThroughSourceField<DataModel, Table, SourceItem>>(sourceQuery: AnySingleSourceNode<SourceItem, false>, targetField: TargetField): SingleThroughQueryBuilder<AppDoc<DataModel, Table>, SourceItem, false>;
+        <SourceItem, const TargetField extends ThroughSourceField<DataModel, Table, SourceItem>>(sourceQuery: AnySingleSourceNode<SourceItem, true>, targetField: TargetField): SingleThroughQueryBuilder<AppDoc<DataModel, Table>, SourceItem, true>;
+    };
 } & TableRangeQueryFacade<DataModel, Table> & {
     [IndexName in TableIndexName<DataModel, Table>]: {
-        (selector: IndexSelector): TableQueryFacade<DataModel, Table>;
-        <const Value extends TableIndexValueArg<DataModel, Table, IndexName>>(value: StrictTableIndexValueArg<DataModel, Table, IndexName, Value>): TableQueryFacade<DataModel, Table>;
+        (selector: IndexName extends UserIndex<DataModel, Table> ? IndexSelector<DataModel, Table, IndexName> : never): TableQueryFacade<DataModel, Table>;
+        <const Args extends TableIndexInvocationArgs<DataModel, Table, IndexName>>(...args: Args): TableQueryFacade<DataModel, Table>;
         (): TableRangeQueryFacade<DataModel, Table>;
         in<const Value extends TableIndexValueArg<DataModel, Table, IndexName>>(values: StrictTableIndexValueArg<DataModel, Table, IndexName, Value>[]): TableBatchQueryFacade<DataModel, Table>;
     };
@@ -131,7 +156,26 @@ type TableNamespace<DataModel extends GenericDataModel, Table extends AppTable<D
 type QueryFacade<DataModel extends GenericDataModel> = {
     [Table in AppTable<DataModel>]: TableNamespace<DataModel, Table>;
 };
+type QuerySourcePlan = {
+    kind: 'id';
+    table: string;
+    id: GenericId<any>;
+} | {
+    kind: 'query';
+    table: string;
+    index?: string;
+    selector?: unknown;
+} | {
+    kind: 'batch';
+    table: string;
+    index: string;
+    values: unknown[];
+};
+type QueryPlan = {
+    source: QuerySourcePlan;
+    modifiers: QueryModifier[];
+    expanders: AnyWithBuilder<any, any>[];
+};
 declare function createQueryFacade<DataModel extends GenericDataModel>(db: GenericDatabaseReader<DataModel>): QueryFacade<DataModel>;
-declare function compute<Output = unknown>(load: () => Promise<Output> | Output): QueryNode<Output>;
 
-export { type AppDoc, type AppTable, type QueryFacade, type RootIndexValueArg, type StrictRootIndexValueArg, type UserIndex, compute, createQueryFacade };
+export { type AppDoc, type AppTable, type QueryFacade, type RootIndexValueArg, type StrictRootIndexValueArg, type UserIndex, createQueryFacade };

package/dist/index.js

@@ -8,31 +8,46 @@ function createQueryNode(executeRoot) {
     }
   };
 }
-async function expandDoc(parent, withBuilder) {
-  const spec = withBuilder(parent) ?? {};
+function createDeferredNode(load) {
+  return createQueryNode(async () => await load());
+}
+function isQueryNode(value) {
+  return typeof value === "object" && value !== null && "_executeRoot" in value && typeof value._executeRoot === "function";
+}
+async function expandDoc(parent, withBuilder, context) {
+  const spec = withBuilder(parent, context) ?? {};
   const entries = await Promise.all(
-    Object.entries(spec).map(
-      async ([key, query]) => [key, await query._executeRoot()]
-    )
+    Object.entries(spec).map(async ([key, value]) => [
+      key,
+      isQueryNode(value) ? await value._executeRoot() : value
+    ])
   );
   return {
     ...parent,
     ...Object.fromEntries(entries)
   };
 }
-async function applyExpanders(item, expanders) {
+async function applyExpanders(item, expanders, context) {
   let current = item;
   for (const expander of expanders) {
-    current = await expandDoc(current, expander);
+    current = await expandDoc(current, expander, context);
   }
   return current;
 }
-async function applyExpandersToMany(items, expanders) {
-  return await Promise.all(items.map((item) => applyExpanders(item, expanders)));
+async function applyExpandersToMany(items, expanders, getContext) {
+  return await Promise.all(
+    items.map((item, index) => applyExpanders(item, expanders, getContext(item, index)))
+  );
 }
 function buildQuery(makeQuery, modifiers) {
   return modifiers.reduce((query, modifier) => modifier(query), makeQuery());
 }
+function createWithContext(source) {
+  return {
+    defer: createDeferredNode,
+    ...source === void 0 ? {} : { source }
+  };
+}
 function createPlan(source) {
   return {
     source,
@@ -52,13 +67,11 @@ function withExpander(plan, expander) {
     expanders: [...plan.expanders, expander]
   };
 }
-function withSourceKey(plan, sourceKey) {
-  return {
-    ...plan,
-    sourceKey
-  };
-}
 function normalizeIndexValues(index, value) {
+  if (Array.isArray(value)) {
+    const fieldNames = inferFieldNamesFromIndex(index);
+    return Object.fromEntries(fieldNames.map((field, index2) => [field, value[index2]]));
+  }
   if (isPlainObject(value)) {
     return value;
   }
@@ -77,8 +90,14 @@ function applyIndexValues(query, values) {
   return current;
 }
 function inferFieldNameFromIndex(index) {
+  return inferFieldNamesFromIndex(index)[0];
+}
+function inferFieldNamesFromIndex(index) {
+  if (index === "by_id") {
+    return ["_id"];
+  }
   if (index.startsWith("by") && index.length > 2) {
-    return `${index[2].toLowerCase()}${index.slice(3)}`;
+    return index.slice(2).split("And").map((part) => `${part[0].toLowerCase()}${part.slice(1)}`);
   }
   throw new Error(`Cannot infer field name from index ${index}`);
 }
@@ -101,49 +120,61 @@ function createIndexedQuery(db, table, index, selector) {
     (q) => applyIndexValues(q, normalizeIndexValues(index, selector))
   );
 }
-function createViaQuery(db, joinTable, index, selector) {
-  const baseQuery = db.query(joinTable);
-  if (selector === void 0) {
-    return baseQuery.withIndex(index);
+function sourceDescription(plan) {
+  switch (plan.source.kind) {
+    case "id":
+      return `${plan.source.table} with id ${plan.source.id}`;
+    case "batch":
+      return `${plan.source.table} via ${plan.source.index}`;
+    case "query":
+      return plan.source.index ? `${plan.source.table} with index ${plan.source.index}` : plan.source.table;
   }
-  if (typeof selector === "function") {
-    return baseQuery.withIndex(index, selector);
+}
+async function resolveThroughPair(db, targetField, source) {
+  const id = source[targetField];
+  if (!id) {
+    return null;
   }
-  return baseQuery.withIndex(
-    index,
-    (q) => applyIndexValues(q, normalizeIndexValues(index, selector))
-  );
+  const target = await db.get(id);
+  return target ? { source, target } : null;
 }
-async function collectViaPairs(db, targetField, links) {
+async function collectThroughPairs(db, targetField, sourceItems) {
   const pairs = await Promise.all(
-    links.map(async (link) => {
-      const id = link[targetField];
-      const doc = id ? await db.get(id) : null;
-      return doc ? { doc, link } : null;
-    })
+    sourceItems.map(async (source) => await resolveThroughPair(db, targetField, source))
   );
   return pairs.filter((pair) => pair !== null);
 }
-async function collectViaPairsUntil(db, targetField, query, count) {
+async function* iterateDecoratedSourceItems(db, plan) {
+  if (plan.source.kind !== "query") {
+    for (const item of await executeMany(db, plan)) {
+      yield item;
+    }
+    return;
+  }
+  const runtime = createPlanRuntime(db, plan);
+  const source = plan.source;
+  const query = buildQuery(
+    () => createIndexedQuery(db, source.table, source.index, source.selector),
+    plan.modifiers
+  );
+  for await (const rawItem of query) {
+    yield await decorateItem(plan, rawItem, await runtime.mapOne(rawItem));
+  }
+}
+async function collectThroughPairsUntil(db, targetField, sourceItems, count) {
   const pairs = [];
-  for await (const link of query) {
-    const id = link[targetField];
-    if (!id) continue;
-    const doc = await db.get(id);
-    if (!doc) continue;
-    pairs.push({ doc, link });
+  for await (const source of sourceItems) {
+    const pair = await resolveThroughPair(db, targetField, source);
+    if (!pair) {
+      continue;
+    }
+    pairs.push(pair);
     if (pairs.length >= count) {
       break;
     }
   }
   return pairs;
 }
-function normalizeViaUniqueError(error, targetTable, joinTable, index) {
-  if (error instanceof Error && error.message === "unique() returned more than one result") {
-    return new Error(`Expected unique ${targetTable} via ${joinTable}.${index}`);
-  }
-  return error;
-}
 function createPlanRuntime(db, plan) {
   const source = plan.source;
   switch (source.kind) {
@@ -188,79 +219,23 @@ function createPlanRuntime(db, plan) {
         }
       };
     }
-    case "via": {
-      const runQuery = () => buildQuery(
-        () => createViaQuery(db, source.joinTable, source.index, source.selector),
-        plan.modifiers
-      );
-      return {
-        unique: async () => {
-          const pairs = await collectViaPairsUntil(
-            db,
-            source.targetField,
-            runQuery(),
-            2
-          );
-          if (pairs.length > 1) {
-            throw new Error("unique() returned more than one result");
-          }
-          return pairs[0] ?? null;
-        },
-        first: async () => {
-          const pairs = await collectViaPairsUntil(
-            db,
-            source.targetField,
-            runQuery(),
-            1
-          );
-          return pairs[0] ?? null;
-        },
-        many: async () => await collectViaPairs(db, source.targetField, await runQuery().collect()),
-        take: async (count) => await collectViaPairs(db, source.targetField, await runQuery().take(count)),
-        paginate: async (opts) => {
-          const result = await runQuery().paginate(opts);
-          return {
-            page: await collectViaPairs(db, source.targetField, result.page),
-            isDone: result.isDone,
-            continueCursor: result.continueCursor
-          };
-        },
-        mapOne: async (rawItem) => rawItem.doc,
-        mapMany: async (rawItems) => rawItems.map((pair) => pair.doc),
-        missingMessages: {
-          unique: `Could not find ${source.targetTable} via ${source.joinTable}.${source.index}`,
-          first: `Could not find first ${source.targetTable} via ${source.joinTable}.${source.index}`
-        },
-        normalizeUniqueError: (error) => normalizeViaUniqueError(
-          error,
-          source.targetTable,
-          source.joinTable,
-          source.index
-        )
-      };
-    }
   }
 }
 async function decorateItem(plan, rawItem, item) {
   let output = item;
-  if (plan.source.kind === "via" && plan.sourceKey) {
-    output = { ...output, [plan.sourceKey]: rawItem.link };
-  }
   if (plan.expanders.length > 0) {
-    output = await applyExpanders(output, plan.expanders);
+    output = await applyExpanders(output, plan.expanders, createWithContext());
   }
   return output;
 }
 async function decorateItems(plan, rawItems, items) {
   let output = items;
-  if (plan.source.kind === "via" && plan.sourceKey) {
-    output = output.map((item, index) => ({
-      ...item,
-      [plan.sourceKey]: rawItems[index].link
-    }));
-  }
   if (plan.expanders.length > 0) {
-    output = await applyExpandersToMany(output, plan.expanders);
+    output = await applyExpandersToMany(
+      output,
+      plan.expanders,
+      () => createWithContext()
+    );
   }
   return output;
 }
@@ -342,10 +317,201 @@ async function executePaginate(db, plan, opts) {
     continueCursor: result?.continueCursor ?? opts.cursor ?? ""
   };
 }
+function createSingleQueryBuilder(executeRoot, nullable) {
+  return {
+    ...createQueryNode(executeRoot),
+    _throughSourceKind: nullable ? "nullableSingle" : "single"
+  };
+}
+function createManyQueryBuilder(executeRoot) {
+  return {
+    ...createQueryNode(executeRoot),
+    _throughSourceKind: "many"
+  };
+}
+async function decorateThroughItem(expanders, pair) {
+  let output = pair.target;
+  if (expanders.length > 0) {
+    output = await applyExpanders(
+      output,
+      expanders,
+      createWithContext(pair.source)
+    );
+  }
+  return output;
+}
+async function decorateThroughItems(expanders, pairs) {
+  let output = pairs.map(({ target }) => target);
+  if (expanders.length > 0) {
+    output = await applyExpandersToMany(
+      output,
+      expanders,
+      (_item, index) => createWithContext(pairs[index].source)
+    );
+  }
+  return output;
+}
+async function executeThroughCollectionMany(db, plan) {
+  const sourceItems = await executeMany(db, plan.sourcePlan);
+  const pairs = await collectThroughPairs(
+    db,
+    plan.targetField,
+    sourceItems
+  );
+  return await decorateThroughItems(plan.expanders, pairs);
+}
+async function executeThroughCollectionFirst(db, plan) {
+  const pair = (await collectThroughPairsUntil(
+    db,
+    plan.targetField,
+    iterateDecoratedSourceItems(db, plan.sourcePlan),
+    1
+  ))[0];
+  if (!pair) {
+    throw new Error(`Could not find first ${plan.targetTable} through ${sourceDescription(plan.sourcePlan)}`);
+  }
+  return await decorateThroughItem(plan.expanders, pair);
+}
+async function executeThroughCollectionFirstOrNull(db, plan) {
+  const pair = (await collectThroughPairsUntil(
+    db,
+    plan.targetField,
+    iterateDecoratedSourceItems(db, plan.sourcePlan),
+    1
+  ))[0];
+  return pair ? await decorateThroughItem(plan.expanders, pair) : null;
+}
+async function executeThroughCollectionUnique(db, plan) {
+  const pairs = await collectThroughPairsUntil(
+    db,
+    plan.targetField,
+    iterateDecoratedSourceItems(db, plan.sourcePlan),
+    2
+  );
+  if (pairs.length > 1) {
+    throw new Error("unique() returned more than one result");
+  }
+  const pair = pairs[0];
+  if (!pair) {
+    throw new Error(`Could not find ${plan.targetTable} through ${sourceDescription(plan.sourcePlan)}`);
+  }
+  return await decorateThroughItem(plan.expanders, pair);
+}
+async function executeThroughCollectionUniqueOrNull(db, plan) {
+  const pairs = await collectThroughPairsUntil(
+    db,
+    plan.targetField,
+    iterateDecoratedSourceItems(db, plan.sourcePlan),
+    2
+  );
+  if (pairs.length > 1) {
+    throw new Error("unique() returned more than one result");
+  }
+  return pairs[0] ? await decorateThroughItem(plan.expanders, pairs[0]) : null;
+}
+async function executeThroughManyNode(db, plan) {
+  const sourceItems = await plan.sourceNode._executeRoot();
+  const pairs = await collectThroughPairs(
+    db,
+    plan.targetField,
+    sourceItems
+  );
+  return await decorateThroughItems(plan.expanders, pairs);
+}
+async function executeThroughSingleNode(db, plan, nullable) {
+  const sourceItem = await plan.sourceNode._executeRoot();
+  if (sourceItem == null) {
+    if (nullable) {
+      return null;
+    }
+    throw new Error(`Could not find ${plan.targetTable} through source query`);
+  }
+  const pair = await resolveThroughPair(
+    db,
+    plan.targetField,
+    sourceItem
+  );
+  if (!pair) {
+    if (nullable) {
+      return null;
+    }
+    throw new Error(`Could not find ${plan.targetTable} through source query`);
+  }
+  return await decorateThroughItem(plan.expanders, pair);
+}
+function withThroughCollectionExpander(plan, expander) {
+  return {
+    ...plan,
+    expanders: [...plan.expanders, expander]
+  };
+}
+function withThroughNodeExpander(plan, expander) {
+  return {
+    ...plan,
+    expanders: [...plan.expanders, expander]
+  };
+}
+function createThroughCollectionFacade(db, plan) {
+  return {
+    with(withBuilder) {
+      return createThroughCollectionFacade(db, withThroughCollectionExpander(plan, withBuilder));
+    },
+    unique() {
+      return createSingleQueryBuilder(
+        async () => await executeThroughCollectionUnique(db, plan),
+        false
+      );
+    },
+    uniqueOrNull() {
+      return createSingleQueryBuilder(
+        async () => await executeThroughCollectionUniqueOrNull(db, plan),
+        true
+      );
+    },
+    first() {
+      return createSingleQueryBuilder(
+        async () => await executeThroughCollectionFirst(db, plan),
+        false
+      );
+    },
+    firstOrNull() {
+      return createSingleQueryBuilder(
+        async () => await executeThroughCollectionFirstOrNull(db, plan),
+        true
+      );
+    },
+    many() {
+      return createManyQueryBuilder(
+        async () => await executeThroughCollectionMany(db, plan)
+      );
+    }
+  };
+}
+function createThroughManyQueryBuilder(db, plan) {
+  return {
+    ...createQueryNode(async () => await executeThroughManyNode(db, plan)),
+    _throughSourceKind: "many",
+    with(withBuilder) {
+      return createThroughManyQueryBuilder(
+        db,
+        withThroughNodeExpander(plan, withBuilder)
+      );
+    }
+  };
+}
+function createThroughSingleQueryBuilder(db, plan, nullable) {
+  return {
+    ...createQueryNode(async () => await executeThroughSingleNode(db, plan, nullable)),
+    _throughSourceKind: nullable ? "nullableSingle" : "single",
+    with(withBuilder) {
+      return createThroughSingleQueryBuilder(db, withThroughNodeExpander(plan, withBuilder), nullable);
+    }
+  };
+}
 function createExpandableSingleFromPlan(db, plan, nullable) {
   const execute = async () => nullable ? await executeFindOrNull(db, plan) : await executeFind(db, plan);
   return {
-    ...createQueryNode(execute),
+    ...createSingleQueryBuilder(execute, nullable),
     with(withBuilder) {
       return createExpandableSingleFromPlan(
         db,
@@ -364,12 +530,14 @@ function createBatchFacade(db, plan) {
       );
     },
     many() {
-      return createQueryNode(async () => await executeMany(db, plan));
+      return createManyQueryBuilder(async () => await executeMany(db, plan));
     }
   };
 }
 function createCollectionFacade(db, plan) {
   const facade = {
+    _plan: plan,
+    _table: plan.source.table,
     with(withBuilder) {
       return createCollectionFacade(
         db,
@@ -389,30 +557,33 @@ function createCollectionFacade(db, plan) {
       );
     },
     unique() {
-      return createQueryNode(async () => await executeUnique(db, plan));
+      return createSingleQueryBuilder(async () => await executeUnique(db, plan), false);
     },
     uniqueOrNull() {
-      return createQueryNode(async () => await executeUniqueOrNull(db, plan));
+      return createSingleQueryBuilder(
+        async () => await executeUniqueOrNull(db, plan),
+        true
+      );
     },
     first() {
-      return createQueryNode(async () => await executeFirst(db, plan));
+      return createSingleQueryBuilder(async () => await executeFirst(db, plan), false);
     },
     firstOrNull() {
-      return createQueryNode(async () => await executeFirstOrNull(db, plan));
+      return createSingleQueryBuilder(
+        async () => await executeFirstOrNull(db, plan),
+        true
+      );
     },
     take(count) {
-      return executeTake(db, plan, count);
+      return createManyQueryBuilder(async () => await executeTake(db, plan, count));
     },
     paginate(opts) {
       return executePaginate(db, plan, opts);
     },
     many() {
-      return createQueryNode(async () => await executeMany(db, plan));
+      return createManyQueryBuilder(async () => await executeMany(db, plan));
     }
   };
-  if (plan.source.kind === "via") {
-    facade.withSource = (key) => createCollectionFacade(db, withSourceKey(plan, key));
-  }
   return facade;
 }
 function createIdPlan(table, id) {
@@ -438,15 +609,23 @@ function createBatchPlan(table, index, values) {
     values
   });
 }
-function createViaPlan(targetTable, joinTable, targetField, index, selector) {
-  return createPlan({
-    kind: "via",
-    targetTable,
-    joinTable,
-    targetField,
-    index,
-    selector
-  });
+function isCollectionSource(value) {
+  return typeof value === "object" && value !== null && "_plan" in value && "_table" in value;
+}
+function isManySourceNode(value) {
+  return typeof value === "object" && value !== null && "_executeRoot" in value && value._throughSourceKind === "many";
+}
+function isSingleSourceNode(value) {
+  return typeof value === "object" && value !== null && "_executeRoot" in value && (value._throughSourceKind === "single" || value._throughSourceKind === "nullableSingle");
+}
+function normalizeIndexSelectorArgs(args) {
+  if (args.length === 0) {
+    return void 0;
+  }
+  if (args.length === 1) {
+    return args[0];
+  }
+  return args;
 }
 function createTableNamespace(db, table) {
   const rootFacade = createCollectionFacade(db, createQueryPlan(table));
@@ -461,8 +640,36 @@ function createTableNamespace(db, table) {
     in(ids) {
       return createBatchFacade(db, createBatchPlan(table, "by_id", ids));
     },
-    via(joinTable, targetField) {
-      return createViaNamespace(db, table, joinTable, targetField);
+    through(sourceQuery, targetField) {
+      if (isCollectionSource(sourceQuery)) {
+        return createThroughCollectionFacade(db, {
+          targetTable: table,
+          targetField,
+          sourcePlan: sourceQuery._plan,
+          expanders: []
+        });
+      }
+      if (isManySourceNode(sourceQuery)) {
+        return createThroughManyQueryBuilder(db, {
+          targetTable: table,
+          targetField,
+          sourceNode: sourceQuery,
+          expanders: []
+        });
+      }
+      if (isSingleSourceNode(sourceQuery)) {
+        return createThroughSingleQueryBuilder(
+          db,
+          {
+            targetTable: table,
+            targetField,
+            sourceNode: sourceQuery,
+            expanders: []
+          },
+          sourceQuery._throughSourceKind === "nullableSingle"
+        );
+      }
+      throw new Error("through() requires a query facade or lazy query node");
     }
   };
   return new Proxy(target, {
@@ -473,9 +680,13 @@ function createTableNamespace(db, table) {
       if (RESERVED_PROMISE_KEYS.has(prop) || prop === "all") {
         return void 0;
       }
-      const indexMethod = ((value) => createCollectionFacade(
+      const indexMethod = ((...args) => createCollectionFacade(
         db,
-        createQueryPlan(table, prop, value)
+        createQueryPlan(
+          table,
+          prop,
+          normalizeIndexSelectorArgs(args)
+        )
       ));
       indexMethod.in = (values) => createBatchFacade(
         db,
@@ -485,28 +696,6 @@ function createTableNamespace(db, table) {
     }
   });
 }
-function createViaNamespace(db, targetTable, joinTable, targetField) {
-  return new Proxy(
-    {},
-    {
-      get(_target, prop) {
-        if (typeof prop !== "string" || RESERVED_PROMISE_KEYS.has(prop)) {
-          return void 0;
-        }
-        return (value) => createCollectionFacade(
-          db,
-          createViaPlan(
-            targetTable,
-            joinTable,
-            targetField,
-            prop,
-            value
-          )
-        );
-      }
-    }
-  );
-}
 function createQueryFacade(db) {
   return new Proxy(
     {},
@@ -520,9 +709,6 @@ function createQueryFacade(db) {
     }
   );
 }
-function compute(load) {
-  return createQueryNode(async () => await load());
-}
 async function queryUniqueByIndex(db, table, index, value) {
   if (index === "by_id") {
     return await db.query(table).withIndex("by_id", (q) => q.eq("_id", value)).unique();
@@ -533,6 +719,5 @@ async function queryUniqueByIndex(db, table, index, value) {
   ).unique();
 }
 export {
-  compute,
   createQueryFacade
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidtkramer/convex-relations",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "Typed query facade helpers for Convex backends",
   "type": "module",
   "license": "MIT",
@@ -42,6 +42,7 @@
     "convex-test": "^0.0.41",
     "tsup": "^8.5.0",
     "typescript": "^5.9.2",
+    "typical-data": "^0.5.0",
     "vitest": "^4.0.15"
   },
   "packageManager": "pnpm@9.15.9"