### Install ts-proto for TypeScript Integration

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/getting-started.md

Installs the ts-proto package, which is recommended for generating TypeScript types alongside the GraphQL schema.

```bash
npm install ts-proto
```

--------------------------------

### Install proto-graphql Dependencies (npm/pnpm)

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/getting-started.md

Installs the necessary packages for protoc-gen-pothos and Pothos GraphQL using either npm or pnpm. Ensure Node.js v18 or later is installed.

```bash
npm install @proto-graphql/protoc-gen-pothos pothos
# or
pnpm add @proto-graphql/protoc-gen-pothos pothos
```

--------------------------------

### Configure buf.yaml for proto-graphql Dependency

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/getting-started.md

Sets up the buf.yaml file to include the proto-graphql dependency, enabling the use of GraphQL annotations within Protocol Buffer definitions.

```yaml
version: v2
deps:
  - buf.build/proto-graphql/proto-graphql
```

--------------------------------

### Complete buf.gen.yaml Example

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/configuration.md

A comprehensive example of a buf.gen.yaml file demonstrating the configuration for both protoc-gen-ts_proto and protoc-gen-pothos plugins, including various options.

```yaml
# proto/buf.gen.yaml
version: v2
plugins:
  - local: protoc-gen-ts_proto
    out: ../src/__generated__/proto
    opt:
      - esModuleInterop=true
      - unrecognizedEnum=false
      - outputTypeRegistry=true

  - local: protoc-gen-pothos
    out: ../src/__generated__/pothos
    opt:
      - pothos_builder_path=../../builder
      - import_prefix=../proto
      - protobuf_lib=ts-proto
      - partial_inputs=true
      - emit_imported_files=false
      - scalar=google.type.Date=Date
```

--------------------------------

### Define User Protocol Buffer Schema

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/getting-started.md

Defines a simple User message in Protocol Buffers with an ID, name, and email. It imports graphql/schema.proto to enable GraphQL annotations.

```protobuf
syntax = "proto3";

package example;

import "graphql/schema.proto";

message User {
  // Required. Output only.
  uint64 id = 1;
  // Required.
  string name = 2;
  string email = 3;
}
```

--------------------------------

### Create Pothos GraphQL Schema Builder

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/getting-started.md

Initializes a Pothos GraphQL SchemaBuilder instance. This builder will be used to define the GraphQL schema, integrating with generated types.

```typescript
import SchemaBuilder from "@pothos/core";

const builder = new SchemaBuilder({});

export { builder };
```

--------------------------------

### Generate Code with Buf CLI

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/getting-started.md

Commands to navigate to the proto directory, update dependencies, and generate code using Buf. This process generates both TypeScript types and Pothos GraphQL schema files.

```bash
cd proto
buf dep update
buf generate
```

--------------------------------

### Install proto-graphql-js and Pothos Dependencies

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

Installs the `protoc-gen-pothos` plugin, Pothos core, and recommended protobuf runtime libraries (ts-proto or protobuf-es). These are essential for setting up the code generation environment.

```bash
# Install protoc-gen-pothos and Pothos
npm install protoc-gen-pothos @pothos/core

# For ts-proto runtime (recommended)
npm install ts-proto

# For protobuf-es v2 runtime
npm install @bufbuild/protobuf@^2.0.0 @bufbuild/protoc-gen-es@^2.0.0
```

--------------------------------

### Configure buf.gen.yaml for Code Generation

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/getting-started.md

Configures buf.gen.yaml to specify code generation plugins. It includes settings for ts-proto to generate TypeScript types and protoc-gen-pothos to generate Pothos GraphQL schema, with specified output directories and options.

```yaml
version: v2
plugins:
  # Generate TypeScript types with ts-proto
  - local: protoc-gen-ts_proto
    out: ../src/__generated__/proto
    opt:
      - esModuleInterop=true
      - unrecognizedEnum=false
      - outputTypeRegistry=true

  # Generate Pothos GraphQL schema
  - local: protoc-gen-pothos
    out: ../src/__generated__/pothos
    opt:
      - pothos_builder_path=../../builder
      - import_prefix=../proto
```

--------------------------------

### Complete Proto-GraphQL Example

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/proto-annotations/reference.md

A full example of a Protobuf schema using proto-graphql directives, including field options and enum definitions. This schema is then translated into a GraphQL schema, showcasing the generated types, unions, and enums.

```protobuf
syntax = "proto3";

package example;

import "graphql/schema.proto";

option (graphql.schema) = {
  type_prefix: "Api"
  ignore_requests: true
};

message User {
  // Required. Output only.
  uint64 id = 1 [(graphql.field).id = true];

  // Required.
  string name = 2;

  string email = 3;

  Role role = 4;

  string internal_note = 5 [(graphql.field).ignore = true];

  oneof profile {
    BasicProfile basic = 6;
    PremiumProfile premium = 7;
  }
}

enum Role {
  ROLE_UNSPECIFIED = 0;
  ROLE_ADMIN = 1;
  ROLE_USER = 2;
  ROLE_LEGACY = 3 [(graphql.enum_value).ignore = true];
}

message BasicProfile {
  string bio = 1;
}

message PremiumProfile {
  string bio = 1;
  repeated string features = 2;
}
```

--------------------------------

### Map 64-bit Integer Scalar Types

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/configuration.md

An example demonstrating how to map various 64-bit integer Protobuf types (including signed, unsigned, and value wrappers) to the GraphQL BigInt scalar.

