fluent-convex 0.7.1 → 0.7.2

package/src/ConvexBuilder.ts

@@ -0,0 +1,277 @@
+import type { GenericDataModel } from "convex/server";
+import { InferredArgs } from "./types";
+import { InferHandlerReturn } from "./types";
+import { ConvexBuilderDef } from "./types";
+import { CallableBuilder } from "./types";
+import { ConvexBuilderWithHandler } from "./ConvexBuilderWithHandler";
+import type { ConvexMiddleware, AnyConvexMiddleware } from "./middleware";
+import type {
+  FunctionType,
+  Context,
+  EmptyObject,
+  ConvexArgsValidator,
+  ConvexReturnsValidator,
+  QueryCtx,
+  MutationCtx,
+  ActionCtx,
+} from "./types";
+import {
+  type ValidatorInput,
+  type ToConvexArgsValidator,
+  isZodSchema,
+  toConvexValidator,
+  type ReturnsValidatorInput,
+  type ToConvexReturnsValidator,
+} from "./zod_support";
+
+export class ConvexBuilder<
+  TDataModel extends GenericDataModel = GenericDataModel,
+  TFunctionType extends FunctionType | undefined = undefined,
+  TInitialContext extends Context = EmptyObject,
+  TCurrentContext extends Context = EmptyObject,
+  TArgsValidator extends ConvexArgsValidator | undefined = undefined,
+  TReturnsValidator extends ConvexReturnsValidator | undefined = undefined,
+> {
+  protected def: ConvexBuilderDef<
+    TFunctionType,
+    TArgsValidator,
+    TReturnsValidator
+  >;
+
+  constructor(
+    def: ConvexBuilderDef<TFunctionType, TArgsValidator, TReturnsValidator>
+  ) {
+    this.def = def;
+  }
+
+  query(
+    this: ConvexBuilder<
+      TDataModel,
+      undefined,
+      TInitialContext,
+      TCurrentContext,
+      TArgsValidator,
+      TReturnsValidator
+    >
+  ): ConvexBuilder<
+    TDataModel,
+    "query",
+    QueryCtx<TDataModel>,
+    QueryCtx<TDataModel>
+  > {
+    return new ConvexBuilder({
+      ...this.def,
+      functionType: "query",
+    }) as any;
+  }
+
+  mutation(
+    this: ConvexBuilder<
+      TDataModel,
+      undefined,
+      TInitialContext,
+      TCurrentContext,
+      TArgsValidator,
+      TReturnsValidator
+    >
+  ): ConvexBuilder<
+    TDataModel,
+    "mutation",
+    MutationCtx<TDataModel>,
+    MutationCtx<TDataModel>
+  > {
+    return new ConvexBuilder({
+      ...this.def,
+      functionType: "mutation",
+    }) as any;
+  }
+
+  action(
+    this: ConvexBuilder<
+      TDataModel,
+      undefined,
+      TInitialContext,
+      TCurrentContext,
+      TArgsValidator,
+      TReturnsValidator
+    >
+  ): ConvexBuilder<
+    TDataModel,
+    "action",
+    ActionCtx<TDataModel>,
+    ActionCtx<TDataModel>
+  > {
+    return new ConvexBuilder({
+      ...this.def,
+      functionType: "action",
+    }) as any;
+  }
+
+  $context<U extends Context>(): ConvexBuilder<
+    TDataModel,
+    TFunctionType,
+    U & EmptyObject,
+    U,
+    TArgsValidator,
+    TReturnsValidator
+  > {
+    return new ConvexBuilder({
+      ...this.def,
+      middlewares: [],
+    }) as any;
+  }
+
+  middleware<UOutContext extends Context>(
+    middleware: ConvexMiddleware<TInitialContext, UOutContext>
+  ): ConvexMiddleware<TInitialContext, UOutContext>;
+  middleware<UInContext extends Context, UOutContext extends Context>(
+    middleware: ConvexMiddleware<UInContext, UOutContext>
+  ): ConvexMiddleware<UInContext, UOutContext>;
+  middleware<UInContext extends Context, UOutContext extends Context>(
+    middleware: ConvexMiddleware<UInContext, UOutContext>
+  ): ConvexMiddleware<UInContext, UOutContext> {
+    return middleware;
+  }
+
+  use<UOutContext extends Context>(
+    this: ConvexBuilder<
+      TDataModel,
+      FunctionType,
+      TInitialContext,
+      TCurrentContext,
+      TArgsValidator,
+      TReturnsValidator
+    >,
+    middleware: ConvexMiddleware<TCurrentContext, UOutContext>
+  ): ConvexBuilder<
+    TDataModel,
+    TFunctionType,
+    TInitialContext,
+    TCurrentContext & UOutContext,
+    TArgsValidator,
+    TReturnsValidator
+  > {
+    return new ConvexBuilder({
+      ...this.def,
+      middlewares: [...this.def.middlewares, middleware as AnyConvexMiddleware],
+    }) as any;
+  }
+
+  input<UInput extends ValidatorInput>(
+    this: ConvexBuilder<
+      TDataModel,
+      FunctionType,
+      TInitialContext,
+      TCurrentContext,
+      TArgsValidator,
+      TReturnsValidator
+    >,
+    validator: UInput
+  ): ConvexBuilder<
+    TDataModel,
+    TFunctionType,
+    TInitialContext,
+    TCurrentContext,
+    ToConvexArgsValidator<UInput>,
+    TReturnsValidator
+  > {
+    const convexValidator = (
+      isZodSchema(validator) ? toConvexValidator(validator) : validator
+    ) as ToConvexArgsValidator<UInput>;
+
+    return new ConvexBuilder({
+      ...this.def,
+      argsValidator: convexValidator,
+    }) as any;
+  }
+
+  returns<UReturns extends ReturnsValidatorInput>(
+    this: ConvexBuilder<
+      TDataModel,
+      FunctionType,
+      TInitialContext,
+      TCurrentContext,
+      TArgsValidator,
+      TReturnsValidator
+    >,
+    validator: UReturns
+  ): ConvexBuilder<
+    TDataModel,
+    TFunctionType,
+    TInitialContext,
+    TCurrentContext,
+    TArgsValidator,
+    ToConvexReturnsValidator<UReturns>
+  > {
+    const convexValidator = (
+      isZodSchema(validator) ? toConvexValidator(validator) : validator
+    ) as ToConvexReturnsValidator<UReturns>;
+
+    return new ConvexBuilder({
+      ...this.def,
+      returnsValidator: convexValidator,
+    }) as any;
+  }
+
+  handler<
+    TReturn extends InferHandlerReturn<
+      TReturnsValidator,
+      any
+    > = InferHandlerReturn<TReturnsValidator, any>,
+  >(
+    this: ConvexBuilder<
+      TDataModel,
+      FunctionType,
+      TInitialContext,
+      TCurrentContext,
+      TArgsValidator,
+      TReturnsValidator
+    >,
+    handlerFn: (options: {
+      context: TCurrentContext;
+      input: InferredArgs<TArgsValidator>;
+    }) => Promise<TReturn>
+  ): ConvexBuilderWithHandler<
+    TDataModel,
+    TFunctionType & FunctionType,
+    TCurrentContext,
+    TArgsValidator,
+    TReturnsValidator,
+    InferHandlerReturn<TReturnsValidator, TReturn>
+  > &
+    CallableBuilder<
+      TCurrentContext,
+      TArgsValidator,
+      InferHandlerReturn<TReturnsValidator, TReturn>
+    > {
+    if (this.def.handler) {
+      throw new Error(
+        "Handler already defined. Only one handler can be set per function chain."
+      );
+    }
+
+    const rawHandler = async (
+      transformedCtx: Context,
+      baseArgs: InferredArgs<TArgsValidator>
+    ) => {
+      return handlerFn({
+        context: transformedCtx as TCurrentContext,
+        input: baseArgs,
+      });
+    };
+
+    type InferredReturn = InferHandlerReturn<TReturnsValidator, TReturn>;
+
+    return new ConvexBuilderWithHandler<
+      TDataModel,
+      TFunctionType & FunctionType,
+      TCurrentContext,
+      TArgsValidator,
+      TReturnsValidator,
+      InferredReturn
+    >({
+      ...this.def,
+      handler: rawHandler as any,
+    } as any) as any;
+  }
+}

