@skmtc/core 0.0.785 → 0.0.786

package/esm/oas/document/Document.d.ts

@@ -8,23 +8,156 @@ import type { OasSecurityRequirement } from '../securityRequirement/SecurityRequ
 import type { StackTrail } from '../../context/StackTrail.js';
 import type { OasSchema } from '../schema/Schema.js';
 import type { OasRef } from '../ref/Ref.js';
+/**
+ * Fields that define the structure of an OpenAPI v3 document.
+ *
+ * This type represents the normalized structure of an OpenAPI document after
+ * parsing, with operations flattened from the nested paths structure into
+ * a simple array for easier processing.
+ */
 export type DocumentFields = {
+    /** OpenAPI specification version (e.g., '3.0.0', '3.1.0') */
     openapi: string;
+    /** API metadata including title, version, description */
     info: OasInfo;
+    /** Array of server objects providing connectivity information */
     servers?: OasServer[] | undefined;
+    /** Flattened array of all operations from all paths */
     operations: OasOperation[];
+    /** Container for reusable components (schemas, responses, etc.) */
     components?: OasComponents | undefined;
+    /** List of tags used by operations with additional metadata */
     tags?: OasTag[] | undefined;
+    /** Default security requirements that apply to all operations */
     security?: OasSecurityRequirement[] | undefined;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
 };
