@graphql-tools/external-fragment-loader 0.0.0-stage → 0.0.0

package/typings/loader.d.ts

@@ -0,0 +1,25 @@
+import type { DocumentNode } from 'graphql';
+import type { Loader, Source } from '@graphql-tools/utils';
+import type { ExternalFragmentLoaderOptions } from './options.js';
+/**
+ * Custom-loader entry point for `@graphql-tools/load`.
+ *
+ * Custom loaders must return a single DocumentNode (or Source). By default,
+ * use the synchronous resolver so this entry point works for both
+ * `loadTypedefs` and `loadTypedefsSync`. Set `options.async` to use the
+ * asynchronous resolver from an asynchronous load call.
+ */
+type AsyncExternalFragmentLoaderOptions = ExternalFragmentLoaderOptions & {
+    async: true;
+};
+type SyncExternalFragmentLoaderOptions = ExternalFragmentLoaderOptions & {
+    async?: false;
+};
+export default function externalFragmentLoader(_pointer: string, options: AsyncExternalFragmentLoaderOptions): Promise<DocumentNode>;
+export default function externalFragmentLoader(_pointer: string, options: SyncExternalFragmentLoaderOptions): DocumentNode;
+export default function externalFragmentLoader(_pointer: string, options: ExternalFragmentLoaderOptions): DocumentNode | Promise<DocumentNode>;
+export declare class ExternalFragmentLoader implements Loader<ExternalFragmentLoaderOptions> {
+    load(_pointer: string, options: ExternalFragmentLoaderOptions): Promise<Source[]>;
+    loadSync(_pointer: string, options: ExternalFragmentLoaderOptions): Source[];
+}
+export {};

package/typings/options.d.cts

@@ -0,0 +1,100 @@
+import type { GraphQLTagPluckOptions } from '@graphql-tools/graphql-tag-pluck';
+import type { BaseLoaderOptions } from '@graphql-tools/utils';
+export interface ExternalFragmentLoaderOptions extends BaseLoaderOptions {
+    /**
+     * Absolute path to the target package directory whose fragments we're resolving.
+     * This is the package that has missing fragment spreads referencing other packages.
+     */
+    packageDir: string;
+    /**
+     * Directories where dependency packages can be found.
+     * Each entry is an absolute path to a directory containing package folders.
+     *
+     * @example ['/path/to/monorepo/packages', '/path/to/monorepo/libs', '/path/to/node_modules']
+     */
+    externalPackagesDirs: string[];
+    /**
+     * Whether the default function export should use the asynchronous resolver.
+     * Use this with asynchronous loading APIs such as Codegen or `loadDocuments`.
+     * The synchronous loading API cannot consume the Promise returned in async mode.
+     * The class loader's `load` and `loadSync` methods select their path explicitly.
+     * @default false
+     */
+    async?: boolean;
+    /**
+     * Directories within each package to scan for GraphQL fragments.
+     * @default ['src']
+     */
+    scanInternalDirs?: string[];
+    /**
+     * File extensions to scan for GraphQL fragments (without the dot).
+     * @default ['ts', 'tsx', 'js', 'jsx', 'graphql', 'gql']
+     */
+    extensions?: string[];
+    /**
+     * Glob patterns to exclude when scanning packages.
+     * @default ['**\/__generated__/**', '**\/node_modules/**']
+     */
+    excludePatterns?: string[];
+    /**
+     * Optional filter function to decide which dependencies from `package.json`
+     * should be considered as potential packages with fragments based on their package name.
+     * Return true to include the dependency in the search.
+     * @default () => true (all dependencies are considered)
+     *
+     * @example (name) => name.startsWith('my-org-')
+     */
+    packageNameFilter?: (packageName: string) => boolean;
+    /**
+     * Optional filter to decide whether a dependency package should be scanned
+     * for GraphQL fragments based on its package.json dependencies.
+     * Return true to scan the package.
+     *
+     * Unlike `packageNameFilter`, packages rejected by this filter are still
+     * traversed for their own transitive dependencies — they are just not scanned
+     * for fragment definitions.
+     *
+     * @example (deps) => '@apollo/client' in deps
+     */
+    packageDependencyFilter?: (dependencies: Record<string, string>) => boolean;
+    /**
+     * Optional predicate to filter which files should be scanned for fragments.
+     * Receives the file content as a string. Return true to include the file.
+     * Useful to skip code files that don't use a GraphQL tag or a GraphQL magic comment.
+     *
+     * @example (content, filePath) =>
+     *   /\.(graphql|gql)$/.test(filePath) ||
+     *   /\b(?:gql|graphql)\s*`/.test(content) ||
+     *   /\/\*\s*graphql\s*\*\//i.test(content)
+     */
+    fileContentFilter?: (content: string, filePath: string) => boolean;
+    /**
+     * Whether to include devDependencies when scanning for transitive deps.
+     * @default true
+     */
+    includeDevDependencies?: boolean;
+    /**
+     * Options for graphql-tag-pluck when extracting GraphQL from code files.
+     */
+    pluckConfig?: GraphQLTagPluckOptions;
+    /**
+     * Time-to-live for cache entries in milliseconds.
+     * Set this for long-running processes (e.g. watch mode) so stale entries
+     * are automatically evicted. External package maps include parsed sources
+     * and are shared by resolver calls; a `packageDir` package map is not retained
+     * unless that package was already cached as an external dependency. Cache
+     * configuration is shared by all resolver calls in this module. Calls with
+     * a different value recreate all memoized caches, discard their existing
+     * entries, and apply the new value to later calls.
+     * @default Infinity (cache forever)
+     */
+    cacheTTL?: number;
+    /**
+     * When true, invalidate cached data for the target package specified by `packageDir`
+     * before each resolution call, including its fragment map and package.json
+     * dependency metadata. Useful in watch mode to refresh the package being
+     * edited while reusing dependency caches.
+     * @default false
+     */
+    invalidateTargetPackageCache?: boolean;
+}

