@rbxts/rlog/out/rlog.d.ts

Context-based server-side logging solution for ROBLOX projects.

/**
 * @license
 * Copyright 2024 Daymon Littrell-Reyes
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
import { LogData, LogLevel } from "./common";
import { PartialRLogConfig, RLogConfig } from "./configuration";
import type { LogContext } from "./context";
/**
 * Table version of the constructor parameters for {@link RLog}.
 *
 * @public
 */
export interface RLogConstructorParameters {
    config?: PartialRLogConfig;
    context?: LogContext;
    inheritDefault?: boolean;
}
/**
 * Class for server-side Roblox Logging.
 *
 * @remarks
 *
 * You can also use `rlog` or `rLog`- for style purposes.
 *
 * @public
 */
export declare class RLog {
    /**
     * @internal
     * @readonly
     */
    _config: RLogConfig;
    /**
     * The {@link LogContext} assigned to this instance, if any.
     *
     * @remarks
     *
     * Log context provides a way to carry Correlation IDs through-out
     * logs in an individual flow.
     *
     * To learn more about what that means, you can look at the docs
     * for {@link LogContext}.
     *
     * @see {@link RLog.withLogContext | withLogContext}
     */
    readonly context: LogContext | undefined;
    /**
     * The default or "global" {@link RLog} instance.
     *
     * @remarks
     *
     * All loggers inherit from this, so it's a convenient way for
     * attaching global sinks, enrichers, or configuration.
     *
     * You can also use {@link rLogger} for style purposes.
     *
     * @see {@link RLog.UpdateDefaultConfig | UpdateDefaultConfig}
     */
    static readonly default: RLog;
    /**
     * Constructs a new {@link RLog} instance.
     *
     * @param config - Configuration settings to use for this logger instance.
     * @param context - The {@link LogContext} to use as a base for this instance.
     * @param inheritDefault - Whether to merge configs with the {@link RLog.default | default instance}. Defaults to true.
     */
    constructor(config?: PartialRLogConfig, context?: LogContext, inheritDefault?: boolean);
    /**
     * Constructs a new {@link RLog} instance.
     *
     * Uses the provided table in place of the argument names.
     */
    constructor(params: RLogConstructorParameters);
    /**
     * Overwrites the config for the {@link RLog.default | default} instance.
     *
     * @remarks
     *
     * You will rarely need to use this, and generally will want to be using
     * {@link RLog.UpdateDefaultConfig | UpdateDefaultConfig} insted.
     *
     * @param config - The {@link RLogConfig} to use.
     *
     * @see {@link RLog.UpdateDefaultConfig | UpdateDefaultConfig}, {@link RLog.ResetDefaultConfig | ResetDefaultConfig}
     */
    static SetDefaultConfig(config: PartialRLogConfig): void;
    /**
     * Merges the given config with the existing config for the {@link RLog.default | default} instance.
     *
     * Since all {@link RLog} instances inherit their config from the default instance,
     * this is a convenient way to provide default configuration settings.
     *
     * @param config - The {@link RLogConfig} to use.
     *
     * @see {@link RLog.UpdateDefaultConfig | SetDefaultConfig}, {@link RLog.ResetDefaultConfig | ResetDefaultConfig}
     *
     * @example
     * ```ts
     * RLog.UpdateDefaultConfig({ serialization: { encodeFunctions: true } });
     *
     * // Inherits the `encodeFunctions` setting automatically
     * const logger = new RLog({ serialization: { encodeRobloxTypes: false } });
     *
     * logger.i("Player died", { player: player, location: player.Position, revive: () => {} });
     * // > [INFO]: Player died
     * // > { "data": { "player": 1338, "location": "<Vector3>", "revive": "<Function>" } }
     * ```
     */
    static UpdateDefaultConfig(config: PartialRLogConfig): void;
    /**
     * Resets the config for the {@link RLog.default | default} instance to the original settings.
     *
     * @remarks
     *
     * Essentially would be the same as if you never touched the default config.
     *
     * @see {@link RLog.UpdateDefaultConfig | UpdateDefaultConfig}, {@link RLog.ResetDefaultConfig | SetDefaultConfig}
     */
    static ResetDefaultConfig(): void;
    /**
     * Force any pending messages to be sent through the sinks, regardless of the `minLogLevel`.
     *
     * @remarks
     *
     * Intended to be called before the game closes, to ensure there are no missing logs.
     *
     * @see {@link LogContext}
     *
     * @example
     * ```ts
     * game.bindToClose(() => {
     *   RLog.ForceContextFlush();
     * });
     * ```
     */
    static ForceContextFlush(): void;
    /**
     * Creates a new {@link RLog} instance with all the same settings and properties.
     *
     * @remarks
     *
     * Everything is deep copied, so any mutations to the original will safely not replicate.
     *
     * @returns A duplicate of this {@link RLog} instance.
     */
    clone(): RLog;
    /**
     * Creates a new {@link RLog} instance with all the same settings and properties.
     *
     * The provided {@link RLogConstructorParameters | parameters} will be merged with
     * the existing parameters on this instance.
     *
     * @remarks
     *
     * Everything is deep copied, so any mutations to the original will safely not replicate.
     *
     * @returns A duplicate of this {@link RLog} instance.
     */
    clone(params: RLogConstructorParameters): RLog;
    /**
     * Logs a message with a specified log level.
     *
     * @param level - The severity of the log.
     * @param message - The core message of the log.
     * @param data - Data to log. Will be encoded according to this logger's {@link RLogConfig | config}.
     *
     * @see {@link RLog.verbose | verbose}, {@link RLog.debug | debug}, {@link RLog.info | info}, {@link RLog.warning | warning}, {@link RLog.error | error}
     */
    log(level: LogLevel, message: string, data?: LogData): void;
    /**
     * Logs a verbose message.
     *
     * @param message - The message to log.
     * @param data - Data to log.
     *
     * @see {@link RLog.v | v}
     *
     * @example
     * ```log
     * [VERBOSE]: Hello World!
     * { data: { player: "Player1" } }
     * ```
     */
    verbose(message: string, data?: LogData): void;
    /**
     * Shorthand version of {@link RLog.verbose | verbose}.
     *
     * @param message - The message to log.
     * @param data - Data to log.
     */
    v(message: string, data?: LogData): void;
    /**
     * Logs a debug message.
     *
     * @param message - The message to log.
     * @param data - Data to log.
     *
     * @see {@link RLog.d | d}
     *
     * @example
     * ```log
     * [DEBUG]: Hello World!
     * { data: { player: "Player1" } }
     * ```
     */
    debug(message: string, data?: LogData): void;
    /**
     * Shorthand version of {@link RLog.debug | debug}.
     *
     * @param message - The message to log.
     * @param data - Data to log.
     */
    d(message: string, data?: LogData): void;
    /**
     * Logs an informational message.
     *
     * @param message - The message to log.
     * @param data - Data to log.
     *
     * @see {@link RLog.i | i}
     *
     * @example
     * ```log
     * [INFO]: Hello World!
     * { data: { player: "Player1" } }
     * ```
     */
    info(message: string, data?: LogData): void;
    /**
     * Shorthand version of {@link RLog.info | info}.
     *
     * @param message - The message to log.
     * @param data - Data to log.
     */
    i(message: string, data?: LogData): void;
    /**
     * Logs a warning message.
     *
     * @param message - The message to log.
     * @param data - Data to log.
     *
     * @see {@link RLog.w | w}, {@link RLog.warn | warn}
     *
     * @example
     * ```log
     * [WARNING]: Hello World!
     * { data: { player: "Player1" } }
     * ```
     */
    warning(message: string, data?: LogData): void;
    /**
     * Shorthand version of {@link RLog.warning | warning}.
     *
     * @param message - The message to log.
     * @param data - Data to log.
     */
    warn(message: string, data?: LogData): void;
    /**
     * Shorthand version of {@link RLog.warning | warning}.
     *
     * @param message - The message to log.
     * @param data - Data to log.
     */
    w(message: string, data?: LogData): void;
    /**
     * Logs an error message.
     *
     * @param message - The message to log.
     * @param data - Data to log.
     *
     * @see {@link RLog.e | e}
     *
     * @example
     * ```log
     * [ERROR]: Hello World!
     * { data: { player: "Player1" } }
     * ```
     */
    error(message: string, data?: LogData): void;
    /**
     * Shorthand version of {@link RLog.error | error}.
     *
     * @param message - The message to log.
     * @param data - Data to log.
     */
    e(message: string, data?: LogData): void;
    /**
     * Returns a new {@link RLog} with the provided config merged with the existing config.
     *
     * @param config - Configuration settings to apply to the new instance.
     *
     * @returns The new {@link RLog} instance
     *
     * @example
     * ```ts
     * let logger = new RLog({ minLogLevel: LogLevel.DEBUG });
     *
     * const data = { position: new Vector2(5, 10) };
     *
     * logger.v("Hello verbose!", data);
     * logger.d("Hello debug!", data);
     * // > [DEBUG]: Hello debug!
     * // > { data: { position: { X: 5, Y: 10 } } }
     *
     * // Inherits the minLogLevel
     * logger = logger.withConfig({ serialization: { encodeRobloxTypes: false } });
  
     * logger.v("Hello verbose!", data);
     * logger.d("Hello debug!", data);
     * // > [DEBUG]: Hello debug!
     * // > { data: { position: "<Vector2>" } }
     * ```
     */
    withConfig(config: PartialRLogConfig): RLog;
    /**
     * Returns a new {@link RLog} with the {@link RLogConfig.minLogLevel | minLogLevel} set
     * to the provided level.
     *
     * Messages below the minimum level will be ignored.
     *
     * @remarks
     *
     * You can also set this in the {@link RLogConfig | config}, this method is provided
     * purely as a means for easier changing.
     *
     * @param minLevel - The {@link LogLevel} to allow logs for.
     *
     * @returns The new {@link RLog} instance
     *
     * @example
     * ```ts
     * let logger = new RLog();
     *
     * logger.v("Hello verbose!");
     * logger.d("Hello debug!");
     * // > [VERBOSE]: Hello verbose!
     * // > [DEBUG]: Hello debug!
     *
     * logger = logger.withMinLogLevel(LogLevel.DEBUG);
  
     * logger.v("Hello verbose!");
     * logger.d("Hello debug!");
     * // > [DEBUG]: Hello debug!
     * ```
     */
    withMinLogLevel(minLevel: LogLevel): RLog;
    /**
     * Returns a new {@link RLog} with the {@link RLogConfig.tag | tag} set
     * to the provided string.
     *
     * @remarks
     *
     * Tags are appended to log messages when present, for easier filtering.
     *
     * Usually, they're used at the class or module level to keep track of all logs
     * facilitated by a single service or action.
     *
     * @param tag - The new tag to use.
     *
     * @returns The new {@link RLog} instance.
     *
     * @example
     * ```ts
     * let logger = new RLog();
     *
     * logger.d("Hello world!");
     * // > [DEBUG]: "Hello world!"
     *
     * logger = logger.withTag("main");
     *
     * logger.d("Hello world!");
     * // > [DEBUG]: main -> "Hello world!"
     * ```
     */
    withTag(tag: string): RLog;
    /**
     * Returns a new {@link RLog} with the {@link RLog.context | context} set
     * to the provided context.
     *
     * @param context - The new context to use.
     *
     * @returns The new {@link RLog} instance.
     */
    withLogContext(context: LogContext): RLog;
}
export { RLog as rlog, RLog as rLog };
/**
 * Mapping to {@link RLog.default} for easier default usage.
 *
 * @public
 */
export declare const rLogger: RLog;
//# sourceMappingURL=rlog.d.ts.map