@btravstack/pothos 0.32.0 → 0.34.0

package/README.md

@@ -6,12 +6,14 @@ contract-first services. The default export is the plugin, listed after
 `@unthrown/pothos`'s:
 `plugins: [RelayPlugin, ErrorsPlugin, UnthrownPlugin, OrpcPlugin]`.
 
-- `t.procedureField(procedure, { type, call, input, output })` validates the
+- `t.procedureField(procedure, { type, call, input, output, refusals? })` validates the
   field's input through the procedure's own contract before calling it,
   decodes the answer with `output`, and answers each error the procedure
-  declares as the GraphQL error class the builder's `orpc: { refusals }`
-  registers for its code — a member of the field's result union. A registry
-  that misses a code `call` can fail with does not compile.
+  declares as the GraphQL error class registered for its code — a member of
+  the field's result union. Field-local `refusals` override the builder's
+  shared `orpc: { refusals }` defaults. Together the maps must cover every
+  error `call` can return and `InvalidInput`; a missing code does not compile.
+  A declared error handled by a narrower `call` needs no entry.
 - `t.procedureConnection(procedure, { …, connection })` is the same for a
   Relay connection, with the decoded page folded by `connection`.
 - `UNAUTHORIZED` and `FORBIDDEN` are answered as GraphQL's own error, with

package/dist/index.d.mts

@@ -72,30 +72,36 @@ type Covered<Registry, Failure> = Registry extends Refusals<Failure> ? {} : {
 };
 /**
  * `t.procedureField`'s options: `resultField`'s, with `call`, `input` and
- * `output` in place of `resolve`, and the builder's `orpc.refusals` in place
- * of `refusals`. The registry must cover every error `call` can return but
+ * `output` in place of `resolve`. Field-local `refusals` override the builder's
+ * `orpc.refusals`. Together they must cover every error `call` can return but
  * the access refusals, and `InvalidInput`; an uncovered case is a compile
  * error naming it. A declared error `call` handles itself needs no entry.
  */
-type ProcedureFieldOptions<Types extends SchemaTypes, ParentShape, Type extends TypeParam<Types>, Nullable extends FieldNullability<Type>, Args extends InputFieldMap, Kind extends FieldKind, Schema extends z.ZodType, Failure> = Omit<ResultFieldOptions<Types, ParentShape, Type, Nullable, Args, Kind, Failure>, "refusals" | "resolve"> & {
+type ProcedureFieldOptions<Types extends SchemaTypes, ParentShape, Type extends TypeParam<Types>, Nullable extends FieldNullability<Type>, Args extends InputFieldMap, Kind extends FieldKind, Schema extends z.ZodType, Failure, Local extends Readonly<Record<string, ErrorClass>> = {}> = Omit<ResultFieldOptions<Types, ParentShape, Type, Nullable, Args, Kind, Failure>, "refusals" | "resolve"> & {
   readonly call: Call<Types["Context"], z.input<Schema>, Failure>;
+  /** Local refusal classes, overriding the builder's shared defaults by code. */
+  readonly refusals?: Local & ([keyof Local] extends [never] ? Readonly<Record<string, never>> : unknown);
   readonly input: (args: InputShapeFromFields<Args>, parent: ParentShape) => NoInfer<z.input<Schema>>;
   readonly output: z.ZodType<ShapeFromTypeParam<Types, Type, false>>;
   readonly tap?: (value: ShapeFromTypeParam<Types, Type, false>, context: Types["Context"]) => void;
-} & Covered<Types["Refusals"], Exclude<Failure, Access> | InvalidInput>;
+} & Covered<Omit<Types["Refusals"], keyof Local> & Local, Exclude<Failure, Access> | InvalidInput>;
 /**
  * `t.procedureConnection`'s options: `resultConnection`'s, with `call`,
  * `input` and `output` in place of `resolve`, `connection` folding the
  * decoded page into the connection's shape, and an optional `connectionType`
- * for fields beside its edges and page info.
+ * for fields beside its edges and page info. Local `refusals` override the
+ * builder's shared defaults, together covering `call`'s failures and input
+ * validation.
  */
