@tsed/schema 8.19.2 → 8.19.3

package/lib/types/domain/JsonSchema.d.ts

@@ -10,15 +10,86 @@ import { Discriminator } from "./JsonDiscriminator.js";
 import { JsonFormatTypes } from "./JsonFormatTypes.js";
 import { JsonLazyRef } from "./JsonLazyRef.js";
 import type { Infer, PropsToShape, UnionToIntersection } from "./types.js";
+/**
+ * Extended JSON Schema object supporting TypeScript types and Ts.ED enhancements.
+ *
+ * This interface extends the standard JSON Schema 7 specification with additional
+ * type flexibility, allowing TypeScript classes and types to be used directly
+ * in schema definitions.
+ *
+ * @public
+ */
 export interface JsonSchemaObject extends Omit<JSONSchema7, "type" | "additionalProperties" | "items" | "pattern"> {
     type?: JSONSchema7["type"] | Type | null | (String | null | Date | Number | Object | Boolean)[];
     additionalProperties?: JsonSchemaObject | boolean | Type | JsonSchema;
     items?: JsonSchemaObject | boolean | Type | JsonSchema | (JsonSchemaObject | Type | JsonSchema)[];
     pattern?: string | RegExp;
 }
+/**
+ * Union type representing any valid JSON schema representation.
+ *
+ * This type accepts various schema formats including standard JSON Schema objects,
+ * Ts.ED JsonSchema instances, lazy references, TypeScript classes, and label objects.
+ * It provides maximum flexibility for schema definition across the framework.
+ *
+ * @typeParam T - The TypeScript type this schema represents
+ *
+ * @public
+ */
 export type AnyJsonSchema<T = any> = JsonSchemaObject | JSONSchema7 | JsonSchema<T> | JsonLazyRef | {
     label?: string;
 } | Type;
