@skmtc/core 0.0.795 → 0.0.796

package/esm/context/ResultsHandler.d.ts

@@ -3,17 +3,169 @@ import type { LogRecord } from '../deps/jsr.io/@std/log/0.224.14/logger.js';
 import { BaseHandler } from '../deps/jsr.io/@std/log/0.224.14/base_handler.js';
 import type { BaseHandlerOptions } from '../deps/jsr.io/@std/log/0.224.14/base_handler.js';
 import type { CoreContext } from './CoreContext.js';
+/**
+ * Configuration options for the {@link ResultsHandler}.
+ */
 export interface ResultsHandlerOptions extends BaseHandlerOptions {
+    /** The CoreContext instance to capture results to */
     context: CoreContext;
 }
+/**
+ * Custom log handler that captures warning and error results for SKMTC processing.
+ *
+ * The `ResultsHandler` extends Deno's standard library BaseHandler to provide
+ * specialized logging behavior for the SKMTC pipeline. It integrates with the
+ * CoreContext to capture warnings and errors as structured results that can be
+ * analyzed and reported after processing completes.
+ *
+ * This handler ensures that important processing issues are captured and stored
+ * in the context's results system rather than just being logged to the console.
+ *
+ * ## Key Features
+ *
+ * - **Result Capture**: Automatically captures WARN and ERROR logs as results
+ * - **Immediate Flushing**: Critical errors trigger immediate flush
+ * - **Lifecycle Management**: Proper setup and cleanup with event handlers
+ * - **Context Integration**: Seamlessly integrates with CoreContext results system
+ *
+ * @example Setting up the handler
+ * ```typescript
+ * import { getLogger } from '@std/log';
+ * import { ResultsHandler, CoreContext } from '@skmtc/core';
+ *
+ * const context = new CoreContext({
+ *   // ... context options
+ * });
+ *
+ * const handler = new ResultsHandler('WARN', {
+ *   context: context,
+ *   formatter: '[{levelName}] {msg}'
+ * });
+ *
+ * const logger = getLogger();
+ * logger.addHandler(handler);
+ *
+ * // Now warnings and errors will be captured as results
+ * logger.warning('Schema validation issue detected');
+ * logger.error('Failed to process operation');
+ * ```
+ *
+ * @example Integration in pipeline
+ * ```typescript
+ * class ProcessingPipeline {
+ *   async process(document: OasDocument) {
+ *     const context = new CoreContext(options);
+ *
+ *     // Set up results handler
+ *     const handler = new ResultsHandler('WARN', { context });
+ *     const logger = getLogger();
+ *     logger.addHandler(handler);
+ *
+ *     try {
+ *       const result = await this.processDocument(document, context);
+ *
+ *       // Check captured results
+ *       if (context.results.hasWarnings()) {
+ *         console.log('Processing completed with warnings');
+ *       }
+ *
+ *       return result;
+ *     } finally {
+ *       handler.destroy();
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class ResultsHandler extends BaseHandler {
     #private;
+    /** The CoreContext instance for capturing results */
     context: CoreContext;
+    /**
+     * Creates a new ResultsHandler instance.
+     *
+     * @param levelName - The minimum log level to handle
+     * @param options - Handler configuration including CoreContext
+     *
+     * @example
+     * ```typescript
+     * const context = new CoreContext(contextOptions);
+     * const handler = new ResultsHandler('WARN', {
+     *   context,
+     *   formatter: '[{levelName}] {msg}'
+     * });
+     * ```
+     */
     constructor(levelName: LevelName, options: ResultsHandlerOptions);
+    /**
+     * Sets up the handler with event listeners.
+     *
+     * Registers cleanup callbacks for process termination to ensure
+     * proper resource cleanup and result flushing.
+     *
+     * @override
+     */
     setup(): void;
+    /**
+     * Handles incoming log records.
+     *
+     * Processes log records through the base handler and triggers
+     * immediate flushing for critical errors above ERROR level.
+     *
+     * @param logRecord - The log record to handle
+     *
+     * @override
+     */
     handle(logRecord: LogRecord): void;
