@absinthe/socket 中文文档教程

发布于 6年前 浏览 27 项目主页 更新于 3年前

@absinthe/socket

Absinthe Socket

Features

  • Immutable functional API > All received and returned objects with the exception of AbsintheSocket > instances (there are plans to make this immutable too) are treated in an > immutable way. Objects have no methods and instead we provide independant > stateless functions to interact with them.
  • Lazy connect / join > If provided phoenix socket instance is not connected, then instead of > connecting at creation time, connection will be established on the next > invocation of send.
  • Handle pending operations on connection lost > Pending mutations will be aborted, queries will be resent, and subscriptions > reestablished.
  • Cancellable requests > Calling cancel removes given notifier from absintheSocket instance > and sends a Cancel event to all its observers and unsubscribes in case it > holds a subscription request.
  • Operations deduplication > If an already sent request is given to send, then instead of sending > it again, the notifier associated with it will be returned.
  • Observer support of recoverable errors > Since connection lost is handled, then two events needs to exist to represent > this fact: Error (recoverable), Abort (unrecoverable).
  • Multiple observers per request > Calling send returns a notifier which allows attaching any number of > observers that will be notified when result arrives.
  • Observer interaction depending on operation type > For the case of subscriptions, Start event is dispatched when the > subscription is established, while for the other types > (queries and mutations), when the request is sent.

Installation

Using npm

$ npm install --save phoenix @absinthe/socket

Using yarn

$ yarn add phoenix @absinthe/socket

Types

type RequestStatus = "canceled" | "canceling" | "pending" | "sent" | "sending";

// from @jumpn/utils-graphql
type GqlRequest<Variables: void | Object = void> = {
  operation: string,
  variables?: Variables
};

// from @jumpn/utils-graphql
type GqlResponse<Data> = {
  data?: Data,
  errors?: Array<GqlError>
};

// from @jumpn/utils-graphql
type GqlOperationType = "mutation" | "query" | "subscription";

type Observer<Result, Variables: void | Object = void> = {|
  onAbort?: (error: Error) => any,
  onCancel?: () => any,
  onError?: (error: Error) => any,
  onStart?: (notifier: Notifier<Result, Variables>) => any,
  onResult?: (result: Result) => any
|};

type Notifier<Result, Variables: void | Object = void> = {|
  activeObservers: $ReadOnlyArray<Observer<Result, Variables>>,
  canceledObservers: $ReadOnlyArray<Observer<Result, Variables>>,
  isActive: boolean,
  operationType: GqlOperationType,
  request: GqlRequest<Variables>,
  requestStatus: RequestStatus,
  subscriptionId?: string
|};

type AbsintheSocket = {|
  channel: Channel,
  channelJoinCreated: boolean,
  notifiers: Array<Notifier<any>>,
  phoenixSocket: PhoenixSocket
|};

API

cancel

取消通知器向其所有观察者发送 Cancel 事件,并且 如果它持有订阅请求则取消订阅

Parameters

  • absintheSocket AbsintheSocket
  • notifier Notifier<any, any>

Examples

import * as withAbsintheSocket from "@absinthe/socket";

withAbsintheSocket.cancel(absintheSocket, notifier);

>AbsintheSocket

create

给定的 Phoenix Socket 实例创建一个 Absinthe Socket

Parameters

  • phoenixSocket PhoenixSocket

Examples

import * as withAbsintheSocket from "@absinthe/socket";
import {Socket as PhoenixSocket} from "phoenix";

const absintheSocket = withAbsintheSocket.create(
  new PhoenixSocket("ws://localhost:4000/socket")
);

< strong

observe

使用

Parameters

  • absintheSocket AbsintheSocket
  • notifier Notifier<Result, Variables>
  • observer Observer<Result, Variables>

Examples

import * as withAbsintheSocket from "@absinthe/socket"

const logEvent = eventName => (...args) => console.log(eventName, ...args);

const updatedNotifier = withAbsintheSocket.observe(absintheSocket, notifier, {
  onAbort: logEvent("abort"),
  onError: logEvent("error"),
  onStart: logEvent("open"),
  onResult: logEvent("result")
});

send

返回 (通知程序)跟踪其进度 (参见 observe 函数)

Parameters

  • absintheSocket AbsintheSocket
  • request GqlRequest<Variables>

Examples