+/**
+ * Core class representing a JSON Schema with TypeScript type integration.
+ *
+ * JsonSchema is the central class in Ts.ED's schema system, providing a Map-based
+ * interface for building and manipulating JSON Schema definitions. It extends the
+ * standard JSON Schema 7 specification with Ts.ED-specific features including:
+ *
+ * - TypeScript class and type integration
+ * - Property aliasing and naming strategies
+ * - Group-based conditional schemas
+ * - Discriminator support for polymorphic types
+ * - Generic type parameter handling
+ * - Schema composition (oneOf, allOf, anyOf)
+ * - Hook-based transformation pipeline
+ * - Vendor extension support
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * // Create a basic schema
+ * const schema = new JsonSchema({
+ *   type: "string",
+ *   minLength: 1,
+ *   maxLength: 100
+ * });
+ *
+ * // Create schema from TypeScript class
+ * class User {
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const userSchema = JsonSchema.from(User);
+ *
+ * // Generate JSON Schema output
+ * const jsonSchema = userSchema.toJSON();
+ * ```
+ *
+ * ### Key Features
+ *
+ * - **Type Safety**: Generic type parameter `T` represents the TypeScript type
+ * - **Composition**: Support for allOf, oneOf, anyOf schema composition
+ * - **Validation**: Full JSON Schema validation keyword support
+ * - **Transformation**: Hook system for custom schema transformations
+ * - **Groups**: Conditional property inclusion based on groups
+ * - **Generics**: Support for generic type parameters in classes
+ *
+ * @typeParam T - The TypeScript type this schema represents
+ *
+ * @public
+ */
 export declare class JsonSchema<T = JSONSchema7Type> extends Map<string, any> {
     #private;
     readonly $kind: string;
@@ -30,81 +101,413 @@ export declare class JsonSchema<T = JSONSchema7Type> extends Map<string, any> {
     isDiscriminatorKey: boolean;
     isDiscriminator: boolean;
     constructor(obj?: Partial<JSONSchema7> | JsonSchema | Record<string, unknown>);
+    /**
+     * Get the alias map for property name aliases.
+     *
+     * The alias map allows bidirectional property name mapping, useful for
+     * serialization/deserialization with different naming conventions.
+     *
+     * @returns The alias map containing property-to-alias and alias-to-property mappings
+     */
     get alias(): AliasMap;
+    /**
+     * Check if this schema represents a TypeScript class (not a primitive or collection).
+     *
+     * @returns `true` if the schema represents a class, `false` otherwise
+     */
     get isClass(): boolean;
     /**
-     * The current schema is a collection
+     * Check if this schema represents a collection (array, Set, Map, etc.).
+     *
+     * Collections have an associated item schema that defines the type of elements
+     * they contain.
+     *
+     * @returns `true` if the schema is a collection, `false` otherwise
      */
     get isCollection(): boolean;
     /**
-     * The current schema is a reference to another schema
-     * to link property/param to a class schema (if the reference exists).
+     * Check if this is a local schema reference.
+     *
+     * A local schema acts as a reference to link a property or parameter to a class schema.
+     * This is used for type resolution and avoids schema duplication.
+     *
+     * @returns `true` if this is a local schema reference, `false` otherwise
      */
     get isLocalSchema(): boolean;
     /**
-     * Current schema is a generic
+     * Check if this schema represents a generic type.
+     *
+     * Generic schemas have a generic label vendor key and are used for parameterized types.
+     *
+     * @returns `true` if the schema is a generic type, `false` otherwise
      */
     get isGeneric(): boolean;
+    /**
+     * Get the ancestor schema that defines a discriminator.
+     *
+     * Searches through the class hierarchy to find a parent class with a discriminator
+     * configuration. This is used for polymorphic type resolution.
+     *
+     * @returns The ancestor schema with discriminator, or undefined if none found
+     */
     get discriminatorAncestor(): any;
     /**
-     * Return the itemSchema computed type.
-     * If the type is a function used for a recursive model,
-     * the function will be called to get the right type.
+     * Get the computed TypeScript class or type for this schema.
+     *
+     * For local schemas, returns the item schema's target.
+     * For recursive models using functions, resolves the function to get the actual type.
+     *
+     * @returns The TypeScript class or type this schema represents
      */
     get class(): Type<any>;
     /**
-     * Return the itemSchema computed type.
+     * Get the TypeScript class for collection items.
+     *
+     * For collection schemas, returns the type of elements in the collection.
+     * For non-collection schemas, returns the schema's own class.
+     *
+     * @returns The item class for collections, or the schema's class otherwise
      */
     get collectionClass(): Type<any>;
+    /**
+     * Check if this schema can use a $ref reference.
+     *
+     * Schemas with labels can be referenced by $ref to avoid duplication
+     * in generated OpenAPI specifications.
+     *
+     * @returns `true` if the schema can be referenced via $ref, `false` otherwise
+     */
     get canRef(): boolean;
+    /**
+     * Check if this schema allows null values.
+     *
+     * @returns `true` if the schema is nullable, `false` otherwise
+     */
     get isNullable(): boolean;
+    /**
+     * Check if this property is read-only.
+     *
+     * Read-only properties are included in responses but not accepted in requests.
+     *
+     * @returns `true` if the property is read-only, `false` otherwise
+     */
     get isReadOnly(): any;
+    /**
+     * Check if this property is write-only.
+     *
+     * Write-only properties are accepted in requests but not included in responses.
+     * Useful for sensitive data like passwords.
+     *
+     * @returns `true` if the property is write-only, `false` otherwise
+     */
     get isWriteOnly(): any;
+    /**
+     * Check if this schema has a discriminator configuration.
+     *
+     * Discriminators enable polymorphic type resolution based on a property value.
+     *
+     * @returns `true` if a discriminator is configured, `false` otherwise
+     */
     get hasDiscriminator(): boolean;
+    /**
+     * Create a JsonSchema from various input types.
+     *
+     * This factory method intelligently converts different input types into JsonSchema instances:
+     * - Existing JsonSchema: returned as-is
+     * - TypeScript classes: retrieves the schema from JsonEntityStore
+     * - Primitive classes (String, Number, etc.) and Date: creates type schema
+     * - Plain objects: creates schema from JSON Schema definition
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * // From a class
+     * const schema1 = JsonSchema.from(User);
+     *
+     * // From a primitive
+     * const schema2 = JsonSchema.from(String);
+     *
+     * // From a schema object
+     * const schema3 = JsonSchema.from({type: "string", minLength: 1});
+     *
+     * // From existing schema (no-op)
+     * const schema4 = JsonSchema.from(schema1);
+     * ```
+     *
+     * @param item - The input to convert to a JsonSchema
+     * @returns A JsonSchema instance representing the input
+     */
     static from(item: Partial<JsonSchemaObject> | Type<any> | JsonSchema | undefined): JsonSchema<JSONSchema7Type>;
     /**
-     * Check if the schema as key, #key or x-key
-     * @param key
+     * Check if the schema has a property.
+     *
+     * Checks multiple locations in order:
+     * 1. Standard Map keys
+     * 2. Internal keys (prefixed with #)
+     * 3. Vendor extension keys
+     *
+     * @param key - The property key to check
+     * @returns `true` if the property exists, `false` otherwise
      */
     has(key: string): boolean;
     /**
-     * Get the value of the schema by key, #key or x-key.
-     * @param key
-     * @param defaultValue
+     * Get a property value from the schema.
+     *
+     * Retrieves values from multiple locations in order:
+     * 1. Vendor extension keys
+     * 2. Standard Map keys
+     * 3. Internal keys (prefixed with #)
+     * 4. Default value if not found
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * const minLength = schema.get("minLength", 0);
+     * const customKey = schema.get("x-custom");
+     * ```
+     *
+     * @param key - The property key to retrieve
+     * @param defaultValue - Optional default value if key not found
+     * @returns The property value or default value
      */
     get<T = any>(key: string, defaultValue: T): T;
     get<T = any>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Enable group forwarding to nested properties.
+     *
+     * When enabled, groups specified at the parent level are forwarded to nested
+     * object properties, allowing hierarchical group filtering.
+     *
+     * @param bool - Whether to enable group forwarding (default: true)
+     * @returns This schema instance for method chaining
+     */
     forwardGroups(bool?: boolean): this;
+    /**
+     * Assign groups to this property or schema.
+     *
+     * Groups enable conditional inclusion of properties based on serialization context.
+     * For example, you might have "admin" and "public" groups to control visibility.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * schema.groups(["admin", "internal"]);
+     * ```
+     *
+     * @param groups - Array of group names this property belongs to
+     * @param isProperty - Whether this is a property schema (enables group matching hooks)
+     * @returns This schema instance for method chaining
+     */
     groups(groups?: string[], isProperty?: boolean): this;
+    /**
+     * Set a custom name suffix for group-specific schema variations.
+     *
+     * This is used to generate unique schema names when the same model is used
+     * with different groups, avoiding conflicts in OpenAPI components.
+     *
+     * @param groupsName - The groups name suffix
+     * @returns This schema instance for method chaining
+     */
     groupsName(groupsName?: string): this;
+    /**
+     * Specify which groups are allowed access to this schema.
+     *
+     * @param groups - Array of group names allowed to access this schema
+     * @returns This schema instance for method chaining
+     */
     allowedGroups(groups?: string[]): this;
     /**
-     * Assign the Generic Labels used over a class or a schema.
-     * @param genericLabels
+     * Assign generic type parameter labels to a class or schema.
+     *
+     * Used for classes with generic type parameters (e.g., `Paginated<T>`)
+     * to track the parameter names for proper schema generation.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * schema.genericLabels(["T", "U"]);
+     * ```
+     *
+     * @param genericLabels - Array of generic type parameter names
+     * @returns This schema instance for method chaining
      */
     genericLabels(genericLabels: string[]): this;
+    /**
+     * Assign a single generic type label to this schema.
+     *
+     * Marks this schema as representing a generic type parameter.
+     *
+     * @param genericLabel - The generic type parameter name
+     * @returns This schema instance for method chaining
+     */
     genericLabel(genericLabel: string): this;
     /**
-     * Assign the types of the generics that must be used for the property
-     * @param generics
+     * Specify the concrete types for generic parameters.
+     *
+     * When using a generic class, this method assigns the actual types that should
+     * replace the generic parameters for this specific instance.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * // For Paginated<User>
+     * schema.genericOf([User]);
+     * ```
+     *
+     * @param generics - Arrays of generic type values to apply
+     * @returns This schema instance for method chaining
      */
     genericOf(...generics: GenericValue[][]): this;
+    /**
+     * Mark this schema as nullable or non-nullable.
+     *
+     * Nullable schemas can accept `null` values in addition to their base type.
+     * The type parameter is updated to reflect the nullability.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * // Make nullable
+     * schema.nullable(); // or schema.nullable(true)
+     *
+     * // Make non-nullable
+     * schema.nullable(false);
+     * ```
+     *
+     * @param value - Whether the schema is nullable (default: true)
+     * @returns This schema instance with updated type
+     */
     nullable(): JsonSchema<T | null>;
     nullable(value: true): JsonSchema<T | null>;
     nullable(value: false): JsonSchema<Exclude<T, null>>;
+    /**
+     * Get or create the item schema for collections.
+     *
+     * For array/collection types, this defines the schema for individual items.
+     * If the schema already has an item schema, it returns the existing one;
+     * otherwise, it creates a new one from the provided definition.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * // Define array items
+     * const arraySchema = new JsonSchema({type: "array"});
+     * arraySchema.itemSchema({type: "string", minLength: 1});
+     *
+     * // For class-based items
+     * arraySchema.itemSchema(User);
+     * ```
+     *
+     * @param obj - Schema definition for items
+     * @returns The item schema instance
+     */
     itemSchema(obj?: AnyJsonSchema): JsonSchema<JSONSchema7Type>;
+    /**
+     * Get the alias for a property name.
+     *
+     * @param property - The property name to look up
+     * @returns The alias for the property, or undefined if none exists
+     */
     getAliasOf(property: AliasType): AliasType | undefined;
+    /**
+     * Add a bidirectional alias mapping between property names.
+     *
+     * Aliases allow properties to be accessed by alternative names, useful for
+     * supporting different naming conventions (camelCase vs snake_case, etc.).
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * schema.addAlias("userId", "user_id");
+     * // Both "userId" and "user_id" now map to each other
+     * ```
+     *
+     * @param property - The original property name
+     * @param alias - The alias name
+     * @returns This schema instance for method chaining
+     */
     addAlias(property: AliasType, alias: AliasType): this;
+    /**
+     * Remove an alias mapping for a property.
+     *
+     * @param property - The property name to remove aliases for
+     * @returns This schema instance for method chaining
+     */
     removeAlias(property: AliasType): this;
+    /**
+     * Set the `$id` keyword for this schema.
+     *
+     * The `$id` keyword is used to identify the schema and establish a base URI
+     * for resolving relative references.
+     *
+     * @param $id - The schema identifier URI
+     * @returns This schema instance for method chaining
+     */
     $id($id: string): this;
+    /**
+     * Set a `$ref` reference to another schema.
+     *
+     * The `$ref` keyword creates a reference to a schema defined elsewhere,
+     * enabling schema reuse and avoiding duplication.
+     *
+     * @param $ref - The reference URI (e.g., "#/components/schemas/User")
+     * @returns This schema instance for method chaining
+     */
     $ref($ref: string): this;
+    /**
+     * Set the JSON Schema version.
+     *
+     * @param $schema - The JSON Schema version URI
+     * @returns This schema instance for method chaining
+     */
     $schema($schema: JSONSchema7Version): this;
     /**
-     * Create a ref and use name to sharing schema
-     * @param name
+     * Assign a label to enable schema referencing.
+     *
+     * Labeled schemas can be referenced using `$ref` in OpenAPI specifications,
+     * reducing duplication by sharing schema definitions across endpoints.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * schema.label("User");
+     * // Can now be referenced as #/components/schemas/User
+     * ```
+     *
+     * @param name - The label name for the schema
+     * @returns This schema instance for method chaining
      */
     label(name: string): this;
+    /**
+     * Set the name of this schema.
+     *
+     * Unlike `label()`, this sets the name without enabling referencing.
+     *
+     * @param name - The schema name
+     * @returns This schema instance for method chaining
+     */
     name(name: string): this;
+    /**
+     * Mark this property as ignored during serialization.
+     *
+     * Ignored properties are excluded from generated schemas and serialization.
+     * Can be a boolean or a callback function for conditional ignoring.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * // Always ignore
+     * schema.ignore(true);
+     *
+     * // Conditionally ignore based on context
+     * schema.ignore((value, ctx) => {
+     *   return ctx.groups?.includes("public");
+     * });
+     * ```
+     *
+     * @param cb - Boolean flag or callback function to determine if property should be ignored
+     * @returns This schema instance for method chaining
+     */
     ignore(cb: boolean | IgnoreCallback): this;
     /**
      * This keyword can be used to supply a default JSON value associated with a particular schema.

package/lib/types/domain/SpecTypes.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Specification types supported by Ts.ED's schema system.
+ *
+ * This enum defines the different API specification formats that can be generated
+ * from Ts.ED schemas. Each type affects how schemas are serialized and which
+ * features are available.
+ *
+ * ### Specification Types
+ *
+ * - **JSON**: Pure JSON Schema (no OpenAPI-specific features)
+ * - **SWAGGER**: Swagger 2.0 / OpenAPI 2.0 specification
+ * - **OPENAPI**: OpenAPI 3.x specification (recommended)
+ * - **ASYNCAPI**: AsyncAPI 2.x specification (for async/event-driven APIs)
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {SpecTypes} from "@tsed/schema";
+ *
+ * const schema = getJsonSchema(MyModel, {
+ *   specType: SpecTypes.OPENAPI
+ * });
+ * ```
+ *
+ * @public
+ */
 export declare enum SpecTypes {
     JSON = "jsonschema",
     SWAGGER = "swagger2",

package/lib/types/domain/types.d.ts

@@ -1,7 +1,97 @@
 import type { JsonSchema } from "./JsonSchema.js";
+/**
+ * Extracts the inferred TypeScript type from a JsonSchema.
+ *
+ * This utility type enables type-safe schema usage by extracting the type parameter
+ * from JsonSchema instances.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const userSchema = JsonSchema.from({ type: "object" });
+ * type User = Infer<typeof userSchema>; // Extracts the type
+ * ```
+ *
+ * @typeParam S - The JsonSchema to extract the type from
+ *
+ * @public
+ */
 export type Infer<S> = S extends JsonSchema<infer T> ? T : never;
+/**
+ * Maps an object of JsonSchema properties to a concrete TypeScript type.
+ *
+ * Converts a record of JsonSchema properties into a TypeScript type where each
+ * property has the inferred type from its corresponding schema.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const properties = {
+ *   name: string(),
+ *   age: number(),
+ *   email: string().format("email")
+ * };
+ *
+ * type Shape = PropsToShape<typeof properties>;
+ * // Result: { name: string; age: number; email: string }
+ * ```
+ *
+ * @typeParam P - Record of property names to JsonSchema instances
+ *
+ * @public
+ */
 export type PropsToShape<P extends Record<string, JsonSchema<any>>> = {
     [K in keyof P]: Infer<P[K]>;
 };
+/**
+ * Maps common JavaScript constructors to their corresponding TypeScript types.
+ *
+ * This utility type converts constructor functions (String, Number, Date, etc.) into
+ * their corresponding runtime types, enabling better type inference when creating
+ * schemas programmatically.
+ *
+ * ### Type Mappings
+ *
+ * - `StringConstructor` → `string`
+ * - `NumberConstructor` → `number`
+ * - `BooleanConstructor` → `boolean`
+ * - `DateConstructor` → `Date`
+ * - `ArrayConstructor` → `any[]`
+ * - `MapConstructor` → `Record<string, any>`
+ * - `SetConstructor` → `Set<any>`
+ * - `ObjectConstructor` → `Record<string, any>`
+ * - Custom classes → `InstanceType<C>`
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * type StringType = CtorToType<StringConstructor>;  // string
+ * type DateType = CtorToType<DateConstructor>;      // Date
+ * type CustomType = CtorToType<typeof MyClass>;     // MyClass
+ * ```
+ *
+ * @typeParam C - The constructor function to map
+ *
+ * @public
+ */
 export type CtorToType<C> = C extends StringConstructor ? string : C extends NumberConstructor ? number : C extends BooleanConstructor ? boolean : C extends DateConstructor ? Date : C extends ArrayConstructor ? any[] : C extends MapConstructor ? Record<string, any> : C extends SetConstructor ? Set<any> : C extends ObjectConstructor ? Record<string, any> : C extends abstract new (...args: any) => any ? InstanceType<C> : any;
+/**
+ * Converts a union type to an intersection type.
+ *
+ * This advanced TypeScript utility transforms a union of types (A | B | C) into
+ * an intersection of types (A & B & C), which is useful for schema composition
+ * and merging operations.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * type Union = { a: string } | { b: number };
+ * type Intersection = UnionToIntersection<Union>;
+ * // Result: { a: string } & { b: number }
+ * ```
+ *
+ * @typeParam U - The union type to convert
+ *
+ * @public
+ */
 export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;

package/lib/types/fn/boolean.d.ts

@@ -1,8 +1,44 @@
 /**
- * Declare a new boolean model.
+ * Create a boolean schema programmatically.
  *
- * See @@JsonSchema@@ to discover available methods.
+ * This function provides a fluent API for building boolean schemas without decorators.
+ * It returns a JsonSchema instance configured for boolean type, which can be further
+ * customized with descriptions, defaults, and other JSON Schema properties.
  *
- * @schemaFunctional
+ * ### Usage
+ *
+ * ```typescript
+ * import {boolean} from "@tsed/schema";
+ *
+ * // Basic boolean schema
+ * const activeSchema = boolean();
+ *
+ * // Boolean with description and default
+ * const isVerifiedSchema = boolean()
+ *   .description("Whether the user is verified")
+ *   .default(false);
+ *
+ * // Required boolean
+ * const termsAcceptedSchema = boolean()
+ *   .description("User accepted terms and conditions")
+ *   .required();
+ *
+ * // Nullable boolean
+ * const optionalFlagSchema = boolean()
+ *   .nullable()
+ *   .description("Optional feature flag");
+ * ```
+ *
+ * ### Available Methods
+ *
+ * The returned JsonSchema provides many chainable methods:
+ * - `description(text)` - Add description
+ * - `default(value)` - Set default value (true or false)
+ * - `nullable()` - Allow null values
+ * - `const(value)` - Restrict to a single value
+ *
+ * @returns A new JsonSchema configured as a boolean type
+ *
+ * @public
  */
 export declare function boolean(): import("../index.js").JsonSchema<boolean>;