@davidtkramer/convex-relations 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Kramer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,539 @@
+# `@davidtkramer/convex-relations`
+
+Typed relations and query composition for Convex backends.
+
+`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
+```
+
+## Example
+
+With `convex-relations`, a nested API-ready query can look like this:
+
+```ts
+import { query } from "./_generated/server";
+
+export const getPost = query({
+  args: {},
+  handler: async (ctx) => {
+    const post = await ctx.q.posts
+      .bySlug("hello-world")
+      .with((post) => ({
+        author: ctx.q.authors.find(post.authorId),
+        recentComments: ctx.q.comments
+          .byPostId(post._id)
+          .order("desc")
+          .with((comment) => ({
+            author: ctx.q.authors.find(comment.authorId),
+          }))
+          .take(10),
+        categories: ctx.q.categories
+          .via("postCategories", "categoryId")
+          .byPostId(post._id)
+          .many(),
+      }))
+      .unique();
+
+    // post.author is an author document
+    console.log(post.author.name);
+
+    // post.recentComments is a list of comments with nested authors
+    console.log(post.recentComments[0]?.author.name);
+
+    // post.categories is already shaped as related category documents
+    console.log(post.categories.map((category) => category.slug));
+
+    return post;
+  },
+});
+```
+
+This example shows most of the value proposition in one place:
+
+- table-scoped access through `q.posts`, `q.comments`, `q.categories`
+- typed index lookup with `.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
+
+## Equivalent Convex Code
+
+Without `convex-relations`, you end up assembling the same result shape by hand:
+
+```ts
+const post = await ctx.db
+  .query("posts")
+  .withIndex("bySlug", (q) => q.eq("slug", args.slug))
+  .unique();
+
+if (!post) {
+  throw new Error("Post not found");
+}
+
+const [author, recentComments, postCategoryLinks] = await Promise.all([
+  ctx.db.get(post.authorId),
+  ctx.db
+    .query("comments")
+    .withIndex("byPostId", (q) => q.eq("postId", post._id))
+    .order("desc")
+    .take(10),
+  ctx.db
+    .query("postCategories")
+    .withIndex("byPostId", (q) => q.eq("postId", post._id))
+    .collect(),
+]);
+
+const recentCommentsWithAuthors = await Promise.all(
+  recentComments.map(async (comment) => ({
+    ...comment,
+    author: await ctx.db.get(comment.authorId),
+  })),
+);
+
+const categories = (
+  await Promise.all(
+    postCategoryLinks.map((link) => ctx.db.get(link.categoryId)),
+  )
+).filter((category) => category !== null);
+
+return {
+  ...post,
+  author,
+  recentComments: recentCommentsWithAuthors,
+  categories,
+};
+```
+
+That works, but you are responsible for:
+
+- deciding what should run in parallel
+- 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
+
+## Quick Start
+
+Most apps expose the facade on `ctx.q` through `convex-helpers` custom function
+wrappers. A minimal setup looks like this:
+
+```ts
+// convex/lib/functions.ts
+import { customCtx, customQuery } from "convex-helpers/server/customFunctions";
+import { query as baseQuery } from "./_generated/server";
+import type { DataModel } from "./_generated/dataModel";
+import { createQueryFacade } from "@davidtkramer/convex-relations";
+
+export const query = customQuery(
+  baseQuery,
+  customCtx((ctx: { db: any }) => ({
+    q: createQueryFacade<DataModel>(ctx.db),
+  })),
+);
+```
+
+Once you do that, usage looks like this:
+
+```ts
+const post = await ctx.q.posts
+  .bySlug("hello-world")
+  .with((post) => ({
+    author: ctx.q.authors.find(post.authorId),
+    comments: ctx.q.comments.byPostId(post._id).order("desc").take(10),
+  }))
+  .unique();
+```
+
+## Core Concepts
+
+### Table namespaces
+
+Every table becomes a namespace on the returned facade:
+
+```ts
+await ctx.q.posts.many();
+await ctx.q.authors.bySlug("ada-lovelace").unique();
+await ctx.q.comments.byPostId(postId).order("desc").take(20);
+```
+
+### Indexes become methods
+
+For example, imagine these index definitions:
+
+```ts
+authors: defineTable({
+  slug: v.string(),
+  name: v.string(),
+}).index("bySlug", ["slug"]);
+
+comments: defineTable({
+  postId: v.id("posts"),
+  authorId: v.id("authors"),
+  status: v.union(v.literal("pending"), v.literal("approved")),
+  body: v.string(),
+})
+  .index("byPostId", ["postId"])
+  .index("byPostIdAndStatus", ["postId", "status"]);
+```
+
+```ts
+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" })
+  .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.
+
+## API
+
+### `createQueryFacade<DataModel>(db)`
+
+Creates a typed facade over your Convex `db`.
+
+```ts
+import { createQueryFacade } from "@davidtkramer/convex-relations";
+import type { DataModel } from "./_generated/dataModel";
+
+const q = createQueryFacade<DataModel>(ctx.db);
+```
+
+### `compute(load)`
+
+Wraps arbitrary async or sync work so it can be used inside `with(...)`.
+
+```ts
+const post = await q.posts
+  .bySlug("hello-world")
+  .with((post) => ({
+    readingTimeMinutes: compute(() =>
+      Math.ceil(post.body.split(/\s+/).length / 200),
+    ),
+  }))
+  .unique();
+```
+
+## Table Access Patterns
+
+### `find(id)` and `findOrNull(id)`
+
+Direct `_id` lookup.
+
+```ts
+const post = await q.posts.find(postId);
+const maybePost = await q.posts.findOrNull(postId);
+```
+
+`find(...)` throws if the document is missing. `findOrNull(...)` returns `null`.
+
+### Full table or index range queries
+
+Zero-argument table or index access creates a range query.
+
+```ts
+const latestPosts = await q.posts.order("desc").take(20);
+
+const authorPosts = await q.posts
+  .byAuthorId()
+  .filter((query) => query.eq(query.field("authorId"), authorId))
+  .order("desc")
+  .many();
+```
+
+### Indexed lookup by value
+
+Single-field indexes accept a scalar:
+
+```ts
+const author = await q.authors.bySlug("ada-lovelace").unique();
+```
+
+Compound indexes accept an object containing a valid prefix:
+
+```ts
+const comments = await q.comments
+  .byPostIdAndCreatedAt({ postId })
+  .order("desc")
+  .take(20);
+
+const exactOrPrefix = await q.comments
+  .byPostIdAndCreatedAt({ postId, createdAt: 1700000000000 })
+  .many();
+```
+
+### Indexed lookup by selector function
+
+You can also pass Convex's index selector callback:
+
+```ts
+const recentComments = await q.comments
+  .byPostIdAndCreatedAt((q) => q.eq("postId", postId).gt("createdAt", cutoff))
+  .many();
+```
+
+### Batch lookup with `.in(...)`
+
+Available on `_id` and indexed entrypoints.
+
+```ts
+const posts = await q.posts.in(postIds).many();
+
+const categories = await q.categories.bySlug
+  .in(["typescript", "convex"])
+  .many();
+```
+
+Batch lookups skip missing rows.
+
+## Relation Expansion with `with(...)`
+
+`with(...)` lets you attach related data or computed fields before a terminal.
+
+```ts
+const post = await q.posts
+  .bySlug("hello-world")
+  .with((post) => ({
+    author: q.authors.find(post.authorId),
+    comments: q.comments.byPostId(post._id).order("desc").take(10),
+    commentCount: compute(async () => {
+      const comments = await q.comments.byPostId(post._id).many();
+      return comments.length;
+    }),
+  }))
+  .unique();
+```
+
+You can chain `with(...)` calls:
+
+```ts
+const post = await q.posts
+  .bySlug("hello-world")
+  .with((post) => ({
+    author: q.authors.find(post.authorId),
+  }))
+  .with((post) => ({
+    otherPostsByAuthor: q.posts.byAuthorId(post.author._id).many(),
+  }))
+  .unique();
+```
+
+Each `with(...)` stage sees fields added by earlier stages.
+
+## Join Table Traversal with `via(...)`
+
+Use `via(joinTable, targetField)` for many-to-many relationships.
+
+Given `postCategories { postId, categoryId }`, you can fetch categories for a post:
+
+```ts
+const categories = await q.categories
+  .via("postCategories", "categoryId")
+  .byPostId(postId)
+  .many();
+```
+
+You can also attach the join row with `withSource(...)`:
+
+```ts
+const categories = await q.categories
+  .via("postCategories", "categoryId")
+  .byPostId(postId)
+  .withSource("link")
+  .many();
+
+categories[0]?.link.postId;
+categories[0]?.link.categoryId;
+```
+
+This is useful when the join table stores metadata like ordering, role, or timestamps.
+
+## Terminals
+
+### `unique()` / `uniqueOrNull()`
+
+Use when the query should match at most one document.
+
+```ts
+const author = await q.authors.bySlug("ada-lovelace").unique();
+const maybeAuthor = await q.authors.bySlug("missing").uniqueOrNull();
+```
+
+### `first()` / `firstOrNull()`
+
+Use when you want the first result from an ordered or filtered range query.
+
+```ts
+const latestComment = await q.comments.byPostId(postId).order("desc").first();
+const maybeLatestComment = await q.comments
+  .byPostId(postId)
+  .order("desc")
+  .firstOrNull();
+```
+
+### `many()`
+
+Collects all matching rows.
+
+```ts
+const comments = await q.comments.byPostId(postId).many();
+```
+
+### `take(count)`
+
+Collects up to `count` rows.
+
+```ts
+const comments = await q.comments.byPostId(postId).order("desc").take(20);
+```
+
+### `paginate(opts)`
+
+Returns Convex-style pagination output.
+
+```ts
+const page = await q.posts.byAuthorId(authorId).paginate({
+  cursor: null,
+  numItems: 25,
+});
+```
+
+## Error Semantics
+
+- `find(...)` throws if the document is missing
+- `unique()` throws if there is no match
+- `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
+
+### What runs in parallel
+
+Within a single `with(...)` stage, every field in the returned object runs in parallel.
+
+```ts
+const post = await q.posts.find(postId).with((post) => ({
+  author: q.authors.find(post.authorId),
+  comments: q.comments.byPostId(post._id).take(10),
+  categoryCount: compute(async () => {
+    const categories = await q.categories
+      .via("postCategories", "categoryId")
+      .byPostId(post._id)
+      .many();
+    return categories.length;
+  }),
+}));
+```
+
+Those three branches are executed concurrently.
+
+For collection queries, expansion also runs in parallel across items:
+
+- the query fetches the base rows
+- each row is expanded concurrently
+- each field inside a single expansion stage is also concurrent
+
+### What runs sequentially
+
+Chained `with(...)` stages are sequential by design.
+
+```ts
+q.posts
+  .with((post) => ({ author: q.authors.find(post.authorId) }))
+  .with((post) => ({ otherPosts: q.posts.byAuthorId(post.author._id).many() }));
+```
+
+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.
+
+### Practical guidance
+
+- Prefer one `with(...)` stage when fields are independent
+- Split into multiple `with(...)` stages only when later fields depend on earlier expansions
+- Use `take(...)` or `paginate(...)` instead of `many()` on large collections
+- Use indexed entrypoints whenever possible
+- Use `.in(...)` when you already have a set of ids or indexed values
+
+## Comparison to `convex-helpers/server/relationships`
+
+If you started from Convex relationship helpers like `getOneFrom`, `getManyFrom`, or `getManyVia`, this library aims to provide the same kind of relational navigation with better composition.
+
+This:
+
+```ts
+const categories = await q.categories
+  .via("postCategories", "categoryId")
+  .byPostId(postId)
+  .many();
+```
+
+replaces patterns like:
+
+```ts
+const categories = await getManyVia(
+  db,
+  "postCategories",
+  "categoryId",
+  "postId",
+  postId,
+);
+```
+
+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

@@ -0,0 +1,137 @@
+import { GenericDataModel, TableNamesInDataModel, DocumentByName, IndexNames, NamedTableInfo, NamedIndex, GenericDatabaseReader } from 'convex/server';
+import { GenericId } from 'convex/values';
+
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type AppTable<DataModel extends GenericDataModel> = TableNamesInDataModel<DataModel>;
+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,
+    '_creationTime'
+] ? Field : never;
+type TuplePrefixValues<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, Fields extends readonly string[], Seen extends readonly string[] = []> = 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;
+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 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 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;
+} : {})>;
+type AttachSource<ParentItem, SourceItem, SourceKey extends string> = Simplify<ParentItem & {
+    [K in SourceKey]: SourceItem;
+}>;
+type PaginationOptions = {
+    numItems: number;
+    cursor: string | null;
+};
+type PaginatedResult<Item> = {
+    page: 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> & {
+    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 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>;
+    unique(): UniqueQueryBuilder<Item>;
+    uniqueOrNull(): UniqueOrNullQueryBuilder<Item>;
+    first(): FirstQueryBuilder<Item>;
+    firstOrNull(): FirstOrNullQueryBuilder<Item>;
+    take(count: number): Promise<Item[]>;
+    paginate(opts: PaginationOptions): Promise<PaginatedResult<Item>>;
+    many(): ManyQueryBuilder<Item>;
+};
+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>;
+    unique(): UniqueQueryBuilder<Item>;
+    uniqueOrNull(): UniqueOrNullQueryBuilder<Item>;
+    first(): FirstQueryBuilder<Item>;
+    firstOrNull(): FirstOrNullQueryBuilder<Item>;
+    take(count: number): Promise<Item[]>;
+    paginate(opts: PaginationOptions): Promise<PaginatedResult<Item>>;
+    many(): ManyQueryBuilder<Item>;
+};
+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>>;
+    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>;
+    };
+};
+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>;
+} & 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>;
+        (): TableRangeQueryFacade<DataModel, Table>;
+        in<const Value extends TableIndexValueArg<DataModel, Table, IndexName>>(values: StrictTableIndexValueArg<DataModel, Table, IndexName, Value>[]): TableBatchQueryFacade<DataModel, Table>;
+    };
+};
+type QueryFacade<DataModel extends GenericDataModel> = {
+    [Table in AppTable<DataModel>]: TableNamespace<DataModel, Table>;
+};
+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 };

package/dist/index.js

@@ -0,0 +1,538 @@
+// src/index.ts
+var RESERVED_PROMISE_KEYS = /* @__PURE__ */ new Set(["then", "catch", "finally"]);
+function createQueryNode(executeRoot) {
+  return {
+    _executeRoot: executeRoot,
+    then(onfulfilled, onrejected) {
+      return executeRoot().then(onfulfilled, onrejected);
+    }
+  };
+}
+async function expandDoc(parent, withBuilder) {
+  const spec = withBuilder(parent) ?? {};
+  const entries = await Promise.all(
+    Object.entries(spec).map(
+      async ([key, query]) => [key, await query._executeRoot()]
+    )
+  );
+  return {
+    ...parent,
+    ...Object.fromEntries(entries)
+  };
+}
+async function applyExpanders(item, expanders) {
+  let current = item;
+  for (const expander of expanders) {
+    current = await expandDoc(current, expander);
+  }
+  return current;
+}
+async function applyExpandersToMany(items, expanders) {
+  return await Promise.all(items.map((item) => applyExpanders(item, expanders)));
+}
+function buildQuery(makeQuery, modifiers) {
+  return modifiers.reduce((query, modifier) => modifier(query), makeQuery());
+}
+function createPlan(source) {
+  return {
+    source,
+    modifiers: [],
+    expanders: []
+  };
+}
+function withModifier(plan, modifier) {
+  return {
+    ...plan,
+    modifiers: [...plan.modifiers, modifier]
+  };
+}
+function withExpander(plan, expander) {
+  return {
+    ...plan,
+    expanders: [...plan.expanders, expander]
+  };
+}
+function withSourceKey(plan, sourceKey) {
+  return {
+    ...plan,
+    sourceKey
+  };
+}
+function normalizeIndexValues(index, value) {
+  if (isPlainObject(value)) {
+    return value;
+  }
+  return {
+    [inferFieldNameFromIndex(index)]: value
+  };
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function applyIndexValues(query, values) {
+  let current = query;
+  for (const [field, value] of Object.entries(values)) {
+    current = current.eq(field, value);
+  }
+  return current;
+}
+function inferFieldNameFromIndex(index) {
+  if (index.startsWith("by") && index.length > 2) {
+    return `${index[2].toLowerCase()}${index.slice(3)}`;
+  }
+  throw new Error(`Cannot infer field name from index ${index}`);
+}
+function createIndexedQuery(db, table, index, selector) {
+  const baseQuery = db.query(table);
+  if (index === void 0) {
+    return baseQuery;
+  }
+  if (selector === void 0) {
+    return baseQuery.withIndex(index);
+  }
+  if (typeof selector === "function") {
+    return baseQuery.withIndex(index, selector);
+  }
+  if (index === "by_id") {
+    return baseQuery.withIndex(index, (q) => q.eq("_id", selector));
+  }
+  return baseQuery.withIndex(
+    index,
+    (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);
+  }
+  if (typeof selector === "function") {
+    return baseQuery.withIndex(index, selector);
+  }
+  return baseQuery.withIndex(
+    index,
+    (q) => applyIndexValues(q, normalizeIndexValues(index, selector))
+  );
+}
+async function collectViaPairs(db, targetField, links) {
+  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;
+    })
+  );
+  return pairs.filter((pair) => pair !== null);
+}
+async function collectViaPairsUntil(db, targetField, query, 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 });
+    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) {
+    case "id":
+      return {
+        findOrNull: async () => await db.get(source.id),
+        mapOne: async (rawItem) => rawItem,
+        mapMany: async (rawItems) => rawItems,
+        missingMessages: {
+          find: `Could not find ${source.table} with id ${source.id}`
+        }
+      };
+    case "batch":
+      return {
+        many: async () => (await Promise.all(
+          source.values.map(
+            async (value) => await queryUniqueByIndex(db, source.table, source.index, value)
+          )
+        )).filter(
+          (doc) => doc !== null
+        ),
+        mapOne: async (rawItem) => rawItem,
+        mapMany: async (rawItems) => rawItems,
+        missingMessages: {}
+      };
+    case "query": {
+      const runQuery = () => buildQuery(
+        () => createIndexedQuery(db, source.table, source.index, source.selector),
+        plan.modifiers
+      );
+      return {
+        unique: async () => await runQuery().unique(),
+        first: async () => await runQuery().first(),
+        many: async () => await runQuery().collect(),
+        take: async (count) => await runQuery().take(count),
+        paginate: async (opts) => await runQuery().paginate(opts),
+        mapOne: async (rawItem) => rawItem,
+        mapMany: async (rawItems) => rawItems,
+        missingMessages: {
+          unique: source.index ? `Could not find ${source.table} with index ${source.index}` : `Could not find ${source.table}`,
+          first: `Could not find first ${source.table}`
+        }
+      };
+    }
+    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);
+  }
+  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);
+  }
+  return output;
+}
+async function executeFind(db, plan) {
+  const runtime = createPlanRuntime(db, plan);
+  const rawItem = await runtime.findOrNull?.();
+  if (rawItem == null) {
+    throw new Error(runtime.missingMessages.find);
+  }
+  return await decorateItem(plan, rawItem, await runtime.mapOne(rawItem));
+}
+async function executeFindOrNull(db, plan) {
+  const runtime = createPlanRuntime(db, plan);
+  const rawItem = await runtime.findOrNull?.();
+  if (rawItem == null) {
+    return null;
+  }
+  return await decorateItem(plan, rawItem, await runtime.mapOne(rawItem));
+}
+async function executeUnique(db, plan) {
+  const runtime = createPlanRuntime(db, plan);
+  let rawItem;
+  try {
+    rawItem = await runtime.unique?.();
+  } catch (error) {
+    throw runtime.normalizeUniqueError ? runtime.normalizeUniqueError(error) : error;
+  }
+  if (rawItem == null) {
+    throw new Error(runtime.missingMessages.unique);
+  }
+  return await decorateItem(plan, rawItem, await runtime.mapOne(rawItem));
+}
+async function executeUniqueOrNull(db, plan) {
+  const runtime = createPlanRuntime(db, plan);
+  let rawItem;
+  try {
+    rawItem = await runtime.unique?.();
+  } catch (error) {
+    throw runtime.normalizeUniqueError ? runtime.normalizeUniqueError(error) : error;
+  }
+  if (rawItem == null) {
+    return null;
+  }
+  return await decorateItem(plan, rawItem, await runtime.mapOne(rawItem));
+}
+async function executeFirst(db, plan) {
+  const runtime = createPlanRuntime(db, plan);
+  const rawItem = await runtime.first?.();
+  if (rawItem == null) {
+    throw new Error(runtime.missingMessages.first);
+  }
+  return await decorateItem(plan, rawItem, await runtime.mapOne(rawItem));
+}
+async function executeFirstOrNull(db, plan) {
+  const runtime = createPlanRuntime(db, plan);
+  const rawItem = await runtime.first?.();
+  if (rawItem == null) {
+    return null;
+  }
+  return await decorateItem(plan, rawItem, await runtime.mapOne(rawItem));
+}
+async function executeMany(db, plan) {
+  const runtime = createPlanRuntime(db, plan);
+  const rawItems = await runtime.many?.();
+  return await decorateItems(plan, rawItems ?? [], await runtime.mapMany(rawItems ?? []));
+}
+async function executeTake(db, plan, count) {
+  const runtime = createPlanRuntime(db, plan);
+  const rawItems = await runtime.take?.(count);
+  return await decorateItems(plan, rawItems ?? [], await runtime.mapMany(rawItems ?? []));
+}
+async function executePaginate(db, plan, opts) {
+  const runtime = createPlanRuntime(db, plan);
+  const result = await runtime.paginate?.(opts);
+  const rawItems = result?.page ?? [];
+  return {
+    page: await decorateItems(plan, rawItems, await runtime.mapMany(rawItems)),
+    isDone: result?.isDone ?? true,
+    continueCursor: result?.continueCursor ?? opts.cursor ?? ""
+  };
+}
+function createExpandableSingleFromPlan(db, plan, nullable) {
+  const execute = async () => nullable ? await executeFindOrNull(db, plan) : await executeFind(db, plan);
+  return {
+    ...createQueryNode(execute),
+    with(withBuilder) {
+      return createExpandableSingleFromPlan(
+        db,
+        withExpander(plan, withBuilder),
+        nullable
+      );
+    }
+  };
+}
+function createBatchFacade(db, plan) {
+  return {
+    with(withBuilder) {
+      return createBatchFacade(
+        db,
+        withExpander(plan, withBuilder)
+      );
+    },
+    many() {
+      return createQueryNode(async () => await executeMany(db, plan));
+    }
+  };
+}
+function createCollectionFacade(db, plan) {
+  const facade = {
+    with(withBuilder) {
+      return createCollectionFacade(
+        db,
+        withExpander(plan, withBuilder)
+      );
+    },
+    order(direction) {
+      return createCollectionFacade(
+        db,
+        withModifier(plan, (query) => query.order(direction))
+      );
+    },
+    filter(filterer) {
+      return createCollectionFacade(
+        db,
+        withModifier(plan, (query) => query.filter(filterer))
+      );
+    },
+    unique() {
+      return createQueryNode(async () => await executeUnique(db, plan));
+    },
+    uniqueOrNull() {
+      return createQueryNode(async () => await executeUniqueOrNull(db, plan));
+    },
+    first() {
+      return createQueryNode(async () => await executeFirst(db, plan));
+    },
+    firstOrNull() {
+      return createQueryNode(async () => await executeFirstOrNull(db, plan));
+    },
+    take(count) {
+      return executeTake(db, plan, count);
+    },
+    paginate(opts) {
+      return executePaginate(db, plan, opts);
+    },
+    many() {
+      return createQueryNode(async () => await executeMany(db, plan));
+    }
+  };
+  if (plan.source.kind === "via") {
+    facade.withSource = (key) => createCollectionFacade(db, withSourceKey(plan, key));
+  }
+  return facade;
+}
+function createIdPlan(table, id) {
+  return createPlan({
+    kind: "id",
+    table,
+    id
+  });
+}
+function createQueryPlan(table, index, selector) {
+  return createPlan({
+    kind: "query",
+    table,
+    index,
+    selector
+  });
+}
+function createBatchPlan(table, index, values) {
+  return createPlan({
+    kind: "batch",
+    table,
+    index,
+    values
+  });
+}
+function createViaPlan(targetTable, joinTable, targetField, index, selector) {
+  return createPlan({
+    kind: "via",
+    targetTable,
+    joinTable,
+    targetField,
+    index,
+    selector
+  });
+}
+function createTableNamespace(db, table) {
+  const rootFacade = createCollectionFacade(db, createQueryPlan(table));
+  const target = {
+    ...rootFacade,
+    find(id) {
+      return createExpandableSingleFromPlan(db, createIdPlan(table, id), false);
+    },
+    findOrNull(id) {
+      return createExpandableSingleFromPlan(db, createIdPlan(table, id), true);
+    },
+    in(ids) {
+      return createBatchFacade(db, createBatchPlan(table, "by_id", ids));
+    },
+    via(joinTable, targetField) {
+      return createViaNamespace(db, table, joinTable, targetField);
+    }
+  };
+  return new Proxy(target, {
+    get(currentTarget, prop, receiver) {
+      if (typeof prop !== "string" || prop in currentTarget) {
+        return Reflect.get(currentTarget, prop, receiver);
+      }
+      if (RESERVED_PROMISE_KEYS.has(prop) || prop === "all") {
+        return void 0;
+      }
+      const indexMethod = ((value) => createCollectionFacade(
+        db,
+        createQueryPlan(table, prop, value)
+      ));
+      indexMethod.in = (values) => createBatchFacade(
+        db,
+        createBatchPlan(table, prop, values)
+      );
+      return indexMethod;
+    }
+  });
+}
+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(
+    {},
+    {
+      get(_target, prop) {
+        if (typeof prop !== "string" || RESERVED_PROMISE_KEYS.has(prop)) {
+          return void 0;
+        }
+        return createTableNamespace(db, prop);
+      }
+    }
+  );
+}
+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();
+  }
+  return await db.query(table).withIndex(
+    index,
+    (q) => applyIndexValues(q, normalizeIndexValues(index, value))
+  ).unique();
+}
+export {
+  compute,
+  createQueryFacade
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@davidtkramer/convex-relations",
+  "version": "0.1.0",
+  "description": "Typed query facade helpers for Convex backends",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidtkramer/convex-relations.git"
+  },
+  "homepage": "https://github.com/davidtkramer/convex-relations",
+  "bugs": {
+    "url": "https://github.com/davidtkramer/convex-relations/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --typecheck"
+  },
+  "peerDependencies": {
+    "convex": "^1.25.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "convex": "1.25.4",
+    "convex-test": "^0.0.41",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.15"
+  },
+  "packageManager": "pnpm@9.15.9"
+}