@gaganref/confect-server 0.0.0-stage → 10.3.1-fork.10

package/src/ComponentCtx.ts

@@ -0,0 +1,192 @@
+import type * as IdScope from "@confect/core/IdScope";
+import type { GenericId, Rebase } from "@confect/core/GenericId";
+import type {
+  DocumentByName,
+  GenericActionCtx,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  QueryInitializer,
+  NamedTableInfo,
+  TableNamesInDataModel,
+  SystemDataModel,
+  WithoutSystemFields,
+  WithOptionalSystemFields,
+  SchedulableFunctionReference,
+  OptionalRestArgs,
+  VectorIndexNames,
+  VectorSearchQuery,
+} from "convex/server";
+import type { PatchValue } from "./DatabaseWriter.js";
+
+/**
+ * Distinguishes raw component services from structurally compatible app ctxs.
+ */
+export interface Identifier<
+  Kind extends string,
+  DataModel,
+  Scope extends IdScope.IdScope,
+> {
+  readonly "~@confect/server/ComponentCtx": {
+    readonly kind: Kind;
+    readonly dataModel: DataModel;
+    readonly scope: Scope;
+  };
+}
+
+interface Reader<
+  DataModel extends GenericDataModel,
+  Scope extends IdScope.IdScope,
+> {
+  get<TableName extends TableNamesInDataModel<DataModel>>(
+    table: TableName,
+    id: GenericId<NoInfer<TableName>, Scope>,
+  ): Promise<DocumentByName<DataModel, TableName> | null>;
+  get<TableName extends TableNamesInDataModel<DataModel>>(
+    id: GenericId<TableName, Scope>,
+  ): Promise<DocumentByName<DataModel, TableName> | null>;
+  normalizeId<TableName extends TableNamesInDataModel<DataModel>>(
+    table: TableName,
+    id: string,
+  ): GenericId<TableName, Scope> | null;
+  query<TableName extends TableNamesInDataModel<DataModel>>(
+    table: TableName,
+  ): QueryInitializer<NamedTableInfo<DataModel, TableName>>;
+}
+
+type ScopedSystem<Scope extends IdScope.IdScope> = Rebase<
+  SystemDataModel,
+  IdScope.App,
+  Scope
+>;
+
+export interface DatabaseReader<
+  DataModel extends GenericDataModel,
+  Scope extends IdScope.IdScope,
+> extends Reader<DataModel, Scope> {
+  readonly system: Reader<ScopedSystem<Scope>, Scope>;
+}
+
+export interface DatabaseWriter<
+  DataModel extends GenericDataModel,
+  Scope extends IdScope.IdScope,
+> extends DatabaseReader<DataModel, Scope> {
+  insert<TableName extends TableNamesInDataModel<DataModel>>(
+    table: TableName,
+    value: WithoutSystemFields<DocumentByName<DataModel, TableName>>,
+  ): Promise<GenericId<TableName, Scope>>;
+  patch<TableName extends TableNamesInDataModel<DataModel>>(
+    table: TableName,
+    id: GenericId<NoInfer<TableName>, Scope>,
+    value: PatchValue<
+      WithoutSystemFields<DocumentByName<DataModel, TableName>>
+    >,
+  ): Promise<void>;
+  patch<TableName extends TableNamesInDataModel<DataModel>>(
+    id: GenericId<TableName, Scope>,
+    value: PatchValue<
+      WithoutSystemFields<DocumentByName<DataModel, TableName>>
+    >,
+  ): Promise<void>;
+  replace<TableName extends TableNamesInDataModel<DataModel>>(
+    table: TableName,
+    id: GenericId<NoInfer<TableName>, Scope>,
+    value: WithOptionalSystemFields<DocumentByName<DataModel, TableName>>,
+  ): Promise<void>;
+  replace<TableName extends TableNamesInDataModel<DataModel>>(
+    id: GenericId<TableName, Scope>,
+    value: WithOptionalSystemFields<DocumentByName<DataModel, TableName>>,
+  ): Promise<void>;
+  delete<TableName extends TableNamesInDataModel<DataModel>>(
+    table: TableName,
+    id: GenericId<NoInfer<TableName>, Scope>,
+  ): Promise<void>;
+  delete<TableName extends TableNamesInDataModel<DataModel>>(
+    id: GenericId<TableName, Scope>,
+  ): Promise<void>;
+}
+
+export interface StorageReader<Scope extends IdScope.IdScope> {
+  getUrl(id: GenericId<"_storage", Scope>): Promise<string | null>;
+  getMetadata(
+    id: GenericId<"_storage", Scope>,
+  ): Promise<
+    Rebase<
+      Awaited<
+        ReturnType<GenericQueryCtx<GenericDataModel>["storage"]["getMetadata"]>
+      >,
+      IdScope.App,
+      Scope
+    >
+  >;
+}
+
+export interface StorageWriter<
+  Scope extends IdScope.IdScope,
+> extends StorageReader<Scope> {
+  generateUploadUrl(): Promise<string>;
+  delete(id: GenericId<"_storage", Scope>): Promise<void>;
+}
+
+export interface StorageActionWriter<
+  Scope extends IdScope.IdScope,
+> extends StorageWriter<Scope> {
+  get(id: GenericId<"_storage", Scope>): Promise<Blob | null>;
+  store(
+    blob: Blob,
+    options?: { sha256?: string },
+  ): Promise<GenericId<"_storage", Scope>>;
+}
+
+export interface Scheduler<Scope extends IdScope.IdScope> {
+  runAfter<FunctionReference extends SchedulableFunctionReference>(
+    delayMs: number,
+    ref: FunctionReference,
+    ...args: OptionalRestArgs<FunctionReference>
+  ): Promise<GenericId<"_scheduled_functions", Scope>>;
+  runAt<FunctionReference extends SchedulableFunctionReference>(
+    timestamp: number | Date,
+    ref: FunctionReference,
+    ...args: OptionalRestArgs<FunctionReference>
+  ): Promise<GenericId<"_scheduled_functions", Scope>>;
+  cancel(id: GenericId<"_scheduled_functions", Scope>): Promise<void>;
+}
+
+export type Query<
+  DataModel extends GenericDataModel,
+  Scope extends IdScope.IdScope,
+> = Omit<GenericQueryCtx<DataModel>, "auth" | "db" | "storage"> & {
+  readonly db: DatabaseReader<DataModel, Scope>;
+  readonly storage: StorageReader<Scope>;
+};
+
+export type Mutation<
+  DataModel extends GenericDataModel,
+  Scope extends IdScope.IdScope,
+> = Omit<
+  GenericMutationCtx<DataModel>,
+  "auth" | "db" | "storage" | "scheduler"
+> & {
+  readonly db: DatabaseWriter<DataModel, Scope>;
+  readonly storage: StorageWriter<Scope>;
+  readonly scheduler: Scheduler<Scope>;
+};
+
+export type Action<
+  DataModel extends GenericDataModel,
+  Scope extends IdScope.IdScope,
+> = Omit<
+  GenericActionCtx<DataModel>,
+  "auth" | "storage" | "vectorSearch" | "scheduler"
+> & {
+  readonly storage: StorageActionWriter<Scope>;
+  readonly scheduler: Scheduler<Scope>;
+  readonly vectorSearch: <
+    TableName extends TableNamesInDataModel<DataModel>,
+    IndexName extends VectorIndexNames<NamedTableInfo<DataModel, TableName>>,
+  >(
+    table: TableName,
+    index: IndexName,
+    query: VectorSearchQuery<NamedTableInfo<DataModel, TableName>, IndexName>,
+  ) => Promise<Array<{ _id: GenericId<TableName, Scope>; _score: number }>>;
+};

