feat: Add log level functionality with LogLevel enum and logger methods

[jkebinger]

Summary

This PR restores log level functionality similar to the predecessor project (prefab-cloud-js) with a simplified, non-hierarchical approach suitable for client-side evaluation.

Changes

New Features

1. LogLevel Enum

• Public LogLevel enum with values: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
• Exported for use in application code

2. getLogLevel(loggerName) Method

• Returns a LogLevel enum value
• Looks up configured logger key (default: "log-levels.default")
• Returns LogLevel.DEBUG as default if not configured
• Note: loggerName parameter currently unused (all loggers share same level)

3. Logger Convenience Methods

• New reforge.logger.* API with methods: trace(), debug(), info(), warn(), error(), fatal()
• Automatically checks configured log level before logging
• Maps to appropriate console methods
• Simple, clean API: reforge.logger.info("message")

4. Helper Functions

• shouldLogAtLevel(configuredLevel, desiredLevel) - Compare LogLevel enum values (recommended)
• getLogLevelSeverity(level) - Get numeric severity for manual comparison

5. Configuration

• New optional loggerKey init parameter (default: "log-levels.default")
• All loggers share the same global log level

Breaking Changes

shouldLog() No Longer Traverses Hierarchy

• Old behavior: Traversed logger name hierarchy (e.g., log-level.my.app → log-level.my → log-level)
• New behavior: Exact key match only (log-level.{loggerName})
• Reason: Client-side evaluation with single context means hierarchy traversal isn't meaningful

This simplification aligns with the architectural constraint that the server evaluates configs once per request with a single context.

Test Coverage

• Added 18 new test cases
• All 73 tests passing
• Coverage includes:
  • LogLevel enum values
  • getLogLevel() with various configurations
  • Logger methods at all levels
  • Helper functions (shouldLogAtLevel, getLogLevelSeverity)
  • shouldLog() exact match behavior

Documentation

• Updated README with comprehensive sections:
  • getLogLevel() usage and configuration
  • logger.* methods with examples
  • LogLevel comparison helpers
  • Console method mapping
  • Updated shouldLog() docs to reflect no-hierarchy behavior

Example Usage

import { reforge, LogLevel, Context } from "@reforge-com/javascript";

await reforge.init({
  sdkKey: "your-key",
  context: new Context({ user: { id: "123" } }),
  loggerKey: "log-levels.default", // optional
});

// Configure log level
reforge.hydrate({ "log-levels.default": "INFO" });

// Use the logger
reforge.logger.debug("Debug message");  // Not logged (below INFO)
reforge.logger.info("Info message");    // ✓ Logged
reforge.logger.warn("Warning");         // ✓ Logged
reforge.logger.error("Error");          // ✓ Logged

// Or check level programmatically
const level = reforge.getLogLevel("my.logger");
if (shouldLogAtLevel(level, LogLevel.DEBUG)) {
  console.debug("Debug details");
}

Migration Notes

If you were using shouldLog() with hierarchical logger names, you'll need to:

• Update to use exact key matches for log-level.{loggerName} configs
• OR switch to using reforge.logger.* methods with the global log level
• OR use getLogLevel() + shouldLogAtLevel() for programmatic checks

🤖 Generated with Claude Code

[jdwyah]

thanks