-/** Top level document object describing the API */
+/**
+ * Represents a complete OpenAPI v3 document in the SKMTC OAS processing system.
+ *
+ * The `OasDocument` class is the root object in the OAS hierarchy, containing all
+ * the information needed to describe a complete REST API. It provides normalized
+ * access to document properties with built-in validation and error handling.
+ *
+ * ## Key Features
+ *
+ * - **Normalized Structure**: Operations are flattened from nested paths for easier processing
+ * - **Lazy Initialization**: Fields are set after construction during parsing
+ * - **Type Safety**: All properties are typed and validated on access
+ * - **Extensibility**: Supports OpenAPI extension fields (x-* properties)
+ * - **JSON Serialization**: Can be converted back to standard OpenAPI JSON format
+ *
+ * @example Basic document access
+ * ```typescript
+ * import { OasDocument } from '@skmtc/core';
+ *
+ * // Document is typically created during parsing
+ * const document = new OasDocument();
+ * document.fields = {
+ *   openapi: '3.0.0',
+ *   info: { title: 'My API', version: '1.0.0' },
+ *   operations: [
+ *     // ... parsed operations
+ *   ],
+ *   components: {
+ *     schemas: {
+ *       User: { type: 'object', properties: { id: { type: 'string' } } }
+ *     }
+ *   }
+ * };
+ *
+ * console.log(document.info.title); // 'My API'
+ * console.log(document.operations.length); // Number of operations
+ * ```
+ *
+ * @example Iterating over operations
+ * ```typescript
+ * // Process all operations in the document
+ * for (const operation of document.operations) {
+ *   console.log(`${operation.method.toUpperCase()} ${operation.path}`);
+ *
+ *   if (operation.operationId) {
+ *     console.log(`Operation ID: ${operation.operationId}`);
+ *   }
+ * }
+ * ```
+ *
+ * @example Working with components
+ * ```typescript
+ * if (document.components?.schemas) {
+ *   const userSchema = document.components.schemas.get('User');
+ *   if (userSchema) {
+ *     console.log('User schema found:', userSchema);
+ *   }
+ * }
+ * ```
+ */
 export declare class OasDocument {
     #private;
     /** Static identifier property for OasDocument */
     oasType: 'openapi';
+    /**
+     * Creates a new OasDocument instance.
+     *
+     * The document is typically created with undefined fields and populated
+     * later during the parsing process. This allows for lazy initialization
+     * and proper error handling during document processing.
+     *
+     * @param fields - Optional document fields (usually set later during parsing)
+     *
+     * @example
+     * ```typescript
+     * // Usually created without fields during parsing
+     * const document = new OasDocument();
+     *
+     * // Fields are set later by the parser
+     * document.fields = parsedDocumentFields;
+     * ```
+     */
     constructor(fields?: DocumentFields);
+    /**
+     * Removes an item from the document based on a stack trail path.
+     *
+     * This method is used internally during document processing to remove
+     * specific operations or schema components. The stack trail indicates
+     * the path to the item within the document structure.
+     *
+     * @param stackTrail - Path to the item to remove
+     * @returns The removed item, or undefined if not found
+     *
+     * @internal This method is primarily used by the processing pipeline
+     *
+     * @example
+     * ```typescript
+     * // Remove an operation at /users POST
+     * const removed = document.removeItem(new StackTrail(['paths', '/users', 'post']));
+     *
+     * // Remove a schema component
+     * const removedSchema = document.removeItem(new StackTrail(['components', 'schemas', 'User']));
+     * ```
+     */
     removeItem(stackTrail: StackTrail): OasOperation | OasSchema | OasRef<'schema'> | undefined;
+    /**
+     * Sets the document fields after parsing.
+     *
+     * This setter is called by the parsing pipeline to populate the document
+     * with parsed OpenAPI data. It enables lazy initialization and proper
+     * error handling during document processing.
+     *
+     * @param fields - The parsed document fields
+     *
+     * @example
+     * ```typescript
+     * const document = new OasDocument();
+     * document.fields = {
+     *   openapi: '3.0.0',
+     *   info: { title: 'API', version: '1.0' },
+     *   operations: [],
+     *   // ... other fields
+     * };
+     * ```
+     */
     set fields(fields: DocumentFields);
     /** OpenAPI specification version */
     get openapi(): string;
@@ -41,6 +174,27 @@ export declare class OasDocument {
     get security(): OasSecurityRequirement[] | undefined;
     /** Specification Extension fields */
     get extensionFields(): Record<string, unknown> | undefined;
+    /**
+     * Converts the document back to a JSON-serializable OpenAPI object.
+     *
+     * This method serializes the document to a standard OpenAPI v3 format,
+     * which can be used for output, validation, or further processing. The
+     * resulting object follows the OpenAPI specification structure.
+     *
+     * @returns A JSON-serializable object representing the OpenAPI document
+     *
+     * @example
+     * ```typescript
+     * // Convert document back to standard OpenAPI format
+     * const openApiJson = document.toJSON();
+     *
+     * // Can be stringified for output
+     * const yamlString = JSON.stringify(openApiJson, null, 2);
+     *
+     * // Or used with OpenAPI tools
+     * await validateOpenApiDocument(openApiJson);
+     * ```
+     */
     toJSON(): object;
 }
 //# sourceMappingURL=Document.d.ts.map

package/esm/oas/document/Document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Document.d.ts","sourceRoot":"","sources":["../../../src/oas/document/Document.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAG7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAE3C,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,SAAS,CAAA;IACjC,UAAU,EAAE,YAAY,EAAE,CAAA;IAC1B,UAAU,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;IACtC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC3B,QAAQ,CAAC,EAAE,sBAAsB,EAAE,GAAG,SAAS,CAAA;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,mDAAmD;AACnD,qBAAa,WAAW;;IACtB,iDAAiD;IACjD,OAAO,EAAE,SAAS,CAAY;gBAIlB,MAAM,CAAC,EAAE,cAAc;IAInC,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS;IA6B3F,IAAI,MAAM,CAAC,MAAM,EAAE,cAAc,EAEhC;IAED,oCAAoC;IACpC,IAAI,OAAO,IAAI,MAAM,CAMpB;IAED,mBAAmB;IACnB,IAAI,IAAI,IAAI,OAAO,CAMlB;IAED,IAAI,OAAO,IAAI,SAAS,EAAE,GAAG,SAAS,CAMrC;IAED,yCAAyC;IACzC,IAAI,UAAU,IAAI,YAAY,EAAE,CAM/B;IAED,iEAAiE;IACjE,IAAI,UAAU,IAAI,aAAa,GAAG,SAAS,CAM1C;IAED,wDAAwD;IACxD,IAAI,IAAI,IAAI,MAAM,EAAE,GAAG,SAAS,CAM/B;IAED,gDAAgD;IAChD,IAAI,QAAQ,IAAI,sBAAsB,EAAE,GAAG,SAAS,CAMnD;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAMzD;IAED,MAAM,IAAI,MAAM;CAYjB"}
+{"version":3,"file":"Document.d.ts","sourceRoot":"","sources":["../../../src/oas/document/Document.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAG7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAE3C;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,IAAI,EAAE,OAAO,CAAA;IACb,iEAAiE;IACjE,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,SAAS,CAAA;IACjC,uDAAuD;IACvD,UAAU,EAAE,YAAY,EAAE,CAAA;IAC1B,mEAAmE;IACnE,UAAU,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;IACtC,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,sBAAsB,EAAE,GAAG,SAAS,CAAA;IAC/C,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,qBAAa,WAAW;;IACtB,iDAAiD;IACjD,OAAO,EAAE,SAAS,CAAY;IAK9B;;;;;;;;;;;;;;;;;OAiBG;gBACS,MAAM,CAAC,EAAE,cAAc;IAInC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS;IA6B3F;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,MAAM,CAAC,MAAM,EAAE,cAAc,EAEhC;IAED,oCAAoC;IACpC,IAAI,OAAO,IAAI,MAAM,CAMpB;IAED,mBAAmB;IACnB,IAAI,IAAI,IAAI,OAAO,CAMlB;IAED,IAAI,OAAO,IAAI,SAAS,EAAE,GAAG,SAAS,CAMrC;IAED,yCAAyC;IACzC,IAAI,UAAU,IAAI,YAAY,EAAE,CAM/B;IAED,iEAAiE;IACjE,IAAI,UAAU,IAAI,aAAa,GAAG,SAAS,CAM1C;IAED,wDAAwD;IACxD,IAAI,IAAI,IAAI,MAAM,EAAE,GAAG,SAAS,CAM/B;IAED,gDAAgD;IAChD,IAAI,QAAQ,IAAI,sBAAsB,EAAE,GAAG,SAAS,CAMnD;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAMzD;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,IAAI,MAAM;CAYjB"}

package/esm/oas/document/Document.js

@@ -12,8 +12,85 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 var _OasDocument_fields;
 import "../../_dnt.polyfills.js";
 import { match } from 'ts-pattern';
-/** Top level document object describing the API */
+/**
+ * Represents a complete OpenAPI v3 document in the SKMTC OAS processing system.
+ *
+ * The `OasDocument` class is the root object in the OAS hierarchy, containing all
+ * the information needed to describe a complete REST API. It provides normalized
+ * access to document properties with built-in validation and error handling.
+ *
+ * ## Key Features
+ *
+ * - **Normalized Structure**: Operations are flattened from nested paths for easier processing
+ * - **Lazy Initialization**: Fields are set after construction during parsing
+ * - **Type Safety**: All properties are typed and validated on access
+ * - **Extensibility**: Supports OpenAPI extension fields (x-* properties)
+ * - **JSON Serialization**: Can be converted back to standard OpenAPI JSON format
+ *
+ * @example Basic document access
+ * ```typescript
+ * import { OasDocument } from '@skmtc/core';
+ *
+ * // Document is typically created during parsing
+ * const document = new OasDocument();
+ * document.fields = {
+ *   openapi: '3.0.0',
+ *   info: { title: 'My API', version: '1.0.0' },
+ *   operations: [
+ *     // ... parsed operations
+ *   ],
+ *   components: {
+ *     schemas: {
+ *       User: { type: 'object', properties: { id: { type: 'string' } } }
+ *     }
+ *   }
+ * };
+ *
+ * console.log(document.info.title); // 'My API'
+ * console.log(document.operations.length); // Number of operations
+ * ```
+ *
+ * @example Iterating over operations
+ * ```typescript
+ * // Process all operations in the document
+ * for (const operation of document.operations) {
+ *   console.log(`${operation.method.toUpperCase()} ${operation.path}`);
+ *
+ *   if (operation.operationId) {
+ *     console.log(`Operation ID: ${operation.operationId}`);
+ *   }
+ * }
+ * ```
+ *
+ * @example Working with components
+ * ```typescript
+ * if (document.components?.schemas) {
+ *   const userSchema = document.components.schemas.get('User');
+ *   if (userSchema) {
+ *     console.log('User schema found:', userSchema);
+ *   }
+ * }
+ * ```
+ */
 export class OasDocument {
+    /**
+     * Creates a new OasDocument instance.
+     *
+     * The document is typically created with undefined fields and populated
+     * later during the parsing process. This allows for lazy initialization
+     * and proper error handling during document processing.
+     *
+     * @param fields - Optional document fields (usually set later during parsing)
+     *
+     * @example
+     * ```typescript
+     * // Usually created without fields during parsing
+     * const document = new OasDocument();
+     *
+     * // Fields are set later by the parser
+     * document.fields = parsedDocumentFields;
+     * ```
+     */
     constructor(fields) {
         /** Static identifier property for OasDocument */
         Object.defineProperty(this, "oasType", {
@@ -22,10 +99,31 @@ export class OasDocument {
             writable: true,
             value: 'openapi'
         });
-        /** @internal */
+        /** @internal Private fields storage */
         _OasDocument_fields.set(this, void 0);
         __classPrivateFieldSet(this, _OasDocument_fields, fields, "f");
     }
+    /**
+     * Removes an item from the document based on a stack trail path.
+     *
+     * This method is used internally during document processing to remove
+     * specific operations or schema components. The stack trail indicates
+     * the path to the item within the document structure.
+     *
+     * @param stackTrail - Path to the item to remove
+     * @returns The removed item, or undefined if not found
+     *
+     * @internal This method is primarily used by the processing pipeline
+     *
+     * @example
+     * ```typescript
+     * // Remove an operation at /users POST
+     * const removed = document.removeItem(new StackTrail(['paths', '/users', 'post']));
+     *
+     * // Remove a schema component
+     * const removedSchema = document.removeItem(new StackTrail(['components', 'schemas', 'User']));
+     * ```
+     */
     removeItem(stackTrail) {
         const [first, second, third] = stackTrail.stackTrail;
         return match(first)
@@ -47,6 +145,26 @@ export class OasDocument {
             throw new Error(`Unexpected stack trail: ${stackTrail}`);
         });
     }
+    /**
+     * Sets the document fields after parsing.
+     *
+     * This setter is called by the parsing pipeline to populate the document
+     * with parsed OpenAPI data. It enables lazy initialization and proper
+     * error handling during document processing.
+     *
+     * @param fields - The parsed document fields
+     *
+     * @example
+     * ```typescript
+     * const document = new OasDocument();
+     * document.fields = {
+     *   openapi: '3.0.0',
+     *   info: { title: 'API', version: '1.0' },
+     *   operations: [],
+     *   // ... other fields
+     * };
+     * ```
+     */
     set fields(fields) {
         __classPrivateFieldSet(this, _OasDocument_fields, fields, "f");
     }
@@ -105,6 +223,27 @@ export class OasDocument {
         }
         return __classPrivateFieldGet(this, _OasDocument_fields, "f").extensionFields;
     }
+    /**
+     * Converts the document back to a JSON-serializable OpenAPI object.
+     *
+     * This method serializes the document to a standard OpenAPI v3 format,
+     * which can be used for output, validation, or further processing. The
+     * resulting object follows the OpenAPI specification structure.
+     *
+     * @returns A JSON-serializable object representing the OpenAPI document
+     *
+     * @example
+     * ```typescript
+     * // Convert document back to standard OpenAPI format
+     * const openApiJson = document.toJSON();
+     *
+     * // Can be stringified for output
+     * const yamlString = JSON.stringify(openApiJson, null, 2);
+     *
+     * // Or used with OpenAPI tools
+     * await validateOpenApiDocument(openApiJson);
+     * ```
+     */
     toJSON() {
         return {
             openapi: this.openapi,

package/esm/oas/object/Object.d.ts

@@ -3,32 +3,138 @@ import type { OasRef } from '../ref/Ref.js';
 import type { OasSchema, ToJsonSchemaOptions } from '../schema/Schema.js';
 import type { CustomValue } from '../../types/CustomValue.js';
 import type { OpenAPIV3 } from 'openapi-types';
+/**
+ * Constructor fields for {@link OasObject}.
+ *
+ * @template Nullable - Whether the object can be null (affects type unions)
+ */
 export type OasObjectFields<Nullable extends boolean | undefined> = {
+    /** A short summary of the object */
     title?: string;
+    /** A description of the object */
     description?: string;
+    /** Record mapping property names to their schemas */
     properties?: Record<string, OasSchema | OasRef<'schema'> | CustomValue> | undefined;
+    /** Array of required property names */
     required?: string[] | undefined;
+    /** Default value for the object (null allowed if Nullable is true) */
     default?: Nullable extends true ? Record<string, unknown> | null | undefined : Record<string, unknown> | undefined;
+    /** Whether additional properties are allowed (true/false/schema) */
     additionalProperties?: boolean | OasSchema | OasRef<'schema'> | undefined;
+    /** Whether the object value can be null */
     nullable?: Nullable;
+    /** Maximum number of properties allowed */
     maxProperties?: number;
+    /** Minimum number of properties required */
     minProperties?: number;
+    /** Array of valid enum values for the object */
     enums?: Nullable extends true ? (Record<string, unknown> | null)[] | undefined : Record<string, unknown>[] | undefined;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
+    /** Example value for the object (null allowed if Nullable is true) */
     example?: Nullable extends true ? Record<string, unknown> | null | undefined : Record<string, unknown> | undefined;
+    /** Whether the object is read-only */
     readOnly?: boolean;
+    /** Whether the object is write-only */
     writeOnly?: boolean;
+    /** Whether the object is deprecated */
     deprecated?: boolean;
 };
+/**
+ * Arguments for the {@link OasObject.addProperty} method.
+ */
 export type AddPropertyArgs = {
+    /** The name of the property to add */
     name: string;
+    /** The schema definition for the property */
     schema: OasSchema | OasRef<'schema'> | CustomValue | undefined;
+    /** Whether the property should be required */
     required?: boolean;
 };
 /**
- * Object representing an object and/or a record in the OpenAPI Specification.
+ * Represents an object schema in the OpenAPI Specification.
+ *
+ * `OasObject` handles both:
+ * - **Objects**: Types with fixed, named properties (like TypeScript interfaces)
+ * - **Records**: Types with dynamic keys and consistent value types (like TypeScript Record<string, T>)
+ *
+ * This class provides comprehensive support for object validation constraints,
+ * property management, and JSON Schema conversion. It supports nullable types
+ * through generic type parameters and handles complex property relationships.
+ *
+ * ## Key Features
+ *
+ * - **Property Management**: Add/remove properties with automatic required field handling
+ * - **Type Safety**: Generic nullable type support with proper TypeScript inference
+ * - **Validation**: Min/max properties, additional properties, and enum constraints
+ * - **JSON Schema**: Convert to standard JSON Schema format for validation
+ * - **Immutability**: All mutations return new instances (functional style)
+ *
+ * @template Nullable - Whether the object value itself can be null
+ *
+ * @example Basic object schema
+ * ```typescript
+ * import { OasObject } from '@skmtc/core';
+ *
+ * const userObject = new OasObject({
+ *   title: 'User',
+ *   description: 'A user in the system',
+ *   properties: {
+ *     id: new OasString({ title: 'User ID' }),
+ *     name: new OasString({ title: 'Full Name' }),
+ *     email: new OasString({ format: 'email' })
+ *   },
+ *   required: ['id', 'name'],
+ *   additionalProperties: false
+ * });
+ * ```
  *
- * Objects have fixed, named fields. Records have any number of fields that do not have predefined names.
+ * @example Dynamic property management
+ * ```typescript
+ * // Start with empty object
+ * let schema = OasObject.empty();
+ *
+ * // Add properties dynamically
+ * schema = schema.addProperty({
+ *   name: 'id',
+ *   schema: new OasString(),
+ *   required: true
+ * });
+ *
+ * schema = schema.addProperty({
+ *   name: 'metadata',
+ *   schema: new OasObject({ additionalProperties: true }),
+ *   required: false
+ * });
+ *
+ * // Remove a property
+ * schema = schema.removeProperty('metadata');
+ * ```
+ *
+ * @example Record-style object (additional properties)
+ * ```typescript
+ * const recordObject = new OasObject({
+ *   title: 'StringMap',
+ *   description: 'A map of string keys to string values',
+ *   additionalProperties: new OasString(), // Any string key -> string value
+ *   minProperties: 1 // At least one property required
+ * });
+ *
+ * // This allows: { [key: string]: string }
+ * ```
+ *
+ * @example Nullable object support
+ * ```typescript
+ * const nullableUser = new OasObject<true>({
+ *   nullable: true,
+ *   properties: {
+ *     name: new OasString()
+ *   },
+ *   default: null // Can have null default when nullable
+ * });
+ *
+ * // This represents: { name: string } | null
+ * ```
  */
 export declare class OasObject<Nullable extends boolean | undefined = boolean | undefined> {
     /**
@@ -82,29 +188,168 @@ export declare class OasObject<Nullable extends boolean | undefined = boolean |
     writeOnly?: boolean;
     deprecated?: boolean;
     enums?: Nullable extends true ? (Record<string, unknown> | null)[] | undefined : Record<string, unknown>[] | undefined;
+    /**
+     * Creates a new OasObject instance.
+     *
+     * @param fields - Object configuration fields
+     *
+     * @example
+     * ```typescript
+     * const userSchema = new OasObject({
+     *   title: 'User',
+     *   properties: {
+     *     id: new OasString({ title: 'ID' }),
+     *     name: new OasString({ title: 'Name' })
+     *   },
+     *   required: ['id'],
+     *   additionalProperties: false
+     * });
+     * ```
+     */
     constructor(fields?: OasObjectFields<Nullable>);
-    /** Creates new empty OasObject */
+    /**
+     * Creates a new empty OasObject with no properties.
+     *
+     * This factory method creates a non-nullable object with empty properties
+     * and required arrays, useful as a starting point for dynamic object building.
+     *
+     * @returns A new empty OasObject instance
+     *
+     * @example
+     * ```typescript
+     * // Start with empty object and build up
+     * let schema = OasObject.empty();
+     *
+     * schema = schema.addProperty({
+     *   name: 'id',
+     *   schema: new OasString(),
+     *   required: true
+     * });
+     *
+     * schema = schema.addProperty({
+     *   name: 'name',
+     *   schema: new OasString(),
+     *   required: true
+     * });
+     * ```
+     */
     static empty(): OasObject<false>;
     /**
      * Adds a new property to the object.
      *
-     * @param {AddPropertyArgs} args - The arguments for adding a property.
-     * @param {string} args.name - The name of the property to add.
-     * @param {OasSchema | OasRef<'schema'> | CustomValue | undefined} args.schema - The schema of the property to add.
-     * @param {boolean} args.required - Whether the property is required.
-     * @returns {OasObject} A new OasObject with the added property.
+     * This method returns a new OasObject instance with the added property,
+     * following an immutable pattern. If the property is marked as required,
+     * it will be added to the required array.
+     *
+     * @param args - Property addition arguments
+     * @param args.name - The name of the property to add
+     * @param args.schema - The schema definition for the property
+     * @param args.required - Whether the property should be required (default: false)
+     * @returns A new OasObject with the added property
+     *
+     * @example Adding a simple property
+     * ```typescript
+     * const original = OasObject.empty();
+     * const withName = original.addProperty({
+     *   name: 'username',
+     *   schema: new OasString({ minLength: 3 }),
+     *   required: true
+     * });
+     *
+     * console.log(withName.required); // ['username']
+     * ```
+     *
+     * @example Chaining property additions
+     * ```typescript
+     * const userSchema = OasObject.empty()
+     *   .addProperty({
+     *     name: 'id',
+     *     schema: new OasInteger(),
+     *     required: true
+     *   })
+     *   .addProperty({
+     *     name: 'email',
+     *     schema: new OasString({ format: 'email' }),
+     *     required: true
+     *   })
+     *   .addProperty({
+     *     name: 'age',
+     *     schema: new OasInteger({ minimum: 0 }),
+     *     required: false
+     *   });
+     * ```
      */
     addProperty({ name, schema, required }: AddPropertyArgs): OasObject;
     /**
      * Removes a property from the object.
      *
-     * @param {string} name - The name of the property to remove.
-     * @returns {OasObject} A new OasObject with the removed property.
+     * This method returns a new OasObject instance with the specified property
+     * removed. If the property was required, it will also be removed from the
+     * required array. If the property doesn't exist, returns the same instance.
+     *
+     * @param name - The name of the property to remove
+     * @returns A new OasObject with the property removed, or the same instance if property doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const userSchema = new OasObject({
+     *   properties: {
+     *     id: new OasString(),
+     *     name: new OasString(),
+     *     email: new OasString(),
+     *     temporaryField: new OasString()
+     *   },
+     *   required: ['id', 'name', 'temporaryField']
+     * });
+     *
+     * // Remove temporary field
+     * const cleanedSchema = userSchema.removeProperty('temporaryField');
+     *
+     * console.log(cleanedSchema.required); // ['id', 'name']
+     * console.log('temporaryField' in cleanedSchema.properties); // false
+     * ```
      */
     removeProperty(name: string): OasObject;
     isRef(): this is OasRef<'schema'>;
     resolve(): OasObject;
     resolveOnce(): OasObject;
+    /**
+     * Converts the OasObject to a standard JSON Schema object.
+     *
+     * This method serializes the object to the JSON Schema format used in
+     * OpenAPI specifications. It handles property conversion, additional
+     * properties rules, and validation constraints.
+     *
+     * @param options - Conversion options for handling references and context
+     * @returns A JSON Schema representation of the object
+     *
+     * @example
+     * ```typescript
+     * const userObject = new OasObject({
+     *   title: 'User',
+     *   properties: {
+     *     id: new OasString(),
+     *     name: new OasString()
+     *   },
+     *   required: ['id'],
+     *   additionalProperties: false
+     * });
+     *
+     * const jsonSchema = userObject.toJsonSchema({ refContext: new Map() });
+     *
+     * console.log(jsonSchema);
+     * // {
+     * //   type: 'object',
+     * //   title: 'User',
+     * //   properties: {
+     * //     id: { type: 'string' },
+     * //     name: { type: 'string' }
+     * //   },
+     * //   required: ['id'],
+     * //   additionalProperties: false
+     * // }
+     * ```
+     */
     toJsonSchema(options: ToJsonSchemaOptions): OpenAPIV3.NonArraySchemaObject;
 }
 //# sourceMappingURL=Object.d.ts.map