couchbase 4.6.0 → 4.7.0-dev.1

package/dist/logger.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Represents log levels in ascending order of severity.
+ *
+ * Log levels follow standard severity conventions.
+ *
+ * - TRACE: Finest-grained informational events for detailed debugging.
+ * - DEBUG: Detailed informational events useful for debugging.
+ * - INFO: Informational messages highlighting application progress.
+ * - WARN: Potentially harmful situations that warrant attention.
+ * - ERROR: Error events that might still allow the application to continue.
+ *
+ * @category Logging
+ */
+export declare enum LogLevel {
+    /**
+     * Finest-grained informational events, typically used for detailed debugging.
+     */
+    TRACE = 0,
+    /**
+     * Detailed informational events useful for debugging an application.
+     */
+    DEBUG = 1,
+    /**
+     * Informational messages that highlight the progress of the application.
+     */
+    INFO = 2,
+    /**
+     * Potentially harmful situations that warrant attention.
+     */
+    WARN = 3,
+    /**
+     * Error events that might still allow the application to continue running.
+     */
+    ERROR = 4
+}
+/**
+ * Parses a log level from either a string or LogLevel enum value.
+ *
+ * When a string is provided, the parsing is case-insensitive.
+ *
+ * @param level - The log level as a string or LogLevel enum value.
+ * @returns {LogLevel | undefined} The corresponding LogLevel enum value, or undefined if invalid.
+ *
+ * @category Logging
+ */
+export declare function parseLogLevel(level: LogLevel | string): LogLevel | undefined;
+/**
+ * Interface for logging operations within the Couchbase SDK.
+ *
+ * All logging methods are optional, allowing implementers to choose which
+ * log levels to support.
+ *
+ * @category Logging
+ */
+export interface Logger {
+    /**
+     * Logs a message at the TRACE level.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    trace?(message: string, ...args: any[]): void;
+    /**
+     * Logs a message at the DEBUG level.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    debug?(message: string, ...args: any[]): void;
+    /**
+     * Logs a message at the INFO level.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    info?(message: string, ...args: any[]): void;
+    /**
+     * Logs a message at the WARN level.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    warn?(message: string, ...args: any[]): void;
+    /**
+     * Logs a message at the ERROR level.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    error?(message: string, ...args: any[]): void;
+}
+/**
+ * A no-operation logger implementation that discards all log messages.
+ *
+ * @category Logging
+ */
+export declare class NoOpLogger implements Logger {
+    /**
+     * No-op implementation of trace logging.
+     */
+    trace(): void;
+    /**
+     * No-op implementation of debug logging.
+     */
+    debug(): void;
+    /**
+     * No-op implementation of info logging.
+     */
+    info(): void;
+    /**
+     * No-op implementation of warn logging.
+     */
+    warn(): void;
+    /**
+     * No-op implementation of error logging.
+     */
+    error(): void;
+}
+/**
+ * A safe wrapper around user-provided Logger implementations.
+ *
+ * This wrapper ensures that calling any logging method is always safe, even if the
+ * underlying logger is undefined or the underlying logger only implements a subset
+ * of methods.
+ *
+ * @category Logging
+ */
+export declare class CouchbaseLogger implements Logger {
+    private readonly _logger?;
+    /**
+     * Creates a new CouchbaseLogger wrapper.
+     *
+     * @param logger - Optional user-provided logger implementation.
+     *                 Can be undefined or implement only a subset of methods.
+     */
+    constructor(logger?: Logger);
+    /**
+     * Logs a message at the TRACE level if the underlying logger implements it.
+     *
+     * If the logger is undefined or doesn't implement trace, this is a no-op.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    trace(message: string, ...args: any[]): void;
+    /**
+     * Logs a message at the DEBUG level if the underlying logger implements it.
+     *
+     * If the logger is undefined or doesn't implement debug, this is a no-op.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    debug(message: string, ...args: any[]): void;
+    /**
+     * Logs a message at the INFO level if the underlying logger implements it.
+     *
+     * If the logger is undefined or doesn't implement info, this is a no-op.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    info(message: string, ...args: any[]): void;
+    /**
+     * Logs a message at the WARN level if the underlying logger implements it.
+     *
+     * If the logger is undefined or doesn't implement warn, this is a no-op.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    warn(message: string, ...args: any[]): void;
+    /**
+     * Logs a message at the ERROR level if the underlying logger implements it.
+     *
+     * If the logger is undefined or doesn't implement error, this is a no-op.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    error(message: string, ...args: any[]): void;
+}
+/**
+ * Creates a CouchbaseLogger that outputs to the console up to the specified log level.
+ *
+ * @param logLevel - The log level to output to the console.
+ * @param prefix - Optional prefix to prepend to all log messages.
+ * @returns {CouchbaseLogger} A CouchbaseLogger configured for console output.
+ *
+ * @category Logging
+ */
+export declare function createConsoleLogger(logLevel: LogLevel, prefix?: string): CouchbaseLogger;

package/dist/logger.js

@@ -0,0 +1,213 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConsoleLogger = exports.CouchbaseLogger = exports.NoOpLogger = exports.parseLogLevel = exports.LogLevel = void 0;
+/**
+ * Represents log levels in ascending order of severity.
+ *
+ * Log levels follow standard severity conventions.
+ *
+ * - TRACE: Finest-grained informational events for detailed debugging.
+ * - DEBUG: Detailed informational events useful for debugging.
+ * - INFO: Informational messages highlighting application progress.
+ * - WARN: Potentially harmful situations that warrant attention.
+ * - ERROR: Error events that might still allow the application to continue.
+ *
+ * @category Logging
+ */
+var LogLevel;
+(function (LogLevel) {
+    /**
+     * Finest-grained informational events, typically used for detailed debugging.
+     */
+    LogLevel[LogLevel["TRACE"] = 0] = "TRACE";
+    /**
+     * Detailed informational events useful for debugging an application.
+     */
+    LogLevel[LogLevel["DEBUG"] = 1] = "DEBUG";
+    /**
+     * Informational messages that highlight the progress of the application.
+     */
+    LogLevel[LogLevel["INFO"] = 2] = "INFO";
+    /**
+     * Potentially harmful situations that warrant attention.
+     */
+    LogLevel[LogLevel["WARN"] = 3] = "WARN";
+    /**
+     * Error events that might still allow the application to continue running.
+     */
+    LogLevel[LogLevel["ERROR"] = 4] = "ERROR";
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
+/**
+ * @internal
+ */
+const LOG_LEVEL_NAMES = ['trace', 'debug', 'info', 'warn', 'error'];
+/**
+ * Parses a log level from either a string or LogLevel enum value.
+ *
+ * When a string is provided, the parsing is case-insensitive.
+ *
+ * @param level - The log level as a string or LogLevel enum value.
+ * @returns {LogLevel | undefined} The corresponding LogLevel enum value, or undefined if invalid.
+ *
+ * @category Logging
+ */
+function parseLogLevel(level) {
+    if (typeof level === 'number') {
+        return level >= LogLevel.TRACE && level <= LogLevel.ERROR
+            ? level
+            : undefined;
+    }
+    const normalized = level.toLowerCase();
+    const index = LOG_LEVEL_NAMES.indexOf(normalized);
+    return index >= 0 ? index : undefined;
+}
+exports.parseLogLevel = parseLogLevel;
+/**
+ * A no-operation logger implementation that discards all log messages.
+ *
+ * @category Logging
+ */
+class NoOpLogger {
+    /**
+     * No-op implementation of trace logging.
+     */
+    trace() { }
+    /**
+     * No-op implementation of debug logging.
+     */
+    debug() { }
+    /**
+     * No-op implementation of info logging.
+     */
+    info() { }
+    /**
+     * No-op implementation of warn logging.
+     */
+    warn() { }
+    /**
+     * No-op implementation of error logging.
+     */
+    error() { }
+}
+exports.NoOpLogger = NoOpLogger;
+/**
+ * A safe wrapper around user-provided Logger implementations.
+ *
+ * This wrapper ensures that calling any logging method is always safe, even if the
+ * underlying logger is undefined or the underlying logger only implements a subset
+ * of methods.
+ *
+ * @category Logging
+ */
+class CouchbaseLogger {
+    /**
+     * Creates a new CouchbaseLogger wrapper.
+     *
+     * @param logger - Optional user-provided logger implementation.
+     *                 Can be undefined or implement only a subset of methods.
+     */
+    constructor(logger) {
+        this._logger = logger;
+    }
+    /**
+     * Logs a message at the TRACE level if the underlying logger implements it.
+     *
+     * If the logger is undefined or doesn't implement trace, this is a no-op.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    trace(message, ...args) {
+        var _a, _b;
+        (_b = (_a = this._logger) === null || _a === void 0 ? void 0 : _a.trace) === null || _b === void 0 ? void 0 : _b.call(_a, message, ...args);
+    }
+    /**
+     * Logs a message at the DEBUG level if the underlying logger implements it.
+     *
+     * If the logger is undefined or doesn't implement debug, this is a no-op.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    debug(message, ...args) {
+        var _a, _b;
+        (_b = (_a = this._logger) === null || _a === void 0 ? void 0 : _a.debug) === null || _b === void 0 ? void 0 : _b.call(_a, message, ...args);
+    }
+    /**
+     * Logs a message at the INFO level if the underlying logger implements it.
+     *
+     * If the logger is undefined or doesn't implement info, this is a no-op.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    info(message, ...args) {
+        var _a, _b;
+        (_b = (_a = this._logger) === null || _a === void 0 ? void 0 : _a.info) === null || _b === void 0 ? void 0 : _b.call(_a, message, ...args);
+    }
+    /**
+     * Logs a message at the WARN level if the underlying logger implements it.
+     *
+     * If the logger is undefined or doesn't implement warn, this is a no-op.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    warn(message, ...args) {
+        var _a, _b;
+        (_b = (_a = this._logger) === null || _a === void 0 ? void 0 : _a.warn) === null || _b === void 0 ? void 0 : _b.call(_a, message, ...args);
+    }
+    /**
+     * Logs a message at the ERROR level if the underlying logger implements it.
+     *
+     * If the logger is undefined or doesn't implement error, this is a no-op.
+     *
+     * @param message - The message to log.
+     * @param args - Optional additional arguments for formatting or context.
+     */
+    error(message, ...args) {
+        var _a, _b;
+        (_b = (_a = this._logger) === null || _a === void 0 ? void 0 : _a.error) === null || _b === void 0 ? void 0 : _b.call(_a, message, ...args);
+    }
+}
+exports.CouchbaseLogger = CouchbaseLogger;
+/**
+ * Creates a CouchbaseLogger that outputs to the console up to the specified log level.
+ *
+ * @param logLevel - The log level to output to the console.
+ * @param prefix - Optional prefix to prepend to all log messages.
+ * @returns {CouchbaseLogger} A CouchbaseLogger configured for console output.
+ *
+ * @category Logging
+ */
+function createConsoleLogger(logLevel, prefix) {
+    const consoleImpl = {};
+    const formatMessage = (msg) => (prefix ? `${prefix} ${msg}` : msg);
+    if (logLevel <= LogLevel.TRACE) {
+        consoleImpl.trace = (message, ...args) => {
+            console.trace(formatMessage(message), ...args);
+        };
+    }
+    if (logLevel <= LogLevel.DEBUG) {
+        consoleImpl.debug = (message, ...args) => {
+            console.debug(formatMessage(message), ...args);
+        };
+    }
+    if (logLevel <= LogLevel.INFO) {
+        consoleImpl.info = (message, ...args) => {
+            console.info(formatMessage(message), ...args);
+        };
+    }
+    if (logLevel <= LogLevel.WARN) {
+        consoleImpl.warn = (message, ...args) => {
+            console.warn(formatMessage(message), ...args);
+        };
+    }
+    if (logLevel <= LogLevel.ERROR) {
+        consoleImpl.error = (message, ...args) => {
+            console.error(formatMessage(message), ...args);
+        };
+    }
+    return new CouchbaseLogger(consoleImpl);
+}
+exports.createConsoleLogger = createConsoleLogger;

package/dist/loggingmeter.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @internal
+ */
+import { CouchbaseLogger } from './logger';
+import { Meter, ValueRecorder } from './metrics';
+/**
+ * Represents the percentile values for a set of recorded metrics.
+ *
+ * @internal
+ */
+interface PercentileReport {
+    /**
+     * Total count of all recorded values.
+     */
+    total_count: number;
+    /**
+     * Mapping of percentile value (e.g., "50", "90") to recorded value.
+     */
+    percentiles_us: Record<string, number>;
+}
+/**
+ * Represents a complete logging meter report with metadata.
+ *
+ * @internal
+ */
+interface LoggingMeterReport {
+    /**
+     * Metadata about the report.
+     */
+    meta: {
+        /**
+         * The interval (in seconds) at which reports are emitted.
+         */
+        emit_interval_s: number;
+    };
+    /**
+     * Operations organized by service type.
+     */
+    operations: Record<string, Record<string, PercentileReport>>;
+}
+/**
+ * Internal class for periodically emitting meter reports.
+ *
+ * @internal
+ */
+declare class LoggingMeterReporter {
+    private readonly _loggingMeter;
+    private readonly _emitInterval;
+    private readonly _logger;
+    private _timerId;
+    private _stopped;
+    constructor(loggingMeter: LoggingMeter, emitInterval: number, logger: CouchbaseLogger);
+    /**
+     * @internal
+     */
+    start(): void;
+    /**
+     * @internal
+     */
+    stop(): void;
+    /**
+     * @internal
+     */
+    report(): void;
+    /**
+     * @internal
+     */
+    toJSON(): Record<string, any>;
+}
+/**
+ * A logging-based meter implementation that records metrics using HDR histograms
+ * and periodically reports percentile statistics.
+ *
+ * @internal
+ */
+export declare class LoggingMeter implements Meter {
+    private readonly _recorders;
+    private readonly _reporter;
+    private readonly _emitInterval;
+    /**
+     * Creates a new LoggingMeter with the specified flush interval.
+     *
+     * @param logger - The logger to be used by the LoggingMeter.
+     * @param emitInterval - The interval in milliseconds between reports (default: 600000ms = 10 minutes).
+     */
+    constructor(logger: CouchbaseLogger, emitInterval?: number);
+    /**
+     * Gets the meter's LoggingMeterReporter.
+     *
+     * @internal
+     */
+    get reporter(): LoggingMeterReporter;
+    /**
+     * Gets or creates a value recorder for the specified metric name and tags.
+     *
+     * @param _name - Unused.
+     * @param tags - Key-value pairs that categorize the metric.
+     * @returns A value recorder for recording values.
+     */
+    valueRecorder(_name: string, tags: Record<string, string>): ValueRecorder;
+    /**
+     * Creates a report of all recorded metrics and resets the histograms.
+     *
+     * @returns The logging meter report with percentile statistics.
+     */
+    createReport(): LoggingMeterReport | null;
+    /**
+     * Stops the threshold logging reporter and cleans up resources.
+     *
+     * This method should be called when shutting down the application or when
+     * the tracer is no longer needed to ensure the periodic reporting timer
+     * is properly cleared.
+     */
+    cleanup(): void;
+    /**
+     * @internal
+     */
+    toJSON(): Record<string, any>;
+}
+export {};