healthCheck() - Resolver

healthCheck() is a query resolver that allows you to get data from:

• Async Functions during other resolver logic / GraphQL / API calls server-side
• GraphQL - As a GraphQL query
• API route (GET)
• Clientside Hooks for calling the API with react-query from Web / Mobile

Resolver Config

Input / output types, defaults, schemas and general config for the healthCheck() resolver are defined in its DataBridge file. Importable from:

import { healthCheckBridge } from '@app/core/resolvers/healthCheck.bridge'

Input Shape

You can find the schema used to validate the input arguments for the healthCheck() resolver in the bridge config:

const HealthCheckInput = healthCheckBridge.inputSchema

const HealthCheckInput = z.object({
    echo: z
        .string()
        .default("Hello World"),
    verbose: z
        .boolean()
        .optional(),
})

If needed, you can extract the TypeScript type from the schema using z.input(), e.g.:

type HealthCheckInput = z.input<typeof HealthCheckInput>

{
    echo?: string;
    verbose?: boolean;
}

Output Shape

You can find the schema used to provide output defaults for the healthCheck() resolver in the bridge config too:

const HealthCheckOutput = healthCheckBridge.outputSchema

const HealthCheckOutput = z.object({
    echo: z
        .string()
        .optional(),
    status: z
        .literal("OK"),
    alive: z
        .boolean(),
    kicking: z
        .boolean(),
    now: z
        .string(),
    aliveTime: z
        .number(),
    aliveSince: z
        .date(),
    serverTimezone: z
        .string(),
    requestHost: z
        .string()
        .optional(),
    requestProtocol: z
        .string()
        .optional(),
    requestURL: z
        .string()
        .optional(),
    baseURL: z
        .string()
        .optional(),
    backendURL: z
        .string()
        .optional(),
    apiURL: z
        .string()
        .optional(),
    graphURL: z
        .string()
        .optional(),
    port: z
        .number()
        .int()
        .nullable(),
    debugPort: z
        .number()
        .int()
        .nullable(),
    nodeVersion: z
        .string()
        .optional(),
    v8Version: z
        .string()
        .optional(),
    systemArch: z
        .string()
        .optional(),
    systemPlatform: z
        .string()
        .optional(),
    systemRelease: z
        .string()
        .optional(),
    systemFreeMemory: z
        .number()
        .optional(),
    systemTotalMemory: z
        .number()
        .optional(),
    systemLoadAverage: z
        .array(z.number())
        .optional(),
    context: z
        .record(z.string(), z.unknown())
        .nullish(),
})

Here too, you can extract the TypeScript type from the schema using z.output(), e.g.:

type HealthCheckOutput = z.output<typeof HealthCheckOutput>

{
    echo?: string | undefined;
    status: "OK";
    alive: boolean;
    kicking: boolean;
    now: string;
    aliveTime: number;
    aliveSince: Date;
    serverTimezone: string;
    requestHost?: string | undefined;
    requestProtocol?: string | undefined;
    requestURL?: string | undefined;
    baseURL?: string | undefined;
    backendURL?: string | undefined;
    apiURL?: string | undefined;
    graphURL?: string | undefined;
    port: number | null;
    debugPort: number | null;
    nodeVersion?: string | undefined;
    v8Version?: string | undefined;
    systemArch?: string | undefined;
    systemPlatform?: string | undefined;
    systemRelease?: string | undefined;
    systemFreeMemory?: number | undefined;
    systemTotalMemory?: number | undefined;
    systemLoadAverage?: number[] | undefined;
    context?: ({
        [x: string]: unknown;
    } | null) | undefined;
}

Server Usage

healthCheck() function

import { healthCheck } from '@app/core/resolvers/healthCheck.resolver'

// ... Later, in resolver or script logic ...
const output = await healthCheck({ ...inputArgs })
//     ?^ HealthCheckOutput 

Note that using resolvers like healthCheck() as async functions is only available server-side, and might cause issues if imported into the client bundle. For client-side usage, use any of the other options below.

GraphQL Query

healthCheckFetcher()

import { healthCheckFetcher } from '@app/core/resolvers/healthCheck.query'

healthCheckFetcher() is a universal GraphQL query fetcher function.
It wil query the healthCheck resolver for you as a GraphQL query:

const response = await healthCheckFetcher({ healthCheckArgs: { ...inputArgs } })
//       ?^ { healthCheck: HealthCheckOutput } 

Just make sure the healthCheckArgs input matches the HealthCheckInput schema.

If you prefer, you can also use the following GraphQL snippet in your own GraphQL fetching logic:

GraphQL Query Snippet

query healthCheck($healthCheckArgs: HealthCheckInput!) {
    healthCheck(args: $healthCheckArgs) {
        echo
        status
        alive
        kicking
        now
        aliveTime
        aliveSince
        serverTimezone
        requestHost
        requestProtocol
        requestURL
        baseURL
        backendURL
        apiURL
        graphURL
        port
        debugPort
        nodeVersion
        v8Version
        systemArch
        systemPlatform
        systemRelease
        systemFreeMemory
        systemTotalMemory
        systemLoadAverage
        context {
            zodType
            baseType
        }
    }
}

Custom Query

Using a custom query, you can omit certain fields you don’t need and request only what’s necessary.

If you do, we suggest using graphqlQuery(), as it works seamlessly on the server, browser and mobile app:

import { graphql } from '@app/core/graphql/graphql'
import { graphqlQuery } from '@app/core/graphql/graphqlQuery'
 
const query = graphql(`
    query healthCheck($healthCheckArgs: HealthCheckInput!) {
        healthCheck(args: $healthCheckArgs) {
            // -i- ... type hints for the fields you need ... -i-
        }
    }
`)
 
const response = await graphqlQuery(query, { healthCheckArgs: { ...inputArgs } })
//       ?^ { healthCheck: HealthCheckOutput } 

Just make sure the healthCheckArgs input matches the HealthCheckInput schema.

Next.js API Route

GET requests

GET /api/health?...

Provide query parameters as needed (e.g. ?someArg=123).

Make sure the params / query input match the HealthCheckInput schema.

Client Usage

Custom react-query hook

e.g. In the healthCheck.query.ts file:

import { useQuery, UseQueryOptions, QueryKey } from '@tanstack/react-query'

 
export const useHealthCheckQuery = (
    input: HealthCheckQueryInput,
    options?: Omit<UseQueryOptions<HealthCheckQueryOutput>, 'queryFn' | 'queryKey'> & {
        queryKey?: QueryKey,
    },
) => {
    return useQuery({
        queryKey: ['healthCheckFetcher', input],
        queryFn: (context) => healthCheckFetcher(input),
        ...options,
    })
}

Be sure to check the useQuery docs for all the available options you might want to prefill or abstract.

Usage in React

import { useHealthCheckQuery } from '@app/core/resolvers/healthCheck.query'

const { data, error, isLoading } = useHealthCheckQuery({ healthCheckArgs: /* ... */ }, {
    // ... any additional options ...
})

Be sure to check the useQuery docs for all the available options.

Developer Notes

Why this resolver?

We included this resolver in the starterkit as a reference implementation for a simple API resolver.

While it can be used to verify that the application is running and responsive, its main goals for inclusion are to demonstrate:

• How to create a basic API resolver.
• What our way of working of creating resolvers gets you. (typesafety, async function, REST API, GraphQL API, docs)
• Automatic docgen for API resolvers. (this entire docs page)

Adding your own resolvers

If you want to quickly replicate this way of working for setting up APIs with all the side-effects listed above, you can use our resolver generator:

npm run add:resolver

Other

Disclaimer - Automatic Docgen