@davidtkramer/convex-relations 0.2.0 → 0.4.1

package/README.md

@@ -126,8 +126,6 @@ That works, but you are responsible for:
 - [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
 
@@ -157,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),
   })),
 );
 ```
@@ -223,18 +222,26 @@ 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 and returns an object whose values are
-other query nodes or `compute(...)` calls.
+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) => ({
+  .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();
 ```
@@ -259,26 +266,30 @@ 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),
     ),
   }))
@@ -364,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;
     }),
@@ -407,12 +418,12 @@ const categories = await q.categories
 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 with `withSource(...)`:
+You can also attach the source row through the normal `with(...)` callback:
 
 ```ts
 const categories = await q.categories
   .through(q.postCategories.byPostId(postId).order("desc"), "categoryId")
-  .withSource("link")
+  .with((category, { source }) => ({ link: source }))
   .many();
 
 categories[0]?.link.postId;
@@ -427,7 +438,7 @@ timestamps.
 ```ts
 const author = await q.authors
   .through(q.posts.bySlug("hello-world"), "authorId")
-  .withSource("post")
+  .with((author, { source }) => ({ post: source }))
   .unique();
 
 author.post.slug;
@@ -445,12 +456,12 @@ const tags = await q.tags
       .take(10),
     "tagId",
   )
