graphql-lookahead

library1.4.0jsnpmunverified

graphql-lookahead is a TypeScript library (v1.4.0) that enables GraphQL resolvers to check whether specific fields are requested in the incoming operation (query/mutation). This allows optimizing database queries by avoiding fetching nested relationships when not needed. It works with any GraphQL server and ORM. The library is actively maintained with regular releases and provides accurate field/type/hierarchy checks through a callback-based API (`until`, `next`, `nextFragment`). Key differentiators: lightweight, no magic AST parsing, typed, and supports fragment spreads. Peer dependency: graphql 16.x. ESM-only, ships TypeScript types.

database

npm install graphql-lookahead

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-LOOKAHEAD

graphql-lookahead

databasejavascriptv1.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

lookahead

✓ import { lookahead } from 'graphql-lookahead'

✗ const lookahead = require('graphql-lookahead')

The library is ESM-only. CommonJS require will fail.

lookahead

✓ import { lookahead } from 'graphql-lookahead'

✗ import lookahead from 'graphql-lookahead'

Default import is not available; the function is a named export.

lookahead types

✓ import type { LookaheadOptions, UntilHandlerDetails } from 'graphql-lookahead'

Type imports are available from the index.

Shows basic usage of lookahead in a resolver to conditionally fetch a field.

import { lookahead } from 'graphql-lookahead'; import { GraphQLResolveInfo } from 'graphql'; // Inside a resolver: const resolver = async ( _parent: unknown, _args: unknown, _context: unknown, info: GraphQLResolveInfo ) => { if (lookahead({ info, until: ({ field }) => field === 'email' })) { // Fetch email from database } return {}; }; export { resolver };

Debug

Known issues

breakingRequires GraphQL v16.x (peer dependency). Will not work with v15 or older.

fix

Upgrade GraphQL to v16.x.

affects: >=1.0.0

breakingESM-only package. CommonJS require will throw a runtime error.

fix

Use import syntax or enable ESM in your project.

affects: >=1.0.0

gotchaThe `until` callback is called for every nested field, which may impact performance on deeply nested queries.

fix

Use the `depth` option to limit recursion or early return in the callback.

affects: >=1.0.0

gotchaThe `field` property in the details object refers to the alias name if an alias is used in the query.

fix

Check `selection.name.value` for the original field name or use the `fieldDef` property.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'graphql-lookahead'

Package not installed or project not set to ESM.

fix

Run 'npm install graphql graphql-lookahead' and ensure package.json contains '"type": "module"'.

Error: lookahead is not a function

Default import used (import lookahead from ...) instead of named import.

fix

Change to 'import { lookahead } from 'graphql-lookahead'.

TypeError: graphql-lookahead is not a function

CommonJS require used on an ESM-only package.

fix

Use dynamic import: 'const { lookahead } = await import('graphql-lookahead');'

GraphQLError: Unknown type '...'

The package expects GraphQL v16.x but older version is installed.

fix

Run 'npm install graphql@16' to upgrade.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

graphqlrequiredPeer dependency: GraphQL runtime version 16.x

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/accesimpot/graphql-lookahead ↗

packagegraphql-lookahead ↗

homepagehttps://github.com/accesimpot/graphql-lookahead#readme ↗