@gaganref/confect-core 10.3.1-fork.71 → 10.3.1-fork.73

package/src/App.ts

@@ -1,12 +1,11 @@
-import type { ComponentDefinition, EnvDefinition } from "convex/server";
-import type { Infer, Validator } from "convex/values";
+import type { ComponentDefinition } from "convex/server";
 import type * as HttpApi from "effect/http-api/HttpApi";
 import * as Predicate from "effect/Predicate";
 import type * as Env from "./Env.js";
 import type * as MiddlewareSpec from "./MiddlewareSpec.js";
+import * as Mount from "./Mount.js";
 
 const TypeId = "~@confect/core/App";
-const MountTypeId = "~@confect/core/App/Mount";
 
 /**
  * The default export of a Convex component's `convex.config` module.
@@ -20,107 +19,11 @@ export type HttpPrefix = `/${string}`;
  */
 export type Api = HttpApi.HttpApi<string, any>;
 
-type EnvOf<D extends Definition> = D["__env"];
-
-type IsOptional<V> = V extends Validator<any, "optional", any> ? true : false;
-
-type RequiredKeys<E extends EnvDefinition> = {
-  [K in keyof E]: IsOptional<E[K]> extends true ? never : K;
-}[keyof E];
-
-type SlotValue<V extends Validator<any, any, any>> = Extract<Infer<V>, string>;
-
-/**
- * What one component env slot accepts: a constant, or an entry whose Convex
- * value fits. A required slot takes only a required entry.
- */
-type Slot<V extends Validator<any, any, any>> =
-  IsOptional<V> extends true
-    ? SlotValue<V> | undefined | Env.Entry<string, any, SlotValue<V>, boolean>
-    : SlotValue<V> | Env.Entry<string, any, SlotValue<V>, false>;
-
-export type Bindings<E extends EnvDefinition> = {
-  readonly [K in RequiredKeys<E>]: Slot<E[K]>;
-} & {
-  readonly [K in Exclude<keyof E, RequiredKeys<E>>]?: Slot<E[K]>;
-};
-
-type HttpOptions = { readonly httpPrefix?: HttpPrefix };
-
-export type Options<D extends Definition> = HttpOptions &
-  ([RequiredKeys<EnvOf<D>>] extends [never]
-    ? { readonly env?: Bindings<EnvOf<D>> }
-    : { readonly env: Bindings<EnvOf<D>> });
-
-type Exact<D extends Definition, O> = {
-  readonly [K in Exclude<keyof O, "env" | "httpPrefix">]: never;
-} & (O extends { readonly env: infer B }
-  ? {
-      readonly env: { readonly [K in Exclude<keyof B, keyof EnvOf<D>>]: never };
-    }
-  : unknown);
-
-export interface MountData {
-  readonly definition: Definition;
-  readonly httpPrefix: HttpPrefix | undefined;
-  readonly env: Readonly<Record<string, string | Env.AnyEntry | undefined>>;
-}
-
-/**
- * A mounted Convex component. `O` keeps the options as written, so {@link make}
- * can see which backends the bound entries come from.
- */
-export interface Mount<out D extends Definition, out O> extends MountData {
-  readonly [MountTypeId]: { readonly definition: D; readonly options: O };
-  readonly httpPrefix: O extends {
-    readonly httpPrefix: infer P extends HttpPrefix;
-  }
-    ? P
-    : undefined;
-}
-
-export type AnyMount = Mount<Definition, unknown>;
-
-/**
- * Mount a Convex component: the default export of its `convex.config` module,
- * official or Confect-authored. `env` is typed against the component's own
- * `defineComponent({ env })` declaration, so a missing required binding, an
- * optional entry in a required slot, a wrong literal and an unknown slot fail
- * to typecheck.
- */
-export function mount<const D extends Definition>(
-  definition: D &
-    ([RequiredKeys<EnvOf<D>>] extends [never]
-      ? unknown
-      : "App.mount: this component declares required env; pass { env }"),
-): Mount<D, {}>;
-export function mount<const D extends Definition, const O extends Options<D>>(
-  definition: D,
-  options: O & Exact<NoInfer<D>, NoInfer<O>>,
-): Mount<D, O>;
-export function mount(
-  definition: Definition,
-  options?: {
-    readonly httpPrefix?: HttpPrefix;
-    readonly env?: MountData["env"];
-  },
-): AnyMount {
-  return {
-    [MountTypeId]: { definition, options },
-    definition,
-    httpPrefix: options?.httpPrefix,
-    env: options?.env ?? {},
-    // The overloads above carry the precise types; this body serves both.
-  } as AnyMount;
-}
-
 type OwnerOf<V> = V extends Env.Entry<infer N, any, any, any> ? N : never;
 
 type Owners<M> =
