@confect/core 10.0.0-next.14 → 10.0.0-next.17

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@confect/core",
   "description": "Shared specs and schemas used by all Confect packages",
-  "version": "10.0.0-next.14",
+  "version": "10.0.0-next.17",
   "author": "RJ Dellecese",
   "bugs": {
     "url": "https://github.com/rjdellecese/confect/issues"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0-rc.108",
-    "@types/node": "26.2.0",
-    "effect": "4.0.0-rc.108",
+    "@effect/vitest": "4.0.0-rc.111",
+    "@types/node": "22.20.1",
+    "effect": "4.0.0-rc.111",
     "tsdown": "0.22.14",
-    "tsx": "4.23.11",
+    "tsx": "4.23.12",
     "typescript": "7.0.2",
     "unrun": "0.3.1",
     "vitest": "4.1.10",
@@ -37,6 +37,7 @@
     "LICENSE",
     "README.md",
     "dist",
+    "!dist/*.tsbuildinfo",
     "package.json",
     "src"
   ],
@@ -50,11 +51,11 @@
   "module": "./dist/index.js",
   "peerDependencies": {
     "convex": "^1.32.0",
-    "effect": "^4.0.0-rc.108"
+    "effect": "^4.0.0-rc.111"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/rjdellecese/confect.git"
+    "url": "git+https://github.com/rjdellecese/confect.git"
   },
   "sideEffects": false,
   "type": "module",
@@ -62,7 +63,7 @@
   "scripts": {
     "bench": "tsx test/Refs.bench.ts",
     "clean": "shx rm -rf dist coverage node_modules",
-    "dev": "tsdown --watch --config-loader unrun",
+    "dev": "tsdown --watch --no-clean --config-loader unrun",
     "test": "vitest run",
     "typecheck": "tsc -b tsconfig.src.json"
   }

package/src/FunctionSpec.ts

@@ -9,6 +9,7 @@ import * as Schema from "effect/Schema";
 import * as Predicate from "effect/Predicate";
 import * as FunctionProvenance from "./FunctionProvenance";
 import { validateConfectFunctionIdentifier } from "./Identifier";
+import type * as MiddlewareSpec from "./MiddlewareSpec";
 import * as RuntimeAndFunctionType from "./RuntimeAndFunctionType";
 
 export const TypeId = "@confect/core/FunctionSpec";
@@ -22,12 +23,44 @@ export interface FunctionSpec<
   FunctionVisibility_ extends FunctionVisibility,
   Name_ extends string,
   FunctionProvenance_ extends FunctionProvenance.FunctionProvenance,