+    /**
+     * Captures log messages as results in the context.
+     *
+     * Converts log level names to result types and captures them
+     * in the associated CoreContext for later analysis.
+     *
+     * @param levelName - The log level name ('WARN' or 'ERROR')
+     *
+     * @throws {Error} When an unsupported log level is provided
+     *
+     * @example
+     * ```typescript
+     * // This is called automatically by the logging system
+     * handler.log('WARN'); // Captures as 'warning' result
+     * handler.log('ERROR'); // Captures as 'error' result
+     * ```
+     */
     log(levelName: string): void;
+    /**
+     * Flushes any buffered content.
+     *
+     * This implementation resets the internal buffer. Override
+     * this method in subclasses to implement custom flushing behavior.
+     *
+     * @override
+     */
     flush(): void;
+    /**
+     * Destroys the handler and cleans up resources.
+     *
+     * Flushes any remaining content and removes event listeners
+     * to prevent memory leaks.
+     *
+     * @override
+     *
+     * @example
+     * ```typescript
+     * const handler = new ResultsHandler('WARN', { context });
+     *
+     * try {
+     *   // Use handler
+     *   logger.addHandler(handler);
+     *   await processDocument();
+     * } finally {
+     *   // Always clean up
+     *   handler.destroy();
+     * }
+     * ```
+     */
     destroy(): void;
 }
 //# sourceMappingURL=ResultsHandler.d.ts.map

