@gaganref/confect-core 10.3.1-fork.5 → 10.3.1-fork.50

package/src/ManifestSection.ts

@@ -0,0 +1,29 @@
+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>>;
+}
+
+export interface ManifestSection<Value = unknown> {
+  readonly owner: string;
+  readonly format: number;
+  describe(input: {
+    readonly path: string;
+    readonly spec: FunctionSpec.AnyWithProps;
+    readonly middleware: ReadonlyArray<MiddlewareSpec.AnyMiddlewareSpec>;
+  }): Value;
+  check?(
+    next: Data<Value>,
+    previous: unknown,
+  ): {
+    readonly errors: ReadonlyArray<string>;
+    readonly notes: ReadonlyArray<string>;
+  };
+}
+
+export interface Entry {
+  readonly key: string;
+  readonly section: ManifestSection;
+}

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

@@ -41,7 +41,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 +449,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 +483,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,
@@ -532,6 +543,7 @@ export const fromFunctionReference = <
   Returns_,
 >(
   functionReference: ConvexFunctionReference<Type, Visibility, Args_, Returns_>,
+  functionType?: NoInfer<Type>,
 ): ConvexRef<
   Extract<
     RuntimeAndFunctionType.RuntimeAndFunctionType,
@@ -545,6 +557,7 @@ export const fromFunctionReference = <
   return {
     [TypeId]: TypeId,
     _tag: "Convex",
+    ...(functionType === undefined ? {} : { functionType }),
     convexFunctionName:
       address.name ??
       address.reference ??

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;
+      }),
+    );
+  });