@gaganref/confect-core 10.3.1-fork.9 → 10.3.1-fork.90

package/src/Http.ts

@@ -7,7 +7,7 @@ import * as SchemaAST from "effect/SchemaAST";
 import type * as HttpApi from "effect/http-api/HttpApi";
 import * as HttpApiBuilder from "effect/http-api/HttpApiBuilder";
 import type * as HttpApiGroup from "effect/http-api/HttpApiGroup";
-import * as HttpApiScalar from "effect/http-api/HttpApiScalar";
+import { scalarDocs } from "./internal/scalarDocs.js";
 import * as App from "./App.js";
 
 const TypeId = "~@confect/core/Http";
@@ -57,10 +57,7 @@ export const make = <
   const routes =
     options.docs === undefined
       ? api
-      : Layer.merge(
-          api,
-          HttpApiScalar.layerCdn(options.api, { path: options.docs }),
-        );
+      : Layer.merge(api, scalarDocs(options.api, options.docs));
   const http: Http<HttpApi.HttpApi<Id, Groups>, typeof routes> = {
     [TypeId]: TypeId,
     api: options.api,
@@ -73,10 +70,7 @@ export const make = <
 export const isHttp = (u: unknown): u is Any =>
   Predicate.hasProperty(u, TypeId) && u[TypeId] === TypeId;
 
-export type Owner =
-  | { readonly kind: "app" }
-  | { readonly kind: "docs" }
-  | { readonly kind: "mount"; readonly mount: string };
+export type Owner = { readonly kind: "app" } | { readonly kind: "docs" };
 
 export interface Route {
   readonly method: string;
@@ -104,7 +98,7 @@ export class DuplicateRoute extends Data.TaggedError("DuplicateRoute")<{
   readonly second: Owner;
 }> {
   override get message(): string {
-    return `${this.method} ${this.path} is declared twice (${ownerLabel(this.first)} and ${ownerLabel(this.second)}).`;
+    return `${this.method} ${this.path} is declared twice (${this.first.kind} and ${this.second.kind}).`;
   }
 }
 
@@ -124,9 +118,6 @@ export type RouteError =
   | DuplicateRoute
   | OverlappingMountPrefixes;
 
-const ownerLabel = (owner: Owner): string =>
-  owner.kind === "mount" ? `mount "${owner.mount}"` : owner.kind;
-
 const trimSlash = (prefix: string): string =>
   prefix.length > 1 && prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
 
@@ -160,14 +151,10 @@ interface KeyedRoute {
   readonly key: string;
 }
 
-const apiRoutes = (
-  api: App.Api,
-  prefix: string,
-  owner: Owner,
-): ReadonlyArray<KeyedRoute> =>
+const apiRoutes = (api: App.Api, owner: Owner): ReadonlyArray<KeyedRoute> =>
   Object.values<HttpApiGroup.Top>(api.groups).flatMap((group) =>
     Object.values(group.endpoints).map((endpoint) => {
-      const path = prefix + endpoint.path;
+      const path = endpoint.path;
       const declared = paramNames(endpoint.params);
       return {
         route: { method: endpoint.method, path, owner },
@@ -177,20 +164,19 @@ const apiRoutes = (
   );
 
 /**
- * Every HTTP route the backend serves: the app's api, its docs page and each
- * mount's api under its prefix. Fails when an app route or the docs page is at
- * or under a mount's prefix (Convex accepts that and lets the app route
- * silently shadow the component's), when two routes share a method and path, or
- * when two mount prefixes overlap.
+ * The backend's own HTTP routes and docs page. Fails when a route is at or
+ * under a mount's prefix (Convex accepts that and lets the app route silently
+ * shadow the component's), when two routes share a method and path, or when two
+ * mount prefixes overlap.
  */
 export const routes = (
   app: App.Any,
   http?: Any,
 ): Result.Result<ReadonlyArray<Route>, RouteError> => {
-  const mounts = App.mounts(app).flatMap(({ name, httpPrefix, api }) =>
+  const mounts = App.mounts(app).flatMap(({ name, httpPrefix }) =>
     httpPrefix === undefined
       ? []
-      : [{ name, httpPrefix: trimSlash(httpPrefix), api }],
+      : [{ name, httpPrefix: trimSlash(httpPrefix) }],
   );
 
   for (const [index, first] of mounts.entries()) {
@@ -213,7 +199,7 @@ export const routes = (
     http === undefined
       ? []
       : [
-          ...apiRoutes(http.api, "", { kind: "app" }),
+          ...apiRoutes(http.api, { kind: "app" }),
           ...(http.docs === undefined
             ? []
             : [
@@ -244,16 +230,8 @@ export const routes = (
     }
   }
 
-  const all = [
-    ...own,
-    ...mounts.flatMap(({ name, httpPrefix, api }) =>
-      api === undefined
-        ? []
-        : apiRoutes(api, httpPrefix, { kind: "mount", mount: name }),
-    ),
-  ];
   const seen = new Map<string, Route>();
-  for (const { route, key } of all) {
+  for (const { route, key } of own) {
     const previous = seen.get(key);
     if (previous !== undefined) {
       return Result.fail(
@@ -267,5 +245,5 @@ export const routes = (
     }
     seen.set(key, route);
   }
-  return Result.succeed(all.map(({ route }) => route));
+  return Result.succeed(own.map(({ route }) => route));
 };

package/src/ManifestSection.ts

@@ -0,0 +1,108 @@
+import type * as FunctionSpec from "./FunctionSpec.js";
+import type * as MiddlewareSpec from "./MiddlewareSpec.js";
+
+export interface Data<Value = unknown> {
+  readonly format: number;
+  readonly functions: Readonly<Record<string, Value>>;
+}
+
+/**
+ * The backend codegen generates: the app, or a component under the name its
+ * `defineComponent` gives it.
+ */
+export type Target =
+  | { readonly kind: "app" }
+  | { readonly kind: "component"; readonly name: string };
+
+/**
+ * What codegen hands a section's `render`: the exports of each `confect/` file
+ * it matched, every registered function with the spec file declaring it, each
+ * mounted component with the specifier of its definition, every file `match`
+ * was offered, the backend it generates and the absolute path of `confect/`.
+ */
+export interface GenerateInput {
+  readonly modules: ReadonlyArray<{
+    readonly relativePath: string;
+    readonly exports: Readonly<Record<string, unknown>>;
+  }>;
+  readonly functions: ReadonlyArray<{
+    readonly path: string;
+    readonly source: string;
+  }>;
+  readonly mounts: ReadonlyArray<{
+    readonly name: string;
+    readonly definition: string;
+  }>;
+  readonly files: ReadonlyArray<string>;
+  readonly target: Target;
+  readonly confectDirectory: string;
+}
+
+/**
+ * What codegen hands a section's `verify.check`: the exports of each `confect/`
+ * file `verify.match` selected, each mounted component with the specifier of
+ * its definition, and the backend it generates.
+ */
+export interface VerifyInput {
+  readonly modules: GenerateInput["modules"];
+  readonly mounts: GenerateInput["mounts"];
+  readonly target: Target;
+}
+
+export interface Generate {
+  readonly file: string;
+  match(relativePath: string): boolean;
+  render(input: GenerateInput): {
+    readonly contents: string;
+    readonly errors: ReadonlyArray<string>;
+  };
+  /**
+   * A check codegen runs once every `_generated` file exists, so the files
+   * `match` selects may import this section's file or any other. Codegen fails
+   * with each string `check` returns.
+   */
+  readonly verify?: {
+    match(relativePath: string): boolean;
+    check(input: VerifyInput): ReadonlyArray<string>;
+  };
+}
+
+/**
+ * What codegen hands a section's `summarize`: the `confect/` files its
+ * `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<
+  Value = unknown,
+  Data_ extends { readonly format: number } = Data<Value>,
+> {
+  readonly owner: string;
+  readonly format: number;
+  describe(input: {
+    readonly path: string;
+    readonly spec: FunctionSpec.AnyWithProps;
+    readonly middleware: ReadonlyArray<MiddlewareSpec.AnyMiddlewareSpec>;
+  }): Value;
+  summarize?(input: SummarizeInput<Value>): Data_;
+  check?(
+    next: Data_,
+    previous: unknown,
+  ): {
+    readonly errors: ReadonlyArray<string>;
+    readonly notes: ReadonlyArray<string>;
+  };
+  readonly generate?: Generate;
+}
+
+export type Any = ManifestSection<unknown, { readonly format: number }>;
+
+export interface Entry {
+  readonly key: string;
+  readonly section: Any;
+}

package/src/Mount.ts

@@ -0,0 +1,401 @@
+import { componentsGeneric } from "convex/server";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import * as SchemaAST from "effect/SchemaAST";
+import type * as App from "./App.js";
+import * 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 * 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];
+
+/**
+ * What a push runs for a mount: its component's `init`, at the mount's
+ * component path, with the install args encoded.
+ */
+export interface InitCall {
+  readonly componentPath: string;
+  readonly functionName: string;
+  readonly args: unknown;
+}
+
+const contractOf = (schema: Schema.Top) =>
+  SchemaAST.resolveAt<Callback.Any>(CallbackContract)(
+    Schema.toEncoded(schema).ast,
+  );
+
+type Create<E, R> = (
+  contract: Callback.Any,
+  ref: Ref.Any,
+) => Effect.Effect<unknown, E, R>;
+
+const placeholderHandle: Create<never, never> = (contract) =>
+  Schema.decodeEffect(Callback.handle(contract))("").pipe(Effect.orDie);
+
+/**
+ * Handles for the union member `value` takes: the first member that fits once
+ * its callback slots hold placeholder handles and whose handles `create` makes.
+ * A target that satisfies only a later member's contract takes that member.
+ */
+const withMemberHandles = <E, R>(
+  members: ReadonlyArray<Schema.Top>,
+  value: unknown,
+  create: Create<E, R>,
+): Effect.Effect<unknown, E, R> => {
+  const fitting = members.filter((member) =>
+    Schema.is(member)(
+      Effect.runSync(withHandles(member, value, placeholderHandle)),
+    ),
+  );
+  return fitting.length === 0
+    ? Effect.succeed(value)
+    : Effect.firstSuccessOf(
+        fitting.map((member) => withHandles(member, value, create)),
+      );
+};
+
+/**
+ * The schema of each key's value in a struct or a record.
+ */
+const entrySchema = (
+  schema: Schema.Top,
+): ((key: string) => Schema.Top | undefined) | undefined => {
+  if (Predicate.hasProperty(schema, "fields")) {
+    const fields = schema.fields as Readonly<Record<string, Schema.Top>>;
+    return (key) => fields[key];
+  }
+  if (SchemaAST.isObjects(schema.ast) && Predicate.hasProperty(schema, "value"))
+    return () => schema.value as Schema.Top;
+  return undefined;
+};
+
+/**
+ * Put a handle in each callback slot: a host ref in a field whose schema
+ * carries a callback contract, at any depth of struct fields and record values,
+ * through `optionalKey`, `optional` and the union member the value takes.
+ */
+const withHandles = <E, R>(
+  schema: Schema.Top,
+  value: unknown,
+  create: Create<E, R>,
+): Effect.Effect<unknown, E, R> => {
+  const contract = contractOf(schema);
+  if (contract !== undefined && Ref.isRef(value))
+    return create(contract, value);
+  if (Predicate.hasProperty(schema, "schema"))
+    return withHandles(schema.schema as Schema.Top, value, create);
+  if (Predicate.hasProperty(schema, "members") && Array.isArray(schema.members))
+    return withMemberHandles(schema.members, value, create);
+  const at = entrySchema(schema);
+  if (at === undefined || !Predicate.isObject(value))
+    return Effect.succeed(value);
+  return Effect.forEach(Object.entries(value), ([key, field]) => {
+    const fieldSchema = at(key);
+    return fieldSchema === undefined
+      ? Effect.succeed([key, field] as const)
+      : withHandles(fieldSchema, field, create).pipe(
+          Effect.map((resolved) => [key, resolved] as const),
+        );
+  }).pipe(Effect.map(Object.fromEntries));
+};
+
+/**
+ * The `init` call a mount's install args make, with each callback slot's host
+ * ref replaced by the handle `create` makes for the slot's contract. None for a
+ * component without `init`.
+ */
+export const initCall = <E, R>(
+  mount: Any,
+  create: Create<E, R>,
+): Effect.Effect<Option.Option<InitCall>, E | Schema.SchemaError, R> => {
+  const { component, name, args } = data(mount);
+  const init = component.init;
+  if (init === undefined) return Effect.succeedNone;
+  return withHandles(init.args, args ?? {}, create).pipe(
+    Effect.flatMap(Schema.encodeUnknownEffect(init.args)),
+    Effect.map((encoded) =>
+      Option.some({
+        componentPath: name,
+        functionName: init.convexFunctionName,
+        args: encoded,
+      }),
+    ),
+  );
+};