```yaml
opt:
  - scalar=int64=BigInt
  - scalar=uint64=BigInt
  - scalar=sint64=BigInt
  - scalar=fixed64=BigInt
  - scalar=sfixed64=BigInt
  - scalar=google.protobuf.Int64Value=BigInt
  - scalar=google.protobuf.UInt64Value=BigInt
```

--------------------------------

### Apply File-Level Options in ProtoBuf

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

Applies global options to all types within a Protocol Buffers file using the `graphql.schema` option. This allows for consistent naming prefixes and can be used to ignore request and response types globally. The example demonstrates prefixing all generated types and ignoring specific request/response messages.

```protobuf
syntax = "proto3";

package example.api;

import "graphql/schema.proto";

option (graphql.schema) = {
  type_prefix: "Api"
  ignore_requests: true
  ignore_responses: true
};

message User {
  uint64 id = 1;
  string name = 2;
}

// Ignored due to ignore_requests option
message GetUserRequest {
  uint64 id = 1;
}

// Ignored due to ignore_responses option
message GetUserResponse {
  User user = 1;
}
```

--------------------------------

### Integrate Generated Types into Pothos Schema

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

Demonstrates how to use the generated Pothos type references (User$Ref, UserInput$Ref, etc.) within a Pothos schema definition to create a mutation field. This example shows creating a user with input validation and resolution.

```typescript
// Usage in schema
import { builder } from "./builder";
import {
  User$Ref,
  UserInput$Ref,
  UserAddress$Ref,
  Role$Ref,
} from "./__generated__/pothos/example/user.pb.pothos";

builder.mutationType({
  fields: (t) => ({
    createUser: t.field({
      type: User$Ref,
      args: {
        input: t.arg({ type: UserInput$Ref, required: true }),
      },
      resolve: async (_, { input }) => {
        return {
          id: BigInt(Date.now()),
          name: input.name,
          address: input.address ? {
            city: input.address.city,
            country: input.address.country,
          } : undefined,
        };
      },
    }),
  }),
});
```

--------------------------------

### Use Generated Types in GraphQL Schema

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/getting-started.md

Demonstrates how to use the generated User type reference (User$Ref) within a Pothos GraphQL schema. It defines a query field 'user' that resolves to a sample user object, utilizing the generated type for schema definition.

```typescript
import { builder } from "./builder";
import { User$Ref } from "./__generated__/pothos/example/user.pb.pothos";

// Register the generated type with your schema
builder.queryType({
  fields: (t) => ({
    user: t.field({
      type: User$Ref,
      resolve: () => ({
        id: 1n,
        name: "Alice",
        email: "alice@example.com",
      }),
    }),
  }),
});

export const schema = builder.toSchema();
```

--------------------------------

### Scalar Type Mapping Configuration for protoc-gen-pothos

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/packages/protoc-gen-pothos/README.md

This YAML snippet demonstrates how to configure custom scalar type mappings within protoc-gen-pothos. It shows examples of mapping Protobuf types like int64 and google.type.Date to GraphQL scalars like BigInt and Date.

```yaml
opt:
  - scalar=google.type.Date=Date

```

```yaml
opt:
  - scalar=int64=BigInt
  - scalar=uint64=BigInt
  - scalar=sint64=BigInt
  - scalar=fixed64=BigInt
  - scalar=sfixed64=BigInt
  - scalar=google.protobuf.Int64Value=BigInt
  - scalar=google.protobuf.UInt64Value=BigInt
  - scalar=google.protobuf.SInt64Value=BigInt
  - scalar=google.protobuf.Fixed64Value=BigInt
  - scalar=google.protobuf.SFixed64Value=BigInt

```

--------------------------------

### Protobuf Enum Value Name Conversion for GraphQL

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/type-mapping/enums.md

Shows how Protobuf enum value names are converted for GraphQL by removing the enum name prefix. For example, `MY_ENUM_FOO` becomes `FOO` in the GraphQL schema.

```protobuf
enum MyEnum {
  MY_ENUM_UNSPECIFIED = 0;
  MY_ENUM_FOO = 1;
  MY_ENUM_BAR = 2;
}
```

```graphql
enum MyEnum {
  FOO
  BAR
}
```

--------------------------------

### Define Protobuf Oneof Extension (TypeScript)

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-protobuf-es.md

This example showcases the 'protobufOneof' extension for defining oneof fields in protobuf. It specifies the full name, name, message name, and package of the oneof. Crucially, it also lists the fields that are part of this oneof, including their names and types, enabling proper GraphQL union type generation.

```typescript
extensions: {
  protobufOneof: {
    fullName: "testapis.oneof.OneofParent.required_oneof_members",
    name: "required_oneof_members",
    messageName: "OneofParent",
    package: "testapis.oneof",
    fields: [
      { name: "required_message1", type: "testapis.oneof.OneofMemberMessage1" },
      { name: "required_message2", type: "testapis.oneof.OneofMemberMessage2" },
    ],
  },
}
```

--------------------------------

### Convert Protobuf Oneofs to GraphQL Union Types

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

This example shows how to convert protobuf 'oneof' fields into GraphQL union types. The 'graphql/schema.proto' import and specific options enable this conversion, allowing a single field to represent multiple possible types.

```protobuf
syntax = "proto3";

package example;

import "graphql/schema.proto";

message Media {
  string title = 1;

  // Required. disallow not_set.
  oneof content {
    Image image = 2;
    Video video = 3;
  }
}

message Image {
  string url = 1;
  int32 width = 2;
  int32 height = 3;
}

message Video {
  string url = 1;
  int32 duration = 2;
}
```