package/src/ConvexConfigProvider.ts

@@ -0,0 +1,39 @@
+import { pipe } from "effect/Function";
+import * as Array from "effect/Array";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+declare const process: { env: Record<string, string | undefined> };
+
+/**
+ * A `ConfigProvider` that reads configuration directly from `process.env` by
+ * exact path lookup.
+ *
+ * The Convex runtime exposes `process.env` for direct key access but does not
+ * make it enumerable, so the built-in `ConfigProvider.fromEnv` (which builds a
+ * trie over the environment to resolve and enumerate config paths) cannot be
+ * used. This provider resolves each requested path to a single environment
+ * variable, joining the path segments with `"_"` to match the key convention
+ * `fromEnv` uses. As with the built-in providers, an empty string is treated as
+ * a missing value, so `Config.withDefault` and `Config.option` recover from
+ * it.
+ */
+export const make = (): ConfigProvider.ConfigProvider =>
+  ConfigProvider.make((path) => {
+    const value = process.env[pipe(path, Array.map(String), Array.join("_"))];
+
+    return Effect.succeed(
+      value === undefined || value === ""
+        ? undefined
+        : ConfigProvider.makeValue(value),
+    );
+  });
+
+/**
+ * Installs the Convex-aware `ConfigProvider` as the ambient provider.
+ */
+export const layer: Layer.Layer<never> = Layer.succeed(
+  ConfigProvider.ConfigProvider,
+  make(),
+);

