{"id":13689429,"url":"https://github.com/realm/realm-graphql","last_synced_at":"2025-05-01T23:34:26.317Z","repository":{"id":46281446,"uuid":"113117020","full_name":"realm/realm-graphql","owner":"realm","description":"GraphQL client for Realm Object Server","archived":true,"fork":false,"pushed_at":"2021-11-08T09:43:56.000Z","size":853,"stargazers_count":80,"open_issues_count":22,"forks_count":11,"subscribers_count":24,"default_branch":"master","last_synced_at":"2024-08-03T15:17:51.187Z","etag":null,"topics":["apollo-client","graphql","reactive","realm","realm-object-server","web"],"latest_commit_sha":null,"homepage":"https://realm.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/realm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-05T01:43:15.000Z","updated_at":"2024-01-14T13:32:19.000Z","dependencies_parsed_at":"2022-09-03T00:33:11.546Z","dependency_job_id":null,"html_url":"https://github.com/realm/realm-graphql","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realm%2Frealm-graphql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realm%2Frealm-graphql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realm%2Frealm-graphql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realm%2Frealm-graphql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/realm","download_url":"https://codeload.github.com/realm/realm-graphql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224282273,"owners_count":17285798,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apollo-client","graphql","reactive","realm","realm-object-server","web"],"created_at":"2024-08-02T15:01:47.408Z","updated_at":"2024-11-12T13:31:42.892Z","avatar_url":"https://github.com/realm.png","language":"TypeScript","funding_links":[],"categories":["graphql"],"sub_categories":[],"readme":"# DEPRECATED\nWith the introduction of [MongoDB Realm](https://www.mongodb.com/realm), this package is **deprecated**. Please use [MongoDB Realm Cloud](https://docs.mongodb.com/realm/) and the [GraphQL API](https://docs.mongodb.com/realm/graphql/).\n\n-----\n# Realm GraphQL Client\n\nA set of helper methods and classes to make it easier to use the Apollo GraphQL client with the Realm Object Server.\n\n## Using the Client\n\nThe Realm GraphQL client provides a few helper and convenience API to make it easier to consume the [Realm Object Server GraphQL API](https://github.com/realm/realm-graphql-service) with the [Apollo Client](https://www.apollographql.com/client).\n\n### Prerequisites\n\nAdd the [apollo-link](https://www.npmjs.com/package/apollo-link), [apollo-link-http](https://www.npmjs.com/package/apollo-link-http), [apollo-link-ws](https://www.npmjs.com/package/apollo-link-ws), and [subscriptions-transport-ws](https://www.npmjs.com/package/subscriptions-transport-ws) packages to your project:\n\n```\nnpm install graphql apollo-link apollo-link-http apollo-link-ws apollo-utilities subscriptions-transport-ws --save\n```\n\nThen, add the Realm GraphQL client package:\n\n```\nnpm install realm-graphql-client --save\n```\n\n### Getting Started\n\n#### Authenticating the user\n\nTo start consuming the GraphQL API, you'll need to login a user:\n\n```ts\nimport { Credentials, User } from 'realm-graphql-client';\n\nconst credentials = Credentials.usernamePassword('SOME-USERNAME', 'SOME-PASSWORD');\nconst user = await User.authenticate(credentials, 'http://my-ros-instance:9080');\n```\n\nOther credential providers are supported, such as JWT, Facebook, Google etc. They are all exposed as factories on the `Credentials` class.\n\nAfter you have your user, you can create a helper config that will handle token refreshes and authentication:\n\n```ts\nimport { GraphQLConfig } from 'realm-graphql-client';\n\nconst config = await GraphQLConfig.create(\n  user,\n  '/~/test'\n);\n```\n\nNote that each config is created per Realm path, so if you need to query multiple Realms, you'll need to obtain a config instance for each of them.\n\n#### Setting up the Client\n\nOnce you have a config, you can use that to create an Apollo client instance and configure it. The config exposes 4 properties:\n\n- `httpEndpoint`: This is the endpoint you'll use to execute queries and mutations against.\nIt can be used to configure Apollo's [httpLink](https://www.apollographql.com/docs/link/links/http.html).\n- `authLink`: This is a link that provides an Authorization header for the user/path combination.\nIt should be composed together with your `httpLink`.\n- `webSocketEndpoint`: This is the endpoint you'll use to execute subscriptions against. It can be\nused to configure Apollo's [WebSocket Link](https://www.apollographql.com/docs/link/links/ws.html).\n- `connectionParams`: This is a function that will provide an authorization object each time a\nwebsocket connection is established. You should pass that directly (without invoking it) to the\nWebSocketLink's constructor's options.\n\nLet's look at a small example. First, let's configure the `httpLink` that we'll use for querying and mutating:\n\n```ts\nimport { HttpLink } from 'apollo-link-http';\nimport { concat } from 'apollo-link';\n\nconst httpLink = concat(\n    config.authLink,\n    // Note: if using node.js, you'll need to provide fetch as well.\n    new HttpLink({ uri: config.httpEndpoint })\n  );\n```\n\nThen, let's configure the websocket link that we'll use for subscriptions:\n\n```ts\nimport { WebSocketLink } from 'apollo-link-ws';\n\n// Note: if using node.js, you'll need to provide webSocketImpl as well.\nconst webSocketLink = new WebSocketLink({\n  uri: config.webSocketEndpoint,\n  options: {\n    connectionParams: config.connectionParams,\n  }\n});\n```\n\nFinally, we need to use [split](https://www.apollographql.com/docs/link/composition.html#directional) to direct subscriptions to the websocket link and queries and mutations to the http link:\n\n```ts\nimport { split } from 'apollo-link';\nimport { getMainDefinition } from 'apollo-utilities';\n\nconst link = split(\n  ({ query }) =\u003e {\n    const { kind, operation } = getMainDefinition(query);\n    return kind === 'OperationDefinition' \u0026\u0026 operation === 'subscription';\n  },\n  webSocketLink,\n  httpLink,\n);\n\n// Finally, create the client\nclient = new ApolloClient({\n  link: link,\n  cache: new InMemoryCache()\n});\n```\n\n### Using the client\n\nNow that you have configured your client, you can use to access the ROS GraphQL API.\n\n#### Queries\n\nQuerying data is as simple as invoking `client.query()`:\n\n```ts\nconst query = gql`\n  query {\n    companies {\n      companyId\n      name\n      address\n    }\n  }\n`;\n\nconst response = await client.query({\n  query: query\n});\n\nconst companies = response.data.companies;\n```\n\nFor a complete list of supported query operations, refer to the [GraphQL Server docs](https://github.com/realm/realm-object-server-graphql#querying).\n\nFor a detailed documentation on the Apollo Client query capabilities, refer to the [Apollo docs](https://www.apollographql.com/docs/angular/basics/queries.html).\n\nFor a comprehensive documentation on the query language syntax, refer to the [Realm JS Query Language docs](https://github.com/realm/realm-js/blob/master/docs/tutorials/query-language.md#backlink-queries).\n\n**Note**: Server Realms (used by GraphQL) don't have named backlinks, even if the client Realms had them defined, so you'll need to use the fully qualified backlink syntax, e.g.:\n\n```json\n{\n  golfers(query: \"@links.Club.golfers.id = 'some-club-id'\") {\n    firstName\n    lastName\n  }\n}\n```\n\n#### Mutations\n\nMutating data happens when you invoke the `client.mutate()` method:\n\n```ts\nconst mutation = gql`\n  mutation {\n    result: addCompany(input: {\n      companyId: \"some-unique-id\"\n      name: \"My Amazing Company\"\n      address: \"Mars\"\n    }) {\n      companyId\n      name\n      address\n    }\n  }\n`\n\nconst response = await client.mutate({\n  mutation: mutation\n});\n\nconst addedCompany = response.data.result;\n```\n\nFor a complete list of supported mutation operations, refer to the [GraphQL Server docs](https://github.com/realm/realm-object-server-graphql#mutating).\n\nFor a detailed documentation on the Apollo Client query capabilities, refer to the [Apollo docs](https://www.apollographql.com/docs/angular/basics/mutations.html).\n\n#### Subscriptions\n\nSubscribing for changes happens when you invoke the `client.subscribe()` method. You get\nan `Observable` sequence you can then add an observer to:\n\n```ts\nconst observable = await client.subscribe({\n  query: gql`\n    subscription {\n      companies${additionalParameters || ''} {\n        companyId\n        name\n        address\n      }\n    }\n  `\n});\n\nobservable.subscribe({\n  next(data) {\n    const companies = data.data.companies;\n    // Update you UI\n  },\n  error(value) {\n    // Notify the user of the failure\n  }\n});\n```\n\nFor a complete list of supported mutation operations, refer to the [GraphQL Server docs](https://github.com/realm/realm-object-server-graphql#subscribing).\n\nFor a detailed documentation on the Apollo Client query capabilities, refer to the [Apollo docs](https://www.apollographql.com/docs/angular/features/subscriptions.html).\n\n\n## Developing the client\n\n### Commands for Building, Cleaning, Testing, Linting and Watching\n\nAfter `npm install`\n\n1. To Build `npm run build`\n2. To Clean Artifacts `npm run clean`\n3. To Test `npm run test`\n4. To Lint `npm run lint`\n5. To Buld and Watch when you make changes `npm run watch`\n\n### Debugging with Visual Studio Code\n\n1. Set a breakpoint in your code ending in `.ts` or your test ending in `.spec.ts`\n2. Run Either `src/index.ts` or `All Tests` in the debug pane.\n\n### Some Advice\n\nNever use arrow functions on the `Mocha` test handlers. Why? The callback has its own set of methods. The arrow function does not have an easy way to reference `this`\n\nSay you want to increase the timeout of the function callback in your tests\n\n```javascript\nit('should do something', () =\u003e {\n    this.timeout(2000) // this is not the callback function!\n})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealm%2Frealm-graphql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frealm%2Frealm-graphql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealm%2Frealm-graphql/lists"}