larasopp 1.2.23 → 1.2.24

package/README.md

@@ -1,70 +1,443 @@
-# Laravel websocket client
+# Larasopp Client
 
-#### Server
+WebSocket client for Laravel with full TypeScript support and type safety.
+
+## Features
+
+- 🔌 **WebSocket Connection** - Real-time bidirectional communication
+- 🎯 **Full TypeScript Support** - Complete type safety for channels, events, and users
+- 📡 **Channel Subscriptions** - Subscribe to multiple channels
+- 🎧 **Event Listeners** - Listen to specific events with typed callbacks
+- 👥 **Presence Channels** - Track users joining/leaving channels
+- 🔐 **Authentication** - Token-based authentication
+- 🔄 **Auto Reconnect** - Automatic reconnection with configurable delays
+- ✅ **Type Safety** - Compile-time type checking for all operations
+
+## Installation
+
+```bash
+npm install larasopp
+# or
+yarn add larasopp
+# or
+pnpm add larasopp
 ```
-https://www.npmjs.com/package/larasopp-server
+
+## Related Packages
+
+- **Server**: [larasopp-server](https://www.npmjs.com/package/larasopp-server)
+- **Laravel Package**: `composer require larasopp/larasopp`
+
+## Quick Start
+
+```typescript
+import Larasopp from 'larasopp';
+
+const larasopp = new Larasopp({
+  host: 'ws://127.0.0.1:3001',
+  token: 'your-auth-token'
+});
+
+larasopp.connect();
 ```
-#### Laravel package
+
+## TypeScript Support
+
+Larasopp provides full TypeScript support with generic types for channels, events, and users.
+
+### Defining Types
+
+```typescript
+// Define your channel events structure
+type ChannelsEvents = {
+  chat: {
+    message: { text: string; author: string; timestamp: number };
+    typing: { user: string };
+    userJoined: { user: string };
+  };
+  notifications: {
+    alert: { title: string; body: string; type: 'info' | 'warning' | 'error' };
+    update: { version: string };
+  };
+};
+
+// Define your user type
+interface MyUser {
+  id: number;
+  name: string;
+  email: string;
+  avatar?: string;
+}
+
+// Create typed instance
+const larasopp = new Larasopp<ChannelsEvents, MyUser>({
+  host: 'ws://127.0.0.1:3001',
+  token: 'your-token'
+});
 ```
-composer require larasopp/larasopp
+
+## API Reference
+
+### Configuration
+
+```typescript
+interface IConfig {
+  host: string;                    // WebSocket server URL
+  token?: string;                  // Authentication token
+  reviver?: (key: string, value: any) => any;  // JSON reviver function
+  dataReviver?: { [key: string]: (value: any) => any };  // Per-key revivers
+  reconnect?: number;              // Max reconnection attempts
+  reconnectDelay?: number;         // Delay between reconnections (ms)
+}
 ```
 
-### Connect app to websocket
+### Connection
 
-```js
-...
-import Larasopp from "Larasopp";
+#### `connect(token?: string)`
 
-const larasopp = new Larasopp({
-	host: 'ws://127.0.0.1:3001',
-	token: 'token'
-});
+Connect to the WebSocket server.
 
+```typescript
 larasopp.connect();
-//or
-larasopp.connect('token');
+// or with token
+larasopp.connect('new-token');
+```
+
+#### `disconnect()`
+
+Disconnect from the WebSocket server.
+
+```typescript
+larasopp.disconnect();
+```
+
+#### `setToken(token: string)`
+
+Update authentication token.
+
+```typescript
+larasopp.setToken('new-token');
+```
 
+### Channels
+
+#### `subscribe<K>(channel: K): Listener`
+
+Subscribe to a channel. Returns a `Listener` instance for the channel.
+
+```typescript
+// TypeScript will enforce that 'chat' exists in ChannelsEvents
+const listener = larasopp.subscribe('chat');
 ```
 
-### Update user token
+#### `unsubscribe<K>(channel: K)`
+
+Unsubscribe from a channel.
+
+```typescript
+larasopp.unsubscribe('chat');
+```
+
+#### `countListeners<K>(channel: K): number`
+
+Get the number of listeners for a channel.
 
-```js
-larasopp.setToken('new token');
+```typescript
+const count = larasopp.countListeners('chat');
 ```
 
-### Subscribe on channel and listen event
+### Events
 
-```js
-const listener = larasopp.subscribe('chat').listen('message',(data) => {
-	console.log(data.text); // Hello World
+#### `listen<K>(event: K, callback, withCache?: boolean): this`
+
+Listen to a specific event on the subscribed channel.
+
+```typescript
+const listener = larasopp.subscribe('chat');
+
+// TypeScript knows 'message' exists and its data type
+listener.listen('message', (data) => {
+  // data is typed as { text: string; author: string; timestamp: number }
+  console.log(data.text, data.author);
 });
 
-// Unsubscribe event
-listener.remove();
+// withCache: true will call callback immediately if cached data exists
+listener.listen('typing', (data) => {
+  console.log(data.user, 'is typing');
+}, true);
 ```
 
-### Trigger event on subscribe channel
+#### `trigger<K, E>(channel: K, event: E, message, permission?, waitSubscribe?): void`
+
+Trigger an event on a channel.
+
+**Permission Levels:**
+
+- **`'public'`** - Event will be sent to all channel subscribers AND to the API application
+- **`'protected'`** - Event will be sent to all channel subscribers but NOT to the API application
+- **`'private'`** - Event will be sent ONLY to the API application, not to channel subscribers
+
+```typescript
+// TypeScript ensures 'chat' channel and 'message' event exist
+// and that the message matches the event type
+
+// Public: sent to all subscribers and API
+larasopp.trigger('chat', 'message', {
+  text: 'Hello World',
+  author: 'John Doe',
+  timestamp: Date.now()
+}, 'public');
 
-```js
-larasopp.trigger('chat','message',{
-	text: 'Hello World'
-},'public');
+// Protected: sent to subscribers only, not to API
+larasopp.trigger('chat', 'message', {
+  text: 'User message',
+  author: 'Jane Doe',
+  timestamp: Date.now()
+}, 'protected');
+
+// Private: sent to API only, not to subscribers
+larasopp.trigger('chat', 'message', {
+  text: 'Admin notification',
+  author: 'System',
+  timestamp: Date.now()
+}, 'private', true); // waitSubscribe: true waits for subscription
 ```
 
-### Unsubscribe channel
+### Event Permissions
 
-```js
-larasopp.unsubscribe('chat');
+When triggering events, you can specify one of three permission levels:
+
+| Permission | Channel Subscribers | API Application | Use Case |
+|------------|---------------------|-----------------|----------|
+| `'public'` | ✅ Yes | ✅ Yes | Broadcast to everyone including server-side processing |
+| `'protected'` | ✅ Yes | ❌ No | Client-to-client communication without server handling |
+| `'private'` | ❌ No | ✅ Yes | Server-side only events (notifications, admin actions) |
+
+**Examples:**
+
+```typescript
+// Public: Broadcast message to all users and process on server
+larasopp.trigger('chat', 'message', {
+  text: 'Hello everyone!',
+  author: 'John'
+}, 'public');
+
+// Protected: Send to users but don't trigger server-side handlers
+larasopp.trigger('chat', 'typing', {
+  user: 'John'
+}, 'protected');
+
+// Private: Server-side only (e.g., admin notifications, system events)
+larasopp.trigger('notifications', 'alert', {
+  title: 'System Maintenance',
+  body: 'Scheduled maintenance in 5 minutes'
+}, 'private');
 ```
 
-### Disconnect
+### Presence Channels
 
-```js
-larasopp.disconnect();
+#### `here(callback, withCache?: boolean): this`
+
+Get list of users currently in the channel.
+
+```typescript
+listener.here((users) => {
+  // users is typed as MyUser[]
+  users.forEach(user => {
+    console.log(user.name, 'is here');
+  });
+});
+```
+
+#### `joining(callback, withCache?: boolean): this`
+
+Listen for users joining the channel.
+
+```typescript
+listener.joining((user) => {
+  // user is typed as MyUser
+  console.log(user.name, 'joined');
+});
+```
+
+#### `leaving(callback, withCache?: boolean): this`
+
+Listen for users leaving the channel.
+
+```typescript
+listener.leaving((user) => {
+  // user is typed as MyUser
+  console.log(user.name, 'left');
+});
+```
+
+### User Management
+
+#### `user(callback): void`
+
+Get current authenticated user.
+
+```typescript
+larasopp.user((user) => {
+  // user is typed as MyUser
+  console.log('Current user:', user.name);
+});
+```
+
+#### `userRefresh(callback): void`
+
+Refresh current user data.
+
+```typescript
+larasopp.userRefresh((user) => {
+  // user is typed as MyUser
+  console.log('Refreshed user:', user);
+});
+```
+
+### Socket Events
+
+#### `addListener(event, callback): EventListener | undefined`
+
+Listen to socket-level events: `'open'`, `'close'`, `'error'`.
+
+```typescript
+larasopp.addListener('open', () => {
+  console.log('Connected to WebSocket');
+});
+
+larasopp.addListener('close', () => {
+  console.log('Disconnected from WebSocket');
+});
+
+larasopp.addListener('error', (error) => {
+  console.error('WebSocket error:', error);
+});
+```
+
+### Listener Management
+
+#### `remove()`
+
+Remove all event listeners from a channel subscription.
+
+```typescript
+const listener = larasopp.subscribe('chat');
+listener.listen('message', handleMessage);
+
+// Later, remove all listeners
+listener.remove();
+```
+
+#### `unsubscribe()`
+
+Unsubscribe from the channel and remove all listeners.
+
+```typescript
+listener.unsubscribe();
 ```
 
-### Permissions
+## Complete Example
+
+```typescript
+import Larasopp from 'larasopp';
+
+// Define types
+type AppChannels = {
+  chat: {
+    message: { text: string; author: string };
+    typing: { user: string };
+  };
+  notifications: {
+    alert: { title: string; body: string };
+  };
+};
+
+interface AppUser {
+  id: number;
+  name: string;
+  email: string;
+}
+
+// Create instance
+const larasopp = new Larasopp<AppChannels, AppUser>({
+  host: 'ws://127.0.0.1:3001',
+  token: 'auth-token',
+  reconnect: 5,
+  reconnectDelay: 1000
+});
+
+// Connect
+larasopp.connect();
+
+// Listen to connection events
+larasopp.addListener('open', () => {
+  console.log('Connected');
+});
+
+// Subscribe to channel
+const chatListener = larasopp.subscribe('chat');
 
-```js
-'public' | 'protected' | 'private'
+// Listen to events with full type safety
+chatListener.listen('message', (data) => {
+  // TypeScript knows data structure
+  console.log(`${data.author}: ${data.text}`);
+});
+
+chatListener.listen('typing', (data) => {
+  console.log(`${data.user} is typing...`);
+});
+
+// Presence channel features
+chatListener.here((users) => {
+  console.log('Users in channel:', users.map(u => u.name));
+});
+
+chatListener.joining((user) => {
+  console.log(`${user.name} joined`);
+});
+
+chatListener.leaving((user) => {
+  console.log(`${user.name} left`);
+});
+
+// Trigger events
+larasopp.trigger('chat', 'message', {
+  text: 'Hello!',
+  author: 'John'
+}, 'public');
+
+// Get current user
+larasopp.user((user) => {
+  console.log('Logged in as:', user.name);
+});
+
+// Cleanup
+chatListener.remove();
+larasopp.unsubscribe('chat');
+larasopp.disconnect();
 ```
+
+## Type Safety Benefits
+
+With TypeScript support, you get:
+
+- ✅ **Compile-time checks** - Catch errors before runtime
+- ✅ **Autocomplete** - IDE suggests available channels and events
+- ✅ **Type inference** - Automatic type detection for callbacks
+- ✅ **Refactoring safety** - Rename channels/events with confidence
+- ✅ **Documentation** - Types serve as inline documentation
+
+## License
+
+MIT
+
+## Author
+
+Sergey Serov
+
+## Links
+
+- [GitHub Repository](https://github.com/SergoMorello/larasopp.client)
+- [NPM Package](https://www.npmjs.com/package/larasopp)
+- [Server Package](https://www.npmjs.com/package/larasopp-server)

package/lib/Listener.d.ts

@@ -1,16 +1,18 @@
 import EventEmmiter from "easy-event-emitter";
 import type Larasopp from ".";
-declare class Listener extends EventEmmiter.Stack {
+import type { TListenCallback, TJoiningCallback, TLeavingCallback, THereCallback, TUser } from "./types";
+declare class Listener<TEvents = Record<string, unknown>, TUserType extends TUser = TUser> extends EventEmmiter.Stack {
     private readonly context;
     private channel;
     private listener?;
     private cacheEvents;
     private hereMap;
-    constructor(channel: string, constext: Larasopp);
-    listen(event: string, callback: (data: any) => void, withCache?: boolean): this;
-    here(callback: (data: any) => void, withCache?: boolean): this;
-    joining(callback: (data: any) => void, withCache?: boolean): this;
-    leaving(callback: (data: any) => void, withCache?: boolean): this;
+    constructor(channel: string, constext: Larasopp<any, TUserType>);
+    listen<K extends keyof TEvents>(event: K, callback: TListenCallback<TEvents[K]>, withCache?: boolean): this;
+    private listenInternal;
+    here(callback: THereCallback<TUserType>, withCache?: boolean): this;
+    joining(callback: TJoiningCallback<TUserType>, withCache?: boolean): this;
+    leaving(callback: TLeavingCallback<TUserType>, withCache?: boolean): this;
     unsubscribe(): void;
     private hasCache;
     private getCache;

package/lib/Listener.js

@@ -43,8 +43,22 @@ class Listener extends easy_event_emitter_1.default.Stack {
         this.here(() => { }, true);
     }
     listen(event, callback, withCache = false) {
-        if (withCache && this.hasCache(event))
+        const eventString = String(event);
+        if (withCache && this.hasCache(eventString)) {
+            callback(this.getCache(eventString));
+        }
+        const listener = this.context.events.addListener(`${this.channel}:${eventString}`, (data) => {
+            callback(data);
+            if (withCache)
+                this.pushCache(eventString, data);
+        });
+        this.push(listener);
+        return this;
+    }
+    listenInternal(event, callback, withCache = false) {
+        if (withCache && this.hasCache(event)) {
             callback(this.getCache(event));
+        }
         const listener = this.context.events.addListener(`${this.channel}:${event}`, (data) => {
             callback(data);
             if (withCache)
@@ -63,17 +77,17 @@ class Listener extends easy_event_emitter_1.default.Stack {
             this.hereMap.delete(leave.id);
             callback([...this.hereMap.values()]);
         }));
-        const hereListener = this.listen('__HERE', (here) => {
+        const hereListener = this.listenInternal('__HERE', (here) => {
             this.hereMap = new Map(here.map((u) => [u.id, u]));
             callback([...this.hereMap.values()]);
         }, withCache);
         return hereListener;
     }
     joining(callback, withCache = false) {
-        return this.listen('__JOIN', callback, withCache);
+        return this.listenInternal('__JOIN', callback, withCache);
     }
     leaving(callback, withCache = false) {
-        return this.listen('__LEAVE', callback, withCache);
+        return this.listenInternal('__LEAVE', callback, withCache);
     }
     unsubscribe() {
         this.context.unsubscribe(this.channel);

package/lib/index.d.ts

@@ -1,18 +1,19 @@
 import { type EventListener } from "easy-event-emitter";
 import Core from "./Core";
 import Listener from "./Listener";
-import type { IConfig, TPermissions, TSocketEvents, TListenerCallback } from "./types";
-declare class Larasopp extends Core {
+import type { IConfig, TPermissions, TSocketEvents, TListenerCallback, TUser } from "./types";
+declare class Larasopp<TChannelsEvents = Record<string, Record<string, unknown>>, TUserType extends TUser = TUser> extends Core {
     private readonly channels;
     constructor(config: IConfig);
     private listenResumeSubscribes;
-    user(callback: (user: any) => void): void;
-    userRefresh(callback: (user: any) => void): void;
-    subscribe(channel: string): Listener;
-    unsubscribe(channel: string): void;
-    trigger<T>(channel: string, event: string, message: T, permission?: TPermissions, waitSubscribe?: boolean): void;
+    user(callback: (user: TUserType) => void): void;
+    userRefresh(callback: (user: TUserType) => void): void;
+    subscribe<K extends keyof TChannelsEvents>(channel: K): Listener<TChannelsEvents[K], TUserType>;
+    unsubscribe<K extends keyof TChannelsEvents>(channel: K): void;
+    trigger<K extends keyof TChannelsEvents, E extends keyof TChannelsEvents[K]>(channel: K, event: E, message: TChannelsEvents[K][E], permission?: TPermissions, waitSubscribe?: boolean): void;
+    trigger(channel: string, event: string, message: unknown, permission?: TPermissions, waitSubscribe?: boolean): void;
     private pushListener;
-    countListeners(channel: string): number;
+    countListeners<K extends keyof TChannelsEvents>(channel: K): number;
     addListener(event: TSocketEvents, callback: TListenerCallback): EventListener | undefined;
 }
 export type { Listener, EventListener };

package/lib/index.js

@@ -29,19 +29,13 @@ class Larasopp extends Core_1.default {
         if (!this.status)
             return;
         this.send({ me: true });
-        const listener = this.events.addListener(`__SYSTEM:user`, (e) => {
-            callback(e);
-            listener.remove();
-        });
+        this.events.once(`__SYSTEM:user`, callback);
     }
     userRefresh(callback) {
         if (!this.status)
             return;
         this.send({ me: 'refresh' });
-        const listener = this.events.addListener(`__SYSTEM:user-refresh`, (e) => {
-            callback(e);
-            listener.remove();
-        });
+        this.events.once(`__SYSTEM:user-refresh`, callback);
     }
     subscribe(channel) {
         const listener = new Listener_1.default(channel, this);

package/lib/types.d.ts

@@ -27,6 +27,16 @@ export interface IConfig {
     reconnect?: number;
     reconnectDelay?: number;
 }
-export type TChannels = {
-    [channel: string]: Listener[];
+export type TUser = {
+    id: string | number;
+    [key: string]: unknown;
 };
+export type TChannels<TChannelsEvents = Record<string, Record<string, unknown>>, TUserType extends TUser = TUser> = {
+    [K in keyof TChannelsEvents]?: Listener<TChannelsEvents[K], TUserType>[];
+};
+export type TJoinData<T extends TUser = TUser> = T;
+export type TLeaveData<T extends TUser = TUser> = T;
+export type THereCallback<T extends TUser = TUser> = (users: T[]) => void;
+export type TListenCallback<T = unknown> = (data: T) => void;
+export type TJoiningCallback<T extends TUser = TUser> = (data: TJoinData<T>) => void;
+export type TLeavingCallback<T extends TUser = TUser> = (data: TLeaveData<T>) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "larasopp",
-  "version": "1.2.23",
+  "version": "1.2.24",
   "description": "Websocket client for laravel",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -23,9 +23,30 @@
   },
   "keywords": [
     "websocket",
+    "websocket-client",
     "laravel",
+    "laravel-broadcast",
     "broadcast",
-    "events"
+    "events",
+    "typescript",
+    "types",
+    "type-safe",
+    "type-safety",
+    "typing",
+    "real-time",
+    "realtime",
+    "presence",
+    "channels",
+    "client",
+    "socket",
+    "ws",
+    "event-emitter",
+    "subscription",
+    "reconnect",
+    "authentication",
+    "token",
+    "pubsub",
+    "publish-subscribe"
   ],
   "author": "Sergey Serov",
   "license": "MIT",