feature: add federation-link-util library

integration-tests/tests/schema/contracts.spec.ts

@@ -268,7 +268,6 @@ test('federation schema contains list of tags', async () => {
       },
     ],
   });
-
   expect(result.tags).toMatchInlineSnapshot(`
     [
       toyota,

packages/libraries/federation-link-utils/README.md

@@ -0,0 +1,65 @@
+# GraphQL Hive - federation-link-utils
+
+[Hive](https://the-guild.dev/graphql/hive) is a fully open-source schema registry, analytics,
+metrics and gateway for [GraphQL federation](https://the-guild.dev/graphql/hive/federation) and
+other GraphQL APIs.
+
+---
+
+This library can be used to create custom features for GraphQL schemas backed by Federation's
+[`@link`](https://www.apollographql.com/docs/graphos/reference/federation/directives#the-link-directive)
+directive.
+
+## Features
+
+- Link version support.
+- Import `as`/namespacing support that follows the [link spec](https://specs.apollo.dev/link/v1.0/).
+- Only `graphql` as a peer dependency.
+
+## Usage
+
+This library is for power users who want to develop their own Federation 2 `@link` feature(s). It
+enables you to define and support multiple versions of the feature and to easily reference the named
+imports. This includes official federation features if you choose to implement them yourself.
+
+```graphql
+# schema.graphql
+
+directive @example(eg: String!) on FIELD
+extend schema @link(url: "https://specs.graphql-hive.com/example/v1.0", import: ["@example"])
+type Query {
+  user: User @example(eg: "query { user { id name } }")
+}
+
+type User {
+  id: ID!
+  name: String
+}
+```
+
+```typescript
+// specs.ts
+import { extractLinkImplementations } from '@graphql-hive/federation-link-utils'
+
+const typeDefs = parse(sdl)
+const { matchesImplementation, resolveImportName } = extractLinkImplementations(typeDefs);
+if (matchesImplementation('https://specs.graphql-hive.com/example', 'v1.0')) {
+  const examples: Record<string, string> = {}
+  const exampleName = resolveImportName('https://specs.graphql-hive.com/example', '@example')
+  visit(typeDefs, {
+    FieldDefinition: node => {
+      const example = node.directives?.find(d => d.name.value === exampleName)
+      if (example) {
+        examples[node.name.value] = (
+          example.arguments?.find(a => a.name.value === 'eg')?.value as
+            | StringValueNode
+            | undefined
+        )?.value
+      }
+    }
+  })
+  return examples
+}
+
+// result[0] ==> { user: "query { user { id name } }"}
+```

packages/libraries/federation-link-utils/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@graphql-hive/federation-link-utils",
+  "version": "0.0.1",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "graphql-hive/platform",
+    "directory": "packages/libraries/federation-link-utils"
+  },
+  "homepage": "https://the-guild.dev/graphql/hive",
+  "author": {
+    "email": "contact@the-guild.dev",
+    "name": "The Guild",
+    "url": "https://the-guild.dev"
+  },
+  "license": "MIT",
+  "private": true,
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/typings/index.d.cts",
+        "default": "./dist/cjs/index.js"
+      },
+      "import": {
+        "types": "./dist/typings/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "default": {
+        "types": "./dist/typings/index.d.ts",
+        "default": "./dist/esm/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typings": "dist/typings/index.d.ts",
+  "scripts": {
+    "build": "node ../../../scripts/generate-version.mjs && bob build",
+    "check:build": "bob check"
+  },
+  "peerDependencies": {
+    "graphql": "^14.0.0 || ^15.0.0 || ^16.0.0"
+  },
+  "devDependencies": {
+    "graphql": "16.9.0",
+    "tslib": "2.8.1",
+    "vitest": "3.0.5"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "directory": "dist"
+  },
+  "sideEffects": false,
+  "typescript": {
+    "definition": "dist/typings/index.d.ts"
+  }
+}

packages/libraries/federation-link-utils/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * Exposes a simple and efficient API for interacting with Federation V2's `@link` directives
+ * according to spec.
+ */
+
+import type { DocumentNode } from 'graphql';
+import { FederatedLinkUrl } from './link-url.js';
+import { FederatedLink } from './link.js';
+
+export const FEDERATION_V1 = Symbol('Federation_V1');
+
+export type LinkVersion = string | { major: number; minor: number } | null | typeof FEDERATION_V1;
+
+export function extractLinkImplementations(typeDefs: DocumentNode): {
+  /**
+   *
+   * @param identity The link identity. E.g. https://specs.apollo.dev/link/v1.0
+   * @param name The imported object name, without namespacing. E.g. "@link"
+   * @returns The imported object's name within the typedefs. E.g.
+   *   For `@link(url: "https://example.com/", import: [{ name: "@example", as: "@eg" }])`,
+   *   `resolveImportName("@example")` returns "eg".
+   *   And for `@link(url: "https://example.com/foo")`, `resolveImportName("@example")`
+   *   returns the namespaced name, "foo__example"
+   */
+  resolveImportName: (identity: string, name: string) => string;
+
+  /**
+   * Check that the linked version is supported by the code implementation.
+   *
+   * @param identity The link identity. E.g. https://specs.graphql-hive.com/example
+   * @param version The version in which the feature was added. E.g. 1.0
+   * @returns true if the supplied link supports this the version argument.
+   *   E.g. matchesImplementation('https://specs.graphql-hive.com/example', '1.1') returns true if
+   *   is version >= 1.1 < 2.0, but false if the link is version 1.0
+   */
+  matchesImplementation: (identity: string, version: LinkVersion) => boolean;
+} {
+  const linkByIdentity = Object.fromEntries(
+    FederatedLink.fromTypedefs(typeDefs).map(l => [l.identity, l]),
+  );
+  // Any schema with a `@link` directive present is considered federation 2
+  // although according to federation docs, schemas require linking specifically
+  // the federation 2.x spec. The reason for not being so picky is that supergraphs also
+  // use @link, but do not necessarily link to the federation 2.x spec.
+  const supportsFederationV2 = Object.keys(linkByIdentity).length > 0;
+
+  return {
+    resolveImportName: (identity, name) => {
+      if (!supportsFederationV2) {
+        // Identities dont matter for Federation v1. There are no links to reference.
+        // So return the name without the identity's namespace
+        return name.startsWith('@') ? name.substring(1) : name;
+      }
+
+      const matchingLink = linkByIdentity[identity];
+      if (!matchingLink) {
+        const defaultLink = new FederatedLink(FederatedLinkUrl.fromUrl(identity), null, []);
+        // The identity was not imported, but return we still will return what is assumed to be the name
+        // of the import based off the identity. `matchesImplementation` should be used for cases where
+        // it matters whether or not a specific url was linked.
+        return defaultLink.resolveImportName(name);
+      }
+      return matchingLink.resolveImportName(name);
+    },
+    matchesImplementation: (identity, version) => {
+      if (version === FEDERATION_V1) {
+        return !supportsFederationV2;
+      }
+      const matchingLink = linkByIdentity[identity];
+      if (!matchingLink) {
+        return false;
+      }
+      if (typeof version === 'string') {
+        return matchingLink.supports(version);
+      }
+      if (version === null) {
+        return matchingLink.supports(version);
+      }
+      return matchingLink.supports(version.major, version.minor);
+    },
+  };
+}

packages/libraries/federation-link-utils/src/link-import.ts

@@ -0,0 +1,48 @@
+import { ConstValueNode, Kind } from 'graphql';
+
+export class FederatedLinkImport {
+  constructor(
+    public name: string,
+    public as: string | null,
+  ) {}
+
+  public toString(): string {
+    return this.as ? `{ name: "${this.name}", as: "${this.as}" }` : `"${this.name}"`;
+  }
+
+  static fromTypedefs(node: ConstValueNode): FederatedLinkImport[] {
+    if (node.kind == Kind.LIST) {
+      const imports = node.values.map(v => {
+        if (v.kind === Kind.STRING) {
+          return new FederatedLinkImport(v.value, null);
+        }
+        if (v.kind === Kind.OBJECT) {
+          let name: string = '';
+          let as: string | null = null;
+
+          v.fields.forEach(f => {
+            if (f.name.value === 'name') {
+              if (f.value.kind !== Kind.STRING) {
+                throw new Error(
+                  `Expected string value for @link "name" field but got "${f.value.kind}"`,
+                );
+              }
+              name = f.value.value;
+            } else if (f.name.value === 'as') {
+              if (f.value.kind !== Kind.STRING) {
+                throw new Error(
+                  `Expected string value for @link "as" field but got "${f.value.kind}"`,
+                );
+              }
+              as = f.value.value;
+            }
+          });
+          return new FederatedLinkImport(name, as);
+        }
+        throw new Error(`Unexpected value kind "${v.kind}" in @link import declaration`);
+      });
+      return imports;
+    }
+    throw new Error(`Expected a list of @link imports but got "${node.kind}"`);
+  }
+}

packages/libraries/federation-link-utils/src/link-url.ts

@@ -0,0 +1,90 @@
+const VERSION_MATCH = /v(\d{1,3})\.(\d{1,4})/i;
+
+function parseVersion(version: string | null): [number, number] {
+  const versionParts = version?.match(VERSION_MATCH);
+  if (versionParts?.length) {
+    const [_full, major, minor] = versionParts;
+    return [Number(major), Number(minor)];
+  }
+  return [-1, -1];
+}
+
+/**
+ * A wrapper around the `@link` url -- this parses all necessary data to identify the link
+ * and determine which version is most appropriate to use.
+ */
+export class FederatedLinkUrl {
+  // -1 if no version is set
+  private readonly major: number;
+  private readonly minor: number;
+
+  constructor(
+    public readonly identity: string,
+    public readonly name: string | null,
+    public readonly version: string | null,
+  ) {
+    const [major, minor] = parseVersion(version);
+    this.major = major;
+    this.minor = minor;
+  }
+
+  public toString(): string {
+    return `${this.identity}${this.version ? `/${this.version}` : ''}`;
+  }
+
+  static fromUrl = (urlSource: string): FederatedLinkUrl => {
+    const url = new URL(urlSource);
+    const parts = url.pathname.split('/').filter(Boolean);
+    const versionOrName = parts[parts.length - 1];
+    if (versionOrName) {
+      if (VERSION_MATCH.test(versionOrName)) {
+        const maybeName = parts[parts.length - 2];
+        return new FederatedLinkUrl(
+          url.origin + (maybeName ? `/${parts.slice(0, parts.length - 1).join('/')}` : ''),
+          maybeName ?? null,
+          versionOrName,
+        );
+      }
+      return new FederatedLinkUrl(`${url.origin}/${parts.join('/')}`, versionOrName, null);
+    }
+    return new FederatedLinkUrl(url.origin, null, null);
+  };
+
+  /** Check if this version supports another version */
+  supports(version: string): boolean;
+  supports(major: number, minor: number): boolean;
+  supports(version: FederatedLinkUrl): boolean;
+  supports(version: null): boolean;
+  supports(...args: [string] | [number, number] | [FederatedLinkUrl] | [null]): boolean {
+    const majorOrVersion = args[0];
+    let major: number, minor: number;
+    if (typeof majorOrVersion === 'string') {
+      [major, minor] = parseVersion(majorOrVersion);
+    } else if (typeof majorOrVersion === 'number') {
+      [major, minor] = args as [number, number];
+    } else if (majorOrVersion instanceof FederatedLinkUrl) {
+      // check that it is the same spec
+      if (majorOrVersion.identity !== this.identity) {
+        return false;
+      }
+      major = majorOrVersion.major;
+      minor = majorOrVersion.minor;
+    } else if (majorOrVersion === null) {
+      // handles null case
+      return majorOrVersion === this.version;
+    } else {
+      throw new Error(`Unsupported version argument: ${JSON.stringify(args)} [${typeof args}].`);
+    }
+    return this.isCompatibleVersion(major, minor);
+  }
+
+  private isCompatibleVersion(major: number, minor: number): boolean {
+    if (this.major === major) {
+      if (this.major === 0) {
+        return this.minor === minor;
+      }
+      return this.minor >= minor;
+    }
+    return false;
+  }
+}