--------------------------------

### Build and Test Commands (Bash)

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/CLAUDE.md

Common commands for building, testing, linting, and formatting the project using pnpm. Includes commands for running all tests, E2E tests, and specific test files.

```bash
# Build all packages
pnpm build

# Run unit tests
pnpm test

# Generate E2E test APIs and run E2E tests
pnpm test:e2e:gen
pnpm test:e2e

# Lint and format (Biome)
pnpm lint

Run a single test file:
pnpm vitest run path/to/file.test.ts
```

--------------------------------

### Buf Code Generation Commands

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/buf-setup.md

A sequence of bash commands to execute Buf code generation. This includes navigating to the proto directory, updating dependencies, and running the generation process.

```bash
# Navigate to proto directory
cd proto

# Update dependencies (first time or when buf.yaml changes)
buf dep update

# Generate code
buf generate
```

--------------------------------

### Buf Configuration for Protobuf and Pothos GraphQL

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/packages/protoc-gen-pothos/README.md

This YAML configuration sets up Buf to handle Protobuf dependencies and generate code using both ts-proto and protoc-gen-pothos. It specifies the output directories and plugin paths for each generator.

```yaml
# proto/buf.yaml
version: v1
deps:
  - buf.build/proto-graphql/proto-graphql

```

```yaml
# proto/buf.gen.yaml
version: v1
plugins:
  - name: ts
    out: ../src/__generated__/proto
    strategy: all
    path: ../node_modules/.bin/protoc-gen-ts_proto
    opt:
      - esModuleInterop=true     # required
      - unrecognizedEnum=false   # required
      - outputTypeRegistry=true  # required
    strategy: all
  - name: pothos
    path: ../node_modules/.bin/protoc-gen-pothos
    out: ../src/__generated__/pothos
    opt:
      - pothos_builder_path=../../builder
      - import_prefix=../proto

```

--------------------------------

### Buf Workspace and Dependencies (buf.yaml)

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/buf-setup.md

Configures the Buf workspace and specifies project dependencies. The `buf.build/proto-graphql/proto-graphql` dependency is crucial for providing GraphQL annotations used in proto files.

```yaml
# proto/buf.yaml
version: v2
deps:
  - buf.build/proto-graphql/proto-graphql
```

--------------------------------

### Define Shape Type for Input with TypeScript

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-protobuf-es-v1.md

Illustrates how to define a '$Shape' type alias in TypeScript for a GraphQL input type, deriving field types from a protobuf message. This example shows an optional nested message field.

```typescript
export type PostInput$Shape = {
  title: Post["title"];                    // Required field
  publishedDate?: DateInput$Shape | null;  // Optional nested message
};
```

--------------------------------

### Import GraphQL Schema Annotation

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/proto-annotations/reference.md

This snippet shows how to import the GraphQL schema annotation into your proto file. This is a prerequisite for using any of the GraphQL proto annotations.

```protobuf
import "graphql/schema.proto";
```

--------------------------------

### Resolve Protobuf Oneof Fields in GraphQL

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-protobuf-es.md

Provides examples of GraphQL resolvers for Protobuf 'oneof' fields. It shows how to access the 'value' property of the oneof object for both required and optional fields, handling potential null or undefined values.

```typescript
requiredOneofMembers: t.field({
  type: OneofParentRequiredOneofMembers$Ref,
  nullable: false,
  description: "Required. disallow not_set.",
  resolve: (source) => {
    const value = source.requiredOneofMembers.value;
    if (value == null) {
      throw new Error("requiredOneofMembers should not be null");
    }
    return value;
  },
  extensions: { protobufField: { name: "required_oneof_members" } },
}),

optionalOneofMembers: t.field({
  type: OneofParentOptionalOneofMembers$Ref,
  nullable: true,
  resolve: (source) => {
    return source.optionalOneofMembers.value;  // returns undefined if not set
  },
  extensions: { protobufField: { name: "optional_oneof_members" } },
}),
```

--------------------------------

### Repeated Field Nullability in TypeScript

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-protobuf-es-v1.md

Demonstrates how to define nullability for repeated (list) fields in proto-graphql-js using TypeScript. It shows examples for required lists (where neither the list nor its items can be null) and optional lists (where the list itself can be null, but its items cannot).

```typescript
requiredPrimitivesList: t.field({
  type: [Primitives$Ref],
  nullable: { list: false, items: false },
  description: "Required.",
  resolve: (source) => {
    return source.requiredPrimitivesList!;
  },
  extensions: {
    protobufField: {
      name: "required_primitives_list",
      typeFullName: "testapis.primitives.Primitives",
    },
  },
}),

optionalPrimitivesList: t.expose("optionalPrimitivesList", {
  type: [Primitives$Ref],
  nullable: { list: true, items: false },
  description: "Optional.",
  extensions: {
    protobufField: {
      name: "optional_primitives_list",
      typeFullName: "testapis.primitives.Primitives",
    },
  },
}),
```

--------------------------------

### Configure Pothos Plugin for Proto-GraphQL Generation

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

This configuration file (buf.gen.yaml) sets up the protoc-gen-pothos plugin for generating GraphQL schemas from Protocol Buffers. It specifies output paths, options for ts-proto integration, and custom scalar mappings.

