@skmtc/core 0.0.785 → 0.0.787

package/script/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

package/script/oas/object/Object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../../src/oas/object/Object.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../../src/oas/object/Object.ts"],"names":[],"mappings":"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"}

package/script/oas/object/Object.js

@@ -4,11 +4,109 @@ exports.OasObject = void 0;
 require("../../_dnt.polyfills.js");
 const ts_pattern_1 = require("ts-pattern");
 /**
- * Object representing an object and/or a record in the OpenAPI Specification.
+ * Represents an object schema in the OpenAPI Specification.
  *
- * Objects have fixed, named fields. Records have any number of fields that do not have predefined names.
+ * `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
+ * });
+ * ```
+ *
+ * @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
+ * ```
  */
 class OasObject {
+    /**
+     * 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 = {}) {
         /**
          * Object is part the 'schema' set which is used
@@ -161,7 +259,32 @@ class OasObject {
         this.deprecated = fields.deprecated;
         this.enums = fields.enums;
     }
-    /** 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() {
         return new OasObject({
             nullable: false,
@@ -172,11 +295,47 @@ class OasObject {
     /**
      * 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 }) {
         if (!schema) {
@@ -198,8 +357,31 @@ class 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) {
         if (!this.properties?.[name]) {
@@ -225,6 +407,43 @@ class OasObject {
     resolveOnce() {
         return this;
     }
+    /**
+     * 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) {
         return {
             type: 'object',