+  MiddlewareSpecs_ extends MiddlewareSpec.AnyMiddlewareSpec = never,
 > {
   readonly [TypeId]: TypeId;
   readonly runtimeAndFunctionType: RuntimeAndFunctionType_;
   readonly functionVisibility: FunctionVisibility_;
   readonly name: Name_;
   readonly functionProvenance: FunctionProvenance_;
+  readonly middlewareSpecs: ReadonlyArray<MiddlewareSpecs_>;
+}
+
+export interface Builder<
+  RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
+  FunctionVisibility_ extends FunctionVisibility,
+  Name_ extends string,
+  FunctionProvenance_ extends FunctionProvenance.FunctionProvenance,
+  MiddlewareSpecs_ extends MiddlewareSpec.AnyMiddlewareSpec = never,
+> extends FunctionSpec<
+  RuntimeAndFunctionType_,
+  FunctionVisibility_,
+  Name_,
+  FunctionProvenance_,
+  MiddlewareSpecs_
+> {
+  middleware<MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec>(
+    middlewareSpec: MiddlewareSpec_ &
+      MiddlewareSpec.ValidateFunctionAttach<
+        MiddlewareSpec_,
+        RuntimeAndFunctionType_,
+        FunctionProvenance_,
+        MiddlewareSpecs_
+      >,
+  ): Builder<
+    RuntimeAndFunctionType_,
+    FunctionVisibility_,
+    Name_,
+    FunctionProvenance_,
+    MiddlewareSpecs_ | MiddlewareSpec_
+  >;
 }
 
 export interface Any {
@@ -38,21 +71,24 @@ export interface AnyWithProps extends FunctionSpec<
   RuntimeAndFunctionType.RuntimeAndFunctionType,
   FunctionVisibility,
   string,
-  FunctionProvenance.FunctionProvenance
+  FunctionProvenance.FunctionProvenance,
+  MiddlewareSpec.AnyMiddlewareSpec
 > {}
 
 export interface AnyConfect extends FunctionSpec<
   RuntimeAndFunctionType.RuntimeAndFunctionType,
   FunctionVisibility,
   string,
-  FunctionProvenance.AnyConfect
+  FunctionProvenance.AnyConfect,
+  MiddlewareSpec.AnyMiddlewareSpec
 > {}
 
 export interface AnyConvex extends FunctionSpec<
   RuntimeAndFunctionType.RuntimeAndFunctionType,
   FunctionVisibility,
   string,
-  FunctionProvenance.AnyConvex
+  FunctionProvenance.AnyConvex,
+  MiddlewareSpec.AnyMiddlewareSpec
 > {}
 
 export interface AnyWithPropsWithRuntime<
@@ -61,7 +97,8 @@ export interface AnyWithPropsWithRuntime<
   RuntimeAndFunctionType.WithRuntime<Runtime>,
   FunctionVisibility,
   string,
-  FunctionProvenance.FunctionProvenance
+  FunctionProvenance.FunctionProvenance,
+  MiddlewareSpec.AnyMiddlewareSpec
 > {}
 
 export interface AnyWithPropsWithFunctionType<
@@ -70,7 +107,8 @@ export interface AnyWithPropsWithFunctionType<
   RuntimeAndFunctionType_,
   FunctionVisibility,
   string,
-  FunctionProvenance.FunctionProvenance
+  FunctionProvenance.FunctionProvenance,
+  MiddlewareSpec.AnyMiddlewareSpec
 > {}
 
 export interface AnyWithPropsWithFunctionProvenance<
@@ -79,7 +117,8 @@ export interface AnyWithPropsWithFunctionProvenance<
   RuntimeAndFunctionType.RuntimeAndFunctionType,
   FunctionVisibility,
   string,
-  FunctionProvenance_
+  FunctionProvenance_,
+  MiddlewareSpec.AnyMiddlewareSpec
 > {}
 
 export type GetRuntimeAndFunctionType<FunctionSpec_ extends AnyWithProps> =
@@ -90,6 +129,9 @@ export type GetFunctionVisibility<FunctionSpec_ extends AnyWithProps> =
 
 export type Name<FunctionSpec_ extends AnyWithProps> = FunctionSpec_["name"];
 
+export type MiddlewareSpecs<FunctionSpec_ extends AnyWithProps> =
+  FunctionSpec_["middlewareSpecs"][number];
+
 export type Args<FunctionSpec_ extends AnyWithProps> = FunctionSpec_ extends {
   functionProvenance: {
     _tag: "Confect";
@@ -202,6 +244,40 @@ export type WithoutName<
 
 const Proto = {
   [TypeId]: TypeId,
+
+  middleware(
+    this: AnyWithProps,
+    middlewareSpec: MiddlewareSpec.AnyMiddlewareSpec,
+  ) {
+    if (this.functionProvenance._tag === "Convex") {
+      throw new Error(
+        `Plain Convex function "${this.name}" cannot have middleware`,
+      );
+    }
+    const functionType = this.runtimeAndFunctionType.functionType;
+    if (!middlewareSpec.functionTypes[functionType]) {
+      throw new Error(
+        `Middleware "${middlewareSpec.key}" does not declare function type "${functionType}" of function "${this.name}"`,
+      );
+    }
+    if (
+      this.middlewareSpecs.some(
+        (existing) => existing.key === middlewareSpec.key,
+      )
+    ) {
+      throw new Error(
+        `Middleware "${middlewareSpec.key}" is already attached to function "${this.name}"`,
+      );
+    }
+
+    return Object.assign(Object.create(Proto), {
+      runtimeAndFunctionType: this.runtimeAndFunctionType,
+      functionVisibility: this.functionVisibility,
+      name: this.name,
+      functionProvenance: this.functionProvenance,
+      middlewareSpecs: [...this.middlewareSpecs, middlewareSpec],
+    });
+  },
 };
 
 const make =
@@ -228,7 +304,7 @@ const make =
     args: () => Args_;
     returns: () => Returns_;
     error?: () => Error_;
-  }): FunctionSpec<
+  }): Builder<
     RuntimeAndFunctionType_,
     FunctionVisibility_,
     Name_,
