@movibe/logger v1.3.1

@movibe/logger

A TypeScript-based universal logging solution that provides consistent logging across different platforms and environments.

Features

• 🌟 Universal Compatibility - Works across Node.js, browsers, and other JavaScript runtimes
• 🔒 Type Safety - Built with TypeScript for robust type checking
• 📦 Multiple Transports - Support for console, file, and custom transport layers
• 🎯 Configurable Levels - Flexible log level configuration
• 🚀 Performance Optimized - Minimal overhead for production environments
• 🔍 Context Support - Rich contextual logging capabilities
• 📊 Structured Logging - JSON-based log format for better parsing

Table of Contents

• @movibe/logger
  • Features
  • Table of Contents
  • Installation
  • Type Definitions
  • Basic Usage
    • Creating a Custom Logger
    • Using the Custom Logger
  • Advanced Features
    • User Tracking
    • Screen Tracking
    • Error Handling
    • E-commerce Tracking
    • Custom Events
  • API Reference
    • Core Methods
    • User Methods
    • E-commerce Methods
  • Contributing
  • License

Installation

npm install @movibe/logger
# or
yarn add @movibe/logger
# or
bun add @movibe/logger

Type Definitions

Define your custom types for type-safe logging:

// Log tags for different types of logs
type CustomLogTags = "custom_start" | "custom_end";

// Network tags for API and GraphQL operations
type CustomNetworkTags =
  | "GraphqlQuery_error_graphql"
  | "RestApi_error"
  | "api_call"
  | "websocket";

// User properties interface
interface CustomUser {
  id: string;
  role: string;
  email?: string;
  name?: string;
  phone?: string;
  status?: string;
}

// E-commerce checkout interface
interface CustomCheckout {
  currency?: string;
  value?: number;
  customField: string;
}

// Purchase information interface
interface CustomPurchase {
  type: "credit_card";
  customStatus: string;
  affiliation?: string;
  coupon?: string;
  currency?: string;
}

// Custom events with their respective payloads
type CustomEvent = {
  "app-open": Record<string, never>;
  "user-login": { method: string };
  "user-register": { method: string };
  "add-to-cart": { product_id: string; quantity: number };
  "remove-from-cart": { product_id: string; quantity: number };
};

Basic Usage

Creating a Custom Logger

Primeiro, crie sua classe customizada implementando a interface LoggerStrategyType:

import { LoggerStrategyType } from "@movibe/logger";

const TAG = "DEBUG";

// Define your custom types
type CustomLogTags = "custom_start" | "custom_end";
type CustomNetworkTags =
  | "GraphqlQuery_error_graphql"
  | "RestApi_error"
  | "api_call"
  | "websocket";
interface CustomUser {
  id: string;
  role: string;
  email?: string;
  name?: string;
  phone?: string;
  status?: string;
}
interface CustomCheckout {
  currency?: string;
  value?: number;
  customField: string;
}
interface CustomPurchase {
  type: "credit_card";
  customStatus: string;
  affiliation?: string;
  coupon?: string;
  currency?: string;
}

type CustomEvent = {
  "app-open": Record<string, never>;
  "user-login": { method: string };
  "user-register": { method: string };
  "add-to-cart": { product_id: string; quantity: number };
  "remove-from-cart": { product_id: string; quantity: number };
};

// Implement your custom logger
export class DebugLogger
  implements
    LoggerStrategyType<
      CustomLogTags,
      CustomNetworkTags,
      CustomUser,
      CustomCheckout,
      CustomPurchase,
      CustomEvent
    >
{
  init(): void {
    console.log(`${TAG}.init`);
  }

  info(feature: string, name: string, properties?: any): void {
    console.log(`${TAG}.info: `, feature, name, properties);
  }

  error(
    feature: string,
    name: string,
    critical = false,
    error: Error,
    extra: Record<string, unknown> = {}
  ): void {
    console.error(`${TAG}.error: `, { critical, error, extra, feature, name });
  }

  event(name: string, properties?: Record<string, any>): void {
    if (properties) {
      console.log(`${TAG}.event: `, name, properties);
    } else {
      console.log(`${TAG}.event: `, name);
    }
  }

  network(name: CustomNetworkTags, properties?: Record<string, any>): void {
    if (properties) {
      console.log(
        `${TAG}.network: ${properties.operationName} | `,
        name,
        properties
      );
    } else {
      console.log(`${TAG}.network:`, name);
    }
  }

  logScreen(screenName: string, properties?: Record<string, any>): void {
    console.log(`${TAG}.logScreen: `, { screenName, ...properties });
  }

  setUser(user: CustomUser): void {
    const userProperties = {
      email: user.email ?? "",
      id: user.id,
      name: user.name ?? "",
      phone: user.phone,
      status: user.status,
    };

    console.log(`${TAG}.setUser: `, userProperties);
    this.setUserId(user.id);
  }

  setUserId(userId: string): void {
    console.log(`${TAG}.setUserId: `, userId);
  }

  setUserProperty(name: string, value: any): void {
    console.log(`${TAG}.setUserProperty: `, name, value);
  }

  setUserProperties(properties: CustomUser): void {
    console.log(`${TAG}.setUserProperties: `, properties);
  }

  logBeginCheckout(checkoutId: string, properties: CustomCheckout): void {
    console.log(`${TAG}.logBeginCheckout: `, checkoutId, properties);
  }

  logPaymentSuccess(checkoutId: string, properties: CustomPurchase): void {
    console.log(`${TAG}.logPaymentSuccess: `, checkoutId, properties);
  }

  reset(): void {
    console.log(`${TAG}.reset`);
  }

  flush(): void {
    console.log(`${TAG}.flush`);
  }

  getId(): string {
    return "DebugLogger";
  }
}