package/esm/context/ResultsHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ResultsHandler.d.ts","sourceRoot":"","sources":["../../src/context/ResultsHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,4CAA4C,CAAA;AACtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAA;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,kDAAkD,CAAA;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAA;AAC1F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGnD,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,OAAO,EAAE,WAAW,CAAA;CACrB;AAED,qBAAa,cAAe,SAAQ,WAAW;;IAC7C,OAAO,EAAE,WAAW,CAAA;gBAMR,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB;IAMvD,KAAK;IAML,MAAM,CAAC,SAAS,EAAE,SAAS;IASpC,GAAG,CAAC,SAAS,EAAE,MAAM;IAWrB,KAAK;IAMI,OAAO;CAKjB"}
+{"version":3,"file":"ResultsHandler.d.ts","sourceRoot":"","sources":["../../src/context/ResultsHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,4CAA4C,CAAA;AACtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAA;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,kDAAkD,CAAA;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAA;AAC1F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGnD;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,qDAAqD;IACrD,OAAO,EAAE,WAAW,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,qBAAa,cAAe,SAAQ,WAAW;;IAC7C,qDAAqD;IACrD,OAAO,EAAE,WAAW,CAAA;IAOpB;;;;;;;;;;;;;;OAcG;gBACS,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB;IAMhE;;;;;;;OAOG;IACM,KAAK;IAMd;;;;;;;;;OASG;IACM,MAAM,CAAC,SAAS,EAAE,SAAS;IASpC;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM;IAWrB;;;;;;;OAOG;IACH,KAAK;IAWL;;;;;;;;;;;;;;;;;;;;;OAqBG;IACM,OAAO;CAKjB"}

package/esm/context/ResultsHandler.js

@@ -7,25 +7,143 @@ var _ResultsHandler_instances, _ResultsHandler_unloadCallback, _ResultsHandler_r
 import { LogLevels } from '../deps/jsr.io/@std/log/0.224.14/levels.js';
 import { BaseHandler } from '../deps/jsr.io/@std/log/0.224.14/base_handler.js';
 import { match } from 'ts-pattern';
+/**
+ * Custom log handler that captures warning and error results for SKMTC processing.
+ *
+ * The `ResultsHandler` extends Deno's standard library BaseHandler to provide
+ * specialized logging behavior for the SKMTC pipeline. It integrates with the
+ * CoreContext to capture warnings and errors as structured results that can be
+ * analyzed and reported after processing completes.
+ *
+ * This handler ensures that important processing issues are captured and stored
+ * in the context's results system rather than just being logged to the console.
+ *
+ * ## Key Features
+ *
+ * - **Result Capture**: Automatically captures WARN and ERROR logs as results
+ * - **Immediate Flushing**: Critical errors trigger immediate flush
+ * - **Lifecycle Management**: Proper setup and cleanup with event handlers
+ * - **Context Integration**: Seamlessly integrates with CoreContext results system
+ *
+ * @example Setting up the handler
+ * ```typescript
+ * import { getLogger } from '@std/log';
+ * import { ResultsHandler, CoreContext } from '@skmtc/core';
+ *
+ * const context = new CoreContext({
+ *   // ... context options
+ * });
+ *
+ * const handler = new ResultsHandler('WARN', {
+ *   context: context,
+ *   formatter: '[{levelName}] {msg}'
+ * });
+ *
+ * const logger = getLogger();
+ * logger.addHandler(handler);
+ *
+ * // Now warnings and errors will be captured as results
+ * logger.warning('Schema validation issue detected');
+ * logger.error('Failed to process operation');
+ * ```
+ *
+ * @example Integration in pipeline
+ * ```typescript
+ * class ProcessingPipeline {
+ *   async process(document: OasDocument) {
+ *     const context = new CoreContext(options);
+ *
+ *     // Set up results handler
+ *     const handler = new ResultsHandler('WARN', { context });
+ *     const logger = getLogger();
+ *     logger.addHandler(handler);
+ *
+ *     try {
+ *       const result = await this.processDocument(document, context);
+ *
+ *       // Check captured results
+ *       if (context.results.hasWarnings()) {
+ *         console.log('Processing completed with warnings');
+ *       }
+ *
+ *       return result;
+ *     } finally {
+ *       handler.destroy();
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export class ResultsHandler extends BaseHandler {
+    /**
+     * Creates a new ResultsHandler instance.
+     *
+     * @param levelName - The minimum log level to handle
+     * @param options - Handler configuration including CoreContext
+     *
+     * @example
+     * ```typescript
+     * const context = new CoreContext(contextOptions);
+     * const handler = new ResultsHandler('WARN', {
+     *   context,
+     *   formatter: '[{levelName}] {msg}'
+     * });
+     * ```
+     */
     constructor(levelName, options) {
         super(levelName, options);
         _ResultsHandler_instances.add(this);
+        /** The CoreContext instance for capturing results */
         Object.defineProperty(this, "context", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Bound callback for cleanup on process unload */
         _ResultsHandler_unloadCallback.set(this, (() => {
             this.destroy();
-        }).bind(this));
+        }).bind(this)
+        /**
+         * Creates a new ResultsHandler instance.
+         *
+         * @param levelName - The minimum log level to handle
+         * @param options - Handler configuration including CoreContext
+         *
+         * @example
+         * ```typescript
+         * const context = new CoreContext(contextOptions);
+         * const handler = new ResultsHandler('WARN', {
+         *   context,
+         *   formatter: '[{levelName}] {msg}'
+         * });
+         * ```
+         */
+        );
         this.context = options.context;
     }
+    /**
+     * Sets up the handler with event listeners.
+     *
+     * Registers cleanup callbacks for process termination to ensure
+     * proper resource cleanup and result flushing.
+     *
+     * @override
+     */
     setup() {
         __classPrivateFieldGet(this, _ResultsHandler_instances, "m", _ResultsHandler_resetBuffer).call(this);
         addEventListener('unload', __classPrivateFieldGet(this, _ResultsHandler_unloadCallback, "f"));
     }
+    /**
+     * Handles incoming log records.
+     *
+     * Processes log records through the base handler and triggers
+     * immediate flushing for critical errors above ERROR level.
+     *
+     * @param logRecord - The log record to handle
+     *
+     * @override
+     */
     handle(logRecord) {
         super.handle(logRecord);
         // Immediately flush if log level is higher than ERROR
@@ -33,6 +151,23 @@ export class ResultsHandler extends BaseHandler {
             this.flush();
         }
     }
