@tsed/schema 8.19.2 → 8.19.3

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

@@ -1,8 +1,50 @@
 /**
- * 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 declare function number(): import("../index.js").JsonSchema<number>;

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

@@ -1,8 +1,48 @@
 /**
- * Declare a new string model.
+ * Create a string schema programmatically.
  *
- * See @@JsonSchema@@ to discover available methods.
+ * This function provides a fluent API for building string schemas without decorators.
+ * It returns a JsonSchema instance configured for string type, which can be further
+ * customized with validation constraints, formats, and other JSON Schema properties.
  *
- * @schemaFunctional
+ * ### Usage
+ *
+ * ```typescript
+ * import {string} from "@tsed/schema";
+ *
+ * // Basic string schema
+ * const nameSchema = string();
+ *
+ * // String with constraints
+ * const emailSchema = string()
+ *   .format("email")
+ *   .minLength(5)
+ *   .maxLength(100)
+ *   .description("User email address");
+ *
+ * // String with pattern
+ * const phoneSchema = string()
+ *   .pattern(/^\d{3}-\d{3}-\d{4}$/)
+ *   .description("Phone number in format: 123-456-7890");
+ *
+ * // Enum string
+ * const statusSchema = string()
+ *   .enum("active", "inactive", "pending");
+ * ```
+ *
+ * ### Available Methods
+ *
+ * The returned JsonSchema provides many chainable methods:
+ * - `minLength(n)` / `maxLength(n)` - Length constraints
+ * - `pattern(regex)` - Pattern matching
+ * - `format(type)` - Format validation (email, uri, date-time, etc.)
+ * - `enum(...values)` - Restrict to specific values
+ * - `description(text)` - Add description
+ * - `default(value)` - Set default value
+ * - `nullable()` - Allow null values
+ *
+ * @returns A new JsonSchema configured as a string type
+ *
+ * @public
  */
 export declare function string(): import("../index.js").JsonSchema<string>;

package/lib/types/interfaces/IgnoreCallback.d.ts

@@ -1,4 +1,28 @@
 import { JsonHookContext } from "./JsonHookContext.js";
+/**
+ * Callback function to determine whether a property should be ignored during serialization.
+ *
+ * This callback is invoked during schema generation to conditionally ignore properties
+ * based on the current context and the default ignore value.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const ignoreCallback: IgnoreCallback = (value, ctx) => {
+ *   // Ignore properties when specific groups are active
+ *   if (ctx.groups?.includes('admin')) {
+ *     return false; // Don't ignore for admin group
+ *   }
+ *   return value; // Use default ignore value
+ * };
+ * ```
+ *
+ * @param value - The default ignore value for the property
+ * @param ctx - The current JSON hook context containing serialization metadata
+ * @returns `true` to ignore the property, `false` to include it
+ *
+ * @public
+ */
 export interface IgnoreCallback {
     (value: boolean, ctx: JsonHookContext): boolean;
 }

package/lib/types/interfaces/JsonHookContext.d.ts

@@ -4,13 +4,44 @@ declare global {
         }
     }
 }
+/**
+ * Context object passed to JSON schema hooks during serialization and schema generation.
+ *
+ * This context provides information about the current serialization state, including
+ * the target instance, active groups, and extensible custom properties. It enables
+ * hooks to make context-aware decisions during schema generation and transformation.
+ *
+ * The interface is extensible via TypeScript module augmentation, allowing packages
+ * to add custom context properties through the `TsED.JsonHookContext` namespace.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {JsonHookContext} from "@tsed/schema";
+ *
+ * function myHook(value: any, ctx: JsonHookContext) {
+ *   // Access the target instance
+ *   console.log(ctx.self);
+ *
+ *   // Check active groups
+ *   if (ctx.groups?.includes('admin')) {
+ *     // Apply admin-specific transformations
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface JsonHookContext extends TsED.JsonHookContext {
     /**
      * The current instance used by serializer function
      */
     self: any;
     /**
+     * Active groups for conditional schema generation.
      *
+     * When set to an array, only properties belonging to these groups will be included.
+     * When set to `false`, group filtering is disabled.
      */
     groups?: string[] | false;
     [key: string]: any;