import * as withAbsintheSocket from "@absinthe/socket";

const operation = `
  subscription userSubscription($userId: ID!) {
    user(userId: $userId) {
      id
      name
    }
  }
`;

// This example uses a subscription, but the functionallity is the same for
// all operation types (queries, mutations and subscriptions)

const notifier = withAbsintheSocket.send(absintheSocket, {
  operation,
  variables: {userId: 10}
});

返回 Notifier

toObservable

创建一个将遵循给定通知程序的 Observable

Parameters

  • absintheSocket AbsintheSocket
  • notifier Notifier<Result, Variables>
  • options Object? (optional, default {})
    • options.unsubscribe function (): undefined?
    • options.onError function (error: Error): undefined?
    • options.onStart function (notifier: Notifier<Result, Variables>): undefined?
    • options.handlers …any

Examples

import * as withAbsintheSocket from "@absinthe/socket";

const unobserveOrCancelIfNeeded = (absintheSocket, notifier, observer) => {
  if (notifier && observer) {
    withAbsintheSocket.unobserveOrCancel(absintheSocket, notifier, observer);
  }
};

const logEvent = eventName => (...args) => console.log(eventName, ...args);

const observable = withAbsintheSocket.toObservable(absintheSocket, notifier, {
  onError: logEvent("error"),
  onStart: logEvent("open"),
  unsubscribe: unobserveOrCancelIfNeeded
});

返回 Observable

unobserve

分离观察者

Parameters

  • absintheSocket AbsintheSocket
  • notifier Notifier<any, any>
  • observer Observer<any, any>

Examples

import * as withAbsintheSocket from "@absinthe/socket";

withAbsintheSocket.unobserve(absintheSocket, notifier, observer);

从通知程序中

unobserveOrCancel

如果除了给定的观察者之外没有其他观察者,则取消通知程序,或者 将给定的观察者与通知者分离,否则

Parameters

  • absintheSocket AbsintheSocket
  • notifier Notifier<Result, Variables>
  • observer Observer<Result, Variables>

Examples

import * as withAbsintheSocket from "@absinthe/socket";

withAbsintheSocket.unobserve(absintheSocket, notifier, observer);

License

MIT :copyright: Jumpn Limited。

@absinthe/socket

Absinthe Socket

Features

  • Immutable functional API > All received and returned objects with the exception of AbsintheSocket > instances (there are plans to make this immutable too) are treated in an > immutable way. Objects have no methods and instead we provide independant > stateless functions to interact with them.
  • Lazy connect / join > If provided phoenix socket instance is not connected, then instead of > connecting at creation time, connection will be established on the next > invocation of send.
  • Handle pending operations on connection lost > Pending mutations will be aborted, queries will be resent, and subscriptions > reestablished.
  • Cancellable requests > Calling cancel removes given notifier from absintheSocket instance > and sends a Cancel event to all its observers and unsubscribes in case it > holds a subscription request.
  • Operations deduplication > If an already sent request is given to send, then instead of sending > it again, the notifier associated with it will be returned.
  • Observer support of recoverable errors > Since connection lost is handled, then two events needs to exist to represent > this fact: Error (recoverable), Abort (unrecoverable).
  • Multiple observers per request > Calling send returns a notifier which allows attaching any number of > observers that will be notified when result arrives.
  • Observer interaction depending on operation type > For the case of subscriptions, Start event is dispatched when the > subscription is established, while for the other types > (queries and mutations), when the request is sent.

Installation

Using npm

$ npm install --save phoenix @absinthe/socket

Using yarn

$ yarn add phoenix @absinthe/socket

Types

type RequestStatus = "canceled" | "canceling" | "pending" | "sent" | "sending";

// from @jumpn/utils-graphql
type GqlRequest<Variables: void | Object = void> = {
  operation: string,
  variables?: Variables
};

// from @jumpn/utils-graphql
type GqlResponse<Data> = {
  data?: Data,
  errors?: Array<GqlError>
};

// from @jumpn/utils-graphql
type GqlOperationType = "mutation" | "query" | "subscription";

type Observer<Result, Variables: void | Object = void> = {|
  onAbort?: (error: Error) => any,
  onCancel?: () => any,
  onError?: (error: Error) => any,
  onStart?: (notifier: Notifier<Result, Variables>) => any,
  onResult?: (result: Result) => any
|};

