@larablox/monolog 0.1.0

package/out/Monolog/Handler/AbstractProcessingHandler.d.ts

@@ -0,0 +1,30 @@
+import { AbstractHandler } from "./AbstractHandler";
+import type { FormatterInterface } from "../Formatter/FormatterInterface";
+import type { LogRecord } from "../LogRecord";
+import type { Processor } from "../Processor/ProcessorInterface";
+/**
+ * PHP: `Monolog\Handler\AbstractProcessingHandler`, which folds in
+ * `ProcessableHandlerTrait` and `FormattableHandlerTrait`.
+ */
+export declare abstract class AbstractProcessingHandler extends AbstractHandler {
+    protected processors: Processor[];
+    protected formatter?: FormatterInterface;
+    /** Handles a record. */
+    handle(record: LogRecord): boolean;
+    /** Writes the record down to the log of the implementing handler. */
+    protected abstract write(record: LogRecord): void;
+    /** Adds a processor in the stack. */
+    pushProcessor(processor: Processor): this;
+    /** Removes the processor on top of the stack and returns it. */
+    popProcessor(): Processor | undefined;
+    /** Processes a record. */
+    protected processRecord(record: LogRecord): LogRecord;
+    /** Sets the formatter. */
+    setFormatter(formatter: FormatterInterface): this;
+    /** Gets the formatter, building the default one on first use. */
+    getFormatter(): FormatterInterface;
+    /** Gets the default formatter. */
+    protected getDefaultFormatter(): FormatterInterface;
+    /** Resets the handler and any processors on it that support resetting. */
+    reset(): void;
+}

package/out/Monolog/Handler/AbstractProcessingHandler.luau

@@ -0,0 +1,79 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local AbstractHandler = TS.import(script, script.Parent, "AbstractHandler").AbstractHandler
+local LineFormatter = TS.import(script, script.Parent.Parent, "Formatter", "LineFormatter").LineFormatter
+local isResettable = TS.import(script, script.Parent.Parent, "ResettableInterface").isResettable
+local runProcessor = TS.import(script, script.Parent.Parent, "Processor", "ProcessorInterface").runProcessor
+--[[
+	*
+	 * PHP: `Monolog\Handler\AbstractProcessingHandler`, which folds in
+	 * `ProcessableHandlerTrait` and `FormattableHandlerTrait`.
+	 
+]]
+local AbstractProcessingHandler
+do
+	local super = AbstractHandler
+	AbstractProcessingHandler = setmetatable({}, {
+		__tostring = function()
+			return "AbstractProcessingHandler"
+		end,
+		__index = super,
+	})
+	AbstractProcessingHandler.__index = AbstractProcessingHandler
+	function AbstractProcessingHandler:constructor(...)
+		super.constructor(self, ...)
+		self.processors = {}
+	end
+	function AbstractProcessingHandler:handle(record)
+		if not self:isHandling(record) then
+			return false
+		end
+		local processed = record
+		if not (#self.processors == 0) then
+			processed = self:processRecord(processed)
+		end
+		processed.formatted = self:getFormatter():format(processed)
+		self:write(processed)
+		return self.bubble == false
+	end
+	function AbstractProcessingHandler:pushProcessor(processor)
+		local _processors = self.processors
+		local _processor = processor
+		table.insert(_processors, 1, _processor)
+		return self
+	end
+	function AbstractProcessingHandler:popProcessor()
+		return table.remove(self.processors, 1)
+	end
+	function AbstractProcessingHandler:processRecord(record)
+		local processed = record
+		for _, processor in self.processors do
+			processed = runProcessor(processor, processed)
+		end
+		return processed
+	end
+	function AbstractProcessingHandler:setFormatter(formatter)
+		self.formatter = formatter
+		return self
+	end
+	function AbstractProcessingHandler:getFormatter()
+		if self.formatter == nil then
+			self.formatter = self:getDefaultFormatter()
+		end
+		return self.formatter
+	end
+	function AbstractProcessingHandler:getDefaultFormatter()
+		return LineFormatter.new()
+	end
+	function AbstractProcessingHandler:reset()
+		super.reset(self)
+		for _, processor in self.processors do
+			if isResettable(processor) then
+				processor:reset()
+			end
+		end
+	end
+end
+return {
+	AbstractProcessingHandler = AbstractProcessingHandler,
+}

package/out/Monolog/Handler/Handler.d.ts

@@ -0,0 +1,15 @@
+import type { HandlerInterface } from "./HandlerInterface";
+import type { LogRecord } from "../LogRecord";
+/**
+ * PHP: `Monolog\Handler\Handler`.
+ *
+ * `__destruct` and `__serialize` are not ported: Luau has neither.
+ */
+export declare abstract class Handler implements HandlerInterface {
+    abstract isHandling(record: LogRecord): boolean;
+    abstract handle(record: LogRecord): boolean;
+    /** Handles a set of records at once. */
+    handleBatch(records: Array<LogRecord>): void;
+    /** Closes the handler. */
+    close(): void;
+}

package/out/Monolog/Handler/Handler.luau

@@ -0,0 +1,25 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * PHP: `Monolog\Handler\Handler`.
+	 *
+	 * `__destruct` and `__serialize` are not ported: Luau has neither.
+	 
+]]
+local Handler
+do
+	Handler = {}
+	function Handler:constructor()
+	end
+	function Handler:handleBatch(records)
+		for _, record in records do
+			self:handle(record)
+		end
+	end
+	function Handler:close()
+		--
+	end
+end
+return {
+	Handler = Handler,
+}