@@ -241,6 +317,7 @@ const make =
       functionVisibility,
       name,
       functionProvenance: FunctionProvenance.Confect(args, returns, error),
+      middlewareSpecs: [],
     });
   };
 
@@ -281,7 +358,7 @@ const makePaginated =
     /** The page element schema. */
     item: () => Item_;
     error?: () => Error_;
-  }): FunctionSpec<
+  }): Builder<
     RuntimeAndFunctionType_,
     FunctionVisibility_,
     Name_,
@@ -299,6 +376,7 @@ const makePaginated =
         item,
         error,
       ),
+      middlewareSpecs: [],
     });
   };
 
@@ -385,7 +463,7 @@ const makeConvex =
   >() =>
   <const Name_ extends string>(
     name: Name_,
-  ): FunctionSpec<
+  ): Builder<
     RuntimeAndFunctionType_,
     FunctionVisibility_,
     Name_,
@@ -401,6 +479,7 @@ const makeConvex =
         ExtractArgs<F>,
         ExtractReturns<F>
       >(),
+      middlewareSpecs: [],
     }) as any;
   };
 

package/src/GroupSpec.ts

@@ -1,6 +1,7 @@
 import * as Predicate from "effect/Predicate";
 import * as Record from "effect/Record";
 import type * as FunctionSpec from "./FunctionSpec";
+import type * as MiddlewareSpec from "./MiddlewareSpec";
 import type * as RuntimeAndFunctionType from "./RuntimeAndFunctionType";
 import { validateConfectFunctionIdentifier } from "./Identifier";
 
@@ -19,31 +20,63 @@ export interface GroupSpec<
   // modules. Functions, by contrast, stay homogeneous (a Node group only accepts
   // Node actions) — `addFunction` keeps the `<Runtime>` bound below.
   Groups_ extends AnyWithProps = never,