-type ProcedureConnectionOptions<Types extends SchemaTypes, ParentShape, Type extends OutputType<Types>, Nullable extends boolean, EdgeNullability extends FieldNullability<[unknown]>, NodeNullability extends boolean, Args extends InputFieldMap, Kind extends FieldKind, Schema extends z.ZodType, Page, Failure, Connection extends ConnectionShapeForType<Types, Type, false, EdgeNullability, NodeNullability> = ConnectionShapeForType<Types, Type, false, EdgeNullability, NodeNullability>> = Omit<ResultConnectionOptions<Types, ParentShape, Type, Nullable, EdgeNullability, NodeNullability, Args, Kind, Failure, Connection>, "refusals" | "resolve"> & {
+type ProcedureConnectionOptions<Types extends SchemaTypes, ParentShape, Type extends OutputType<Types>, Nullable extends boolean, EdgeNullability extends FieldNullability<[unknown]>, NodeNullability extends boolean, Args extends InputFieldMap, Kind extends FieldKind, Schema extends z.ZodType, Page, Failure, Connection extends ConnectionShapeForType<Types, Type, false, EdgeNullability, NodeNullability> = ConnectionShapeForType<Types, Type, false, EdgeNullability, NodeNullability>, Local extends Readonly<Record<string, ErrorClass>> = {}> = Omit<ResultConnectionOptions<Types, ParentShape, Type, Nullable, EdgeNullability, NodeNullability, Args, Kind, Failure, Connection>, "refusals" | "resolve"> & {
   readonly call: Call<Types["Context"], z.input<Schema>, Failure>;
+  /** Local refusal classes, overriding the builder's shared defaults by code. */
+  readonly refusals?: Local & ([keyof Local] extends [never] ? Readonly<Record<string, never>> : unknown);
   readonly input: (args: DefaultConnectionArguments & InputShapeFromFields<Args>, parent: ParentShape) => NoInfer<z.input<Schema>>;
   readonly output: z.ZodType<Page>;
   readonly connectionType?: ObjectRef<Types, Connection>;
   readonly connection: (page: Page, args: DefaultConnectionArguments & InputShapeFromFields<Args>) => Connection;
-} & Covered<Types["Refusals"], Exclude<Failure, Access> | InvalidInput>;
+} & Covered<Omit<Types["Refusals"], keyof Local> & Local, Exclude<Failure, Access> | InvalidInput>;
 declare global {
   export namespace PothosSchemaTypes {
     interface UserSchemaTypes {
@@ -118,12 +124,12 @@ declare global {
        * union; the service refusing access is GraphQL's own error, with
        * `extensions.code`.
        */
-      procedureField: <Type extends TypeParam<Types>, Schema extends z.ZodType, Failure, Nullable extends FieldNullability<Type> = Types["DefaultFieldNullability"], Args extends InputFieldMap = {}>(procedure: Procedure<Schema>, options: ProcedureFieldOptions<Types, ParentShape, Type, Nullable, Args, Kind, Schema, Failure>) => FieldRef<Types, ShapeFromTypeParam<Types, Type, Nullable>, Kind>;
+      procedureField: <Type extends TypeParam<Types>, Schema extends z.ZodType, Failure, Nullable extends FieldNullability<Type> = Types["DefaultFieldNullability"], Args extends InputFieldMap = {}, const Local extends Readonly<Record<string, ErrorClass>> = {}>(procedure: Procedure<Schema>, options: ProcedureFieldOptions<Types, ParentShape, Type, Nullable, Args, Kind, Schema, Failure, Local>) => FieldRef<Types, ShapeFromTypeParam<Types, Type, Nullable>, Kind>;
       /**
        * A Relay connection answering an oRPC procedure: `procedureField`'s
        * contract, with the decoded page folded by `connection`.
        */
-      procedureConnection: <Type extends OutputType<Types>, Schema extends z.ZodType, Page, Failure, Nullable extends boolean, Args extends InputFieldMap = {}, EdgeNullability extends FieldNullability<[unknown]> = Types["DefaultEdgesNullability"], NodeNullability extends boolean = Types["DefaultNodeNullability"], Connection extends ConnectionShapeForType<Types, Type, false, EdgeNullability, NodeNullability> = ConnectionShapeForType<Types, Type, false, EdgeNullability, NodeNullability>>(procedure: Procedure<Schema>, options: ProcedureConnectionOptions<Types, ParentShape, Type, Nullable, EdgeNullability, NodeNullability, Args, Kind, Schema, Page, Failure, Connection>) => FieldRef<Types, ConnectionShapeForType<Types, Type, Nullable, EdgeNullability, NodeNullability>>;
+      procedureConnection: <Type extends OutputType<Types>, Schema extends z.ZodType, Page, Failure, Nullable extends boolean, Args extends InputFieldMap = {}, EdgeNullability extends FieldNullability<[unknown]> = Types["DefaultEdgesNullability"], NodeNullability extends boolean = Types["DefaultNodeNullability"], Connection extends ConnectionShapeForType<Types, Type, false, EdgeNullability, NodeNullability> = ConnectionShapeForType<Types, Type, false, EdgeNullability, NodeNullability>, const Local extends Readonly<Record<string, ErrorClass>> = {}>(procedure: Procedure<Schema>, options: ProcedureConnectionOptions<Types, ParentShape, Type, Nullable, EdgeNullability, NodeNullability, Args, Kind, Schema, Page, Failure, Connection, Local>) => FieldRef<Types, ConnectionShapeForType<Types, Type, Nullable, EdgeNullability, NodeNullability>>;
     }
   }
 }

package/dist/index.mjs

@@ -102,19 +102,25 @@ const loadProcedure = async (registry, procedure, call, input, output) => {
 const procedureErrors = (registry, procedure) => ({ types: Object.values(refusalsOf(registry, procedure)) });
 const defineProcedureFields = () => {
 	const fieldBuilder = RootFieldBuilder.prototype;
-	fieldBuilder.procedureField = function procedureField(procedure, { call, input, output, tap, ...options }) {
+	fieldBuilder.procedureField = function procedureField(procedure, { call, input, output, tap, refusals, ...options }) {
 		return this.resultField({
 			...options,
-			refusals: refusalsOf(this.builder.options.orpc?.refusals ?? {}, procedure),
+			refusals: refusalsOf({
+				...this.builder.options.orpc?.refusals,
+				...refusals
+			}, procedure),
 			resolve: (parent, args, context) => callProcedure(procedure, input(args, parent), call(context), output).tap((value) => {
 				tap?.(value, context);
 			})
 		});
 	};
-	fieldBuilder.procedureConnection = function procedureConnection(procedure, { call, input, output, connection, connectionType, ...options }) {
+	fieldBuilder.procedureConnection = function procedureConnection(procedure, { call, input, output, connection, connectionType, refusals, ...options }) {
 		return this.resultConnection({
 			...options,
-			refusals: refusalsOf(this.builder.options.orpc?.refusals ?? {}, procedure),
+			refusals: refusalsOf({
+				...this.builder.options.orpc?.refusals,
+				...refusals
+			}, procedure),
 			resolve: (parent, args, context) => callProcedure(procedure, input(args, parent), call(context), output).map((page) => connection(page, args))
 		}, connectionType);
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/pothos",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Pothos fields that call oRPC procedures, each declared error answered as a typed GraphQL refusal",
   "keywords": [
     "graphql",