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

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

@@ -1,5 +1,8 @@
 import * as IdScope from "./IdScope.js";
+import type * as Callback from "./Callback.js";
+import { CallbackContract } from "./internal/annotations.js";
 import type {
+  CommitTsPlaceholder,
   GenericId as ConvexGenericId,
   PropertyValidators,
   Validator,
@@ -7,6 +10,7 @@ import type {
   VArray,
   VBoolean,
   VBytes,
+  VCommitTs,
   VFloat64,
   VId,
   VInt64,
@@ -30,6 +34,7 @@ import * as Schema from "effect/Schema";
 import * as SchemaAST from "effect/SchemaAST";
 import * as String from "effect/String";
 
+import * as CommitTs from "./CommitTs.js";
 import * as GenericId from "./GenericId.js";
 import type {
   IsAny,
@@ -46,10 +51,24 @@ 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 = Effect.runSync(compileArgsAst(ast, scope));
+  if (reservedArgument === undefined) return validators;
+  if (Object.hasOwn(validators, reservedArgument)) {
+    throw new ReservedArgumentCollision({
+      functionName,
+      argument: reservedArgument,
+    });
+  }
+  return { ...validators, [reservedArgument]: v.optional(v.any()) };
+};
+
+const compileArgsAst = (ast: SchemaAST.AST, scope: IdScope.IdScope) =>
+  pipe(
     ast,
     Match.value,
     Match.tag("Objects", (objectsAst) =>
@@ -58,9 +77,18 @@ export const compileArgsSchema = <ConfectValue, ConvexValue>(
         : Effect.fail(new IndexSignaturesAreNotSupportedError()),
     ),
     Match.orElse(() => Effect.fail(new TopLevelMustBeObjectError())),
-    Effect.runSync,
   );
-};
+
+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
 
@@ -113,6 +141,7 @@ export type ReadonlyValue =
   | bigint
   | boolean
   | ArrayBuffer
+  | CommitTsPlaceholder
   | ReadonlyArrayValue
   | ReadonlyRecordValue
   | null;
@@ -160,7 +189,9 @@ type ConvertValueToValidator<
           ? VBoolean<OptionalValue<boolean, Optionality>, Optionality>
           : VLiteral<OptionalValue<Vl, Optionality>, Optionality>
         : IsUnion<Vl> extends true
-          ? UnionValueToValidator<Vl, Optionality>
+          ? IsCommitTs<Vl> extends true
+            ? VCommitTs<OptionalValue<Vl, Optionality>, Optionality>
+            : UnionValueToValidator<Vl, Optionality>
           : [Vl] extends [number]
             ? [number] extends [Vl]
               ? VFloat64<OptionalValue<number, Optionality>, Optionality>
@@ -173,17 +204,25 @@ type ConvertValueToValidator<
                 ? StringValueToValidator<Vl, Optionality>
                 : [Vl] extends [ArrayBuffer]
                   ? VBytes<OptionalValue<ArrayBuffer, Optionality>, Optionality>
-                  : IsRecursive<Vl> extends true
-                    ? VAny<any, Optionality>
-                    : Vl extends ReadonlyArray<infer El>
-                      ? VArray<
-                          OptionalValue<MutableValue<El[]>, Optionality>,
-                          ConvertValueToValidator<El>,
-                          Optionality
-                        >
-                      : Vl extends object
-                        ? ObjectValueToValidator<Vl, Optionality>
-                        : never;
+                  : IsCommitTs<Vl> extends true
+                    ? VCommitTs<OptionalValue<Vl, Optionality>, Optionality>
+                    : IsRecursive<Vl> extends true
+                      ? VAny<any, Optionality>
+                      : Vl extends ReadonlyArray<infer El>
+                        ? VArray<
+                            OptionalValue<MutableValue<El[]>, Optionality>,
+                            ConvertValueToValidator<El>,
+                            Optionality
+                          >
+                        : Vl extends object
+                          ? ObjectValueToValidator<Vl, Optionality>
+                          : never;
+
+type IsCommitTs<Vl> = [Vl] extends [bigint | CommitTsPlaceholder]
+  ? [CommitTsPlaceholder] extends [Vl]
+    ? true
+    : false
+  : false;
 
 type StringValueToValidator<Vl, Optionality extends "required" | "optional"> =
   Vl extends ConvexGenericId<string>
@@ -239,11 +278,29 @@ export type UndefinedOrValueToValidator<Vl extends ReadonlyValue | undefined> =
 type UnionValueToValidator<Vl, Optionality extends "required" | "optional"> =
   IsRecursive<Vl> extends true
     ? VAny<any, Optionality>
-    : VUnion<
-        OptionalValue<MutableValue<Vl>, Optionality>,
-        ValueTupleToValidatorTuple<UnionToTuple<Vl>>,
-        Optionality
-      >;
+    : [Extract<Vl, CommitTsPlaceholder>] extends [never]
+      ? VUnion<
+          OptionalValue<MutableValue<Vl>, Optionality>,
+          ValueTupleToValidatorTuple<UnionToTuple<Vl>>,
+          Optionality
+        >
+      : CommitTsUnionValueToValidator<Vl, Optionality>;
+
+// A CommitTs is one validator at runtime, so its bigint and placeholder
+// branches collapse into a single member, as true and false do into VBoolean.
+// Only a union holding a placeholder comes here, because the infer that lets
+// the spread tuple satisfy VUnion's constraint makes other unions far costlier.
+type CommitTsUnionValueToValidator<
+  Vl,
+  Optionality extends "required" | "optional",
+> = [
+  VCommitTs,
+  ...ValueTupleToValidatorTuple<
+    UnionToTuple<Exclude<Vl, bigint | CommitTsPlaceholder>>
+  >,
+] extends infer VdMembers extends Validator<any, "required", any>[]
+  ? VUnion<OptionalValue<MutableValue<Vl>, Optionality>, VdMembers, Optionality>
+  : never;
 
 type ValueTupleToValidatorTuple<
   VlTuple extends readonly unknown[],
@@ -313,6 +370,7 @@ export const compileAst = (
   scope: IdScope.IdScope = IdScope.app,
 ): Effect.Effect<
   Validator<any, any, any>,
+  | TopLevelMustBeObjectError
   | UnsupportedSchemaTypeError
   | UnsupportedPropertySignatureKeyTypeError
   | IndexSignaturesAreNotSupportedError
@@ -320,8 +378,24 @@ export const compileAst = (
   | OptionalTupleElementsAreNotSupportedError
   | EmptyTupleIsNotSupportedError
   | EmptyUnionIsNotSupportedError
-> =>
-  isRecursive(ast)
+> => {
+  const contract = SchemaAST.resolveAt<Callback.Any>(CallbackContract)(ast);
+  if (contract !== undefined) {
+    return Effect.gen(function* () {
+      const args = yield* compileArgsAst(
+        Schema.toEncoded(contract.functionProvenance.args).ast,
+        scope,
+      );
+      const returns = yield* compileAst(
+        Schema.toEncoded(contract.functionProvenance.returns).ast,
+        false,
+        scope,
+      );
+      return v.function({ fnType: contract.functionType, args, returns });
+    });
+  }
+  if (CommitTs.isCommitTs(ast)) return Effect.succeed(v.commitTs());
+  return isRecursive(ast)
     ? Effect.succeed(v.any())
     : pipe(
         ast,
@@ -400,6 +474,7 @@ export const compileAst = (
         ),
         Match.exhaustive,
       );
+};
 
 const handleUnion = (
   { types }: SchemaAST.Union,