@confect/server 1.0.0-next.0

package/src/FunctionImpl.ts

@@ -0,0 +1,112 @@
+import type * as FunctionSpec from "@confect/core/FunctionSpec";
+import type * as GroupPath from "@confect/core/GroupPath";
+import type * as GroupSpec from "@confect/core/GroupSpec";
+import { Array, Context, Effect, Layer, Ref, String } from "effect";
+import type * as Api from "./Api";
+import type * as Handler from "./Handler";
+import { setNestedProperty } from "./internal/utils";
+import * as Registry from "./Registry";
+import * as RegistryItem from "./RegistryItem";
+
+export interface FunctionImpl<
+  GroupPath_ extends string,
+  FunctionName extends string,
+> {
+  readonly groupPath: GroupPath_;
+  readonly functionName: FunctionName;
+}
+
+export const FunctionImpl = <
+  GroupPath_ extends string,
+  FunctionName extends string,
+>({
+  groupPath,
+  functionName,
+}: {
+  groupPath: GroupPath_;
+  functionName: FunctionName;
+}) =>
+  Context.GenericTag<FunctionImpl<GroupPath_, FunctionName>>(
+    `@confect/server/FunctionImpl/${groupPath}/${functionName}`,
+  );
+
+export const make = <
+  Api_ extends Api.AnyWithProps,
+  const GroupPath_ extends GroupPath.All<Api.Groups<Api_>>,
+  const FunctionName extends FunctionSpec.Name<
+    GroupSpec.Functions<GroupPath.GroupAt<Api.Groups<Api_>, GroupPath_>>
+  >,
+>(
+  api: Api_,
+  groupPath: GroupPath_,
+  functionName: FunctionName,
+  handler: Handler.WithName<
+    Api.Schema<Api_>,
+    GroupSpec.Functions<GroupPath.GroupAt<Api.Groups<Api_>, GroupPath_>>,
+    FunctionName
+  >,
+): Layer.Layer<FunctionImpl<GroupPath_, FunctionName>> => {
+  const groupPathParts = String.split(groupPath, ".");
+  const [firstGroupPathPart, ...restGroupPathParts] = groupPathParts;
+
+  const group_: GroupSpec.AnyWithProps = Array.reduce(
+    restGroupPathParts,
+    (api as any).spec.groups[firstGroupPathPart as any]!,
+    (currentGroup: any, groupPathPart: any) =>
+      currentGroup.groups[groupPathPart],
+  );
+
+  const function_ = group_.functions[functionName]!;
+
+  return Layer.effect(
+    FunctionImpl<GroupPath_, FunctionName>({
+      groupPath,
+      functionName,
+    }),
+    Effect.gen(function* () {
+      const registry = yield* Registry.Registry;
+
+      yield* Ref.update(registry, (registryItems) =>
+        setNestedProperty(
+          registryItems,
+          [...groupPathParts, functionName],
+          RegistryItem.make({
+            function_,
+            handler: handler as Handler.AnyWithProps,
+          }),
+        ),
+      );
+
+      return {
+        groupPath,
+        functionName,
+      };
+    }),
+  );
+};
+
+/**
+ * Get the function implementation service type for a specific group path and function name.
+ */
+export type ForGroupPathAndFunction<
+  GroupPath_ extends string,
+  FunctionName extends string,
+> = FunctionImpl<GroupPath_, FunctionName>;
+
+/**
+ * Get all function implementation services required for a group at a given path.
+ */
+export type FromGroupAtPath<
+  GroupPath_ extends string,
+  Group extends GroupSpec.AnyWithProps,
+> =
+  GroupPath.GroupAt<Group, GroupPath_> extends infer GroupAtPath extends
+    GroupSpec.AnyWithProps
+    ? FunctionSpec.Name<
+        GroupSpec.Functions<GroupAtPath>
+      > extends infer FunctionNames extends string
+      ? FunctionNames extends string
+        ? FunctionImpl<GroupPath_, FunctionNames>
+        : never
+      : never
+    : never;

package/src/GroupImpl.ts

