dfuse JavaScript/ TypeScript 客户端库

一个 GraphQL, WebSocket 和 HTTP REST 客户端库, 以消耗 dfuse API https://dfuse.io (英语) (单位:千美元)文档) (中文(简体) ).

安装

使用 Yarn :

yarn add @dfuse/client

# Use this command if you are using npm
#npm install --save @dfuse/client

特征

你用这个图书馆得到什么

• API 完全覆盖 dfuse( GraphQL, REST & WebSocket)
• API 密码 库存发放和管理(自动更新、过期处理、储存等)
• 套接字关闭时自动重新连接
• 在插座重新连接的最后一个标记位置进行流程进度管理和自动启动
• 完全定制电源

快速启动

通知 您应该替换字符序列 Paste your API key here 与您从上面的脚本中获取的实际 API 密钥 https://app.dfuse.io (英语)。你会 连接到 EOSIO 实例的本地 dfuse 或 dfuse 社区版 ? 替换 apiKey: "<Paste your API key here>" 与 authentication: false 所以认证是 已禁用.

埃奥西奥

见 实例/基本/eosio/流-传输-graphl.ts

const { createDfuseClient } = require("@dfuse/client")
const client = createDfuseClient({
  apiKey: "<Paste your API key here>",
  network: "mainnet.eos.dfuse.io",
})

const streamTransfer = `subscription($cursor: String!) {
  searchTransactionsForward(query: "receiver:eosio.token action:transfer -data.quantity:'0.0001 EOS'", cursor: $cursor) {
    undo cursor
    trace {
      matchingActions { json }
    }
  }
}`

await client.graphql(streamTransfer, (message, stream) => {
  if (message.type === "error") {
    console.log("An error occurred", message.errors, message.terminal)
  }

  if (message.type === "data") {
    const data = message.data.searchTransactionsForward
    const actions = data.trace.matchingActions

    actions.forEach(({ json }: any) => {
      const { from, to, quantity, memo } = json
      console.log(`Transfer [${from} -> ${to}, ${quantity}] (${memo})`)
    })

    stream.mark({ cursor: data.cursor })
  }

  if (message.type === "complete") {
    console.log("Stream completed")
  }
})

以利亚

见 实例/基本/结果/流转.ts

const { createDfuseClient } = require("@dfuse/client")

const streamTransfer = `subscription($cursor: String) {
  searchTransactions(query: "method:'transfer(address,uint256)'", cursor: $cursor) {
    undo cursor
    node { hash from to value(encoding: ETHER) }
  }
}`

await client.graphql(streamTransfer, (message, stream) => {
  if (message.type === "error") {
    console.log("An error occurred", message.errors, message.terminal)
  }

  if (message.type === "data") {
    const { cursor, node } = message.data.searchTransactions
    console.log(`Transfer [${node.from} -> ${node.to}, ${node.value}]`)

    stream.mark({ cursor })
  }

  if (message.type === "complete") {
    console.log("Stream completed")
  }
})

节点.js

如果你瞄准一个 Node.js 相反,你需要带来一个 fetch 兼容 函数和正则 WebSocket 客户端.

您可自由使用符合相应要求的相容图书馆。 改为: 简单点,如果 fetch 和(或) WebSocket 在全球范围内提供global, (中文(简体) ), 由图书馆自动选择。 虽然污染全球范围,但它是 最容易开始的方法.

这是这个项目中的例子 分别使用 节点比对 财务报告和审定财务报表 财务报告和审定财务报表 负 页:1 fetch 财务报告和审定财务报表 WebSocket 页:1.

使用Yarn的安装指令是:

yarn add node-fetch ws

在您申请的护靴阶段, 在做任何 @dfuse/client 进口/需求, 设置以下代码:

global.fetch = require("node-fetch");
global.WebSocket = require("ws");

你可以检查 节点.js 配置 例如,如何避免污染全球范围.

模拟默认

库会对某些依赖性做出正常的默认假设 图书馆需要。 本节详述我们认为是 最重要的东西.

获取

图书馆要求 Fetch 像接口。 在浏览器环境中, 这是 fetch 使用的函数( 我们检查 window.fetch 实值 a 函数).

若为 window.fetch 未定义, 我们退后检查 global.fetch 变量. 这可以设置在一个节点.js环境中,以指向兼容的执行 联 合 国 fetch,就像一个由 节点比对 软件包.

如果没有提供,则库会出错。 为了避免这个错误,你应该通过 页:1 httpClientOptions.fetch 选项,用于创建 dfuse 客户端.

