@davidtkramer/convex-relations 0.4.2 → 0.5.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)
@@ -513,6 +514,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

@@ -80,7 +80,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> = {

package/dist/index.js

@@ -69,7 +69,9 @@ function withExpander(plan, expander) {
 }
 function normalizeIndexValues(index, value, indexFields) {
   if (Array.isArray(value)) {
-    return Object.fromEntries(indexFields.map((field, index2) => [field, value[index2]]));
+    return Object.fromEntries(
+      indexFields.slice(0, value.length).map((field, index2) => [field, value[index2]])
+    );
   }
   if (isPlainObject(value)) {
     return value;
@@ -339,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.2",
+  "version": "0.5.0",
   "description": "Typed query facade helpers for Convex backends",
   "type": "module",
   "license": "MIT",