@tsed/schema 8.19.2 → 8.19.4

package/lib/esm/domain/JsonSchema.js

@@ -13,6 +13,57 @@ import { JsonEntityStore } from "./JsonEntityStore.js";
 function isEnum(type) {
     return isObject(type) && !("toJSON" in 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 class JsonSchema extends Map {
     /**
      * All required fields are stored here
@@ -66,40 +117,77 @@ export class JsonSchema extends Map {
             this.assign(obj);
         }
     }
+    /**
+     * 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() {
         return this.#alias;
     }
+    /**
+     * 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() {
         return isClass(this.class) && !this.isCollection;
     }
     /**
-     * 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() {
         return this.#isCollection;
     }
     /**
-     * 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() {
         return this.#isLocalSchema;
     }
     /**
-     * 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() {
         return this.has(VendorKeys.GENERIC_LABEL);
     }
+    /**
+     * 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() {
         const ancestors = ancestorsOf(this.#target);
         const ancestor = ancestors.find((ancestor) => JsonEntityStore.from(ancestor).schema.isDiscriminator);
         return ancestor && JsonEntityStore.from(ancestor).schema;
     }
     /**
-     * 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() {
         if (this.#isLocalSchema) {
@@ -108,26 +196,94 @@ export class JsonSchema extends Map {
         return getComputedType(this.#target);
     }
     /**
-     * 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() {
         return this.isCollection && this.#itemSchema ? this.#itemSchema.class : this.class;
     }
+    /**
+     * 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() {
         return this.#useRefLabel;
     }
+    /**
+     * Check if this schema allows null values.
+     *
+     * @returns `true` if the schema is nullable, `false` otherwise
+     */
     get isNullable() {
         return !!this.get(VendorKeys.NULLABLE);
     }
+    /**
+     * 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() {
         return this.get("readOnly");
     }
+    /**
+     * 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() {
         return this.get("writeOnly");
     }
+    /**
+     * 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() {
         return !!this.#discriminator;
     }
+    /**
+     * 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) {
         if (item instanceof JsonSchema) {
             return item;
@@ -141,8 +297,15 @@ export class JsonSchema extends Map {
         return new JsonSchema(item);
     }
     /**
-     * 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) {
         if (super.has(key)) {
@@ -165,10 +328,35 @@ export class JsonSchema extends Map {
         }
         return defaultValue;
     }
+    /**
+     * 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 = true) {
         this.vendorKey(VendorKeys.FORWARD_GROUPS, bool);
         return 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, isProperty) {
         if (groups) {
             this.vendorKey(VendorKeys.GROUPS, groups);
@@ -186,29 +374,75 @@ export class JsonSchema extends Map {
         }
         return 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) {
         groupsName && this.vendorKey(VendorKeys.GROUPS_NAME, groupsName);
         return 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) {
         groups && this.vendorKey(VendorKeys.ALLOWED_GROUPS, groups);
         return 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) {
         this.vendorKey(VendorKeys.GENERIC_LABELS, genericLabels);
         return 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) {
         this.vendorKey(VendorKeys.GENERIC_LABEL, genericLabel);
         return 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) {
         const mapped = this.mapGenerics(this.#itemSchema || this.mapToJsonSchema(this.getTarget()), generics);
@@ -221,6 +455,27 @@ export class JsonSchema extends Map {
         }
         return this;
     }
+    /**
+     * 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 = {}) {
         this.#itemSchema = this.#itemSchema || this.mapToJsonSchema(obj);
         if (isPlainObject(obj)) {
@@ -231,45 +486,139 @@ export class JsonSchema extends Map {
         }
         return this.#itemSchema;
     }
+    /**
+     * 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) {
         return this.#alias.get(property);
     }
+    /**
+     * 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, alias) {
         this.#alias.set(property, alias);
         this.#alias.set(alias, property);
         return 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) {
         const alias = this.#alias.get(property);
         alias && this.#alias.delete(alias);
         this.#alias.delete(property);
         return 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) {
         super.set("$id", $id);
         return 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) {
         super.set("$ref", $ref);
         return this;
     }
+    /**
+     * Set the JSON Schema version.
+     *
+     * @param $schema - The JSON Schema version URI
+     * @returns This schema instance for method chaining
+     */
     $schema($schema) {
         super.set("$schema", $schema);
         return 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) {
         this.#useRefLabel = true;
         super.set("name", name);
         return 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) {
         super.set("name", name);
         return 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) {
         if (typeof cb !== "boolean") {
             this.$hooks.on("ignore", cb);

package/lib/esm/domain/SpecTypes.js

@@ -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 var SpecTypes;
 (function (SpecTypes) {
     SpecTypes["JSON"] = "jsonschema";

package/lib/esm/fn/boolean.js

@@ -1,10 +1,46 @@
 import { from } from "./from.js";
 /**
- * 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 function boolean() {
     return from(Boolean);

package/lib/esm/fn/number.js

@@ -1,10 +1,52 @@
 import { from } from "./from.js";
 /**
- * Declare a new number model.
+ * Create a number schema programmatically.
  *
- * * See @@JsonSchema@@ to discover available methods.
+ * This function provides a fluent API for building number schemas without decorators.
+ * It returns a JsonSchema instance configured for number type, which can be further
+ * customized with validation constraints and other JSON Schema properties.
  *
- * @schemaFunctional
+ * ### Usage
+ *
+ * ```typescript
+ * import {number} from "@tsed/schema";
+ *
+ * // Basic number schema
+ * const ageSchema = number();
+ *
+ * // Number with range constraints
+ * const priceSchema = number()
+ *   .minimum(0)
+ *   .maximum(999999.99)
+ *   .description("Product price in USD");
+ *
+ * // Integer with exclusive bounds
+ * const scoreSchema = number()
+ *   .integer()
+ *   .exclusiveMinimum(0)
+ *   .exclusiveMaximum(100);
+ *
+ * // Multiple of constraint
+ * const quantitySchema = number()
+ *   .multipleOf(5)
+ *   .minimum(0)
+ *   .description("Quantity in packs of 5");
+ * ```
+ *
+ * ### Available Methods
+ *
+ * The returned JsonSchema provides many chainable methods:
+ * - `minimum(n)` / `maximum(n)` - Range constraints (inclusive)
+ * - `exclusiveMinimum(n)` / `exclusiveMaximum(n)` - Range constraints (exclusive)
+ * - `multipleOf(n)` - Value must be multiple of n
+ * - `integer()` - Restrict to integers only
+ * - `description(text)` - Add description
+ * - `default(value)` - Set default value
+ * - `nullable()` - Allow null values
+ *
+ * @returns A new JsonSchema configured as a number type
+ *
+ * @public
  */
 export function number() {
     return from(Number);