github.com/hasura/ndc-sdk-go/cmd/hasura-ndc-go@v0.0.0-20240508172728-e960be013ca2/README.md

# Native Data Connector code generator

The NDC code generator provides a set of tools to develop data connectors quickly. It's suitable for developers who create connectors for business logic functions (or action in GraphQL Engine v2).

The generator is inspired by [ndc-typescript-deno](https://github.com/hasura/ndc-typescript-deno) and [ndc-nodejs-lambda](https://github.com/hasura/ndc-nodejs-lambda) that automatically infer TypeScript functions as NDC functions/procedures for use at runtime. It's possible to do this with Go via reflection. However, code generation is better for performance, type-safe, and no magic.

## Installation

### Download

Get a release [here](https://github.com/hasura/ndc-sdk-go/releases).

### Build from source

To install with Go 1.21+:

```bash
go install github.com/hasura/ndc-sdk-go/cmd/hasura-ndc-go@latest
```

## How to Use

```bash
❯ hasura-ndc-go -h
Usage: hasura-ndc-go <command>

Flags:
  -h, --help    Show context-sensitive help.

Commands:
  new --name=STRING --module=STRING
    Initialize an NDC connector boilerplate. For example:

        hasura-ndc-go new -n example -m github.com/foo/example

  generate
    Generate schema and implementation for the connector from functions.

  test snapshots
    Generate test snapshots.
```

### Initialize connector project

The `new` command generates a boilerplate project for connector development from [template](templates/new) with the following folder structure:

- `functions`: the folder contains query and mutation functions. The `generate` command will parse `.go` files in this folder.
- `types`: the folder contains reusable types such as `RawConfiguration`, `Configuration` and `State`.
- `connector.go`: parts of Connector methods, except `GetSchema`, `Query` and `Mutation` methods that will be generated by the `generate` command.
- `main.go`: the main function that runs the connector CLI.
- `go.mod`: the module file with required dependencies.
- `README.md`: the index README file.
- `Dockerfile`: the build template for Docker image.

The command requires names of the connector and module. By default, the tool creates a new folder with the connector name. If you want to customize the path or generate files in the current folder. use `--output` (`-o`) argument.

```bash
hasura-ndc-go new -n example -m github.com/foo/example -o .
```

### Generate queries and mutations

The `generate` command parses code in the `functions` folder, finds functions and types that are allowed to be exposed and generates the following files:

- `schema.generated.json`: the generated connector schema in JSON format.
- `connector.generated.go`: implement `GetSchema`, `Query` and `Mutation` methods with exposed functions.

```bash
hasura-ndc-go generate
```

## How it works

### Functions

Functions that are allowed to be exposed as queries or mutations need to have a `Function` or `Procedure` prefix in the name. For example:

```go
// FunctionHello sends a hello message
func FunctionHello(ctx context.Context, state *types.State, arguments *HelloArguments) (*HelloResult, error)

// ProcedureCreateAuthor creates an author
func ProcedureCreateAuthor(ctx context.Context, state *types.State, arguments *CreateAuthorArguments) (*CreateAuthorResult, error)
```

Or use `@function` or `@procedure` comment tag:

> [!IMPORTANT]
> The first word of the comment must be the function name. Without it the parser can not find the exact comment of the function:

```go
// Hello sends a hello message
// @function
func Hello(ctx context.Context, state *types.State, arguments *HelloArguments) (*HelloResult, error)

// CreateAuthor creates an author
// @procedure
func CreateAuthor(ctx context.Context, state *types.State, arguments *CreateAuthorArguments) (*CreateAuthorResult, error)

// you also can set the alias after the tag:

// Foo a bar
// @function bar
func Foo(ctx context.Context, state *types.State) (*FooResult, error)
```

Function and Procedure names will be formatted to `camelCase` by default.

> The generator detects comments by the nearby code position. It isn't perfectly accurate in some use cases. Prefixing name in the function is highly recommended.

A function must have 2 (no argument) or 3 parameters. `Context` and `State` are always present as 2 first parameters. The result is a tuple with an expected output and `error`.

> [Function](https://hasura.github.io/ndc-spec/specification/schema/functions.html) is a type of Query and [Procedure](https://hasura.github.io/ndc-spec/specification/schema/procedures.html) is a type of mutation. [Collection](https://hasura.github.io/ndc-spec/specification/schema/collections.html) is usually used for database queries so it isn't used for business logic.

### Types

The tool only infers arguments and result types of exposed functions to generate object type schemas:

- Argument type must be a struct with serializable properties.
- Result type can be a scalar, slice, or struct.

#### Object Types

The tool can infer properties of the struct and generate [Object Type](https://hasura.github.io/ndc-spec/specification/schema/object-types.html) schema. The `json` tags will be read as properties name to be consistent with `JSON Marshaller` and `Unmarshaller`. For example, with the following type:

```go
type CreateAuthorResult struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

// auto-generated
// func (j CreateAuthorResult) ToMap() map[string]any {
//   return map[string]any{
//     "id": j.ID,
//     "name": j.Name,
//   }
// }
```

the schema will be:

```json
{
  "CreateAuthorResult": {
    "fields": {
      "id": {
        "type": {
          "name": "Int",
          "type": "named"
        }
      },
      "name": {
        "type": {
          "name": "String",
          "type": "named"
        }
      }
    }
  }
}
```

#### Arguments

Arguments must be defined as struct types. The generator automatically infers argument types in functions to generate schemas and Encoder and Decoder methods. Value fields are treated as required and pointer fields are optional.

```go
type HelloArguments struct {
	Greeting string `json:"greeting"` // value argument will be required
	Count    *int   `json:"count"`    // pointer arguments are optional
}
```

#### Scalar Types

**Supported types**

The basic scalar types supported are:

| Name        | Native type                 | Description                                                                           | JSON representation |
| ----------- | --------------------------- | ------------------------------------------------------------------------------------- | ------------------- |
| Boolean     | bool                        | A 8-bit signed integer with a minimum value of -2^7 and a maximum value of 2^7 - 1    | boolean             |
| String      | string                      | String                                                                                | string              |
| Int8        | int8, uin8                  | A 8-bit signed integer with a minimum value of -2^7 and a maximum value of 2^7 - 1    | int8                |
| Int16       | int16, uint16               | A 16-bit signed integer with a minimum value of -2^15 and a maximum value of 2^15 - 1 | int16               |
| Int32       | int32, uint32               | A 32-bit signed integer with a minimum value of -2^31 and a maximum value of 2^31 - 1 | int32               |
| Int64       | int64, uint64               | A 64-bit signed integer with a minimum value of -2^63 and a maximum value of 2^63 - 1 | int64               |
| Bigint      | scalar.BigInt               | A 64-bit signed integer with a minimum value of -2^63 and a maximum value of 2^63 - 1 | string              |
| Float32     | float32                     | An IEEE-754 single-precision floating-point number                                    | float32             |
| Float64     | float64                     | An IEEE-754 double-precision floating-point number                                    | float64             |
| UUID        | github.com/google/uuid.UUID | UUID string (8-4-4-4-12)                                                              | uuid                |
| Date        | scalar.Date                 | ISO 8601 date                                                                         | string              |
| TimestampTZ | time.Time                   | ISO 8601 timestamp-with-timezone                                                      | string              |
| Enum        |                             | Enumeration values                                                                    | string              |
| Bytes       | scalar.Bytes                | Base64-encoded bytes                                                                  | string              |
| JSON        | any, map[K]V                | Arbitrary JSON                                                                        | json                |
| RawJSON     | json.RawMessage             | Raw arbitrary JSON                                                                    | json                |

> [!NOTE]
> We don't recommend to use the `RawJSON` scalar for `function` arguments because the decoder will re-encode the value to `[]byte` that isn't performance-wise.

Alias scalar types will be inferred to the origin type in the schema.

```go
// the scalar type in schema is still a `String`.
type Text string
```

If you want to define a custom scalar type, the type name must have a `Scalar` prefix or `@scalar` tag in the comment. The generator doesn't care about the underlying type even if it is a struct.

> [!IMPORTANT]
> Require the type name at the head of the comment if using comment tags.

```go
type ScalarFoo struct {
  bar string
}
// output: Foo
// auto-generated
// func (j ScalarFoo) ScalarName() string {
//   return "Foo"
// }


// Tag a tag scalar
// @scalar
type Tag struct {
  tag string
}
// output: Tag

// Foo a foo scalar
// @scalar Bar
type Foo struct {}
// output: Bar
```

For custom scalar, you must implement a method to decode `any` value so its data can be set when resolving request query arguments. `UnmarshalJSON` is also used when encoding results.

```go
func (c *ScalarFoo) FromValue(value any) (err error) {
	c.Bar, err = utils.DecodeString(value)
	return
}

func (c *ScalarFoo) UnmarshalJSON(b []byte) error {
	var s string
	if err := json.Unmarshal(b, &s); err != nil {
		return err
	}

	c.bar = s

	return nil
}
```

#### Enum

You can define the enum type with `@enum` comment tag. The data type must be an alias of string.

```go
// @enum <values separated by commas>
//
// example:
//
// SomeEnum some enum
// @enum foo, bar
type SomeEnum string
```

The tool will help generate schema, constants and helper methods for it.

```json
{
  "scalar_types": {
    "SomeEnum": {
      "aggregate_functions": {},
      "comparison_operators": {},
      "representation": {
        "one_of": ["foo", "bar"],
        "type": "enum"
      }
    }
  }
}
```

![Enum scalar](../../assets/scalar-enum.gif)

#### Limitation

Comments of types from third-party packages can't be parsed. If you want to use scalars from 3rd dependencies, you must wrap them with type alias.

### Documentation

The tool parses comments of functions and types by the nearby code position to describe properties in the schema. For example:

```go
// Creates an author
func ProcedureCreateAuthor(ctx context.Context, state *types.State, arguments *CreateAuthorArguments) (*CreateAuthorResult, error)

// {
//   "name": "createAuthor",
//   "description": "Creates an author",
//   ...
// }
```

## Example

See [example/codegen](../../example/codegen).

## Test Snapshots

The tool supports test snapshots generation for query and mutation requests and responses that are compatible with [ndc-test replay](https://github.com/hasura/ndc-spec/tree/main/ndc-test#custom-tests) command. See generated snapshots at [the codegen example](../../example/codegen/testdata).

```bash
Usage: hasura-ndc-go test snapshots

Generate test snapshots.

Flags:
  -h, --help                     Show context-sensitive help.
      --log-level="info"         Log level.

      --schema=STRING            NDC schema file path. Use either endpoint or schema path
      --endpoint=STRING          The endpoint of the connector. Use either endpoint or schema path
      --dir=STRING               The directory of test snapshots.
      --depth=10                 The selection depth of nested fields in result types.
      --seed=SEED                Using a fixed seed will produce the same output on every run.
      --query=QUERY,...          Specify individual queries to be generated. Separated by commas, or 'all' for all queries
      --mutation=MUTATION,...    Specify individual mutations to be generated. Separated by commas, or 'all' for all mutations
      --strategy="none"          Decide the strategy to do when the snapshot file exists.
```

The command accepts either a connector `--endpoint` or a JSON `--schema` file.

**Endpoint**

```bash
hasura-ndc-go test snapshots --endpoint http://localhost:8080 --dir testdata
```

**NDC Schema**

```bash
hasura-ndc-go test snapshots --schema schema.generated.json --dir testdata
```