@davidtkramer/convex-relations 0.5.0 → 0.6.0

package/README.md

@@ -345,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:

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;
@@ -154,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidtkramer/convex-relations",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Typed query facade helpers for Convex backends",
   "type": "module",
   "license": "MIT",
@@ -28,11 +28,6 @@
   },
   "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"
   },
@@ -45,5 +40,9 @@
     "typical-data": "^0.5.0",
     "vitest": "^4.0.15"
   },
-  "packageManager": "pnpm@9.15.9"
-}
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --typecheck"
+  }
+}