```yaml
version: v2
plugins:
  - local: protoc-gen-pothos
    out: ../src/__generated__/pothos
    opt:
      # Required: Path to Pothos builder (relative to generated files)
      - pothos_builder_path=../../builder

      # Required for ts-proto: Path to ts-proto output
      - import_prefix=../proto

      # Protobuf runtime: ts-proto | protobuf-es-v1 | protobuf-es
      - protobuf_lib=ts-proto

      # Generate types for imported proto files
      - emit_imported_files=true

      # Generate partial input types with all fields nullable
      - partial_inputs=true

      # Exclude scalar oneofs from unions
      - ignore_non_message_oneof_fields=true

      # Custom scalar mappings
      - scalar=int64=BigInt
      - scalar=uint64=BigInt
      - scalar=google.type.Date=Date
```

--------------------------------

### Squash Protobuf Oneof into GraphQL Union Type

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

This example shows how to configure a protobuf message containing only a oneof field to be directly converted into a GraphQL union type. The `squash_union` option on both the message and the oneof field enables this behavior.

```protobuf
syntax = "proto3";

package example;

import "graphql/schema.proto";

message Content {
  option (graphql.object_type).squash_union = true;

  oneof content {
    option (graphql.oneof).squash_union = true;
    Blog blog = 1 [(graphql.object_type).squash_union = true];
    Video video = 2 [(graphql.object_type).squash_union = true];
  }
}

message Blog {
  string title = 1;
  string body = 2;
}

message Video {
  string url = 1;
  int32 duration = 2;
}

message Post {
  // Required.
  string id = 1;
  Content content = 2;
}
```

--------------------------------

### Buf Configuration for ts-proto Runtime

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

Configures Buf for code generation using the ts-proto runtime. This involves setting up `buf.yaml` for dependencies and `buf.gen.yaml` to specify the `protoc-gen-ts_proto` for message types and `protoc-gen-pothos` for GraphQL schema generation, including custom options.

```yaml
# proto/buf.yaml
version: v2
deps:
  - buf.build/proto-graphql/proto-graphql
```

```yaml
# proto/buf.gen.yaml
version: v2
plugins:
  # ts-proto for TypeScript message types
  - local: protoc-gen-ts_proto
    out: ../src/__generated__/proto
    opt:
      - esModuleInterop=true
      - unrecognizedEnum=false
      - outputTypeRegistry=true

  # protoc-gen-pothos for GraphQL schema
  - local: protoc-gen-pothos
    out: ../src/__generated__/pothos
    opt:
      - pothos_builder_path=../../builder
      - import_prefix=../proto
      - protobuf_lib=ts-proto
```

--------------------------------

### Set Import Prefix for Generated Files

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/configuration.md

Defines the path to the output directory of ts-proto or protobuf-es generated files. This is required when using ts-proto to correctly reference generated types.

```yaml
opt:
  - import_prefix=../proto
```

--------------------------------

### Pothos Builder Initialization

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

Initializes a Pothos `SchemaBuilder` instance. This file (`builder.ts`) is typically imported by other schema definition files and serves as the central point for configuring the GraphQL schema builder.

```typescript
// src/builder.ts
import SchemaBuilder from "@pothos/core";

const builder = new SchemaBuilder({});

export { builder };
```

--------------------------------

### Buf Generation Configuration with ts-proto (buf.gen.yaml)

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/buf-setup.md

Sets up Buf code generation using ts-proto for TypeScript message types and protoc-gen-pothos for GraphQL schema generation. It includes essential options for both plugins to ensure correct output and type handling.

```yaml
# proto/buf.gen.yaml
version: v2
plugins:
  # ts-proto for TypeScript message types
  - local: protoc-gen-ts_proto
    out: ../src/__generated__/proto
    opt:
      - esModuleInterop=true      # Required for proper imports
      - unrecognizedEnum=false    # Required
      - outputTypeRegistry=true   # Required for type resolution

  # protoc-gen-pothos for GraphQL schema
  - local: protoc-gen-pothos
    out: ../src/__generated__/pothos
    opt:
      - pothos_builder_path=../../builder
      - import_prefix=../proto
      - protobuf_lib=ts-proto
```

--------------------------------

### Enable Partial Input Types

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/configuration.md

Generates partial input types where all fields are nullable. When enabled, both regular input types (e.g., UserInput) and partial input types (e.g., UserPartialInput) are created.

```yaml
opt:
  - partial_inputs=true
```

--------------------------------

### GraphQL Annotations in Proto Files

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/buf-setup.md

Demonstrates how to use GraphQL annotations within a proto3 file to customize schema generation. The `graphql.field` annotation is used here to mark a field as an ID and specify its output-only nature.

```protobuf
syntax = "proto3";
package example;

import "graphql/schema.proto";

message User {
  // Required. Output only.
  uint64 id = 1 [(graphql.field).id = true];
  // Required.
  string name = 2;
}
```

--------------------------------

### Configure File-Level GraphQL Schema Options

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/proto-annotations/reference.md

Applies file-level options to all types within a proto file. It allows setting a type prefix and ignoring messages based on their names (Request/Response).

```protobuf
option (graphql.schema) = {
  type_prefix: "Api"
  ignore_requests: true
  ignore_responses: true
};
```

--------------------------------

### Generated File Imports in TypeScript

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-protobuf-es.md

Demonstrates the import patterns for generated files in TypeScript, including message types, schema symbols, and utilities from `@bufbuild/protobuf`. It highlights the structure of imports from `@bufbuild/protobuf` and Pothos core types.

