@absinthe/socket 中文文档教程
@absinthe/socket
Absinthe Socket
- Features
- Installation
- Using npm
- Using yarn
- Types
- API
- cancel
- create
- observe
- send
- toObservable
- unobserve
- unobserveOrCancel
- License
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
AbsintheSocketnotifier
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
AbsintheSocketnotifier
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
AbsintheSocketrequest
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
AbsintheSocketnotifier
Notifier<Result, Variables>options
Object? (optional, default{}
)
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
AbsintheSocketnotifier
Notifier<any, any>observer
Observer<any, any>
Examples
import * as withAbsintheSocket from "@absinthe/socket";
withAbsintheSocket.unobserve(absintheSocket, notifier, observer);
从通知程序中
unobserveOrCancel
如果除了给定的观察者之外没有其他观察者,则取消通知程序,或者 将给定的观察者与通知者分离,否则
Parameters
absintheSocket
AbsintheSocketnotifier
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
- Installation
- Using npm
- Using yarn
- Types
- API
- cancel
- create
- observe
- send
- toObservable
- unobserve
- unobserveOrCancel
- License
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
AbsintheSocketnotifier
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
AbsintheSocketnotifier
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
AbsintheSocketrequest
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
AbsintheSocketnotifier
Notifier<Result, Variables>options
Object? (optional, default{}
)
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
AbsintheSocketnotifier
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
AbsintheSocketnotifier
Notifier<Result, Variables>observer
Observer<Result, Variables>
Examples
import * as withAbsintheSocket from "@absinthe/socket";
withAbsintheSocket.unobserve(absintheSocket, notifier, observer);
License
MIT :copyright: Jumpn Limited.