@skmtc/core 0.0.789 → 0.0.790

package/esm/context/RenderContext.d.ts

@@ -8,16 +8,206 @@ import type * as log from '../deps/jsr.io/@std/log/0.224.14/mod.js';
 import { File } from '../dsl/File.js';
 import type { Preview, Mapping } from '../types/Preview.js';
 import type { JsonFile } from '../dsl/JsonFile.js';
+/**
+ * Constructor arguments for {@link RenderContext}.
+ */
 type ConstructorArgs = {
+    /** Map of generated files to render */
     files: Map<string, File | JsonFile>;
+    /** Preview data for generated content */
     previews: Record<string, Record<string, Preview>>;
+    /** Mapping data for file relationships */
     mappings: Record<string, Record<string, Mapping>>;
+    /** Optional Prettier configuration for code formatting */
     prettierConfig?: PrettierConfigType;
+    /** Base path for resolving file paths */
     basePath: string | undefined;
+    /** Stack trail for distributed tracing */
     stackTrail: StackTrail;
+    /** Logger instance for debug information */
     logger: log.Logger;
+    /** Function to capture result status */
     captureCurrentResult: (result: ResultType) => void;
 };
+/**
+ * The rendering context for the final phase of the SKMTC transformation pipeline.
+ *
+ * `RenderContext` is responsible for taking the generated artifacts from the generation
+ * phase and rendering them into their final form with proper formatting, path resolution,
+ * and file preparation. It handles code formatting via Prettier, path normalization,
+ * and produces the final artifacts ready for writing to the filesystem.
+ *
+ * This context represents the culmination of the three-phase SKMTC pipeline, transforming
+ * generator outputs into production-ready code files with proper formatting and structure.
+ *
+ * ## Key Features
+ *
+ * - **Code Formatting**: Automatic Prettier formatting for generated TypeScript/JavaScript code
+ * - **Path Resolution**: Intelligent path resolution with base path support
+ * - **Content Collation**: Combines all generated content into organized file structures
+ * - **Metadata Generation**: Tracks file statistics (lines, characters) and relationships
+ * - **Error Tracking**: Comprehensive error handling with Sentry integration
+ * - **Performance Monitoring**: Built-in tracing and performance measurement
+ *
+ * @example Basic rendering usage
+ * ```typescript
+ * import { RenderContext } from '@skmtc/core';
+ *
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: previewData,
+ *   mappings: mappingData,
+ *   prettierConfig: {
+ *     semi: false,
+ *     singleQuote: true,
+ *     trailingComma: 'all'
+ *   },
+ *   basePath: './src/generated',
+ *   stackTrail: traceStack,
+ *   logger: myLogger,
+ *   captureCurrentResult: (result) => console.log(result)
+ * });
+ *
+ * const rendered = await renderContext.render();
+ *
+ * // Access rendered files
+ * Object.entries(rendered.artifacts).forEach(([path, content]) => {
+ *   console.log(`Rendered ${path}: ${rendered.files[path].lines} lines`);
+ *   // Write to filesystem
+ *   await Deno.writeTextFile(path, content);
+ * });
+ * ```
+ *
+ * @example With custom Prettier configuration
+ * ```typescript
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: {},
+ *   mappings: {},
+ *   prettierConfig: {
+ *     parser: 'typescript',
+ *     printWidth: 120,
+ *     tabWidth: 2,
+ *     semi: true,
+ *     singleQuote: true,
+ *     trailingComma: 'es5',
+ *     bracketSpacing: true,
+ *     arrowParens: 'avoid'
+ *   },
+ *   basePath: './packages/api-client/src',
+ *   stackTrail: stack,
+ *   logger: logger,
+ *   captureCurrentResult: resultHandler
+ * });
+ *
+ * const result = await renderContext.render();
+ *
+ * // All TypeScript files are automatically formatted
+ * console.log('Formatted files:', Object.keys(result.artifacts).length);
+ * ```
+ *
+ * @example Processing render results
+ * ```typescript
+ * const rendered = await renderContext.render();
+ *
+ * // Analyze file statistics
+ * const totalLines = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.lines, 0);
+ * const totalChars = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.characters, 0);
+ *
+ * console.log(`Generated ${Object.keys(rendered.artifacts).length} files`);
+ * console.log(`Total lines: ${totalLines}`);
+ * console.log(`Total characters: ${totalChars}`);
+ *
+ * // Check for large files
+ * const largeFiles = Object.entries(rendered.files)
+ *   .filter(([_, metadata]) => metadata.lines > 1000)
+ *   .map(([path, metadata]) => ({ path, lines: metadata.lines }));
+ *
+ * if (largeFiles.length > 0) {
+ *   console.log('Large files detected:', largeFiles);
+ * }
+ *
+ * // Access preview and mapping data
+ * console.log('Previews available:', Object.keys(rendered.previews));
+ * console.log('Mappings available:', Object.keys(rendered.mappings));
+ * ```
+ *
+ * @example Integration with CoreContext
+ * ```typescript
+ * // Typically used within CoreContext.toArtifacts()
+ * class CustomCoreContext extends CoreContext {
+ *   async renderWithPostProcessing(
+ *     files: Map<string, File | JsonFile>,
+ *     previews: Record<string, Record<string, Preview>>,
+ *     mappings: Record<string, Record<string, Mapping>>
+ *   ) {
+ *     const renderContext = new RenderContext({
+ *       files,
+ *       previews,
+ *       mappings,
+ *       prettierConfig: this.prettierConfig,
+ *       basePath: this.settings?.basePath,
+ *       stackTrail: this.stackTrail,
+ *       logger: this.logger,
+ *       captureCurrentResult: this.captureCurrentResult.bind(this)
+ *     });
+ *
+ *     const rendered = await renderContext.render();
+ *
+ *     // Post-process rendered files
+ *     const processedArtifacts: Record<string, string> = {};
+ *
+ *     for (const [path, content] of Object.entries(rendered.artifacts)) {
+ *       // Add file headers, license notices, etc.
+ *       const processedContent = this.addFileHeader(content, path);
+ *       processedArtifacts[path] = processedContent;
+ *     }
+ *
+ *     return {
+ *       ...rendered,
+ *       artifacts: processedArtifacts
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @example Error handling during rendering
+ * ```typescript
+ * try {
+ *   const renderContext = new RenderContext({
+ *     files: generatedFiles,
+ *     previews: {},
+ *     mappings: {},
+ *     prettierConfig: prettierConfig,
+ *     basePath: './invalid-path', // This might cause issues
+ *     stackTrail: stack,
+ *     logger: logger,
+ *     captureCurrentResult: (result) => {
+ *       if (result === 'error') {
+ *         console.error('Render error detected');
+ *       }
+ *     }
+ *   });
+ *
+ *   const result = await renderContext.render();
+ *
+ *   // Check if any files failed to render
+ *   const failedFiles = Object.entries(result.files)
+ *     .filter(([path, metadata]) => metadata.lines === 0)
+ *     .map(([path]) => path);
+ *
+ *   if (failedFiles.length > 0) {
+ *     console.warn('Files with no content:', failedFiles);
+ *   }
+ *
+ * } catch (error) {
+ *   console.error('Render operation failed:', error);
+ *   // Sentry automatically captures the error
+ * }
+ * ```
+ */
 export declare class RenderContext {
     #private;
     files: Map<string, File | JsonFile>;

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

@@ -1 +1 @@
-{"version":3,"file":"RenderContext.d.ts","sourceRoot":"","sources":["../../src/context/RenderContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAEpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAGrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,KAAK,GAAG,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAA;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAElD,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC,CAAA;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,cAAc,CAAC,EAAE,kBAAkB,CAAA;IACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;IAClB,oBAAoB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;CACnD,CAAA;AAsBD,qBAAa,aAAa;;IACxB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC,CAAA;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAEjD,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;IAElB,oBAAoB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;gBACtC,EACV,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,MAAM,EACN,UAAU,EACV,oBAAoB,EACrB,EAAE,eAAe;IAWZ,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IAiBhD,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAuC3C,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAIlD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ;IAU1C,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS;CAO7D"}
+{"version":3,"file":"RenderContext.d.ts","sourceRoot":"","sources":["../../src/context/RenderContext.ts"],"names":[],"mappings":"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"}

package/esm/context/RenderContext.js

@@ -17,6 +17,185 @@ import { toResolvedArtifactPath } from '../helpers/toResolvedArtifactPath.js';
 import { tracer } from '../helpers/tracer.js';
 import { File } from '../dsl/File.js';
 import * as prettier from 'prettier';
+/**
+ * The rendering context for the final phase of the SKMTC transformation pipeline.
+ *
+ * `RenderContext` is responsible for taking the generated artifacts from the generation
+ * phase and rendering them into their final form with proper formatting, path resolution,
+ * and file preparation. It handles code formatting via Prettier, path normalization,
+ * and produces the final artifacts ready for writing to the filesystem.
+ *
+ * This context represents the culmination of the three-phase SKMTC pipeline, transforming
+ * generator outputs into production-ready code files with proper formatting and structure.
+ *
+ * ## Key Features
+ *
+ * - **Code Formatting**: Automatic Prettier formatting for generated TypeScript/JavaScript code
+ * - **Path Resolution**: Intelligent path resolution with base path support
+ * - **Content Collation**: Combines all generated content into organized file structures
+ * - **Metadata Generation**: Tracks file statistics (lines, characters) and relationships
+ * - **Error Tracking**: Comprehensive error handling with Sentry integration
+ * - **Performance Monitoring**: Built-in tracing and performance measurement
+ *
+ * @example Basic rendering usage
+ * ```typescript
+ * import { RenderContext } from '@skmtc/core';
+ *
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: previewData,
+ *   mappings: mappingData,
+ *   prettierConfig: {
+ *     semi: false,
+ *     singleQuote: true,
+ *     trailingComma: 'all'
+ *   },
+ *   basePath: './src/generated',
+ *   stackTrail: traceStack,
+ *   logger: myLogger,
+ *   captureCurrentResult: (result) => console.log(result)
+ * });
+ *
+ * const rendered = await renderContext.render();
+ *
+ * // Access rendered files
+ * Object.entries(rendered.artifacts).forEach(([path, content]) => {
+ *   console.log(`Rendered ${path}: ${rendered.files[path].lines} lines`);
+ *   // Write to filesystem
+ *   await Deno.writeTextFile(path, content);
+ * });
+ * ```
+ *
+ * @example With custom Prettier configuration
+ * ```typescript
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: {},
+ *   mappings: {},
+ *   prettierConfig: {
+ *     parser: 'typescript',
+ *     printWidth: 120,
+ *     tabWidth: 2,
+ *     semi: true,
+ *     singleQuote: true,
+ *     trailingComma: 'es5',
+ *     bracketSpacing: true,
+ *     arrowParens: 'avoid'
+ *   },
+ *   basePath: './packages/api-client/src',
+ *   stackTrail: stack,
+ *   logger: logger,
+ *   captureCurrentResult: resultHandler
+ * });
+ *
+ * const result = await renderContext.render();
+ *
+ * // All TypeScript files are automatically formatted
+ * console.log('Formatted files:', Object.keys(result.artifacts).length);
+ * ```
+ *
+ * @example Processing render results
+ * ```typescript
+ * const rendered = await renderContext.render();
+ *
+ * // Analyze file statistics
+ * const totalLines = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.lines, 0);
+ * const totalChars = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.characters, 0);
+ *
+ * console.log(`Generated ${Object.keys(rendered.artifacts).length} files`);
+ * console.log(`Total lines: ${totalLines}`);
+ * console.log(`Total characters: ${totalChars}`);
+ *
+ * // Check for large files
+ * const largeFiles = Object.entries(rendered.files)
+ *   .filter(([_, metadata]) => metadata.lines > 1000)
+ *   .map(([path, metadata]) => ({ path, lines: metadata.lines }));
+ *
+ * if (largeFiles.length > 0) {
+ *   console.log('Large files detected:', largeFiles);
+ * }
+ *
+ * // Access preview and mapping data
+ * console.log('Previews available:', Object.keys(rendered.previews));
+ * console.log('Mappings available:', Object.keys(rendered.mappings));
+ * ```
+ *
+ * @example Integration with CoreContext
+ * ```typescript
+ * // Typically used within CoreContext.toArtifacts()
+ * class CustomCoreContext extends CoreContext {
+ *   async renderWithPostProcessing(
+ *     files: Map<string, File | JsonFile>,
+ *     previews: Record<string, Record<string, Preview>>,
+ *     mappings: Record<string, Record<string, Mapping>>
+ *   ) {
+ *     const renderContext = new RenderContext({
+ *       files,
+ *       previews,
+ *       mappings,
+ *       prettierConfig: this.prettierConfig,
+ *       basePath: this.settings?.basePath,
+ *       stackTrail: this.stackTrail,
+ *       logger: this.logger,
+ *       captureCurrentResult: this.captureCurrentResult.bind(this)
+ *     });
+ *
+ *     const rendered = await renderContext.render();
+ *
+ *     // Post-process rendered files
+ *     const processedArtifacts: Record<string, string> = {};
+ *
+ *     for (const [path, content] of Object.entries(rendered.artifacts)) {
+ *       // Add file headers, license notices, etc.
+ *       const processedContent = this.addFileHeader(content, path);
+ *       processedArtifacts[path] = processedContent;
+ *     }
+ *
+ *     return {
+ *       ...rendered,
+ *       artifacts: processedArtifacts
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @example Error handling during rendering
+ * ```typescript
+ * try {
+ *   const renderContext = new RenderContext({
+ *     files: generatedFiles,
+ *     previews: {},
+ *     mappings: {},
+ *     prettierConfig: prettierConfig,
+ *     basePath: './invalid-path', // This might cause issues
+ *     stackTrail: stack,
+ *     logger: logger,
+ *     captureCurrentResult: (result) => {
+ *       if (result === 'error') {
+ *         console.error('Render error detected');
+ *       }
+ *     }
+ *   });
+ *
+ *   const result = await renderContext.render();
+ *
+ *   // Check if any files failed to render
+ *   const failedFiles = Object.entries(result.files)
+ *     .filter(([path, metadata]) => metadata.lines === 0)
+ *     .map(([path]) => path);
+ *
+ *   if (failedFiles.length > 0) {
+ *     console.warn('Files with no content:', failedFiles);
+ *   }
+ *
+ * } catch (error) {
+ *   console.error('Render operation failed:', error);
+ *   // Sentry automatically captures the error
+ * }
+ * ```
+ */
 export class RenderContext {
     constructor({ files, previews, mappings, prettierConfig, basePath, logger, stackTrail, captureCurrentResult }) {
         Object.defineProperty(this, "files", {

package/esm/oas/boolean/Boolean.d.ts

@@ -2,17 +2,158 @@ import "../../_dnt.polyfills.js";
 import type { OpenAPIV3 } from 'openapi-types';
 import type { OasRef } from '../ref/Ref.js';
 import type { ToJsonSchemaOptions } from '../schema/Schema.js';
+/**
+ * Constructor fields for {@link OasBoolean}.
+ *
+ * @template Nullable - Whether the boolean can be null (affects type unions)
+ */
 export type BooleanFields<Nullable extends boolean | undefined> = {
+    /** A short summary of the boolean schema */
     title?: string;
+    /** A description of the boolean schema */
     description?: string;
+    /** Whether the boolean value can be null */
     nullable?: Nullable;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
+    /** Example value for the boolean (null allowed if Nullable is true) */
     example?: Nullable extends true ? boolean | null | undefined : boolean | undefined;
+    /** Array of valid enum values for the boolean (null allowed if Nullable is true) */
     enums?: Nullable extends true ? (boolean | null)[] | undefined : boolean[] | undefined;
+    /** Default value for the boolean (null allowed if Nullable is true) */
     default?: Nullable extends true ? boolean | null | undefined : boolean | undefined;
 };
 /**
- * Object representing a boolean in the OpenAPI Specification.
+ * Represents a boolean schema in the OpenAPI Specification.
+ *
+ * The `OasBoolean` class handles boolean data types in OpenAPI schemas, supporting
+ * both simple true/false values and more complex boolean schemas with constraints,
+ * enumerations, and nullable types. This class provides type-safe boolean handling
+ * with optional null value support through generic typing.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Generic nullable type support with proper TypeScript inference
+ * - **Enum Support**: Constrain boolean values to specific true/false combinations
+ * - **Null Handling**: Optional null value support for nullable boolean types
+ * - **Validation**: Default values and example validation
+ * - **JSON Schema**: Converts to standard JSON Schema format for validation
+ * - **Documentation**: Rich metadata support for API documentation
+ *
+ * @template Nullable - Whether the boolean value itself can be null
+ *
+ * @example Basic boolean schema
+ * ```typescript
+ * import { OasBoolean } from '@skmtc/core';
+ *
+ * const isActiveSchema = new OasBoolean({
+ *   title: 'Active Status',
+ *   description: 'Whether the user account is active',
+ *   default: true,
+ *   example: true
+ * });
+ *
+ * // This represents: boolean with default true
+ * ```
+ *
+ * @example Nullable boolean schema
+ * ```typescript
+ * const nullableFlag = new OasBoolean<true>({
+ *   title: 'Optional Flag',
+ *   description: 'An optional boolean flag that can be null',
+ *   nullable: true,
+ *   default: null,
+ *   example: true
+ * });
+ *
+ * // This represents: boolean | null
+ * ```
+ *
+ * @example Boolean with enum constraints
+ * ```typescript
+ * const strictBoolean = new OasBoolean({
+ *   title: 'Confirmation',
+ *   description: 'Must explicitly be true to confirm action',
+ *   enums: [true], // Only true is allowed
+ *   example: true
+ * });
+ *
+ * // This only accepts true, effectively making it required
+ * ```
+ *
+ * @example Boolean with null in enum
+ * ```typescript
+ * const triStateBoolean = new OasBoolean<true>({
+ *   title: 'Approval Status',
+ *   description: 'Approval can be true (approved), false (denied), or null (pending)',
+ *   nullable: true,
+ *   enums: [true, false, null],
+ *   default: null,
+ *   example: null
+ * });
+ *
+ * // This represents: true | false | null (tri-state logic)
+ * ```
+ *
+ * @example Feature flag schema
+ * ```typescript
+ * const featureFlag = new OasBoolean({
+ *   title: 'Feature Enabled',
+ *   description: 'Whether the new feature is enabled for this user',
+ *   default: false,
+ *   example: false
+ * });
+ *
+ * // Used in configuration objects
+ * const userConfig = new OasObject({
+ *   properties: {
+ *     darkMode: featureFlag,
+ *     notifications: featureFlag,
+ *     betaFeatures: featureFlag
+ *   }
+ * });
+ * ```
+ *
+ * @example Consent and agreement booleans
+ * ```typescript
+ * const consentSchema = new OasBoolean({
+ *   title: 'Terms Accepted',
+ *   description: 'User has accepted the terms and conditions',
+ *   enums: [true], // Must be true to be valid
+ *   example: true
+ * });
+ *
+ * const privacyConsent = new OasBoolean({
+ *   title: 'Privacy Policy Accepted',
+ *   description: 'User has accepted the privacy policy',
+ *   default: false,
+ *   example: true
+ * });
+ *
+ * // Used in registration forms where consent is required
+ * ```
+ *
+ * @example Optional settings with nullable booleans
+ * ```typescript
+ * const userPreferences = new OasObject({
+ *   properties: {
+ *     emailNotifications: new OasBoolean<true>({
+ *       title: 'Email Notifications',
+ *       description: 'Enable email notifications (null means use default)',
+ *       nullable: true,
+ *       default: null
+ *     }),
+ *     smsNotifications: new OasBoolean<true>({
+ *       title: 'SMS Notifications',
+ *       description: 'Enable SMS notifications (null means not set)',
+ *       nullable: true,
+ *       default: null
+ *     })
+ *   }
+ * });
+ *
+ * // Allows: { emailNotifications: true, smsNotifications: null }
+ * ```
  */
 export declare class OasBoolean<Nullable extends boolean | undefined = boolean | undefined> {
     /**

package/esm/oas/boolean/Boolean.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Boolean.d.ts","sourceRoot":"","sources":["../../../src/oas/boolean/Boolean.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,MAAM,MAAM,aAAa,CAAC,QAAQ,SAAS,OAAO,GAAG,SAAS,IAAI;IAChE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzC,OAAO,CAAC,EAAE,QAAQ,SAAS,IAAI,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;IAClF,KAAK,CAAC,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;IACtF,OAAO,CAAC,EAAE,QAAQ,SAAS,IAAI,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;CACnF,CAAA;AAED;;GAEG;AACH,qBAAa,UAAU,CAAC,QAAQ,SAAS,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS;IAChF;;;OAGG;IACH,OAAO,EAAG,QAAQ,CAAS;IAC3B;;OAEG;IACH,IAAI,EAAG,SAAS,CAAS;IACzB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B;;OAEG;IACH,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAA;IAE9B,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACpD;;OAEG;IACH,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;IAEjF;;OAEG;IACH,KAAK,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;IACrF;;OAEG;IACH,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;gBAErE,MAAM,GAAE,aAAa,CAAC,QAAQ,CAAM;IAUhD,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC;IAIjC,OAAO,IAAI,UAAU,CAAC,QAAQ,CAAC;IAI/B,WAAW,IAAI,UAAU,CAAC,QAAQ,CAAC;IAKnC,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC,oBAAoB;CAW5E"}
+{"version":3,"file":"Boolean.d.ts","sourceRoot":"","sources":["../../../src/oas/boolean/Boolean.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAE9D;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,QAAQ,SAAS,OAAO,GAAG,SAAS,IAAI;IAChE,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzC,uEAAuE;IACvE,OAAO,CAAC,EAAE,QAAQ,SAAS,IAAI,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;IAClF,oFAAoF;IACpF,KAAK,CAAC,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;IACtF,uEAAuE;IACvE,OAAO,CAAC,EAAE,QAAQ,SAAS,IAAI,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;CACnF,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmIG;AACH,qBAAa,UAAU,CAAC,QAAQ,SAAS,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS;IAChF;;;OAGG;IACH,OAAO,EAAG,QAAQ,CAAS;IAC3B;;OAEG;IACH,IAAI,EAAG,SAAS,CAAS;IACzB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B;;OAEG;IACH,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAA;IAE9B,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACpD;;OAEG;IACH,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;IAEjF;;OAEG;IACH,KAAK,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;IACrF;;OAEG;IACH,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;gBAErE,MAAM,GAAE,aAAa,CAAC,QAAQ,CAAM;IAUhD,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC;IAIjC,OAAO,IAAI,UAAU,CAAC,QAAQ,CAAC;IAI/B,WAAW,IAAI,UAAU,CAAC,QAAQ,CAAC;IAKnC,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC,oBAAoB;CAW5E"}