@gaganref/confect-server 10.3.1-fork.9 → 10.3.1-fork.91

package/src/MountInit.ts

@@ -0,0 +1,80 @@
+import * as Mount from "@confect/core/Mount";
+import { internalMutationGeneric } from "convex/server";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Callback from "./Callback.js";
+
+/**
+ * A mount the push visits: its `init`, if its component declares one, and
+ * whether its component lists mounts of its own.
+ */
+export interface Entry {
+  readonly mount: Mount.Any;
+  readonly nested: boolean;
+}
+
+/**
+ * What the push does at one mount, in order. A mount whose callback handles
+ * cannot be made ends the list with its failure, so no later mount runs.
+ */
+export type Step =
+  | {
+      readonly componentPath: string;
+      readonly nested: boolean;
+      readonly init: {
+        readonly functionName: string;
+        readonly args: unknown;
+      } | null;
+    }
+  | { readonly componentPath: string; readonly failure: string };
+
+const failure = (cause: Cause.Cause<unknown>) => {
+  const error = Cause.squash(cause);
+  return error instanceof Error ? error.message : String(error);
+};
+
+const step = (entry: Entry) =>
+  Mount.initCall(entry.mount, (contract, ref) =>
+    Callback.create(contract, ref as never),
+  ).pipe(
+    Effect.exit,
+    Effect.map((exit): Step =>
+      Exit.isSuccess(exit)
+        ? {
+            componentPath: Mount.data(entry.mount).name,
+            nested: entry.nested,
+            init: Option.match(exit.value, {
+              onNone: () => null,
+              onSome: ({ functionName, args }) => ({ functionName, args }),
+            }),
+          }
+        : {
+            componentPath: Mount.data(entry.mount).name,
+            failure: failure(exit.cause),
+          },
+    ),
+  );
+
+/**
+ * The internal mutation codegen writes to `convex/confectDeploy.ts`. It makes
+ * each mount's callback handles and returns the steps a push runs, in
+ * declaration order.
+ */
+export const mutation = (entries: ReadonlyArray<Entry>) =>
+  internalMutationGeneric({
+    args: {},
+    handler: () =>
+      Effect.runPromise(
+        Effect.gen(function* () {
+          const steps: Array<Step> = [];
+          for (const entry of entries) {
+            const next = yield* step(entry);
+            steps.push(next);
+            if ("failure" in next) break;
+          }
+          return steps;
+        }),
+      ),
+  });

package/src/MutationRunner.ts

@@ -1,4 +1,5 @@
-import * as Ref from "@confect/core/Ref";
+import * as ReservedArgument from "./internal/reservedArgument.js";
+import type * as Ref from "@confect/core/Ref";
 import type { GenericActionCtx } from "convex/server";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
@@ -46,7 +47,7 @@ const make = (nativeRunMutation: GenericActionCtx<any>["runMutation"]) => {
             yield* MutationTransactionContext.MutationTransactionContext;
           return yield* controls.runMutation(mutation, actualArgs, options);
         }
