sailfork / t3code-github / .repos/ effect/ packages/ tools/ graphql-generator/ src/ Generator.ts

/**
 * Generates typed GraphQL modules and diagnostics without writing to disk.
 * The CLI uses {@link generate} to write, check or watch the output.
 *
 * @since 4.0.0
 */
import type * as Effect from "effect/Effect"
import type * as FileSystem from "effect/FileSystem"
import type * as Path from "effect/Path"
import type { PlatformError } from "effect/PlatformError"
import type { Config } from "./Config.ts"
import * as Generate from "./internal/Generate.ts"

/**
 * A generated file: an absolute path and the full contents to write there.
 *
 * @stability experimental
 * @category models
 * @since 4.0.0
 */
export interface GeneratedFile {
  readonly path: string
  readonly contents: string
}

/**
 * A problem found while generating.
 *
 * - `path` is relative to the `cwd` passed to {@link 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.
 *
 * @stability experimental
 * @category models
 * @since 4.0.0
 */
export interface Diagnostic {
  readonly severity: "error" | "warning"
  readonly path: string
  readonly line: number | undefined
  readonly column: number | undefined
  readonly message: string
  readonly codeFrame: string | undefined
}

/**
 * The result of {@link 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.
 *
 * @stability experimental
 * @category models
 * @since 4.0.0
 */
export interface GenerateResult {
  readonly files: ReadonlyArray<GeneratedFile>
  readonly deletes: ReadonlyArray<string>
  readonly diagnostics: ReadonlyArray<Diagnostic>
}

/**
 * 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.
 *
 * @stability experimental
 * @category errors
 * @since 4.0.0
 */
export { ConfigError } from "./internal/Generate.ts"

/**
 * 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.
 * - Input objects on a cycle, such as filters with `and` / `or`, are
 *   `Schema.Codec` consts annotated with written-out Type and Encoded
 *   interfaces, and reference the cycle through `Schema.suspend`.
 *
 * @stability experimental
 * @category generation
 * @since 4.0.0
 */
export const generate: (
  config: Config,
  options: { readonly cwd: string }
) => Effect.Effect<GenerateResult, Generate.ConfigError | PlatformError, FileSystem.FileSystem | Path.Path> = (
  config,
  options
) => Generate.generate(config, { cwd: options.cwd })