package/out/Monolog/Handler/HandlerInterface.d.ts

@@ -0,0 +1,12 @@
+import type { LogRecord } from "../LogRecord";
+/** PHP: `Monolog\Handler\HandlerInterface`. */
+export interface HandlerInterface {
+    /** Checks whether the given record will be handled by this handler. */
+    isHandling(record: LogRecord): boolean;
+    /** Handles a record. Returning true stops the bubbling chain. */
+    handle(record: LogRecord): boolean;
+    /** Handles a set of records at once. */
+    handleBatch(records: Array<LogRecord>): void;
+    /** Closes the handler. */
+    close(): void;
+}

package/out/Monolog/Handler/HandlerInterface.luau

@@ -0,0 +1,3 @@
+-- Compiled with roblox-ts v3.0.0
+--* PHP: `Monolog\Handler\HandlerInterface`. 
+return nil

package/out/Monolog/Handler/NullHandler.d.ts

@@ -0,0 +1,10 @@
+import { Handler } from "./Handler";
+import { Level } from "../Level";
+import type { LogRecord } from "../LogRecord";
+/** PHP: `Monolog\Handler\NullHandler`. Swallows everything at or above the level. */
+export declare class NullHandler extends Handler {
+    protected readonly level: Level;
+    constructor(level?: Level);
+    isHandling(record: LogRecord): boolean;
+    handle(record: LogRecord): boolean;
+}

package/out/Monolog/Handler/NullHandler.luau

@@ -0,0 +1,36 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Handler = TS.import(script, script.Parent, "Handler").Handler
+local Level = TS.import(script, script.Parent.Parent, "Level").Level
+--* PHP: `Monolog\Handler\NullHandler`. Swallows everything at or above the level. 
+local NullHandler
+do
+	local super = Handler
+	NullHandler = setmetatable({}, {
+		__tostring = function()
+			return "NullHandler"
+		end,
+		__index = super,
+	})
+	NullHandler.__index = NullHandler
+	function NullHandler.new(...)
+		local self = setmetatable({}, NullHandler)
+		return self:constructor(...) or self
+	end
+	function NullHandler:constructor(level)
+		if level == nil then
+			level = Level.Debug
+		end
+		super.constructor(self)
+		self.level = level
+	end
+	function NullHandler:isHandling(record)
+		return record.level >= self.level
+	end
+	function NullHandler:handle(record)
+		return record.level >= self.level
+	end
+end
+return {
+	NullHandler = NullHandler,
+}

package/out/Monolog/Handler/RobloxConsoleHandler.d.ts

