@model-ts/graphql 0.0.0-stage → 7.1.0

package/src/Definitions.ts

@@ -0,0 +1,465 @@
+import type { Schema } from "effect"
+import type { GraphQLScalarType } from "graphql"
+import { GraphQLEnumType } from "graphql"
+import { type AnyDefinition } from "./Assembly.ts"
+import type { RuntimeRef, ConnectionRef, Field } from "./FieldTypes.ts"
+import {
+  type FieldMap,
+  type ResolverFields,
+  type EnumFields,
+  type SubscriptionFields,
+  type CheckedFields,
+  type SourceIssue,
+  type SourceSlot,
+} from "./FieldTypes.ts"
+import { type Description, type Contextual } from "./FieldTypes.ts"
+import {
+  type Tag,
+  type NamesOfKind,
+  type RegistrationCheck,
+  type CheckedMembers,
+} from "./Registry.ts"
+import { type DefinitionKind } from "./Registry.ts"
+import type { AnyResolve, AnyConfig } from "./Resolver.ts"
+import { input } from "./SchemaTypes.ts"
+import { invalid, metadata } from "./SchemaTypes.ts"
+
+export interface ObjectDefinition<
+  N extends string,
+  A,
+  F,
+  O extends ObjectOptions = {},
+  C = {},
+> extends Contextual<C> {
+  readonly "~kind": "object"
+  readonly "~name": N
+  readonly "~model": Schema.Schema<A>
+  readonly "~description"?: string
+  readonly "~implements"?: O["implements"]
+  readonly fields: F
+}
+
+export interface NamedDefinition<
+  K extends DefinitionKind,
+  N extends string,
+  A,
+> {
+  readonly "~kind": K
+  readonly "~name": N
+  readonly "~model": Schema.Schema<A>
+}
+
+export interface ScalarDefinition<
+  K extends "scalar" | "enum",
+  N extends string,
+  S extends Schema.Top,
+> extends NamedDefinition<K, N, S["Type"]> {
+  readonly "~scalar"?: GraphQLScalarType
+  readonly schema: S["Rebuild"]
+}
+
+export interface InterfaceDefinition<N extends string, A, F, C = {}>
+  extends NamedDefinition<"interface", N, A>, Contextual<C> {
+  readonly "~description"?: string
+  readonly "~resolveType"?: (value: A) => string | null
+  readonly fields: F
+}
+
+export interface ObjectOptions extends Description {
+  readonly implements?: readonly string[]
+}
+
+export interface AbstractOptions<
+  A,
+  Members extends readonly string[],
+> extends Description {
+  readonly members: Members
+  readonly resolveType?: (value: A) => NoInfer<Members[number]> | null
+}
+
+export interface UnionDefinition<
+  N extends string,
+  A,
+  Members extends readonly string[],
+> extends NamedDefinition<"union", N, A> {
+  readonly options: AbstractOptions<A, Members>
+}
+
+export interface RootDefinition<
+  K extends "query" | "mutation" | "subscription",
+  F,
+  C = {},
+> extends Contextual<C> {
+  readonly "~kind": K
+  readonly fields: F
+}
+
+/** Only the literal tag is read for implicit naming; output fields never inspect model ASTs. */
+export function tagName(model: {
+  readonly fields?: { readonly _tag?: Schema.Constraint }
+}): string {
+  const tag = model.fields?._tag?.ast
+  return tag?._tag === "Literal" && typeof tag.literal === "string"
+    ? tag.literal
+    : invalid("Object model needs a literal _tag; use an explicit name")
+}
+
+export interface InterfaceOptions<Types, A> extends Description {
+  readonly resolveType?: (value: A) => NamesOfKind<Types, "object"> | null
+}
+
+export type EnumValue<A> = A | ({ readonly value: A } & Description)
+export interface EnumOptions<A> extends Description {
+  readonly values: Readonly<Record<string, EnumValue<A>>>
+}
+
+type MappedValues<V> = V[keyof V] extends infer A
+  ? A extends { readonly value: infer Value }
+    ? Value
+    : A
+  : never
+
+type CheckedEnumValues<A, V> = {
+  readonly [K in keyof V]: [MappedValues<Pick<V, K>>] extends [A]
+    ? unknown
+    : "Use a literal from the registered enum model"
+}
+
+export type CompleteEnum<A, V> = [Exclude<A, MappedValues<V>>] extends [never]
+  ? unknown
+  : {
+      readonly error: `Missing enum values: ${Exclude<A, MappedValues<V>> & string}; map every model literal in values`
+    }
+
+export interface EnumDefinition<
+  N extends string,
+  S extends Schema.Top,
+> extends ScalarDefinition<"enum", N, S> {
+  readonly "~enum"?: EnumOptions<S["Type"]>
+}
+
+/** Explicit member names are checked against the corresponding model, in order. */
+type NamedMembers<
+  Types,
+  M extends readonly Schema.Top[],
+  Names extends readonly string[],
+> = Names["length"] extends M["length"]
+  ? {
+      readonly [I in keyof Names]: I extends keyof M
+        ? Names[I] & RegistrationCheck<Types, Names[I], M[I]["Type"], "object">
+        : never
+    }
+  : {
+      readonly error: "Provide one registered object name per union model, in the same order"
+    }
+
+type Implemented<O> = O extends {
+  readonly implements: readonly (infer I extends string)[]
+}
+  ? I
+  : never
+
+/** Interface fields are known when the barrel is assembled, not at model registration. */
+export type CheckedInterfaces<Types, M> = {
+  readonly [K in keyof M]: M[K] extends ObjectDefinition<
+    infer N,
+    infer A,
+    infer F,
+    infer O,
+    infer _C
+  >
+    ? {
+        readonly [I in Implemented<O>]: Extract<
+          M[keyof M],
+          { readonly "~kind": "interface"; readonly "~name": I }
+        > extends { readonly fields: infer IF }
+          ? {
+              readonly [P in Exclude<keyof IF, keyof F>]: [
+                SourceIssue<Types, A, P, IF[P]>,
+              ] extends [never]
+                ? IF[P] extends SourceSlot<A>
+                  ? never
+                  : P
+                : P
+            }[Exclude<keyof IF, keyof F>] extends infer Bad
+            ? [Bad] extends [never]
+              ? never
+              : `${N}.${Bad & string}: cannot inherit ${I} field; supply a compatible source property or override with a resolver`
+            : never
+          : never
+      }[Implemented<O>] extends infer Issue
+      ? [Issue] extends [never]
+        ? unknown
+        : { readonly error: Issue }
+      : never
+    : unknown
+}
+
+export function mappedEnumeration(
+  name: string,
+  schema: Schema.Schema<string>,
+  options: EnumOptions<string>,
+): GraphQLEnumType {
+  const ast = schema.ast
+  const literals = (ast._tag === "Union" ? ast.types : [ast]).map((value) =>
+    value._tag === "Literal" && typeof value.literal === "string"
+      ? value.literal
+      : invalid(`${name}: enums require string Schema.Literals`),
+  )
+  const values = Object.entries(options.values).map(([key, entry]) => {
+    const config = typeof entry === "string" ? { value: entry } : entry
+    if (!literals.includes(config.value))
+      invalid(`${name}.${key}: value must be a model literal`)
+    return [key, config] as const
+  })
+  if (
+    literals.some(
+      (literal) => !values.some(([, config]) => config.value === literal),
+    )
+  )
+    invalid(`${name}: map every model literal in values`)
+  // Aliases are ambiguous on serialization: require one external name per internal value.
+  if (new Set(values.map(([, config]) => config.value)).size !== values.length)
+    invalid(
+      `${name}: enum values must be unique; use one name per model literal`,
+    )
+  return new GraphQLEnumType({
+    name,
+    ...metadata(ast),
+    ...options,
+    values: Object.fromEntries(values),
+  })
+}
+
+export interface DefinitionBuilder<Types, G, C> {
+  object<
+    M extends Schema.Schema<{ readonly _tag: string }> & {
+      readonly fields: { readonly _tag: Schema.Constraint }
+    },
+    const F extends FieldMap<M["Type"], C>,
+  >(
+    model: M & RegistrationCheck<Types, Tag<M>, NoInfer<M["Type"]>, "object">,
+    fields: F & CheckedFields<Types, Tag<M>, M["Type"], NoInfer<F>>,
+  ): ObjectDefinition<Tag<M>, M["Type"], F, {}, C>
+  object<
+    M extends Schema.Schema<{ readonly _tag: string }> & {
+      readonly fields: { readonly _tag: Schema.Constraint }
+    },
+    const F extends FieldMap<M["Type"], C>,
+    const O extends ObjectOptions & {
+      readonly implements?: readonly NamesOfKind<Types, "interface">[]
+    },
+  >(
+    model: M & RegistrationCheck<Types, Tag<M>, NoInfer<M["Type"]>, "object">,
+    options: O,
+    fields: F & CheckedFields<Types, Tag<M>, M["Type"], NoInfer<F>>,
+  ): ObjectDefinition<Tag<M>, M["Type"], F, O, C>
+  object<
+    const N extends string,
+    A,
+    const F extends FieldMap<A, C>,
+    const O extends ObjectOptions & {
+      readonly implements?: readonly NamesOfKind<Types, "interface">[]
+    } = {},
+  >(
+    name: N & RegistrationCheck<Types, N, NoInfer<A>, "object">,
+    model: Schema.Schema<A>,
+    options: O,
+    fields: F & CheckedFields<Types, N, A, NoInfer<F>>,
+  ): ObjectDefinition<N, A, F, O, C>
+  interface<const N extends string, A, const F extends FieldMap<A, C>>(
+    name: N & RegistrationCheck<Types, N, NoInfer<A>, "interface">,
+    model: Schema.Schema<A>,
+    fields: F & CheckedFields<Types, N, A, NoInfer<F>>,
+  ): InterfaceDefinition<N, A, F, C>
+  interface<const N extends string, A, const F extends FieldMap<A, C>>(
+    name: N & RegistrationCheck<Types, N, NoInfer<A>, "interface">,
+    model: Schema.Schema<A>,
+    options: InterfaceOptions<Types, NoInfer<A>>,
+    fields: F & CheckedFields<Types, N, A, NoInfer<F>>,
+  ): InterfaceDefinition<N, A, F, C>
+  union<const N extends string, S extends Schema.Union<readonly Schema.Top[]>>(
+    name: N & RegistrationCheck<Types, N, NoInfer<S["Type"]>, "union">,
+    model: S & CheckedMembers<Types, NoInfer<S["members"]>>,
+    options?: Description & {
+      readonly resolveType?: (
+        value: S["Type"],
+      ) => NoInfer<Tag<S["members"][number]>> | null
+    },
+  ): UnionDefinition<N, S["Type"], readonly Tag<S["members"][number]>[]>
+  union<
+    const N extends string,
+    S extends Schema.Union<readonly Schema.Top[]>,
+    const Members extends readonly string[],
+  >(
+    name: N & RegistrationCheck<Types, N, NoInfer<S["Type"]>, "union">,
+    model: S,
+    options: AbstractOptions<NoInfer<S["Type"]>, Members> & {
+      readonly members: Members &
+        NamedMembers<Types, NoInfer<S["members"]>, Members>
+    },
+  ): UnionDefinition<N, S["Type"], Members>
+  scalar<
+    const N extends string,
+    S extends Schema.Top & Schema.Codec<unknown, unknown>,
+  >(
+    name: N & RegistrationCheck<Types, N, NoInfer<S["Type"]>, "scalar">,
+    codec: S,
+    scalarType?: GraphQLScalarType,
+  ): ScalarDefinition<"scalar", N, S>
+  enum<const N extends string, S extends Schema.Literals<readonly string[]>>(
+    name: N & RegistrationCheck<Types, N, NoInfer<S["Type"]>, "enum">,
+    schema: S,
+  ): EnumDefinition<N, S>
+  enum<
+    const N extends string,
+    S extends Schema.Literals<readonly string[]>,
+    const V extends Readonly<Record<string, EnumValue<string>>>,
+  >(
+    name: N & RegistrationCheck<Types, N, NoInfer<S["Type"]>, "enum">,
+    schema: S,
+    options: Description & {
+      readonly values: V &
+        CompleteEnum<NoInfer<S["Type"]>, V> &
+        CheckedEnumValues<NoInfer<S["Type"]>, V>
+    },
+  ): EnumDefinition<N, S>
+  readonly queryField: EnumFields<Types, C, "query"> &
+    ResolverFields<Types, G, C, "query">
+  readonly mutationField: EnumFields<Types, C, "mutation"> &
+    ResolverFields<Types, G, C, "mutation">
+  readonly subscriptionField: SubscriptionFields<Types, G, C, "subscription">
+}
+
+export function makeDefinitions<Types, G, C>(
+  rootField: (
+    ref: RuntimeRef | ConnectionRef<string>,
+    input: AnyResolve | AnyConfig,
+  ) => Field<unknown>,
+): DefinitionBuilder<Types, G, C> {
+  const object = (...args: readonly unknown[]) => {
+    const explicit = typeof args[0] === "string"
+    // Public overloads validate each positional argument before this boundary.
+    const model = (explicit ? args[1] : args[0]) as Schema.Top & {
+      readonly fields?: { readonly _tag?: Schema.Constraint }
+    }
+    const name = explicit ? args[0] : tagName(model)
+    const rest = args.slice(explicit ? 2 : 1)
+    const options = (rest.length === 1 ? {} : rest[0]) as ObjectOptions
+    return {
+      "~kind": "object",
+      "~name": name,
+      "~model": model,
+      "~implements": options.implements ?? [],
+      ...(options.description === undefined
+        ? {}
+        : { "~description": options.description }),
+      fields: rest.at(-1),
+    }
+  }
+  // The overloads enforce registration and field contracts before this erased
+  // construction boundary; the runtime stores their validated metadata unchanged.
+  return {
+    object,
+    interface: (
+      name: string,
+      model: Schema.Top,
+      ...rest:
+        | [AnyDefinition["fields"]]
+        | [
+            Description & {
+              readonly resolveType?: (value: unknown) => string | null
+            },
+            AnyDefinition["fields"],
+          ]
+    ) => {
+      const [options, fieldMap] =
+        rest.length === 1 ? [undefined, rest[0]] : rest
+      return {
+        "~kind": "interface",
+        "~name": name,
+        "~model": model,
+        "~description": options?.description,
+        "~resolveType": options?.resolveType,
+        fields: fieldMap,
+      }
+    },
+    union: (
+      name: string,
+      model: Schema.Union<readonly Schema.Top[]>,
+      options?: Description & {
+        readonly members?: readonly string[]
+        readonly resolveType?: (value: unknown) => string | null
+      },
+    ) => ({
+      "~kind": "union",
+      "~name": name,
+      "~model": model,
+      options: {
+        ...options,
+        members:
+          options?.members ??
+          model.members.map((member) =>
+            // The implicit-members overload requires tagged models; explicit members bypass this branch.
+            tagName(
+              member as Schema.Top & {
+                readonly fields?: { readonly _tag?: Schema.Constraint }
+              },
+            ),
+          ),
+      },
+    }),
+    scalar: (
+      name: string,
+      model: Schema.Top,
+      scalarType?: GraphQLScalarType,
+    ) => {
+      if (scalarType && scalarType.name !== name)
+        invalid(
+          `Scalar name ${scalarType.name} does not match ${name}; register the scalar under its existing name`,
+        )
+      return {
+        "~kind": "scalar",
+        "~name": name,
+        "~model": model,
+        schema: input(name, model),
+        "~scalar": scalarType,
+      }
+    },
+    enum: (
+      name: string,
+      model: Schema.Literals<readonly string[]>,
+      options?: EnumOptions<string>,
+    ) => ({
+      "~enum": options,
+      "~kind": "enum",
+      "~name": name,
+      "~model": model,
+      schema: input(name, model),
+    }),
+    queryField: (
+      name: string,
+      ref: RuntimeRef | ConnectionRef<string>,
+      input: AnyResolve | AnyConfig,
+    ) => ({
+      "~kind": "query",
+      fields: { [name]: rootField(ref, input) },
+    }),
+    mutationField: (
+      name: string,
+      ref: RuntimeRef | ConnectionRef<string>,
+      input: AnyResolve | AnyConfig,
+    ) => ({
+      "~kind": "mutation",
+      fields: { [name]: rootField(ref, input) },
+    }),
+    subscriptionField: (
+      name: string,
+      ref: RuntimeRef | ConnectionRef<string>,
+      input: AnyResolve | AnyConfig,
+    ) => ({
+      "~kind": "subscription",
+      fields: { [name]: rootField(ref, input) },
+    }),
+  } as unknown as DefinitionBuilder<Types, G, C>
+}