-  M extends Mount<Definition, infer O>
-    ? O extends { readonly env: infer B }
-      ? { [K in keyof B]: OwnerOf<B[K]> }[keyof B]
-      : never
+  M extends Mount.Mount<any, any, Mount.Declared<any, infer B>>
+    ? { [K in keyof B]: OwnerOf<B[K]> }[keyof B]
     : never;
 
 type OwnedBy<N extends string, M> = {
@@ -133,53 +36,56 @@ export type Kind = "app" | "component";
 
 export interface App<
   E extends Env.Any,
-  M extends Readonly<Record<string, AnyMount>>,
+  M extends ReadonlyArray<Mount.Any>,
   K extends Kind = Kind,
 > {
   readonly [TypeId]: typeof TypeId;
   readonly kind: K;
   readonly env: E;
+  readonly components: ReadonlyArray<Definition>;
   readonly mounts: M;
   readonly requiresMiddleware: ReadonlyArray<MiddlewareSpec.AnyMiddlewareSpec>;
 }
 
-export type Any = App<Env.Any, Readonly<Record<string, AnyMount>>>;
+export type Any = App<Env.Any, ReadonlyArray<Mount.Any>>;
 
 /**
- * Declare a backend, in `confect/app.ts`: its env and its mounted Convex
- * components by name. Set `kind: "component"` when declaring a component; the
- * default is `"app"`. Codegen rejects a kind that differs from its target.
- * Codegen writes `convex/convex.config.ts` from it. A mount that binds another
- * backend's env entry fails to typecheck.
+ * Declare a backend, in `confect/app.ts`: its env, the `convex.config`
+ * definitions of the Convex components it mounts, and its mounts. Set `kind:
+ * "component"` when declaring a component; the default is `"app"`. Codegen
+ * rejects a kind that differs from its target, and writes
+ * `convex/convex.config.ts` with one `app.use` per mount, in list order, using
+ * the definition whose `defineComponent` name is the mount's component name. A
+ * mount that binds another backend's env entry fails to typecheck.
  *
  * ```ts
+ * import email from "@acme/email/convex.config";
+ * import workpool from "@convex-dev/workpool/convex.config";
+ *
  * export default App.make({
  *   env,
- *   mounts: {
- *     email: App.mount(email, {
- *       httpPrefix: "/email",
- *       env: { FROM: env.EMAIL_FROM, KEY: env.RESEND_API_KEY },
- *     }),
- *     importsPool: App.mount(workpool),
- *   },
+ *   components: [email, workpool],
+ *   mounts: [BulkEmail, TransactionalEmail, ImportsPool],
  * });
  * ```
  */
 export const make = <
   const E extends Env.Any,
-  const M extends Readonly<Record<string, AnyMount>> = {},
+  const M extends ReadonlyArray<Mount.Any> = [],
   const K extends Kind = "app",
 >(
   options: {
     readonly env: E;
     readonly requiresMiddleware?: ReadonlyArray<MiddlewareSpec.AnyMiddlewareSpec>;
+    readonly components?: ReadonlyArray<Definition>;
     readonly mounts?: M & OwnedBy<NoInfer<Env.Name<E>>, NoInfer<M>>;
   } & ([K] extends ["app"] ? { readonly kind?: K } : { readonly kind: K }),
 ): App<E, M, K> => ({
   [TypeId]: TypeId,
   kind: options.kind ?? ("app" as K),
   env: options.env,
-  mounts: options.mounts ?? ({} as M),
+  components: options.components ?? [],
+  mounts: options.mounts ?? ([] as unknown as M),
   requiresMiddleware: options.requiresMiddleware ?? [],
 });
 
@@ -189,20 +95,16 @@ export const isApp = (u: unknown): u is Any =>
   Predicate.hasProperty(u, "kind") &&
   (u.kind === "app" || u.kind === "component");
 
-export const isMount = (u: unknown): u is AnyMount =>
-  Predicate.hasProperty(u, MountTypeId);
-
 export const env = <A extends Any>(app: A): A["env"] => app.env;
 
 /**
- * Every mount with its name, in declaration order.
+ * The `convex.config` definitions the backend lists, in list order.
+ */
+export const components = (app: Any): ReadonlyArray<Definition> =>
+  app.components;
+
+/**
+ * What each mount was declared with, in list order.
  */
-export const mounts = (
-  app: Any,
-): ReadonlyArray<MountData & { readonly name: string }> =>
-  Object.entries(app.mounts).map(([name, installed]) => ({
-    name,
-    definition: installed.definition,
-    httpPrefix: installed.httpPrefix,
-    env: installed.env,
-  }));
+export const mounts = (app: Any): ReadonlyArray<Mount.Data> =>
+  app.mounts.map(Mount.data);

package/src/Auth.ts

@@ -2,6 +2,7 @@ import type { AuthProvider } from "convex/server";
 import * as Predicate from "effect/Predicate";
 import type * as App from "./App.js";
 import type * as Env from "./Env.js";
+import * as Mount from "./Mount.js";
 import type { TypeError } from "./Types.js";
 
 const TypeId = "~@confect/core/Auth";
@@ -85,19 +86,19 @@ export type Any = Auth<App.Any>;
  */
 export function siteUrl(path?: `/${string}`): SiteUrl;
 export function siteUrl(
-  mount: { readonly httpPrefix: App.HttpPrefix },
+  mount: Mount.Mount<any, string, Mount.Declared<App.HttpPrefix>>,
   path?: `/${string}`,
 ): SiteUrl;
 export function siteUrl(
-  pathOrMount?: `/${string}` | { readonly httpPrefix: App.HttpPrefix },
+  pathOrMount?: `/${string}` | Mount.Any,
   path: string = "",
 ): SiteUrl {
   return {
     [SiteUrlTypeId]: SiteUrlTypeId,
     path:
-      typeof pathOrMount === "object"
-        ? pathOrMount.httpPrefix.replace(/\/+$/, "") + path
-        : (pathOrMount ?? ""),
+      typeof pathOrMount === "string" || pathOrMount === undefined
+        ? (pathOrMount ?? "")
+        : (Mount.data(pathOrMount).httpPrefix ?? "").replace(/\/+$/, "") + path,
   };
 }
 

package/src/Component.ts

@@ -418,3 +418,53 @@ export const schema = <
     component[BoundTypeId].from,
     component[BoundTypeId].scope,
   );