-        return yield* Ref.runWithCodec(
+        return yield* ReservedArgument.runWithCodec(
           mutation,
           actualArgs,
           (ref, encodedArgs) => nativeRunMutation(ref, encodedArgs),

package/src/MutationTransactionContext.ts

@@ -1,3 +1,4 @@
+import * as ReservedArgument from "./internal/reservedArgument.js";
 import * as Ref from "@confect/core/Ref";
 import type {
   AdvancedRunQueryOptions,
@@ -32,7 +33,7 @@ const make = (
       args: Ref.Args<Mutation>,
       options: MutationOptions,
     ) =>
-      Ref.runWithCodec(mutation, args, (ref, encodedArgs) =>
+      ReservedArgument.runWithCodec(mutation, args, (ref, encodedArgs) =>
         ctx.runMutation(ref, encodedArgs, options),
       ),
   ),

package/src/OfficialComponent.ts

@@ -0,0 +1,168 @@
+import * as Ref from "@confect/core/Ref";
+import { getFunctionReference } from "@confect/core/RefInternal";
+import type {
+  DefaultFunctionArgs,
+  GenericActionCtx,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+} from "convex/server";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as ActionCtx from "./ActionCtx.js";
+import type * as ActionRunner from "./ActionRunner.js";
+import * as MutationCtx from "./MutationCtx.js";
+import type * as MutationRunner from "./MutationRunner.js";
+import * as QueryCtx from "./QueryCtx.js";
+import type * as QueryRunner from "./QueryRunner.js";
+import * as ReservedArgument from "./internal/reservedArgument.js";
+
+/**
+ * An official component's method rejected. `cause` is the rejection as thrown.
+ */
+export class ComponentCallFailed extends Schema.TaggedError<ComponentCallFailed>()(
+  "ComponentCallFailed",
+  { component: Schema.String, method: Schema.String, cause: Schema.Defect() },
+) {}
+
+declare const unsupported: unique symbol;
+type Unsupported = typeof unsupported;
+type Needs<Param> = [GenericActionCtx<GenericDataModel>] extends [Param]
+  ? [GenericMutationCtx<GenericDataModel>] extends [Param]
+    ? [GenericQueryCtx<GenericDataModel>] extends [Param]
+      ? QueryRunner.QueryRunner
+      : MutationRunner.MutationRunner
+    : [GenericQueryCtx<GenericDataModel>] extends [Param]
+      ? Unsupported
+      : ActionRunner.ActionRunner
+  : Unsupported;
+
+type Method<Official> = {
+  [K in keyof Official & string]: Official[K] extends (
+    ctx: infer Ctx,
+    ...args: infer _Args
+  ) => Promise<unknown>
+    ? Needs<Ctx> extends Unsupported
+      ? never
+      : K
+    : never;
+}[keyof Official & string];
+
+type Call<F> = F extends (
+  ctx: infer Ctx,
+  ...args: infer Args
+) => Promise<infer A>
+  ? (...args: Args) => Effect.Effect<A, never, Needs<Ctx>>
+  : never;
+
+type Lifted<Official> = <M extends Method<Official>>(
+  method: M,
+  ...args: Parameters<Call<Official[M]>>
+) => ReturnType<Call<Official[M]>>;
+
+/**
+ * Lift official promise methods, deriving each capability from its ctx
+ * parameter. A rejection is caller misuse, a limit or a platform fault rather
+ * than a domain fact, so it dies.
+ */
+export const make = <Official extends object>(
+  component: string,
+  official: Official,
+): Lifted<Official> => {
+  const context = Effect.gen(function* () {
+    const action = yield* Effect.serviceOption(
+      ActionCtx.ActionCtx<GenericDataModel>(),
+    );
+    if (Option.isSome(action)) return action.value;
+    const mutation = yield* Effect.serviceOption(
+      MutationCtx.MutationCtx<GenericDataModel>(),
+    );
+    if (Option.isSome(mutation)) return mutation.value;
+    const query = yield* Effect.serviceOption(
+      QueryCtx.QueryCtx<GenericDataModel>(),
+    );
+    if (Option.isSome(query)) return query.value;
+    return yield* Effect.die(
+      new Error(`${component} called outside a Confect handler`),
+    );
+  });
+  const call = Effect.fn(`${component}.call`)(function* (
+    method: Method<Official>,
+    ...args: unknown[]
+  ) {
+    const ctx = yield* context;
+    // Method selects promise methods whose first argument accepts a native handler context.
+    const invoke = official[method] as (
+      native: typeof ctx,
+      ...args: unknown[]
+    ) => Promise<unknown>;
+    return yield* Effect.tryPromise({
+      try: () => invoke.call(official, ctx, ...args),
+      catch: (cause) => ComponentCallFailed.make({ component, method, cause }),
+    }).pipe(Effect.orDie);
+  });
+  // Confect installs the native ctx with the runner capability inferred by Needs.
+  return call as unknown as Lifted<Official>;
+};
+
+/**
+ * A function reference with its encoded arguments, ready for an official method
+ * that takes both.
+ */
+export interface Fn<R extends Ref.Any> {
+  readonly reference: Ref.FunctionReference<R>;
+  readonly args: DefaultFunctionArgs;
+}
+
+/**
+ * Choose whether an official component call forwards the caller's carrier.
+ */
+export interface EncodeCallOptions {
+  /**
+   * Forward the caller's carrier to reserving mutations and actions. Use `none`
+   * when the component replays or compares the stored arguments.
+   */
+  readonly carrier: "forward" | "none";
+}
+
+/**
+ * Encode a ref's arguments through its codecs to the wire record an official
+ * method expects, with an explicit carrier policy.
+ */
+export const encodeCall = <R extends Ref.Any>(
+  ref: R,
+  args: NoInfer<Ref.Args<R>>,
+  options: EncodeCallOptions,
+): Effect.Effect<Fn<R>> =>
+  (options.carrier === "forward"
+    ? ReservedArgument.encodeArgs(ref, args)
+    : Ref.encodeArgs(ref, args)
+  ).pipe(
+    Effect.flatMap(
+      Schema.decodeUnknownEffect(Schema.Record(Schema.String, Schema.Unknown)),
+    ),
+    Effect.map((encoded) => ({
+      reference: getFunctionReference(ref),
+      args: encoded,
+    })),
+    Effect.orDie,
+  );
+
+/**
+ * Encode a callback's real field without fabricating the rest of its arguments.
+ */
+export const encodeField = <
+  R extends Ref.AnyConfect,
+  K extends keyof Ref.Args<R> & keyof Ref.ArgsFields<R>,
+>(
+  ref: R,
+  key: K,
+  value: NoInfer<Ref.Args<R>[K]>,
+): Effect.Effect<unknown> => {
+  const fields = ref.args.fields as Record<
+    keyof Ref.ArgsFields<R>,
+    Schema.Codec<unknown, unknown>
+  >;
+  return Schema.encodeUnknownEffect(fields[key])(value).pipe(Effect.orDie);
+};

package/src/OrderedQuery.ts

@@ -40,14 +40,13 @@ export type OrderedQuery<
   >;
   readonly stream: () => Stream.Stream<Doc, Document.DocumentDecodeError>;
   /**
-   * Native pagination is application-only. Use `QueryStream.paginate` for
-   * component index queries.
+   * Native pagination works in applications and components. A query may call
+   * `.paginate()` once across the host and every component query it calls. A
+   * second call throws. Use `QueryStream.paginate` for another index read.
    */
   readonly paginate: {
     readonly app: NativePaginate<TableInfo_, Doc>;
-    readonly component: {
-      readonly "Native pagination is unavailable in components. Use QueryStream.paginate for index queries.": never;
-    };
+    readonly component: NativePaginate<TableInfo_, Doc>;
   }[TargetKind];
 };