@tsed/schema 8.27.0 → 8.28.1

package/lib/esm/decorators/common/customKey.js

@@ -4,7 +4,7 @@ import { JsonEntityFn } from "./jsonEntityFn.js";
  *
  * The `@CustomKey()` decorator allows adding vendor-specific extensions or custom metadata
  * to schemas. These custom keys are only included in the generated schema when explicitly
- * requested with the `customKeys: true` option in `getJsonSchema()`.
+ * requested with the `customKeys: true` option in `compile()`.
  *
  * ### Basic Usage
  *
@@ -56,12 +56,12 @@ import { JsonEntityFn } from "./jsonEntityFn.js";
  * Custom keys must be explicitly requested:
  *
  * ```typescript
- * import { getJsonSchema } from "@tsed/schema";
+ * import { compile } from "@tsed/schema";
  *
- * const schema = getJsonSchema(UserModel, { customKeys: true });
+ * const schema = compile(UserModel, { customKeys: true });
  * // Schema will include x-internal-id and other custom keys
  *
- * const standardSchema = getJsonSchema(UserModel);
+ * const standardSchema = compile(UserModel);
  * // Custom keys are omitted by default
  * ```
  *

package/lib/esm/decorators/common/ref.js

@@ -0,0 +1,15 @@
+import { JsonEntityFn } from "./jsonEntityFn.js";
+/**
+ * Set a `$ref` value on the current schema property/parameter.
+ *
+ * Supports local references (`#/...`) and external URLs.
+ *
+ * @param ref - Reference URI
+ * @decorator
+ */
+export function Ref(ref) {
+    return JsonEntityFn((entity) => {
+        entity.itemSchema.delete("type");
+        entity.itemSchema.$ref(ref);
+    });
+}

package/lib/esm/decorators/generics/generics.js

@@ -1,6 +1,6 @@
 import { JsonEntityStore } from "../../domain/JsonEntityStore.js";
 /**
- * Define generics list. This list is used by @@GenericOf@@ and the @@getJsonSchema@@ function to build the correct JsonSchema.
+ * Define generics list. This list is used by @@GenericOf@@ and the @@compile@@ function to build the correct JsonSchema.
  *
  * See @@GenericOf@@ decorator for more details.
  *

package/lib/esm/domain/SpecTypes.js

@@ -17,7 +17,7 @@
  * ```typescript
  * import {SpecTypes} from "@tsed/schema";
  *
- * const schema = getJsonSchema(MyModel, {
+ * const schema = compile(MyModel, {
  *   specType: SpecTypes.OPENAPI
  * });
  * ```

package/lib/esm/fn/index.js

@@ -12,6 +12,7 @@ import { lazyRef } from "./lazyRef.js";
 import { number } from "./number.js";
 import { object } from "./object.js";
 import { oneOf } from "./oneOf.js";
+import { ref } from "./ref.js";
 import { string } from "./string.js";
 import { uri } from "./uri.js";
 import { url } from "./url.js";
@@ -39,6 +40,7 @@ export const s = {
     lazyRef,
     object,
     oneOf,
+    $ref: ref,
     string,
     uri,
     url

package/lib/esm/fn/ref.js

@@ -0,0 +1,17 @@
+import { JsonSchema } from "../domain/JsonSchema.js";
+/**
+ * Create a schema reference from an external or internal `$ref` URI.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * const UserRef = ref("https://api.example.com/doc/swagger.json#/components/schemas/User");
+ * ```
+ *
+ * @param path - The reference URI
+ * @returns A JsonSchema containing the `$ref`
+ * @schemaFunctional
+ */
+export function ref(path) {
+    return new JsonSchema().$ref(path);
+}

package/lib/esm/index.js

@@ -80,6 +80,7 @@ export * from "./decorators/common/pattern.js";
 export * from "./decorators/common/property.js";
 export * from "./decorators/common/readOnly.js";
 export * from "./decorators/common/recordOf.js";
+export * from "./decorators/common/ref.js";
 export * from "./decorators/common/required.js";
 export * from "./decorators/common/requiredGroups.js";
 export * from "./decorators/common/schema.js";
@@ -150,6 +151,7 @@ export * from "./fn/lazyRef.js";
 export * from "./fn/number.js";
 export * from "./fn/object.js";
 export * from "./fn/oneOf.js";
+export * from "./fn/ref.js";
 export * from "./fn/string.js";
 export * from "./fn/uri.js";
 export * from "./fn/url.js";
@@ -163,6 +165,7 @@ export * from "./interfaces/JsonSchemaOptions.js";
 export * from "./registries/enumRegistries.js";
 export * from "./registries/JsonSchemaMapperContainer.js";
 export * from "./utils/buildPath.js";