+  MiddlewareSpecs_ extends MiddlewareSpec.AnyMiddlewareSpec = never,
 > {
   readonly [TypeId]: TypeId;
   readonly runtime: Runtime;
   readonly name: Name_;
   readonly functions: {
-    [FunctionName in FunctionSpec.Name<
-      FunctionSpec.AnyWithPropsWithRuntime<Runtime>
-    >]: FunctionSpec.WithName<Functions_, FunctionName>;
+    [
+      FunctionName in FunctionSpec.Name<
+        FunctionSpec.AnyWithPropsWithRuntime<Runtime>
+      >
+    ]: FunctionSpec.WithName<Functions_, FunctionName>;
   };
   readonly groups: {
     [GroupName in Name<Groups_>]: WithName<Groups_, GroupName>;
   };
+  readonly middlewareSpecs: ReadonlyArray<MiddlewareSpecs_>;
 
   addFunction<Function extends FunctionSpec.AnyWithPropsWithRuntime<Runtime>>(
-    function_: Function,
-  ): GroupSpec<Runtime, Name_, Functions_ | Function, Groups_>;
+    function_: Function &
+      MiddlewareSpec.ValidateAddedFunction<Function, MiddlewareSpecs_>,
+  ): GroupSpec<
+    Runtime,
+    Name_,
+    Functions_ | Function,
+    Groups_,
+    MiddlewareSpecs_
+  >;
 
   addGroup<Group extends AnyWithProps>(
     group: Group,
-  ): GroupSpec<Runtime, Name_, Functions_, Groups_ | Group>;
+  ): GroupSpec<Runtime, Name_, Functions_, Groups_ | Group, MiddlewareSpecs_>;
 
   addGroupAt<const AtName extends string, Group extends AnyWithProps>(
     name: AtName,
     group: Group,
-  ): GroupSpec<Runtime, Name_, Functions_, Groups_ | NamedAt<Group, AtName>>;
+  ): GroupSpec<
+    Runtime,
+    Name_,
+    Functions_,
+    Groups_ | NamedAt<Group, AtName>,
+    MiddlewareSpecs_
+  >;
+
+  middleware<MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec>(
+    middlewareSpec: MiddlewareSpec_ &
+      MiddlewareSpec.ValidateAttach<
+        MiddlewareSpec_,
+        Functions_,
+        MiddlewareSpecs_
+      >,
+  ): GroupSpec<
+    Runtime,
+    Name_,
+    Functions_,
+    Groups_,
+    MiddlewareSpecs_ | MiddlewareSpec_
+  >;
 }
 
 export interface Any {
@@ -54,7 +87,8 @@ export interface AnyWithProps extends GroupSpec<
   RuntimeAndFunctionType.Runtime,
   string,
   FunctionSpec.AnyWithProps,
-  AnyWithProps
+  AnyWithProps,
+  MiddlewareSpec.AnyMiddlewareSpec
 > {}
 
 export interface AnyWithPropsWithRuntime<
@@ -63,7 +97,8 @@ export interface AnyWithPropsWithRuntime<
   Runtime,
   string,
   FunctionSpec.AnyWithPropsWithRuntime<Runtime>,
-  AnyWithPropsWithRuntime<Runtime>
+  AnyWithPropsWithRuntime<Runtime>,
+  MiddlewareSpec.AnyMiddlewareSpec
 > {}
 
 export type Name<Group extends AnyWithProps> = Group["name"];
@@ -74,6 +109,9 @@ export type Functions<Group extends AnyWithProps> =
 export type Groups<Group extends AnyWithProps> =
   Group["groups"][keyof Group["groups"]];
 
+export type MiddlewareSpecs<Group extends AnyWithProps> =
+  Group["middlewareSpecs"][number];
+
 export type GroupNames<Group extends AnyWithProps> = [Groups<Group>] extends [
   never,
 ]
@@ -101,9 +139,16 @@ export type AddGroups<
     infer Runtime,
     infer Name_,
     infer Functions_,
-    infer Groups_
+    infer Groups_,
+    infer MiddlewareSpecs_
   >
-    ? GroupSpec<Runtime, Name_, Functions_, Groups_ | ExtraGroups>
+    ? GroupSpec<
+        Runtime,
+        Name_,
+        Functions_,
+        Groups_ | ExtraGroups,
+        MiddlewareSpecs_
+      >
     : never;
 
 const Proto = {
@@ -115,11 +160,25 @@ const Proto = {
   ) {
     const this_ = this as AnyWithProps;
 
+    const overlapping = function_.middlewareSpecs.find(
+      (functionMiddlewareSpec) =>
+        this_.middlewareSpecs.some(
+          (groupMiddlewareSpec) =>
+            groupMiddlewareSpec.key === functionMiddlewareSpec.key,
+        ),
+    );
+    if (overlapping !== undefined) {
+      throw new Error(
+        `Middleware "${overlapping.key}" is attached to both function "${function_.name}" and its group`,
+      );
+    }
+
     return makeProto({
       runtime: this_.runtime,
       name: this_.name,
       functions: Record.set(this_.functions, function_.name, function_),
       groups: this_.groups,
+      middlewareSpecs: this_.middlewareSpecs,
     });
   },
 
@@ -132,6 +191,7 @@ const Proto = {
       name: this_.name,
       functions: this_.functions,
       groups: Record.set(this_.groups, group_.name, group_),
+      middlewareSpecs: this_.middlewareSpecs,
     });
   },
 