可在封面下使用任何 HTTP 库类 轴 甚至是 XMLHttpRequest 如果你愿意的话.

网络安全套

图书馆要求 WebSocket 具有相同语义的客户端界面 作为浏览器环境中的 WebSocket API.

在浏览器环境中,这是标准 WebSocket 使用的变量 (我们检查一下) window.WebSocket 页:1.

若为 window.WebSocket 未定义, 我们退后检查 global.WebSocket 变量. 这可以设置在一个节点.js环境中,以指向兼容的执行 联 合 国 WebSocket 客户端,就像由 负 软件包.

如果没有提供,则库会出错。 为了避免这个错误,你应该通过 页:1 streamClientOptions.socketOptions.webSocketFactory 编辑 graphqlStreamClientOptions.socketOptions.webSocketFactory 创建 dfuse 时选项 客户端. 这个工厂的方法接收到连接到远程端点的完整url (这将包括用于url查询参数的 API 令牌) 并应 返回一个有效的 WebSocket 客户端对象.

我们强烈建议使用 负 软件包正中 节点.js环境.

API 托肯存储器

API 令牌存储界面被 dfuse 客户端用于执行 持续检索和写入 API 令牌 。 我们确是受限的 aPI 令牌发行端点 因此 高级 重要事项 重新使用有效的符号,而不是每次生成一个新的符号 以避免击中 API 令牌发行利率限制器.

图书馆,没有的时候 apiTokenStore 选项传递给客户端 选择默认 ApiTokenStore 根据您所处的环境执行.

在浏览器环境中,所使用的具体执行是: 本地图集ApiTokenStore 课。 这将保存并取回浏览器上的令牌 localStorage (a项下) dfuse:token ) (中文(简体) ).

在节点环境中,所使用的具体执行是: 在 DiskApiToken 斯托尔 上 课. 这将保存并取回磁盘上本地文件上的令牌 时间 ~/.dfuse/<sha256-api-key>/token.info。 。 。 .

说明 根据部署目标(Docker, VM 等),可能 该主目录( e)~无法写入, 导致默认值 在 DiskApiToken 斯托尔 上 例如,在Node.js环境中无法正确工作。 在这种情况下,简单地界定 自己来 apiTokenStore 实例来使用和选择符号的位置 应该保存。 证明a 文件目录 实例并用作 apiTokenStore 即时配置值 dfuse 客户端 :

import { createDfuseClient, FileApiTokenStore } from "@dfuse/client";

const client = createDfuseClient({
  ...,
  apiTokenStore: new FileApiTokenStore("/tmp/dfuse-token.json"),
  ...,
});

API 密码

API 的全部参考文献可见于 https://dfuse-io.github.io/client-js/ 互联网档案馆的存檔,存档日期2013-12-11。 。 。 .

此站点是通过运行生成的 typedoc 。在此仓库上。 整个API 这里有一个快速指数,指向 重要实体的文献部分应读取理解 图书馆的各个部分:

工厂

• 创建 Dfuse 客户端

接口

• Dfuse 客户端
• 流线
• 流线
• Http 客户端
• 套接字
• 阿皮托肯斯托尔

选项

• Dfuseclient 选项
• 流式选择
• Httpclient 选项
• 套接字选项

执行情况

• 默认客户端
• 本地图集ApiTokenStore
• 在 DiskApiToken 斯托尔 上
• 文件目录
• 在记忆中的 ApiTokenStore

说明 DefaultStreamClient, (中文(简体) ), DefaultHttpClient, (中文(简体) ), DefaultSocket, (中文(简体) ), DefaultApiTokenManager 所有私人执行都没有曝光.

实例

说明 你可以非常容易地从这个仓库中直接运行实例。 把它砍下来 电脑,运行 yarn install && yarn build 在项目目录中。 连接当地 因此,它被实例所使用:

yarn link               # Adds a symlink of this project to your global installation
yarn link @dfuse/client # Adds `@dfuse/client` in this project's `node_modules` folder (global symlink)

确保您有一个环境变量 DFUSE_API_KEY 设置到您的 dfuse API 密钥值. 然后简单地发布以下命令( 选择您想要运行的示例文件) :

yarn run:example examples/basic/eosio/stream-transfers-graphql.ts

浏览器示例

浏览器实例要工作,需要编辑 browser.html 文件 :

• 编辑 browser.html 设置您自己的 API 密钥的文件, 查找 apiKey: "<Paste API key here!>", 在文件中.