@@ -0,0 +1,55 @@
+import { AbstractProcessingHandler } from "./AbstractProcessingHandler";
+import { Level } from "../Level";
+import type { FormatterInterface } from "../Formatter/FormatterInterface";
+import type { LogRecord } from "../LogRecord";
+/**
+ * PHP: `Monolog\Handler\PHPConsoleHandler`.
+ *
+ * Upstream streams debug/error/exception data to the (now abandoned) "PHP
+ * Console" Chrome extension via `PhpConsole\Connector`. There is no such
+ * target on Roblox, so this adapts the same handler shape -- the `options`
+ * bag, the record-kind branching in `write()`, the default formatter -- to
+ * the platform's own output console (`print`/`warn`) instead, superseding
+ * what the old, not-a-real-upstream-class `ConsoleHandler` used to do.
+ */
+/**
+ * Reduced from upstream's `Options`: everything else there
+ * (`classesPartialsTraceIgnore`, `useOwnErrorsHandler`/`useOwnExceptionsHandler`,
+ * `sourcesBasePath`, `registerHelper`, `serverEncoding`, `headersLimit`,
+ * `password`, `enableSslOnlyMode`, `ipMasks`, `enableEvalListener`, every
+ * `dumper*` key, `detectDumpTraceAndSource`, `dataStorage`) is either specific
+ * to the PHP Console wire protocol or paired with `ErrorHandler`/`SignalHandler`,
+ * both out of scope for this port -- there is no connector object left to
+ * configure with them.
+ */
+export interface Options {
+    /** Whether this handler is active at all. */
+    enabled: boolean;
+    /** Context keys checked, in order, for a debug "tag" to prefix the message with. */
+    debugTagsKeysInContext: Array<string>;
+}
+export declare class RobloxConsoleHandler extends AbstractProcessingHandler {
+    private readonly options;
+    constructor(options?: Partial<Options>, level?: Level, bubble?: boolean);
+    /** PHP: `PHPConsoleHandler::getOptions()`. */
+    getOptions(): Options;
+    /** PHP: `PHPConsoleHandler::handle()`. */
+    handle(record: LogRecord): boolean;
+    /** PHP: `PHPConsoleHandler::write()`. */
+    protected write(record: LogRecord): void;
+    /** PHP: `PHPConsoleHandler::handleDebugRecord()`. */
+    private writeDebugRecord;
+    /** PHP: `PHPConsoleHandler::handleExceptionRecord()`. */
+    private writeExceptionRecord;
+    /** PHP: `PHPConsoleHandler::handleErrorRecord()`. */
+    private writeErrorRecord;
+    /**
+     * PHP: `PHPConsoleHandler::getRecordTags()`. Upstream also checks
+     * `$filteredContext[0]`, PHP's implicit first-array-index -- Luau/TS have
+     * no positional index on a `RecordBag`, so only the named
+     * `debugTagsKeysInContext` keys are checked.
+     */
+    private getRecordTags;
+    /** PHP: `PHPConsoleHandler::getDefaultFormatter()`. */
+    protected getDefaultFormatter(): FormatterInterface;
+}

package/out/Monolog/Handler/RobloxConsoleHandler.luau