package/src/ConvexFunctionDefinitions.ts

@@ -0,0 +1,91 @@
+import type * as Layer from "effect/Layer";
+import * as Match from "effect/Match";
+import * as Record from "effect/Record";
+import type * as GroupSpec from "@confect/core/GroupSpec";
+import type * as FunctionSpec from "@confect/core/FunctionSpec";
+import type * as DatabaseSchema from "./DatabaseSchema.js";
+import type * as GroupImpl from "./GroupImpl.js";
+import * as GroupRegistry from "./GroupRegistry.js";
+import * as FunctionRegistryItem from "./FunctionRegistryItem.js";
+import * as RegisteredConvexFunction from "./RegisteredConvexFunction.js";
+import type * as RegisteredFunctions from "./RegisteredFunctions.js";
+import * as ResolvedMiddleware from "./ResolvedMiddleware.js";
+import { mapLeaves } from "./internal/utils.js";
+
+export interface Definitions {
+  readonly [name: string]: RegisteredConvexFunction.Definition | Definitions;
+}
+
+type DefinitionTag<
+  Function extends FunctionSpec.AnyWithProps,
+  Provenance = Function["functionProvenance"],
+> = Provenance extends { readonly _tag: "Convex" }
+  ? "Registered"
+  : `${Capitalize<Function["functionVisibility"]>}${Capitalize<Function["runtimeAndFunctionType"]["functionType"]>}`;
+
+export type ForGroup<Group extends GroupSpec.AnyWithProps> = {
+  readonly [Name in FunctionSpec.Name<GroupSpec.Functions<Group>>]: Extract<
+    RegisteredConvexFunction.Definition,
+    {
+      readonly _tag: DefinitionTag<
+        FunctionSpec.WithName<GroupSpec.Functions<Group>, Name>
+      >;
+    }
+  >;
+} & {
+  readonly [Name in GroupSpec.Name<GroupSpec.Groups<Group>>]: ForGroup<
+    GroupSpec.WithName<GroupSpec.Groups<Group>, Name>
+  >;
+};
+
+export const isDefinition = (
+  value: RegisteredConvexFunction.Definition | Definitions,
+): value is RegisteredConvexFunction.Definition =>
+  typeof value._tag === "string";
+
+const registerDefinitions = (
+  definitions: Definitions,
+): RegisteredFunctions.AnyWithProps =>
+  Record.map(definitions, (value) =>
+    isDefinition(value)
+      ? RegisteredConvexFunction.register(value)
+      : registerDefinitions(value),
+  );
+
+export const register = <Group extends GroupSpec.AnyWithProps>(
+  definitions: Definitions,
+): RegisteredFunctions.RegisteredFunctionsForGroupSpec<Group> =>
+  registerDefinitions(
+    definitions,
+  ) as RegisteredFunctions.RegisteredFunctionsForGroupSpec<Group>;
+
+export const buildForGroup = <Group extends GroupSpec.AnyWithProps>(
+  databaseSchema: DatabaseSchema.AnyWithProps,
+  groupLayer: Layer.Layer<GroupImpl.GroupImpl<"Finalized">>,
+): ForGroup<Group> => {
+  const { functionRegistryItems, middlewareRegistryItems } =
+    GroupRegistry.make(groupLayer);
+  return mapLeaves<
+    FunctionRegistryItem.AnyWithProps,
+    RegisteredConvexFunction.Definition
+  >(
+    functionRegistryItems as {
+      [key: string]: FunctionRegistryItem.AnyWithProps;
+    },
+    FunctionRegistryItem.isFunctionRegistryItem,
+    (item) =>
+      Match.value(item).pipe(
+        Match.tag("Convex", ({ handler }) =>
+          RegisteredConvexFunction.Definition.Registered({ handler }),
+        ),
+        Match.tag("Confect", (confect) =>
+          RegisteredConvexFunction.prepare(
+            databaseSchema,
+            confect,
+            ResolvedMiddleware.resolve(confect, middlewareRegistryItems),
+          ),
+        ),
+        Match.exhaustive,
+      ),
+  ) as ForGroup<Group>;
+};