+    /**
+     * Captures log messages as results in the context.
+     *
+     * Converts log level names to result types and captures them
+     * in the associated CoreContext for later analysis.
+     *
+     * @param levelName - The log level name ('WARN' or 'ERROR')
+     *
+     * @throws {Error} When an unsupported log level is provided
+     *
+     * @example
+     * ```typescript
+     * // This is called automatically by the logging system
+     * handler.log('WARN'); // Captures as 'warning' result
+     * handler.log('ERROR'); // Captures as 'error' result
+     * ```
+     */
     log(levelName) {
         this.context.captureCurrentResult(match(levelName)
             .with('WARN', () => 'warning')
@@ -41,9 +176,39 @@ export class ResultsHandler extends BaseHandler {
             throw new Error(`Unexpected log level name: ${levelName}`);
         }));
     }
+    /**
+     * Flushes any buffered content.
+     *
+     * This implementation resets the internal buffer. Override
+     * this method in subclasses to implement custom flushing behavior.
+     *
+     * @override
+     */
     flush() {
         __classPrivateFieldGet(this, _ResultsHandler_instances, "m", _ResultsHandler_resetBuffer).call(this);
     }
+    /**
+     * Destroys the handler and cleans up resources.
+     *
+     * Flushes any remaining content and removes event listeners
+     * to prevent memory leaks.
+     *
+     * @override
+     *
+     * @example
+     * ```typescript
+     * const handler = new ResultsHandler('WARN', { context });
+     *
+     * try {
+     *   // Use handler
+     *   logger.addHandler(handler);
+     *   await processDocument();
+     * } finally {
+     *   // Always clean up
+     *   handler.destroy();
+     * }
+     * ```
+     */
     destroy() {
         this.flush();
         removeEventListener('unload', __classPrivateFieldGet(this, _ResultsHandler_unloadCallback, "f"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skmtc/core",
-  "version": "0.0.795",
+  "version": "0.0.796",
   "repository": {
     "type": "git",
     "url": "https://github.com/skmtc/skmtc.git"

package/script/context/ResultsHandler.d.ts

@@ -3,17 +3,169 @@ import type { LogRecord } from '../deps/jsr.io/@std/log/0.224.14/logger.js';
 import { BaseHandler } from '../deps/jsr.io/@std/log/0.224.14/base_handler.js';
 import type { BaseHandlerOptions } from '../deps/jsr.io/@std/log/0.224.14/base_handler.js';
 import type { CoreContext } from './CoreContext.js';
+/**
+ * Configuration options for the {@link ResultsHandler}.
+ */
 export interface ResultsHandlerOptions extends BaseHandlerOptions {
+    /** The CoreContext instance to capture results to */
     context: CoreContext;
 }
+/**
+ * Custom log handler that captures warning and error results for SKMTC processing.
+ *
+ * The `ResultsHandler` extends Deno's standard library BaseHandler to provide
+ * specialized logging behavior for the SKMTC pipeline. It integrates with the
+ * CoreContext to capture warnings and errors as structured results that can be
+ * analyzed and reported after processing completes.
+ *
+ * This handler ensures that important processing issues are captured and stored
+ * in the context's results system rather than just being logged to the console.
+ *
+ * ## Key Features
+ *
+ * - **Result Capture**: Automatically captures WARN and ERROR logs as results
+ * - **Immediate Flushing**: Critical errors trigger immediate flush
+ * - **Lifecycle Management**: Proper setup and cleanup with event handlers
+ * - **Context Integration**: Seamlessly integrates with CoreContext results system
+ *
+ * @example Setting up the handler
+ * ```typescript
+ * import { getLogger } from '@std/log';
+ * import { ResultsHandler, CoreContext } from '@skmtc/core';
+ *
+ * const context = new CoreContext({
+ *   // ... context options
+ * });
+ *
+ * const handler = new ResultsHandler('WARN', {
+ *   context: context,
+ *   formatter: '[{levelName}] {msg}'
+ * });
+ *
+ * const logger = getLogger();
+ * logger.addHandler(handler);
+ *
+ * // Now warnings and errors will be captured as results
+ * logger.warning('Schema validation issue detected');
+ * logger.error('Failed to process operation');
+ * ```
+ *
+ * @example Integration in pipeline
+ * ```typescript
+ * class ProcessingPipeline {
+ *   async process(document: OasDocument) {
+ *     const context = new CoreContext(options);
+ *
+ *     // Set up results handler
+ *     const handler = new ResultsHandler('WARN', { context });
+ *     const logger = getLogger();
+ *     logger.addHandler(handler);
+ *
+ *     try {
+ *       const result = await this.processDocument(document, context);
+ *
+ *       // Check captured results
+ *       if (context.results.hasWarnings()) {
+ *         console.log('Processing completed with warnings');
+ *       }
+ *
+ *       return result;
+ *     } finally {
+ *       handler.destroy();
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class ResultsHandler extends BaseHandler {
     #private;
+    /** The CoreContext instance for capturing results */
     context: CoreContext;
+    /**
+     * Creates a new ResultsHandler instance.
+     *
+     * @param levelName - The minimum log level to handle
+     * @param options - Handler configuration including CoreContext
+     *
+     * @example
+     * ```typescript
+     * const context = new CoreContext(contextOptions);
+     * const handler = new ResultsHandler('WARN', {
+     *   context,
+     *   formatter: '[{levelName}] {msg}'
+     * });
+     * ```
+     */
     constructor(levelName: LevelName, options: ResultsHandlerOptions);
+    /**
+     * Sets up the handler with event listeners.
+     *
+     * Registers cleanup callbacks for process termination to ensure
+     * proper resource cleanup and result flushing.
+     *
+     * @override
+     */
     setup(): void;
+    /**
+     * Handles incoming log records.
+     *
+     * Processes log records through the base handler and triggers
+     * immediate flushing for critical errors above ERROR level.
+     *
+     * @param logRecord - The log record to handle
+     *
+     * @override
+     */
     handle(logRecord: LogRecord): void;
+    /**
+     * Captures log messages as results in the context.
+     *
+     * Converts log level names to result types and captures them
+     * in the associated CoreContext for later analysis.
+     *
+     * @param levelName - The log level name ('WARN' or 'ERROR')
+     *
+     * @throws {Error} When an unsupported log level is provided
+     *
+     * @example
+     * ```typescript
+     * // This is called automatically by the logging system
+     * handler.log('WARN'); // Captures as 'warning' result
+     * handler.log('ERROR'); // Captures as 'error' result
+     * ```
+     */
     log(levelName: string): void;
+    /**
+     * Flushes any buffered content.
+     *
+     * This implementation resets the internal buffer. Override
+     * this method in subclasses to implement custom flushing behavior.
+     *
+     * @override
+     */
     flush(): void;
+    /**
+     * Destroys the handler and cleans up resources.
+     *
+     * Flushes any remaining content and removes event listeners
+     * to prevent memory leaks.
+     *
+     * @override
+     *
+     * @example
+     * ```typescript
+     * const handler = new ResultsHandler('WARN', { context });
+     *
+     * try {
+     *   // Use handler
+     *   logger.addHandler(handler);
+     *   await processDocument();
+     * } finally {
+     *   // Always clean up
+     *   handler.destroy();
+     * }
+     * ```
+     */
     destroy(): void;
 }
 //# sourceMappingURL=ResultsHandler.d.ts.map

package/script/context/ResultsHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ResultsHandler.d.ts","sourceRoot":"","sources":["../../src/context/ResultsHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,4CAA4C,CAAA;AACtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAA;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,kDAAkD,CAAA;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAA;AAC1F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGnD,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,OAAO,EAAE,WAAW,CAAA;CACrB;AAED,qBAAa,cAAe,SAAQ,WAAW;;IAC7C,OAAO,EAAE,WAAW,CAAA;gBAMR,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB;IAMvD,KAAK;IAML,MAAM,CAAC,SAAS,EAAE,SAAS;IASpC,GAAG,CAAC,SAAS,EAAE,MAAM;IAWrB,KAAK;IAMI,OAAO;CAKjB"}
+{"version":3,"file":"ResultsHandler.d.ts","sourceRoot":"","sources":["../../src/context/ResultsHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,4CAA4C,CAAA;AACtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAA;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,kDAAkD,CAAA;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAA;AAC1F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGnD;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,qDAAqD;IACrD,OAAO,EAAE,WAAW,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,qBAAa,cAAe,SAAQ,WAAW;;IAC7C,qDAAqD;IACrD,OAAO,EAAE,WAAW,CAAA;IAOpB;;;;;;;;;;;;;;OAcG;gBACS,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB;IAMhE;;;;;;;OAOG;IACM,KAAK;IAMd;;;;;;;;;OASG;IACM,MAAM,CAAC,SAAS,EAAE,SAAS;IASpC;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM;IAWrB;;;;;;;OAOG;IACH,KAAK;IAWL;;;;;;;;;;;;;;;;;;;;;OAqBG;IACM,OAAO;CAKjB"}

package/script/context/ResultsHandler.js

@@ -10,25 +10,143 @@ exports.ResultsHandler = void 0;
 const levels_js_1 = require("../deps/jsr.io/@std/log/0.224.14/levels.js");
 const base_handler_js_1 = require("../deps/jsr.io/@std/log/0.224.14/base_handler.js");
 const ts_pattern_1 = require("ts-pattern");
+/**
+ * Custom log handler that captures warning and error results for SKMTC processing.
+ *
+ * The `ResultsHandler` extends Deno's standard library BaseHandler to provide
+ * specialized logging behavior for the SKMTC pipeline. It integrates with the
+ * CoreContext to capture warnings and errors as structured results that can be
+ * analyzed and reported after processing completes.
+ *
+ * This handler ensures that important processing issues are captured and stored
+ * in the context's results system rather than just being logged to the console.
+ *
+ * ## Key Features
+ *
+ * - **Result Capture**: Automatically captures WARN and ERROR logs as results
+ * - **Immediate Flushing**: Critical errors trigger immediate flush
+ * - **Lifecycle Management**: Proper setup and cleanup with event handlers
+ * - **Context Integration**: Seamlessly integrates with CoreContext results system
+ *
+ * @example Setting up the handler
+ * ```typescript
+ * import { getLogger } from '@std/log';
+ * import { ResultsHandler, CoreContext } from '@skmtc/core';
+ *
+ * const context = new CoreContext({
+ *   // ... context options
+ * });
+ *
+ * const handler = new ResultsHandler('WARN', {
+ *   context: context,
+ *   formatter: '[{levelName}] {msg}'
+ * });
+ *
+ * const logger = getLogger();
+ * logger.addHandler(handler);
+ *
+ * // Now warnings and errors will be captured as results
+ * logger.warning('Schema validation issue detected');
+ * logger.error('Failed to process operation');
+ * ```
+ *
+ * @example Integration in pipeline
+ * ```typescript
+ * class ProcessingPipeline {
+ *   async process(document: OasDocument) {
+ *     const context = new CoreContext(options);
+ *
+ *     // Set up results handler
+ *     const handler = new ResultsHandler('WARN', { context });
+ *     const logger = getLogger();
+ *     logger.addHandler(handler);
+ *
+ *     try {
+ *       const result = await this.processDocument(document, context);
+ *
+ *       // Check captured results
+ *       if (context.results.hasWarnings()) {
+ *         console.log('Processing completed with warnings');
+ *       }
+ *
+ *       return result;
+ *     } finally {
+ *       handler.destroy();
+ *     }
+ *   }
+ * }
+ * ```
+ */
 class ResultsHandler extends base_handler_js_1.BaseHandler {
+    /**
+     * Creates a new ResultsHandler instance.
+     *
+     * @param levelName - The minimum log level to handle
+     * @param options - Handler configuration including CoreContext
+     *
+     * @example
+     * ```typescript
+     * const context = new CoreContext(contextOptions);
+     * const handler = new ResultsHandler('WARN', {
+     *   context,
+     *   formatter: '[{levelName}] {msg}'
+     * });
+     * ```
+     */
     constructor(levelName, options) {
         super(levelName, options);
         _ResultsHandler_instances.add(this);
+        /** The CoreContext instance for capturing results */
         Object.defineProperty(this, "context", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Bound callback for cleanup on process unload */
         _ResultsHandler_unloadCallback.set(this, (() => {
             this.destroy();
-        }).bind(this));
+        }).bind(this)
+        /**
+         * Creates a new ResultsHandler instance.
+         *
+         * @param levelName - The minimum log level to handle
+         * @param options - Handler configuration including CoreContext
+         *
+         * @example
+         * ```typescript
+         * const context = new CoreContext(contextOptions);
+         * const handler = new ResultsHandler('WARN', {
+         *   context,
+         *   formatter: '[{levelName}] {msg}'
+         * });
+         * ```
+         */
+        );
         this.context = options.context;
     }
+    /**
+     * Sets up the handler with event listeners.
+     *
+     * Registers cleanup callbacks for process termination to ensure
+     * proper resource cleanup and result flushing.
+     *
+     * @override
+     */
     setup() {
         __classPrivateFieldGet(this, _ResultsHandler_instances, "m", _ResultsHandler_resetBuffer).call(this);
         addEventListener('unload', __classPrivateFieldGet(this, _ResultsHandler_unloadCallback, "f"));
     }
+    /**
+     * Handles incoming log records.
+     *
+     * Processes log records through the base handler and triggers
+     * immediate flushing for critical errors above ERROR level.
+     *
+     * @param logRecord - The log record to handle
+     *
+     * @override
+     */
     handle(logRecord) {
         super.handle(logRecord);
         // Immediately flush if log level is higher than ERROR
@@ -36,6 +154,23 @@ class ResultsHandler extends base_handler_js_1.BaseHandler {
             this.flush();
         }
     }
+    /**
+     * Captures log messages as results in the context.
+     *
+     * Converts log level names to result types and captures them
+     * in the associated CoreContext for later analysis.
+     *
+     * @param levelName - The log level name ('WARN' or 'ERROR')
+     *
+     * @throws {Error} When an unsupported log level is provided
+     *
+     * @example
+     * ```typescript
+     * // This is called automatically by the logging system
+     * handler.log('WARN'); // Captures as 'warning' result
+     * handler.log('ERROR'); // Captures as 'error' result
+     * ```
+     */
     log(levelName) {
         this.context.captureCurrentResult((0, ts_pattern_1.match)(levelName)
             .with('WARN', () => 'warning')
@@ -44,9 +179,39 @@ class ResultsHandler extends base_handler_js_1.BaseHandler {
             throw new Error(`Unexpected log level name: ${levelName}`);
         }));
     }
+    /**
+     * Flushes any buffered content.
+     *
+     * This implementation resets the internal buffer. Override
+     * this method in subclasses to implement custom flushing behavior.
+     *
+     * @override
+     */
     flush() {
         __classPrivateFieldGet(this, _ResultsHandler_instances, "m", _ResultsHandler_resetBuffer).call(this);
     }
+    /**
+     * Destroys the handler and cleans up resources.
+     *
+     * Flushes any remaining content and removes event listeners
+     * to prevent memory leaks.
+     *
+     * @override
+     *
+     * @example
+     * ```typescript
+     * const handler = new ResultsHandler('WARN', { context });
+     *
+     * try {
+     *   // Use handler
+     *   logger.addHandler(handler);
+     *   await processDocument();
+     * } finally {
+     *   // Always clean up
+     *   handler.destroy();
+     * }
+     * ```
+     */
     destroy() {
         this.flush();
         removeEventListener('unload', __classPrivateFieldGet(this, _ResultsHandler_unloadCallback, "f"));