@@ -0,0 +1,141 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local AbstractProcessingHandler = TS.import(script, script.Parent, "AbstractProcessingHandler").AbstractProcessingHandler
+local _Level = TS.import(script, script.Parent.Parent, "Level")
+local Level = _Level.Level
+local Levels = _Level.Levels
+local LineFormatter = TS.import(script, script.Parent.Parent, "Formatter", "LineFormatter").LineFormatter
+local Utils = TS.import(script, script.Parent.Parent, "Utils").Utils
+--[[
+	*
+	 * PHP: `Monolog\Handler\PHPConsoleHandler`.
+	 *
+	 * Upstream streams debug/error/exception data to the (now abandoned) "PHP
+	 * Console" Chrome extension via `PhpConsole\Connector`. There is no such
+	 * target on Roblox, so this adapts the same handler shape -- the `options`
+	 * bag, the record-kind branching in `write()`, the default formatter -- to
+	 * the platform's own output console (`print`/`warn`) instead, superseding
+	 * what the old, not-a-real-upstream-class `ConsoleHandler` used to do.
+	 
+]]
+--[[
+	*
+	 * Reduced from upstream's `Options`: everything else there
+	 * (`classesPartialsTraceIgnore`, `useOwnErrorsHandler`/`useOwnExceptionsHandler`,
+	 * `sourcesBasePath`, `registerHelper`, `serverEncoding`, `headersLimit`,
+	 * `password`, `enableSslOnlyMode`, `ipMasks`, `enableEvalListener`, every
+	 * `dumper*` key, `detectDumpTraceAndSource`, `dataStorage`) is either specific
+	 * to the PHP Console wire protocol or paired with `ErrorHandler`/`SignalHandler`,
+	 * both out of scope for this port -- there is no connector object left to
+	 * configure with them.
+	 
+]]
+local DEFAULT_OPTIONS = {
+	enabled = true,
+	debugTagsKeysInContext = { "tag" },
+}
+local RobloxConsoleHandler
+do
+	local super = AbstractProcessingHandler
+	RobloxConsoleHandler = setmetatable({}, {
+		__tostring = function()
+			return "RobloxConsoleHandler"
+		end,
+		__index = super,
+	})
+	RobloxConsoleHandler.__index = RobloxConsoleHandler
+	function RobloxConsoleHandler.new(...)
+		local self = setmetatable({}, RobloxConsoleHandler)
+		return self:constructor(...) or self
+	end
+	function RobloxConsoleHandler:constructor(options, level, bubble)
+		if options == nil then
+			options = {}
+		end
+		if level == nil then
+			level = Level.Debug
+		end
+		if bubble == nil then
+			bubble = true
+		end
+		super.constructor(self, level, bubble)
+		local _object = {}
+		local _left = "enabled"
+		local _condition = options.enabled
+		if _condition == nil then
+			_condition = DEFAULT_OPTIONS.enabled
+		end
+		_object[_left] = _condition
+		_object.debugTagsKeysInContext = options.debugTagsKeysInContext or DEFAULT_OPTIONS.debugTagsKeysInContext
+		self.options = _object
+	end
+	function RobloxConsoleHandler:getOptions()
+		return self.options
+	end
+	function RobloxConsoleHandler:handle(record)
+		if self.options.enabled then
+			return super.handle(self, record)
+		end
+		-- Upstream also requires `connector.isActiveClient()` here; there is no
+		-- connector to ask, so `enabled` is the only gate left.
+		return not self.bubble
+	end
+	function RobloxConsoleHandler:write(record)
+		if Levels:isLowerThan(record.level, Level.Notice) then
+			self:writeDebugRecord(record)
+		elseif record.context.exception ~= nil then
+			self:writeExceptionRecord(record)
+		else
+			self:writeErrorRecord(record)
+		end
+	end
+	function RobloxConsoleHandler:writeDebugRecord(record)
+		local _binding = self:getRecordTags(record)
+		local tags = _binding[1]
+		local filteredContext = _binding[2]
+		local message = record.message
+		if (next(filteredContext)) ~= nil then
+			message = `{message} {Utils:jsonEncode(filteredContext)}`
+		end
+		print(`[{tags}] {message}`)
+	end
+	function RobloxConsoleHandler:writeExceptionRecord(record)
+		warn(tostring(record.context.exception))
+	end
+	function RobloxConsoleHandler:writeErrorRecord(record)
+		local context = record.context
+		local message = if context.message ~= nil then tostring(context.message) else record.message
+		if context.file == nil and context.line == nil then
+			warn(message)
+			return nil
+		end
+		local file = if context.file ~= nil then tostring(context.file) else "?"
+		local line = if context.line ~= nil then tostring(context.line) else "?"
+		warn(`{message} ({file}:{line})`)
+	end
+	function RobloxConsoleHandler:getRecordTags(record)
+		local filteredContext = {}
+		for key, value in pairs(record.context) do
+			filteredContext[key] = value
+		end
+		local tag
+		for _, key in self.options.debugTagsKeysInContext do
+			if filteredContext[key] ~= nil then
+				tag = tostring(filteredContext[key])
+				filteredContext[key] = nil
+				break
+			end
+		end
+		local _condition = tag
+		if _condition == nil then
+			_condition = Levels:toPsrLogLevel(record.level)
+		end
+		return { _condition, filteredContext }
+	end
+	function RobloxConsoleHandler:getDefaultFormatter()
+		return LineFormatter.new("%message%")
+	end
+end
+return {
+	RobloxConsoleHandler = RobloxConsoleHandler,
+}

package/out/Monolog/Handler/TestHandler.d.ts