@@ -144,6 +204,44 @@ const Proto = {
       name: this_.name,
       functions: this_.functions,
       groups: Record.set(this_.groups, name, withName(name, group_)),
+      middlewareSpecs: this_.middlewareSpecs,
+    });
+  },
+
+  middleware<MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec>(
+    this: Any,
+    middlewareSpec: MiddlewareSpec_,
+  ) {
+    const this_ = this as AnyWithProps;
+
+    if (
+      this_.middlewareSpecs.some(
+        (existing) => existing.key === middlewareSpec.key,
+      )
+    ) {
+      throw new Error(
+        `Middleware "${middlewareSpec.key}" is already attached to this group`,
+      );
+    }
+
+    for (const function_ of Object.values(this_.functions)) {
+      if (
+        function_.middlewareSpecs.some(
+          (existing) => existing.key === middlewareSpec.key,
+        )
+      ) {
+        throw new Error(
+          `Middleware "${middlewareSpec.key}" is attached to both function "${function_.name}" and its group`,
+        );
+      }
+    }
+
+    return makeProto({
+      runtime: this_.runtime,
+      name: this_.name,
+      functions: this_.functions,
+      groups: this_.groups,
+      middlewareSpecs: [...this_.middlewareSpecs, middlewareSpec],
     });
   },
 };
@@ -153,22 +251,26 @@ const makeProto = <
   Name_ extends string,
   Functions_ extends FunctionSpec.AnyWithPropsWithRuntime<Runtime>,
   Groups_ extends AnyWithPropsWithRuntime<Runtime>,
+  MiddlewareSpecs_ extends MiddlewareSpec.AnyMiddlewareSpec,
 >({
   runtime,
   name,
   functions,
   groups,
+  middlewareSpecs,
 }: {
   runtime: Runtime;
   name: Name_;
   functions: Record.ReadonlyRecord<string, Functions_>;
   groups: Record.ReadonlyRecord<string, Groups_>;
-}): GroupSpec<Runtime, Name_, Functions_, Groups_> =>
+  middlewareSpecs: ReadonlyArray<MiddlewareSpecs_>;
+}): GroupSpec<Runtime, Name_, Functions_, Groups_, MiddlewareSpecs_> =>
   Object.assign(Object.create(Proto), {
     runtime,
     name,
     functions,
     groups,
+    middlewareSpecs,
   });
 
 export const make = (): GroupSpec<"Convex", ""> =>
@@ -177,6 +279,7 @@ export const make = (): GroupSpec<"Convex", ""> =>
     name: "",
     functions: Record.empty(),
     groups: Record.empty(),
+    middlewareSpecs: [],
   });
 
 export const makeAt = <const Name_ extends string>(
@@ -189,6 +292,7 @@ export const makeAt = <const Name_ extends string>(
     name,
     functions: Record.empty(),
     groups: Record.empty(),
+    middlewareSpecs: [],
   });
 };
 
@@ -198,6 +302,7 @@ export const makeNode = (): GroupSpec<"Node", ""> =>
     name: "",
     functions: Record.empty(),
     groups: Record.empty(),
+    middlewareSpecs: [],
   });
 
 export const makeNodeAt = <const Name_ extends string>(
@@ -210,6 +315,7 @@ export const makeNodeAt = <const Name_ extends string>(
     name,
     functions: Record.empty(),
     groups: Record.empty(),
+    middlewareSpecs: [],
   });
 };
 
@@ -229,5 +335,6 @@ export const withName = <const Name_ extends string>(
     name,
     functions: group_.functions,
     groups: group_.groups,
+    middlewareSpecs: group_.middlewareSpecs,
   });
 };