logging: add logger class to dependants

Adds to all the places.

Also adds a test logging level variable to allow for setting the test logging level.

.env.test.example

@@ -5,3 +5,6 @@ VITE_ABLY_ENV=local
 
 # A key when testing using a local realtime setup
 VITE_ABLY_API_KEY=your-test-api-key
+
+# Whether to log during tests, valid values are "silent", "error", "warn", "info", "debug", "trace"
+VITE_TEST_LOG_LEVEL=silent

src/Chat.ts

@@ -1,9 +1,10 @@
 import * as Ably from 'ably';
 
-import { ClientOptions } from './config.js';
+import { ClientOptions, DefaultClientOptions } from './config.js';
+import { makeLogger } from './logger.js';
 import { RealtimeWithOptions } from './realtimeextensions.js';
 import { DefaultRooms, Rooms } from './Rooms.js';
-import { AGENT_STRING } from './version.js';
+import { AGENT_STRING, VERSION } from './version.js';
 
 /**
  * This is the core client for Ably chat. It provides access to chat rooms.
@@ -26,8 +27,12 @@ export class ChatClient {
    */
   constructor(realtime: Ably.Realtime, clientOptions?: ClientOptions) {
     this._realtime = realtime;
-    this._rooms = new DefaultRooms(realtime, clientOptions);
+    clientOptions = clientOptions ?? DefaultClientOptions;
+    const logger = makeLogger(clientOptions);
+
+    this._rooms = new DefaultRooms(realtime, clientOptions, logger);
     this.setAgent();
+    logger.trace(`ably chat client version ${VERSION}; initialised`);
   }
 
   /**

src/ChatApi.ts

@@ -3,6 +3,7 @@ import * as Ably from 'ably';
 import { Message } from './Message.js';
 import { OccupancyEvent } from './Occupancy.js';
 import { PaginatedResult } from './query.js';
+import { Logger } from './logger.js';
 
 export interface GetMessagesQueryParams {
   start?: number;
@@ -25,9 +26,11 @@ interface CreateMessageRequest {
  */
 export class ChatApi {
   private readonly realtime: Ably.Realtime;
+  private readonly _logger: Logger;
 
-  constructor(realtime: Ably.Realtime) {
+  constructor(realtime: Ably.Realtime, logger: Logger) {
     this.realtime = realtime;
+    this._logger = logger;
   }
 
   async getMessages(roomId: string, params: GetMessagesQueryParams): Promise<PaginatedResult<Message>> {

src/Messages.ts

@@ -2,6 +2,7 @@ import * as Ably from 'ably';
 
 import { ChatApi } from './ChatApi.js';
 import { MessageEvents } from './events.js';
+import { Logger } from './logger.js';
 import { DefaultMessage, Message } from './Message.js';
 import { PaginatedResult } from './query.js';
 import { SubscriptionManager } from './SubscriptionManager.js';
@@ -143,14 +144,16 @@ export class DefaultMessages extends EventEmitter<MessageEventsMap> implements M
   private readonly _managedChannel: SubscriptionManager;
   private readonly _chatApi: ChatApi;
   private readonly _clientId: string;
+  private readonly _logger: Logger;
   private _internalListener: Ably.messageCallback<Ably.InboundMessage> | undefined;
 
-  constructor(roomId: string, managedChannel: SubscriptionManager, chatApi: ChatApi, clientId: string) {
+  constructor(roomId: string, managedChannel: SubscriptionManager, chatApi: ChatApi, clientId: string, logger: Logger) {
     super();
     this._roomId = roomId;
     this._managedChannel = managedChannel;
     this._chatApi = chatApi;
     this._clientId = clientId;
+    this._logger = logger;
   }
 
   /**

src/Occupancy.ts

@@ -1,6 +1,7 @@
 import * as Ably from 'ably';
 
 import { ChatApi } from './ChatApi.js';
+import { Logger } from './logger.js';
 import { SubscriptionManager } from './SubscriptionManager.js';
 import EventEmitter from './utils/EventEmitter.js';
 
@@ -76,12 +77,14 @@ export class DefaultOccupancy extends EventEmitter<OccupancyEventsMap> implement
   private readonly _managedChannel: SubscriptionManager;
   private readonly _chatApi: ChatApi;
   private _internalListener: any;
+  private _logger: Logger;
 
-  constructor(roomId: string, managedChannel: SubscriptionManager, chatApi: ChatApi) {
+  constructor(roomId: string, managedChannel: SubscriptionManager, chatApi: ChatApi, logger: Logger) {
     super();
     this.roomId = roomId;
     this._managedChannel = managedChannel;
     this._chatApi = chatApi;
+    this._logger = logger;
   }
 
   /**

src/Presence.ts

@@ -1,6 +1,7 @@
 import * as Ably from 'ably';
 
 import { PresenceEvents } from './events.js';
+import { Logger } from './logger.js';
 import { SubscriptionManager } from './SubscriptionManager.js';
 import EventEmitter from './utils/EventEmitter.js';
 
@@ -172,6 +173,7 @@ export interface Presence {
 export class DefaultPresence extends EventEmitter<PresenceEventsMap> implements Presence {
   private readonly subscriptionManager: SubscriptionManager;
   private readonly clientId: string;
+  private readonly _logger: Logger;
 
   /**
    * Constructor for Presence
@@ -180,10 +182,11 @@ export class DefaultPresence extends EventEmitter<PresenceEventsMap> implements
    * @param {string} clientId - The client ID, attached to presences messages as an identifier of the sender.
    * A channel can have multiple connections using the same clientId.
    */
-  constructor(subscriptionManager: SubscriptionManager, clientId: string) {
+  constructor(subscriptionManager: SubscriptionManager, clientId: string, logger: Logger) {
     super();
     this.subscriptionManager = subscriptionManager;
     this.clientId = clientId;
+    this._logger = logger;
   }
 
   /**

src/Room.ts

@@ -2,6 +2,7 @@ import * as Ably from 'ably';
 
 import { ChatApi } from './ChatApi.js';
 import { ClientOptions } from './config.js';
+import { Logger } from './logger.js';
 import { DefaultMessages, Messages } from './Messages.js';
 import { DefaultOccupancy, Occupancy } from './Occupancy.js';
 import { DefaultPresence, Presence } from './Presence.js';
@@ -64,6 +65,7 @@ export class DefaultRoom implements Room {
   private readonly _presence: Presence;
   private readonly _reactions: RoomReactions;
   private readonly _occupancy: Occupancy;
+  private readonly _logger: Logger;
 
   /**
    * Constructs a new Room instance.
@@ -73,28 +75,30 @@ export class DefaultRoom implements Room {
    * @param chatApi An instance of the ChatApi.
    * @param clientOptions The client options from the chat instance.
    */
-  constructor(roomId: string, realtime: Ably.Realtime, chatApi: ChatApi, clientOptions: ClientOptions) {
+  constructor(roomId: string, realtime: Ably.Realtime, chatApi: ChatApi, clientOptions: ClientOptions, logger: Logger) {
     this._roomId = roomId;
     this.chatApi = chatApi;
     const messagesChannelName = `${this._roomId}::$chat::$chatMessages`;
 
     const subscriptionManager = new DefaultSubscriptionManager(
       realtime.channels.get(messagesChannelName, DEFAULT_CHANNEL_OPTIONS),
     );
-    this._messages = new DefaultMessages(roomId, subscriptionManager, this.chatApi, realtime.auth.clientId);
-    this._presence = new DefaultPresence(subscriptionManager, realtime.auth.clientId);
+    this._messages = new DefaultMessages(roomId, subscriptionManager, this.chatApi, realtime.auth.clientId, logger);
+    this._presence = new DefaultPresence(subscriptionManager, realtime.auth.clientId, logger);
     this._typingIndicators = new DefaultTypingIndicator(
       roomId,
       realtime,
       realtime.auth.clientId,
       clientOptions.typingTimeoutMs,
+      logger,
     );
 
     const reactionsManagedChannel = new DefaultSubscriptionManager(
       realtime.channels.get(`${this._roomId}::$chat::$reactions`, DEFAULT_CHANNEL_OPTIONS),
     );
-    this._reactions = new DefaultRoomReactions(roomId, reactionsManagedChannel, realtime.auth.clientId);
-    this._occupancy = new DefaultOccupancy(roomId, subscriptionManager, this.chatApi);
+    this._reactions = new DefaultRoomReactions(roomId, reactionsManagedChannel, realtime.auth.clientId, logger);
+    this._occupancy = new DefaultOccupancy(roomId, subscriptionManager, this.chatApi, logger);
+    this._logger = logger;
   }
 
   /**

src/RoomReactions.ts

@@ -1,6 +1,7 @@
 import * as Ably from 'ably';
 
 import { RoomReactionEvents } from './events.js';
+import { Logger } from './logger.js';
 import { SubscriptionManager } from './SubscriptionManager.js';
 import EventEmitter from './utils/EventEmitter.js';
 
@@ -98,12 +99,14 @@ export class DefaultRoomReactions extends EventEmitter<RoomReactionEventsMap> im
   private readonly roomId: string;
   private readonly _managedChannel: SubscriptionManager;
   private readonly clientId: string;
+  private readonly _logger: Logger;
 
-  constructor(roomId: string, managedChannel: SubscriptionManager, clientId: string) {
+  constructor(roomId: string, managedChannel: SubscriptionManager, clientId: string, logger: Logger) {
     super();
     this.roomId = roomId;
     this._managedChannel = managedChannel;
     this.clientId = clientId;
+    this._logger = logger;
   }
 
   /**

src/Rooms.ts

@@ -1,7 +1,8 @@
 import * as Ably from 'ably';
 
 import { ChatApi } from './ChatApi.js';
-import { ClientOptions, DefaultClientOptions } from './config.js';
+import { ClientOptions } from './config.js';
+import { Logger } from './logger.js';
 import { DefaultRoom, Room } from './Room.js';
 
 /**
@@ -45,17 +46,19 @@ export class DefaultRooms implements Rooms {
   private readonly chatApi: ChatApi;
   private readonly _clientOptions: ClientOptions;
   private rooms: Record<string, Room> = {};
+  private _logger: Logger;
 
   /**
    * Constructs a new Rooms instance.
    *
    * @param realtime An instance of the Ably Realtime client.
    * @param clientOptions The client options from the chat instance.
    */
-  constructor(realtime: Ably.Realtime, clientOptions?: ClientOptions) {
+  constructor(realtime: Ably.Realtime, clientOptions: ClientOptions, logger: Logger) {
     this.realtime = realtime;
-    this.chatApi = new ChatApi(realtime);
-    this._clientOptions = clientOptions ? clientOptions : DefaultClientOptions;
+    this.chatApi = new ChatApi(realtime, logger);
+    this._clientOptions = clientOptions;
+    this._logger = logger;
   }
 
   /**
@@ -64,7 +67,7 @@ export class DefaultRooms implements Rooms {
   get(roomId: string): Room {
     if (this.rooms[roomId]) return this.rooms[roomId];
 
-    const room = new DefaultRoom(roomId, this.realtime, this.chatApi, this._clientOptions);
+    const room = new DefaultRoom(roomId, this.realtime, this.chatApi, this._clientOptions, this._logger);
     this.rooms[roomId] = room;
 
     return room;

src/TypingIndicator.ts

@@ -1,6 +1,7 @@
 import * as Ably from 'ably';
 
 import { TypingIndicatorEvents } from './events.js';
+import { Logger } from './logger.js';
 import { DefaultSubscriptionManager, SubscriptionManager } from './SubscriptionManager.js';
 import EventEmitter from './utils/EventEmitter.js';
 import { DEFAULT_CHANNEL_OPTIONS } from './version.js';
@@ -110,6 +111,7 @@ export class DefaultTypingIndicator extends EventEmitter<TypingIndicatorEventsMa
   private readonly _currentlyTypingClientIds: Set<string>;
   private readonly _typingIndicatorsChannelName: string;
   private readonly _managedChannel: SubscriptionManager;
+  private readonly _logger: Logger;
 
   // Timeout for typing indicator
   private readonly _typingTimeoutMs: number;
@@ -122,7 +124,7 @@ export class DefaultTypingIndicator extends EventEmitter<TypingIndicatorEventsMa
    * @param clientId - The client ID.
    * @param typingTimeoutMs - The timeout for the typing indicator, set to 3000ms by default.
    */
-  constructor(roomId: string, realtime: Ably.Realtime, clientId: string, typingTimeoutMs: number) {
+  constructor(roomId: string, realtime: Ably.Realtime, clientId: string, typingTimeoutMs: number, logger: Logger) {
     super();
     this._roomId = roomId;
     this._clientId = clientId;
@@ -135,6 +137,7 @@ export class DefaultTypingIndicator extends EventEmitter<TypingIndicatorEventsMa
     // Timeout for typing indicator
     this._typingTimeoutMs = typingTimeoutMs;
     this._timerId = null;
+    this._logger = logger;
   }
 
   /**

src/config.ts

@@ -1,3 +1,5 @@
+import { LogHandler, LogLevel } from './logger.js';
+
 /**
  * Configuration options for the chat client.
  */
@@ -7,11 +9,24 @@ export interface ClientOptions {
    * @defaultValue 3000
    */
   typingTimeoutMs: number;
+
+  /**
+   * A custom log handler that will be used to log messages from the client.
+   * @defaultValue The client will log messages to the console.
+   */
+  logHandler?: LogHandler;
+
+  /**
+   * The minimum log level at which messages will be logged.
+   * @defaultValue LogLevel.error
+   */
+  logLevel?: LogLevel;
 }
 
 /**
  * Default configuration options for the chat client.
  */
 export const DefaultClientOptions: ClientOptions = {
   typingTimeoutMs: 3000,
+  logLevel: LogLevel.error,
 };

src/version.ts

@@ -1,5 +1,5 @@
 // Update this when you release a new version
-const VERSION = '0.0.1';
+export const VERSION = '0.0.1';
 const AGENT_STRING = 'chat-js/' + VERSION;
 const DEFAULT_CHANNEL_OPTIONS = { params: { agent: AGENT_STRING } };