Generator

Generates typed GraphQL modules and diagnostics without writing to disk. The CLI uses generate to write, check or watch the output.

5 exports Since v4.0.0 Source

Errors

ConfigError

Since v4.0.0

The config cannot be used with this schema, e.g. a scalars key that isn't a custom scalar or a built-in Int, Float or ID, or an absolute documents pattern.

Signature

declare class ConfigError extends YieldableError<this> & {
  readonly _tag: "ConfigError";
} & Readonly<{
  readonly message: string;
}> {
  constructor(args: {
    readonly message: string;
  });
}

Generation

generate

Since v4.0.0

Generates the .graphql.ts module for every document file and the shared module, in memory.

Details

Relative paths in the config, and the documents globs, resolve against options.cwd, which is normally the config file's directory.
foo.graphql generates foo.graphql.ts next to it, and foo.gql generates foo.gql.ts.
The shared module goes to config.shared, or next to the schema as <schema name>.graphql.ts, and holds only the scalars, enums, input objects and possible __typename unions the operations reach. A shared path equal to the schema, a document or a document's output is an error diagnostic.
Entries under a glob root that can't be read, such as dangling symlinks, are skipped.
Custom scalars named DateTime and URI default to Schema.DateTimeUtcFromString and Schema.String. Configured scalars override these defaults. Other unmapped custom scalars decode as Schema.Json, and one warning lists every one the operations reach.
A selection on an interface or union decodes as a Schema.Union discriminated by __typename, which is added to the document. Types the selection doesn't name, including ones the server adds later, fall into a last member built with GraphQL.otherTypename.
@skip / @include with a variable condition make the fields they cover optional keys; literal conditions are folded.
Recursive input objects produce error diagnostics.

Signature

declare const generate: (config: Config, options: {
  readonly cwd: string;
}) => Effect.Effect<GenerateResult, Generate.ConfigError | PlatformError, FileSystem.FileSystem | Path.Path>

Models

Diagnostic

interface

Since v4.0.0

A problem found while generating.

path is relative to the cwd passed to generate, with / separators.
line and column are 1-based. They, and codeFrame, are undefined for diagnostics about the run as a whole, such as the unmapped-scalars warning, which is reported against the schema file.
Any "error" means the output must not be written. Warnings don't stop generation.

Signature

interface Diagnostic {
  readonly codeFrame: string | undefined;
  readonly column: number | undefined;
  readonly line: number | undefined;
  readonly message: string;
  readonly path: string;
  readonly severity: "error" | "warning";
}

GeneratedFile

interface

Since v4.0.0

A generated file: an absolute path and the full contents to write there.

Signature

interface GeneratedFile {
  readonly contents: string;
  readonly path: string;
}

GenerateResult

interface

Since v4.0.0

The result of generate. files and deletes are empty when diagnostics holds an error.

deletes lists stale *.graphql.ts and *.gql.ts files by absolute path. A file qualifies only under a documents glob root, with a generator header naming a missing sibling source, and when absent from files. Shared modules and files without a matching document header are excluded.

Signature

interface GenerateResult {
  readonly deletes: readonly Array<string>;
  readonly diagnostics: readonly Array<Diagnostic>;
  readonly files: readonly Array<GeneratedFile>;
}