-  .withSource("link")
+  .with((tag, { source }) => ({ link: source }))
   .many();
 ```
 
 After `through(...)`, you can keep shaping the target result with `with(...)`
-and `withSource(...)`, then choose a terminal like `many()` or `first()`.
+and then choose a terminal like `many()` or `first()`.
 
 ## Terminals
 
@@ -517,10 +528,10 @@ 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
       .through(q.postCategories.byPostId(post._id), "categoryId")
       .many();
@@ -586,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 use leading positional arguments
-
-## License
-
-MIT

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { GenericDataModel, TableNamesInDataModel, DocumentByName, GenericTableInfo, FilterBuilder, ExpressionOrValue, NamedTableInfo, IndexNames, IndexRangeBuilder, NamedIndex, IndexRange, GenericDatabaseReader } from 'convex/server';
+import { GenericDataModel, TableNamesInDataModel, DocumentByName, GenericTableInfo, FilterBuilder, ExpressionOrValue, NamedTableInfo, IndexNames, IndexRangeBuilder, NamedIndex, IndexRange, GenericDatabaseReader, SchemaDefinition } from 'convex/server';
 import { GenericId } from 'convex/values';
 
 type Simplify<T> = {
@@ -43,16 +43,20 @@ type QueryPlanHandle<DataModel extends GenericDataModel, Table extends AppTable<
     readonly _plan: QueryPlan;
     readonly _table: Table;
 };
-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 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;
@@ -89,12 +93,10 @@ type ThroughSourceField<DataModel extends GenericDataModel, TargetTable extends
     [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>>(withBuilder: Builder): ManyThroughQueryBuilder<ExpandWith<Item, Builder>, SourceItem>;
-    withSource<const SourceKey extends string>(key: SourceKey): ManyThroughQueryBuilder<AttachSource<Item, SourceItem, SourceKey>, SourceItem>;
+    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>>(withBuilder: Builder): SingleThroughQueryBuilder<ExpandWith<Item, Builder>, SourceItem, Nullable>;
-    withSource<const SourceKey extends string>(key: SourceKey): SingleThroughQueryBuilder<AttachSource<Item, SourceItem, SourceKey>, SourceItem, Nullable>;
+    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>>;
@@ -125,8 +127,7 @@ type TableBatchQueryFacade<DataModel extends GenericDataModel, Table extends App
     many(): BatchQueryBuilder<Item>;
 };
 type ThroughQueryFacade<DataModel extends GenericDataModel, TargetTable extends AppTable<DataModel>, SourceItem, Item = AppDoc<DataModel, TargetTable>> = {
-    with<Builder extends AnyWithBuilder<Item>>(withBuilder: Builder): ThroughQueryFacade<DataModel, TargetTable, SourceItem, ExpandWith<Item, Builder>>;
-    withSource<const SourceKey extends string>(key: SourceKey): ThroughQueryFacade<DataModel, TargetTable, SourceItem, AttachSource<Item, SourceItem, SourceKey>>;
+    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>;
@@ -164,18 +165,19 @@ type QuerySourcePlan = {
     table: string;
     index?: string;
     selector?: unknown;
+    indexFields?: readonly string[];
 } | {
     kind: 'batch';
     table: string;
     index: string;
     values: unknown[];
+    indexFields?: readonly string[];
 };
 type QueryPlan = {
     source: QuerySourcePlan;
     modifiers: QueryModifier[];
-    expanders: AnyWithBuilder<any>[];
+    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>;
+declare function createQueryFacade<DataModel extends GenericDataModel>(db: GenericDatabaseReader<DataModel>, schema: SchemaDefinition<any, boolean>): QueryFacade<DataModel>;
 
-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,16 +67,15 @@ function withExpander(plan, expander) {
     expanders: [...plan.expanders, expander]
   };
 }
-function normalizeIndexValues(index, value) {
+function normalizeIndexValues(index, value, indexFields) {
   if (Array.isArray(value)) {
-    const fieldNames = inferFieldNamesFromIndex(index);
-    return Object.fromEntries(fieldNames.map((field, index2) => [field, value[index2]]));
+    return Object.fromEntries(indexFields.map((field, index2) => [field, value[index2]]));
   }
   if (isPlainObject(value)) {
     return value;
   }
   return {
-    [inferFieldNameFromIndex(index)]: value
+    [index === "by_id" ? "_id" : indexFields[0]]: value
   };
 }
 function isPlainObject(value) {
@@ -74,19 +88,16 @@ function applyIndexValues(query, values) {
   }
   return current;
 }
-function inferFieldNameFromIndex(index) {
-  return inferFieldNamesFromIndex(index)[0];
-}
-function inferFieldNamesFromIndex(index) {
+function requireIndexFields(index, indexFields) {
   if (index === "by_id") {
     return ["_id"];
   }
-  if (index.startsWith("by") && index.length > 2) {
-    return index.slice(2).split("And").map((part) => `${part[0].toLowerCase()}${part.slice(1)}`);
+  if (indexFields === void 0) {
+    throw new Error(`Missing schema metadata for index ${index}`);
   }
-  throw new Error(`Cannot infer field name from index ${index}`);
+  return indexFields;
 }
-function createIndexedQuery(db, table, index, selector) {
+function createIndexedQuery(db, table, index, selector, indexFields = []) {
   const baseQuery = db.query(table);
   if (index === void 0) {
     return baseQuery;
@@ -100,9 +111,10 @@ function createIndexedQuery(db, table, index, selector) {
   if (index === "by_id") {
     return baseQuery.withIndex(index, (q) => q.eq("_id", selector));
   }
+  const fields = requireIndexFields(index, indexFields);
   return baseQuery.withIndex(
     index,
-    (q) => applyIndexValues(q, normalizeIndexValues(index, selector))
+    (q) => applyIndexValues(q, normalizeIndexValues(index, selector, fields))
   );
 }
 function sourceDescription(plan) {
@@ -139,7 +151,13 @@ async function* iterateDecoratedSourceItems(db, plan) {
   const runtime = createPlanRuntime(db, plan);
   const source = plan.source;
   const query = buildQuery(
-    () => createIndexedQuery(db, source.table, source.index, source.selector),
+    () => createIndexedQuery(
+      db,
+      source.table,
+      source.index,
+      source.selector,
+      source.indexFields
+    ),
     plan.modifiers
   );
   for await (const rawItem of query) {
@@ -176,18 +194,28 @@ function createPlanRuntime(db, plan) {
       return {
         many: async () => (await Promise.all(
           source.values.map(
-            async (value) => await queryUniqueByIndex(db, source.table, source.index, value)
+            async (value) => await queryManyByIndex(
+              db,
+              source.table,
+              source.index,
+              value,
+              source.indexFields
+            )
           )
-        )).filter(
-          (doc) => doc !== null
-        ),
+        )).flat(),
         mapOne: async (rawItem) => rawItem,
         mapMany: async (rawItems) => rawItems,
         missingMessages: {}
       };
     case "query": {
       const runQuery = () => buildQuery(
-        () => createIndexedQuery(db, source.table, source.index, source.selector),
+        () => createIndexedQuery(
+          db,
+          source.table,
+          source.index,
+          source.selector,
+          source.indexFields
+        ),
         plan.modifiers
       );
       return {
@@ -209,14 +237,18 @@ function createPlanRuntime(db, plan) {
 async function decorateItem(plan, rawItem, item) {
   let output = item;
   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.expanders.length > 0) {
-    output = await applyExpandersToMany(output, plan.expanders);
+    output = await applyExpandersToMany(
+      output,
+      plan.expanders,
+      () => createWithContext()
+    );
   }
   return output;
 }
@@ -310,22 +342,25 @@ function createManyQueryBuilder(executeRoot) {
     _throughSourceKind: "many"
   };
 }
-async function decorateThroughItem(expanders, sourceKey, pair) {
+async function decorateThroughItem(expanders, pair) {
   let output = pair.target;
-  if (sourceKey) {
-    output = { ...output, [sourceKey]: pair.source };
-  }
   if (expanders.length > 0) {
-    output = await applyExpanders(output, expanders);
+    output = await applyExpanders(
+      output,
+      expanders,
+      createWithContext(pair.source)
+    );
   }
   return output;
 }
-async function decorateThroughItems(expanders, sourceKey, pairs) {
-  let output = pairs.map(
-    ({ source, target }) => sourceKey ? { ...target, [sourceKey]: source } : target
-  );
+async function decorateThroughItems(expanders, pairs) {
+  let output = pairs.map(({ target }) => target);
   if (expanders.length > 0) {
-    output = await applyExpandersToMany(output, expanders);
+    output = await applyExpandersToMany(
+      output,
+      expanders,
+      (_item, index) => createWithContext(pairs[index].source)
+    );
   }
   return output;
 }
@@ -336,7 +371,7 @@ async function executeThroughCollectionMany(db, plan) {
     plan.targetField,
     sourceItems
   );
-  return await decorateThroughItems(plan.expanders, plan.sourceKey, pairs);
+  return await decorateThroughItems(plan.expanders, pairs);
 }
 async function executeThroughCollectionFirst(db, plan) {
   const pair = (await collectThroughPairsUntil(
@@ -348,7 +383,7 @@ async function executeThroughCollectionFirst(db, plan) {
   if (!pair) {
     throw new Error(`Could not find first ${plan.targetTable} through ${sourceDescription(plan.sourcePlan)}`);
   }
-  return await decorateThroughItem(plan.expanders, plan.sourceKey, pair);
+  return await decorateThroughItem(plan.expanders, pair);
 }
 async function executeThroughCollectionFirstOrNull(db, plan) {
   const pair = (await collectThroughPairsUntil(
@@ -357,7 +392,7 @@ async function executeThroughCollectionFirstOrNull(db, plan) {
     iterateDecoratedSourceItems(db, plan.sourcePlan),
     1
   ))[0];
-  return pair ? await decorateThroughItem(plan.expanders, plan.sourceKey, pair) : null;
+  return pair ? await decorateThroughItem(plan.expanders, pair) : null;
 }
 async function executeThroughCollectionUnique(db, plan) {
   const pairs = await collectThroughPairsUntil(
@@ -373,7 +408,7 @@ async function executeThroughCollectionUnique(db, plan) {
   if (!pair) {
     throw new Error(`Could not find ${plan.targetTable} through ${sourceDescription(plan.sourcePlan)}`);
   }
-  return await decorateThroughItem(plan.expanders, plan.sourceKey, pair);
+  return await decorateThroughItem(plan.expanders, pair);
 }
 async function executeThroughCollectionUniqueOrNull(db, plan) {
   const pairs = await collectThroughPairsUntil(
@@ -385,7 +420,7 @@ async function executeThroughCollectionUniqueOrNull(db, plan) {
   if (pairs.length > 1) {
     throw new Error("unique() returned more than one result");
   }
-  return pairs[0] ? await decorateThroughItem(plan.expanders, plan.sourceKey, pairs[0]) : null;
+  return pairs[0] ? await decorateThroughItem(plan.expanders, pairs[0]) : null;
 }
 async function executeThroughManyNode(db, plan) {
   const sourceItems = await plan.sourceNode._executeRoot();
@@ -394,7 +429,7 @@ async function executeThroughManyNode(db, plan) {
     plan.targetField,
     sourceItems
   );
-  return await decorateThroughItems(plan.expanders, plan.sourceKey, pairs);
+  return await decorateThroughItems(plan.expanders, pairs);
 }
 async function executeThroughSingleNode(db, plan, nullable) {
   const sourceItem = await plan.sourceNode._executeRoot();
@@ -415,7 +450,7 @@ async function executeThroughSingleNode(db, plan, nullable) {
     }
     throw new Error(`Could not find ${plan.targetTable} through source query`);
   }
-  return await decorateThroughItem(plan.expanders, plan.sourceKey, pair);
+  return await decorateThroughItem(plan.expanders, pair);
 }
 function withThroughCollectionExpander(plan, expander) {
   return {
@@ -423,32 +458,17 @@ function withThroughCollectionExpander(plan, expander) {
     expanders: [...plan.expanders, expander]
   };
 }
-function withThroughCollectionSourceKey(plan, sourceKey) {
-  return {
-    ...plan,
-    sourceKey
-  };
-}
 function withThroughNodeExpander(plan, expander) {
   return {
     ...plan,
     expanders: [...plan.expanders, expander]
   };
 }
-function withThroughNodeSourceKey(plan, sourceKey) {
-  return {
-    ...plan,
-    sourceKey
-  };
-}
 function createThroughCollectionFacade(db, plan) {
   return {
     with(withBuilder) {
       return createThroughCollectionFacade(db, withThroughCollectionExpander(plan, withBuilder));
     },
-    withSource(key) {
-      return createThroughCollectionFacade(db, withThroughCollectionSourceKey(plan, key));
-    },
     unique() {
       return createSingleQueryBuilder(
         async () => await executeThroughCollectionUnique(db, plan),
@@ -489,9 +509,6 @@ function createThroughManyQueryBuilder(db, plan) {
         db,
         withThroughNodeExpander(plan, withBuilder)
       );
-    },
-    withSource(key) {
-      return createThroughManyQueryBuilder(db, withThroughNodeSourceKey(plan, key));
     }
   };
 }
@@ -501,9 +518,6 @@ function createThroughSingleQueryBuilder(db, plan, nullable) {
     _throughSourceKind: nullable ? "nullableSingle" : "single",
     with(withBuilder) {
       return createThroughSingleQueryBuilder(db, withThroughNodeExpander(plan, withBuilder), nullable);
-    },
-    withSource(key) {
-      return createThroughSingleQueryBuilder(db, withThroughNodeSourceKey(plan, key), nullable);
     }
   };
 }
@@ -592,20 +606,22 @@ function createIdPlan(table, id) {
     id
   });
 }
-function createQueryPlan(table, index, selector) {
+function createQueryPlan(table, index, selector, indexFields) {
   return createPlan({
     kind: "query",
     table,
     index,
-    selector
+    selector,
+    indexFields
   });
 }
-function createBatchPlan(table, index, values) {
+function createBatchPlan(table, index, values, indexFields) {
   return createPlan({
     kind: "batch",
     table,
     index,
-    values
+    values,
+    indexFields
   });
 }
 function isCollectionSource(value) {
@@ -626,7 +642,7 @@ function normalizeIndexSelectorArgs(args) {
   }
   return args;
 }
-function createTableNamespace(db, table) {
+function createTableNamespace(db, table, resolveIndexFields) {
   const rootFacade = createCollectionFacade(db, createQueryPlan(table));
   const target = {
     ...rootFacade,
@@ -684,18 +700,49 @@ function createTableNamespace(db, table) {
         createQueryPlan(
           table,
           prop,
-          normalizeIndexSelectorArgs(args)
+          normalizeIndexSelectorArgs(args),
+          resolveIndexFields(table, prop)
         )
       ));
       indexMethod.in = (values) => createBatchFacade(
         db,
-        createBatchPlan(table, prop, values)
+        createBatchPlan(
+          table,
+          prop,
+          values,
+          resolveIndexFields(table, prop)
+        )
       );
       return indexMethod;
     }
   });
 }
-function createQueryFacade(db) {
+function createIndexFieldResolver(schema) {
+  const cache = /* @__PURE__ */ new Map();
+  return (table, index) => {
+    if (index === "by_id") {
+      return ["_id"];
+    }
+    const cacheKey = `${table}:${index}`;
+    const cached = cache.get(cacheKey);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const tableDefinition = schema.tables[table];
+    const indexes = tableDefinition?.[" indexes"]();
+    const match = indexes?.find(
+      (candidate) => candidate.indexDescriptor === index
+    );
+    if (match !== void 0 && Array.isArray(match.fields)) {
+      const fields = [...match.fields];
+      cache.set(cacheKey, fields);
+      return fields;
+    }
+    throw new Error(`Missing schema metadata for index ${table}.${index}`);
+  };
+}
+function createQueryFacade(db, schema) {
+  const resolveIndexFields = createIndexFieldResolver(schema);
   return new Proxy(
     {},
     {
@@ -703,24 +750,26 @@ function createQueryFacade(db) {
         if (typeof prop !== "string" || RESERVED_PROMISE_KEYS.has(prop)) {
           return void 0;
         }
-        return createTableNamespace(db, prop);
+        return createTableNamespace(
+          db,
+          prop,
+          resolveIndexFields
+        );
       }
     }
   );
 }
-function compute(load) {
-  return createQueryNode(async () => await load());
-}
-async function queryUniqueByIndex(db, table, index, value) {
+async function queryManyByIndex(db, table, index, value, indexFields) {
   if (index === "by_id") {
-    return await db.query(table).withIndex("by_id", (q) => q.eq("_id", value)).unique();
+    const doc = await db.query(table).withIndex("by_id", (q) => q.eq("_id", value)).unique();
+    return doc ? [doc] : [];
   }
+  const fields = requireIndexFields(index, indexFields);
   return await db.query(table).withIndex(
     index,
-    (q) => applyIndexValues(q, normalizeIndexValues(index, value))
-  ).unique();
+    (q) => applyIndexValues(q, normalizeIndexValues(index, value, fields))
+  ).collect();
 }
 export {
-  compute,
   createQueryFacade
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidtkramer/convex-relations",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "description": "Typed query facade helpers for Convex backends",
   "type": "module",
   "license": "MIT",