完成后,只需双击 browser.html 文件( 编号open examples/reference/browser.html 关于Unix/Mac系统.

基础

这些是启动实例, 显示您可以使用的具体用途 @dfuse/client 图书馆。 这些玩具实例有低到没有错误处理, 请检查 高级部分 关于高效使用的生产级别详情 @dfuse/client

埃奥西奥

• 图QL 流转( 查询)

• 图QL 搜索您的最新交易( 订阅)

• REST 检查余额(固定区块与现在之间)

• REST 搜索您的最新交易

• WebSocket 串流传输

• WebSocket流全球状态

• 用于 EOSIO

• dfuse 社区版(EOSIO)

以利亚

• 图QL 流转
• GraphQL 搜索您的最近交易
• 图QL 流式交易

高级

您可以找到一些实例, 以所有正确的模式来利用全电源库 高效地消耗区链数据,严格数据完整性以及如何正确使用 处理出错和边缘大小写( 如微叉 !) .

常见

这些例子都是适用于我们支持的所有链条的一般概念,或 有关《公约》某些特定 client-js 类似配置 WebSocket 的库 连接或客户端实例本身的行为.

• 客户端 & Socket 通知 - 查看库生成的所有事件
• 永远流出 - 总是与 dfuse 流相接
• 多个活性流 - 同时连接多个 dfuse 流
• 导航叉 - 处理取消/重做步骤
• GraphQL 永不错过一击-确保数据一致性
• 永不错过一击-确保数据一致性
• 节点.js HTTP & WebSocket配置 - 避免污染全球范围并自定义WebSocket客户端
• 图表QL - 使用“ gql” 标记和打字

埃奥西奥

• Has Accounts - 快速检查链上是否存在账户的方法
• 音轨内存使用法 - 或如何使用搜索光标获取下一个结果
• 流出可逆事件- 避免处理微分叉( 非活性)

参考文献

在此文件夹中, 您将获得全部参考示例 。 用来展示实际的全部数据 你每通电话都会收到 也可以在那里检查可以处理的信息流 在每个 dfuse Stream 和 库本身的全部配置选项以及所有 API 调用.

常见

• 认证问题
• api- request.ts (英语)
• 浏览器.html(使用 UMD 构建的显示器浏览器)

EOSIO (REST API) (英语)

• 逐时取取块
• 获取- 交易. ts
• 搜索交易( t)
• 州比宾至杰森州
• 州级
• 国家钥匙账户
• 州-授权链接.ts
• 状态表范围( t)
• 状态表.ts
• 国家会计表
• 状态表表示范围

EOSIO (WebSocket API) (中文(简体) )

• 流-动作-追踪.ts
• 流头- info.ts
• 流表行数
• 流-交易.ts

伊特鲁姆语( GraphQL API)

• 流出-待决-交易ts

发展

开发这个库的最佳方法是修改和增加实例 到项目.

举例来说,很简单,遵循这些指示:

1. 安装项目依赖性, 以便您同时获得开发工具 :

   yarn install
   

2. 将项目内部连接起来,这是纠正运行所必需的 导入示例 @dfuse/client数字 :

   yarn link
   yarn link @dfuse/client
   

3. 启动构建监视器, 这样分发文件总是最新的 。 忘记 这样做将防止实例选择你最近所做的改变 来源文件!

   yarn start
   

4. 最后一个步骤是添加 .env 文件包含 调和 API 密钥 用于运行示例。 创建文件 .env 在项目根部 内容如下:

   DFUSE_API_KEY=Replace this with API key!
   

5. 最后检查一下 让我们举个例子 确保一切正常

   yarn run:example examples/basic/eosio/state-check-balance.ts
   

出版

第一步是更新更改日志(变动情况),通过更新 ## In Progress 要更改为 ## <Version> (<Month> <Day>, <Year>) (即说. ## 0.11.11 (March 26, 2019)(中文(简体) ) 和承诺.

假设您已经获得发布此软件包的访问权限,执行的命令只是:

yarn run publish:latest

此命令将自动执行一个干净的构建, 然后执行全测试 套件,然后是出版软件包,然后是出版文件,最后推动承诺 并标记到远程仓库.

释放前

如果您想要发布一个未标为最新版本的预发版本, 这样人们仍然拉 目前的稳定版本,除非它们明确选择使用,请使用下列引用:

yarn run publish:next

是否与 publish:latest 但此步骤不会公布文件.

贷记/鸣谢

感谢(并拥抱)我们亲爱的朋友 丹尼斯·卡丽尔 从 EOS 国家 用于创建此工程的初始版本.

许可证

麻省理工学院