@@ -0,0 +1,60 @@
+import type * as GroupPath from "@confect/core/GroupPath";
+import type * as GroupSpec from "@confect/core/GroupSpec";
+import { Context, Layer } from "effect";
+import type * as Api from "./Api";
+import type * as FunctionImpl from "./FunctionImpl";
+
+export interface GroupImpl<GroupPath_ extends string> {
+  readonly groupPath: GroupPath_;
+}
+
+export const GroupImpl = <GroupPath_ extends string>({
+  groupPath,
+}: {
+  groupPath: GroupPath_;
+}) =>
+  Context.GenericTag<GroupImpl<GroupPath_>>(
+    `@confect/server/GroupImpl/${groupPath}`,
+  );
+
+export const make = <
+  Api_ extends Api.AnyWithProps,
+  const GroupPath_ extends GroupPath.All<Api.Groups<Api_>>,
+>(
+  _api: Api_,
+  groupPath: GroupPath_,
+): Layer.Layer<
+  GroupImpl<GroupPath_>,
+  never,
+  | FromGroupWithPath<GroupPath_, Api.Groups<Api_>>
+  | FunctionImpl.FromGroupAtPath<GroupPath_, Api.Groups<Api_>>
+> =>
+  Layer.succeed(
+    GroupImpl<GroupPath_>({
+      groupPath,
+    }),
+    {
+      groupPath,
+    },
+  ) as Layer.Layer<
+    GroupImpl<GroupPath_>,
+    never,
+    | FromGroupWithPath<GroupPath_, Api.Groups<Api_>>
+    | FunctionImpl.FromGroupAtPath<GroupPath_, Api.Groups<Api_>>
+  >;
+
+export type FromGroups<Groups extends GroupSpec.Any> = Groups extends never
+  ? never
+  : Groups extends GroupSpec.AnyWithProps
+    ? GroupImpl<GroupSpec.Name<Groups>>
+    : never;
+
+export type FromGroupWithPath<
+  GroupPath_ extends string,
+  Group extends GroupSpec.AnyWithProps,
+> =
+  GroupPath.SubGroupsAt<Group, GroupPath_> extends infer SubGroupPaths
+    ? SubGroupPaths extends string
+      ? GroupImpl<SubGroupPaths>
+      : never
+    : never;

package/src/Handler.ts

@@ -0,0 +1,105 @@
+import type { FunctionSpec } from "@confect/core";
+import type { Effect } from "effect";
+import type * as ActionCtx from "./ActionCtx";
+import type * as ActionRunner from "./ActionRunner";
+import type * as Auth from "./Auth";
+import type * as DatabaseReader from "./DatabaseReader";
+import type * as DatabaseSchema from "./DatabaseSchema";
+import type * as DatabaseWriter from "./DatabaseWriter";
+import type * as DataModel from "./DataModel";
+import type * as MutationCtx from "./MutationCtx";
+import type * as MutationRunner from "./MutationRunner";
+import type * as QueryCtx from "./QueryCtx";
+import type * as QueryRunner from "./QueryRunner";
+import type * as Scheduler from "./Scheduler";
+import type {
+  StorageActionWriter,
+  StorageReader,
+  StorageWriter,
+} from "./Storage";
+import type * as VectorSearch from "./VectorSearch";
+
+export type Handler<
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+  FunctionSpec_ extends FunctionSpec.AnyWithProps,
+> =
+  FunctionSpec_ extends FunctionSpec.WithFunctionType<FunctionSpec_, "query">
+    ? Query<DatabaseSchema_, FunctionSpec_>
+    : FunctionSpec_ extends FunctionSpec.WithFunctionType<
+          FunctionSpec_,
+          "mutation"
+        >
+      ? Mutation<DatabaseSchema_, FunctionSpec_>
+      : FunctionSpec_ extends FunctionSpec.WithFunctionType<
+            FunctionSpec_,
+            "action"
+          >
+        ? Action<DatabaseSchema_, FunctionSpec_>
+        : never;
+
+export type Query<
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+  FunctionSpec_ extends FunctionSpec.AnyWithPropsWithFunctionType<"query">,
+> = Base<
+  FunctionSpec_,
+  | DatabaseReader.DatabaseReader<DatabaseSchema_>
+  | Auth.Auth
+  | StorageReader
+  | QueryRunner.QueryRunner
+  | QueryCtx.QueryCtx<DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>>
+>;
+
+export type Mutation<
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+  FunctionSpec_ extends FunctionSpec.AnyWithPropsWithFunctionType<"mutation">,
+> = Base<
+  FunctionSpec_,
+  | DatabaseReader.DatabaseReader<DatabaseSchema_>
+  | DatabaseWriter.DatabaseWriter<DatabaseSchema_>
+  | Auth.Auth
+  | Scheduler.Scheduler
+  | StorageReader
+  | StorageWriter
+  | QueryRunner.QueryRunner
+  | MutationRunner.MutationRunner
+  | MutationCtx.MutationCtx<
+      DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
+    >
+>;
+
+export type Action<
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+  FunctionSpec_ extends FunctionSpec.AnyWithPropsWithFunctionType<"action">,
+> = Base<
+  FunctionSpec_,
+  | Scheduler.Scheduler
+  | Auth.Auth
+  | StorageReader
+  | StorageWriter
+  | StorageActionWriter
+  | QueryRunner.QueryRunner
+  | MutationRunner.MutationRunner
+  | ActionRunner.ActionRunner
+  | VectorSearch.VectorSearch<DataModel.FromSchema<DatabaseSchema_>>
+  | ActionCtx.ActionCtx<
+      DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
+    >
+>;
+
+type Base<FunctionSpec_ extends FunctionSpec.AnyWithProps, R> = (
+  args: FunctionSpec.Args<FunctionSpec_>["Type"],
+) => Effect.Effect<FunctionSpec.Returns<FunctionSpec_>["Type"], never, R>;
+
+export type AnyWithProps = Handler<
+  DatabaseSchema.AnyWithProps,
+  FunctionSpec.AnyWithProps
+>;
+
+export type WithName<
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+  FunctionSpec_ extends FunctionSpec.AnyWithProps,
+  FunctionName extends string,
+> = Handler<
+  DatabaseSchema_,
+  FunctionSpec.WithName<FunctionSpec_, FunctionName>
+>;