```typescript
// @generated by protoc-gen-pothos v0.6.2 with parameter "protobuf_lib=protobuf-es,..."

import { builder } from "../../builder";

// Import message types AND Schema symbols
import {
  User,
  UserSchema,
  Address,
  AddressSchema,
} from "@example/proto/user_pb";

// Import create and isMessage from @bufbuild/protobuf
import { create, isMessage } from "@bufbuild/protobuf";

// Import Pothos types
import { InputObjectRef, EnumRef } from "@pothos/core";
```

--------------------------------

### Configure GraphQL Input Type Options

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/proto-annotations/reference.md

Configures options for GraphQL input type generation. It allows disabling the generation of partial input types and ignoring input types altogether.

```protobuf
// Output only (no input type)
message ReadOnlyData {
  option (graphql.input_type).ignore = true;
  string value = 1;
}

// Disable partial input
message StrictInput {
  option (graphql.input_type).no_partial = true;
  string required_field = 1;
}
```

--------------------------------

### Define User and Config Messages with Partial Input Options in ProtoBuf

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

Defines Protocol Buffers messages, `User` and `Config`, demonstrating the use of options related to partial input type generation. The `User` message will have a partial input type generated by default due to the global `partial_inputs` option. The `Config` message explicitly disables partial input generation using `option (graphql.input_type).no_partial = true`.

```protobuf
syntax = "proto3";

package example;

import "graphql/schema.proto";

message User {
  // Required.
  string name = 1;
  string email = 2;
  string bio = 3;
}

message Config {
  option (graphql.input_type).no_partial = true;

  // Required.
  string key = 1;
  // Required.
  string value = 2;
}
```

--------------------------------

### Buf Generation Configuration with protobuf-es v1 (buf.gen.yaml)

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/buf-setup.md

Provides the Buf code generation configuration for legacy projects using protobuf-es v1. It utilizes `protoc-gen-es` for TypeScript types and `protoc-gen-pothos` for GraphQL schema generation.

```yaml
# proto/buf.gen.yaml
version: v2
plugins:
  # protobuf-es v1 for TypeScript message types
  - local: protoc-gen-es
    out: ../src/__generated__/proto
    opt:
      - target=ts

  # protoc-gen-pothos for GraphQL schema
  - local: protoc-gen-pothos
    out: ../src/__generated__/pothos
    opt:
      - pothos_builder_path=../../builder
      - import_prefix=../proto
      - protobuf_lib=protobuf-es-v1
```

--------------------------------

### Configure Partial Input Types in buf.gen.yaml

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

Enables the generation of partial input types for Protocol Buffers messages using a `buf.gen.yaml` configuration. When `partial_inputs=true` is set, the plugin generates a secondary input type for each message where all fields are nullable, facilitating partial updates. This can be disabled for specific messages using the `no_partial` option.

```yaml
# proto/buf.gen.yaml
version: v2
plugins:
  - local: protoc-gen-pothos
    out: ../src/__generated__/pothos
    opt:
      - pothos_builder_path=../../builder
      - import_prefix=../proto
      - partial_inputs=true
```

--------------------------------

### Specify Protobuf Implementation

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/configuration.md

Selects the protobuf implementation to use for type discrimination. Options include 'ts-proto', 'protobuf-es-v1', and 'protobuf-es'. The default is 'ts-proto'.

```yaml
opt:
  - protobuf_lib=ts-proto
```

--------------------------------

### Basic Protobuf to GraphQL Type Conversion

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/type-mapping/messages.md

Demonstrates the default conversion of a Protobuf message into GraphQL ObjectType and InputType. No external dependencies are required for this basic conversion.

```protobuf
message User {
  string name = 1;
  string email = 2;
}
```

```graphql
type User {
  name: String
  email: String
}

input UserInput {
  name: String
  email: String
}
```

--------------------------------

### Generate Basic Object Type from Protobuf Message (TypeScript)

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-protobuf-es-v1.md

Demonstrates how a protobuf message like 'Date' is converted into a GraphQL object type in TypeScript. It includes import statements, object type definition using `builder.objectRef`, field exposure using `t.expose`, and type discrimination with `isTypeOf`. Dependencies include the protobuf-es runtime.

```typescript
import { Date } from "@testapis/protobuf-es/testapis/custom_types/date_pb";

export const Date$Ref = builder.objectRef<Date>("Date");
builder.objectType(Date$Ref, {
  name: "Date",
  fields: (t) => ({
    year: t.expose("year", {
      type: "Int",
      nullable: false,
      extensions: { protobufField: { name: "year", typeFullName: "uint32" } },
    }),
    month: t.expose("month", {
      type: "Int",
      nullable: false,
      extensions: { protobufField: { name: "month", typeFullName: "uint32" } },
    }),
    day: t.expose("day", {
      type: "Int",
      nullable: false,
      extensions: { protobufField: { name: "day", typeFullName: "uint32" } },
    }),
  }),
  isTypeOf: (source) => {
    return source instanceof Date;
  },
  extensions: {
    protobufMessage: {
      fullName: "testapis.custom_types.Date",
      name: "Date",
      package: "testapis.custom_types",
    },
  },
});
```

--------------------------------

### Represent 64-bit Integers as Strings in TypeScript

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-ts-proto.md

Illustrates how proto-graphql-js represents 64-bit integer fields as strings in TypeScript. This ensures compatibility and proper handling of large integer values.

```typescript
requiredInt64Value: t.expose("requiredInt64Value", {
  type: "String",
  nullable: false,
  extensions: {
    protobufField: { name: "required_int64_value", typeFullName: "int64" },
  },
}),
```