+export * from "./utils/compile.js";
 export * from "./utils/concatParameters.js";
 export * from "./utils/concatPath.js";
 export * from "./utils/defineStatusModel.js";

package/lib/esm/registries/JsonSchemaMapperContainer.js

@@ -11,7 +11,7 @@ export function registerJsonSchemaMapper(type, mapper, spec) {
 /**
  * @ignore
  */
-export function getJsonSchemaMapper(type, options) {
+export function compileMapper(type, options) {
     const mapper = JsonSchemaMappersContainer.get(`${options?.specType}:${type}`) || JsonSchemaMappersContainer.get(type);
     if (mapper) {
         return mapper;
@@ -23,7 +23,7 @@ export function getJsonSchemaMapper(type, options) {
  * @ignore
  */
 export function execMapper(type, args, options, parent) {
-    return getJsonSchemaMapper(type, options)(...args, options, parent);
+    return compileMapper(type, options)(...args, options, parent);
 }
 export function hasMapper(type) {
     return JsonSchemaMappersContainer.has(type);

package/lib/esm/utils/compile.js

@@ -0,0 +1,13 @@
+import { getJsonSchema } from "./getJsonSchema.js";
+/**
+ * Compile a class, parameter store, or `JsonSchema` into a plain JSON schema object.
+ *
+ * This is an alias of `getJsonSchema(...)`.
+ *
+ * @param model Class, parameter store, or `JsonSchema` to compile.
+ * @param options JSON schema generation options.
+ * @returns Compiled JSON schema object.
+ */
+export function compile(model, options = {}) {
+    return getJsonSchema(model, options);
+}

package/lib/esm/utils/getJsonSchema.js

@@ -1,6 +1,7 @@
 import "../components/index.js";
 import { getValue, isClass, isPlainObject, nameOf } from "@tsed/core";
 import { JsonParameterStore } from "../domain/JsonParameterStore.js";
+import { JsonSchema } from "../domain/JsonSchema.js";
 import { SpecTypes } from "../domain/SpecTypes.js";
 import { execMapper } from "../registries/JsonSchemaMapperContainer.js";
 import { getJsonEntityStore } from "./getJsonEntityStore.js";
@@ -27,6 +28,10 @@ function get(model, options) {
     CACHES.set(model, cache);
     const key = getKey(options);
     if (!cache.has(key)) {
+        if (model instanceof JsonSchema) {
+            cache.set(key, model.toJSON(options));
+            return cache.get(key);
+        }
         const entity = getJsonEntityStore(model);
         let mapper = "schema";
         if (entity instanceof JsonParameterStore) {

package/lib/types/decorators/common/customKey.d.ts

@@ -3,7 +3,7 @@
  *
  * The `@CustomKey()` decorator allows adding vendor-specific extensions or custom metadata
  * to schemas. These custom keys are only included in the generated schema when explicitly
- * requested with the `customKeys: true` option in `getJsonSchema()`.
+ * requested with the `customKeys: true` option in `compile()`.
  *
  * ### Basic Usage
  *
@@ -55,12 +55,12 @@
  * Custom keys must be explicitly requested:
  *
  * ```typescript
- * import { getJsonSchema } from "@tsed/schema";
+ * import { compile } from "@tsed/schema";
  *
- * const schema = getJsonSchema(UserModel, { customKeys: true });
+ * const schema = compile(UserModel, { customKeys: true });
  * // Schema will include x-internal-id and other custom keys
  *
- * const standardSchema = getJsonSchema(UserModel);
+ * const standardSchema = compile(UserModel);
  * // Custom keys are omitted by default
  * ```
  *

package/lib/types/decorators/common/ref.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Set a `$ref` value on the current schema property/parameter.
+ *
+ * Supports local references (`#/...`) and external URLs.
+ *
+ * @param ref - Reference URI
+ * @decorator
+ */
+export declare function Ref(ref: string): (...args: any[]) => any;

package/lib/types/decorators/generics/generics.d.ts

@@ -1,5 +1,5 @@
 /**
- * Define generics list. This list is used by @@GenericOf@@ and the @@getJsonSchema@@ function to build the correct JsonSchema.
+ * Define generics list. This list is used by @@GenericOf@@ and the @@compile@@ function to build the correct JsonSchema.
  *
  * See @@GenericOf@@ decorator for more details.
  *

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

@@ -17,7 +17,7 @@
  * ```typescript
  * import {SpecTypes} from "@tsed/schema";
  *
- * const schema = getJsonSchema(MyModel, {
+ * const schema = compile(MyModel, {
  *   specType: SpecTypes.OPENAPI
  * });
  * ```

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

@@ -13,6 +13,7 @@ import { lazyRef } from "./lazyRef.js";
 import { number } from "./number.js";
 import { object } from "./object.js";
 import { oneOf } from "./oneOf.js";
+import { ref } from "./ref.js";
 import { string } from "./string.js";
 import { uri } from "./uri.js";
 import { url } from "./url.js";
@@ -40,6 +41,7 @@ export declare const s: {
     readonly lazyRef: typeof lazyRef;
     readonly object: typeof object;
     readonly oneOf: typeof oneOf;
+    readonly $ref: typeof ref;
     readonly string: typeof string;
     readonly uri: typeof uri;
     readonly url: typeof url;

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

@@ -0,0 +1,15 @@
+import { JsonSchema } from "../domain/JsonSchema.js";
+/**
+ * Create a schema reference from an external or internal `$ref` URI.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * const UserRef = ref("https://api.example.com/doc/swagger.json#/components/schemas/User");
+ * ```
+ *
+ * @param path - The reference URI
+ * @returns A JsonSchema containing the `$ref`
+ * @schemaFunctional
+ */
+export declare function ref<T = unknown>(path: string): JsonSchema<T>;

package/lib/types/index.d.ts

@@ -80,6 +80,7 @@ export * from "./decorators/common/pattern.js";
 export * from "./decorators/common/property.js";
 export * from "./decorators/common/readOnly.js";
 export * from "./decorators/common/recordOf.js";
+export * from "./decorators/common/ref.js";
 export * from "./decorators/common/required.js";
 export * from "./decorators/common/requiredGroups.js";
 export * from "./decorators/common/schema.js";
@@ -150,6 +151,7 @@ export * from "./fn/lazyRef.js";
 export * from "./fn/number.js";
 export * from "./fn/object.js";
 export * from "./fn/oneOf.js";
+export * from "./fn/ref.js";
 export * from "./fn/string.js";
 export * from "./fn/uri.js";
 export * from "./fn/url.js";
@@ -163,6 +165,7 @@ export * from "./interfaces/JsonSchemaOptions.js";
 export * from "./registries/enumRegistries.js";
 export * from "./registries/JsonSchemaMapperContainer.js";
 export * from "./utils/buildPath.js";
+export * from "./utils/compile.js";
 export * from "./utils/concatParameters.js";
 export * from "./utils/concatPath.js";
 export * from "./utils/defineStatusModel.js";

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

@@ -11,7 +11,7 @@ import type { GenericsMap } from "../utils/generics.js";
  * ### Usage
  *
  * ```typescript
- * import {getJsonSchema, JsonSchemaOptions} from "@tsed/schema";
+ * import {compile, JsonSchemaOptions} from "@tsed/schema";
  *
  * const options: JsonSchemaOptions = {
  *   specType: SpecTypes.OPENAPI,
@@ -21,7 +21,7 @@ import type { GenericsMap } from "../utils/generics.js";
  *   customKeys: true
  * };
  *
- * const schema = getJsonSchema(MyModel, options);
+ * const schema = compile(MyModel, options);
  * ```
  *
  * @public

package/lib/types/registries/JsonSchemaMapperContainer.d.ts

@@ -12,7 +12,7 @@ export declare function registerJsonSchemaMapper(type: string, mapper: JsonSchem
 /**
  * @ignore
  */
-export declare function getJsonSchemaMapper(type: string, options: any): JsonSchemaMapper;
+export declare function compileMapper(type: string, options: any): JsonSchemaMapper;
 /**
  * @ignore
  */

package/lib/types/utils/compile.d.ts

@@ -0,0 +1,14 @@
+import { Type } from "@tsed/core";
+import { JsonParameterStore } from "../domain/JsonParameterStore.js";
+import { JsonSchema } from "../domain/JsonSchema.js";
+import { JsonSchemaOptions } from "../interfaces/JsonSchemaOptions.js";
+/**
+ * Compile a class, parameter store, or `JsonSchema` into a plain JSON schema object.
+ *
+ * This is an alias of `getJsonSchema(...)`.
+ *
+ * @param model Class, parameter store, or `JsonSchema` to compile.
+ * @param options JSON schema generation options.
+ * @returns Compiled JSON schema object.
+ */
+export declare function compile(model: Type<any> | JsonParameterStore | JsonSchema, options?: JsonSchemaOptions): any;

package/lib/types/utils/getJsonSchema.d.ts

@@ -1,5 +1,6 @@
 import "../components/index.js";
 import { Type } from "@tsed/core";
 import { JsonParameterStore } from "../domain/JsonParameterStore.js";
+import { JsonSchema } from "../domain/JsonSchema.js";
 import { JsonSchemaOptions } from "../interfaces/JsonSchemaOptions.js";
-export declare function getJsonSchema(model: Type<any> | JsonParameterStore, options?: JsonSchemaOptions): any;
+export declare function getJsonSchema(model: Type<any> | JsonParameterStore | JsonSchema, options?: JsonSchemaOptions): any;

package/package.json

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