package/src/ConvexLogger.ts

@@ -0,0 +1,43 @@
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as Match from "effect/Match";
+
+/**
+ * Writes structured Effect logs through Convex's severity-aware console
+ * methods. Trace and Debug use `console.debug`, Info uses `console.info`, Warn
+ * uses `console.warn`, and Error and Fatal use `console.error`. The payload
+ * retains the original Effect level, cause, annotations, spans, timestamp, and
+ * fiber ID.
+ */
+export const logger: Logger.Logger<unknown, void> = Logger.make((options) => {
+  const console = options.fiber.getRef(Console.Console);
+  const output = Logger.formatStructured.log(options);
+  return Match.value(options.logLevel).pipe(
+    Match.whenOr("Trace", "Debug", () => console.debug(output)),
+    Match.when("Info", () => console.info(output)),
+    Match.when("Warn", () => console.warn(output)),
+    Match.whenOr("Error", "Fatal", () => console.error(output)),
+    Match.whenOr("All", "None", () => console.log(output)),
+    Match.exhaustive,
+  );
+});
+
+/**
+ * Replaces Effect's default console logger without changing custom loggers,
+ * tracing, or the minimum log level. Confect installs this layer automatically
+ * for function handlers and HTTP routes.
+ */
+export const layer: Layer.Layer<never> = Layer.effect(
+  Logger.CurrentLoggers,
+  Effect.map(
+    Logger.CurrentLoggers,
+    (loggers) =>
+      new Set(
+        Array.from(loggers, (current) =>
+          current === Logger.defaultLogger ? logger : current,
+        ),
+      ),
+  ),
+);

package/src/CronJob.ts

@@ -0,0 +1,42 @@
+import type { Ref } from "@confect/core";
+import type { Cron, Duration } from "effect";
+import * as Predicate from "effect/Predicate";
+
+export const TypeId = "~@confect/server/CronJob";
+export type TypeId = typeof TypeId;
+
+export interface CronJob {
+  readonly [TypeId]: TypeId;
+
+  readonly identifier: string;
+  readonly schedule: Cron.Cron | Duration.Duration;
+  readonly ref: Ref.AnyMutation | Ref.AnyAction;
+  readonly args: Record<string, unknown>;
+}
+
+export const isCronJob = (u: unknown): u is CronJob =>
+  Predicate.hasProperty(u, TypeId);
+
+const Proto = {
+  [TypeId]: TypeId,
+};
+
+const makeProto = (
+  identifier: string,
+  schedule: Cron.Cron | Duration.Duration,
+  ref: Ref.AnyMutation | Ref.AnyAction,
+  args: Record<string, unknown>,
+): CronJob =>
+  Object.assign(Object.create(Proto), {
+    identifier,
+    schedule,
+    ref,
+    args,
+  });
+
+export const make = <R extends Ref.AnyMutation | Ref.AnyAction>(
+  identifier: string,
+  schedule: Cron.Cron | Duration.Duration,
+  ref: R,
+  ...args: Ref.OptionalArgs<R>
+): CronJob => makeProto(identifier, schedule, ref, args[0] ?? {});

package/src/CronJobs.ts

