convex-helpers 0.1.22 → 0.1.23

package/README.md

@@ -136,6 +136,68 @@ export const myComplexQuery = zodQuery({
 })
 ```
 
+## Hono for advanced HTTP endpoint definitions
+
+[Hono](https://hono.dev/) is an optimized web framework you can use to define
+HTTP api endpoints easily
+([`httpAction` in Convex](https://docs.convex.dev/functions/http-actions)).
+
+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,
+  HonoWithConvex,
+  HttpRouterWithHono,
+} from "convex-helpers/server/hono";
+import { ActionCtx } from "./_generated/server";
+
+const app: HonoWithConvex<ActionCtx> = new Hono();
+
+// See the [guide on Stack](https://stack.convex.dev/hono-with-convex)
+// for tips on using Hono for HTTP endpoints.
+app.get("/", async (c) => {
+  return c.json("Hello world!");
+});
+
+export default new HttpRouterWithHono(app);
+```
+
+## CRUD utilities
+
+To generate a basic CRUD api for your tables, you can use this helper to define
+these functions for a given table:
+
+- `create`
+- `read`
+- `update`
+- `delete`
+- `paginate`
+
+**Note: I recommend only doing this for prototyping or [internal functions](https://docs.convex.dev/functions/internal-functions)**
+
+Example:
+```ts
+
+// in convex/users.ts
+import { crud } from "convex-helpers/server";
+import { internalMutation, internalQuery } from "../convex/_generated/server";
+
+const Users = Table("users", {...});
+
+export const { read, update } = crud(Users, internalQuery, internalMutation);
+
+// in convex/schema.ts
+import { Users } from "./users";
+export default defineSchema({users: Users.table});
+
+// in some file, in an action:
+const user = await ctx.runQuery(internal.users.read, { id: userId });
+
+await ctx.runMutation(internal.users.update, { status: "inactive" });
+```
+
 ## Validator utilities
 
 When using validators for defining database schema or function arguments,
@@ -145,18 +207,17 @@ these validators help:
 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. Make the validators look more like TypeScript types, even though they're
-runtime values.
-3. Add utilties for partial, pick and omit to match the TypeScript type
+2. Add utilties for partial, pick and omit to match the TypeScript type
 utilities.
-4. Add shorthand for a union of `literals`, a `nullable` field, a `deprecated`
+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).
+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).
 
 Example:
 ```js
 import { Table } from "convex-helpers/server";
-// Note some redefinitions in the import for even more terse definitions.
 import {
   literals, partial, deprecated, brandedString,
 } from "convex-helpers/validators";

package/dist/server/hono.d.ts

@@ -0,0 +1,105 @@
+/**
+ * This file contains a helper class for integrating Convex with Hono.
+ *
+ * See the [guide on Stack](https://stack.convex.dev/hono-with-convex)
+ * for tips on using Hono for HTTP endpoints.
+ *
+ * To use this helper, create a new Hono app in convex/http.ts like so:
+ * ```ts
+ * import {
+ *   Hono,
+ *   HonoWithConvex,
+ *   HttpRouterWithHono,
+ * } from "convex-helpers/server/hono";
+ * import { ActionCtx } from "./_generated/server";
+ *
+ * const app: HonoWithConvex<ActionCtx> = new Hono();
+ *
+ * app.get("/", async (c) => {
+ *   return c.json("Hello world!");
+ * });
+ *
+ * export default new HttpRouterWithHono(app);
+ * ```
+ */
+import { HttpRouter, PublicHttpAction, RoutableMethod, GenericActionCtx } from "convex/server";
+import { Hono } from "hono";
+export { Hono };
+/**
+ * Hono uses the `FetchEvent` type internally, which has to do with service workers
+ * and isn't included in the Convex tsconfig.
+ *
+ * As a workaround, define this type here so Hono + Convex compiles.
+ */
+declare global {
+    type FetchEvent = any;
+}
+/**
+ * A type representing a Hono app with `c.env` containing Convex's
+ * `HttpEndpointCtx` (e.g. `c.env.runQuery` is valid).
+ */
+export type HonoWithConvex<ActionCtx extends GenericActionCtx<any>> = Hono<{
+    Bindings: {
+        [Name in keyof ActionCtx]: ActionCtx[Name];
+    };
+}>;
+/**
+ * An implementation of the Convex `HttpRouter` that integrates with Hono by
+ * overridding `getRoutes` and `lookup`.
+ *
+ * This defers all routing and request handling to the provided Hono app, and
+ * passes along the Convex `HttpEndpointCtx` to the Hono handlers as part of
+ * `env`.
+ *
+ * It will attempt to log each request with the most specific Hono route it can
+ * find. For example,
+ *
+ * ```
+ * app.on("GET", "*", ...)
+ * app.on("GET", "/profile/:userId", ...)
+ *
+ * const http = new HttpRouterWithHono(app);
+ * http.lookup("/profile/abc", "GET") // [handler, "GET", "/profile/:userId"]
+ * ```
+ *
+ * An example `convex/http.ts` file would look like this:
+ * ```
+ * const app: HonoWithConvex = new Hono();
+ *
+ * // add Hono routes on `app`
+ *
+ * export default new HttpRouterWithHono(app);
+ * ```
+ */
+export declare class HttpRouterWithHono<ActionCtx extends GenericActionCtx<any>> extends HttpRouter {
+    private _app;
+    private _handler;
+    private _handlerInfoCache;
+    constructor(app: HonoWithConvex<ActionCtx>);
+    /**
+     * Returns a list of routed HTTP endpoints.
+     *
+     * These are used to populate the list of routes shown in the Functions page of the Convex dashboard.
+     *
+     * @returns - an array of [path, method, endpoint] tuples.
+     */
+    getRoutes: () => [string, "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", (...args: any) => any][];
+    /**
+     * Returns the appropriate HTTP endpoint and its routed request path and method.
+     *
+     * The path and method returned are used for logging and metrics, and should
+     * match up with one of the routes returned by `getRoutes`.
+     *
+     * For example,
+     *
+     * ```js
+     * http.route({ pathPrefix: "/profile/", method: "GET", handler: getProfile});
+     *
+     * http.lookup("/profile/abc", "GET") // returns [getProfile, "GET", "/profile/*"]
+     *```
+     *
+     * @returns - a tuple [PublicHttpEndpoint, method, path] or null.
+     */
+    lookup: (path: string, method: RoutableMethod | "HEAD") => readonly [PublicHttpAction, "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", string];
+}
+export declare function normalizeMethod(method: RoutableMethod | "HEAD"): RoutableMethod;

package/dist/server/hono.js

@@ -0,0 +1,154 @@
+/**
+ * This file contains a helper class for integrating Convex with Hono.
+ *
+ * See the [guide on Stack](https://stack.convex.dev/hono-with-convex)
+ * for tips on using Hono for HTTP endpoints.
+ *
+ * To use this helper, create a new Hono app in convex/http.ts like so:
+ * ```ts
+ * import {
+ *   Hono,
+ *   HonoWithConvex,
+ *   HttpRouterWithHono,
+ * } from "convex-helpers/server/hono";
+ * import { ActionCtx } from "./_generated/server";
+ *
+ * const app: HonoWithConvex<ActionCtx> = new Hono();
+ *
+ * app.get("/", async (c) => {
+ *   return c.json("Hello world!");
+ * });
+ *
+ * export default new HttpRouterWithHono(app);
+ * ```
+ */
+import { httpActionGeneric, HttpRouter, ROUTABLE_HTTP_METHODS, } from "convex/server";
+import { Hono } from "hono";
+export { Hono };
+/**
+ * An implementation of the Convex `HttpRouter` that integrates with Hono by
+ * overridding `getRoutes` and `lookup`.
+ *
+ * This defers all routing and request handling to the provided Hono app, and
+ * passes along the Convex `HttpEndpointCtx` to the Hono handlers as part of
+ * `env`.
+ *
+ * It will attempt to log each request with the most specific Hono route it can
+ * find. For example,
+ *
+ * ```
+ * app.on("GET", "*", ...)
+ * app.on("GET", "/profile/:userId", ...)
+ *
+ * const http = new HttpRouterWithHono(app);
+ * http.lookup("/profile/abc", "GET") // [handler, "GET", "/profile/:userId"]
+ * ```
+ *
+ * An example `convex/http.ts` file would look like this:
+ * ```
+ * const app: HonoWithConvex = new Hono();
+ *
+ * // add Hono routes on `app`
+ *
+ * export default new HttpRouterWithHono(app);
+ * ```
+ */
+export class HttpRouterWithHono extends HttpRouter {
+    _app;
+    _handler;
+    _handlerInfoCache;
+    constructor(app) {
+        super();
+        this._app = app;
+        // Single Convex httpEndpoint handler that just forwards the request to the
+        // Hono framework
+        this._handler = httpActionGeneric(async (ctx, request) => {
+            return await app.fetch(request, ctx);
+        });
+        this._handlerInfoCache = new Map();
+    }
+    /**
+     * Returns a list of routed HTTP endpoints.
+     *
+     * These are used to populate the list of routes shown in the Functions page of the Convex dashboard.
+     *
+     * @returns - an array of [path, method, endpoint] tuples.
+     */
+    getRoutes = () => {
+        const convexRoutes = [];
+        // Likely a better way to do this, but hono will have multiple handlers with the same
+        // name (i.e. for middleware), so de-duplicate so we don't show multiple routes in the dashboard.
+        const seen = new Set();
+        this._app.routes.forEach((route) => {
+            // Hono uses "ALL" in its router, which is not supported by the Convex router.
+            // Expand this into a route for every routable method supported by Convex.
+            if (route.method === "ALL") {
+                for (const method of ROUTABLE_HTTP_METHODS) {
+                    const name = `${method} ${route.path}`;
+                    if (!seen.has(name)) {
+                        seen.add(name);
+                        convexRoutes.push([route.path, method, route.handler]);
+                    }
+                }
+            }
+            else {
+                const name = `${route.method} ${route.path}`;
+                if (!seen.has(name)) {
+                    seen.add(name);
+                    convexRoutes.push([
+                        route.path,
+                        route.method,
+                        route.handler,
+                    ]);
+                }
+            }
+        });
+        return convexRoutes;
+    };
+    /**
+     * Returns the appropriate HTTP endpoint and its routed request path and method.
+     *
+     * The path and method returned are used for logging and metrics, and should
+     * match up with one of the routes returned by `getRoutes`.
+     *
+     * For example,
+     *
+     * ```js
+     * http.route({ pathPrefix: "/profile/", method: "GET", handler: getProfile});
+     *
+     * http.lookup("/profile/abc", "GET") // returns [getProfile, "GET", "/profile/*"]
+     *```
+     *
+     * @returns - a tuple [PublicHttpEndpoint, method, path] or null.
+     */
+    lookup = (path, method) => {
+        const match = this._app.router.match(method, path);
+        if (match === null) {
+            return [this._handler, normalizeMethod(method), path];
+        }
+        // There might be multiple handlers for a route (in the case of middleware),
+        // so choose the most specific one for the purposes of logging
+        const handlersAndRoutes = match[0];
+        const mostSpecificHandler = handlersAndRoutes[handlersAndRoutes.length - 1][0][0];
+        // On the first request let's populate a lookup from handler to info
+        if (this._handlerInfoCache.size === 0) {
+            for (const r of this._app.routes) {
+                this._handlerInfoCache.set(r.handler, {
+                    method: normalizeMethod(method),
+                    path: r.path,
+                });
+            }
+        }
+        const info = this._handlerInfoCache.get(mostSpecificHandler);
+        if (info) {
+            return [this._handler, info.method, info.path];
+        }
+        return [this._handler, normalizeMethod(method), path];
+    };
+}
+export function normalizeMethod(method) {
+    // HEAD is handled by Convex by running GET and stripping the body.
+    if (method === "HEAD")
+        return "GET";
+    return method;
+}

package/dist/server/index.d.ts

@@ -1,4 +1,5 @@
-import { Validator } from "convex/values";
+import { QueryBuilder, MutationBuilder, GenericDataModel, WithoutSystemFields, DocumentByName, RegisteredMutation, RegisteredQuery, FunctionVisibility, paginationOptsValidator, PaginationResult } from "convex/server";
+import { GenericId, Infer, ObjectType, Validator } from "convex/values";
 import { Expand } from "..";
 /**
  * Define a table with system fields _id and _creationTime. This also returns
@@ -16,21 +17,22 @@ import { Expand } from "..";
  * }
  */
 export declare function Table<T extends Record<string, Validator<any, any, any>>, TableName extends string>(name: TableName, fields: T): {
+    name: TableName;
     table: import("convex/server").TableDefinition<import("convex/dist/cjs-types/type_utils").Expand<import("convex/dist/cjs-types/server/system_fields").SystemFields & import("convex/dist/cjs-types/type_utils").Expand<{ [Property_1 in { [Property in keyof T]: T[Property]["isOptional"] extends true ? Property : never; }[keyof T]]?: T[Property_1]["type"] | undefined; } & { [Property_2 in Exclude<keyof T, { [Property in keyof T]: T[Property]["isOptional"] extends true ? Property : never; }[keyof T]>]: T[Property_2]["type"]; }>>, "_creationTime" | ({ [Property_3 in keyof T]: Property_3 | `${Property_3 & string}.${T[Property_3]["fieldPaths"]}`; }[keyof T] & string), {}, {}, {}>;
     doc: import("convex/dist/cjs-types/values/validator").ObjectValidator<Expand<T & {
-        _id: Validator<import("convex/values").GenericId<TableName>, false, never>;
+        _id: Validator<GenericId<TableName>, false, never>;
         _creationTime: Validator<number, false, never>;
     }>>;
     withoutSystemFields: T;
     withSystemFields: Expand<T & {
-        _id: Validator<import("convex/values").GenericId<TableName>, false, never>;
+        _id: Validator<GenericId<TableName>, false, never>;
         _creationTime: Validator<number, false, never>;
     }>;
     systemFields: {
-        _id: Validator<import("convex/values").GenericId<TableName>, false, never>;
+        _id: Validator<GenericId<TableName>, false, never>;
         _creationTime: Validator<number, false, never>;
     };
-    _id: Validator<import("convex/values").GenericId<TableName>, false, never>;
+    _id: Validator<GenericId<TableName>, false, never>;
 };
 /**
  *
@@ -44,3 +46,51 @@ export declare function missingEnvVariableUrl(envVarName: string, whereToGet: st
  * @returns The deployment name, like "screaming-lemur-123"
  */
 export declare function deploymentName(): string | undefined;
+/**
+ * Create CRUD operations for a table.
+ * You can expose these operations in your API. For example, in convex/users.ts:
+ *
+ * ```ts
+ * // in convex/users.ts
+ * import { crud } from "convex-helpers/server";
+ * import { query, mutation } from "./convex/_generated/server";
+ *
+ * const Users = Table("users", {
+ *  name: v.string(),
+ *  ///...
+ * });
+ *
+ * export const { create, read, paginate, update, destroy } =
+ *   crud(Users, query, mutation);
+ * ```
+ *
+ * Then from a client, you can access `api.users.create`.
+ *
+ * @param table The table to create CRUD operations for.
+ * Of type returned from Table() in "convex-helpers/server".
+ * @param query The query to use - use internalQuery or query from
+ * "./convex/_generated/server" or a customQuery.
+ * @param mutation The mutation to use - use internalMutation or mutation from
+ * "./convex/_generated/server" or a customMutation.
+ * @returns An object with create, read, update, and delete functions.
+ */
+export declare function crud<Fields extends Record<string, Validator<any, any, any>>, TableName extends string, DataModel extends GenericDataModel, QueryVisibility extends FunctionVisibility, MutationVisibility extends FunctionVisibility>(table: {
+    name: TableName;
+    _id: Validator<GenericId<TableName>>;
+    withoutSystemFields: Fields;
+}, query: QueryBuilder<DataModel, QueryVisibility>, mutation: MutationBuilder<DataModel, MutationVisibility>): {
+    create: RegisteredMutation<MutationVisibility, ObjectType<Fields>, Promise<DocumentByName<DataModel, TableName>>>;
+    read: RegisteredQuery<QueryVisibility, {
+        id: GenericId<TableName>;
+    }, Promise<DocumentByName<DataModel, TableName> | null>>;
+    paginate: RegisteredQuery<QueryVisibility, {
+        paginationOpts: Infer<typeof paginationOptsValidator>;
+    }, Promise<PaginationResult<DocumentByName<DataModel, TableName>>>>;
+    update: RegisteredMutation<MutationVisibility, {
+        id: GenericId<TableName>;
+        patch: Partial<WithoutSystemFields<DocumentByName<DataModel, TableName>>>;
+    }, Promise<void>>;
+    destroy: RegisteredMutation<MutationVisibility, {
+        id: GenericId<TableName>;
+    }, Promise<DocumentByName<DataModel, TableName> | null>>;
+};

package/dist/server/index.js

@@ -1,4 +1,4 @@
-import { defineTable } from "convex/server";
+import { defineTable, paginationOptsValidator, } from "convex/server";
 import { v } from "convex/values";
 /**
  * Define a table with system fields _id and _creationTime. This also returns
@@ -27,6 +27,7 @@ export function Table(name, fields) {
         ...systemFields,
     };
     return {
+        name,
         table,
         doc: v.object(withSystemFields),
         withoutSystemFields: fields,
@@ -60,3 +61,76 @@ export function deploymentName() {
     const regex = new RegExp("https://(.+).convex.cloud");
     return regex.exec(url)?.[1];
 }
+import { partial } from "../validators";
+/**
+ * Create CRUD operations for a table.
+ * You can expose these operations in your API. For example, in convex/users.ts:
+ *
+ * ```ts
+ * // in convex/users.ts
+ * import { crud } from "convex-helpers/server";
+ * import { query, mutation } from "./convex/_generated/server";
+ *
+ * const Users = Table("users", {
+ *  name: v.string(),
+ *  ///...
+ * });
+ *
+ * export const { create, read, paginate, update, destroy } =
+ *   crud(Users, query, mutation);
+ * ```
+ *
+ * Then from a client, you can access `api.users.create`.
+ *
+ * @param table The table to create CRUD operations for.
+ * Of type returned from Table() in "convex-helpers/server".
+ * @param query The query to use - use internalQuery or query from
+ * "./convex/_generated/server" or a customQuery.
+ * @param mutation The mutation to use - use internalMutation or mutation from
+ * "./convex/_generated/server" or a customMutation.
+ * @returns An object with create, read, update, and delete functions.
+ */
+export function crud(table, query, mutation) {
+    return {
+        create: mutation({
+            args: table.withoutSystemFields,
+            handler: async (ctx, args) => {
+                const id = await ctx.db.insert(table.name, args);
+                return (await ctx.db.get(id));
+            },
+        }),
+        read: query({
+            args: { id: table._id },
+            handler: async (ctx, args) => {
+                return await ctx.db.get(args.id);
+            },
+        }),
+        paginate: query({
+            args: {
+                paginationOpts: paginationOptsValidator,
+            },
+            handler: async (ctx, args) => {
+                return ctx.db.query(table.name).paginate(args.paginationOpts);
+            },
+        }),
+        update: mutation({
+            args: {
+                id: v.id(table.name),
+                patch: v.object(partial(table.withoutSystemFields)),
+            },
+            handler: async (ctx, args) => {
+                await ctx.db.patch(args.id, args.patch);
+            },
+        }),
+        destroy: mutation({
+            args: { id: table._id },
+            handler: async (ctx, args) => {
+                const old = await ctx.db.get(args.id);
+                if (old) {
+                    await ctx.db.delete(args.id);
+                }
+                return old;
+            },
+        }),
+    };
+}