@chirpier/chirpier-js 0.1.2 → 0.1.4

package/src/index.ts

@@ -1,30 +1,36 @@
 // Import necessary dependencies
 import axios, { AxiosInstance } from "axios";
 import axiosRetry from "axios-retry";
-import { v4 as uuidv4 } from "@lukeed/uuid";
 import { Base64 } from "js-base64";
 import {
   DEFAULT_API_ENDPOINT,
   DEFAULT_RETRIES,
   DEFAULT_TIMEOUT,
+  DEFAULT_BATCH_SIZE,
+  DEFAULT_FLUSH_DELAY,
+  MAX_QUEUE_SIZE,
 } from "./constants";
+import AsyncLock from "async-lock";
+
+// Define logging levels
+export enum LogLevel {
+  None = 0,
+  Error = 1,
+  Info = 2,
+  Debug = 3,
+}
 
 // Define the options interface for Chirpier initialization
 interface Options {
   key: string;
-  apiEndpoint?: string;
-  retries?: number;
-  timeout?: number;
-  batchSize?: number;
-  flushInterval?: number;
+  logLevel?: LogLevel;
 }
 
 // Define the Event interface for monitoring
 export interface Event {
   group_id: string;
-  stream: string;
+  stream_name: string;
   value: number;
-  event_id?: string;
 }
 
 // Custom error class for Chirpier-specific errors
@@ -36,41 +42,48 @@ export class ChirpierError extends Error {
   }
 }
 