package/src/ConvexBuilderWithHandler.ts

@@ -0,0 +1,185 @@
+import {
+  type GenericDataModel,
+  type RegisteredQuery,
+  type RegisteredMutation,
+  type RegisteredAction,
+  queryGeneric,
+  internalQueryGeneric,
+  mutationGeneric,
+  internalMutationGeneric,
+  actionGeneric,
+  internalActionGeneric,
+} from "convex/server";
+import { applyMiddlewares } from "./builder";
+import { InferredArgs } from "./types";
+import { ConvexBuilderDef } from "./types";
+import { CallableBuilder } from "./types";
+import type { ConvexMiddleware, AnyConvexMiddleware } from "./middleware";
+import type {
+  FunctionType,
+  Context,
+  EmptyObject,
+  ConvexArgsValidator,
+  ConvexReturnsValidator,
+  QueryCtx,
+  MutationCtx,
+  ActionCtx,
+} from "./types";
+
+export class ConvexBuilderWithHandler<
+  TDataModel extends GenericDataModel = GenericDataModel,
+  TFunctionType extends FunctionType = FunctionType,
+  TCurrentContext extends Context = EmptyObject,
+  TArgsValidator extends ConvexArgsValidator | undefined = undefined,
+  TReturnsValidator extends ConvexReturnsValidator | undefined = undefined,
+  THandlerReturn = any,
+> {
+  private def: ConvexBuilderDef<
+    TFunctionType,
+    TArgsValidator,
+    TReturnsValidator
+  >;
+
+  constructor(
+    def: ConvexBuilderDef<TFunctionType, TArgsValidator, TReturnsValidator>
+  ) {
+    this.def = def;
+
+    // Make the instance callable by returning a Proxy
+    return new Proxy(this, {
+      apply: (_target, _thisArg, args: [TCurrentContext]) => {
+        return this._call(args[0]);
+      },
+    }) as any;
+  }
+
+  // Internal method to handle the call
+  private _call(
+    context: TCurrentContext
+  ): (args: InferredArgs<TArgsValidator>) => Promise<THandlerReturn> {
+    const { handler, middlewares } = this.def;
+
+    if (!handler) {
+      throw new Error("Handler not set.");
+    }
+
+    return async (args: InferredArgs<TArgsValidator>) => {
+      const transformedContext = await applyMiddlewares(context, middlewares);
+      return handler(transformedContext as any, args);
+    };
+  }
+
+  use<UOutContext extends Context>(
+    middleware: ConvexMiddleware<TCurrentContext, UOutContext>
+  ): ConvexBuilderWithHandler<
+    TDataModel,
+    TFunctionType,
+    TCurrentContext & UOutContext,
+    TArgsValidator,
+    TReturnsValidator,
+    THandlerReturn
+  > &
+    CallableBuilder<
+      TCurrentContext & UOutContext,
+      TArgsValidator,
+      THandlerReturn
+    > {
+    return new ConvexBuilderWithHandler({
+      ...this.def,
+      middlewares: [...this.def.middlewares, middleware as AnyConvexMiddleware],
+    }) as any;
+  }
+
+  public(): TFunctionType extends "query"
+    ? RegisteredQuery<
+        "public",
+        InferredArgs<TArgsValidator>,
+        Promise<THandlerReturn>
+      >
+    : TFunctionType extends "mutation"
+      ? RegisteredMutation<
+          "public",
+          InferredArgs<TArgsValidator>,
+          Promise<THandlerReturn>
+        >
+      : TFunctionType extends "action"
+        ? RegisteredAction<
+            "public",
+            InferredArgs<TArgsValidator>,
+            Promise<THandlerReturn>
+          >
+        : never {
+    return this._register("public") as any;
+  }
+
+  internal(): TFunctionType extends "query"
+    ? RegisteredQuery<
+        "internal",
+        InferredArgs<TArgsValidator>,
+        Promise<THandlerReturn>
+      >
+    : TFunctionType extends "mutation"
+      ? RegisteredMutation<
+          "internal",
+          InferredArgs<TArgsValidator>,
+          Promise<THandlerReturn>
+        >
+      : TFunctionType extends "action"
+        ? RegisteredAction<
+            "internal",
+            InferredArgs<TArgsValidator>,
+            Promise<THandlerReturn>
+          >
+        : never {
+    return this._register("internal") as any;
+  }
+
+  private _register(visibility: "public" | "internal"): any {
+    const {
+      functionType,
+      argsValidator,
+      returnsValidator,
+      handler,
+      middlewares,
+    } = this.def;
+
+    if (!functionType) {
+      throw new Error(
+        "Function type not set. Call .query(), .mutation(), or .action() first."
+      );
+    }
+
+    if (!handler) {
+      throw new Error(
+        "Handler not set. Call .handler() before .public() or .internal()."
+      );
+    }
+
+    // Compose the handler with all middlewares (including those added after .handler())
+    const composedHandler = async (
+      baseCtx:
+        | QueryCtx<TDataModel>
+        | MutationCtx<TDataModel>
+        | ActionCtx<TDataModel>,
+      baseArgs: any
+    ) => {
+      const transformedContext = await applyMiddlewares(baseCtx, middlewares);
+      return handler(transformedContext as any, baseArgs);
+    };
+
+    const config = {
+      args: argsValidator || {},
+      ...(returnsValidator ? { returns: returnsValidator } : {}),
+      handler: composedHandler,
+    } as any;
+
+    const isPublic = visibility === "public";
+    const registrationFn = {
+      query: isPublic ? queryGeneric : internalQueryGeneric,
+      mutation: isPublic ? mutationGeneric : internalMutationGeneric,
+      action: isPublic ? actionGeneric : internalActionGeneric,
+    }[functionType];
+
+    return registrationFn(config);
+  }
+}