package/typings/options.d.ts

@@ -0,0 +1,100 @@
+import type { GraphQLTagPluckOptions } from '@graphql-tools/graphql-tag-pluck';
+import type { BaseLoaderOptions } from '@graphql-tools/utils';
+export interface ExternalFragmentLoaderOptions extends BaseLoaderOptions {
+    /**
+     * Absolute path to the target package directory whose fragments we're resolving.
+     * This is the package that has missing fragment spreads referencing other packages.
+     */
+    packageDir: string;
+    /**
+     * Directories where dependency packages can be found.
+     * Each entry is an absolute path to a directory containing package folders.
+     *
+     * @example ['/path/to/monorepo/packages', '/path/to/monorepo/libs', '/path/to/node_modules']
+     */
+    externalPackagesDirs: string[];
+    /**
+     * Whether the default function export should use the asynchronous resolver.
+     * Use this with asynchronous loading APIs such as Codegen or `loadDocuments`.
+     * The synchronous loading API cannot consume the Promise returned in async mode.
+     * The class loader's `load` and `loadSync` methods select their path explicitly.
+     * @default false
+     */
+    async?: boolean;
+    /**
+     * Directories within each package to scan for GraphQL fragments.
+     * @default ['src']
+     */
+    scanInternalDirs?: string[];
+    /**
+     * File extensions to scan for GraphQL fragments (without the dot).
+     * @default ['ts', 'tsx', 'js', 'jsx', 'graphql', 'gql']
+     */
+    extensions?: string[];
+    /**
+     * Glob patterns to exclude when scanning packages.
+     * @default ['**\/__generated__/**', '**\/node_modules/**']
+     */
+    excludePatterns?: string[];
+    /**
+     * Optional filter function to decide which dependencies from `package.json`
+     * should be considered as potential packages with fragments based on their package name.
+     * Return true to include the dependency in the search.
+     * @default () => true (all dependencies are considered)
+     *
+     * @example (name) => name.startsWith('my-org-')
+     */
+    packageNameFilter?: (packageName: string) => boolean;
+    /**
+     * Optional filter to decide whether a dependency package should be scanned
+     * for GraphQL fragments based on its package.json dependencies.
+     * Return true to scan the package.
+     *
+     * Unlike `packageNameFilter`, packages rejected by this filter are still
+     * traversed for their own transitive dependencies — they are just not scanned
+     * for fragment definitions.
+     *
+     * @example (deps) => '@apollo/client' in deps
+     */
+    packageDependencyFilter?: (dependencies: Record<string, string>) => boolean;
+    /**
+     * Optional predicate to filter which files should be scanned for fragments.
+     * Receives the file content as a string. Return true to include the file.
+     * Useful to skip code files that don't use a GraphQL tag or a GraphQL magic comment.
+     *
+     * @example (content, filePath) =>
+     *   /\.(graphql|gql)$/.test(filePath) ||
+     *   /\b(?:gql|graphql)\s*`/.test(content) ||
+     *   /\/\*\s*graphql\s*\*\//i.test(content)
+     */
+    fileContentFilter?: (content: string, filePath: string) => boolean;
+    /**
+     * Whether to include devDependencies when scanning for transitive deps.
+     * @default true
+     */
+    includeDevDependencies?: boolean;
+    /**
+     * Options for graphql-tag-pluck when extracting GraphQL from code files.
+     */
+    pluckConfig?: GraphQLTagPluckOptions;
+    /**
+     * Time-to-live for cache entries in milliseconds.
+     * Set this for long-running processes (e.g. watch mode) so stale entries
+     * are automatically evicted. External package maps include parsed sources
+     * and are shared by resolver calls; a `packageDir` package map is not retained
+     * unless that package was already cached as an external dependency. Cache
+     * configuration is shared by all resolver calls in this module. Calls with
+     * a different value recreate all memoized caches, discard their existing
+     * entries, and apply the new value to later calls.
+     * @default Infinity (cache forever)
+     */
+    cacheTTL?: number;
+    /**
+     * When true, invalidate cached data for the target package specified by `packageDir`
+     * before each resolution call, including its fragment map and package.json
+     * dependency metadata. Useful in watch mode to refresh the package being
+     * edited while reusing dependency caches.
+     * @default false
+     */
+    invalidateTargetPackageCache?: boolean;
+}

