convex-helpers 0.1.24 → 0.1.26

package/README.md

@@ -18,6 +18,7 @@ define custom behavior, allowing you to:
 See the associated [Stack Post](https://stack.convex.dev/custom-functions)
 
 For example:
+
 ```js
 import { customQuery } from "convex-helpers/server/customFunctions.js
 
@@ -49,6 +50,7 @@ See the [Stack post on relationship helpers](https://stack.convex.dev/functional
 and the [relationship schema structures post](https://stack.convex.dev/relationship-structures-let-s-talk-about-schemas).
 
 Example:
+
 ```js
 import {
   getOneFromOrThrow,
@@ -66,7 +68,11 @@ const posts = await asyncMap(
     const comments = await getManyFrom(db, "comments", "postId", post._id);
     // many-to-many via join table
     const categories = await getManyViaOrThrow(
-      db, "postCategories", "categoryId", "postId", post._id
+      db,
+      "postCategories",
+      "categoryId",
+      "postId",
+      post._id
     );
     return { ...post, comments, categories };
   }
@@ -86,46 +92,51 @@ See the associated [Stack post](https://stack.convex.dev/track-sessions-without-
 Example for a query (action & mutation are similar):
 
 In your React's root, add the `SessionProvider`:
+
 ```js
 import { SessionProvider } from "convex-helpers/react/sessions";
 //...
 <ConvexProvider client={convex}>
-	<SessionProvider>
-		<App />
-	</SessionProvider>
-</ConvexProvider>
+  <SessionProvider>
+    <App />
+  </SessionProvider>
+</ConvexProvider>;
 ```
 
 Pass the session ID from the client automatically to a server query:
+
 ```js
-import {  useSessionQuery } from "convex-helpers/react/sessions";
+import { useSessionQuery } from "convex-helpers/react/sessions";
 
 const results = useSessionQuery(api.myModule.mySessionQuery, { arg1: 1 });
 ```
 
 Define a server query function in `convex/myModule.ts`:
+
 ```js
 export const mySessionQuery = queryWithSession({
-	args: { arg1: v.number() },
-	handler: async (ctx, args) => {
-		// ctx.anonymousUser
-	}
-})
+  args: { arg1: v.number() },
+  handler: async (ctx, args) => {
+    // ctx.anonymousUser
+  },
+});
 ```
 
 Using `customQuery` to make `queryWithSession`:
+
 ```js
 import { customQuery } from "convex-helpers/server/customFunctions";
 import { SessionIdArg } from "convex-helpers/server/sessions";
 
 export const queryWithSession = customQuery(query, {
-	args: SessionIdArg,
-	input: async (ctx, { sessionId }) => {
-		const anonymousUser = await getAnonUser(ctx, sessionId);
-		return { ctx: { ...ctx, anonymousUser }, args: {} };
-	},
+  args: SessionIdArg,
+  input: async (ctx, { sessionId }) => {
+    const anonymousUser = await getAnonUser(ctx, sessionId);
+    return { ctx: { ...ctx, anonymousUser }, args: {} };
+  },
 });
 ```
+
 **Note:** `getAnonUser` is some function you write to look up a user by session.
 
 ## Row-level security
@@ -145,6 +156,7 @@ features for validating arguments, this is for you!
 See the [Stack post on Zod validation](https://stack.convex.dev/wrappers-as-middleware-zod-validation) to see how to validate your Convex functions using the [zod](https://www.npmjs.com/package/zod) library.
 
 Example:
+
 ```js
 import { z } from "zod";
 import { zCustomQuery, zid } from "convex-helpers/server/zod";
@@ -177,8 +189,8 @@ export const myComplexQuery = zodQuery({
     //... args at this point has been validated and has the types of what
     // zod parses the values into.
     // e.g. boolWithDefault is `bool` but has an input type `bool | undefined`.
-  }
-})
+  },
+});
 ```
 
 ## Hono for advanced HTTP endpoint definitions
@@ -190,6 +202,7 @@ HTTP api endpoints easily
 See the [guide on Stack](https://stack.convex.dev/hono-with-convex) for tips on using Hono for HTTP endpoints.
 
 To use it, put this in your `convex/http.ts` file:
+
 ```ts
 import {
   Hono,
@@ -223,6 +236,7 @@ these functions for a given table:
 **Note: I recommend only doing this for prototyping or [internal functions](https://docs.convex.dev/functions/internal-functions)**
 
 Example:
+
 ```ts
 
 // in convex/users.ts
@@ -249,22 +263,26 @@ When using validators for defining database schema or function arguments,
 these validators help:
 
 1. Add a `Table` utility that defines a table and keeps references to the fields
-to avoid re-defining validators. To learn more about sharing validators, read
-[this article](https://stack.convex.dev/argument-validation-without-repetition),
-an extension of [this article](https://stack.convex.dev/types-cookbook).
+   to avoid re-defining validators. To learn more about sharing validators, read
+   [this article](https://stack.convex.dev/argument-validation-without-repetition),
+   an extension of [this article](https://stack.convex.dev/types-cookbook).
 2. Add utilties for partial, pick and omit to match the TypeScript type
-utilities.
+   utilities.
 3. Add shorthand for a union of `literals`, a `nullable` field, a `deprecated`
-field, and `brandedString`. To learn more about branded strings see
-[this article](https://stack.convex.dev/using-branded-types-in-validators).
+   field, and `brandedString`. To learn more about branded strings see
+   [this article](https://stack.convex.dev/using-branded-types-in-validators).
 4. Make the validators look more like TypeScript types, even though they're
-runtime values. (This is controvercial and not required to use the above).
+   runtime values. (This is controvercial and not required to use the above).
 
 Example:
+
 ```js
 import { Table } from "convex-helpers/server";
 import {
-  literals, partial, deprecated, brandedString,
+  literals,
+  partial,
+  deprecated,
+  brandedString,
 } from "convex-helpers/validators";
 import { omit, pick } from "convex-helpers";
 import { Infer } from "convex/values";
@@ -309,3 +327,39 @@ const balanceAndEmail = pick(Account.withoutSystemFields, ["balance", "email"]);
 // A validator for all the fields except balance.
 const accountWithoutBalance = omit(Account.withSystemFields, ["balance"]);
 ```
+
+## Filter
+
+See the [guide on Stack](https://stack.convex.dev/complex-filters-in-convex)
+for an analysis of complex filters on Convex.
+
+The `filter` helper composes with `ctx.db.query` to apply arbitrary TypeScript
+or JavaScript filters to a database query.
+
+Examples:
+
+```js
+import { filter } from "convex-helpers/server/filter";
+
+export const evens = query({
+  args: {},
+  handler: async (ctx) => {
+    return await filter(
+      ctx.db.query("counter_table"),
+      (c) => c.counter % 2 === 0
+    ).collect();
+  },
+});
+
+export const lastCountLongerThanName = query({
+  args: {},
+  handler: async (ctx) => {
+    return await filter(
+      ctx.db.query("counter_table"),
+      (c) => c.counter > c.name.length
+    )
+      .order("desc")
+      .first();
+  },
+});
+```

package/dist/react/sessions.d.ts

@@ -29,15 +29,18 @@ type SessionArgsArray<Fn extends SessionFunction<"mutation" | "action">> = keyof
 /**
  * Context for a Convex session, creating a server session and providing the id.
  *
- * @param props - Where you want your session ID to be persisted. Roughly:
+ * @param useStorage - Where you want your session ID to be persisted. Roughly:
  *  - sessionStorage is saved per-tab
  *  - localStorage is shared between tabs, but not browser profiles.
+ * @param storageKey - Key under which to store the session ID in the store
+ * @param idGenerator - Function to return a new, unique session ID string. Defaults to crypto.randomUUID
  * @returns A provider to wrap your React nodes which provides the session ID.
  * To be used with useSessionQuery and useSessionMutation.
  */
 export declare const SessionProvider: React.FC<{
     useStorage?: UseStorage<SessionId>;
     storageKey?: string;
+    idGenerator?: () => string;
     children?: React.ReactNode;
 }>;
 export declare function useSessionQuery<Query extends SessionFunction<"query">>(query: Query, ...args: SessionQueryArgsArray<Query>): FunctionReturnType<Query> | undefined;

package/dist/react/sessions.js

@@ -23,20 +23,23 @@ const SessionContext = React.createContext(null);
 /**
  * Context for a Convex session, creating a server session and providing the id.
  *
- * @param props - Where you want your session ID to be persisted. Roughly:
+ * @param useStorage - Where you want your session ID to be persisted. Roughly:
  *  - sessionStorage is saved per-tab
  *  - localStorage is shared between tabs, but not browser profiles.
+ * @param storageKey - Key under which to store the session ID in the store
+ * @param idGenerator - Function to return a new, unique session ID string. Defaults to crypto.randomUUID
  * @returns A provider to wrap your React nodes which provides the session ID.
  * To be used with useSessionQuery and useSessionMutation.
  */
-export const SessionProvider = ({ useStorage, storageKey, children }) => {
+export const SessionProvider = ({ useStorage, storageKey, idGenerator, children }) => {
     const storeKey = storageKey ?? "convex-session-id";
-    const initialId = useMemo(() => crypto.randomUUID(), []);
+    const idGen = idGenerator ?? crypto.randomUUID.bind(crypto);
+    const initialId = useMemo(() => idGen(), []);
     // Get or set the ID from our desired storage location.
     const useStorageOrDefault = useStorage ?? useSessionStorage;
     const [sessionId, setSessionId] = useStorageOrDefault(storeKey, initialId);
     const refreshSessionId = useCallback(async (beforeUpdate) => {
-        const newSessionId = crypto.randomUUID();
+        const newSessionId = idGen();
         if (beforeUpdate) {
             await beforeUpdate(newSessionId);
         }

package/dist/server/zod.d.ts

@@ -1,5 +1,5 @@
 import { ZodTypeDef, z } from "zod";
-import { v, GenericId, ObjectType, PropertyValidators, Validator } from "convex/values";
+import { GenericId, ObjectType, PropertyValidators, Validator } from "convex/values";
 import { FunctionVisibility, GenericDataModel, GenericActionCtx, GenericQueryCtx, MutationBuilder, QueryBuilder, GenericMutationCtx, ActionBuilder } from "convex/server";
 import { Mod, Registration, UnvalidatedBuilder } from "./customFunctions";
 import { EmptyObject } from "..";
@@ -194,9 +194,19 @@ type ValidatedBuilder<FuncType extends "query" | "mutation" | "action", ModArgsV
  * builder will require argument validation too.
  */
 type CustomBuilder<FuncType extends "query" | "mutation" | "action", ModArgsValidator extends PropertyValidators, ModCtx extends Record<string, any>, ModMadeArgs extends Record<string, any>, InputCtx, Visibility extends FunctionVisibility> = ModArgsValidator extends EmptyObject ? ValidatedBuilder<FuncType, ModArgsValidator, ModCtx, ModMadeArgs, InputCtx, Visibility> & UnvalidatedBuilder<FuncType, ModCtx, ModMadeArgs, InputCtx, Visibility> : ValidatedBuilder<FuncType, ModArgsValidator, ModCtx, ModMadeArgs, InputCtx, Visibility>;
-type ConvexValidatorFromZod<Z extends z.ZodTypeAny> = Z extends Zid<infer TableName> ? Validator<GenericId<TableName>> : Z extends z.ZodString ? Validator<string> : Z extends z.ZodNumber ? Validator<number> : Z extends z.ZodNaN ? Validator<number> : Z extends z.ZodBigInt ? Validator<bigint> : Z extends z.ZodBoolean ? Validator<boolean> : Z extends z.ZodNull ? Validator<null> : Z extends z.ZodUnknown ? Validator<any, false, string> : Z extends z.ZodAny ? Validator<any, false, string> : Z extends z.ZodArray<infer Inner> ? Validator<ConvexValidatorFromZod<Inner>["type"][]> : Z extends z.ZodObject<infer ZodShape> ? ReturnType<typeof v.object<{
+/**
+ * START Include some types from convex that aren't exported currently.
+ */
+type JoinFieldPaths<Start extends string, End extends string> = `${Start}.${End}`;
+type ObjectValidator<Validators extends PropertyValidators> = Validator<ObjectType<Validators>, false, {
+    [Property in keyof Validators]: JoinFieldPaths<Property & string, Validators[Property]["fieldPaths"]> | Property;
+}[keyof Validators] & string>;
+/**
+ * END types copied from Convex. Delete when Convex exports these types.
+ */
+type ConvexValidatorFromZod<Z extends z.ZodTypeAny> = Z extends Zid<infer TableName> ? Validator<GenericId<TableName>> : Z extends z.ZodString ? Validator<string> : Z extends z.ZodNumber ? Validator<number> : Z extends z.ZodNaN ? Validator<number> : Z extends z.ZodBigInt ? Validator<bigint> : Z extends z.ZodBoolean ? Validator<boolean> : Z extends z.ZodNull ? Validator<null> : Z extends z.ZodUnknown ? Validator<any, false, string> : Z extends z.ZodAny ? Validator<any, false, string> : Z extends z.ZodArray<infer Inner> ? Validator<ConvexValidatorFromZod<Inner>["type"][]> : Z extends z.ZodObject<infer ZodShape> ? ObjectValidator<{
     [key in keyof ZodShape]: ConvexValidatorFromZod<ZodShape[key]>;
-}>> : Z extends z.ZodUnion<infer T> ? Validator<ConvexValidatorFromZod<T[number]>["type"], false, ConvexValidatorFromZod<T[number]>["fieldPaths"]> : Z extends z.ZodDiscriminatedUnion<any, infer T> ? Validator<ConvexValidatorFromZod<T[number]>["type"], false, ConvexValidatorFromZod<T[number]>["fieldPaths"]> : Z extends z.ZodTuple<infer Inner> ? Validator<ConvexValidatorFromZod<Inner[number]>["type"][]> : Z extends z.ZodLazy<infer Inner> ? ConvexValidatorFromZod<Inner> : Z extends z.ZodLiteral<infer Literal> ? Validator<Literal> : Z extends z.ZodEnum<infer T> ? Validator<T[number]> : Z extends z.ZodEffects<infer Inner> ? ConvexValidatorFromZod<Inner> : Z extends z.ZodOptional<infer Inner> ? ConvexValidatorFromZod<Inner> extends Validator<infer InnerConvex, false, infer InnerFieldPaths> ? Validator<InnerConvex | undefined, true, InnerFieldPaths> : never : Z extends z.ZodNullable<infer Inner> ? ConvexValidatorFromZod<Inner> extends Validator<infer InnerConvex, infer InnerOptional, infer InnerFieldPaths> ? Validator<null | InnerConvex, InnerOptional, InnerFieldPaths> : never : Z extends z.ZodBranded<infer Inner, any> ? ConvexValidatorFromZod<Inner> : Z extends z.ZodDefault<infer Inner> ? ConvexValidatorFromZod<Inner> extends Validator<infer InnerConvex, false, infer InnerFieldPaths> ? Validator<InnerConvex | undefined, true, InnerFieldPaths> : never : Z extends z.ZodReadonly<infer Inner> ? ConvexValidatorFromZod<Inner> : Z extends z.ZodPipeline<infer Inner, any> ? ConvexValidatorFromZod<Inner> : never;
+}> : Z extends z.ZodUnion<infer T> ? Validator<ConvexValidatorFromZod<T[number]>["type"], false, ConvexValidatorFromZod<T[number]>["fieldPaths"]> : Z extends z.ZodDiscriminatedUnion<any, infer T> ? Validator<ConvexValidatorFromZod<T[number]>["type"], false, ConvexValidatorFromZod<T[number]>["fieldPaths"]> : Z extends z.ZodTuple<infer Inner> ? Validator<ConvexValidatorFromZod<Inner[number]>["type"][]> : Z extends z.ZodLazy<infer Inner> ? ConvexValidatorFromZod<Inner> : Z extends z.ZodLiteral<infer Literal> ? Validator<Literal> : Z extends z.ZodEnum<infer T> ? Validator<T[number]> : Z extends z.ZodEffects<infer Inner> ? ConvexValidatorFromZod<Inner> : Z extends z.ZodOptional<infer Inner> ? ConvexValidatorFromZod<Inner> extends Validator<infer InnerConvex, false, infer InnerFieldPaths> ? Validator<InnerConvex | undefined, true, InnerFieldPaths> : never : Z extends z.ZodNullable<infer Inner> ? ConvexValidatorFromZod<Inner> extends Validator<infer InnerConvex, infer InnerOptional, infer InnerFieldPaths> ? Validator<null | InnerConvex, InnerOptional, InnerFieldPaths> : never : Z extends z.ZodBranded<infer Inner, any> ? ConvexValidatorFromZod<Inner> : Z extends z.ZodDefault<infer Inner> ? ConvexValidatorFromZod<Inner> extends Validator<infer InnerConvex, false, infer InnerFieldPaths> ? Validator<InnerConvex | undefined, true, InnerFieldPaths> : never : Z extends z.ZodReadonly<infer Inner> ? ConvexValidatorFromZod<Inner> : Z extends z.ZodPipeline<infer Inner, any> ? ConvexValidatorFromZod<Inner> : never;
 /**
  * Turn a Zod validator into a Convex Validator.
  * @param zod Zod validator can be a Zod object, or a Zod type like `z.string()`

package/dist/testing.d.ts

@@ -0,0 +1,33 @@
+import { ConvexClient } from "convex/browser";
+import { FunctionArgs, FunctionReference, FunctionReturnType, UserIdentity } from "convex/server";
+/**
+ * This is a helper for testing Convex functions against a locally running backend.
+ *
+ * An example of calling a function:
+ * ```
+ * const t = new ConvexTestingHelper();
+ * const result = await t.query(api.foo.bar, { arg1: "baz" })
+ * ```
+ *
+ * An example of calling a function with auth:
+ * ```
+ * const t = new ConvexTestingHelper();
+ * const identityA = t.newIdentity({ name: "Person A"})
+ * const result = await t.withIdentity(identityA).query(api.users.getProfile);
+ * ```
+ */
+export declare class ConvexTestingHelper {
+    private _nextSubjectId;
+    client: ConvexClient;
+    private _adminKey;
+    constructor(options?: {
+        adminKey?: string;
+        backendUrl?: string;
+    });
+    newIdentity(args: Partial<Omit<UserIdentity, "tokenIdentifier">>): Omit<UserIdentity, "tokenIdentifier">;
+    withIdentity(identity: Omit<UserIdentity, "tokenIdentifier">): Pick<ConvexClient, "mutation" | "action" | "query">;
+    mutation<Mutation extends FunctionReference<"mutation">>(mutation: Mutation, args: FunctionArgs<Mutation>): Promise<Awaited<FunctionReturnType<Mutation>>>;
+    query<Query extends FunctionReference<"query", "public">>(query: Query, args: FunctionArgs<Query>): Promise<Awaited<FunctionReturnType<Query>>>;
+    action<Action extends FunctionReference<"action">>(action: Action, args: FunctionArgs<Action>): Promise<Awaited<FunctionReturnType<Action>>>;
+    close(): Promise<void>;
+}

package/dist/testing.js

@@ -0,0 +1,73 @@
+import { ConvexClient } from "convex/browser";
+/**
+ * This is a helper for testing Convex functions against a locally running backend.
+ *
+ * An example of calling a function:
+ * ```
+ * const t = new ConvexTestingHelper();
+ * const result = await t.query(api.foo.bar, { arg1: "baz" })
+ * ```
+ *
+ * An example of calling a function with auth:
+ * ```
+ * const t = new ConvexTestingHelper();
+ * const identityA = t.newIdentity({ name: "Person A"})
+ * const result = await t.withIdentity(identityA).query(api.users.getProfile);
+ * ```
+ */
+export class ConvexTestingHelper {
+    _nextSubjectId = 0;
+    client;
+    _adminKey;
+    constructor(options = {}) {
+        this.client = new ConvexClient(options.backendUrl ?? "http://127.0.0.1:3210");
+        this._adminKey =
+            options.adminKey ??
+                // default admin key for local backends - from https://github.com/get-convex/convex-backend/blob/main/Justfile
+                "0135d8598650f8f5cb0f30c34ec2e2bb62793bc28717c8eb6fb577996d50be5f4281b59181095065c5d0f86a2c31ddbe9b597ec62b47ded69782cd";
+    }
+    newIdentity(args) {
+        const subject = `test subject ${this._nextSubjectId}`;
+        this._nextSubjectId += 1;
+        const issuer = "test issuer";
+        return {
+            ...args,
+            subject,
+            issuer,
+        };
+    }
+    withIdentity(identity) {
+        return {
+            mutation: (functionReference, args) => {
+                this.client.setAdminAuth(this._adminKey, identity);
+                return this.client.mutation(functionReference, args).finally(() => {
+                    this.client.client.clearAuth();
+                });
+            },
+            action: (functionReference, args) => {
+                this.client.setAdminAuth(this._adminKey, identity);
+                return this.client.action(functionReference, args).finally(() => {
+                    this.client.client.clearAuth();
+                });
+            },
+            query: (functionReference, args) => {
+                this.client.setAdminAuth(this._adminKey, identity);
+                return this.client.query(functionReference, args).finally(() => {
+                    this.client.client.clearAuth();
+                });
+            },
+        };
+    }
+    async mutation(mutation, args) {
+        return this.client.mutation(mutation, args);
+    }
+    async query(query, args) {
+        return this.client.query(query, args);
+    }
+    async action(action, args) {
+        return this.client.action(action, args);
+    }
+    async close() {
+        return this.client.close();
+    }
+}