+
+/**
+ * A component's `init`: an internal Confect mutation whose args are the install
+ * args each mount passes.
+ */
+export type Init = Ref.AnyConfect & {
+  readonly "~RuntimeAndFunctionType": RuntimeAndFunctionType.ConvexMutation;
+  readonly "~FunctionVisibility": "internal";
+};
+
+export interface DescriptorOptions {
+  readonly init?: Init;
+  /**
+   * The component's `_generated/component` contract. A mount of a descriptor
+   * with one rebases a callback slot's args with `callbackArgs`.
+   */
+  readonly contract?: Component<Spec.AnyWithProps, IdScope.IdScope, string>;
+  readonly env?: Readonly<Record<string, Schema.Top>>;
+  /**
+   * Builds the component's client from its native mount, then the mount's
+   * `options` when the client takes any.
+   */
+  readonly client: (...args: never) => unknown;
+}
+
+export type Descriptor<
+  Name extends string = string,
+  Options extends DescriptorOptions = DescriptorOptions,
+> = Options & { readonly name: Name };
+
+/**
+ * Describe a Convex component for `Mount.make`, as `defineComponent` does for
+ * Convex. A component with `init` takes install `args` at each mount, and one
+ * with `env` takes `env`. Export it from the package's `./client` entry.
+ *
+ * ```ts
+ * export default Component.make("email", {
+ *   init: refs.internal.install.init,
+ *   env: { RESEND_API_KEY: Schema.String },
+ *   client: Client.make,
+ * });
+ * ```
+ */
+export const make = <
+  const Name extends string,
+  const Options extends DescriptorOptions,
+>(
+  name: Name,
+  options: Options,
+): Descriptor<Name, Options> => ({ ...options, name });

