@gaganref/confect-core 10.3.1-fork.6 → 10.3.1-fork.61

package/src/ManifestSection.ts

@@ -0,0 +1,74 @@
+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>>;
+}
+
+/**
+ * What codegen hands a section's `render`: the exports of each `confect/` file
+ * it matched, every registered function with the spec file declaring it, and
+ * each mounted component with the specifier of its definition.
+ */
+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;
+  }>;
+}
+
+export interface Generate {
+  readonly file: string;
+  match(relativePath: string): boolean;
+  render(input: GenerateInput): {
+    readonly contents: string;
+    readonly errors: ReadonlyArray<string>;
+  };
+}
+
+/**
+ * What codegen hands a section's `summarize`: the `confect/` files its
+ * `generate` matched, and each function's description by path.
+ */
+export interface SummarizeInput<Value = unknown> {
+  readonly modules: GenerateInput["modules"];
+  readonly functions: Readonly<Record<string, Value>>;
+}
+
+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/Profile.ts

@@ -0,0 +1,141 @@
+import type * as Schema from "effect/Schema";
+import type * as FunctionProvenance from "./FunctionProvenance.js";
+import type * as MiddlewareSpec from "./MiddlewareSpec.js";
+
+/**
+ * A type-level function from a function's name and args fields to the fields a
+ * profile's builders require. Read `this["Name"]` and `this["Args"]` directly
+ * in `Type`, passing them to a type alias; a nested object type cannot name
+ * `this`.
+ */
+export interface Fields {
+  readonly Name: string;
+  // `unknown`, not `ArgsFields`: an index signature here would leak into
+  // `keyof this["Args"]`.
+  readonly Args: unknown;
+  readonly Type: object;
+}
+
+export interface NoFields extends Fields {
+  readonly Type: {};
+}
+
+export type Apply<
+  Fields_ extends Fields,
+  Name_ extends string,
+  Args_,
+> = (Fields_ & { readonly Name: Name_; readonly Args: Args_ })["Type"];
+
+/**
+ * A base profile's fields and its extension's, for one function.
+ */
+export interface Both<
+  Base extends Fields,
+  Extension extends Fields,
+> extends Fields {
+  readonly Type: Apply<Base, this["Name"], this["Args"]> &
+    Apply<Extension, this["Name"], this["Args"]>;
+}
+
+/**
+ * What a profile callback sees. `args` stays a thunk.
+ */
+export interface Info<FieldsType> {
+  readonly name: string;
+  readonly description?: string;
+  readonly args: () => FunctionProvenance.ArgsFields;
+  readonly fields: "description" extends keyof FieldsType
+    ? Omit<FieldsType, "description">
+    : FieldsType;
+}
+
+export interface Attachment<
+  MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec,
+  FieldsType,
+> {
+  readonly spec: MiddlewareSpec_;
+  readonly options: (
+    info: Info<FieldsType>,
+  ) => MiddlewareSpec.Options<MiddlewareSpec_>;
+}
+
+/**
+ * A middleware without options has none to compute and is attached at most
+ * once, so it joins a profile's list directly.
+ */
+type TakesOptions<MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec> = [
+  MiddlewareSpec.WithoutOptions<MiddlewareSpec_>,
+] extends [never]
+  ? unknown
+  : MiddlewareSpec.AttachmentError<`Middleware "${MiddlewareSpec.Key<MiddlewareSpec_>}" takes no options, so list it without Profile.attach`>;
+
+/**
+ * Attach a middleware that takes options to every function a profile builds,
+ * with options computed from each function's fields.
+ */
+export const attach = <
+  MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec,
+  FieldsType,
+>(
+  spec: MiddlewareSpec_ & TakesOptions<MiddlewareSpec_>,
+  options: (
+    info: Info<FieldsType>,
+  ) => MiddlewareSpec.Options<NoInfer<MiddlewareSpec_>>,
+): Attachment<MiddlewareSpec_, FieldsType> => ({ spec, options });
+
+/**
+ * A type function for a schema wrapper, applied to each declared codec.
+ */
+export interface SchemaTransform {
+  readonly Input: Schema.Codec<unknown, unknown>;
+  readonly Type: Schema.Codec<any, any>;
+}
+
+/**
+ * Args wrappers transform the declared field map, before Struct composition.
+ */
+export interface ArgsTransform {
+  readonly Input: unknown;
+  readonly Type: FunctionProvenance.ArgsFields;
+}
+
+export interface Transforms {
+  readonly args?: ArgsTransform;
+  readonly returns?: SchemaTransform;
+  readonly item?: SchemaTransform;
+  readonly error?: SchemaTransform;
+}
+
+export type Transform<T, Input> = (T & { readonly Input: Input })["Type" &
+  keyof T];
+
+/**
+ * Error wrappers opt into Schema.Never when no error thunk was declared.
+ */
+export type Wrappers<T extends Transforms, FieldsType> = {
+  readonly [K in keyof T]-?: K extends keyof Transforms
+    ? <
+        Input extends (K extends "args"
+          ? FunctionProvenance.ArgsFields
+          : Schema.Codec<any, any>),
+      >(
+        thunk: () => Input,
+        info: Info<FieldsType>,
+      ) => () => Transform<T[K], Input>
+    : never;
+} & { readonly [K in Exclude<keyof Transforms, keyof T>]?: never };
+
+type NonemptyError<T extends Transforms> = T extends {
+  readonly error: infer E extends SchemaTransform;
+}
+  ? [Transform<E, typeof Schema.Never>["Type"]] extends [never]
+    ? MiddlewareSpec.AttachmentError<"Profile error wrapper must add an error to Schema.Never">
+    : unknown
+  : unknown;
+
+export type SchemaConfig<T extends Transforms, FieldsType> = ([
+  keyof T,
+] extends [never]
+  ? { readonly schemas?: never }
+  : { readonly schemas: Wrappers<T, FieldsType> }) &
+  NonemptyError<T>;

