@btravstack/pothos 0.0.0-stage → 0.28.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benoit TRAVERS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @btravstack/pothos
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Pothos](https://pothos-graphql.dev) fields that call
+[oRPC](https://orpc.dev) procedures, for a GraphQL gateway in front of
+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
+  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.
+- `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
+  `extensions.code`, whether the procedure declares them or not.
+- `loadProcedure` and `procedureErrors` are the same answer through a
+  DataLoader; `contractCall`, `contractInput` and `contractOutput` are the
+  contract half on its own.
+
+Every dependency is a peer: Pothos plugins and `graphql` each need one copy.
+
+```sh
+pnpm add @btravstack/pothos @pothos/core @pothos/plugin-errors @pothos/plugin-relay \
+  @unthrown/pothos@^0.1.0 graphql unthrown zod \
+  @orpc/client@2.0.0-beta.28 @orpc/contract@2.0.0-beta.28
+```
+
+See
+[Resolve GraphQL fields from oRPC procedures](https://btravstack.github.io/btravstack/how-to/resolve-graphql-fields-from-orpc).

package/dist/index.d.mts

@@ -0,0 +1,159 @@
+import { BasePlugin, FieldKind, FieldNullability, InputFieldMap, InputShapeFromFields, ObjectRef, OutputType, SchemaTypes, ShapeFromTypeParam, TypeParam } from "@pothos/core";
+import { ResultConnectionOptions } from "@unthrown/pothos/relay";
+import { CaseOf, Caseable, Refusals, ResultFieldOptions } from "@unthrown/pothos";
+import { AsyncResult } from "unthrown";
+import { z } from "zod";
+import { AnySchema, ErrorMap, ProcedureContract } from "@orpc/contract";
+import { ConnectionShapeForType, DefaultConnectionArguments } from "@pothos/plugin-relay";
+//#region src/plugin.d.ts
+declare const pluginName = "orpc";
+declare class PothosOrpcPlugin<Types extends SchemaTypes> extends BasePlugin<Types> {}
+declare global {
+  export namespace PothosSchemaTypes {
+    interface Plugins<Types extends SchemaTypes> {
+      orpc: PothosOrpcPlugin<Types>;
+    }
+  }
+}
+//#endregion
+//#region src/contract.d.ts
+/**
+ * The one Zod schema a procedure's contract declares for its input, typed as
+ * declared — to derive a GraphQL argument's shape from it (`.shape`, a
+ * `z.preprocess` around it) when the schema is built.
+ *
+ * A procedure whose contract holds anything but exactly one Zod input schema
+ * is a mistake in the schema's source, not a request's: it throws, once, as
+ * the schema is built.
+ */
+export declare const contractInput: <Input extends z.ZodType, Output extends AnySchema, Errors extends ErrorMap>(procedure: ProcedureContract<Input, Output, Errors>) => Input;
+declare const InvalidInput_base: import("unthrown").TaggedErrorConstructor<"InvalidInput">;
+/**
+ * An input the procedure's contract refuses, caught before the procedure is
+ * called: each of the contract's issues, with its message and path.
+ */
+export declare class InvalidInput extends InvalidInput_base<{
+  readonly issues: readonly {
+    readonly message: string;
+    readonly path: readonly PropertyKey[];
+  }[];
+}> {
+  message: string;
+}
+/**
+ * `call`, handed the input as the procedure's contract parses it and encodes
+ * it back for the wire — its defaults applied, its codecs run, asynchronous
+ * refinements included — or `InvalidInput` without calling it. A schema with a
+ * transform cannot be encoded back: `call` gets the input as given, which the
+ * contract admitted. A contract whose input is not one Zod
+ * schema is a defect.
+ */
+export declare const contractCall: <Schema extends z.ZodType, OutputSchema extends AnySchema, Errors extends ErrorMap, Output, Failure>(procedure: ProcedureContract<Schema, OutputSchema, Errors>, input: unknown, call: (validated: z.input<Schema>) => AsyncResult<Output, Failure>) => AsyncResult<Output, Failure | InvalidInput>;
+/**
+ * A procedure's answer decoded by `schema` — the shape the GraphQL field
+ * resolves, codecs run. An answer the schema refuses is a defect: the service
+ * broke its own contract.
+ */
+export declare const contractOutput: <Schema extends z.ZodType>(schema: Schema, value: unknown) => AsyncResult<z.infer<Schema>, never>;
+//#endregion
+//#region src/procedure-field.d.ts
+type ErrorClass = new (failure: never) => Error;
+type Access = {
+  readonly code: "UNAUTHORIZED" | "FORBIDDEN";
+};
+type Procedure<Schema extends z.ZodType> = ProcedureContract<Schema, AnySchema, ErrorMap>;
+type AnyProcedure = Procedure<z.ZodType>;
+type Call<Context, Input, Failure> = (context: Context) => (input: Input) => AsyncResult<unknown, Failure>;
+type Covered<Registry, Failure> = Registry extends Refusals<Failure> ? {} : {
+  readonly uncovered: Exclude<CaseOf<Failure>, keyof Registry>;
+};
+/**
+ * `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
+ * 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"> & {
+  readonly call: Call<Types["Context"], z.input<Schema>, Failure>;
+  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>;
+/**
+ * `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.
+ */
+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"> & {
+  readonly call: Call<Types["Context"], z.input<Schema>, Failure>;
+  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>;
+declare global {
+  export namespace PothosSchemaTypes {
+    interface UserSchemaTypes {
+      Refusals: Readonly<Record<string, ErrorClass>>;
+    }
+    interface ExtendDefaultTypes<PartialTypes extends Partial<UserSchemaTypes>> {
+      Refusals: PartialTypes["Refusals"] & {};
+    }
+    interface SchemaBuilderOptions<Types extends SchemaTypes> {
+      orpc?: {
+        readonly refusals: Types["Refusals"];
+      };
+    }
+    interface RootFieldBuilder<Types extends SchemaTypes, ParentShape, Kind extends FieldKind = FieldKind> {
+      /**
+       * A field answering an oRPC procedure: `input` maps the field's
+       * arguments to the procedure's input, the contract validates it before
+       * `call` runs, and `output` decodes the answer. A declared error is
+       * answered as its registered refusal, a member of the field's result
+       * 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>;
+      /**
+       * 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>>;
+    }
+  }
+}
+/**
+ * The refusals a procedure can answer, read from `registry`: one per error
+ * code its contract declares, and `InvalidInput`. A code the registry lacks is
+ * left out, and so are `UNAUTHORIZED` and `FORBIDDEN`, answered as GraphQL's
+ * own error.
+ */
+export declare const refusalsOf: <Failure>(registry: Readonly<Record<string, ErrorClass>>, procedure: AnyProcedure) => Refusals<Failure>;
+/**
+ * `call` handed the input the procedure's contract accepts, its answer decoded
+ * by `output`. `UNAUTHORIZED` and `FORBIDDEN`, declared or not, leave the
+ * error channel: they travel as a `GraphQLError` carrying the code in
+ * `extensions.code`, an error of the operation, never a refusal of the field.
+ */
+export declare const callProcedure: <Schema extends z.ZodType, Output, Failure>(procedure: Procedure<Schema>, input: unknown, call: (input: z.input<Schema>) => AsyncResult<unknown, Failure>, output: z.ZodType<Output>) => AsyncResult<Output, Exclude<Failure, Access> | InvalidInput>;
+/**
+ * What a DataLoader answers for one key read through `procedure`: the decoded
+ * value, or an `Error` — the registered refusal for a declared error, the
+ * defect otherwise — so one key's failure never fails the batch.
+ *
+ * **It answers a `Promise`, and that is the boundary**: a DataLoader's batch
+ * function answers a value or an `Error` per key.
+ */
+export declare const loadProcedure: <Schema extends z.ZodType, Output, Failure extends Caseable>(registry: Readonly<Record<string, ErrorClass>>, procedure: Procedure<Schema>, call: (input: z.input<Schema>) => AsyncResult<unknown, Failure>, input: unknown, output: z.ZodType<Output>) => Promise<Output | Error>;
+/**
+ * The `errors` option of a field that reads `procedure` through
+ * `loadProcedure`: the registered refusals it can answer, as the field's
+ * result union.
+ */
+export declare const procedureErrors: (registry: Readonly<Record<string, ErrorClass>>, procedure: AnyProcedure) => {
+  readonly types: (new (...args: never[]) => Error)[];
+};
+//#endregion
+export { type ProcedureConnectionOptions, type ProcedureFieldOptions, pluginName as default };

package/dist/index.mjs

@@ -0,0 +1,112 @@
+import SchemaBuilder, { BasePlugin, RootFieldBuilder } from "@pothos/core";
+import { ORPCError } from "@orpc/client";
+import "@unthrown/pothos/relay";
+import { outcomeOf } from "@unthrown/pothos";
+import { GraphQLError } from "graphql";
+import { Err, P, TaggedError, fromPromise, fromSafePromise, fromSafeThrowable } from "unthrown";
+import { z } from "zod";
+//#region src/contract.ts
+/**
+* The one Zod schema a procedure's contract declares for its input, typed as
+* declared — to derive a GraphQL argument's shape from it (`.shape`, a
+* `z.preprocess` around it) when the schema is built.
+*
+* A procedure whose contract holds anything but exactly one Zod input schema
+* is a mistake in the schema's source, not a request's: it throws, once, as
+* the schema is built.
+*/
+const contractInput = (procedure) => {
+	const [schema] = z.tuple([z.custom((value) => value instanceof z.ZodType)]).parse(procedure["~orpc"].inputSchemas);
+	return schema;
+};
+/**
+* An input the procedure's contract refuses, caught before the procedure is
+* called: each of the contract's issues, with its message and path.
+*/
+var InvalidInput = class extends TaggedError("InvalidInput") {
+	message = "Input does not satisfy the service contract";
+};
+/**
+* `call`, handed the input as the procedure's contract parses it and encodes
+* it back for the wire — its defaults applied, its codecs run, asynchronous
+* refinements included — or `InvalidInput` without calling it. A schema with a
+* transform cannot be encoded back: `call` gets the input as given, which the
+* contract admitted. A contract whose input is not one Zod
+* schema is a defect.
+*/
+const contractCall = (procedure, input, call) => fromSafeThrowable(() => contractInput(procedure))().toAsync().flatMap((schema) => fromSafePromise(schema.safeParseAsync(input)).flatMap((parsed) => parsed.success ? wireInput(schema, parsed.data, input) : Err(new InvalidInput({ issues: parsed.error.issues })))).flatMap((validated) => call(validated));
+const wireInput = (schema, parsed, given) => fromPromise(z.encodeAsync(schema, parsed), (cause, defect) => cause instanceof z.core.$ZodEncodeError ? "Unencodable" : defect(cause)).recoverErrCases((matcher) => matcher.with("Unencodable", () => given));
+/**
+* A procedure's answer decoded by `schema` — the shape the GraphQL field
+* resolves, codecs run. An answer the schema refuses is a defect: the service
+* broke its own contract.
+*/
+const contractOutput = (schema, value) => fromSafePromise(schema.parseAsync(value));
+//#endregion
+//#region src/procedure-field.ts
+const ACCESS_CODES = /* @__PURE__ */ new Set(["UNAUTHORIZED", "FORBIDDEN"]);
+/**
+* The refusals a procedure can answer, read from `registry`: one per error
+* code its contract declares, and `InvalidInput`. A code the registry lacks is
+* left out, and so are `UNAUTHORIZED` and `FORBIDDEN`, answered as GraphQL's
+* own error.
+*/
+const refusalsOf = (registry, procedure) => Object.fromEntries([...Object.keys(procedure["~orpc"].errorMap), "InvalidInput"].flatMap((code) => {
+	const Refusal = ACCESS_CODES.has(code) ? void 0 : registry[code];
+	return Refusal === void 0 ? [] : [[code, Refusal]];
+}));
+const accessRefusalOf = (cause) => cause instanceof ORPCError && (cause.code === "UNAUTHORIZED" || cause.code === "FORBIDDEN") ? new GraphQLError("Service refused access", { extensions: { code: cause.code } }) : void 0;
+/**
+* `call` handed the input the procedure's contract accepts, its answer decoded
+* by `output`. `UNAUTHORIZED` and `FORBIDDEN`, declared or not, leave the
+* error channel: they travel as a `GraphQLError` carrying the code in
+* `extensions.code`, an error of the operation, never a refusal of the field.
+*/
+const callProcedure = (procedure, input, call, output) => contractCall(procedure, input, (validated) => withoutAccess(call(validated))).flatMap((value) => contractOutput(output, value)).recoverDefect((cause) => {
+	throw accessRefusalOf(cause) ?? cause;
+});
+function withoutAccess(called) {
+	return called.flatMapErrCases((matcher, defect) => matcher.with({ code: "UNAUTHORIZED" }, { code: "FORBIDDEN" }, (failure) => defect(failure)).with(P._, (failure) => Err(failure)));
+}
+/**
+* What a DataLoader answers for one key read through `procedure`: the decoded
+* value, or an `Error` — the registered refusal for a declared error, the
+* defect otherwise — so one key's failure never fails the batch.
+*
+* **It answers a `Promise`, and that is the boundary**: a DataLoader's batch
+* function answers a value or an `Error` per key.
+*/
+const loadProcedure = async (registry, procedure, call, input, output) => outcomeOf(callProcedure(procedure, input, call, output), refusalsOf(registry, procedure));
+/**
+* The `errors` option of a field that reads `procedure` through
+* `loadProcedure`: the registered refusals it can answer, as the field's
+* result union.
+*/
+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 }) {
+		return this.resultField({
+			...options,
+			refusals: refusalsOf(this.builder.options.orpc?.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 }) {
+		return this.resultConnection({
+			...options,
+			refusals: refusalsOf(this.builder.options.orpc?.refusals ?? {}, procedure),
+			resolve: (parent, args, context) => callProcedure(procedure, input(args, parent), call(context), output).map((page) => connection(page, args))
+		}, connectionType);
+	};
+};
+//#endregion
+//#region src/plugin.ts
+const pluginName = "orpc";
+var PothosOrpcPlugin = class extends BasePlugin {};
+SchemaBuilder.registerPlugin(pluginName, PothosOrpcPlugin);
+defineProcedureFields();
+//#endregion
+export { InvalidInput, callProcedure, contractCall, contractInput, contractOutput, pluginName as default, loadProcedure, procedureErrors, refusalsOf };

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@btravstack/pothos",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.28.0",
+  "description": "Pothos fields that call oRPC procedures, each declared error answered as a typed GraphQL refusal",
+  "keywords": [
+    "graphql",
+    "orpc",
+    "pothos",
+    "typescript",
+    "unthrown"
+  ],
+  "homepage": "https://github.com/btravstack/btravstack#readme",
+  "bugs": {
+    "url": "https://github.com/btravstack/btravstack/issues"
+  },
+  "license": "MIT",
+  "author": "Benoit TRAVERS <benoit.travers.fr@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/btravstack/btravstack.git",
+    "directory": "packages/pothos"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./dist/index.mjs"
+  ],
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@btravstack/tsconfig": "0.4.0",
+    "@orpc/client": "2.0.0-beta.28",
+    "@orpc/contract": "2.0.0-beta.28",
+    "@pothos/core": "4.15.1",
+    "@pothos/plugin-errors": "4.9.3",
+    "@pothos/plugin-relay": "4.8.1",
+    "@types/node": "26.6.4",
+    "@unthrown/pothos": "0.1.0",
+    "@unthrown/vitest": "5.12.0",
+    "@vitest/coverage-v8": "5.0.3",
+    "graphql": "17.0.2",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "typescript-consumer": "npm:typescript@5.9.3",
+    "unthrown": "5.12.0",
+    "vitest": "5.0.3",
+    "zod": "4.6.5"
+  },
+  "peerDependencies": {
+    "@orpc/client": "^2.0.0-beta.28",
+    "@orpc/contract": "^2.0.0-beta.28",
+    "@pothos/core": "^4.15.0",
+    "@pothos/plugin-errors": "^4.9.0",
+    "@pothos/plugin-relay": "^4.8.0",
+    "@unthrown/pothos": "^0.1.0",
+    "graphql": "^16.10.0 || ^17.0.0",
+    "unthrown": "^5.12.0",
+    "zod": "^4.3.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts --clean",
+    "dev": "tsdown src/index.ts --format esm --dts --watch",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json && node ./node_modules/typescript-consumer/bin/tsc --noEmit -p tsconfig.test-d.json"
+  }
 }