+interface QueuedEvent {
+  event: Event;
+  timestamp: number;
+  retryCount: number;
+}
+
 /**
  * Main Chirpier class for monitoring events.
  */
 export class Chirpier {
+  private static instance: Chirpier | null = null;
   private readonly apiKey: string;
   private readonly apiEndpoint: string;
   private readonly retries: number;
   private readonly timeout: number;
   private readonly axiosInstance: AxiosInstance;
-  private eventQueue: Event[] = [];
-  private flushTimeout: NodeJS.Timeout | null = null;
+  private eventQueue: QueuedEvent[] = [];
   private readonly batchSize: number;
-  private readonly flushInterval: number;
+  private readonly flushDelay: number;
+  private flushTimeoutId: NodeJS.Timeout | null = null;
+  private readonly queueLock = new AsyncLock();
+  private readonly flushLock = new AsyncLock();
+  private readonly logLevel: LogLevel;
 
   /**
    * Initializes a new instance of the Chirpier class.
    * @param options - Configuration options for the SDK.
    */
-  constructor({
-    key,
-    apiEndpoint = DEFAULT_API_ENDPOINT,
-    retries = DEFAULT_RETRIES,
-    timeout = DEFAULT_TIMEOUT,
-    batchSize = 100,
-    flushInterval = 500,
-  }: Options) {
+  private constructor(options: Options) {
+    const { key, logLevel = LogLevel.None } = options;
+
     if (!key || typeof key !== "string") {
       throw new ChirpierError("API key is required and must be a string");
     }
+
     this.apiKey = key;
-    this.apiEndpoint = apiEndpoint;
-    this.retries = retries;
-    this.timeout = timeout;
-    this.batchSize = batchSize;
-    this.flushInterval = flushInterval;
+    this.apiEndpoint = DEFAULT_API_ENDPOINT;
+    this.retries = DEFAULT_RETRIES;
+    this.timeout = DEFAULT_TIMEOUT;
+    this.batchSize = DEFAULT_BATCH_SIZE;
+    this.flushDelay = DEFAULT_FLUSH_DELAY;
+    this.logLevel = logLevel;
 
     // Create axios instance with authorization header
     this.axiosInstance = axios.create({
@@ -102,6 +115,18 @@ export class Chirpier {
     });
   }
 
+  /**
+   * Gets the singleton instance of Chirpier, creating it if it doesn't exist.
+   * @param options - Configuration options for the SDK.
+   * @returns The Chirpier instance.
+   */
+  public static getInstance(options: Options): Chirpier | null {
+    if (!Chirpier.instance && options.key) {
+      Chirpier.instance = new Chirpier(options);
+    }
+    return Chirpier.instance;
+  }
+
   /**
    * Validates the event structure.
    * @param event - The event to validate.
@@ -114,8 +139,8 @@ export class Chirpier {
         event.group_id
       ) &&
       event.group_id.trim().length > 0 &&
-      typeof event.stream === "string" &&
-      event.stream.trim().length > 0 &&
+      typeof event.stream_name === "string" &&
+      event.stream_name.trim().length > 0 &&
       typeof event.value === "number"
     );
   }
@@ -125,27 +150,26 @@ export class Chirpier {
    * @param event - The event to monitor.
    */
   public async monitor(event: Event): Promise<void> {
-    if (!this.apiKey) {
-      throw new ChirpierError("Chirpier SDK must be initialized before calling monitor()");
-    }
-
     if (!this.isValidEvent(event)) {
       throw new ChirpierError(
-        "Invalid event format. Must include group_id, stream, and numeric value."
+        "Invalid event format. Must include group_id, stream_name, and numeric value."
       );
     }
 
-    // Ensure event_id is only set once
-    const eventWithID = { ...event, event_id: event.event_id || uuidv4() };
+    await this.queueLock.acquire("queue", async () => {
+      if (this.eventQueue.length >= MAX_QUEUE_SIZE) {
+        throw new ChirpierError("Event queue is full.");
+      }
 
-    this.eventQueue.push(eventWithID);
+      this.eventQueue.push({ event, timestamp: Date.now(), retryCount: 0 });
+    });
 
     if (this.eventQueue.length >= this.batchSize) {
-      this.flushQueue();
-    } else if (!this.flushTimeout) {
-      this.flushTimeout = setTimeout(
+      await this.flushQueue();
+    } else if (!this.flushTimeoutId) {
+      this.flushTimeoutId = setTimeout(
         () => this.flushQueue(),
-        this.flushInterval
+        this.flushDelay
       );
     }
   }
@@ -154,32 +178,65 @@ export class Chirpier {
    * Flushes the event queue by sending all events to the API.
    */
   private async flushQueue(): Promise<void> {
-    if (this.eventQueue.length === 0) {
-      return;
-    }
-    
-    if (this.flushTimeout) {
-      clearTimeout(this.flushTimeout);
-      this.flushTimeout = null;
-    }
+    // Acquire the flush lock
+    await this.flushLock.acquire("flush", async () => {
+      let eventsToSend: QueuedEvent[] = [];
 
-    const eventsToSend = [...this.eventQueue];
-    this.eventQueue = [];
+      // Extract events from the queue under the queue lock
+      await this.queueLock.acquire("eventQueue", async () => {
+        if (this.eventQueue.length > 0) {
+          eventsToSend = [...this.eventQueue];
+          this.eventQueue = [];
+        }
+      });
 
-    try {
-      await this.sendEvents(eventsToSend);
-      console.info(`Successfully sent ${eventsToSend.length} events`);
-    } catch (error) {
-      console.error("Failed to send events:", error);
-    }
+      if (eventsToSend.length === 0) {
+        return;
+      }
 
-    // Schedule next flush if there are more events
-    if (this.eventQueue.length > 0) {
-      this.flushTimeout = setTimeout(
-        () => this.flushQueue(),
-        this.flushInterval
-      );
-    }
+      try {
+        // Clear any pending flush timeout
+        if (this.flushTimeoutId) {
+          clearTimeout(this.flushTimeoutId);
+          this.flushTimeoutId = null;
+        }
+
+        // Attempt to send events
+        await this.sendEvents(eventsToSend.map((qe) => qe.event));
+
+        if (this.logLevel >= LogLevel.Info) {
+          console.info(`Successfully sent ${eventsToSend.length} events`);
+        }
+      } catch (error) {
+        // Log failure
+        if (this.logLevel >= LogLevel.Error) {
+          console.error("Failed to send events:", error);
+        }
+
+        // Requeue failed events with retry count checks
+        const retryableEvents: QueuedEvent[] = [];
+        for (const queuedEvent of eventsToSend) {
+          if (queuedEvent.retryCount >= this.retries) {
+            if (this.logLevel >= LogLevel.Error) {
+              console.error(
+                `Dropping event after ${this.retries} retries:`,
+                queuedEvent.event
+              );
+            }
+            continue; // Skip adding this event back to the queue
+          }
+
+          // Increment retry count and add back to the queue
+          queuedEvent.retryCount++;
+          retryableEvents.push(queuedEvent);
+        }
+
+        // Requeue remaining retryable events
+        await this.queueLock.acquire("eventQueue", async () => {
+          this.eventQueue = [...retryableEvents, ...this.eventQueue];
+        });
+      }
+    });
   }
 
   /**
@@ -189,6 +246,21 @@ export class Chirpier {
   private async sendEvents(events: Event[]): Promise<void> {
     await this.axiosInstance.post(this.apiEndpoint, events);
   }
+
+  // Stop the timeout and uninitialize the Chirpier instance
+  public static async stop(): Promise<void> {
+    if (!Chirpier.instance) {
+      return;
+    }
+    if (Chirpier.instance.flushTimeoutId) {
+      clearTimeout(Chirpier.instance.flushTimeoutId);
+      Chirpier.instance.flushTimeoutId = null;
+    }
+    // Flush any remaining events in the queue
+    await Chirpier.instance.flushQueue();
+    // Uninitialize the Chirpier instance
+    Chirpier.instance = null;
+  }
 }
 
 /**
@@ -226,9 +298,6 @@ function isValidJWT(token: string): boolean {
   }
 }
 
-// Singleton instance of Chirpier
-let chirpierInstance: Chirpier | null = null;
-
 /**
  * Initializes the Chirpier SDK.
  * @param options - Configuration options for the SDK.
@@ -239,15 +308,19 @@ export function initialize(options: Options): void {
   }
 
   try {
-    chirpierInstance = new Chirpier(options);
+    Chirpier.getInstance(options);
   } catch (error) {
     if (error instanceof ChirpierError) {
-      console.error("Failed to initialize Chirpier SDK:", error.message);
+      if (options.logLevel && options.logLevel >= LogLevel.Error) {
+        console.error("Failed to initialize Chirpier SDK:", error.message);
+      }
     } else {
-      console.error(
-        "An unexpected error occurred during Chirpier SDK initialization:",
-        error
-      );
+      if (options.logLevel && options.logLevel >= LogLevel.Error) {
+        console.error(
+          "An unexpected error occurred during Chirpier SDK initialization:",
+          error
+        );
+      }
     }
     throw error;
   }
@@ -258,12 +331,14 @@ export function initialize(options: Options): void {
  * @param event - The event to monitor.
  */
 export function monitor(event: Event): void {
-  if (!chirpierInstance) {
+  const instance = Chirpier.getInstance({} as Options);
+  if (!instance) {
     throw new ChirpierError(
       "Chirpier SDK is not initialized. Please call initialize() first."
     );
   }
-  chirpierInstance.monitor(event).catch((error) => {
+
+  instance.monitor(event).catch((error) => {
     console.error("Error in monitor function:", error);
   });
 }

package/src/__tests__/mocks/server.ts

@@ -1,6 +0,0 @@
-import axios from "axios";
-
-// Cleanup mock server after tests
-export function cleanupMockServer() {
-  axios.defaults.adapter = undefined;
-}

package/src/__tests__/sdk.test.ts

@@ -1,222 +0,0 @@
-import { Chirpier, ChirpierError, Event, initialize, monitor } from "../index";
-import { DEFAULT_API_ENDPOINT, DEFAULT_RETRIES } from "../constants";
-import MockAdapter from "axios-mock-adapter";
-import axios from "axios";
-import { cleanupMockServer } from "./mocks/server";
-import { v4 as uuidv4 } from "@lukeed/uuid";
-
-jest.mock("@lukeed/uuid");
-
-describe("Chirpier SDK", () => {
-  let chirpier: Chirpier;
-
-  afterEach(() => {
-    // Clean up mock server
-    cleanupMockServer();
-  });
-
-  describe("Initialization", () => {
-    test("should initialize with default values", () => {
-      chirpier = new Chirpier({
-        key: "api_key",
-      });
-
-      // Setup mock server
-      const mock = new MockAdapter(axios);
-      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
-
-      expect(chirpier["apiEndpoint"]).toBe(DEFAULT_API_ENDPOINT);
-      expect(chirpier["retries"]).toBe(DEFAULT_RETRIES);
-    });
-
-    test("should initialize with custom values using mock server", () => {
-      chirpier = new Chirpier({
-        key: "api_key",
-      });
-
-      // Setup mock server
-      const mock = new MockAdapter(axios);
-      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
-
-      const customChirpier = new Chirpier({
-        key: "api_key",
-        apiEndpoint: DEFAULT_API_ENDPOINT,
-        retries: 5,
-      });
-
-      expect(customChirpier["apiEndpoint"]).toBe(DEFAULT_API_ENDPOINT);
-      expect(customChirpier["retries"]).toBe(5);
-    });
-
-    test("should throw error if key is not provided", () => {
-      chirpier = new Chirpier({
-        key: "api_key",
-      });
-
-      // Setup mock server
-      const mock = new MockAdapter(axios);
-      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
-
-      expect(() => new Chirpier({} as any)).toThrow(ChirpierError);
-    });
-
-    test("should throw error if key is not a valid JWT", () => {
-      expect(() => initialize({ key: "invalid_key" })).toThrow(ChirpierError);
-    });
-
-    test("should initialize successfully with a valid JWT", () => {
-      const validJWT = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
-      expect(() => initialize({ key: validJWT })).not.toThrow();
-    });
-  });
-
-  describe("monitor", () => {
-    test("event should be sent", async () => {
-      chirpier = new Chirpier({
-        key: "api_key",
-      });
-
-      // Setup mock server
-      const mock = new MockAdapter(axios);
-      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
-
-      const validJWT = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
-      initialize({ key: validJWT });
-  
-      const event: Event = {
-        group_id: "f3438ee9-b964-48aa-b938-a803df440a3c",
-        stream: "test-stream",
-        value: 1,
-      };
-
-      await chirpier.monitor(event);
-
-      await new Promise(resolve => setTimeout(resolve, 1000)); // Wait for flush
-
-      expect(mock.history.post.length).toBe(1);
-      expect(mock.history.post[0].url).toBe(DEFAULT_API_ENDPOINT);
-      expect(JSON.parse(mock.history.post[0].data)).toEqual([
-        {
-          group_id: "f3438ee9-b964-48aa-b938-a803df440a3c",
-          stream: "test-stream",
-          value: 1,
-        },
-      ]);
-
-      // Clean up the mock
-      mock.reset();
-    });
-
-    test("should throw error for invalid event", async () => {
-      chirpier = new Chirpier({
-        key: "api_key",
-      });
-      const invalidEvent = {
-        group_id: "f3438ee9-b964-48aa-b938-a803df440a3c",
-      } as any;
-      await expect(chirpier.monitor(invalidEvent)).rejects.toThrow(
-        ChirpierError
-      );
-
-      // Clean up the mock
-      const mock = new MockAdapter(axios);
-      mock.reset();
-    });
-
-    test("should batch events and flush when batch size is reached", async () => {
-      const mock = new MockAdapter(axios);
-      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
-
-      const validJWT = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
-      initialize({ key: validJWT, batchSize: 2 });
-
-      const event: Event = {
-        group_id: "f3438ee9-b964-48aa-b938-a803df440a3c",
-        stream: "test-stream",
-        value: 1,
-      };
-
-      monitor(event);
-      monitor(event);
-
-      await new Promise(resolve => setTimeout(resolve, 100)); // Wait for flush
-
-      expect(mock.history.post.length).toBe(1);
-      expect(JSON.parse(mock.history.post[0].data).length).toBe(2);
-
-      mock.reset();
-    });
-
-    test("should flush events after interval", async () => {
-      const mock = new MockAdapter(axios);
-      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
-
-      const validJWT = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
-      initialize({ key: validJWT, flushInterval: 100 });
-
-      const event: Event = {
-        group_id: "f3438ee9-b964-48aa-b938-a803df440a3c",
-        stream: "test-stream",
-        value: 1,
-      };
-
-      monitor(event);
-
-      await new Promise(resolve => setTimeout(resolve, 1000)); // Wait for flush
-
-      expect(mock.history.post.length).toBe(1);
-      expect(JSON.parse(mock.history.post[0].data).length).toBe(1);
-
-      mock.reset();
-    });
-
-    test("should use provided event_id if available", async () => {
-      const mock = new MockAdapter(axios);
-      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
-
-      const validJWT = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
-      initialize({ key: validJWT });
-
-      const event: Event = {
-        group_id: "f3438ee9-b964-48aa-b938-a803df440a3c",
-        stream: "test-stream",
-        value: 1,
-        event_id: "f3438ee9-b964-48aa-b938-a803df440a3c",
-      };
-
-      monitor(event);
-
-      await new Promise(resolve => setTimeout(resolve, 1000)); // Wait for flush
-
-      expect(mock.history.post.length).toBe(1);
-      expect(JSON.parse(mock.history.post[0].data)[0].event_id).toBe("f3438ee9-b964-48aa-b938-a803df440a3c");
-
-      mock.reset();
-    });
-
-    test("should generate event_id if not provided", async () => {
-      const mock = new MockAdapter(axios);
-      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
-
-      (uuidv4 as jest.Mock).mockReturnValue("generated-uuid");
-
-      const validJWT = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
-      initialize({ key: validJWT });
-
-      const event: Event = {
-        group_id: "f3438ee9-b964-48aa-b938-a803df440a3c",
-        stream: "test-stream",
-        value: 1,
-      };
-
-      monitor(event);
-
-      await new Promise(resolve => setTimeout(resolve, 1000)); // Wait for flush
-
-      expect(mock.history.post.length).toBe(1);
-      expect(JSON.parse(mock.history.post[0].data)[0].event_id).toBe("generated-uuid");
-
-      mock.reset();
-    });
-  });
-});