package/src/Ref.ts

@@ -6,7 +6,7 @@ import type {
   PaginationOptions,
   PaginationResult,
 } from "convex/server";
-import { getFunctionAddress, makeFunctionReference } from "convex/server";
+import { getFunctionAddress } from "convex/server";
 import type { Value } from "convex/values";
 import { ConvexError } from "convex/values";
 import * as Effect from "effect/Effect";
@@ -18,6 +18,7 @@ import type * as FunctionProvenance from "./FunctionProvenance.js";
 import type * as FunctionSpec from "./FunctionSpec.js";
 import * as Lazy from "./Lazy.js";
 import * as MiddlewareSpec from "./MiddlewareSpec.js";
+import { getFunctionReference } from "./RefInternal.js";
 import type * as RuntimeAndFunctionType from "./RuntimeAndFunctionType.js";
 
 export const TypeId = "~@confect/core/Ref";
@@ -41,7 +42,9 @@ export interface Base<
     : (args: Args_) => void;
   readonly "~Returns": Returns_;
   readonly "~Error": Error_;
+  readonly functionType?: RuntimeAndFunctionType_["functionType"];
   readonly convexFunctionName: string;
+  readonly reservedArgument?: string;
   /**
    * Preserved for component references and function handles, which have no
    * local name.
@@ -447,14 +450,19 @@ export const make = <
         ({
           [TypeId]: TypeId,
           _tag: "Convex",
+          functionType: functionSpec.runtimeAndFunctionType.functionType,
           convexFunctionName,
         }) as Any,
     ),
     Match.tag("Confect", (provenance): Any =>
-      fromProvenance(convexFunctionName, provenance, [
-        ...groupMiddlewareAttachments,
-        ...functionSpec.middlewareAttachments,
-      ]),
+      fromProvenance(
+        convexFunctionName,
+        provenance,
+        [...groupMiddlewareAttachments, ...functionSpec.middlewareAttachments],
+        undefined,
+        functionSpec.runtimeAndFunctionType.functionType,
+        functionSpec.reservedArgument,
+      ),
     ),
     Match.exhaustive,
   ) as FromFunctionSpec<
@@ -476,11 +484,15 @@ export const fromProvenance = (
   provenance: FunctionProvenance.AnyConfect,
   middlewareAttachments: ReadonlyArray<MiddlewareAttachment.MiddlewareAttachment>,
   functionReference?: ConvexFunctionReference<any, any>,
+  functionType?: "query" | "mutation" | "action",
+  reservedArgument?: string,
 ): AnyConfect => {
   const ref = {
     [TypeId]: TypeId as TypeId,
     _tag: "Confect" as const,
+    ...(functionType === undefined ? {} : { functionType }),
     convexFunctionName,
+    ...(reservedArgument === undefined ? {} : { reservedArgument }),
     ...(functionReference === undefined ? {} : { functionReference }),
     kind: provenance.kind,
     middlewareAttachments,
@@ -501,27 +513,6 @@ export const fromProvenance = (
 export const getConvexFunctionName = (ref: Any): string =>
   ref.convexFunctionName;
 
-const functionReferenceCache = new Map<string, FunctionReference<Any>>();
-
-export const getFunctionReference = <Ref_ extends Any>(
-  ref: Ref_,
-): FunctionReference<Ref_> => {
-  if (ref.functionReference !== undefined) {
-    return ref.functionReference as FunctionReference<Ref_>;
-  }
-  const convexFunctionName = getConvexFunctionName(ref);
-
-  const cached = functionReferenceCache.get(convexFunctionName);
-  if (cached !== undefined) {
-    return cached as FunctionReference<Ref_>;
-  }
-
-  const functionReference = makeFunctionReference(convexFunctionName);
-  functionReferenceCache.set(convexFunctionName, functionReference);
-
-  return functionReference as FunctionReference<Ref_>;
-};
-
 /**
  * Adapt a native reference without assigning Confect codecs or typed errors.
  */