package/src/Errors.ts

@@ -0,0 +1,188 @@
+import { Cause, Context, Effect, Option, Schema } from "effect"
+import { GraphQLError } from "graphql"
+import {
+  type ErrorSchema,
+  type ErrorsOf,
+  errorMember,
+  errorName,
+} from "./Results.ts"
+
+export interface ErrorPolicyOptions<
+  I extends readonly ErrorSchema[],
+  P extends readonly ErrorSchema[],
+> {
+  /** Infrastructure failures are always masked. */
+  readonly internal?: I
+  /** Only declared fields of these errors may reach clients. */
+  readonly public?: P
+  /** Preserve an existing API's codes; unspecified tags use their own name. */
+  readonly publicCodes?: [P[number]] extends [never]
+    ? never
+    : Partial<Record<ErrorsOf<NoInfer<P>>["_tag"], string>>
+}
+
+export interface ErrorPolicy {
+  readonly internal: readonly ErrorSchema[]
+  readonly public: readonly ErrorSchema[]
+  readonly publicCodes?: Readonly<Record<string, string>>
+}
+
+export const defaultErrorPolicy: ErrorPolicy = { internal: [], public: [] }
+
+export interface ErrorReport {
+  /** Unmodified Effect cause, including defects and tracing annotations. */
+  readonly cause: Cause.Cause<unknown>
+  readonly coordinate: string
+  readonly phase: "resolve" | "authorize" | "subscribe" | "execute"
+}
+
+/** Optional per-runtime telemetry. Capture dependencies when constructing its layer. */
+export class ErrorReporter extends Context.Service<
+  ErrorReporter,
+  {
+    readonly report: (event: ErrorReport) => Effect.Effect<void>
+  }
+>()("@model-ts/graphql/ErrorReporter") {}
+
+// A GraphQLError from user code is not permission to disclose its message.
+// Only errors created by our boundaries, or declared in a policy, are trusted.
+const trusted = new WeakSet<GraphQLError>()
+export const isBoundaryError = (error: unknown): boolean =>
+  error instanceof GraphQLError && trusted.has(error)
+
+export const fieldError = (
+  message: string,
+  extensions: Readonly<Record<string, unknown>>,
+  cause?: Cause.Cause<unknown>,
+): GraphQLError => {
+  const error = new GraphQLError(message, {
+    ...(cause ? { originalError: new Error(message, { cause }) } : {}),
+    extensions,
+  })
+  trusted.add(error)
+  return error
+}
+
+export const forbidden = (field: string): GraphQLError =>
+  fieldError(`You don't have permission to access field "${field}"`, {
+    code: "FORBIDDEN",
+  })
+
+// Wrappers are not Errors (graphql-js treats Error values as failures). Keep the
+// class instance private while the enumerable projection exposes only declared fields.
+const resultInstances = new WeakMap<object, object>()
+export const resultSource = (value: unknown): unknown =>
+  typeof value === "object" && value !== null
+    ? (resultInstances.get(value) ?? value)
+    : value
+
+/** Maps declared typed failures; undefined means the failure must be masked. */
+function visibleFailure(
+  error: unknown,
+  members: readonly ErrorSchema[],
+  policy: ErrorPolicy,
+): unknown {
+  if (isBoundaryError(error)) return error
+  if (typeof error !== "object" || error === null) return undefined
+  const matches = (schema: ErrorSchema) => Schema.is(schema)(error)
+  if (policy.internal.some(matches)) return undefined
+  const member = members.find(matches)
+  if (member) {
+    const wrapper = {
+      ...declaredFields(member, error),
+      [errorMember]: errorName(member),
+    }
+    resultInstances.set(wrapper, error)
+    return wrapper
+  }
+  const visible = policy.public.find(matches)
+  if (visible) {
+    const { _tag, message, ...extensions } = declaredFields(visible, error)
+    const tag = errorName(visible)
+    return fieldError(String(message ?? tag), {
+      ...extensions,
+      code: policy.publicCodes?.[tag] ?? tag,
+    })
+  }
+  return undefined
+}
+
+export const recoverCause = (
+  cause: Cause.Cause<unknown>,
+  members: readonly ErrorSchema[],
+  policy: ErrorPolicy,
+  location: Omit<ErrorReport, "cause">,
+): Effect.Effect<unknown> =>
+  Effect.gen(function* () {
+    // Do not turn cancellation into an error response or a telemetry incident.
+    if (Cause.hasInterruptsOnly(cause)) return yield* Effect.interrupt
+    const reason = cause.reasons.length === 1 ? cause.reasons[0] : undefined
+    const original =
+      reason?._tag === "Fail"
+        ? reason.error
+        : reason?._tag === "Die"
+          ? reason.defect
+          : undefined
+    const visible = visibleFailure(original, members, policy)
+    if (visible !== undefined) return visible
+    const reporter = yield* Effect.serviceOption(ErrorReporter)
+    if (Option.isSome(reporter)) {
+      // Telemetry must never replace the original failure or disclose its own defect.
+      yield* Effect.suspend(() =>
+        reporter.value.report({ cause, ...location }),
+      ).pipe(Effect.catchCause(() => Effect.void))
+    }
+    return fieldError(
+      "Internal server error",
+      { code: "INTERNAL_SERVER_ERROR" },
+      cause,
+    )
+  })
+
+/** Handles both synchronous throws and Effect failures, before the Promise bridge. */
+export const protect = (
+  evaluate: () => unknown,
+  members: readonly ErrorSchema[],
+  policy: ErrorPolicy,
+  location: Omit<ErrorReport, "cause">,
+): Effect.Effect<unknown, never, unknown> =>
+  Effect.suspend(() => {
+    const output = evaluate()
+    if (output instanceof Error) return Effect.fail(output)
+    return Effect.isEffect(output) ? output : Effect.succeed(output)
+  }).pipe(
+    Effect.flatMap((value) => {
+      if (value instanceof Error) return Effect.fail(value)
+      // JavaScript callers can bypass the type contract. A truthy Promise must
+      // never authorize a request or run outside the Effect cancellation boundary.
+      if (
+        value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        "then" in value &&
+        typeof value.then === "function"
+      ) {
+        return Effect.die(
+          new Error(
+            "Return a value or Effect; wrap Promise APIs with Effect.tryPromise",
+          ),
+        )
+      }
+      return Effect.succeed(value)
+    }),
+    Effect.catchCause((cause) =>
+      recoverCause(cause, members, policy, location),
+    ),
+    Effect.withSpan(`GraphQL.${location.phase}`, {
+      attributes: { "graphql.field": location.coordinate },
+    }),
+  )
+
+export function declaredFields(
+  schema: ErrorSchema,
+  error: object,
+): Record<string, unknown> {
+  // Error.message can be non-enumerable; never copy stack/cause/incidental fields.
+  return Object.fromEntries(
+    Object.keys(schema.fields).map((key) => [key, Reflect.get(error, key)]),
+  )
+}