type Notifier<Result, Variables: void | Object = void> = {|
  activeObservers: $ReadOnlyArray<Observer<Result, Variables>>,
  canceledObservers: $ReadOnlyArray<Observer<Result, Variables>>,
  isActive: boolean,
  operationType: GqlOperationType,
  request: GqlRequest<Variables>,
  requestStatus: RequestStatus,
  subscriptionId?: string
|};

type AbsintheSocket = {|
  channel: Channel,
  channelJoinCreated: boolean,
  notifiers: Array<Notifier<any>>,
  phoenixSocket: PhoenixSocket
|};

API

cancel

Cancels a notifier sending a Cancel event to all its observers and unsubscribing in case it holds a subscription request

Parameters

  • absintheSocket AbsintheSocket
  • notifier Notifier<any, any>

Examples

import * as withAbsintheSocket from "@absinthe/socket";

withAbsintheSocket.cancel(absintheSocket, notifier);

Returns AbsintheSocket

create

Creates an Absinthe Socket using the given Phoenix Socket instance

Parameters

  • phoenixSocket PhoenixSocket

Examples

import * as withAbsintheSocket from "@absinthe/socket";
import {Socket as PhoenixSocket} from "phoenix";

const absintheSocket = withAbsintheSocket.create(
  new PhoenixSocket("ws://localhost:4000/socket")
);

Returns AbsintheSocket

observe

Observes given notifier using the provided observer

Parameters

  • absintheSocket AbsintheSocket
  • notifier Notifier<Result, Variables>
  • observer Observer<Result, Variables>

Examples

import * as withAbsintheSocket from "@absinthe/socket"

const logEvent = eventName => (...args) => console.log(eventName, ...args);

const updatedNotifier = withAbsintheSocket.observe(absintheSocket, notifier, {
  onAbort: logEvent("abort"),
  onError: logEvent("error"),
  onStart: logEvent("open"),
  onResult: logEvent("result")
});

send

Sends given request and returns an object (notifier) to track its progress (see observe function)

Parameters

  • absintheSocket AbsintheSocket
  • request GqlRequest<Variables>

Examples

import * as withAbsintheSocket from "@absinthe/socket";

const operation = `
  subscription userSubscription($userId: ID!) {
    user(userId: $userId) {
      id
      name
    }
  }
`;

// This example uses a subscription, but the functionallity is the same for
// all operation types (queries, mutations and subscriptions)

const notifier = withAbsintheSocket.send(absintheSocket, {
  operation,
  variables: {userId: 10}
});

Returns Notifier<Result, Variables>

toObservable

Creates an Observable that will follow the given notifier

Parameters

  • absintheSocket AbsintheSocket
  • notifier Notifier<Result, Variables>
  • options Object? (optional, default {})
    • options.unsubscribe function (): undefined?
    • options.onError function (error: Error): undefined?
    • options.onStart function (notifier: Notifier<Result, Variables>): undefined?
    • options.handlers …any

Examples

import * as withAbsintheSocket from "@absinthe/socket";

const unobserveOrCancelIfNeeded = (absintheSocket, notifier, observer) => {
  if (notifier && observer) {
    withAbsintheSocket.unobserveOrCancel(absintheSocket, notifier, observer);
  }
};

const logEvent = eventName => (...args) => console.log(eventName, ...args);

const observable = withAbsintheSocket.toObservable(absintheSocket, notifier, {
  onError: logEvent("error"),
  onStart: logEvent("open"),
  unsubscribe: unobserveOrCancelIfNeeded
});

Returns Observable

unobserve

Detaches observer from notifier

Parameters

  • absintheSocket AbsintheSocket
  • notifier Notifier<any, any>
  • observer Observer<any, any>

Examples

import * as withAbsintheSocket from "@absinthe/socket";

withAbsintheSocket.unobserve(absintheSocket, notifier, observer);

Returns AbsintheSocket

unobserveOrCancel

Cancels notifier if there are no more observers apart from the one given, or detaches given observer from notifier otherwise

Parameters

  • absintheSocket AbsintheSocket
  • notifier Notifier<Result, Variables>
  • observer Observer<Result, Variables>

Examples

import * as withAbsintheSocket from "@absinthe/socket";

withAbsintheSocket.unobserve(absintheSocket, notifier, observer);

License

MIT :copyright: Jumpn Limited.

    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
    原文