@confect/core 10.0.0-next.20 → 10.0.0-next.22

package/src/Ref.ts

@@ -1,3 +1,4 @@
+import type * as MiddlewareAttachment from "./MiddlewareAttachment";
 import type {
   DefaultFunctionArgs,
   FunctionReference as ConvexFunctionReference,
@@ -102,6 +103,7 @@ interface ConfectRefWithTypes<
   readonly returns: Schema.Codec<any, any>;
   readonly kind: FunctionProvenance.ConfectKind;
   readonly middlewareSpecs: ReadonlyArray<MiddlewareSpec.AnyMiddlewareSpec>;
+  readonly middlewareAttachments: ReadonlyArray<MiddlewareAttachment.MiddlewareAttachment>;
   readonly error?: Schema.Codec<any, any>;
 }
 
@@ -322,7 +324,7 @@ export const make = <FunctionSpec_ extends FunctionSpec.AnyWithProps>(
    */
   convexFunctionNamespace: string,
   functionSpec: FunctionSpec_,
-  groupMiddlewareSpecs: ReadonlyArray<MiddlewareSpec.AnyMiddlewareSpec> = [],
+  groupMiddlewareAttachments: ReadonlyArray<MiddlewareAttachment.MiddlewareAttachment> = [],
 ): FromFunctionSpec<FunctionSpec_> => {
   const convexFunctionName = `${convexFunctionNamespace}:${functionSpec.name}`;
 
@@ -340,10 +342,13 @@ export const make = <FunctionSpec_ extends FunctionSpec.AnyWithProps>(
         _tag: "Confect" as const,
         convexFunctionName,
         kind: provenance.kind,
-        middlewareSpecs: [
-          ...groupMiddlewareSpecs,
-          ...functionSpec.middlewareSpecs,
+        middlewareAttachments: [
+          ...groupMiddlewareAttachments,
+          ...functionSpec.middlewareAttachments,
         ],
+        get middlewareSpecs() {
+          return this.middlewareAttachments.map(({ spec }) => spec);
+        },
       };
 
       Lazy.defineProperty(ref, "args", () => provenance.args);
@@ -514,7 +519,7 @@ const errorSchemaOf = (ref: Any): Option.Option<Schema.Codec<any, any>> =>
   );
 
 /**
- * Decode `encodedError` against the ref's error schema — the function's
+ * Decode `encodedError` against the ref's error schema—the function's
  * declared `error` schema unioned with its covering middlewares' error
  * schemas. Returns `None` if the ref declares no typed error at all (Confect
  * ref without an `error` schema and without failing middleware, or a
@@ -529,22 +534,21 @@ export const decodeError = <Ref_ extends Any>(
   Option.match(errorSchemaOf(ref), {
     onNone: () => Effect.succeed(Option.none<Error<Ref_>>()),
     onSome: (schema) =>
-      Effect.map(
+      Effect.asSome(
         Schema.decodeUnknownEffect(schema)(encodedError),
-        Option.some,
       ) as Effect.Effect<Option.Option<Error<Ref_>>, Schema.SchemaError>,
   });
 
 /**
  * Synchronous counterpart to `decodeError`. Returns `None` when the value is
- * not this ref's typed error — either because the ref declares no `error`
+ * not this ref's typed error—either because the ref declares no `error`
  * schema, or because `encodedError` doesn't match the one it declares.
  *
  * The second case is reachable in normal operation: Convex raises its own
  * `ConvexError`s (an `InvalidCursor` pagination error, for instance), and
  * those never match a user-declared error schema. Callers pair this with a
  * fallback that surfaces the original error, so failing to decode must not
- * throw — a `ParseError` here would replace the real error with an opaque one
+ * throw—a `ParseError` here would replace the real error with an opaque one
  * and lose the only useful diagnostic. Hence the `Option` suffix rather than
  * `Sync`, matching `Schema.decodeUnknownOption`: the sibling `*Sync` helpers
  * in this module all throw on a parse failure, and this one deliberately
@@ -585,8 +589,7 @@ const paginatedKind = (ref: AnyConfect): FunctionProvenance.Paginated =>
   );
 
 /**
- * Encode the args of a paginated query ref via its user-args schema —
- * `paginationOpts` is excluded, since the pagination protocol fields are
+ * Encode the args of a paginated query ref via its user-args schema—`paginationOpts` is excluded, since the pagination protocol fields are
  * managed by the client (e.g. `usePaginatedQuery` from `convex/react`), not by
  * the caller. Requires a ref built with `FunctionSpec.publicPaginatedQuery`
  * (or `internalPaginatedQuery`).
@@ -630,7 +633,10 @@ export const decodePaginationPageSync = <Ref_ extends AnyPublicPaginatedQuery>(
  * `mapUnknownError` to be turned into a typed `E`, or surfaced as a defect when
  * no handler is provided.
  */
-export const runWithCodec = <Ref_ extends Any, E = never>(
+export const runWithCodec = Effect.fnUntraced(function* <
+  Ref_ extends Any,
+  E = never,
+>(
   ref: Ref_,
   args: Args<Ref_>,
   call: (
@@ -638,29 +644,28 @@ export const runWithCodec = <Ref_ extends Any, E = never>(
     encodedArgs: unknown,
   ) => PromiseLike<unknown>,
   mapUnknownError?: (error: unknown) => E,
-): Effect.Effect<Returns<Ref_>, E | Error<Ref_> | Schema.SchemaError> =>
-  Effect.gen(function* () {
-    const functionReference = getFunctionReference(ref);
-    const invoke = (
-      encodedArgs: unknown,
-    ): Effect.Effect<unknown, Error<Ref_> | E> =>
-      Effect.tryPromise({
-        try: () => Promise.resolve(call(functionReference, encodedArgs)),
-        catch: (error): Error<Ref_> | E => {
-          if (isConvexError(error)) {
-            const decoded = decodeErrorOption(ref, error.data);
-            if (Option.isSome(decoded)) {
-              return decoded.value;
-            }
-          }
-          if (mapUnknownError !== undefined) {
-            return mapUnknownError(error);
+): Effect.fn.Return<Returns<Ref_>, E | Error<Ref_> | Schema.SchemaError> {
+  const functionReference = getFunctionReference(ref);
+  const invoke = (
+    encodedArgs: unknown,
+  ): Effect.Effect<unknown, Error<Ref_> | E> =>
+    Effect.tryPromise({
+      try: () => Promise.resolve(call(functionReference, encodedArgs)),
+      catch: (error): Error<Ref_> | E => {
+        if (isConvexError(error)) {
+          const decoded = decodeErrorOption(ref, error.data);
+          if (Option.isSome(decoded)) {
+            return decoded.value;
           }
-          throw error;
-        },
-      });
-
-    const encodedArgs = yield* encodeArgs(ref, args);
-    const encodedReturns = yield* invoke(encodedArgs);
-    return yield* decodeReturns(ref, encodedReturns);
-  });
+        }
+        if (mapUnknownError !== undefined) {
+          return mapUnknownError(error);
+        }
+        throw error;
+      },
+    });
+
+  const encodedArgs = yield* encodeArgs(ref, args);
+  const encodedReturns = yield* invoke(encodedArgs);
+  return yield* decodeReturns(ref, encodedReturns);
+});

package/src/Refs.ts

@@ -126,7 +126,7 @@ const makeHelper = (
           Ref.make(
             currentConvexFunctionNamespace,
             function_,
-            group.middlewareSpecs,
+            group.middlewareAttachments,
           ),
         ),
         (_subGroup, _function) => {

package/src/SchemaToValidator.ts

@@ -91,7 +91,8 @@ export const compileTableSchema = <TableSchema extends Schema.Codec<any, any>>(
     Match.value,
     Match.tag("Objects", ({ indexSignatures }) =>
       Array.isReadonlyArrayEmpty(indexSignatures)
-        ? (compileAst(ast) as Effect.Effect<any>)
+        ? // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- The return type is derived from the input schema and cannot be recovered from the runtime AST.
+          (compileAst(ast) as Effect.Effect<any>)
         : Effect.fail(new IndexSignaturesAreNotSupportedError()),
     ),
     Match.tag("Union", (unionAst) => compileAst(unionAst)),
@@ -345,6 +346,7 @@ export const compileAst = (
         Match.tag("Unknown", "Any", () => Effect.succeed(v.any())),
         Match.tag("Declaration", (declaration) =>
           Effect.mapBoth(
+            // oxlint-disable-next-line effecttsgo/any-unknown-in-error-context -- Codec inputs are context-free, but Effect's SchemaAST.DeclarationRun erases their requirements to `any`.
             declaration.run(declaration.typeParameters)(
               new ArrayBuffer(0),
               declaration,
@@ -382,23 +384,27 @@ export const compileAst = (
 const handleUnion = (
   { types }: SchemaAST.Union,
   isOptionalPropertyOfTypeLiteral: boolean,
-) =>
-  Effect.gen(function* () {
-    const members = isOptionalPropertyOfTypeLiteral
-      ? Array.filter(types, Predicate.not(SchemaAST.isUndefined))
-      : types;
-
-    const [firstValidator, secondValidator, ...restValidators] =
-      yield* Effect.all(Array.map(members, (type) => compileAst(type)));
-
-    if (firstValidator === undefined) {
-      return yield* new EmptyUnionIsNotSupportedError();
-    } else if (secondValidator === undefined) {
-      return firstValidator;
-    } else {
-      return v.union(firstValidator, secondValidator, ...restValidators);
-    }
-  });
+) => handleUnionTypes(types, isOptionalPropertyOfTypeLiteral);
+
+const handleUnionTypes = Effect.fnUntraced(function* (
+  types: SchemaAST.Union["types"],
+  isOptionalPropertyOfTypeLiteral: boolean,
+) {
+  const members = isOptionalPropertyOfTypeLiteral
+    ? Array.filter(types, Predicate.not(SchemaAST.isUndefined))
+    : types;
+
+  const [firstValidator, secondValidator, ...restValidators] =
+    yield* Effect.all(Array.map(members, (type) => compileAst(type)));
+
+  if (firstValidator === undefined) {
+    return yield* new EmptyUnionIsNotSupportedError();
+  } else if (secondValidator === undefined) {
+    return firstValidator;
+  } else {
+    return v.union(firstValidator, secondValidator, ...restValidators);
+  }
+});
 
 const handleObjects = (objectsAst: SchemaAST.Objects) =>
   pipe(
@@ -429,35 +435,40 @@ const handleObjects = (objectsAst: SchemaAST.Objects) =>
   );
 
 const handleArrays = ({ elements, rest }: SchemaAST.Arrays) =>
-  Effect.gen(function* () {
-    const [f, s, ...r] = elements;
+  handleArrayElements(elements, rest);
 
-    const elementToValidator = (element: SchemaAST.AST) =>
-      SchemaAST.isOptional(element)
-        ? Effect.fail(new OptionalTupleElementsAreNotSupportedError())
-        : compileAst(element);
+const handleArrayElements = Effect.fnUntraced(function* (
+  elements: SchemaAST.Arrays["elements"],
+  rest: SchemaAST.Arrays["rest"],
+) {
+  const [f, s, ...r] = elements;
+
+  const elementToValidator = (element: SchemaAST.AST) =>
+    SchemaAST.isOptional(element)
+      ? Effect.fail(new OptionalTupleElementsAreNotSupportedError())
+      : compileAst(element);
+
+  const arrayItemsValidator = yield* f === undefined
+    ? pipe(
+        rest,
+        Array.head,
+        Option.match({
+          onNone: () => Effect.fail(new EmptyTupleIsNotSupportedError()),
+          onSome: (type) => compileAst(type),
+        }),
+      )
+    : s === undefined
+      ? elementToValidator(f)
+      : Effect.gen(function* () {
+          const firstValidator = yield* elementToValidator(f);
+          const secondValidator = yield* elementToValidator(s);
+          const restValidators = yield* Effect.forEach(r, elementToValidator);
+
+          return v.union(firstValidator, secondValidator, ...restValidators);
+        });
 
-    const arrayItemsValidator = yield* f === undefined
-      ? pipe(
-          rest,
-          Array.head,
-          Option.match({
-            onNone: () => Effect.fail(new EmptyTupleIsNotSupportedError()),
-            onSome: (type) => compileAst(type),
-          }),
-        )
-      : s === undefined
-        ? elementToValidator(f)
-        : Effect.gen(function* () {
-            const firstValidator = yield* elementToValidator(f);
-            const secondValidator = yield* elementToValidator(s);
-            const restValidators = yield* Effect.forEach(r, elementToValidator);
-
-            return v.union(firstValidator, secondValidator, ...restValidators);
-          });
-
-    return v.array(arrayItemsValidator);
-  });
+  return v.array(arrayItemsValidator);
+});
 
 const handlePropertySignatures = (objectsAst: SchemaAST.Objects) =>
   pipe(

package/src/Spec.ts

@@ -10,7 +10,7 @@ export const isSpec = (u: unknown): u is AnyWithProps =>
 
 /**
  * A Confect spec: a flat container of function groups. Groups may be of any
- * runtime — a group built with `GroupSpec.makeNode()` (a Node action group) sits
+ * runtime—a group built with `GroupSpec.makeNode()` (a Node action group) sits
  * alongside `GroupSpec.make()` groups in the same namespace. The runtime of a
  * group lives on the group itself (`GroupSpec.runtime`) and on each function's
  * `RuntimeAndFunctionType`; the spec does not carry a runtime of its own.

package/src/SystemFields.ts

@@ -58,9 +58,9 @@ const splitSystemFields = (input: { [key: PropertyKey]: unknown }) => {
  * output. Transformations construct fresh objects, so without this the system
  * fields would be dropped at every transformation step.
  */
-const wrapGetter = (
-  getter: SchemaGetter.Getter<any, any, any>,
-): SchemaGetter.Getter<any, any, any> =>
+const wrapGetter = <R>(
+  getter: SchemaGetter.Getter<any, any, R>,
+): SchemaGetter.Getter<any, any, R> =>
   new SchemaGetter.Getter((input, options) => {
     if (Option.isNone(input) || !Predicate.isObject(input.value)) {
       return getter.run(input, options);
@@ -93,8 +93,8 @@ const wrapTransformation = (
 
 /**
  * Builds an AST walker that adds the given system-field property signatures to
- * every object node of a schema's AST — including each step of its encoding
- * chain — wrapping transformations so the fields survive them.
+ * every object node of a schema's AST—including each step of its encoding
+ * chain—wrapping transformations so the fields survive them.
  */
 const makeExtendAst = (
   systemPropertySignatures: ReadonlyArray<SchemaAST.PropertySignature>,
@@ -113,7 +113,7 @@ const makeExtendAst = (
     if (SchemaAST.isUnion(ast)) {
       return new SchemaAST.Union(
         Array.map(ast.types, extendAst),
-        ast.mode,
+        ast.options,
         ast.annotations,
         ast.checks,
         ast.encoding === undefined ? undefined : extendEncoding(ast.encoding),
@@ -156,9 +156,8 @@ const makeExtendAst = (
  *
  * A plain `Struct` gains the fields via `Schema.fieldsAssign` and a `Union`
  * has them distributed across its members, preserving the schema's
- * `Struct`/`Union` structure. Any other object-shaped schema — one built with
- * `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a suspended schema
- * — is extended at the AST level: every object node in its encoding chain
+ * `Struct`/`Union` structure. Any other object-shaped schema—one built with
+ * `Schema.decodeTo`/`Schema.encodeKeys`, a branded struct, a suspended schema—is extended at the AST level: every object node in its encoding chain
  * gains the system fields, and each transformation is wrapped so the fields
  * bypass the user-defined getters. Schemas that do not resolve to an object
  * shape at every step (such as `Schema.Class`, whose decoded values are class
@@ -264,7 +263,7 @@ export type ExtendWithSystemFields<
 
 /**
  * The decoded/encoded document shape: a table's fields plus Convex's system
- * fields. Deliberately a bare intersection (no `Expand`/`Simplify`) — flattening
+ * fields. Deliberately a bare intersection (no `Expand`/`Simplify`)—flattening
  * it with a homomorphic mapped type collapses to `{ [x: string]: any }` when
  * `Document` is still an unresolved generic, which breaks structural
  * comparability in the database reader/writer plumbing.

package/src/Table.ts

@@ -86,7 +86,7 @@ export type AnyWithProps = Table<
 // (`.index`, `.searchIndex`, `.vectorIndex`) live here and return new
 // `UnnamedTable`s, accumulating plain index metadata records. The
 // user-supplied `lazyFields` callback is just carried through until first
-// access of `Fields` / `Doc` on a bound table. The codegen pipeline emits a
+// access of `Fields`/`Doc` on a bound table. The codegen pipeline emits a
 // wrapper file per user-authored table that simply invokes the unnamed
 // callable with the filename basename.
 
@@ -241,7 +241,7 @@ export type TablesRecord<Tables extends AnyWithProps> = {
 // spread of the metadata records) and never invokes the callback. Binding
 // via `unnamed(tableName)` installs lazy memoised getters for `Fields` and
 // `Doc` via `Lazy.defineProperty`, so the first access materialises the
-// value and replaces the getter with a plain data property — second-and-
+// value and replaces the getter with a plain data property—second-and-
 // subsequent accesses are observably indistinguishable from a plain
 // property and avoid all function-call overhead.
 

package/src/index.ts

@@ -5,6 +5,7 @@ export * as GroupPath from "./GroupPath";
 export * as GroupSpec from "./GroupSpec";
 export * as Identifier from "./Identifier";
 export * as Lazy from "./Lazy";
+export * as MiddlewareAttachment from "./MiddlewareAttachment";
 export * as MiddlewareSpec from "./MiddlewareSpec";
 export * as PaginationError from "./PaginationError";
 export * as PaginationOptions from "./PaginationOptions";