@adonisjs/transmit-client 0.1.5 → 0.2.0

package/LICENSE.md

@@ -1,9 +1,9 @@
-# The MIT License
-
-Copyright (c) 2023, Romain Lanz, AdonisJS Core Team, contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# The MIT License
+
+Copyright (c) 2023, Romain Lanz, AdonisJS Core Team, contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -27,7 +27,7 @@
 
 <hr />
 
-AdonisJS Transmit Client is a client for the native Server-Sent-Event (SSE) module of AdonisJS. It is built on top of the [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/ntSource) API and provides a simple API to receive events from the server.
+AdonisJS Transmit Client is a client for the native Server-Sent-Event (SSE) module of AdonisJS. It is built on top of the [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) API and provides a simple API to receive events from the server.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO 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.
+Once the subscription is created, you can listen for events on the channel using the `onMessage` method. You can define as many listeners as you want.
 
 ```ts
-const transmit = new Transmit({
-  baseUrl: 'http://localhost:3333',
-  beforeSubscribe: (_request: RequestInit) => {
-    console.log('beforeSubscribe')
-  },
-  beforeUnsubscribe: (_request: RequestInit) => {
-    console.log('beforeUnsubscribe')
-  },
+import {subscribe} from 'node:diagnostics_channel'
+
+subscribe.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')
-  },
+subscribe.onMessageOnce((message) => {
+  console.log('I will be called only once')
 })
 ```
 
 ### 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,84 @@
+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>;
+    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;
     beforeSubscribe?: (request: RequestInit) => void;
     beforeUnsubscribe?: (request: RequestInit) => void;
     maxReconnectAttempts?: number;
@@ -9,24 +87,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 };