--------------------------------

### Mapping 64-bit Integers to GraphQL Int (YAML)

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/type-mapping/scalars.md

This YAML snippet demonstrates how to map 64-bit Protobuf integer types to the GraphQL `Int` scalar. A warning is included, as this can lead to precision loss for values exceeding `Number.MAX_SAFE_INTEGER` in JavaScript.

```yaml
opt:
  - scalar=int64=Int
  - scalar=uint64=Int
```

--------------------------------

### Buf Generation Configuration with protobuf-es v2 (buf.gen.yaml)

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/buf-setup.md

Configures Buf code generation for projects using protobuf-es v2. It specifies the `protoc-gen-es` plugin for TypeScript types and `protoc-gen-pothos` for GraphQL schema generation, along with necessary options.

```yaml
# proto/buf.gen.yaml
version: v2
plugins:
  # protobuf-es v2 for TypeScript message types
  - local: protoc-gen-es
    out: ../src/__generated__/proto
    opt:
      - target=ts

  # protoc-gen-pothos for GraphQL schema
  - local: protoc-gen-pothos
    out: ../src/__generated__/pothos
    opt:
      - pothos_builder_path=../../builder
      - import_prefix=../proto
      - protobuf_lib=protobuf-es
```

--------------------------------

### Adding Type Prefixes to GraphQL Types

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/type-mapping/messages.md

Demonstrates how to add a prefix to all generated GraphQL type names using the `(graphql.schema).type_prefix` option. This helps in namespacing and avoiding naming conflicts.

```protobuf
option (graphql.schema).type_prefix = "Api";

message User {
  string name = 1;
}
```

```graphql
type ApiUser {
  name: String
}
```

--------------------------------

### Convert Post Input to Proto Message

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-protobuf-es-v1.md

Shows a TypeScript '$toProto' function to convert a Post input shape to a protobuf Post message. It includes logic for recursively converting nested messages like 'publishedDate'.

```typescript
export function PostInput$toProto(
  input: PostInput$Shape | null | undefined,
): Post {
  return new Post({
    title: input?.title ?? undefined,
    publishedDate: input?.publishedDate
      ? DateInput$toProto(input.publishedDate)
      : undefined,
  });
}
```

--------------------------------

### Enable Emitting Imported Files

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/configuration.md

When set to true, this option generates GraphQL types for messages defined in imported .proto files, not just the files being processed directly.

```yaml
opt:
  - emit_imported_files=true
```

--------------------------------

### Generated GraphQL Schema from Protobuf

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/proto-annotations/reference.md

The GraphQL schema generated from the provided Protobuf schema. It includes types for User, Role, BasicProfile, and PremiumProfile, along with a union for UserProfile, reflecting the Protobuf structure and directives.

```graphql
type ApiUser {
  id: ID!
  name: String!
  email: String
  role: ApiRole
  profile: ApiUserProfile
}

union ApiUserProfile = ApiBasicProfile | ApiPremiumProfile

enum ApiRole {
  ADMIN
  USER
}

type ApiBasicProfile {
  bio: String
}

type ApiPremiumProfile {
  bio: String
  features: [String!]!
}
```

--------------------------------

### Custom Scalar Mapping Configuration (YAML)

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/type-mapping/scalars.md

This snippet shows how to configure custom scalar mappings in YAML format. It demonstrates mapping Protobuf types like `int64` and `google.protobuf.Int64Value` to GraphQL `BigInt`. This is useful for handling large integer values that exceed JavaScript's safe integer limits.

```yaml
opt:
  - scalar=int64=BigInt
  - scalar=uint64=BigInt
  - scalar=sint64=BigInt
  - scalar=fixed64=BigInt
  - scalar=sfixed64=BigInt
  - scalar=google.protobuf.Int64Value=BigInt
  - scalar=google.protobuf.UInt64Value=BigInt
  - scalar=google.protobuf.SInt64Value=BigInt
  - scalar=google.protobuf.Fixed64Value=BigInt
  - scalar=google.protobuf.SFixed64Value=BigInt
```

--------------------------------

### Generate Basic Input Type in TypeScript

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-protobuf-es.md

This snippet demonstrates the generation of a basic input type for a Protocol Buffer message with primitive fields. It defines the TypeScript shape and implements the GraphQL input object reference using the builder.

```typescript
export type PrimitivesInput$Shape = {
  requiredInt32Value: Primitives["requiredInt32Value"];
  requiredStringValue: Primitives["requiredStringValue"];
  requiredBoolValue: Primitives["requiredBoolValue"];
};

export const PrimitivesInput$Ref: InputObjectRef<PrimitivesInput$Shape> = 
  builder.inputRef<PrimitivesInput$Shape>("PrimitivesInput").implement({
    fields: (t) => ({
      requiredInt32Value: t.field({
        type: "Int",
        required: true,
        extensions: {
          protobufField: { name: "required_int32_value", typeFullName: "int32" },
        },
      }),
      requiredStringValue: t.field({
        type: "String",
        required: true,
        extensions: {
          protobufField: { name: "required_string_value", typeFullName: "string" },
        },
      }),
      requiredBoolValue: t.field({
        type: "Boolean",
        required: true,
        extensions: {
          protobufField: { name: "required_bool_value", typeFullName: "bool" },
        },
      }),
    }),
    extensions: {
      protobufMessage: {
        fullName: "example.Primitives",
        name: "Primitives",
        package: "example",
      },
    },
  });
```

--------------------------------

### Generated GraphQL Schema from Proto Definition

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