package/typings/resolve.d.cts

@@ -0,0 +1,57 @@
+import { type DocumentNode } from 'graphql';
+import { type GraphQLTagPluckOptions } from '@graphql-tools/graphql-tag-pluck';
+interface FragmentInfo {
+    name: string;
+    typeCondition: string;
+}
+interface ParsedSource {
+    rawSDL: string;
+    document: DocumentNode;
+}
+export interface PackageFragmentMap {
+    fragments: Map<string, {
+        filePath: string;
+        typeCondition: string;
+    }>;
+    spreadsPerFile: Map<string, Set<string>>;
+    defsPerFile: Map<string, FragmentInfo[]>;
+}
+export interface ResolvedExternalFile {
+    filePath: string;
+    definitions: FragmentInfo[];
+    packageName: string;
+}
+interface ResolvedExternalFileWithSources extends ResolvedExternalFile {
+    sources: ParsedSource[];
+}
+export interface ExternalFragmentResolverOptions {
+    packageDir: string;
+    externalPackagesDirs: string[];
+    packageNameFilter?: (packageName: string) => boolean;
+    packageDependencyFilter?: (dependencies: Record<string, string>) => boolean;
+    includeDevDependencies?: boolean;
+    scanInternalDirs?: string[];
+    extensions?: string[];
+    excludePatterns?: string[];
+    pluckConfig?: GraphQLTagPluckOptions;
+    fileContentFilter?: (content: string, filePath: string) => boolean;
+    cacheTTL?: number;
+    invalidateTargetPackageCache?: boolean;
+}
+/**
+ * Clears all internal caches.
+ */
+export declare function clearCache(): void;
+/**
+ * Resolves cross-package GraphQL fragment dependencies across external packages.
+ * Async version — reads files in parallel for better performance on large codebases.
+ */
+export declare function resolveExternalFragmentsWithSources(options: ExternalFragmentResolverOptions, filterToRequiredFragments?: boolean): Promise<ResolvedExternalFileWithSources[]>;
+export declare function resolveExternalFragments(options: ExternalFragmentResolverOptions): Promise<ResolvedExternalFile[]>;
+/**
+ * Resolves cross-package GraphQL fragment dependencies across external packages.
+ * Sync version.
+ */
+export declare function resolveExternalFragmentsSyncWithSources(options: ExternalFragmentResolverOptions, filterToRequiredFragments?: boolean): ResolvedExternalFileWithSources[];
+export declare function resolveExternalFragmentsSync(options: ExternalFragmentResolverOptions): ResolvedExternalFile[];
+export {};

package/typings/resolve.d.ts

@@ -0,0 +1,57 @@
+import { type DocumentNode } from 'graphql';
+import { type GraphQLTagPluckOptions } from '@graphql-tools/graphql-tag-pluck';
+interface FragmentInfo {
+    name: string;
+    typeCondition: string;
+}
+interface ParsedSource {
+    rawSDL: string;
+    document: DocumentNode;
+}
+export interface PackageFragmentMap {
+    fragments: Map<string, {
+        filePath: string;
+        typeCondition: string;
+    }>;
+    spreadsPerFile: Map<string, Set<string>>;
+    defsPerFile: Map<string, FragmentInfo[]>;
+}
+export interface ResolvedExternalFile {
+    filePath: string;
+    definitions: FragmentInfo[];
+    packageName: string;
+}
+interface ResolvedExternalFileWithSources extends ResolvedExternalFile {
+    sources: ParsedSource[];
+}
+export interface ExternalFragmentResolverOptions {
+    packageDir: string;
+    externalPackagesDirs: string[];
+    packageNameFilter?: (packageName: string) => boolean;
+    packageDependencyFilter?: (dependencies: Record<string, string>) => boolean;
+    includeDevDependencies?: boolean;
+    scanInternalDirs?: string[];
+    extensions?: string[];
+    excludePatterns?: string[];
+    pluckConfig?: GraphQLTagPluckOptions;
+    fileContentFilter?: (content: string, filePath: string) => boolean;
+    cacheTTL?: number;
+    invalidateTargetPackageCache?: boolean;
+}
+/**
+ * Clears all internal caches.
+ */
+export declare function clearCache(): void;
+/**
+ * Resolves cross-package GraphQL fragment dependencies across external packages.
+ * Async version — reads files in parallel for better performance on large codebases.
+ */
+export declare function resolveExternalFragmentsWithSources(options: ExternalFragmentResolverOptions, filterToRequiredFragments?: boolean): Promise<ResolvedExternalFileWithSources[]>;
+export declare function resolveExternalFragments(options: ExternalFragmentResolverOptions): Promise<ResolvedExternalFile[]>;
+/**
+ * Resolves cross-package GraphQL fragment dependencies across external packages.
+ * Sync version.
+ */
+export declare function resolveExternalFragmentsSyncWithSources(options: ExternalFragmentResolverOptions, filterToRequiredFragments?: boolean): ResolvedExternalFileWithSources[];
+export declare function resolveExternalFragmentsSync(options: ExternalFragmentResolverOptions): ResolvedExternalFile[];
+export {};