@confect/core 10.0.0-next.21 → 10.0.0-next.23

package/src/Ref.ts

@@ -1,3 +1,4 @@
+import type * as MiddlewareAttachment from "./MiddlewareAttachment";
 import type {
   DefaultFunctionArgs,
   FunctionReference as ConvexFunctionReference,
@@ -35,8 +36,8 @@ export interface Base<
 
 /**
  * A reference to a single Convex function, as callers see it: the wire name
- * plus the data needed to encode args, decode returns, and decode typed
- * errors. A ref is one of two shapes, keyed by the spec's provenance.
+ * plus the data needed to encode args, decode returns, and decode typed errors.
+ * A ref is one of two shapes, keyed by the spec's provenance.
  */
 export type Ref<
   RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
@@ -80,8 +81,8 @@ export type ConfectRef<
 /**
  * Internal form used while mapping a spec to a ref. Supplying the already
  * derived value types avoids repeatedly expanding `Schema.Struct` for every
- * leaf in a generated ref tree; the public `ConfectRef` alias still derives
- * the same values from its fields and schemas.
+ * leaf in a generated ref tree; the public `ConfectRef` alias still derives the
+ * same values from its fields and schemas.
  */
 interface ConfectRefWithTypes<
   RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
@@ -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>;
 }
 
@@ -123,7 +125,9 @@ export interface ConvexRef<
 
 export type Any = Ref<any, any, any, any, any>;
 
-/** Erased Confect-provenance ref used by provenance-specific APIs. */
+/**
+ * Erased Confect-provenance ref used by provenance-specific APIs.
+ */
 export type AnyConfect = Extract<Any, { readonly _tag: "Confect" }>;
 
 export type AnyInternal = Ref<any, "internal", any, any, any>;
@@ -226,7 +230,9 @@ export type Args<Ref_> = Ref_ extends { readonly "~Args": infer Args_ }
   ? Args_
   : never;
 