Illustrates the GraphQL schema generated from the `user.proto` definition. It includes a `User` object type, a corresponding `UserInput` input type, and a `Role` enum type, reflecting the protobuf structure and annotations.

```graphql
type User {
  id: ID!
  name: String!
  email: String
  role: Role
}

input UserInput {
  name: String!
  email: String
  role: Role
}

enum Role {
  ADMIN
  USER
}
```

--------------------------------

### Configure GraphQL Field Options

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/proto-annotations/reference.md

Configures options for individual fields within a message. This includes ignoring fields, renaming them, skipping resolvers, using the ID type, and controlling nullability for inputs and outputs.

```protobuf
message User {
  // Use ID type
  uint64 id = 1 [(graphql.field).id = true];

  // Rename field
  string user_name = 2 [(graphql.field).name = "name"];

  // Ignore field
  string internal = 3 [(graphql.field).ignore = true];

  // Skip resolver
  string computed = 4 [(graphql.field).skip_resolver = true];

  // Force non-null output
  string required = 5 [(graphql.field).output_nullability = NON_NULL];

  // Force nullable input
  string optional = 6 [(graphql.field).input_nullability = NULLABLE];
}
```

--------------------------------

### Configure Custom Scalar Mappings in buf.gen.yaml

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

Maps Protocol Buffers types to custom GraphQL scalars using a `buf.gen.yaml` configuration file. This is useful for handling types like 64-bit integers or specific date/money types that require custom GraphQL representations. The `scalar` option in the plugin configuration specifies the mapping.

```yaml
# proto/buf.gen.yaml
version: v2
plugins:
  - local: protoc-gen-pothos
    out: ../src/__generated__/pothos
    opt:
      - pothos_builder_path=../../builder
      - import_prefix=../proto
      - protobuf_lib=ts-proto
      # Map 64-bit integers to BigInt scalar
      - scalar=int64=BigInt
      - scalar=uint64=BigInt
      - scalar=sint64=BigInt
      - scalar=google.protobuf.Int64Value=BigInt
      - scalar=google.protobuf.UInt64Value=BigInt
      # Map custom types
      - scalar=google.type.Date=Date
      - scalar=google.type.Money=Money
```

--------------------------------

### Basic Protobuf to GraphQL Enum Conversion

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/type-mapping/enums.md

Demonstrates the fundamental conversion of a Protobuf enum to its GraphQL equivalent. Protobuf enums are mapped directly to GraphQL enums, with the `_UNSPECIFIED` convention typically being excluded.

```protobuf
enum Role {
  ROLE_UNSPECIFIED = 0;
  ROLE_ADMIN = 1;
  ROLE_USER = 2;
}
```

```graphql
enum Role {
  ADMIN
  USER
}
```

--------------------------------

### Configure GraphQL Object Type Options

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/proto-annotations/reference.md

Configures options for GraphQL object type generation. This includes ignoring messages, squashing oneofs into unions, generating interfaces, and overriding type names.

```protobuf
// Generate as interface
message Node {
  option (graphql.object_type).interface = true;
  uint64 id = 1;
}

// Generate as union
message Content {
  option (graphql.object_type).squash_union = true;
  oneof content {
    Blog blog = 1;
    Video video = 2;
  }
}

// Rename type
message InternalUser {
  option (graphql.object_type).name = "User";
  string name = 1;
}

// Ignore message
message Secret {
  option (graphql.object_type).ignore = true;
  string data = 1;
}
```

--------------------------------

### Generate Basic Object Type in TypeScript

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-ts-proto.md

This snippet demonstrates how a basic protobuf message like 'Date' is converted into a GraphQL object type using ts-proto. It includes importing the generated type, defining a reference, and configuring the object type with its fields, types, nullability, and protobuf extensions. The `isTypeOf` function is crucial for type discrimination using the `$type` property.

```typescript
import { Date } from "@testapis/ts-proto/testapis/custom_types/date";

export const Date$Ref = builder.objectRef<Date>("Date");
builder.objectType(Date$Ref, {
  name: "Date",
  fields: (t) => ({
    year: t.expose("year", {
      type: "Int",
      nullable: false,
      extensions: { protobufField: { name: "year", typeFullName: "uint32" } },
    }),
    month: t.expose("month", {
      type: "Int",
      nullable: false,
      extensions: { protobufField: { name: "month", typeFullName: "uint32" } },
    }),
    day: t.expose("day", {
      type: "Int",
      nullable: false,
      extensions: { protobufField: { name: "day", typeFullName: "uint32" } },
    }),
  }),
  isTypeOf: (source) => {
    return (source as Date | { $type: string & {}; }).$type ===
      "testapis.custom_types.Date";
  },
  extensions: {
    protobufMessage: {
      fullName: "testapis.custom_types.Date",
      name: "Date",
      package: "testapis.custom_types",
    },
  },
});
```

--------------------------------

### Basic Object Type Generation in TypeScript

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-protobuf-es.md

Demonstrates how to generate a basic object type in TypeScript using protobuf-es v2. It includes importing the message and schema, defining the object reference, and configuring fields with their protobuf metadata. The `isTypeOf` function uses `isMessage` for type checking.

