@rbxts/rlog
Version:
Context-based server-side logging solution for ROBLOX projects.
150 lines • 5.15 kB
TypeScript
/**
* @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 { PartialRLogConfig } from "../configuration";
import { LogContext } from "./log-context";
/**
* A callback that take in a {@link LogContext} and optionally returns a value.
*
* @see {@link withLogContext}, {@link withLogContextAsync}
*
* @typeParam R - The type of value returned by the function, or void.
* @public
*/
export type ContextCallback<R = void> = (context: LogContext) => R;
/**
* Wraps around a callback, automatically creating and managing the lifecycle
* for a {@link LogContext}.
*
* @remarks
*
* The callback will be invoked immediately, and within the same thread.
*
* Any errors thrown within the callback will be re-thrown after calling
* {@link LogContext.stop | stop} on the created context to avoid memory leaks.
*
* Any value returned from the callback will also be propagated appropriately.
*
* @param config - Config to create the context with.
* @param callback - {@link ContextCallback} scope to run and provide the context for.
*
* @see {@link withLogContextAsync}
*
* @example
* ```ts
* remotes.buyPet.connect((player: Player, pet: PetId) => {
* // automatically starts and stops the context
* withLogContext({ minLogLevel: LogLevel.DEBUG }, (context) => {
* buyPet(context, player.UserId, pet);
* });
* });
* ```
*
* @typeParam R - The type of value returned by the function, or void.
* @public
*/
export declare function withLogContext<R = void>(config: PartialRLogConfig, callback: ContextCallback<R>): R;
/**
* Wraps around a callback, automatically creating and managing the lifecycle
* for a {@link LogContext}.
*
* @remarks
*
* The callback will be invoked immediately, and within the same thread.
*
* Any errors thrown within the callback will be re-thrown after calling
* {@link LogContext.stop | stop} on the created context to avoid memory leaks.
*
* Any value returned from the callback will also be propagated appropriately.
*
* @param callback - {@link ContextCallback} scope to run and provide the context for.
*
* @see {@link withLogContextAsync}
*
* @example
* ```ts
* remotes.buyPet.connect((player: Player, pet: PetId) => {
* // automatically starts and stops the context
* withLogContext((context) => {
* buyPet(context, player.UserId, pet);
* });
* });
* ```
*
* @typeParam R - The type of value returned by the function, or void.
* @public
*/
export declare function withLogContext<R = void>(callback: ContextCallback<R>): R;
/**
* Wraps around an async callback, automatically creating and managing the lifecycle
* for a {@link LogContext}.
*
* @remarks
*
* Will call {@link LogContext.stop | stop} on the created context when the executed
* scope is finished- regardless if the promise was cancelled or threw an error.
*
* Any value returned from the callback will also be propagated appropriately.
*
* @param config - Config to create the context with.
* @param callback - {@link ContextCallback} scope to run and provide the context for.
*
* @see {@link withLogContext}
*
* @example
* ```ts
* remotes.buyPet.onRequest((player: Player, pet: PetId) =>
* // automatically starts and stops the context
* withLogContextAsync({ minLogLevel: LogLevel.DEBUG }, async (context) => {
* return buyPet(context, player.UserId, pet);
* }),
* );
* ```
*
* @typeParam R - The type of value returned by the function, or void.
* @public
*/
export declare function withLogContextAsync<R = void>(config: PartialRLogConfig, callback: ContextCallback<Promise<R>>): Promise<R>;
/**
* Wraps around an async callback, automatically creating and managing the lifecycle
* for a {@link LogContext}.
*
* @remarks
*
* Will call {@link LogContext.stop | stop} on the created context when the executed
* scope is finished- regardless if the promise was cancelled or threw an error.
*
* Any value returned from the callback will also be propagated appropriately.
*
* @param callback - {@link ContextCallback} scope to run and provide the context for.
*
* @see {@link withLogContext}
*
* @example
* ```ts
* remotes.buyPet.onRequest((player: Player, pet: PetId) =>
* // automatically starts and stops the context
* withLogContextAsync(async (context) => {
* return buyPet(context, player.UserId, pet);
* }),
* );
* ```
*
* @typeParam R - The type of value returned by the function, or void.
* @public
*/
export declare function withLogContextAsync<R = void>(callback: ContextCallback<Promise<R>>): Promise<R>;
//# sourceMappingURL=util.d.ts.map