@davidtkramer/convex-relations 0.4.3 → 0.6.0

package/README.md

@@ -123,6 +123,7 @@ That works, but you are responsible for:
 - [Relation Expansion with `with(...)`](#relation-expansion-with-with)
 - [Reference Traversal with `through(...)`](#reference-traversal-with-through)
 - [Terminals](#terminals)
+- [In-Memory Shaping](#in-memory-shaping)
 - [Error Semantics](#error-semantics)
 - [Performance Characteristics](#performance-characteristics)
 - [Comparison to `convex-helpers/server/relationships`](#comparison-to-convex-helpersserverrelationships)
@@ -344,6 +345,42 @@ const exactOrPrefix = await q.comments
   .many();
 ```
 
+### Union tables narrow by index
+
+When a table's document is a `v.union(...)`, a positional lookup narrows the
+result to the variants an index equality can actually return. A variant is
+kept when its field can hold the value, or when it lacks the field and the
+value may be `undefined` (Convex indexes a missing field as `undefined`).
+
+```ts
+const activities = defineTable(
+  v.union(
+    v.object({ postId: v.id("posts"), kind: v.literal("view") }),
+    v.object({ postId: v.id("posts"), kind: v.literal("share"), channel: v.string() }),
+    v.object({
+      postId: v.id("posts"),
+      kind: v.union(v.literal("flag"), v.literal("report")),
+      status: v.union(v.literal("pending"), v.literal("resolved")),
+    }),
+  ),
+)
+  .index("byKind", ["kind"])
+  .index("byPostIdAndStatus", ["postId", "status"]);
+
+// { kind: "share"; channel: string; ... }[]
+const shares = await q.activities.byKind("share").many();
+
+// Only the moderation variant carries `status`, so this narrows too.
+const pending = await q.activities.byPostIdAndStatus(postId, "pending").many();
+
+// `.in(...)` narrows on the union of its values.
+const taps = await q.activities.byKind.in(["view", "share"]).many();
+```
+
+A prefix that stops before the discriminating field, the selector-function
+form, and `.filter(...)` all return the full union. Tables that are not unions
+are unaffected.
+
 ### Indexed lookup by selector function
 
 You can also pass Convex's index selector callback:
@@ -513,6 +550,43 @@ const page = await q.posts.byAuthorId(authorId).paginate({
 });
 ```
 
+## In-Memory Shaping
+
+`many()` and `take(count)` return lazy nodes. Chain `filter(...)` or `sort(...)`
+on them to shape the loaded rows in memory before the node resolves. Both run
+after `with(...)` expansions, so they can read expanded relations, which the
+database-side `filter(...)` on a range query cannot.
+
+```ts
+const comments = await q.comments
+  .byPostId(postId)
+  .with((comment) => ({ author: q.authors.findOrNull(comment.authorId) }))
+  .many()
+  .filter((comment): comment is typeof comment & { author: Author } =>
+    comment.author !== null,
+  )
+  .sort((a, b) => b.author.reputation - a.author.reputation);
+```
+
+A type-predicate `filter(...)` narrows the result type. `sort(...)` requires a
+comparator and never mutates the loaded array.
+
+The shaped node is still a lazy node: it works as a `with(...)` value and as a
+`through(...)` source.
+
+```ts
+const post = await q.posts.find(postId).with((post) => ({
+  approvedComments: q.comments
+    .byPostId(post._id)
+    .many()
+    .filter((comment) => comment.status === "approved"),
+}));
+```
+
+Prefer the database-side `filter(...)` and `order(...)` on the range query when
+the condition only involves the row's own fields; in-memory shaping still loads
+and expands every row before discarding it.
+
 ## Error Semantics
 
 - `find(...)` throws if the document is missing

package/dist/index.d.ts

@@ -16,21 +16,29 @@ type UserIndexFields<DataModel extends GenericDataModel, Table extends AppTable<
 type SingleIndexField<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = UserIndexFields<DataModel, Table, IndexName> extends readonly [
     infer Field extends string
 ] ? Field : never;
+type DocFieldType<Doc, Field extends string> = Doc extends unknown ? Field extends keyof Doc ? Doc[Field] : never : never;
+type Overlaps<A, B> = [Extract<A, B> | Extract<B, A>] extends [never] ? false : true;
+type VariantsMatching<Doc, Field extends string, Value> = Doc extends unknown ? Field extends keyof Doc ? Overlaps<Doc[Field], Value> extends true ? Doc : never : undefined extends Value ? Doc : never : never;
+type NarrowByIndexArgs<Doc, Fields extends readonly string[], Args extends readonly unknown[]> = Args extends readonly [infer Value, ...infer RestArgs] ? Fields extends readonly [
+    infer Field extends string,
+    ...infer RestFields extends readonly string[]
+] ? NarrowByIndexArgs<VariantsMatching<Doc, Field, Value>, RestFields, RestArgs> : Doc : Doc;
+type NarrowedIndexItem<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends TableIndexName<DataModel, Table>, Args extends readonly unknown[]> = IndexName extends UserIndex<DataModel, Table> ? NarrowByIndexArgs<AppDoc<DataModel, Table>, UserIndexFields<DataModel, Table, IndexName>, Args> : AppDoc<DataModel, Table>;
 type TuplePrefixArgs<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, Fields extends readonly string[], Seen extends readonly string[] = [], SeenValues extends readonly unknown[] = []> = Fields extends readonly [
     infer Head extends string,
     ...infer Tail extends readonly string[]
-] ? [...SeenValues, AppDoc<DataModel, Table>[Head]] | TuplePrefixArgs<DataModel, Table, Tail, [
+] ? [...SeenValues, DocFieldType<AppDoc<DataModel, Table>, Head>] | TuplePrefixArgs<DataModel, Table, Tail, [
     ...Seen,
     Head
 ], [
     ...SeenValues,
-    AppDoc<DataModel, Table>[Head]
+    DocFieldType<AppDoc<DataModel, Table>, Head>
 ]> : never;
 type PositionalIndexArgs<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = TuplePrefixArgs<DataModel, Table, UserIndexFields<DataModel, Table, IndexName>>;
-type RootIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = PositionalIndexArgs<DataModel, Table, IndexName> | (SingleIndexField<DataModel, Table, IndexName> extends never ? never : AppDoc<DataModel, Table>[SingleIndexField<DataModel, Table, IndexName>]);
+type RootIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = PositionalIndexArgs<DataModel, Table, IndexName> | (SingleIndexField<DataModel, Table, IndexName> extends never ? never : DocFieldType<AppDoc<DataModel, Table>, SingleIndexField<DataModel, Table, IndexName>>);
 type StrictRootIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>, Value extends RootIndexValueArg<DataModel, Table, IndexName>> = Value;
 type TableIndexName<DataModel extends GenericDataModel, Table extends AppTable<DataModel>> = UserIndex<DataModel, Table> | 'by_id';
-type UserIndexArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = SingleIndexField<DataModel, Table, IndexName> extends never ? PositionalIndexArgs<DataModel, Table, IndexName> : AppDoc<DataModel, Table>[SingleIndexField<DataModel, Table, IndexName>];
+type UserIndexArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends UserIndex<DataModel, Table>> = SingleIndexField<DataModel, Table, IndexName> extends never ? PositionalIndexArgs<DataModel, Table, IndexName> : DocFieldType<AppDoc<DataModel, Table>, SingleIndexField<DataModel, Table, IndexName>>;
 type TableIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends TableIndexName<DataModel, Table>> = IndexName extends 'by_id' ? GenericId<Table> : IndexName extends UserIndex<DataModel, Table> ? UserIndexArg<DataModel, Table, IndexName> : never;
 type StrictTableIndexValueArg<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends TableIndexName<DataModel, Table>, Value extends TableIndexValueArg<DataModel, Table, IndexName>> = Value;
 type TableIndexInvocationArgs<DataModel extends GenericDataModel, Table extends AppTable<DataModel>, IndexName extends TableIndexName<DataModel, Table>> = IndexName extends 'by_id' ? [GenericId<Table>] : IndexName extends UserIndex<DataModel, Table> ? PositionalIndexArgs<DataModel, Table, IndexName> : never;
@@ -80,7 +88,11 @@ 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[]> & ThroughNodeHandle<Item, 'many'>;
+type ManyQueryBuilder<Item> = QueryNode<Item[]> & ThroughNodeHandle<Item, 'many'> & {
+    filter<Narrowed extends Item>(predicate: (item: Item, index: number) => item is Narrowed): ManyQueryBuilder<Narrowed>;
+    filter(predicate: (item: Item, index: number) => unknown): ManyQueryBuilder<Item>;
+    sort(compare: (a: Item, b: Item) => number): ManyQueryBuilder<Item>;
+};
 type BatchQueryBuilder<Item> = ManyQueryBuilder<Item>;
 type ThroughSourceNodeKind = 'many' | 'single' | 'nullableSingle';
 type ThroughNodeHandle<SourceItem, Kind extends ThroughSourceNodeKind> = {
@@ -150,9 +162,9 @@ type TableNamespace<DataModel extends GenericDataModel, Table extends AppTable<D
 } & TableRangeQueryFacade<DataModel, Table> & {
     [IndexName in TableIndexName<DataModel, Table>]: {
         (selector: IndexName extends UserIndex<DataModel, Table> ? IndexSelector<DataModel, Table, IndexName> : never): TableQueryFacade<DataModel, Table>;
-        <const Args extends TableIndexInvocationArgs<DataModel, Table, IndexName>>(...args: Args): TableQueryFacade<DataModel, Table>;
+        <const Args extends TableIndexInvocationArgs<DataModel, Table, IndexName>>(...args: Args): TableQueryFacade<DataModel, Table, NarrowedIndexItem<DataModel, Table, IndexName, Args>>;
         (): TableRangeQueryFacade<DataModel, Table>;
-        in<const Value extends TableIndexValueArg<DataModel, Table, IndexName>>(values: StrictTableIndexValueArg<DataModel, Table, IndexName, Value>[]): TableBatchQueryFacade<DataModel, Table>;
+        in<const Value extends TableIndexValueArg<DataModel, Table, IndexName>>(values: StrictTableIndexValueArg<DataModel, Table, IndexName, Value>[]): TableBatchQueryFacade<DataModel, Table, NarrowedIndexItem<DataModel, Table, IndexName, Value extends readonly unknown[] ? Value : [Value]>>;
     };
 };
 type QueryFacade<DataModel extends GenericDataModel> = {

package/dist/index.js

@@ -341,7 +341,15 @@ function createSingleQueryBuilder(executeRoot, nullable) {
 function createManyQueryBuilder(executeRoot) {
   return {
     ...createQueryNode(executeRoot),
-    _throughSourceKind: "many"
+    _throughSourceKind: "many",
+    filter(predicate) {
+      return createManyQueryBuilder(
+        async () => (await executeRoot()).filter((item, index) => predicate(item, index))
+      );
+    },
+    sort(compare) {
+      return createManyQueryBuilder(async () => [...await executeRoot()].sort(compare));
+    }
   };
 }
 async function decorateThroughItem(expanders, pair) {

package/package.json

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