package/src/HttpApi.ts

@@ -0,0 +1,232 @@
+import {
+  type HttpApi,
+  HttpApiBuilder,
+  HttpApiScalar,
+  type HttpApp,
+  type HttpRouter,
+  HttpServer,
+} from "@effect/platform";
+import {
+  type HttpRouter as ConvexHttpRouter,
+  type GenericActionCtx,
+  type GenericDataModel,
+  httpActionGeneric,
+  httpRouter,
+  ROUTABLE_HTTP_METHODS,
+  type RouteSpecWithPathPrefix,
+} from "convex/server";
+import { Array, Layer, pipe, Record } from "effect";
+import * as ActionRunner from "./ActionRunner";
+import * as Auth from "./Auth";
+import * as MutationRunner from "./MutationRunner";
+import * as QueryRunner from "./QueryRunner";
+import * as Scheduler from "./Scheduler";
+import { StorageActionWriter, StorageReader, StorageWriter } from "./Storage";
+import * as ActionCtx from "./ActionCtx";
+
+type Middleware = (
+  httpApp: HttpApp.Default,
+) => HttpApp.Default<
+  never,
+  HttpApi.Api | HttpApiBuilder.Router | HttpRouter.HttpRouter.DefaultServices
+>;
+
+const makeHandler =
+  <DataModel extends GenericDataModel>({
+    pathPrefix,
+    apiLive,
+    middleware,
+    scalar,
+  }: {
+    pathPrefix: RoutePath;
+    apiLive: Layer.Layer<
+      HttpApi.Api,
+      never,
+      | QueryRunner.QueryRunner
+      | MutationRunner.MutationRunner
+      | ActionRunner.ActionRunner
+      | Scheduler.Scheduler
+      | Auth.Auth
+      | StorageReader
+      | StorageWriter
+      | StorageActionWriter
+      | GenericActionCtx<DataModel>
+    >;
+    middleware?: Middleware;
+    scalar?: HttpApiScalar.ScalarConfig;
+  }) =>
+  (ctx: GenericActionCtx<DataModel>, request: Request): Promise<Response> => {
+    const ApiLive = apiLive.pipe(
+      Layer.provide(
+        Layer.mergeAll(
+          QueryRunner.layer(ctx.runQuery),
+          MutationRunner.layer(ctx.runMutation),
+          ActionRunner.layer(ctx.runAction),
+          Scheduler.layer(ctx.scheduler),
+          Auth.layer(ctx.auth),
+          StorageReader.layer(ctx.storage),
+          StorageWriter.layer(ctx.storage),
+          StorageActionWriter.layer(ctx.storage),
+          Layer.succeed(ActionCtx.ActionCtx<DataModel>(), ctx),
+        ),
+      ),
+    );
+
+    const ApiDocsLive = HttpApiScalar.layer({
+      path: `${pathPrefix}docs`,
+      scalar: {
+        baseServerURL: `${process.env["CONVEX_SITE_URL"]}${pathPrefix}`,
+        ...scalar,
+      },
+    }).pipe(Layer.provide(ApiLive));
+
+    const EnvLive = Layer.mergeAll(
+      ApiLive,
+      ApiDocsLive,
+      HttpServer.layerContext,
+    );
+
+    const { handler } = HttpApiBuilder.toWebHandler(
+      EnvLive,
+      middleware ? { middleware } : {},
+    );
+
+    return handler(request);
+  };
+
+const makeHttpAction = <DataModel extends GenericDataModel>({
+  pathPrefix,
+  apiLive,
+  middleware,
+  scalar,
+}: {
+  pathPrefix: RoutePath;
+  apiLive: Layer.Layer<
+    HttpApi.Api,
+    never,
+    | QueryRunner.QueryRunner
+    | MutationRunner.MutationRunner
+    | ActionRunner.ActionRunner
+    | Scheduler.Scheduler
+    | Auth.Auth
+    | StorageReader
+    | StorageWriter
+    | StorageActionWriter
+    | GenericActionCtx<DataModel>
+  >;
+  middleware?: Middleware;
+  scalar?: HttpApiScalar.ScalarConfig;
+}) =>
+  httpActionGeneric(
+    makeHandler<DataModel>({
+      pathPrefix,
+      apiLive,
+      ...(middleware ? { middleware } : {}),
+      ...(scalar ? { scalar } : {}),
+    }) as unknown as (
+      ctx: GenericActionCtx<GenericDataModel>,
+      request: Request,
+    ) => Promise<Response>,
+  );
+
+export type HttpApi_ = {
+  apiLive: Layer.Layer<
+    HttpApi.Api,
+    never,
+    | QueryRunner.QueryRunner
+    | MutationRunner.MutationRunner
+    | ActionRunner.ActionRunner
+    | Scheduler.Scheduler
+    | Auth.Auth
+    | StorageReader
+    | StorageWriter
+    | StorageActionWriter
+  >;
+  middleware?: Middleware;
+  scalar?: HttpApiScalar.ScalarConfig;
+};
+
+export type RoutePath = "/" | `/${string}/`;
+
+const mountEffectHttpApi =
+  <DataModel extends GenericDataModel>({
+    pathPrefix,
+    apiLive,
+    middleware,
+    scalar,
+  }: {
+    pathPrefix: RoutePath;
+    apiLive: Layer.Layer<
+      HttpApi.Api,
+      never,
+      | QueryRunner.QueryRunner
+      | MutationRunner.MutationRunner
+      | ActionRunner.ActionRunner
+      | Scheduler.Scheduler
+      | Auth.Auth
+      | StorageReader
+      | StorageWriter
+      | StorageActionWriter
+      | GenericActionCtx<DataModel>
+    >;
+    middleware?: Middleware;
+    scalar?: HttpApiScalar.ScalarConfig;
+  }) =>
+  (convexHttpRouter: ConvexHttpRouter): ConvexHttpRouter => {
+    const handler = makeHttpAction<DataModel>({
+      pathPrefix,
+      apiLive,
+      ...(middleware ? { middleware } : {}),
+      ...(scalar ? { scalar } : {}),
+    });
+
+    Array.forEach(ROUTABLE_HTTP_METHODS, (method) => {
+      const routeSpec: RouteSpecWithPathPrefix = {
+        pathPrefix,
+        method,
+        handler,
+      };
+      convexHttpRouter.route(routeSpec);
+    });
+
+    return convexHttpRouter;
+  };
+
+type HttpApis = Partial<Record<RoutePath, HttpApi_>>;
+
+export const make = (httpApis: HttpApis): ConvexHttpRouter => {
+  applyMonkeyPatches();
+
+  return pipe(
+    httpApis as Record<RoutePath, HttpApi_>,
+    Record.toEntries,
+    Array.reduce(
+      httpRouter(),
+      (convexHttpRouter, [pathPrefix, { apiLive, middleware, scalar }]) =>
+        mountEffectHttpApi({
+          pathPrefix: pathPrefix as RoutePath,
+          apiLive,
+          ...(middleware ? { middleware } : {}),
+          ...(scalar ? { scalar } : {}),
+        })(convexHttpRouter),
+    ),
+  );
+};
+
+const applyMonkeyPatches = () => {
+  // These are necessary until the Convex runtime supports these APIs. See https://discord.com/channels/1019350475847499849/1281364098419785760
+
+  // eslint-disable-next-line no-global-assign
+  URL = class extends URL {
+    override get username() {
+      return "";
+    }
+    override get password() {
+      return "";
+    }
+  };
+
+  Object.defineProperty(Request.prototype, "signal", {
+    get: () => new AbortSignal(),
+  });
+};