@@ -0,0 +1,165 @@
+import { Ref } from "@confect/core";
+import type { CronJob as ConvexCronJob } from "convex/server";
+import { cronJobs as makeConvexCrons, type Crons } from "convex/server";
+import { pipe } from "effect/Function";
+import * as Array from "effect/Array";
+import * as Cron from "effect/Cron";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Match from "effect/Match";
+import * as Option from "effect/Option";
+import * as Order from "effect/Order";
+import * as Predicate from "effect/Predicate";
+import * as Record from "effect/Record";
+import type * as CronJob from "./CronJob.js";
+
+export const TypeId = "~@confect/server/CronJobs";
+export type TypeId = typeof TypeId;
+
+export interface CronJobs {
+  readonly [TypeId]: TypeId;
+  readonly cronJobs: Record<string, CronJob.CronJob>;
+  readonly convexCronJobs: Crons;
+
+  add(cron: CronJob.CronJob): CronJobs;
+}
+
+export const isCronJobs = (u: unknown): u is CronJobs =>
+  Predicate.hasProperty(u, TypeId);
+
+const Proto = {
+  [TypeId]: TypeId,
+
+  add(this: CronJobs, cronJob: CronJob.CronJob) {
+    const newConvexCrons = Object.assign(makeConvexCrons(), {
+      crons: { ...this.convexCronJobs.crons },
+    });
+
+    const functionReference = Ref.getFunctionReference(cronJob.ref);
+    const encodedArgs = Ref.encodeArgsSync(cronJob.ref, cronJob.args);
+
+    Match.value(cronJob.schedule).pipe(
+      Match.when(Cron.isCron, (cron) => {
+        newConvexCrons.cron(
+          cronJob.identifier,
+          cronToConvexCronString(cron),
+          functionReference,
+          encodedArgs,
+        );
+      }),
+      Match.when(Duration.isDuration, (duration) => {
+        newConvexCrons.interval(
+          cronJob.identifier,
+          durationToConvexIntervalSchedule(duration),
+          functionReference,
+          encodedArgs,
+        );
+      }),
+      Match.exhaustive,
+    );
+
+    return makeProto(
+      Record.set(this.cronJobs, cronJob.identifier, cronJob),
+      newConvexCrons,
+    );
+  },
+};
+
+const makeProto = (
+  cronJobs: Record<string, CronJob.CronJob>,
+  convexCronJobs: Crons,
+): CronJobs =>
+  Object.assign(Object.create(Proto), {
+    cronJobs,
+    convexCronJobs,
+  });
+
+export const make = (): CronJobs => makeProto({}, makeConvexCrons());
+
+export const cronToConvexCronString = (cron: Cron.Cron): string => {
+  pipe(
+    cron.tz,
+    Option.filter((tz) =>
+      pipe(
+        tz,
+        Match.value,
+        Match.tag("Offset", ({ offset }) => offset !== 0),
+        Match.tag("Named", ({ id }) => id !== "UTC" && id !== "Etc/UTC"),
+        Match.exhaustive,
+      ),
+    ),
+    Option.map((tz) => {
+      throw new Error(
+        `Convex cron expressions are always evaluated in UTC, but this cron ` +
+          `specifies the time zone "${DateTime.zoneToString(tz)}". ` +
+          `Either omit the timezone or specify UTC.`,
+      );
+    }),
+  );
+
+  const hasNonDefaultSeconds = cron.seconds.size !== 1 || !cron.seconds.has(0);
+  if (hasNonDefaultSeconds) {
+    throw new Error(
+      "Convex cron expressions do not support a seconds field. " +
+        "The seconds field must be the default {0}. " +
+        "Sub-minute scheduling is supported only by interval schedules defined using a Duration.",
+    );
+  }
+
+  return Array.join(
+    [
+      setToField(cron.minutes),
+      setToField(cron.hours),
+      setToField(cron.days),
+      setToField(cron.months),
+      setToField(cron.weekdays),
+    ],
+    " ",
+  );
+};
+
+const setToField = (set: ReadonlySet<number>): string => {
+  if (set.size === 0) return "*";
+  return pipe(
+    set,
+    Array.sort(Order.Number),
+    Array.map((n) => n.toString()),
+    Array.join(","),
+  );
+};
+
+export const durationToConvexIntervalSchedule = (
+  duration: Duration.Duration,
+): IntervalSchedule => {
+  const millis = Duration.toMillis(duration);
+  if (millis <= 0) {
+    throw new Error("Interval must be a positive duration.");
+  }
+
+  const oneHourInMillis = Duration.hours(1).pipe(Duration.toMillis);
+  const hours = millis / oneHourInMillis;
+  if (Number.isInteger(hours)) {
+    return { type: "interval", hours };
+  }
+
+  const oneMinuteInMillis = Duration.minutes(1).pipe(Duration.toMillis);
+  const minutes = millis / oneMinuteInMillis;
+  if (Number.isInteger(minutes)) {
+    return { type: "interval", minutes };
+  }
+
+  const oneSecondInMillis = Duration.seconds(1).pipe(Duration.toMillis);
+  const seconds = millis / oneSecondInMillis;
+  if (Number.isInteger(seconds)) {
+    return { type: "interval", seconds };
+  }
+
+  throw new Error(
+    "Interval must be a whole number of seconds, minutes, or hours.",
+  );
+};
+
+type IntervalSchedule = Extract<
+  ConvexCronJob["schedule"],
+  { type: "interval" }
+>;