```typescript
import { Primitives, PrimitivesSchema } from "@example/proto/primitives_pb";
import { isMessage } from "@bufbuild/protobuf";

export const Primitives$Ref = builder.objectRef<Primitives>("Primitives");
builder.objectType(Primitives$Ref, {
  name: "Primitives",
  fields: (t) => ({
    requiredInt32Value: t.expose("requiredInt32Value", {
      type: "Int",
      nullable: false,
      extensions: {
        protobufField: { name: "required_int32_value", typeFullName: "int32" },
      },
    }),
    requiredStringValue: t.expose("requiredStringValue", {
      type: "String",
      nullable: false,
      extensions: {
        protobufField: { name: "required_string_value", typeFullName: "string" },
      },
    }),
    requiredBoolValue: t.expose("requiredBoolValue", {
      type: "Boolean",
      nullable: false,
      extensions: {
        protobufField: { name: "required_bool_value", typeFullName: "bool" },
      },
    }),
  }),
  isTypeOf: (source) => {
    return isMessage(source, PrimitivesSchema);
  },
  extensions: {
    protobufMessage: {
      fullName: "example.Primitives",
      name: "Primitives",
      package: "example",
    },
  },
});
```

--------------------------------

### Custom Scalar Mapping for Date and Money (YAML)

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/type-mapping/scalars.md

This YAML configuration snippet illustrates mapping custom Protobuf types like `google.type.Date` and `google.type.Money` to corresponding GraphQL scalar types (`Date` and `Money`). This allows for specific handling of domain-specific types.

```yaml
opt:
  - scalar=google.type.Date=Date
  - scalar=google.type.Money=Money
```

--------------------------------

### Convert Date Input to Proto Message

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-protobuf-es-v1.md

Provides a TypeScript function '$toProto' for converting a GraphQL Date input shape to a protobuf Date message. It handles potential null or undefined inputs and uses nullish coalescing for default values.

```typescript
export function DateInput$toProto(
  input: DateInput$Shape | null | undefined,
): Date {
  return new Date({
    year: input?.year ?? undefined,
    month: input?.month ?? undefined,
    day: input?.day ?? undefined,
  });
}
```

--------------------------------

### Define Basic Input Type with TypeScript

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-protobuf-es-v1.md

Defines a basic input type 'DateInput' in TypeScript for GraphQL. It specifies the shape of the input and uses builder.inputRef to create a reference for the GraphQL schema, including protobuf field extensions.

```typescript
export type DateInput$Shape = {
  year: Date["year"];
  month: Date["month"];
  day: Date["day"];
};

export const DateInput$Ref: InputObjectRef<DateInput$Shape> = builder.inputRef<
  DateInput$Shape
>("DateInput").implement({
  fields: (t) => ({
    year: t.field({
      type: "Int",
      required: true,
      extensions: { protobufField: { name: "year", typeFullName: "uint32" } },
    }),
    month: t.field({
      type: "Int",
      required: true,
      extensions: { protobufField: { name: "month", typeFullName: "uint32" } },
    }),
    day: t.field({
      type: "Int",
      required: true,
      extensions: { protobufField: { name: "day", typeFullName: "uint32" } },
    }),
  }),
  extensions: {
    protobufMessage: {
      fullName: "testapis.custom_types.Date",
      name: "Date",
      package: "testapis.custom_types",
    },
  },
});
```

--------------------------------

### Set Pothos Builder Path

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/configuration.md

Specifies the path to the file exporting the Pothos builder instance. This path is resolved relative to the generated file's location.

```yaml
opt:
  - pothos_builder_path=../../builder
```

--------------------------------

### Basic Proto Definition for User and Role

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

Defines a `User` message and `Role` enum in protobuf syntax. It includes GraphQL-specific annotations for the `id` field and imports `graphql/schema.proto` for schema extensions. This definition serves as the source for generating GraphQL types.

```protobuf
// proto/example/user.proto
syntax = "proto3";

package example;

import "graphql/schema.proto";

message User {
  // Required. Output only.
  uint64 id = 1 [(graphql.field).id = true];
  // Required.
  string name = 2;
  string email = 3;
  Role role = 4;
}

enum Role {
  ROLE_UNSPECIFIED = 0;
  ROLE_ADMIN = 1;
  ROLE_USER = 2;
}
```

--------------------------------

### Define Partial Input Type with TypeScript

Source: https://github.com/proto-graphql/proto-graphql-js/blob/main/docs/protoc-gen-pothos/generated-code-reference-protobuf-es-v1.md

Demonstrates the definition of a partial input type in TypeScript when 'partial_inputs=true' is configured. All fields in the partial type are optional, allowing for partial updates.

```typescript
export type DatePartialInput$Shape = {
  year?: Date["year"] | null;
  month?: Date["month"] | null;
  day?: Date["day"] | null;
};

export const DatePartialInput$Ref: InputObjectRef<DatePartialInput$Shape> = 
  builder.inputRef<DatePartialInput$Shape>("DatePartialInput").implement({
    fields: (t) => ({
      year: t.field({
        type: "Int",
        required: false,  // All fields optional
        extensions: { protobufField: { name: "year", typeFullName: "uint32" } },
      }),
      // ...
    }),
    // ...
  });
```

--------------------------------

### Define Protocol Buffer Message Structure

Source: https://context7.com/proto-graphql/proto-graphql-js/llms.txt

Defines a User message with nested Address and an associated Role enum using proto3 syntax. This serves as the source for GraphQL schema generation.

```protobuf
syntax = "proto3";

package example;

message User {
  uint64 id = 1;
  string name = 2;

  message Address {
    string city = 1;
    string country = 2;
  }

  Address address = 3;
}

enum Role {
  ROLE_UNSPECIFIED = 0;
  ROLE_ADMIN = 1;
}
```