package/src/Impl.ts

@@ -0,0 +1,57 @@
+import { Context, Effect, Layer, Predicate } from "effect";
+import type * as Api from "./Api";
+import type { Groups as ApiGroups } from "./Api";
+import type * as GroupImpl from "./GroupImpl";
+
+export const TypeId = "@confect/server/Impl";
+export type TypeId = typeof TypeId;
+
+export const isImpl = (u: unknown): u is AnyWithProps =>
+  Predicate.hasProperty(u, TypeId);
+
+export interface Impl<
+  Api_ extends Api.AnyWithProps,
+  FinalizationStatus_ extends FinalizationStatus,
+> {
+  readonly [TypeId]: TypeId;
+  readonly api: Api_;
+  readonly finalizationStatus: FinalizationStatus_;
+}
+
+export type FinalizationStatus = "Unfinalized" | "Finalized";
+
+export interface AnyWithProps
+  extends Impl<Api.AnyWithProps, FinalizationStatus> {}
+
+export const Impl = <
+  Api_ extends Api.AnyWithProps,
+  FinalizationStatus_ extends FinalizationStatus,
+>() =>
+  Context.GenericTag<Impl<Api_, FinalizationStatus_>>(`@confect/server/Impl`);
+
+export const make = <Api_ extends Api.AnyWithProps>(
+  api: Api_,
+): Layer.Layer<
+  Impl<Api_, "Unfinalized">,
+  never,
+  GroupImpl.FromGroups<ApiGroups<Api_>>
+> =>
+  Layer.effect(
+    Impl<Api_, "Unfinalized">(),
+    Effect.succeed({
+      [TypeId]: TypeId,
+      api,
+      finalizationStatus: "Unfinalized" as const,
+    }),
+  );
+
+export const finalize = <Api_ extends Api.AnyWithProps>(
+  impl: Layer.Layer<Impl<Api_, "Unfinalized">>,
+): Layer.Layer<Impl<Api_, "Finalized">> =>
+  Layer.map(impl, (context) =>
+    Context.make(Impl<Api_, "Finalized">(), {
+      [TypeId]: TypeId,
+      api: Context.get(context, Impl<Api_, "Unfinalized">()).api,
+      finalizationStatus: "Finalized",
+    }),
+  );