@@ -0,0 +1,90 @@
+import { AbstractProcessingHandler } from "./AbstractProcessingHandler";
+import { Level } from "../Level";
+import type { LogLevel } from "../LoggerInterface";
+import type { LogRecord, RecordBag } from "../LogRecord";
+/** PHP: the `array{message: string, context?: mixed[]}` shape `hasRecord()` accepts. */
+export interface RecordAssertion {
+    message: string;
+    context?: RecordBag;
+}
+/** PHP: the `callable(LogRecord, int): mixed $predicate` shape `hasRecordThatPasses()` accepts. */
+export type RecordPredicate = (record: LogRecord, index: number) => boolean;
+/**
+ * PHP: `Monolog\Handler\TestHandler`.
+ *
+ * Ships in Monolog's real (non-dev) autoload, not `autoload-dev`, because
+ * library consumers use it in their own tests -- the same reason this port
+ * carries it under `src/Monolog/Handler` rather than `tests/`, and the same
+ * justification already made for `Monolog\Test\MonologTestCase`.
+ *
+ * Upstream's per-level shorthands (`hasWarning()`, `hasWarningRecords()`,
+ * `hasWarningThatContains()`, `hasWarningThatMatches()`,
+ * `hasWarningThatPasses()`, one set per `Level` case) are dispatched through
+ * PHP's `__call` magic method: it regex-matches the requested method name
+ * apart into a level name and a generic method name, then redirects to the
+ * matching `hasRecord*()` method with the parsed `Level` appended. Luau has
+ * no dynamic method dispatch to replicate that with, so every shorthand is
+ * spelled out explicitly below instead -- one small delegating method per
+ * level per kind, same names, same behavior.
+ *
+ * `hasRecordThatMatches()`/the `*ThatMatches()` shorthands use Luau string
+ * patterns (`string.match`) rather than upstream's PCRE (`preg_match`) --
+ * there is no PCRE engine on this platform. Pattern syntax differs
+ * (`%d`/`%a`/... instead of `\d`/`\w`/...); callers passing a `regex` should
+ * pass a Lua pattern, not a PCRE one.
+ */
+export declare class TestHandler extends AbstractProcessingHandler {
+    protected records: LogRecord[];
+    protected recordsByLevel: Map<Level, LogRecord[]>;
+    private skipReset;
+    getRecords(): Array<LogRecord>;
+    clear(): void;
+    reset(): void;
+    setSkipReset(skipReset: boolean): void;
+    hasRecords(level: Level | LogLevel): boolean;
+    hasRecord(recordAssertions: string | RecordAssertion, level: Level): boolean;
+    hasRecordThatContains(message: string, level: Level): boolean;
+    hasRecordThatMatches(regex: string, level: Level): boolean;
+    hasRecordThatPasses(predicate: RecordPredicate, level: Level | LogLevel): boolean;
+    protected write(record: LogRecord): void;
+    hasEmergencyRecords(): boolean;
+    hasEmergency(recordAssertions: string | RecordAssertion): boolean;
+    hasEmergencyThatContains(message: string): boolean;
+    hasEmergencyThatMatches(regex: string): boolean;
+    hasEmergencyThatPasses(predicate: RecordPredicate): boolean;
+    hasAlertRecords(): boolean;
+    hasAlert(recordAssertions: string | RecordAssertion): boolean;
+    hasAlertThatContains(message: string): boolean;
+    hasAlertThatMatches(regex: string): boolean;
+    hasAlertThatPasses(predicate: RecordPredicate): boolean;
+    hasCriticalRecords(): boolean;
+    hasCritical(recordAssertions: string | RecordAssertion): boolean;
+    hasCriticalThatContains(message: string): boolean;
+    hasCriticalThatMatches(regex: string): boolean;
+    hasCriticalThatPasses(predicate: RecordPredicate): boolean;
+    hasErrorRecords(): boolean;
+    hasError(recordAssertions: string | RecordAssertion): boolean;
+    hasErrorThatContains(message: string): boolean;
+    hasErrorThatMatches(regex: string): boolean;
+    hasErrorThatPasses(predicate: RecordPredicate): boolean;
+    hasWarningRecords(): boolean;
+    hasWarning(recordAssertions: string | RecordAssertion): boolean;
+    hasWarningThatContains(message: string): boolean;
+    hasWarningThatMatches(regex: string): boolean;
+    hasWarningThatPasses(predicate: RecordPredicate): boolean;
+    hasNoticeRecords(): boolean;
+    hasNotice(recordAssertions: string | RecordAssertion): boolean;
+    hasNoticeThatContains(message: string): boolean;
+    hasNoticeThatMatches(regex: string): boolean;
+    hasNoticeThatPasses(predicate: RecordPredicate): boolean;
+    hasInfoRecords(): boolean;
+    hasInfo(recordAssertions: string | RecordAssertion): boolean;
+    hasInfoThatContains(message: string): boolean;
+    hasInfoThatMatches(regex: string): boolean;
+    hasInfoThatPasses(predicate: RecordPredicate): boolean;
+    hasDebugRecords(): boolean;
+    hasDebug(recordAssertions: string | RecordAssertion): boolean;
+    hasDebugThatContains(message: string): boolean;
+    hasDebugThatMatches(regex: string): boolean;
+    hasDebugThatPasses(predicate: RecordPredicate): boolean;
+}