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

package/src/MiddlewareAttachment.ts

@@ -0,0 +1,106 @@
+import * as Data from "effect/Data";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import type * as MiddlewareSpec from "./MiddlewareSpec";
+
+export type MiddlewareAttachment<
+  MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec =
+    MiddlewareSpec.AnyMiddlewareSpec,
+> = MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec
+  ? {
+      readonly spec: MiddlewareSpec_;
+      readonly options: [MiddlewareSpec_["~Options"]] extends [never]
+        ? undefined
+        : MiddlewareSpec.Options<MiddlewareSpec_>;
+    }
+  : never;
+
+export type Args<MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec> = [
+  MiddlewareSpec_["~Options"],
+] extends [never]
+  ? []
+  : [options: MiddlewareSpec.Options<MiddlewareSpec_>];
+
+export type ValidationError = Data.TaggedEnum<{
+  InvalidOptions: {
+    readonly middlewareKey: string;
+    readonly location: string;
+    readonly attachmentIndex: number;
+  };
+  ConflictingSpecs: {
+    readonly middlewareKey: string;
+    readonly location: string;
+    readonly attachmentIndex: number;
+    readonly previousIndex: number;
+  };
+  EquivalentOptions: {
+    readonly middlewareKey: string;
+    readonly location: string;
+    readonly attachmentIndex: number;
+    readonly previousIndex: number;
+  };
+}>;
+
+export const ValidationError = Data.taggedEnum<ValidationError>();
+
+export const formatValidationError = ValidationError.$match({
+  InvalidOptions: ({ middlewareKey, location, attachmentIndex }) =>
+    `Middleware "${middlewareKey}" has invalid options at attachment ${attachmentIndex + 1} on ${location}`,
+  ConflictingSpecs: ({ middlewareKey, location }) =>
+    `Different middleware specs share key "${middlewareKey}" on ${location}`,
+  EquivalentOptions: ({
+    middlewareKey,
+    location,
+    attachmentIndex,
+    previousIndex,
+  }) =>
+    `Middleware "${middlewareKey}" has equivalent options at attachments ${previousIndex + 1} and ${attachmentIndex + 1} on ${location}`,
+});
+
+export const validateAll = (
+  attachments: ReadonlyArray<MiddlewareAttachment>,
+  location: string,
+): Result.Result<void, ValidationError> => {
+  for (const [index, attachment] of attachments.entries()) {
+    const schema = attachment.spec.options;
+    if (schema !== undefined && !Schema.is(schema)(attachment.options)) {
+      return Result.fail(
+        ValidationError.InvalidOptions({
+          middlewareKey: attachment.spec.key,
+          location,
+          attachmentIndex: index,
+        }),
+      );
+    }
+    const equivalent =
+      schema === undefined ? undefined : Schema.toEquivalence(schema);
+    for (const [previousIndex, previous] of attachments.entries()) {
+      if (previousIndex === index) break;
+      if (previous.spec.key !== attachment.spec.key) continue;
+      if (previous.spec !== attachment.spec) {
+        return Result.fail(
+          ValidationError.ConflictingSpecs({
+            middlewareKey: attachment.spec.key,
+            location,
+            attachmentIndex: index,
+            previousIndex,
+          }),
+        );
+      }
+      if (
+        equivalent === undefined ||
+        equivalent(previous.options, attachment.options)
+      ) {
+        return Result.fail(
+          ValidationError.EquivalentOptions({
+            middlewareKey: attachment.spec.key,
+            location,
+            attachmentIndex: index,
+            previousIndex,
+          }),
+        );
+      }
+    }
+  }
+  return Result.void;
+};

package/src/MiddlewareSpec.ts