package/src/MutationCtx.ts

@@ -0,0 +1,11 @@
+import type { GenericDataModel, GenericMutationCtx } from "convex/server";
+import { Context } from "effect";
+
+export const MutationCtx = <DataModel extends GenericDataModel>() =>
+  Context.GenericTag<GenericMutationCtx<DataModel>>(
+    "@confect/server/MutationCtx",
+  );
+
+export type MutationCtx<DataModel extends GenericDataModel> = ReturnType<
+  typeof MutationCtx<DataModel>
+>["Identifier"];

package/src/MutationRunner.ts

@@ -0,0 +1,41 @@
+import * as Ref from "@confect/core/Ref";
+import { type GenericMutationCtx } from "convex/server";
+import { Context, Effect, Layer, Schema } from "effect";
+
+const makeMutationRunner =
+  (runMutation: GenericMutationCtx<any>["runMutation"]) =>
+  <Mutation extends Ref.AnyMutation>(
+    mutation: Mutation,
+    args: Ref.Args<Mutation>["Type"],
+  ) =>
+    Effect.gen(function* () {
+      const function_ = Ref.getFunction(mutation);
+      const functionName = Ref.getConvexFunctionName(mutation);
+
+      const encodedArgs = yield* Schema.encode(function_.args)(args);
+      const encodedReturns = yield* Effect.promise(() =>
+        runMutation(functionName as any, encodedArgs),
+      );
+      return yield* Schema.decode(function_.returns)(encodedReturns);
+    });
+
+export const MutationRunner = Context.GenericTag<
+  ReturnType<typeof makeMutationRunner>
+>("@confect/server/MutationRunner");
+export type MutationRunner = typeof MutationRunner.Identifier;
+
+export const layer = (runMutation: GenericMutationCtx<any>["runMutation"]) =>
+  Layer.succeed(MutationRunner, makeMutationRunner(runMutation));
+
+export class MutationRollback extends Schema.TaggedError<MutationRollback>(
+  "MutationRollback",
+)("MutationRollback", {
+  mutationName: Schema.String,
+  error: Schema.Unknown,
+}) {
+  /* v8 ignore start */
+  override get message(): string {
+    return `Mutation ${this.mutationName} failed and was rolled back.\n\n${this.error}`;
+  }
+  /* v8 ignore stop */
+}