@@ -532,6 +523,7 @@ export const fromFunctionReference = <
   Returns_,
 >(
   functionReference: ConvexFunctionReference<Type, Visibility, Args_, Returns_>,
+  functionType?: NoInfer<Type>,
 ): ConvexRef<
   Extract<
     RuntimeAndFunctionType.RuntimeAndFunctionType,
@@ -545,6 +537,7 @@ export const fromFunctionReference = <
   return {
     [TypeId]: TypeId,
     _tag: "Convex",
+    ...(functionType === undefined ? {} : { functionType }),
     convexFunctionName:
       address.name ??
       address.reference ??

package/src/RefInternal.ts

@@ -0,0 +1,26 @@
+import { makeFunctionReference } from "convex/server";
+import type * as Ref from "./Ref.js";
+
+const functionReferenceCache = new Map<
+  string,
+  Ref.FunctionReference<Ref.Any>
+>();
+
+export const getFunctionReference = <Ref_ extends Ref.Any>(
+  ref: Ref_,
+): Ref.FunctionReference<Ref_> => {
+  if (ref.functionReference !== undefined) {
+    return ref.functionReference as Ref.FunctionReference<Ref_>;
+  }
+  const convexFunctionName = ref.convexFunctionName;
+
+  const cached = functionReferenceCache.get(convexFunctionName);
+  if (cached !== undefined) {
+    return cached as Ref.FunctionReference<Ref_>;
+  }
+
+  const functionReference = makeFunctionReference(convexFunctionName);
+  functionReferenceCache.set(convexFunctionName, functionReference);
+
+  return functionReference as Ref.FunctionReference<Ref_>;
+};

package/src/SchemaToValidator.ts

@@ -46,10 +46,12 @@ import type {
 export const compileArgsSchema = <ConfectValue, ConvexValue>(
   argsSchema: Schema.Codec<ConfectValue, ConvexValue>,
   scope: IdScope.IdScope = IdScope.app,
+  reservedArgument?: string,
+  functionName?: string,
 ): PropertyValidators => {
   const ast = Schema.toEncoded(argsSchema).ast;
 
-  return pipe(
+  const validators = pipe(
     ast,
     Match.value,
     Match.tag("Objects", (objectsAst) =>
@@ -60,8 +62,27 @@ export const compileArgsSchema = <ConfectValue, ConvexValue>(
     Match.orElse(() => Effect.fail(new TopLevelMustBeObjectError())),
     Effect.runSync,
   );
+  if (reservedArgument === undefined) return validators;
+  if (Object.hasOwn(validators, reservedArgument)) {
+    throw new ReservedArgumentCollision({
+      functionName,
+      argument: reservedArgument,
+    });
+  }
+  return { ...validators, [reservedArgument]: v.optional(v.any()) };
 };
 
+export class ReservedArgumentCollision extends Data.TaggedError(
+  "ReservedArgumentCollision",
+)<{
+  readonly functionName: string | undefined;
+  readonly argument: string;
+}> {
+  override get message() {
+    return `${this.functionName} declares the argument "${this.argument}", which its profile reserves. Rename the argument.`;
+  }
+}
+
 // Returns
 
 export const compileReturnsSchema = <ConfectValue, ConvexValue>(

package/src/index.ts

@@ -1,3 +1,4 @@
+export * as ActionCall from "./ActionCall.js";
 export * as Callback from "./Callback.js";
 export * as FunctionProvenance from "./FunctionProvenance.js";
 export * as FunctionSpec from "./FunctionSpec.js";
@@ -13,11 +14,13 @@ export * as GroupSpec from "./GroupSpec.js";
 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 MiddlewareAttachment from "./MiddlewareAttachment.js";
 export * as MiddlewareSpec from "./MiddlewareSpec.js";
 export * as PaginationError from "./PaginationError.js";
 export * as PaginationOptions from "./PaginationOptions.js";
 export * as PaginationResult from "./PaginationResult.js";
+export * as Profile from "./Profile.js";
 export * as Ref from "./Ref.js";
 export * as Refs from "./Refs.js";
 export * as RuntimeAndFunctionType from "./RuntimeAndFunctionType.js";

package/src/internal/scalarDocs.ts

@@ -0,0 +1,72 @@
+import * as Effect from "effect/Effect";
+import * as HttpRouter from "effect/http/HttpRouter";
+import * as HttpServerResponse from "effect/http/HttpServerResponse";
+import type * as HttpApi from "effect/http-api/HttpApi";
+import type * as HttpApiGroup from "effect/http-api/HttpApiGroup";
+import * as OpenApi from "effect/http-api/OpenApi";
+
+const escape = (value: string) =>
+  value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+
+const escapeAttribute = (value: string) =>
+  escape(value).replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+
+const escapeJson = (value: unknown) =>
+  JSON.stringify(value)
+    .replaceAll("<", "\\u003c")
+    .replaceAll("\u2028", "\\u2028")
+    .replaceAll("\u2029", "\\u2029");
+
+// WORKAROUND: Effect 4.0.6's HttpApiScalar module imports its inline Scalar
+// script dynamically, and Convex's bundler then splits a schema that reaches it
+// into an imported chunk, which Convex refuses. This copies `layerCdn`'s page
+// byte for byte. Remove when `checkSchemaBundle.mjs` passes with
+// `HttpApiScalar.layerCdn` restored.
+export const scalarDocs = <
+  Id extends string,
+  Groups extends HttpApiGroup.Constraint,
+>(
+  api: HttpApi.HttpApi<Id, Groups>,
+  path: `/${string}`,
+) =>
+  HttpRouter.use((router) => {
+    let response: HttpServerResponse.HttpServerResponse | undefined;
+    return router.add(
+      "GET",
+      path,
+      Effect.sync(() => {
+        if (response !== undefined) return response;
+        const spec = OpenApi.fromApi(api);
+        const description = (tag: string) =>
+          !spec.info.description
+            ? ""
+            : `<meta name="${tag}" content="${escapeAttribute(spec.info.description)}"/>`;
+        response = HttpServerResponse.html(`<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>${escape(spec.info.title)}</title>
+    ${description("description")}
+    ${description("og:description")}
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="api-reference-container"></div>
+    <script src="${escapeAttribute("https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest/dist/browser/standalone.min.js")}" crossorigin></script>
+    <script>
+      window.Scalar.createApiReference(document.getElementById('api-reference-container'), {
+        ...${escapeJson({ _integration: "html" })},
+        content: ${escapeJson(spec)}
+      })
+    </script>
+  </body>
+</html>`);
+        return response;
+      }),
+    );
+  });