Using the Custom Logger

Depois de criar sua classe customizada, você pode usá-la em qualquer parte da aplicação:

import { LoggerStrategy } from "@movibe/logger";
import { DebugLogger } from "./debug-logger";

// Initialize with custom logger
const logger = new LoggerStrategy<
  CustomLogTags,
  CustomNetworkTags,
  CustomUser,
  CustomCheckout,
  CustomPurchase,
  CustomEvent
>([
  {
    class: new DebugLogger(),
    enabled: true,
  },
]);

// Initialize logger
logger.init();

// Log events with type safety
logger.event("app-open");

// User tracking with custom fields
logger.setUser({
  id: "123",
  role: "user",
  name: "John Doe",
  email: "john@example.com",
  phone: "+1234567890",
  status: "active",
});

// Screen tracking with custom properties
logger.logScreen("HomeScreen", {
  referrer: "DeepLink",
  customData: "test",
});

// Error tracking with context
try {
  throw new Error("Test error");
} catch (error) {
  logger.error("Authentication", "login-failed", true, error as Error, {
    userId: "123",
  });
}

// E-commerce tracking with custom fields
logger.logBeginCheckout("checkout-123", {
  currency: "USD",
  value: 99.99,
  customField: "test-checkout",
});

logger.logPaymentSuccess("checkout-123", {
  type: "credit_card",
  customStatus: "completed",
  currency: "USD",
  affiliation: "web-store",
  coupon: "DISCOUNT10",
});

// Reset and flush
logger.reset();
logger.flush();

Advanced Features

User Tracking

Track user information and properties:

// Set complete user object
logger.setUser({
  id: "123",
  role: "user",
  name: "John Doe",
  email: "john@example.com",
});

// Set individual user property
logger.setUserProperty("plan", "premium");

// Set user ID only
logger.setUserId("123");

Screen Tracking

Track screen views and navigation:

// Basic screen view
logger.logScreen("HomeScreen");

// Screen view with context
logger.logScreen("ProductScreen", {
  referrer: "HomeScreen",
  productId: "123",
});

Error Handling

Comprehensive error tracking:

try {
  throw new Error("API Request Failed");
} catch (error) {
  logger.error(
    "API", // Feature/component
    "request-failed", // Error type
    true, // Is critical error
    error as Error, // Error object
    {
      // Additional context
      endpoint: "/users",
      method: "GET",
      statusCode: 500,
    }
  );
}

E-commerce Tracking

Track e-commerce events and transactions:

// Begin checkout process
logger.logBeginCheckout("checkout-123", {
  currency: "USD",
  value: 99.99,
  customField: "premium-plan",
});

// Track successful payment
logger.logPaymentSuccess("checkout-123", {
  type: "credit_card",
  customStatus: "completed",
  currency: "USD",
  affiliation: "web-store",
});

Custom Events

Track custom events with type safety:

// Track login event
logger.event("user-login", {
  method: "email",
});

// Track cart action
logger.event("add-to-cart", {
  product_id: "prod_123",
  quantity: 1,
});

API Reference

Core Methods

• init() - Initialize the logger
• event(name, properties?) - Log custom events
• error(feature, name, critical, error, extra?) - Log errors
• logScreen(name, properties?) - Track screen views
• setUser(user) - Set user information
• reset() - Reset all user data
• flush() - Flush pending logs

User Methods

• setUserId(id) - Set user ID
• setUserProperty(name, value) - Set single user property
• setUserProperties(properties) - Set multiple user properties

E-commerce Methods

• logBeginCheckout(checkoutId, properties) - Track checkout initiation
• logPaymentSuccess(checkoutId, properties) - Track successful payments

For more detailed documentation, please visit our docs directory.

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.