@@ -38,31 +38,37 @@ export interface SuccessValue {
 
 /**
  * The wrap-style middleware implementation shape: receives the downstream
- * effect (the remaining middleware plus the function handler) and the
- * covered invocation's metadata, and returns the effect that runs in its
- * place.
+ * effect (the remaining middleware plus the function handler) and the covered
+ * invocation's metadata, and returns the effect that runs in its place.
  *
  * Mirrors `RpcMiddleware.RpcMiddleware` in Effect.
  */
-export interface MiddlewareImpl<Provides_, E, R> {
+export interface MiddlewareImpl<Provides_, E, R, Options_ = never> {
   (
     effect: Effect.Effect<SuccessValue, E | unhandled, Provides_>,
-    options: MiddlewareOptions,
+    context: MiddlewareOptions<Options_>,
   ): Effect.Effect<SuccessValue, E | unhandled, R>;
 }
 
-export interface MiddlewareOptions {
-  readonly name: string;
-  readonly functionType: FunctionType;
-  readonly functionVisibility: FunctionVisibility;
-  readonly args: unknown;
-}
+export type MiddlewareOptions<Options_ = never> = {
+  readonly invocation: {
+    readonly name: string;
+    readonly functionType: FunctionType;
+    readonly functionVisibility: FunctionVisibility;
+    readonly args: unknown;
+  };
+} & ([Options_] extends [never] ? unknown : { readonly options: Options_ });
 
-export interface AnyMiddlewareImpl extends MiddlewareImpl<any, any, any> {}
+export interface AnyMiddlewareImpl {
+  (
+    effect: Effect.Effect<SuccessValue, any, any>,
+    context: MiddlewareOptions | MiddlewareOptions<unknown>,
+  ): Effect.Effect<SuccessValue, any, any>;
+}
 
 /**
- * The class shape produced by {@link MiddlewareSpec}. Only the static side is ever
- * used — the class is a value-level carrier for the middleware's key, its
+ * The class shape produced by {@link MiddlewareSpec}. Only the static side is
+ * ever used—the class is a value-level carrier for the middleware's key, its
  * declared functionTypes, and its (lazily-evaluated) error schema, plus the
  * type-level `Provides`/`Error` metadata. It is deliberately not a
  * `Context.Tag`: implementations are registered through the group `Registry`
@@ -75,6 +81,7 @@ export interface MiddlewareSpec<
   Requires_,
   ErrorSchema_ extends Schema.Codec<any, any>,
   FunctionTypes_ extends FunctionType,
+  OptionsSchema_ extends Schema.Schema<any> = never,
 > {
   new (_: never): {
     readonly [TypeId]: TypeId;
@@ -84,11 +91,13 @@ export interface MiddlewareSpec<
   readonly key: Key_;
   readonly functionTypes: SupportedFunctionTypes;
   readonly error?: ErrorSchema_;
+  readonly options?: OptionsSchema_;
   readonly "~Provides": Provides_;
   readonly "~Requires": Requires_;
   readonly "~Error": ErrorSchema_;
   readonly "~FunctionTypes": FunctionTypes_;
   readonly "~Self": Self;
+  readonly "~Options": OptionsSchema_;
 }
 
 export interface AnyMiddlewareSpec {
@@ -96,12 +105,24 @@ export interface AnyMiddlewareSpec {
   readonly key: string;
   readonly functionTypes: SupportedFunctionTypes;
   readonly error?: Schema.Codec<any, any>;
+  readonly options?: Schema.Schema<any>;
   readonly "~Provides": any;
   readonly "~Requires": any;
   readonly "~Error": any;
   readonly "~FunctionTypes": FunctionType;
+  readonly "~Options": any;
 }
 
+export type Options<MiddlewareSpec_ extends AnyMiddlewareSpec> =
+  MiddlewareSpec_["~Options"]["Type"];
+
+export type WithoutOptions<MiddlewareSpec_ extends AnyMiddlewareSpec> =
+  MiddlewareSpec_ extends AnyMiddlewareSpec
+    ? [MiddlewareSpec_["~Options"]] extends [never]
+      ? MiddlewareSpec_
+      : never
+    : never;
+
 export type Key<MiddlewareSpec_ extends AnyMiddlewareSpec> =
   MiddlewareSpec_["key"];
 
@@ -111,8 +132,8 @@ export type Provides<MiddlewareSpec_ extends AnyMiddlewareSpec> =
     : never;
 
 /**
- * The services a middleware's implementation may consume from middleware
- * that runs earlier in the same chain (type-level only, like `provides`).
+ * The services a middleware's implementation may consume from middleware that
+ * runs earlier in the same chain (type-level only, like `provides`).
  */
 export type Requires<MiddlewareSpec_ extends AnyMiddlewareSpec> =
   MiddlewareSpec_ extends AnyMiddlewareSpec
@@ -143,16 +164,20 @@ export type FunctionTypes<MiddlewareSpec_ extends AnyMiddlewareSpec> =
  * encode through, and the function types it may attach to.
  *
  * ```ts
- * class RequireUser extends MiddlewareSpec.MiddlewareSpec<RequireUser, {
- *   provides: CurrentUser
- * }>()("RequireUser", {
+ * class RequireUser extends MiddlewareSpec.MiddlewareSpec<
+ *   RequireUser,
+ *   {
+ *     provides: CurrentUser;
+ *   }
+ * >()("RequireUser", {
  *   error: () => NotSignedIn,
  *   functionTypes: { query: true, mutation: true, action: false },
  * }) {}
  * ```
  *
  * The implementation is server-only and supplied separately via
- * `MiddlewareImpl.make` (or `makeByFunctionType`/`provides`) in `@confect/server`.
+ * `MiddlewareImpl.make` (or `makeByFunctionType`/`provides`) in
+ * `@confect/server`.
  */
 export const MiddlewareSpec =
   <Self, Config extends { provides?: any; requires?: any } = {}>() =>
@@ -160,10 +185,12 @@ export const MiddlewareSpec =
     const Key_ extends string,
     const FunctionTypesConfig_ extends SupportedFunctionTypes,
     ErrorSchema_ extends Schema.Codec<any, any> = never,
+    OptionsSchema_ extends Schema.Schema<any> = never,
   >(
     key: Key_,
     options: {
       readonly error?: () => ErrorSchema_;
+      readonly options?: () => OptionsSchema_;
       readonly functionTypes: FunctionTypesConfig_ &
         ValidateFunctionTypesConfig<FunctionTypesConfig_>;
     },
@@ -173,7 +200,8 @@ export const MiddlewareSpec =
     "provides" extends keyof Config ? Config["provides"] : never,
     "requires" extends keyof Config ? Config["requires"] : never,
     ErrorSchema_,
-    FunctionTypesFromConfig<FunctionTypesConfig_>
+    FunctionTypesFromConfig<FunctionTypesConfig_>,
+    OptionsSchema_
   > => {
     const { query, mutation, action } = options.functionTypes;
     if (!query && !mutation && !action) {
@@ -194,6 +222,9 @@ export const MiddlewareSpec =
     if (options.error !== undefined) {
       Lazy.defineProperty(class_, "error", options.error);
     }
+    if (options.options !== undefined) {
+      Lazy.defineProperty(class_, "options", options.options);
+    }
     return class_;
   };
 
@@ -225,7 +256,7 @@ export const errorSchemas = (
 /**
  * A branded, unconstructible type carrying a spec-authoring error message.
  * Surfaced as (part of) a parameter type so the diagnostic names the exact
- * problem at the `.middleware()` / `.addFunction()` call site.
+ * problem at the `.middleware()`/`.addFunction()` call site.
  */
 export interface AttachmentError<Message extends string> {
   readonly "~@confect/core/MiddlewareSpec/AttachmentError": Message;
@@ -237,10 +268,9 @@ type FunctionTypeOf<FunctionSpec_ extends FunctionSpec.AnyWithProps> =
 type ValidationResult<Errors> = [Errors] extends [never] ? unknown : Errors;
 
 /**
- * A matching-type Convex-provenance function is rejected rather than
- * silently skipped: its raw handler passes through Confect untouched, so
- * the middleware could not actually cover it, and skipping it would be a
- * policy hole.
+ * A matching-type Convex-provenance function is rejected rather than silently
+ * skipped: its raw handler passes through Confect untouched, so the middleware
+ * could not actually cover it, and skipping it would be a policy hole.
  */
 export type ValidateFunction<
   FunctionSpec_ extends FunctionSpec.AnyWithProps,
@@ -251,12 +281,12 @@ export type ValidateFunction<
         readonly functionProvenance: { readonly _tag: "Convex" };
       }
       ? FunctionTypeOf<FunctionSpec_> extends FunctionTypes<MiddlewareSpec_>
-        ? AttachmentError<`Convex-provenance function "${FunctionSpec_["name"]}" cannot be covered by middleware "${Key<MiddlewareSpec_>}" — attach middleware only to groups whose matching-type functions are all Confect-provenance`>
+        ? AttachmentError<`Convex-provenance function "${FunctionSpec_["name"]}" cannot be covered by middleware "${Key<MiddlewareSpec_>}"—attach middleware only to groups whose matching-type functions are all Confect-provenance`>
         : never
       : [
             Extract<
               FunctionSpec.MiddlewareSpecs<FunctionSpec_>,
-              { readonly key: Key<MiddlewareSpec_> }
+              { readonly key: Key<WithoutOptions<MiddlewareSpec_>> }
             >,
           ] extends [never]
         ? FunctionTypeOf<FunctionSpec_> extends FunctionTypes<MiddlewareSpec_>
@@ -267,8 +297,8 @@ export type ValidateFunction<
   : never;
 
 /**
- * Attachment order is chain order, so requiring `requires` to be satisfied
- * by already-attached middleware is exactly requiring the provider to run
+ * Attachment order is chain order, so requiring `requires` to be satisfied by
+ * already-attached middleware is exactly requiring the provider to run
  * earlier.
  */
 export type ValidateAttach<
@@ -276,13 +306,16 @@ export type ValidateAttach<
   Functions_ extends FunctionSpec.AnyWithProps,
   MiddlewareSpecs_ extends AnyMiddlewareSpec,
 > = [
-  Extract<MiddlewareSpecs_, { readonly key: Key<MiddlewareSpec_> }>,
+  Extract<
+    MiddlewareSpecs_,
+    { readonly key: Key<WithoutOptions<MiddlewareSpec_>> }
+  >,
 ] extends [never]
   ? [Exclude<Requires<MiddlewareSpec_>, Provides<MiddlewareSpecs_>>] extends [
       never,
     ]
     ? ValidationResult<ValidateFunction<Functions_, MiddlewareSpec_>>
-    : AttachmentError<`Middleware "${Key<MiddlewareSpec_>}" requires services that no middleware attached earlier to this group provides — attach the providing middleware first`>
+    : AttachmentError<`Middleware "${Key<MiddlewareSpec_>}" requires services that no middleware attached earlier to this group provides—attach the providing middleware first`>
   : AttachmentError<`Middleware "${Key<MiddlewareSpec_>}" is already attached to this group`>;
 
 export type ValidateAddedFunction<
@@ -304,7 +337,7 @@ type GroupOverlap<
       ? [
           Extract<
             MiddlewareSpecs_,
-            { readonly key: Key<FunctionMiddlewareSpec> }
+            { readonly key: Key<WithoutOptions<FunctionMiddlewareSpec>> }
           >,
         ] extends [never]
         ? never
@@ -313,14 +346,14 @@ type GroupOverlap<
     : never;
 
 /**
- * The parameter-type validation applied to the group spec at
- * `GroupImpl.make`: every function's attached middleware must have its
- * `requires` services provided by some middleware covering that function
- * (the group's or the function's own). Checked here — with the group fully
- * assembled — rather than at the spec builders, because a function-level
- * middleware's `requires` may legitimately be satisfied by a group
- * middleware the function spec never sees, and group attachment is
- * declaratively order-independent with respect to `addFunction`.
+ * The parameter-type validation applied to the group spec at `GroupImpl.make`:
+ * every function's attached middleware must have its `requires` services
+ * provided by some middleware covering that function (the group's or the
+ * function's own). Checked here—with the group fully assembled—rather than at
+ * the spec builders, because a function-level middleware's `requires` may
+ * legitimately be satisfied by a group middleware the function spec never sees,
+ * and group attachment is declaratively order-independent with respect to
+ * `addFunction`.
  */
 export type ValidateImplRequires<
   Functions_ extends FunctionSpec.AnyWithProps,
@@ -346,9 +379,12 @@ export type ValidateFunctionAttach<
   FunctionProvenance_ extends FunctionProvenance.FunctionProvenance,
   MiddlewareSpecs_ extends AnyMiddlewareSpec,
 > = FunctionProvenance_ extends { readonly _tag: "Convex" }
-  ? AttachmentError<`Plain Convex functions cannot have middleware — their raw handlers are passed through untouched`>
+  ? AttachmentError<`Plain Convex functions cannot have middleware—their raw handlers are passed through untouched`>
   : [
-        Extract<MiddlewareSpecs_, { readonly key: Key<MiddlewareSpec_> }>,
+        Extract<
+          MiddlewareSpecs_,
+          { readonly key: Key<WithoutOptions<MiddlewareSpec_>> }
+        >,
       ] extends [never]
     ? RuntimeAndFunctionType_["functionType"] extends FunctionTypes<MiddlewareSpec_>
       ? unknown

package/src/PaginationError.ts

@@ -4,7 +4,9 @@ import * as Match from "effect/Match";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 
-/** A Convex pagination cursor that no longer describes the current query. */
+/**
+ * A Convex pagination cursor that no longer describes the current query.
+ */
 export class InvalidCursor extends Schema.TaggedError<InvalidCursor>()(
   "InvalidCursor",
   {
@@ -40,7 +42,9 @@ const fromErrorMessage = (
     ? Option.some(new InvalidCursor({ cause: error }))
     : Option.none();
 
-/** Recognizes an invalid-cursor error emitted by a Convex query. */
+/**
+ * Recognizes an invalid-cursor error emitted by a Convex query.
+ */
 export const fromConvexQueryError = (
   error: unknown,
 ): Option.Option<InvalidCursor> =>
@@ -59,7 +63,9 @@ export const fromConvexQueryError = (
     Match.exhaustive,
   );
 
-/** Recognizes the error data attached to Convex's invalid-cursor error. */
+/**
+ * Recognizes the error data attached to Convex's invalid-cursor error.
+ */
 export const fromConvexErrorData = (
   errorData: unknown,
 ): Option.Option<InvalidCursor> =>

package/src/PaginationOptions.ts

@@ -1,13 +1,13 @@
 import * as Schema from "effect/Schema";
 
 /**
- * Schema for the `paginationOpts` argument that every paginated query
- * receives. Mirrors `paginationOptsValidator` from `convex/server`.
+ * Schema for the `paginationOpts` argument that every paginated query receives.
+ * Mirrors `paginationOptsValidator` from `convex/server`.
  *
  * Use this as the `paginationOpts` field of a paginated query's args schema.
  * Beyond `numItems` and `cursor`, Convex's pagination protocol sends the
  * optional fields (`endCursor`, `id`, `maximumRowsRead`, `maximumBytesRead`)
- * with real requests — most notably `usePaginatedQuery` from `convex/react`
+ * with real requests—most notably `usePaginatedQuery` from `convex/react`
  * always includes `id`, and includes `endCursor` when splitting pages.
  * Declaring them is required for the generated Convex argument validator to
  * accept those requests and for the fields to survive decoding and reach