package/src/ManifestSection.ts

@@ -39,11 +39,13 @@ export interface Generate {
 
 /**
  * What codegen hands a section's `summarize`: the `confect/` files its
- * `generate` matched, and each function's description by path.
+ * `generate` matched, each function's description by path, and the spec file
+ * declaring each function by path, relative to `confect/`.
  */
 export interface SummarizeInput<Value = unknown> {
   readonly modules: GenerateInput["modules"];
   readonly functions: Readonly<Record<string, Value>>;
+  readonly sources: Readonly<Record<string, string>>;
 }
 
 export interface ManifestSection<

package/src/Mount.ts

@@ -0,0 +1,284 @@
+import { componentsGeneric } from "convex/server";
+import * as Context from "effect/Context";
+import * as Schema from "effect/Schema";
+import * as SchemaAST from "effect/SchemaAST";
+import type * as App from "./App.js";
+import type * as Callback from "./Callback.js";
+import * as Component from "./Component.js";
+import type * as Env from "./Env.js";
+import type * as GenericId from "./GenericId.js";
+import type * as IdScope from "./IdScope.js";
+import { CallbackContract } from "./internal/annotations.js";
+import type * as Ref from "./Ref.js";
+
+const TypeId = "~@confect/core/Mount";
+
+type Handle = Ref.AnyConfect & {
+  readonly "~@confect/core/Callback/Handle": Callback.Id;
+};
+
+type ContractOf<H extends Handle> = Callback.Contract<
+  H["~@confect/core/Callback/Handle"],
+  Ref.GetFunctionType<H>,
+  H["args"]["fields"],
+  H["returns"],
+  Extract<NonNullable<H["error"]>, Schema.Top>
+>;
+
+/**
+ * What a mount passes for `init`'s args: the same shape, with a host ref in
+ * each callback slot.
+ */
+type Input<T> = T extends Handle
+  ? Ref.AnyConfect
+  : T extends object
+    ? { readonly [K in keyof T]: Input<T[K]> }
+    : T;
+
+/**
+ * `A` when every alternative of `A` fits `T`; otherwise a type that refuses
+ * each alternative that does not. A callback slot takes an internal host ref
+ * that satisfies the slot's contract. Whether a slot may be left `undefined` is
+ * `Input`'s to say.
+ */
+type Check<T, A> = A extends unknown ? Fit<T, A> : never;
+
+/**
+ * Distributes over the members of `T`, so a value is checked against the
+ * members whose shape it has and fits when it fits one of them.
+ */
+type Fit<T, A> = T extends Handle
+  ? A extends Ref.AnyConfect
+    ? A &
+        Callback.Check<ContractOf<T>, A> &
+        (Ref.GetFunctionVisibility<A> extends "internal"
+          ? unknown
+          : { readonly callbackMustBeInternal: never })
+    : never
+  : T extends object
+    ? A extends Input<T>
+      ? {
+          readonly [K in keyof A]: K extends keyof T
+            ? Check<T[K], A[K]>
+            : never;
+        }
+      : never
+    : A extends T
+      ? A
+      : never;
+
+type ArgsOf<C> = C extends { readonly init: infer I extends Component.Init }
+  ? Ref.Args<I>
+  : never;
+
+/**
+ * `[C]`, not a bare `C`, so the conditional is not distributive. A distributive
+ * one resolves against `Component.Descriptor` while `C` is inferred, drops `A`
+ * from the contextual type, and widens inline literals until `A` falls back to
+ * its constraint.
+ */
+type ArgsField<C, A> = [C] extends [
+  { readonly init: infer I extends Component.Init },
+]
+  ? { readonly args: A & NoInfer<Check<Ref.Args<I>, A>> }
+  : { readonly args?: never };
+
+type IsOptional<S> = S extends { readonly "~type.optionality": "optional" }
+  ? true
+  : false;
+
+type RequiredKeys<E> = {
+  [K in keyof E]: IsOptional<E[K]> extends true ? never : K;
+}[keyof E];
+
+type SlotValue<S> = Extract<Schema.Schema.Type<S & Schema.Top>, string>;
+
+/**
+ * What one env slot accepts: a constant, or an entry of the host's env whose
+ * value fits. A required slot takes only a required entry.
+ */
+type Slot<S> =
+  IsOptional<S> extends true
+    ? SlotValue<S> | undefined | Env.Entry<string, any, SlotValue<S>, boolean>
+    : SlotValue<S> | Env.Entry<string, any, SlotValue<S>, false>;
+
+type Bindings<E> = { readonly [K in RequiredKeys<E>]: Slot<E[K]> } & {
+  readonly [K in Exclude<keyof E, RequiredKeys<E>>]?: Slot<E[K]>;
+};
+
+/**
+ * `B` keeps the bindings as written, so `App.make` can see which backends their
+ * entries come from. `[C]` for the reason `ArgsField` gives: a bare `C` widens
+ * an inline constant to `string`.
+ */
+type EnvField<C, B> = [C] extends [{ readonly env: infer E }]
+  ? [RequiredKeys<E>] extends [never]
+    ? { readonly env?: B & Bindings<E> & NoExtra<B, E> }
+    : { readonly env: B & Bindings<E> & NoExtra<B, E> }
+  : { readonly env?: never };
+
+type NoExtra<B, E> = { readonly [K in Exclude<keyof B, keyof E>]: never };
+
+/**
+ * The client constructor's parameters after the native mount decide whether
+ * `options` is absent, optional or required. A client that takes no native
+ * mount cannot be mounted. That branch is an object, not `never`, so the
+ * literal `name` and `args` beside it keep their types.
+ */
+type OptionsField<C extends Component.Descriptor> =
+  Parameters<C["client"]> extends [unknown, ...infer Rest]
+    ? Rest extends []
+      ? { readonly options?: never }
+      : Rest extends [infer O]
+        ? { readonly options: O }
+        : Rest extends [options?: infer O]
+          ? { readonly options?: Exclude<O, undefined> }
+          : never
+    : { readonly options: never };
+
+export type Client<C extends Component.Descriptor> = ReturnType<C["client"]>;
+
+export interface Data<C extends Component.Descriptor = Component.Descriptor> {
+  readonly component: C;
+  readonly name: string;
+  readonly httpPrefix?: App.HttpPrefix;
+  readonly env?: Readonly<Record<string, string | Env.AnyEntry | undefined>>;
+  readonly args?: unknown;
+  readonly options?: unknown;
+}
+
+/**
+ * What a mount was declared with, as written: its HTTP prefix and env bindings.
+ */
+export interface Declared<
+  P extends App.HttpPrefix | undefined = App.HttpPrefix | undefined,
+  B = unknown,
+> {
+  readonly httpPrefix: P;
+  readonly env: B;
+}
+
+/**
+ * A mounted Convex component. Yield it for its client. Its default is the
+ * component's client over this mount, and `Effect.provideService` replaces it.
+ */
+export interface Mount<
+  C extends Component.Descriptor,
+  Name extends string,
+  D extends Declared = Declared,
+> extends Context.Reference<Client<C>> {
+  readonly [TypeId]: Data<C> & { readonly name: Name };
+  readonly "~declared"?: D;
+}
+
+export type Any = Mount<Component.Descriptor, string>;
+
+export type NameOf<M> = M extends Mount<any, infer N, any> ? N : never;
+
+type InitArgs<C> = C extends { readonly init: infer I extends Component.Init }
+  ? Ref.Args<I>
+  : never;
+
+type CallbackSlot<C> = {
+  [K in keyof InitArgs<C>]-?: NonNullable<InitArgs<C>[K]> extends Handle
+    ? K
+    : never;
+}[keyof InitArgs<C>] &
+  string;
+
+type SlotArgs<C, K extends PropertyKey> = Extract<
+  NonNullable<InitArgs<C>[K & keyof InitArgs<C>]>,
+  Handle
+>["args"]["fields"];
+
+/**
+ * `callbackArgs`, on a mount whose descriptor carries its contract.
+ */
+type CallbackArgs<C, Name extends string> = C extends {
+  readonly contract: Component.Component<any, infer From, any>;
+}
+  ? {
+      /**
+       * A callback slot's contract args, with the component's ids typed for
+       * this mount, for the host function that answers the callback.
+       */
+      readonly callbackArgs: <const K extends CallbackSlot<C>>(
+        slot: K,
+      ) => GenericId.RebaseSchema<
+        Schema.Struct<SlotArgs<C, K>>,
+        From,
+        Component.MountScope<IdScope.App, Name>
+      >["fields"];
+    }
+  : unknown;
+
+/**
+ * Mount a Convex component, as Convex's `app.use` does, in the host's
+ * `confect/<mount>.ts`. `args` is typed from the component's `init`, `env` from
+ * its env slots, and `options` from its client constructor. A handler reaches
+ * the client with `yield* BulkEmail`.
+ *
+ * ```ts
+ * export const BulkEmail = Mount.make(Email, {
+ *   name: "bulkEmail",
+ *   httpPrefix: "/bulk-email",
+ *   env: { RESEND_API_KEY: env.BULK_RESEND_KEY },
+ *   args: {
+ *     fromName: "School office",
+ *     onEvent: refs.internal.circulars.onEmailEvent,
+ *   },
+ * });
+ * ```
+ */
+export const make = <
+  C extends Component.Descriptor,
+  const Name extends string,
+  const A extends Input<ArgsOf<C>>,
+  const P extends App.HttpPrefix = never,
+  const B = {},
+>(
+  component: C,
+  options: {
+    readonly name: Name;
+    readonly httpPrefix?: P;
+  } & EnvField<C, B> &
+    ArgsField<C, A> &
+    OptionsField<C>,
+): Mount<C, Name, Declared<[P] extends [never] ? undefined : P, B>> &
+  CallbackArgs<C, Name> => {
+  const data = { ...(options as object), component } as Data<C> & {
+    readonly name: Name;
+  };
+  // The options were checked against the constructor's parameters above.
+  const client = component.client as unknown as (
+    native: unknown,
+    options?: unknown,
+  ) => Client<C>;
+  const native = () => componentsGeneric()[data.name];
+  const mount = Context.Reference<Client<C>>(`mount/${data.name}`, {
+    defaultValue: () => client(native(), data.options),
+  });
+  const { contract, init } = component;
+  const callbackArgs = (slot: string) => {
+    const field = init!.args.fields[slot]!;
+    const callback = SchemaAST.resolveAt<Callback.Any>(CallbackContract)(
+      Schema.toEncoded(field).ast,
+    )!;
+    const bound = Component.bind(contract!, native() as never);
+    return Component.schema(bound, callback.functionProvenance.args).fields;
+  };
+  return Object.assign(
+    mount,
+    { [TypeId]: data },
+    contract === undefined ? {} : { callbackArgs },
+  ) as Mount<C, Name, Declared<[P] extends [never] ? undefined : P, B>> &
+    CallbackArgs<C, Name>;
+};
+
+/**
+ * What a mount was declared with: its component, name, HTTP prefix, env, args
+ * and options.
+ */
+export const data = <C extends Component.Descriptor, Name extends string>(
+  mount: Mount<C, Name, Declared>,
+): Data<C> & { readonly name: Name } => mount[TypeId];

package/src/index.ts

@@ -15,6 +15,7 @@ export * as Identifier from "./Identifier.js";
 export * as Lazy from "./Lazy.js";
 export * as Manifest from "./Manifest.js";
 export * as ManifestSection from "./ManifestSection.js";
+export * as Mount from "./Mount.js";
 export * as MiddlewareAttachment from "./MiddlewareAttachment.js";
 export * as MiddlewareSpec from "./MiddlewareSpec.js";
 export * as PaginationError from "./PaginationError.js";