@davidtkramer/convex-relations 0.2.0 → 0.4.0

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

@@ -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>;
@@ -173,9 +174,8 @@ type QuerySourcePlan = {
 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>;
 
-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,
@@ -209,14 +224,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 +329,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 +358,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 +370,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 +379,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 +395,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 +407,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 +416,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 +437,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 +445,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 +496,6 @@ function createThroughManyQueryBuilder(db, plan) {
         db,
         withThroughNodeExpander(plan, withBuilder)
       );
-    },
-    withSource(key) {
-      return createThroughManyQueryBuilder(db, withThroughNodeSourceKey(plan, key));
     }
   };
 }
@@ -501,9 +505,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);
     }
   };
 }
@@ -708,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();
@@ -721,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.2.0",
+  "version": "0.4.0",
   "description": "Typed query facade helpers for Convex backends",
   "type": "module",
   "license": "MIT",