Add @enonic-types/lib-graphql types package #200

[rymsha]

Adds a published TypeScript types package @enonic-types/lib-graphql so consumers no longer hand-maintain declarations for /lib/graphql, /lib/graphql-connection and /lib/graphql-rx. Mirrors the lib-mustache #66 scaffolding; the type authoring is the real work here.

Type model

• GraphQLType and per-kind subtypes (GraphQLObjectType, GraphQLInputObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLScalarType, GraphQLTypeReference) are opaque, nominally-branded handles. Consumers pass them around but do not introspect them. GraphQLObjectType exposes getName() because createConnectionType uses it to derive edge / connection names.
• Field configs are typed with GraphQLFieldConfig<Source, Context>. The resolver's env.args is any in the default signature so callers can narrow to a concrete Args interface by annotating the resolver's env parameter, without an explicit cast:

  resolve: (env: DataFetchingEnvironment<Person, GetPersonArgs, AppContext>): Person | null => {
      return env.args.name.length > 0 ? ... : null;
  }

  The runtime never validates arg shape (the schema does), so any here matches actual behavior — it's a bivariance escape hatch, not blanket looseness.
• DataFetchingEnvironment<Source, Args, Context> — three generics, all defaulted to unknown / Record<string, unknown>, reflecting what the Java bridge actually guarantees.
• Extended / custom scalars (Date, DateTime, Time, Json, LocalDateTime, LocalTime) are typed as GraphQLScalarType — same shape as the base graphql-java scalars.

Every signature was cross-checked against GraphQlBean.java, DataFetchingEnvironmentMapper.java, RxBean.java (param order, return types), and the graphql.js / graphql-connection.js / graphql-rx.js wrappers.

Contents

• types/index.d.ts — three declare module blocks: /lib/graphql, /lib/graphql-connection, /lib/graphql-rx.
• types/package.json — @enonic-types/lib-graphql manifest, @enonic-types/core peer dependency, publishConfig.access: public, version 0.0.0 (substituted at build).
• types/tsconfig.json + types/test/typecheck.ts — build-only smoke test that exercises a realistic schema (object type with a typed resolver reading source, args and context, an enum + input + interface + union, a Relay-style connection built through graphql-connection, and a graphql-rx publish processor / subscriber). Runs under tsc --noEmit with strict mode.
• build.gradle — assembleTypes Copy task -> build/types/ (version substituted from project.version, tsconfig + test excluded from the published artifact); jar.dependsOn assembleTypes.
• .github/workflows/enonic-gradle.yml — npmPublish: true on build-and-publish + top-level id-token: write / contents: write permissions for OIDC trusted publishing.

Verified locally

• ./gradlew build green.
• build/types/ contains index.d.ts + a package.json with version substituted to the project version (3.1.0-SNAPSHOT).
• tsc --noEmit -p types/tsconfig.json passes against the realistic-schema smoke test.

Follow-up

• app-guillotine is the primary consumer — once this publishes, guillotine (and any other apps currently building against untyped /lib/graphql*) can depend on @enonic-types/lib-graphql instead of local declarations.
• First publish may need npm trusted-publisher setup on the @enonic-types/lib-graphql name (release-tools Bump graphql-java-extended-scalars from 1.0 to 16.0.0 #71 merged).

Closes #200

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.26%. Comparing base (0d2f885) to head (402a58b).

Additional details and impacted files

@@            Coverage Diff            @@
##             master     #201   +/-   ##
=========================================
  Coverage     87.26%   87.26%           
  Complexity       93       93           
=========================================
  Files            13       13           
  Lines           369      369           
  Branches         50       50           
=========================================
  Hits            322      322           
  Misses           23       23           
  Partials         24       24           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Adds a publishable TypeScript declaration package (@enonic-types/lib-graphql) to provide first-party typings for Enonic XP’s /lib/graphql, /lib/graphql-connection, and /lib/graphql-rx, and wires CI/build to assemble and publish it.

Changes:

• Adds ambient module declarations (types/index.d.ts) covering schema building, connection helpers, and reactive helpers.
• Adds a strict tsc --noEmit smoke test (types/test/typecheck.ts) plus a local types/tsconfig.json for typechecking.
• Adds Gradle/CI automation to assemble the types/ package into build/types/ and enable npm trusted publishing.

Reviewed changes

Copilot reviewed 4 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
types/index.d.ts	Declares the public TS API surface for /lib/graphql* modules (schema builder, connection helper, rx helper).
types/package.json	Defines the npm package metadata for @enonic-types/lib-graphql.
types/tsconfig.json	Typecheck configuration for the declaration package + compile-only test.
types/test/typecheck.ts	Compile-only smoke test exercising the declared typings with a realistic schema.
build.gradle	Adds assembleTypes task to stage the npm package under build/types/ with version substitution.
.github/workflows/enonic-gradle.yml	Enables OIDC permissions and npmPublish: true in the build-and-publish workflow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.