@adonisjs/transmit-client 0.1.6 → 0.2.1

package/README.md

@@ -35,10 +35,10 @@ AdonisJS Transmit Client is a client for the native Server-Sent-Event (SSE) modu
 
   - [Installation](#installation)
   - [Usage](#usage)
-  - [Subscribing to channels](#subscribing-to-channels)
+  - [Creating a subscription](#creating-a-subscription)
+    - [Unsubscribing](#unsubscribing)
     - [Subscription Request](#subscription-request)
     - [Reconnecting](#reconnecting)
-    - [Unsubscribing](#unsubscribing)
 - [Events](#events)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -49,12 +49,6 @@ Install the package from the npm registry as follows:
 
 ```sh
 npm i @adonisjs/transmit-client
-
-# yarn
-yarn add @adonisjs/transmit-client
-
-# pnpm
-pnpm add @adonisjs/transmit-client
 ```
 
 ## Usage
@@ -69,63 +63,44 @@ const transmit = new Transmit({
 })
 ```
 
-## Subscribing to channels
+## Creating a subscription
 
-The `listenOn` method accepts the channel name and a callback to be invoked when the event is received from the server.
+The `subscription` method is used to create a subscription to a channel. The method accepts the channel name
 
 ```ts
-transmit.listenOn<{ message: string }>('chat/1', (payload) => {
-  console.log(payload.message)
-})
+const subscription = transmit.subscription('chat/1')
 ```
 
-You can also listen from a channel only once.
+Then, you have to call the `create` method on the subscription to register it on the backend.
 
 ```ts
-transmit.listenOnce<{ message: string }>('chat/1', () => {
-  console.log('first message received!')
-})
+await subscription.create()
 ```
 
-### Subscription Request
-
-You can alter the subscription request by using the `beforeSubscribe` or `beforeUnsubscribe` options.
+You can listen for events on the channel using the `onMessage` method. You can define as many listeners as you want on the same subscription.
 
 ```ts
-const transmit = new Transmit({
-  baseUrl: 'http://localhost:3333',
-  beforeSubscribe: (_request: RequestInit) => {
-    console.log('beforeSubscribe')
-  },
-  beforeUnsubscribe: (_request: RequestInit) => {
-    console.log('beforeUnsubscribe')
-  },
+subscription.onMessage((message) => {
+  console.log(message)
 })
 ```
 
-### Reconnecting
-
-The transmit client will automatically reconnect to the server when the connection is lost. You can change the number of retries and hook into the reconnect lifecycle as follows:
+You can also listen only once for a message using the `onMessagetOnce` method.
 
 ```ts
-const transmit = new Transmit({
-  baseUrl: 'http://localhost:3333',
-  maxReconnectionAttempts: 5,
-  onReconnectAttempt: (attempt) => {
-    console.log('Reconnect attempt ' + attempt)
-  },
-  onReconnectFailed: () => {
-    console.log('Reconnect failed')
-  },
+subscription.onMessageOnce((message) => {
+  console.log('I will be called only once')
 })
 ```
 
+Note listeners are local only; you can add them before or after registering your subscription on the server.
+
 ### Unsubscribing
 
-The `listenOn` method returns a function to unsubscribe from the channel.
+The `onMessage` method returns a function to remove the message handler from the subscription.
 
 ```ts
-const unsubscribe = transmit.listenOn('chat/1', () => {
+const unsubscribe = subscription.onMessage(() => {
   console.log('message received!')
 })
 
@@ -133,31 +108,50 @@ const unsubscribe = transmit.listenOn('chat/1', () => {
 unsubscribe()
 ```
 
-When unsubscribing from a channel, the client will remove the local listener for that channel. By default, it will not send a request to the server when there are no more listener to unsubscribe from the channel. You can change this behavior by setting the `removeSubscriptionOnZeroListener` option to `true`.
+If you want to entirely remove the subscription from the server, you can call the `delete` method.
+
+```ts
+await subscription.delete()
+```
+
+### Subscription Request
+
+You can alter the subscription request by using the `beforeSubscribe` or `beforeUnsubscribe` options.
 
 ```ts
 const transmit = new Transmit({
   baseUrl: 'http://localhost:3333',
-  removeSubscriptionOnZeroListener: true,
+  beforeSubscribe: (_request: Request) => {
+    console.log('beforeSubscribe')
+  },
+  beforeUnsubscribe: (_request: Request) => {
+    console.log('beforeUnsubscribe')
+  },
 })
 ```
 
-You can also change the default settings locally by passing a boolean to the unsubscribe method.
+### Reconnecting
+
+The transmit client will automatically reconnect to the server when the connection is lost. You can change the number of retries and hook into the reconnect lifecycle as follows:
 
 ```ts
-const unsubscribe = transmit.listenOn('chat/1', () => {
-  console.log('message received!')
+const transmit = new Transmit({
+  baseUrl: 'http://localhost:3333',
+  maxReconnectionAttempts: 5,
+  onReconnectAttempt: (attempt) => {
+    console.log('Reconnect attempt ' + attempt)
+  },
+  onReconnectFailed: () => {
+    console.log('Reconnect failed')
+  },
 })
-
-// later
-unsubscribe(true) // or false
 ```
 
 # Events
 
-The`Transmit` class extends the [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) class and emits multiple events.
+The`Transmit` class uses the [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) class to emits multiple events.
 
-```ts
+  ```ts
 transmit.on('connected', () => {
   console.log('connected')
 })

package/build/transmit.d.ts

@@ -1,6 +1,86 @@
+interface HttpClientOptions {
+    baseUrl: string;
+    uid: string;
+}
+declare class HttpClient {
+    #private;
+    constructor(options: HttpClientOptions);
+    send(request: Request): Promise<Response>;
+    createRequest(path: string, body: Record<string, unknown>): Request;
+}
+
+declare const HookEvent: {
+    readonly BeforeSubscribe: "beforeSubscribe";
+    readonly BeforeUnsubscribe: "beforeUnsubscribe";
+    readonly OnReconnectAttempt: "onReconnectAttempt";
+    readonly OnReconnectFailed: "onReconnectFailed";
+    readonly OnSubscribeFailed: "onSubscribeFailed";
+    readonly OnSubscription: "onSubscription";
+    readonly OnUnsubscription: "onUnsubscription";
+};
+type HookEvent = (typeof HookEvent)[keyof typeof HookEvent];
+
+declare class Hook {
+    #private;
+    register(event: HookEvent, handler: (...args: any[]) => void): this;
+    beforeSubscribe(request: Request): this;
+    beforeUnsubscribe(request: Request): this;
+    onReconnectAttempt(attempt: number): this;
+    onReconnectFailed(): this;
+    onSubscribeFailed(response: Response): this;
+    onSubscription(channel: string): this;
+    onUnsubscription(channel: string): this;
+}
+
+declare const TransmitStatus: {
+    readonly Initializing: "initializing";
+    readonly Connecting: "connecting";
+    readonly Connected: "connected";
+    readonly Disconnected: "disconnected";
+    readonly Reconnecting: "reconnecting";
+};
+type TransmitStatus = (typeof TransmitStatus)[keyof typeof TransmitStatus];
+
+interface SubscriptionOptions {
+    channel: string;
+    httpClient: HttpClient;
+    getEventSourceStatus: () => TransmitStatus;
+    hooks?: Hook;
+}
+declare class Subscription {
+    #private;
+    /**
+     * Returns if the subscription is created or not.
+     */
+    get isCreated(): boolean;
+    /**
+     * Returns if the subscription is deleted or not.
+     */
+    get isDeleted(): boolean;
+    /**
+     * Returns the number of registered handlers.
+     */
+    get handlerCount(): number;
+    constructor(options: SubscriptionOptions);
+    /**
+     * Run all registered handlers for the subscription.
+     */
+    $runHandler(message: unknown): void;
+    create(): Promise<unknown>;
+    forceCreate(): Promise<unknown>;
+    delete(): Promise<void>;
+    onMessage<T>(handler: (message: T) => void): () => void;
+    onMessageOnce<T>(handler: (message: T) => void): void;
+}
+
 interface TransmitOptions {
     baseUrl: string;
-    eventSourceConstructor?: typeof EventSource;
+    uidGenerator?: () => string;
+    eventSourceFactory?: (url: string | URL, options: {
+        withCredentials: boolean;
+    }) => EventSource;
+    eventTargetFactory?: () => EventTarget | null;
+    httpClientFactory?: (baseUrl: string, uid: string) => HttpClient;
     beforeSubscribe?: (request: RequestInit) => void;
     beforeUnsubscribe?: (request: RequestInit) => void;
     maxReconnectAttempts?: number;
@@ -9,24 +89,17 @@ interface TransmitOptions {
     onSubscribeFailed?: (response: Response) => void;
     onSubscription?: (channel: string) => void;
     onUnsubscription?: (channel: string) => void;
-    removeSubscriptionOnZeroListener?: boolean;
 }
-export declare const TransmitStatus: {
-    readonly Initializing: "initializing";
-    readonly Connecting: "connecting";
-    readonly Connected: "connected";
-    readonly Disconnected: "disconnected";
-    readonly Reconnecting: "reconnecting";
-};
-type TTransmitStatus = (typeof TransmitStatus)[keyof typeof TransmitStatus];
-export declare class Transmit extends EventTarget {
+declare class Transmit {
     #private;
+    /**
+     * Returns the unique identifier of the client.
+     */
     get uid(): string;
-    get listOfSubscriptions(): string[];
     constructor(options: TransmitOptions);
-    on(event: Exclude<TTransmitStatus, 'connecting'>, callback: (event: CustomEvent) => void): void;
-    listenOn<T = unknown>(channel: string, callback: (message: T) => void): (unsubscribeOnTheServer?: boolean) => void;
-    listenOnce<T = unknown>(channel: string, callback: (message: T) => void): void;
+    subscription(channel: string): Subscription;
+    on(event: Exclude<TransmitStatus, 'connecting'>, callback: (event: CustomEvent) => void): void;
     close(): void;
 }
-export {};
+
+export { Transmit };