package/src/DataModel.ts

@@ -0,0 +1,81 @@
+import type * as DatabaseSchema from "./DatabaseSchema.js";
+import type * as Table from "./Table.js";
+import type * as TableInfo from "./TableInfo.js";
+import type * as GenericId from "@confect/core/GenericId";
+
+export declare const TypeId: "~@confect/server/DataModel";
+export type TypeId = typeof TypeId;
+
+export interface DataModel<
+  Tables_ extends Readonly<Record<string, Table.AnyWithProps>>,
+> {
+  readonly [TypeId]: Readonly<Tables_>;
+}
+
+export interface Any {
+  readonly [TypeId]: unknown;
+}
+
+export interface AnyWithProps extends DataModel<
+  Readonly<Record<string, Table.AnyWithProps>>
+> {}
+
+export type FromSchema<Schema extends DatabaseSchema.AnyWithProps> = DataModel<
+  Schema[DatabaseSchema.TypeId]
+>;
+
+export type FromTables<Tables_ extends Table.AnyWithProps> = DataModel<
+  Table.TablesRecord<Tables_>
+>;
+
+export type ToConvex<DataModel_ extends AnyWithProps> = {
+  [TableName_ in TableNames<DataModel_>]: TableInfoWithName<
+    DataModel_,
+    TableName_
+  >;
+};
+
+export type Tables<DataModel_ extends AnyWithProps> =
+  DataModel_[TypeId][keyof DataModel_[TypeId]];
+
+export type TableNames<DataModel_ extends AnyWithProps> = Table.Name<
+  Tables<DataModel_>
+> &
+  string;
+
+export type TableWithName<
+  DataModel_ extends AnyWithProps,
+  TableName extends TableNames<DataModel_>,
+> = Table.WithName<Tables<DataModel_>, TableName>;
+
+export type TableInfoWithName_<
+  DataModel_ extends AnyWithProps,
+  TableName extends TableNames<DataModel_>,
+> = TableInfo.TableInfo<Table.WithName<Tables<DataModel_>, TableName>>;
+
+export type TableInfoWithName<
+  DataModel_ extends AnyWithProps,
+  TableName extends TableNames<DataModel_>,
+> = TableInfo.ConvexTableInfo<
+  TableInfo.TableInfo<Table.WithName<Tables<DataModel_>, TableName>>
+>;
+
+export type DocumentWithName<
+  DataModel_ extends AnyWithProps,
+  TableName extends TableNames<DataModel_>,
+> = TableInfo.Document<
+  TableInfo.TableInfo<Table.WithName<Tables<DataModel_>, TableName>>
+>;
+
+export type DocumentByName<
+  DataModel_ extends AnyWithProps,
+  TableName extends TableNames<DataModel_>,
+> = DocumentWithName<DataModel_, TableName>;
+
+export type Id<
+  DataModel_ extends AnyWithProps,
+  TableName extends TableNames<DataModel_>,
+> = GenericId.GenericId<
+  TableName,
+  Table.Scope<TableWithName<DataModel_, TableName>>
+>;