-/** The field map captured by a Confect-provenance ref. */
+/**
+ * The field map captured by a Confect-provenance ref.
+ */
 export type ArgsFields<Ref_> = Ref_ extends {
   readonly _tag: "Confect";
   readonly args: {
@@ -236,7 +242,9 @@ export type ArgsFields<Ref_> = Ref_ extends {
   ? ArgsFields_
   : never;
 
-/** The assembled args schema carried by a Confect-provenance ref. */
+/**
+ * The assembled args schema carried by a Confect-provenance ref.
+ */
 export type ArgsSchema<Ref_> = Ref_ extends {
   readonly _tag: "Confect";
   readonly args: infer ArgsSchema_ extends FunctionProvenance.AnyArgsSchema;
@@ -322,7 +330,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 +348,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);
@@ -476,11 +487,11 @@ export const isConvexError = (error: unknown): error is ConvexError<Value> =>
 /**
  * Build a callback-style handler that decodes the ref's typed error from a
  * caught `ConvexError`, or else forwards the value to `mapUnknownError`. The
- * fallback is also invoked when the input *is* a `ConvexError` but the ref
- * doesn't declare a typed-error schema—by definition such a value falls
- * outside the ref's error contract. Useful when adapting non-Effect APIs (e.g.
- * emitter callbacks for streamed subscriptions) to the same error semantics
- * that `runWithCodec` provides.
+ * fallback is also invoked when the input _is_ a `ConvexError` but the ref
+ * doesn't declare a typed-error schema—by definition such a value falls outside
+ * the ref's error contract. Useful when adapting non-Effect APIs (e.g. emitter
+ * callbacks for streamed subscriptions) to the same error semantics that
+ * `runWithCodec` provides.
  */
 export const decodeErrorOrElse =
   <Ref_ extends Any, E>(ref: Ref_, mapUnknownError: (error: unknown) => E) =>
@@ -514,13 +525,13 @@ const errorSchemaOf = (ref: Any): Option.Option<Schema.Codec<any, any>> =>
   );
 
 /**
- * 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
- * Convex-provenance ref)—by definition there's nothing to decode the value
- * into, and the caller is responsible for deciding what to do (typically:
- * surface the original value as a defect).
+ * 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 Convex-provenance ref)—by
+ * definition there's nothing to decode the value into, and the caller is
+ * responsible for deciding what to do (typically: surface the original value as
+ * a defect).
  */
 export const decodeError = <Ref_ extends Any>(
   ref: Ref_,
@@ -529,26 +540,24 @@ 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`
- * schema, or because `encodedError` doesn't match the one it declares.
+ * 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
- * 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
- * doesn't.
+ * `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 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 doesn't.
  */
 export const decodeErrorOption = <Ref_ extends Any>(
   ref: Ref_,
@@ -585,11 +594,11 @@ 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`).
+ * the caller. Requires a ref built with `FunctionSpec.publicPaginatedQuery` (or
+ * `internalPaginatedQuery`).
  */
 export const encodePaginatedQueryArgsSync = <
   Ref_ extends AnyPublicPaginatedQuery,
@@ -630,7 +639,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 +650,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

@@ -6,7 +6,7 @@ import type * as FunctionSpec from "./FunctionSpec";
 import type * as GroupSpec from "./GroupSpec";
 import type * as MiddlewareSpec from "./MiddlewareSpec";
 import * as Ref from "./Ref";
-import type * as Spec from "./Spec";
+import * as Spec from "./Spec";
 
 export type Refs<
   Spec_ extends Spec.AnyWithProps,
@@ -98,7 +98,7 @@ type Any =
 export const make = <Spec_ extends Spec.AnyWithProps>(
   spec: Spec_,
 ): FromSpec<Spec_> => {
-  const refs = makeHelper(spec.groups);
+  const refs = makeHelper(Spec.groups(spec));
   return {
     public: refs as Refs<Spec_, Ref.AnyPublic>,
     internal: refs as Refs<Spec_, Ref.AnyInternal>,
@@ -126,7 +126,7 @@ const makeHelper = (
           Ref.make(
             currentConvexFunctionNamespace,
             function_,
-            group.middlewareSpecs,
+            group.middlewareAttachments,
           ),
         ),
         (_subGroup, _function) => {

package/src/SchemaToValidator.ts

@@ -384,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(
@@ -431,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

@@ -1,5 +1,6 @@
 import * as Predicate from "effect/Predicate";
 import * as Record from "effect/Record";
+import * as Struct from "effect/Struct";
 import * as GroupSpec from "./GroupSpec";
 
 export const TypeId = "~@confect/core/Spec";
@@ -10,66 +11,76 @@ 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.
  */
-export interface Spec<Groups_ extends GroupSpec.AnyWithProps = never> {
-  readonly [TypeId]: TypeId;
-  readonly groups: {
-    [GroupName in GroupSpec.Name<Groups_>]: GroupSpec.WithName<
-      Groups_,
-      GroupName
-    >;
-  };
-  readonly "~Groups": Groups_;
+export interface Spec<
+  Groups_ extends Record.ReadonlyRecord<string, GroupSpec.AnyWithProps> = {},
+> {
+  readonly [TypeId]: Readonly<Groups_>;
 
   add<Group extends GroupSpec.AnyWithProps>(
     group: Group,
-  ): Spec<Groups_ | Group>;
+  ): Spec<
+    Struct.Assign<Groups_, Record.ReadonlyRecord<GroupSpec.Name<Group>, Group>>
+  >;
 
   addAt<const Name extends string, Group extends GroupSpec.AnyWithProps>(
     name: Name,
     group: Group,
-  ): Spec<Groups_ | GroupSpec.NamedAt<Group, Name>>;
+  ): Spec<
+    Struct.Assign<
+      Groups_,
+      Record.ReadonlyRecord<Name, GroupSpec.NamedAt<Group, Name>>
+    >
+  >;
 }
 
 export interface Any {
-  readonly [TypeId]: TypeId;
+  readonly [TypeId]: unknown;
 }
 
-export interface AnyWithProps extends Spec<GroupSpec.AnyWithProps> {}
+export interface AnyWithProps extends Any {
+  readonly [TypeId]: Record.ReadonlyRecord<string, GroupSpec.AnyWithProps>;
+}
 
-export type Groups<Spec_ extends AnyWithProps> = Spec_["~Groups"];
+export type Groups<Spec_ extends AnyWithProps> =
+  Spec_[TypeId][keyof Spec_[TypeId]];
 
-const Proto = {
-  [TypeId]: TypeId,
+/**
+ * The group record stored by a spec, with its precise member types.
+ */
+export const groups = <Spec_ extends AnyWithProps>(
+  self: Spec_,
+): Spec_[TypeId] => self[TypeId];
 
-  add<Group extends GroupSpec.AnyWithProps>(this: AnyWithProps, group: Group) {
-    return makeProto({
-      groups: Record.set(this.groups, group.name, group),
-    });
+const makeRecord = <
+  Groups_ extends Record.ReadonlyRecord<string, GroupSpec.AnyWithProps>,
+>(
+  record: Groups_,
+): Spec<Groups_> => ({
+  [TypeId]: record,
+  add<Group extends GroupSpec.AnyWithProps>(group: Group) {
+    return makeRecord(
+      Struct.assign(
+        record,
+        Record.singleton<GroupSpec.Name<Group>, Group>(group.name, group),
+      ),
+    );
   },
-
-  addAt<Group extends GroupSpec.AnyWithProps>(
-    this: AnyWithProps,
-    name: string,
+  addAt<const Name extends string, Group extends GroupSpec.AnyWithProps>(
+    name: Name,
     group: Group,
   ) {
-    return makeProto({
-      groups: Record.set(this.groups, name, GroupSpec.withName(name, group)),
-    });
+    return makeRecord(
+      Struct.assign(
+        record,
+        Record.singleton(name, GroupSpec.withName(name, group)),
+      ),
+    );
   },
-};
-
-const makeProto = <Groups_ extends GroupSpec.AnyWithProps>({
-  groups,
-}: {
-  groups: Record.ReadonlyRecord<string, Groups_>;
-}): Spec<Groups_> =>
-  Object.assign(Object.create(Proto), {
-    groups,
-  }) as Spec<Groups_>;
+});
 
-export const make = (): Spec => makeProto({ groups: {} });
+export const make = (): Spec => makeRecord({});

package/src/SystemFields.ts

@@ -13,7 +13,8 @@ import * as Struct from "effect/Struct";
 import * as GenericId from "./GenericId";
 
 /**
- * Produces a schema for Convex system fields. In Confect, system fields include `_id`.
+ * Produces a schema for Convex system fields. In Confect, system fields include
+ * `_id`.
  */
 export const SystemFields = <TableName extends string>(tableName: TableName) =>
   Schema.Struct({
@@ -93,8 +94,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 +114,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),
@@ -154,11 +155,11 @@ const makeExtendAst = (
 /**
  * Extend a table schema with Convex system fields.
  *
- * 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
+ * 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
  * 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
@@ -219,9 +220,9 @@ export const extendWithSystemFields = <
 };
 
 /**
- * Applies the system fields to a single struct, mirroring `Schema.fieldsAssign`.
- * Any other (already-extended or opaque) schema falls back to a `Codec` carrying
- * the system-field document shape.
+ * Applies the system fields to a single struct, mirroring
+ * `Schema.fieldsAssign`. Any other (already-extended or opaque) schema falls
+ * back to a `Codec` carrying the system-field document shape.
  */
 type ApplySystemFields<TableName extends string, S> =
   S extends Schema.Struct<infer Fields extends Schema.Struct.Fields>
@@ -241,10 +242,10 @@ type ApplySystemFields<TableName extends string, S> =
  * This mirrors the runtime {@link extendWithSystemFields}: a `Struct` gains the
  * system fields directly (matching `Schema.fieldsAssign`), and a `Union` has
  * them distributed across its members (matching
- * `union.mapMembers(Tuple.map(Schema.fieldsAssign(...)))`). The `Struct`/`Union`
- * structure is preserved rather than collapsed to a bare `Codec`; any other
- * schema falls back to a `Codec` carrying the system-field document shape,
- * matching the runtime's AST-level extension.
+ * `union.mapMembers(Tuple.map(Schema.fieldsAssign(...)))`). The
+ * `Struct`/`Union` structure is preserved rather than collapsed to a bare
+ * `Codec`; any other schema falls back to a `Codec` carrying the system-field
+ * document shape, matching the runtime's AST-level extension.
  */
 export type ExtendWithSystemFields<
   TableName extends string,
@@ -264,7 +265,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.
 
@@ -417,6 +417,7 @@ export const make = <const TableSchema_ extends Schema.Codec<any, any>>(
  * Extract all of the index field paths within a Convex `Validator`.
  *
  * This is used when declaring table indexes.
+ *
  * @public
  */
 type ExtractFieldPaths<T extends Validator<any, any, any>> =

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";