package/lib/types/interfaces/JsonOpenSpec.d.ts

@@ -1,6 +1,39 @@
 import { OS3Header } from "@tsed/openspec";
+/**
+ * Represents an HTTP header in JSON schema format, compatible with OpenAPI Specification 3.
+ *
+ * This interface extends the OpenAPI 3 header specification, allowing full compatibility
+ * with OpenAPI header definitions while providing JSON schema integration.
+ *
+ * @public
+ */
 export interface JsonHeader extends OS3Header {
 }
+/**
+ * Collection of HTTP headers for OpenAPI operations.
+ *
+ * Headers can be defined as simple values (number or string) or as detailed header
+ * objects with schema information. This flexible structure supports both quick
+ * header definitions and comprehensive OpenAPI header specifications.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const headers: JsonHeaders = {
+ *   // Simple header value
+ *   "X-Rate-Limit": 100,
+ *
+ *   // Detailed header with schema
+ *   "X-Request-ID": {
+ *     description: "Unique request identifier",
+ *     type: "string",
+ *     value: "abc-123"
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
 export interface JsonHeaders {
     [key: string]: number | string | (JsonHeader & {
         type?: string;

package/lib/types/interfaces/JsonSchemaOptions.d.ts

@@ -1,5 +1,31 @@
 import { SpecTypes } from "../domain/SpecTypes.js";
 import type { GenericsMap } from "../utils/generics.js";
+/**
+ * Configuration options for JSON schema generation.
+ *
+ * These options control how JSON schemas are generated from TypeScript classes,
+ * including alias mapping, component references, spec type selection, group filtering,
+ * and custom key generation. The options affect both JSON Schema and OpenAPI
+ * specification generation.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {getJsonSchema, JsonSchemaOptions} from "@tsed/schema";
+ *
+ * const options: JsonSchemaOptions = {
+ *   specType: SpecTypes.OPENAPI,
+ *   specVersion: "3.0.3",
+ *   groups: ["public"],
+ *   useAlias: true,
+ *   customKeys: true
+ * };
+ *
+ * const schema = getJsonSchema(MyModel, options);
+ * ```
+ *
+ * @public
+ */
 export interface JsonSchemaOptions {
     /**
      * Map properties with the alias name. By default, false

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tsed/schema",
   "description": "JsonSchema module for Ts.ED Framework",
   "type": "module",
-  "version": "8.19.2",
+  "version": "8.19.3",
   "source": "./src/index.ts",
   "main": "./lib/esm/index.js",
   "module": "./lib/esm/index.js",
@@ -34,7 +34,7 @@
     "tsed"
   ],
   "dependencies": {
-    "@tsed/openspec": "8.19.2",
+    "@tsed/openspec": "8.19.3",
     "change-case": "^5.4.4",
     "json-schema": "0.4.0",
     "picomatch": "4.0.2",
@@ -43,11 +43,11 @@
   },
   "devDependencies": {
     "@apidevtools/swagger-parser": "10.1.0",
-    "@tsed/barrels": "8.19.2",
-    "@tsed/core": "8.19.2",
-    "@tsed/hooks": "8.19.2",
-    "@tsed/openspec": "8.19.2",
-    "@tsed/typescript": "8.19.2",
+    "@tsed/barrels": "8.19.3",
+    "@tsed/core": "8.19.3",
+    "@tsed/hooks": "8.19.3",
+    "@tsed/openspec": "8.19.3",
+    "@tsed/typescript": "8.19.3",
     "@types/fs-extra": "11.0.4",
     "@types/json-schema": "7.0.15",
     "@types/picomatch": "3.0.2",