{"id":13792197,"url":"https://github.com/dfuse-io/client-js","last_synced_at":"2026-01-12T06:38:50.048Z","repository":{"id":34448503,"uuid":"178021482","full_name":"dfuse-io/client-js","owner":"dfuse-io","description":"dfuse JavaScript/TypeScript Client Library for dfuse API","archived":false,"fork":false,"pushed_at":"2023-10-02T18:58:43.000Z","size":1820,"stargazers_count":52,"open_issues_count":15,"forks_count":28,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-11T01:05:33.713Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.dfuse.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dfuse-io.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,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-03-27T15:20:08.000Z","updated_at":"2025-03-11T09:33:40.000Z","dependencies_parsed_at":"2024-01-28T16:53:37.288Z","dependency_job_id":null,"html_url":"https://github.com/dfuse-io/client-js","commit_stats":{"total_commits":397,"total_committers":18,"mean_commits":"22.055555555555557","dds":0.5264483627204031,"last_synced_commit":"ed4493461c8529899beccf783393c9e3a92851b6"},"previous_names":[],"tags_count":74,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfuse-io%2Fclient-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfuse-io%2Fclient-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfuse-io%2Fclient-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfuse-io%2Fclient-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dfuse-io","download_url":"https://codeload.github.com/dfuse-io/client-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253528899,"owners_count":21922627,"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":[],"created_at":"2024-08-03T22:01:09.378Z","updated_at":"2026-01-12T06:38:50.037Z","avatar_url":"https://github.com/dfuse-io.png","language":"TypeScript","funding_links":[],"categories":["Roadmap"],"sub_categories":[],"readme":"# dfuse JavaScript/TypeScript Client Library\n\nA GraphQL, WebSocket and HTTP REST client library to consume dfuse API \u003chttps://dfuse.io\u003e ([dfuse docs](https://docs.dfuse.io)).\n\n## Installation\n\nUsing Yarn:\n\n    yarn add @dfuse/client\n\n    # Use this command if you are using npm\n    #npm install --save @dfuse/client\n\n## Features\n\nWhat you get by using this library:\n\n- Full dfuse API coverage (GraphQL, REST \u0026 WebSocket)\n- API Token issuance \u0026 management (auto-refresh, expiration handling, storage, etc)\n- Automatic re-connection on socket close\n- Stream progress management and auto-restart at last marked location on socket re-connection\n- Full customization power\n\n## Quick Start\n\n_Notice_ You should replace the sequence of characters `Paste your API key here`\nin the script above with your actual API key obtained from https://app.dfuse.io. You are\nconnecting to a local dfuse for EOSIO instance or to a dfuse Community Edition? Replace\n`apiKey: \"\u003cPaste your API key here\u003e\"` with `authentication: false` so authentication is\ndisabled.\n\n### EOSIO\n\n\u003c!-- prettier-ignore --\u003e\nSee [examples/basic/eosio/stream-transfers-graphql.ts](./examples/basic/eosio/stream-transfers-graphql.ts)\n\n```js\nconst { createDfuseClient } = require(\"@dfuse/client\")\nconst client = createDfuseClient({\n  apiKey: \"\u003cPaste your API key here\u003e\",\n  network: \"mainnet.eos.dfuse.io\",\n})\n\nconst streamTransfer = `subscription($cursor: String!) {\n  searchTransactionsForward(query: \"receiver:eosio.token action:transfer -data.quantity:'0.0001 EOS'\", cursor: $cursor) {\n    undo cursor\n    trace {\n      matchingActions { json }\n    }\n  }\n}`\n\nawait client.graphql(streamTransfer, (message, stream) =\u003e {\n  if (message.type === \"error\") {\n    console.log(\"An error occurred\", message.errors, message.terminal)\n  }\n\n  if (message.type === \"data\") {\n    const data = message.data.searchTransactionsForward\n    const actions = data.trace.matchingActions\n\n    actions.forEach(({ json }: any) =\u003e {\n      const { from, to, quantity, memo } = json\n      console.log(`Transfer [${from} -\u003e ${to}, ${quantity}] (${memo})`)\n    })\n\n    stream.mark({ cursor: data.cursor })\n  }\n\n  if (message.type === \"complete\") {\n    console.log(\"Stream completed\")\n  }\n})\n```\n\n### Ethereum\n\nSee [examples/basic/ethereum/stream-transfers.ts](./examples/basic/ethereum/stream-transfers.ts)\n\n\u003c!-- prettier-ignore --\u003e\n```js\nconst { createDfuseClient } = require(\"@dfuse/client\")\n\nconst streamTransfer = `subscription($cursor: String) {\n  searchTransactions(query: \"method:'transfer(address,uint256)'\", cursor: $cursor) {\n    undo cursor\n    node { hash from to value(encoding: ETHER) }\n  }\n}`\n\nawait client.graphql(streamTransfer, (message, stream) =\u003e {\n  if (message.type === \"error\") {\n    console.log(\"An error occurred\", message.errors, message.terminal)\n  }\n\n  if (message.type === \"data\") {\n    const { cursor, node } = message.data.searchTransactions\n    console.log(`Transfer [${node.from} -\u003e ${node.to}, ${node.value}]`)\n\n    stream.mark({ cursor })\n  }\n\n  if (message.type === \"complete\") {\n    console.log(\"Stream completed\")\n  }\n})\n```\n\n### Node.js\n\nIf you target a `Node.js` environment instead, you will need bring a `fetch` compatible\nfunction and a proper `WebSocket` client.\n\nYou are free to use any compatible library respecting the respective requirements. To\nmake it simple, if `fetch` and/or `WebSocket` are available in the global scope (`global`),\nthey are picked automatically by the library. While polluting the global scope, it's the\neasiest way to get started.\n\nIt's what the examples in this project do using respectively\n[node-fetch](https://www.npmjs.com/package/node-fetch) and\nand [ws](https://www.npmjs.com/package/ws) for `fetch` and `WebSocket` respectively.\n\nInstallation instructions using Yarn would be:\n\n    yarn add node-fetch ws\n\nIn the bootstrap phase of your application, prior doing any `@dfuse/client` imports/require,\nput the following code:\n\n    global.fetch = require(\"node-fetch\");\n    global.WebSocket = require(\"ws\");\n\nYou can check the [Node.js Configuration](./examples/advanced/common/nodejs-fetch-and-websocket-options.ts)\nexample for how to avoid polluting the global scope.\n\n### Sane Defaults\n\nThe library make sane default assumptions about some of the dependencies\nthe library requires. This section details the choices we think are the\nmost important ones.\n\n#### Fetch\n\nThe library requires a `Fetch` like interface. In the Browser environment,\nthis is the `fetch` function that is used (we check that `window.fetch` is\na function).\n\nIf `window.fetch` is undefined, we fallback to check `global.fetch` variable.\nThis can be set in a Node.js environment to point to a compatible implementation\nof `fetch`, like the one provided by the [node-fetch](https://npmjs.com/package/node-fetch)\npackage.\n\nIf none is provided, the library throw an error. To avoid this error, you should pass\nthe `httpClientOptions.fetch` option when creating the dfuse Client.\n\nIt possible to provide you own implementation using under the cover any\nHTTP library like [axios](https://npmjs.com/package/axios) or even\n`XMLHttpRequest` if you wish so.\n\n#### WebSocket\n\nThe library requires a `WebSocket` client interface having the same semantics\nas the WebSocket API in the Browser environment.\n\nIn the Browser environment, this is the standard `WebSocket` variable that is used\n(we check that `window.WebSocket` is present).\n\nIf `window.WebSocket` is undefined, we fallback to check `global.WebSocket` variable.\nThis can be set in a Node.js environment to point to a compatible implementation\nof `WebSocket` client, like the one provided by the [ws](https://npmjs.com/package/ws)\npackage.\n\nIf none is provided, the library throw an error. To avoid this error, you should pass\nthe `streamClientOptions.socketOptions.webSocketFactory` and the\n`graphqlStreamClientOptions.socketOptions.webSocketFactory` options when creating the dfuse\nClient. This factory method receives the full url to connect to the remote endpoint\n(this will include the API token to use in query parameters of the url) and should\nreturn a valid `WebSocket` client object.\n\nWe highly suggest to use [ws](https://npmjs.com/package/ws) package straight in a\nNode.js environment.\n\n#### API Token Store\n\nThe API token store interface is used by the dfuse Client to perform the\npersistent retrieval and writing of the API token. Indeed, we rate limit\nthe API token issuance endpoint and as such, it's **highly** important\nto re-use a valid token instead of generating a new one each time it's\nrequired to avoid hitting the API token issue rate limiter.\n\nThe library, when no `apiTokenStore` options is passed to the client will\npick a default `ApiTokenStore` implementation based on your environment.\n\nIn a Browser environment, the concrete implementation that is used is the\n[LocalStorageApiTokenStore](https://dfuse-io.github.io/client-js/classes/localstorageapitokenstore.html)\nclass. This will save and retrieve the token from the browser `localStorage`\n(under a `dfuse:token` key).\n\nIn a Node.js environment, the concrete implementation that is used is the\n[OnDiskApiTokenStore](https://dfuse-io.github.io/client-js/classes/ondiskapitokenstore.html) class.\nThis will save and retrieve the token from a local file on the disk\nat `~/.dfuse/\u003csha256-api-key\u003e/token.info`.\n\n**Note** Depending on your deployment target (`Docker`, VM, etc.), it's possible\nthat the home directory (`~`) is not writable, causing the default\n[OnDiskApiTokenStore](https://dfuse-io.github.io/client-js/classes/ondiskapitokenstore.html)\ninstance on Node.js environment to not work correctly. In those cases, simply define\nyourself the `apiTokenStore` instance to use and pick the location where the token\nshould be saved. Instantiate a\n[FileApiTokenStore](https://dfuse-io.github.io/client-js/classes/fileapitokenstore.html)\ninstance and use it as the `apiTokenStore` configuration value when instantiating the\ndfuse Client:\n\n```\nimport { createDfuseClient, FileApiTokenStore } from \"@dfuse/client\";\n\nconst client = createDfuseClient({\n  ...,\n  apiTokenStore: new FileApiTokenStore(\"/tmp/dfuse-token.json\"),\n  ...,\n});\n```\n\n### API\n\nThe full API reference can be found at https://dfuse-io.github.io/client-js/.\n\nThis site is generated by running `typedoc` on this repository. The full API\nreference being rather exhaustive, here a quick index pointing to the most\nimportant entities' documentation section that should be read to understand\nthe various part of the library:\n\n##### Factories\n\n- [createDfuseClient](https://dfuse-io.github.io/client-js/globals.html#createdfuseclient)\n\n##### Interfaces\n\n- [DfuseClient](https://dfuse-io.github.io/client-js/interfaces/dfuseclient.html)\n- [StreamClient](https://dfuse-io.github.io/client-js/interfaces/streamclient.html)\n- [Stream](https://dfuse-io.github.io/client-js/interfaces/stream.html)\n- [HttpClient](https://dfuse-io.github.io/client-js/interfaces/httpclient.html)\n- [Socket](https://dfuse-io.github.io/client-js/interfaces/socket.html)\n- [ApiTokenStore](https://dfuse-io.github.io/client-js/interfaces/apitokenstore.html)\n\n##### Options\n\n- [DfuseClientOptions](https://dfuse-io.github.io/client-js/interfaces/dfuseclientoptions.html)\n- [StreamClientOptions](https://dfuse-io.github.io/client-js/interfaces/streamclientoptions.html)\n- [HttpClientOptions](https://dfuse-io.github.io/client-js/interfaces/httpclientoptions.html)\n- [SocketOptions](https://dfuse-io.github.io/client-js/interfaces/socketoptions.html)\n\n##### Implementations\n\n- [DefaultClient](https://dfuse-io.github.io/client-js/classes/defaultclient.html)\n- [LocalStorageApiTokenStore](https://dfuse-io.github.io/client-js/classes/localstorageapitokenstore.html)\n- [OnDiskApiTokenStore](https://dfuse-io.github.io/client-js/classes/ondiskapitokenstore.html)\n- [FileApiTokenStore](https://dfuse-io.github.io/client-js/classes/fileapitokenstore.html)\n- [InMemoryApiTokenStore](https://dfuse-io.github.io/client-js/classes/inmemoryapitokenstore.html)\n\n**Note** `DefaultStreamClient`, `DefaultHttpClient`, `DefaultSocket`, `DefaultApiTokenManager`\nare all private implementations not exposed.\n\n### Examples\n\n**Note** You can run the examples straight from this repository quite easily. Clone it to\nyou computer, run `yarn install \u0026\u0026 yarn build` in the project directory. Link the local\nbuild so it's usable by the examples:\n\n    yarn link               # Adds a symlink of this project to your global installation\n    yarn link @dfuse/client # Adds `@dfuse/client` in this project's `node_modules` folder (global symlink)\n\nEnsures you have an environment variable `DFUSE_API_KEY` set to your dfuse API Key value.\nThen simply issue the following command (pick the example file you want to run):\n\n    yarn run:example examples/basic/eosio/stream-transfers-graphql.ts\n\n#### Browser Example\n\nFor the browser example to work, you need to edit the `browser.html` file:\n\n- Edit the `browser.html` file to put your own API key, search for `apiKey: \"\u003cPaste API key here!\u003e\",` in the file.\n\nOnce this is done, simply double-click on the `browser.html` file (`open examples/reference/browser.html` on Unix/Mac system).\n\n#### Basic\n\nThese are the starter examples showing a concrete use case you can solve using `@dfuse/client`\nlibrary. Those toy examples have low to no error handling, check the [Advanced section](#advanced)\nfor production grade details on efficiently use `@dfuse/client`\n\n##### EOSIO\n\n- [GraphQL Stream Transfers (Query)](./examples/basic/eosio/stream-transfers-graphql.ts)\n- [GraphQL Search Your Latest Transactions (Subscription)](./examples/basic/eosio/search-your-latest-transactions-graphql.ts)\n\n- [REST Check Balance (delta between fixed block and now)](./examples/basic/eosio/state-check-balance.ts)\n- [REST Search Your Latest Transactions](./examples/basic/eosio/search-your-latest-transactions.ts)\n- [WebSocket Stream Transfers](./examples/basic/eosio/stream-transfers-ws.ts)\n- [WebSocket Stream Global State](./examples/basic/eosio/stream-global-state-ws.ts)\n\n- [dfuse for EOSIO](./examples/basic/eosio/dfuse-for-eosio.ts)\n- [dfuse Community Edition (EOSIO)](./examples/basic/eosio/dfuse-community-edition.ts)\n\n##### Ethereum\n\n- [GraphQL Stream Transfers](./examples/basic/ethereum/stream-transfers.ts)\n- [GraphQL Search Your Latest Transactions](./examples/basic/ethereum/search-your-latest-transactions.ts)\n- [GraphQL Stream Transactions](./examples/basic/ethereum/stream-transactions.ts)\n\n#### Advanced\n\nYou will find examples leveraging the full power library with all the correct patterns to\nconsume the Blockchain data efficiently, with strict data integrity and how to properly\ndeal with error and edge cases (like micro-forks!).\n\n##### Common\n\nThose are examples that are general concepts applicable to all chains we support or\nabout some specifities of the `client-js` library like configuring the WebSocket\nconnection or the behavior of the client instance itself.\n\n- [Client \u0026 Socket Notifications - Looking at all events generated by the library](./examples/advanced/common/client-and-socket-notifications.ts)\n- [Forever Stream - Always stay connected to dfuse Stream](./examples/advanced/common/forever-streaming.ts)\n- [Multiple Active Streams - Connects multiple dfuse Streams at the same time](./examples/advanced/common/multiple-active-streams.ts)\n- [Navigating Forks - Dealing with undo/redo steps](./examples/advanced/common/navigating-forks.ts)\n- [GraphQL Never Miss a Beat - Ensuring consistent data integrity](./examples/advanced/common/graphql-never-miss-a-beat.ts)\n- [Never Miss a Beat - Ensuring consistent data integrity](./examples/advanced/common/never-miss-a-beat.ts)\n- [Node.js HTTP \u0026 WebSocket Configuration - Avoid polluting the global scope and customizing WebSocket client](./examples/advanced/common/nodejs-fetch-and-websocket-options.ts)\n- [GraphQL - Use 'gql' tag \u0026 Typings](./examples/advanced/common/graphql-gql-tag.ts)\n\n##### EOSIO\n\n- [Has Account - Quickest way to have a method to check if an account exists on the chain](./examples/advanced/eosio/has-account.ts)\n- [Track RAM Usage - Or how to use the search cursor to fetch next results](./examples/advanced/eosio/track-ram-usage.ts)\n- [Stream Irreversible Events Only - Avoiding dealing with micro-forks (non-live)](./examples/advanced/eosio/stream-only-irreversible-events.ts)\n\n#### Reference\n\nIn this folder, you will get full reference examples. Those are used to showcase the actual full data\nyou receive with each call. It's also there where you can check the flow of messages that can be handled\nin each dfuse Stream and full configuration options for the library itself and all the API calls.\n\n##### Common\n\n- [auth-issue.ts](./examples/reference/common/auth-issue.ts)\n- [api-request.ts](./examples/reference/common/api-request.ts)\n- [browser.html (Showcase Browser using UMD build)](./examples/reference/common/browser.html)\n\n##### EOSIO (REST API)\n\n- [fetch-block-id-by-time.ts](./examples/reference/eosio/fetch-block-id-by-time.ts)\n- [fetch-transaction.ts](./examples/reference/eosio/fetch-transaction.ts)\n- [search-transactions.ts](./examples/reference/eosio/search-transactions.ts)\n- [state-abi-bin-to-json.ts](./examples/reference/eosio/state-abi-bin-to-json.ts)\n- [state-abi.ts](./examples/reference/eosio/state-abi.ts)\n- [state-key-accounts.ts](./examples/reference/eosio/state-key-accounts.ts)\n- [state-permission-links.ts](./examples/reference/eosio/state-permission-links.ts)\n- [state-table-scopes.ts](./examples/reference/eosio/state-table-scopes.ts)\n- [state-table.ts](./examples/reference/eosio/state-table.ts)\n- [state-tables-for-accounts.ts](./examples/reference/eosio/state-tables-for-accounts.ts)\n- [state-tables-for-scopes.ts](./examples/reference/eosio/state-tables-for-scopes.ts)\n\n##### EOSIO (WebSocket API)\n\n- [stream-action-traces.ts](./examples/reference/eosio/stream-action-traces.ts)\n- [stream-head-info.ts](./examples/reference/eosio/stream-head-info.ts)\n- [stream-table-rows.ts](./examples/reference/eosio/stream-table-rows.ts)\n- [stream-transaction.ts](./examples/reference/eosio/stream-transaction.ts)\n\n##### Ethereum (GraphQL API)\n\n- [stream-pending-transactions.ts](./examples/reference/ethereum/stream-pending-transactions.ts)\n\n## Development\n\nThe best way to develop this library is through modifying and adding examples\nto the project.\n\nTo run the examples, it's quite simple, follow these instructions:\n\n1.  Install project dependencies so that you get development tools at the same time:\n\n    ```\n    yarn install\n    ```\n\n1.  Link the project inside itself, that will be necessary to correct run the\n    examples which import `@dfuse/client`:\n\n    ```\n    yarn link\n    yarn link @dfuse/client\n    ```\n\n1.  Start the build watcher so distribution files are always up-to-date. Forgetting\n    to do that will prevent examples from picking latest changes you've made to\n    source files!\n\n    ```\n    yarn start\n    ```\n\n1.  Last step is to add `.env` file containing the [dfuse](https://dfuse.io) API key\n    required to run the examples. Create a file `.env` at the root of the project\n    with the following content:\n\n    ```\n    DFUSE_API_KEY=Replace this with API key!\n    ```\n\n1.  Final check, let's run an example to ensure everything is working:\n\n    ```\n    yarn run:example examples/basic/eosio/state-check-balance.ts\n    ```\n\n### Publishing\n\nFirst step is to update the change log ([CHANGELOG.md](./CHANGELOG.md)) by updating the\n`## In Progress` header to change to `## \u003cVersion\u003e (\u003cMonth\u003e \u003cDay\u003e, \u003cYear\u003e)` (i.e. `## 0.11.11 (March 26, 2019)`)\nand the commit that.\n\nAssuming you have been granted access rights to publish this package, the command to perform is simply:\n\n    yarn run publish:latest\n\nThis command will automatically perform a clean build followed by the execution of the full test\nsuite then a publish the package followed by a publish of the docs and finally push the commits\nand tag to the remote repository.\n\n#### Pre-release\n\nIf you want to publish a pre-release version not flagged as the latest so that people still pulls\nthe current stable version unless they opt-in explicitly, use the following invocation:\n\n    yarn run publish:next\n\nDoes the same work as `publish:latest` but the docs is not published by this step.\n\n## Credits / Acknowledgement\n\nA big thanks (and hug) to our dear friend [Denis Carriere](https://github.com/DenisCarriere) from\n[EOS Nation](https://eosnation.io) for creating the initial version of this project.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdfuse-io%2Fclient-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdfuse-io%2Fclient-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdfuse-io%2Fclient-js/lists"}