@contentful/optimization-api-client 0.1.0-alpha → 0.1.0-alpha11

package/dist/logger.d.cts

@@ -0,0 +1,287 @@
+/**
+ * A {@link LogSink} that writes log events to the browser or Node.js console,
+ * filtering by a configurable verbosity threshold.
+ *
+ * @example
+ * ```typescript
+ * import { logger, ConsoleLogSink } from '@contentful/optimization-api-client/logger'
+ *
+ * logger.addSink(new ConsoleLogSink('debug'))
+ * ```
+ *
+ * @public
+ */
+export declare class ConsoleLogSink extends LogSink {
+    /** Identifies this sink when registered with the {@link Logger}. */
+    name: string;
+    /**
+     * Minimum log level required for events to be output.
+     *
+     * @defaultValue 'error'
+     */
+    readonly verbosity: LogLevels;
+    /**
+     * Creates a new ConsoleLogSink.
+     *
+     * @param verbosity - Minimum log level to output.
+     */
+    constructor(verbosity?: LogLevels);
+    /**
+     * Writes a log event to the console if its level meets the verbosity threshold.
+     *
+     * @param event - The log event to process.
+     * @returns Nothing.
+     */
+    ingest(event: LogEvent): void;
+}
+
+/**
+ * Creates a {@link ScopedLogger} that automatically prepends the given location to every log call.
+ *
+ * @param location - The module or component identifier to prepend.
+ * @returns A {@link ScopedLogger} bound to the specified location.
+ *
+ * @example
+ * ```typescript
+ * import { createScopedLogger } from '@contentful/optimization-api-client/logger'
+ *
+ * const log = createScopedLogger('MyModule')
+ * log.info('Initialization complete')
+ * ```
+ *
+ * @public
+ */
+export declare function createScopedLogger(location: string): ScopedLogger;
+
+/**
+ * A log event emitted by the logger package.
+ *
+ * @public
+ */
+export declare interface LogEvent {
+    /** Logger scope name. */
+    name: string;
+    /** Event severity level. */
+    level: LogLevels;
+    /** Event payload, where the first entry is the formatted message. */
+    messages: unknown[];
+    /** Optional additional context attached by sinks or middleware. */
+    [other: string]: unknown;
+}
+
+/**
+ * Central logger that routes log events through registered {@link LogSink} instances.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from '@contentful/optimization-api-client/logger'
+ *
+ * logger.info('MyModule', 'Application started')
+ * ```
+ *
+ * @public
+ */
+declare class Logger {
+    /** The logger's identifier, used as the event scope name. */
+    readonly name = "@contentful/optimization";
+    private readonly PREFIX_PARTS;
+    private readonly DELIMITER;
+    private sinks;
+    private assembleLocationPrefix;
+    /**
+     * Registers a log sink. If a sink with the same name already exists, it is replaced.
+     *
+     * @param sink - The {@link LogSink} instance to register.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * import { logger, ConsoleLogSink } from '@contentful/optimization-api-client/logger'
+     *
+     * logger.addSink(new ConsoleLogSink('debug'))
+     * ```
+     */
+    addSink(sink: LogSink): void;
+    /**
+     * Removes a registered sink by name.
+     *
+     * @param name - The name of the sink to remove.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.removeSink('ConsoleLogSink')
+     * ```
+     */
+    removeSink(name: string): void;
+    /**
+     * Removes all registered sinks.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.removeSinks()
+     * ```
+     */
+    removeSinks(): void;
+    /**
+     * Logs a message at the debug level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.debug('MyModule', 'Debugging value', someVariable)
+     * ```
+     */
+    debug(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the info level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.info('MyModule', 'Operation completed')
+     * ```
+     */
+    info(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the log level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.log('MyModule', 'General log entry')
+     * ```
+     */
+    log(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the warn level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.warn('MyModule', 'Deprecated method called')
+     * ```
+     */
+    warn(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the error level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message or Error object.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.error('MyModule', new Error('Something failed'))
+     * ```
+     */
+    error(logLocation: string, message: string | Error, ...args: unknown[]): void;
+    /**
+     * Logs a message at the fatal level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message or Error object.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.fatal('MyModule', new Error('Unrecoverable failure'))
+     * ```
+     */
+    fatal(logLocation: string, message: string | Error, ...args: unknown[]): void;
+    private emit;
+    private onLogEvent;
+}
+export { Logger }
+export default Logger;
+
+/**
+ * Shared singleton {@link Logger} instance used across the SDK.
+ *
+ * @public
+ */
+export declare const logger: Logger;
+
+/**
+ * Supported log levels ordered from highest to lowest severity.
+ *
+ * @public
+ */
+export declare type LogLevels = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'log';
+
+/**
+ * Numeric severity map used for log-level threshold comparisons.
+ *
+ * @public
+ */
+export declare const logLevelSeverity: Readonly<Record<LogLevels, number>>;
+
+/**
+ * Abstract base class for log sinks that receive and process log events.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomSink extends LogSink {
+ *   name = 'MyCustomSink'
+ *
+ *   ingest(event: LogEvent): void {
+ *     // process the event
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare abstract class LogSink {
+    /** Display name used to identify this sink for addition and removal. */
+    abstract name: string;
+    /**
+     * Processes an incoming log event.
+     *
+     * @param event - The log event to process.
+     * @returns Nothing.
+     */
+    abstract ingest(event: LogEvent): void;
+}
+
+/**
+ * A location-scoped logger interface whose methods omit the `logLocation` parameter.
+ *
+ * @public
+ */
+export declare interface ScopedLogger {
+    /** Logs at debug level. */
+    debug: (message: string, ...args: unknown[]) => void;
+    /** Logs at info level. */
+    info: (message: string, ...args: unknown[]) => void;
+    /** Logs at log level. */
+    log: (message: string, ...args: unknown[]) => void;
+    /** Logs at warn level. */
+    warn: (message: string, ...args: unknown[]) => void;
+    /** Logs at error level. */
+    error: (message: string | Error, ...args: unknown[]) => void;
+    /** Logs at fatal level. */
+    fatal: (message: string | Error, ...args: unknown[]) => void;
+}
+
+export { }

package/dist/logger.d.mts

@@ -0,0 +1,287 @@
+/**
+ * A {@link LogSink} that writes log events to the browser or Node.js console,
+ * filtering by a configurable verbosity threshold.
+ *
+ * @example
+ * ```typescript
+ * import { logger, ConsoleLogSink } from '@contentful/optimization-api-client/logger'
+ *
+ * logger.addSink(new ConsoleLogSink('debug'))
+ * ```
+ *
+ * @public
+ */
+export declare class ConsoleLogSink extends LogSink {
+    /** Identifies this sink when registered with the {@link Logger}. */
+    name: string;
+    /**
+     * Minimum log level required for events to be output.
+     *
+     * @defaultValue 'error'
+     */
+    readonly verbosity: LogLevels;
+    /**
+     * Creates a new ConsoleLogSink.
+     *
+     * @param verbosity - Minimum log level to output.
+     */
+    constructor(verbosity?: LogLevels);
+    /**
+     * Writes a log event to the console if its level meets the verbosity threshold.
+     *
+     * @param event - The log event to process.
+     * @returns Nothing.
+     */
+    ingest(event: LogEvent): void;
+}
+
+/**
+ * Creates a {@link ScopedLogger} that automatically prepends the given location to every log call.
+ *
+ * @param location - The module or component identifier to prepend.
+ * @returns A {@link ScopedLogger} bound to the specified location.
+ *
+ * @example
+ * ```typescript
+ * import { createScopedLogger } from '@contentful/optimization-api-client/logger'
+ *
+ * const log = createScopedLogger('MyModule')
+ * log.info('Initialization complete')
+ * ```
+ *
+ * @public
+ */
+export declare function createScopedLogger(location: string): ScopedLogger;
+
+/**
+ * A log event emitted by the logger package.
+ *
+ * @public
+ */
+export declare interface LogEvent {
+    /** Logger scope name. */
+    name: string;
+    /** Event severity level. */
+    level: LogLevels;
+    /** Event payload, where the first entry is the formatted message. */
+    messages: unknown[];
+    /** Optional additional context attached by sinks or middleware. */
+    [other: string]: unknown;
+}
+
+/**
+ * Central logger that routes log events through registered {@link LogSink} instances.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from '@contentful/optimization-api-client/logger'
+ *
+ * logger.info('MyModule', 'Application started')
+ * ```
+ *
+ * @public
+ */
+declare class Logger {
+    /** The logger's identifier, used as the event scope name. */
+    readonly name = "@contentful/optimization";
+    private readonly PREFIX_PARTS;
+    private readonly DELIMITER;
+    private sinks;
+    private assembleLocationPrefix;
+    /**
+     * Registers a log sink. If a sink with the same name already exists, it is replaced.
+     *
+     * @param sink - The {@link LogSink} instance to register.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * import { logger, ConsoleLogSink } from '@contentful/optimization-api-client/logger'
+     *
+     * logger.addSink(new ConsoleLogSink('debug'))
+     * ```
+     */
+    addSink(sink: LogSink): void;
+    /**
+     * Removes a registered sink by name.
+     *
+     * @param name - The name of the sink to remove.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.removeSink('ConsoleLogSink')
+     * ```
+     */
+    removeSink(name: string): void;
+    /**
+     * Removes all registered sinks.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.removeSinks()
+     * ```
+     */
+    removeSinks(): void;
+    /**
+     * Logs a message at the debug level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.debug('MyModule', 'Debugging value', someVariable)
+     * ```
+     */
+    debug(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the info level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.info('MyModule', 'Operation completed')
+     * ```
+     */
+    info(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the log level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.log('MyModule', 'General log entry')
+     * ```
+     */
+    log(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the warn level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.warn('MyModule', 'Deprecated method called')
+     * ```
+     */
+    warn(logLocation: string, message: string, ...args: unknown[]): void;
+    /**
+     * Logs a message at the error level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message or Error object.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.error('MyModule', new Error('Something failed'))
+     * ```
+     */
+    error(logLocation: string, message: string | Error, ...args: unknown[]): void;
+    /**
+     * Logs a message at the fatal level.
+     *
+     * @param logLocation - The module or component identifier.
+     * @param message - The log message or Error object.
+     * @param args - Additional arguments forwarded in the log event.
+     * @returns Nothing.
+     *
+     * @example
+     * ```typescript
+     * logger.fatal('MyModule', new Error('Unrecoverable failure'))
+     * ```
+     */
+    fatal(logLocation: string, message: string | Error, ...args: unknown[]): void;
+    private emit;
+    private onLogEvent;
+}
+export { Logger }
+export default Logger;
+
+/**
+ * Shared singleton {@link Logger} instance used across the SDK.
+ *
+ * @public
+ */
+export declare const logger: Logger;
+
+/**
+ * Supported log levels ordered from highest to lowest severity.
+ *
+ * @public
+ */
+export declare type LogLevels = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'log';
+
+/**
+ * Numeric severity map used for log-level threshold comparisons.
+ *
+ * @public
+ */
+export declare const logLevelSeverity: Readonly<Record<LogLevels, number>>;
+
+/**
+ * Abstract base class for log sinks that receive and process log events.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomSink extends LogSink {
+ *   name = 'MyCustomSink'
+ *
+ *   ingest(event: LogEvent): void {
+ *     // process the event
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare abstract class LogSink {
+    /** Display name used to identify this sink for addition and removal. */
+    abstract name: string;
+    /**
+     * Processes an incoming log event.
+     *
+     * @param event - The log event to process.
+     * @returns Nothing.
+     */
+    abstract ingest(event: LogEvent): void;
+}
+
+/**
+ * A location-scoped logger interface whose methods omit the `logLocation` parameter.
+ *
+ * @public
+ */
+export declare interface ScopedLogger {
+    /** Logs at debug level. */
+    debug: (message: string, ...args: unknown[]) => void;
+    /** Logs at info level. */
+    info: (message: string, ...args: unknown[]) => void;
+    /** Logs at log level. */
+    log: (message: string, ...args: unknown[]) => void;
+    /** Logs at warn level. */
+    warn: (message: string, ...args: unknown[]) => void;
+    /** Logs at error level. */
+    error: (message: string | Error, ...args: unknown[]) => void;
+    /** Logs at fatal level. */
+    fatal: (message: string | Error, ...args: unknown[]) => void;
+}
+
+export { }