@powerlines/schema 0.11.45 → 0.11.47

package/dist/extract.cjs

@@ -7,16 +7,115 @@ let defu = require("defu");
 defu = require_runtime.__toESM(defu, 1);
 let _stryke_type_checks = require("@stryke/type-checks");
 let _stryke_type_checks_is_set_object = require("@stryke/type-checks/is-set-object");
-let _stryke_json = require("@stryke/json");
 let _powerlines_core = require("@powerlines/core");
 let _powerlines_deepkit_rolldown_plugin = require("@powerlines/deepkit/rolldown-plugin");
 let _powerlines_deepkit_vendor_type = require("@powerlines/deepkit/vendor/type");
 let _stryke_hash = require("@stryke/hash");
+let _stryke_helpers_deep_clone = require("@stryke/helpers/deep-clone");
+let _stryke_json = require("@stryke/json");
 let _stryke_path_join = require("@stryke/path/join");
 let _stryke_zod = require("@stryke/zod");
 let _valibot_to_json_schema = require("@valibot/to-json-schema");
 
 //#region src/extract.ts
+const SCHEMA_BUNDLE_BASE_URI = "https://powerlines.invalid/";
+function normalizeUri(uri) {
+	return uri.endsWith("#") ? uri.slice(0, -1) : uri;
+}
+function stripUriFragment(uri) {
+	const hashIndex = uri.indexOf("#");
+	return hashIndex >= 0 ? uri.slice(0, hashIndex) : uri;
+}
+function escapeJsonPointerToken(token) {
+	return token.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function toJsonPointer(path) {
+	if (path.length === 0) return "";
+	return `/${path.map((segment) => escapeJsonPointerToken(segment)).join("/")}`;
+}
+function resolveUri(reference, baseUri) {
+	try {
+		return normalizeUri(new URL(reference, baseUri).toString());
+	} catch {
+		return normalizeUri(reference);
+	}
+}
+function collectReferenceTargets(value, path, baseUri, uriToPointer, dynamicUriToFragment) {
+	if (!(0, _stryke_type_checks_is_set_object.isSetObject)(value)) return;
+	const schema = value;
+	const pointer = toJsonPointer(path);
+	const currentBaseUri = (0, _stryke_type_checks.isSetString)(schema.$id) ? resolveUri(schema.$id, baseUri) : baseUri;
+	const currentDocumentUri = stripUriFragment(currentBaseUri);
+	uriToPointer.set(currentBaseUri, pointer);
+	uriToPointer.set(currentDocumentUri, pointer);
+	if ((0, _stryke_type_checks.isSetString)(schema.$anchor)) uriToPointer.set(`${currentDocumentUri}#${schema.$anchor}`, pointer);
+	if ((0, _stryke_type_checks.isSetString)(schema.$dynamicAnchor)) {
+		const dynamicTarget = `${currentDocumentUri}#${schema.$dynamicAnchor}`;
+		uriToPointer.set(dynamicTarget, pointer);
+		dynamicUriToFragment.set(dynamicTarget, `#${schema.$dynamicAnchor}`);
+	}
+	for (const [key, child] of Object.entries(schema)) {
+		if (Array.isArray(child)) {
+			child.forEach((entry, index) => {
+				collectReferenceTargets(entry, [
+					...path,
+					key,
+					String(index)
+				], currentBaseUri, uriToPointer, dynamicUriToFragment);
+			});
+			continue;
+		}
+		collectReferenceTargets(child, [...path, key], currentBaseUri, uriToPointer, dynamicUriToFragment);
+	}
+}
+function rewriteReferenceTargets(value, path, baseUri, uriToPointer, dynamicUriToFragment) {
+	if (!(0, _stryke_type_checks_is_set_object.isSetObject)(value)) return;
+	const schema = value;
+	const currentBaseUri = (0, _stryke_type_checks.isSetString)(schema.$id) ? resolveUri(schema.$id, baseUri) : baseUri;
+	if ((0, _stryke_type_checks.isSetString)(schema.$ref)) {
+		const resolvedRefUri = resolveUri(schema.$ref, currentBaseUri);
+		const pointer = uriToPointer.get(resolvedRefUri) ?? uriToPointer.get(stripUriFragment(resolvedRefUri));
+		if (pointer !== void 0) schema.$ref = pointer.length > 0 ? `#${pointer}` : "#";
+	}
+	if ((0, _stryke_type_checks.isSetString)(schema.$dynamicRef)) {
+		const resolvedDynamicRefUri = resolveUri(schema.$dynamicRef, currentBaseUri);
+		const dynamicFragment = dynamicUriToFragment.get(resolvedDynamicRefUri);
+		if (dynamicFragment) schema.$dynamicRef = dynamicFragment;
+		else {
+			const pointer = uriToPointer.get(resolvedDynamicRefUri) ?? uriToPointer.get(stripUriFragment(resolvedDynamicRefUri));
+			if (pointer !== void 0) schema.$dynamicRef = pointer.length > 0 ? `#${pointer}` : "#";
+		}
+	}
+	for (const [key, child] of Object.entries(schema)) {
+		if (Array.isArray(child)) {
+			child.forEach((entry, index) => {
+				rewriteReferenceTargets(entry, [
+					...path,
+					key,
+					String(index)
+				], currentBaseUri, uriToPointer, dynamicUriToFragment);
+			});
+			continue;
+		}
+		rewriteReferenceTargets(child, [...path, key], currentBaseUri, uriToPointer, dynamicUriToFragment);
+	}
+}
+/**
+* Bundles all external references in a JSON Schema into a single schema document by collecting all reference targets and rewriting the references to point to the bundled definitions. This ensures that the resulting schema is self-contained and can be used independently without relying on external documents.
+*
+* @param schema - The JSON Schema to bundle references for.
+* @returns A new JSON Schema with all references bundled and rewritten to point to the bundled definitions.
+*/
+function bundleReferences(schema) {
+	if (!(0, _stryke_type_checks_is_set_object.isSetObject)(schema)) return schema;
+	const bundledSchema = (0, _stryke_helpers_deep_clone.deepClone)(schema);
+	const baseUri = (0, _stryke_type_checks.isSetString)(bundledSchema.$id) ? resolveUri(bundledSchema.$id, SCHEMA_BUNDLE_BASE_URI) : SCHEMA_BUNDLE_BASE_URI;
+	const uriToPointer = /* @__PURE__ */ new Map();
+	const dynamicUriToFragment = /* @__PURE__ */ new Map();
+	collectReferenceTargets(bundledSchema, [], baseUri, uriToPointer, dynamicUriToFragment);
+	rewriteReferenceTargets(bundledSchema, [], baseUri, uriToPointer, dynamicUriToFragment);
+	return bundledSchema;
+}
 function convertNestedUntypedSchema(value) {
 	if (require_type_checks.isUntypedSchema(value)) return convertUntypedSchemaToJsonSchema(value);
 	if ((0, _stryke_type_checks_is_set_object.isSetObject)(value)) {
@@ -31,7 +130,7 @@ function convertNestedUntypedSchemaArray(value) {
 	return value.map((item) => convertNestedUntypedSchema(item));
 }
 function convertValibotSchemaToJsonSchema(schema) {
-	return (0, _valibot_to_json_schema.toJsonSchema)(schema, { target: "draft-07" });
+	return (0, _valibot_to_json_schema.toJsonSchema)(schema, { target: "draft-2020-12" });
 }
 function convertUntypedSchemaToJsonSchema(schema) {
 	const source = schema;
@@ -99,6 +198,10 @@ function extractHash(variant, input) {
 		variant,
 		input
 	});
+	else if (typeof input === "boolean") return (0, _stryke_hash.murmurhash)({
+		variant,
+		input
+	});
 	else if ((0, _stryke_type_checks_is_set_object.isSetObject)(input)) {
 		if ((0, _stryke_zod.isZod3Type)(input)) return (0, _stryke_hash.murmurhash)({
 			variant,
@@ -132,7 +235,7 @@ function extractHash(variant, input) {
 	throw new Error(`Failed to create an input hash for the provided schema definition input. The input must be a Zod schema, a Standard JSON Schema, a JSON Schema object, a Valibot BaseSchema, or a reflected Deepkit Type object.`);
 }
 /**
-* Converts a reflected Deepkit {@link Type} into a JSON Schema (draft-07) representation.
+* Converts a reflected Deepkit {@link Type} into a JSON Schema (draft-2020-12) representation.
 */
 function extractReflection(reflection) {
 	if (!(0, _powerlines_deepkit_vendor_type.isType)(reflection)) return;
@@ -151,7 +254,15 @@ function extractJsonSchema(schema) {
 		if (require_type_checks.isJsonSchema(schema)) return schema;
 	}
 }
+/**
+* Resolves the concrete source variant for a schema source input.
+*
+* @param input - The schema source input to inspect.
+* @returns The resolved schema source variant.
+* @throws Will throw an error when the input cannot be mapped to a supported source variant.
+*/
 function extractResolvedVariant(input) {
+	if (typeof input === "boolean") return "json-schema";
 	if ((0, _stryke_type_checks_is_set_object.isSetObject)(input)) {
 		if ((0, _stryke_zod.isZod3Type)(input)) return "zod3";
 		else if ((0, _stryke_json.isStandardJsonSchema)(input)) return "standard-schema";
@@ -162,19 +273,41 @@ function extractResolvedVariant(input) {
 	}
 	throw new Error(`Failed to determine the variant of the provided schema definition input. The input must be a Zod schema, a Standard JSON Schema, a JSON Schema object, a Valibot BaseSchema, a reflected Deepkit Type object, or an Untyped schema.`);
 }
+/**
+* Determines the top-level input variant for schema extraction.
+*
+* @param input - The schema input to classify.
+* @returns The resolved schema input variant.
+*/
 function extractVariant(input) {
 	if ((0, _stryke_type_checks.isSetString)(input) || (0, _powerlines_core.isTypeDefinition)(input)) return "type-definition";
 	return extractResolvedVariant(input);
 }
-async function extractSchemaSchema(input, variant) {
-	if (require_type_checks.isExtractedSchema(input)) return input.schema;
+/**
+* Extracts and normalizes a JSON Schema from a concrete schema source input.
+*
+* @param input - The schema source input to extract from.
+* @param variant - Optional source variant override. When omitted, the variant is inferred from the input.
+* @returns A promise that resolves to a bundled JSON Schema.
+* @throws Will throw an error if no valid JSON Schema can be extracted from the input.
+*/
+async function extractSchema(input, variant) {
+	if (require_type_checks.isSchemaWithSource(input)) return input.schema;
 	const resolvedVariant = variant ?? extractResolvedVariant(input);
 	let schema;
 	if (resolvedVariant === "zod3" || resolvedVariant === "json-schema" || resolvedVariant === "standard-schema" || resolvedVariant === "untyped" || resolvedVariant === "valibot") schema = extractJsonSchema(input);
 	else if (resolvedVariant === "reflection") schema = extractReflection(input);
-	if (schema) return schema;
+	if (schema) return bundleReferences(schema);
 	throw new Error(`Failed to extract a valid schema from the provided input. The input must be a Zod schema, a Standard JSON Schema, a JSON Schema object, a Valibot BaseSchema, an untyped schema, or a reflected Deepkit Type object.`);
 }
+/**
+* Builds source metadata for a schema input using a known source variant.
+*
+* @param variant - The schema source variant associated with the input.
+* @param input - The schema source input to wrap.
+* @returns The normalized schema source payload, including the source hash and variant.
+* @throws Will throw an error if the provided variant is unsupported.
+*/
 function extractSource(variant, input) {
 	if (variant === "zod3") return {
 		hash: extractHash(variant, input),
@@ -209,7 +342,7 @@ function extractSource(variant, input) {
 	throw new Error(`Failed to extract source information from the provided input. The input must be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object.`);
 }
 /**
-* Extracts a JSON Schema from a given schema definition input, which can be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object. If the input is a type definition reference (e.g. a file path with an export), it will be resolved and bundled using ESBuild to obtain the actual schema definition before extraction.
+* Extracts a JSON Schema from a given schema definition input, which can be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a Deepkit Type object. If the input is a type definition reference (e.g. a file path with an export), it will be resolved and bundled using Rolldown to obtain the actual schema definition before extraction.
 *
 * @example
 * ```ts
@@ -223,19 +356,20 @@ function extractSource(variant, input) {
 * const schema4 = await extract(context, reflectionType);
 * ```
 *
-* @see https://github.com/colinhacks/zod
+* @see https://zod.dev/
+* @see https://valibot.dev/
 * @see https://standardschema.dev/json-schema#what-schema-libraries-support-this-spec
 * @see https://json-schema.org/
 * @see https://ajv.js.org/json-type-definition.html
 * @see https://deepkit.io/en/documentation/runtime-types/reflection
 *
 * @param context - The context object providing access to the file system and cache path.
-* @param input - The schema definition input to extract, which can be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object. If the input is a string or a type definition reference, it will be resolved and bundled to obtain the actual schema definition before extraction.
-* @param options - Optional overrides for the ESBuild configuration used during extraction. This can include custom plugins, loaders, or other build options to control how the schema definition is resolved and bundled when the input is a type definition reference.
+* @param input - The schema definition input to extract, which can be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a reflected Deepkit Type object. If the input is a string or a type definition reference, it will be resolved and bundled to obtain the actual schema definition before extraction.
+* @param options - Optional overrides for the Rolldown configuration used during extraction. This can include custom plugins, loaders, or other build options to control how the schema definition is resolved and bundled when the input is a type definition reference.
 * @returns A promise that resolves to the extracted and normalized schema as a JSON Schema object. The function will attempt to extract a valid JSON Schema from the provided input, and if successful, it will return the schema. If the extraction process fails or if the input is not a valid schema definition, it will throw an error indicating the failure.
 */
-async function extractSchema(context, input, options = {}) {
-	if (require_type_checks.isExtractedSchema(input)) return input;
+async function extractSchemaWithSource(context, input, options = {}) {
+	if (require_type_checks.isSchemaWithSource(input)) return input;
 	if (require_type_checks.isSchema(input)) return {
 		...input,
 		source: {
@@ -258,18 +392,19 @@ async function extractSchema(context, input, options = {}) {
 		"standard-schema",
 		"zod3",
 		"untyped",
+		"valibot",
 		"reflection"
 	].includes(variant)) source = extractSource(variant, input);
 	else throw new Error(`Invalid schema definition input "${variant}". The variant must be one of "type-definition", "json-schema", "standard-schema", "zod3", "untyped", or "reflection".`);
 	return {
 		variant,
 		source,
-		schema: await extractSchemaSchema(source.schema, source.variant),
+		schema: await extractSchema(source.schema, source.variant),
 		hash
 	};
 }
 /**
-* Extracts a JSON Schema from a given schema definition input, which can be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object. If the input is a type definition reference (e.g. a file path with an export), it will be resolved and bundled using ESBuild to obtain the actual schema definition before extraction.
+* Extracts a JSON Schema from a given schema definition input, which can be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a Deepkit Type object. If the input is a type definition reference (e.g. a file path with an export), it will be resolved and bundled using Rolldown to obtain the actual schema definition before extraction.
 *
 * @example
 * ```ts
@@ -283,7 +418,8 @@ async function extractSchema(context, input, options = {}) {
 * const schema4 = await extract(context, reflectionType);
 * ```
 *
-* @see https://github.com/colinhacks/zod
+* @see https://zod.dev/
+* @see https://valibot.dev/
 * @see https://standardschema.dev/json-schema#what-schema-libraries-support-this-spec
 * @see https://json-schema.org/
 * @see https://ajv.js.org/json-type-definition.html
@@ -292,13 +428,13 @@ async function extractSchema(context, input, options = {}) {
 * @see https://www.typescriptlang.org/docs/handbook/2/types-from-types.html
 *
 * @param context - The context object providing access to the file system and cache path.
-* @param input - The schema definition input to extract, which can be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object.
-* @param options - Optional overrides for the ESBuild configuration used during extraction.
+* @param input - The schema definition input to extract, which can be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a reflected Deepkit Type object.
+* @param options - Optional overrides for the Rolldown configuration used during extraction.
 * @returns A promise that resolves to the extracted and normalized schema as a JSON Schema object.
 * @throws Will throw an error if the input is not a valid schema definition or if the extraction process fails to produce a valid schema.
 */
 async function extract(context, input, options = {}) {
-	if (require_type_checks.isExtractedSchema(input) || require_type_checks.isSchema(input)) return input;
+	if (require_type_checks.isSchemaWithSource(input) || require_type_checks.isSchema(input)) return input;
 	let result;
 	const variant = extractVariant(input);
 	const hash = extractHash(variant, input);
@@ -311,18 +447,20 @@ async function extract(context, input, options = {}) {
 			schema: JSON.parse(schema)
 		};
 	}
-	result ??= await extractSchema(context, input, options);
-	if (!result?.schema) throw new Error(`Failed to extract a valid schema from the provided input. The input must be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object.`);
+	result ??= await extractSchemaWithSource(context, input, options);
+	if (!result?.schema) throw new Error(`Failed to extract a valid schema from the provided input. The input must be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a reflected Deepkit Type object.`);
 	if (context.config.skipCache !== true) await require_persistence.writeSchema(context, result);
 	return result;
 }
 
 //#endregion
+exports.bundleReferences = bundleReferences;
 exports.extract = extract;
 exports.extractHash = extractHash;
 exports.extractJsonSchema = extractJsonSchema;
 exports.extractReflection = extractReflection;
 exports.extractResolvedVariant = extractResolvedVariant;
 exports.extractSchema = extractSchema;
+exports.extractSchemaWithSource = extractSchemaWithSource;
 exports.extractSource = extractSource;
 exports.extractVariant = extractVariant;

package/dist/extract.d.cts

@@ -4,23 +4,60 @@ import { BuildOptions } from "rolldown";
 import { Type } from "@powerlines/deepkit/vendor/type";
 
 //#region src/extract.d.ts
+/**
+ * Bundles all external references in a JSON Schema into a single schema document by collecting all reference targets and rewriting the references to point to the bundled definitions. This ensures that the resulting schema is self-contained and can be used independently without relying on external documents.
+ *
+ * @param schema - The JSON Schema to bundle references for.
+ * @returns A new JSON Schema with all references bundled and rewritten to point to the bundled definitions.
+ */
+declare function bundleReferences(schema: JsonSchema): JsonSchema;
 /**
  * Creates a hash string for a given schema definition input.
  */
-declare function extractHash<T = unknown>(variant: SchemaInputVariant, input: SchemaInput<T>): string;
+declare function extractHash(variant: SchemaInputVariant, input: SchemaInput): string;
 /**
- * Converts a reflected Deepkit {@link Type} into a JSON Schema (draft-07) representation.
+ * Converts a reflected Deepkit {@link Type} into a JSON Schema (draft-2020-12) representation.
  */
-declare function extractReflection<T = unknown>(reflection: Type): JsonSchema<T> | undefined;
+declare function extractReflection(reflection: Type): JsonSchema | undefined;
 /**
  * Extracts a JSON Schema from Zod, Standard Schema, Valibot, untyped, or JSON Schema inputs.
  */
-declare function extractJsonSchema<T = unknown>(schema: unknown): JsonSchema<T> | undefined;
+declare function extractJsonSchema(schema: unknown): JsonSchema | undefined;
+/**
+ * Resolves the concrete source variant for a schema source input.
+ *
+ * @param input - The schema source input to inspect.
+ * @returns The resolved schema source variant.
+ * @throws Will throw an error when the input cannot be mapped to a supported source variant.
+ */
 declare function extractResolvedVariant(input: SchemaSourceInput): SchemaSourceVariant;
-declare function extractVariant<T = unknown>(input: SchemaInput<T>): SchemaInputVariant;
+/**
+ * Determines the top-level input variant for schema extraction.
+ *
+ * @param input - The schema input to classify.
+ * @returns The resolved schema input variant.
+ */
+declare function extractVariant(input: SchemaInput): SchemaInputVariant;
+/**
+ * Extracts and normalizes a JSON Schema from a concrete schema source input.
+ *
+ * @param input - The schema source input to extract from.
+ * @param variant - Optional source variant override. When omitted, the variant is inferred from the input.
+ * @returns A promise that resolves to a bundled JSON Schema.
+ * @throws Will throw an error if no valid JSON Schema can be extracted from the input.
+ */
+declare function extractSchema(input: SchemaSourceInput, variant?: SchemaInputVariant): Promise<JsonSchema>;
+/**
+ * Builds source metadata for a schema input using a known source variant.
+ *
+ * @param variant - The schema source variant associated with the input.
+ * @param input - The schema source input to wrap.
+ * @returns The normalized schema source payload, including the source hash and variant.
+ * @throws Will throw an error if the provided variant is unsupported.
+ */
 declare function extractSource(variant: SchemaSourceVariant, input: SchemaSourceInput): SchemaSource;
 /**
- * Extracts a JSON Schema from a given schema definition input, which can be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object. If the input is a type definition reference (e.g. a file path with an export), it will be resolved and bundled using ESBuild to obtain the actual schema definition before extraction.
+ * Extracts a JSON Schema from a given schema definition input, which can be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a Deepkit Type object. If the input is a type definition reference (e.g. a file path with an export), it will be resolved and bundled using Rolldown to obtain the actual schema definition before extraction.
  *
  * @example
  * ```ts
@@ -34,20 +71,21 @@ declare function extractSource(variant: SchemaSourceVariant, input: SchemaSource
  * const schema4 = await extract(context, reflectionType);
  * ```
  *
- * @see https://github.com/colinhacks/zod
+ * @see https://zod.dev/
+ * @see https://valibot.dev/
  * @see https://standardschema.dev/json-schema#what-schema-libraries-support-this-spec
  * @see https://json-schema.org/
  * @see https://ajv.js.org/json-type-definition.html
  * @see https://deepkit.io/en/documentation/runtime-types/reflection
  *
  * @param context - The context object providing access to the file system and cache path.
- * @param input - The schema definition input to extract, which can be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object. If the input is a string or a type definition reference, it will be resolved and bundled to obtain the actual schema definition before extraction.
- * @param options - Optional overrides for the ESBuild configuration used during extraction. This can include custom plugins, loaders, or other build options to control how the schema definition is resolved and bundled when the input is a type definition reference.
+ * @param input - The schema definition input to extract, which can be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a reflected Deepkit Type object. If the input is a string or a type definition reference, it will be resolved and bundled to obtain the actual schema definition before extraction.
+ * @param options - Optional overrides for the Rolldown configuration used during extraction. This can include custom plugins, loaders, or other build options to control how the schema definition is resolved and bundled when the input is a type definition reference.
  * @returns A promise that resolves to the extracted and normalized schema as a JSON Schema object. The function will attempt to extract a valid JSON Schema from the provided input, and if successful, it will return the schema. If the extraction process fails or if the input is not a valid schema definition, it will throw an error indicating the failure.
  */
-declare function extractSchema<T = unknown>(context: Context, input: SchemaInput, options?: Partial<BuildOptions>): Promise<ExtractedSchema<T>>;
+declare function extractSchemaWithSource(context: Context, input: SchemaInput, options?: Partial<BuildOptions>): Promise<ExtractedSchema>;
 /**
- * Extracts a JSON Schema from a given schema definition input, which can be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object. If the input is a type definition reference (e.g. a file path with an export), it will be resolved and bundled using ESBuild to obtain the actual schema definition before extraction.
+ * Extracts a JSON Schema from a given schema definition input, which can be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a Deepkit Type object. If the input is a type definition reference (e.g. a file path with an export), it will be resolved and bundled using Rolldown to obtain the actual schema definition before extraction.
  *
  * @example
  * ```ts
@@ -61,7 +99,8 @@ declare function extractSchema<T = unknown>(context: Context, input: SchemaInput
  * const schema4 = await extract(context, reflectionType);
  * ```
  *
- * @see https://github.com/colinhacks/zod
+ * @see https://zod.dev/
+ * @see https://valibot.dev/
  * @see https://standardschema.dev/json-schema#what-schema-libraries-support-this-spec
  * @see https://json-schema.org/
  * @see https://ajv.js.org/json-type-definition.html
@@ -70,12 +109,12 @@ declare function extractSchema<T = unknown>(context: Context, input: SchemaInput
  * @see https://www.typescriptlang.org/docs/handbook/2/types-from-types.html
  *
  * @param context - The context object providing access to the file system and cache path.
- * @param input - The schema definition input to extract, which can be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object.
- * @param options - Optional overrides for the ESBuild configuration used during extraction.
+ * @param input - The schema definition input to extract, which can be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a reflected Deepkit Type object.
+ * @param options - Optional overrides for the Rolldown configuration used during extraction.
  * @returns A promise that resolves to the extracted and normalized schema as a JSON Schema object.
  * @throws Will throw an error if the input is not a valid schema definition or if the extraction process fails to produce a valid schema.
  */
-declare function extract<T = unknown>(context: Context, input: SchemaInput, options?: Partial<BuildOptions>): Promise<Schema<T>>;
+declare function extract(context: Context, input: SchemaInput, options?: Partial<BuildOptions>): Promise<Schema>;
 //#endregion
-export { extract, extractHash, extractJsonSchema, extractReflection, extractResolvedVariant, extractSchema, extractSource, extractVariant };
+export { bundleReferences, extract, extractHash, extractJsonSchema, extractReflection, extractResolvedVariant, extractSchema, extractSchemaWithSource, extractSource, extractVariant };
 //# sourceMappingURL=extract.d.cts.map

package/dist/extract.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"extract.d.cts","names":[],"sources":["../src/extract.ts"],"mappings":";;;;;;;;AAqOA;iBAAgB,WAAA,aAAA,CACd,OAAA,EAAS,kBAAA,EACT,KAAA,EAAO,WAAA,CAAY,CAAA;;;;iBAuCL,iBAAA,aAAA,CACd,UAAA,EAAY,IAAA,GACX,UAAA,CAAW,CAAA;;;;iBAWE,iBAAA,aAAA,CACd,MAAA,YACC,UAAU,CAAC,CAAA;AAAA,iBA2BE,sBAAA,CACd,KAAA,EAAO,iBAAA,GACN,mBAAmB;AAAA,iBAsBN,cAAA,aAAA,CACd,KAAA,EAAO,WAAA,CAAY,CAAA,IAClB,kBAAA;AAAA,iBAwCa,aAAA,CACd,OAAA,EAAS,mBAAA,EACT,KAAA,EAAO,iBAAA,GACN,YAAA;;;AAtJoB;AAuCvB;;;;;;;;;;;;;;AAEe;AAWf;;;;;;;;iBAwKsB,aAAA,aAAA,CACpB,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,WAAA,EACP,OAAA,GAAS,OAAA,CAAQ,YAAA,IAChB,OAAA,CAAQ,eAAA,CAAgB,CAAA;AA1KZ;AA2Bf;;;;;;;;AAEsB;AAsBtB;;;;;;;;;;;;;;AAEqB;AAwCrB;;;;AA7Fe,iBAqQO,OAAA,aAAA,CACpB,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,WAAA,EACP,OAAA,GAAS,OAAA,CAAQ,YAAA,IAChB,OAAA,CAAQ,MAAA,CAAO,CAAA"}
+{"version":3,"file":"extract.d.cts","names":[],"sources":["../src/extract.ts"],"mappings":";;;;;;;;AAuOA;;;;iBAAgB,gBAAA,CAAiB,MAAA,EAAQ,UAAA,GAAa,UAAU;;;;iBAgMhD,WAAA,CACd,OAAA,EAAS,kBAAA,EACT,KAAA,EAAO,WAAW;AAFpB;;;AAAA,iBA2CgB,iBAAA,CAAkB,UAAA,EAAY,IAAA,GAAO,UAAU;;;;iBAW/C,iBAAA,CAAkB,MAAA,YAAkB,UAAU;;AApD1C;AAyCpB;;;;;iBA6CgB,sBAAA,CACd,KAAA,EAAO,iBAAA,GACN,mBAAmB;;;AA/CyC;AAW/D;;;iBAoEgB,cAAA,CAAe,KAAA,EAAO,WAAA,GAAc,kBAAkB;AApER;AAkC9D;;;;;;;AAlC8D,iBAoFxC,aAAA,CACpB,KAAA,EAAO,iBAAA,EACP,OAAA,GAAU,kBAAA,GACT,OAAA,CAAQ,UAAA;AAnDW;AAgCtB;;;;;;;AAhCsB,iBAwFN,aAAA,CACd,OAAA,EAAS,mBAAA,EACT,KAAA,EAAO,iBAAA,GACN,YAAA;AA3DmE;AAgBtE;;;;;;;;;;;;;;;;AAGqB;AAqCrB;;;;;;;;;AAxDsE,iBAkIhD,uBAAA,CACpB,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,WAAA,EACP,OAAA,GAAS,OAAA,CAAQ,YAAA,IAChB,OAAA,CAAQ,eAAA;;;;;AA3EI;AAuEf;;;;;;;;;;;;;;;;;;;;;AAI0B;AA6F1B;;;iBAAsB,OAAA,CACpB,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,WAAA,EACP,OAAA,GAAS,OAAA,CAAQ,YAAA,IAChB,OAAA,CAAQ,MAAA"}

package/dist/extract.d.mts

@@ -4,23 +4,60 @@ import { Context } from "@powerlines/core";
 import { Type } from "@powerlines/deepkit/vendor/type";
 
 //#region src/extract.d.ts
+/**
+ * Bundles all external references in a JSON Schema into a single schema document by collecting all reference targets and rewriting the references to point to the bundled definitions. This ensures that the resulting schema is self-contained and can be used independently without relying on external documents.
+ *
+ * @param schema - The JSON Schema to bundle references for.
+ * @returns A new JSON Schema with all references bundled and rewritten to point to the bundled definitions.
+ */
+declare function bundleReferences(schema: JsonSchema): JsonSchema;
 /**
  * Creates a hash string for a given schema definition input.
  */
-declare function extractHash<T = unknown>(variant: SchemaInputVariant, input: SchemaInput<T>): string;
+declare function extractHash(variant: SchemaInputVariant, input: SchemaInput): string;
 /**
- * Converts a reflected Deepkit {@link Type} into a JSON Schema (draft-07) representation.
+ * Converts a reflected Deepkit {@link Type} into a JSON Schema (draft-2020-12) representation.
  */
-declare function extractReflection<T = unknown>(reflection: Type): JsonSchema<T> | undefined;
+declare function extractReflection(reflection: Type): JsonSchema | undefined;
 /**
  * Extracts a JSON Schema from Zod, Standard Schema, Valibot, untyped, or JSON Schema inputs.
  */
-declare function extractJsonSchema<T = unknown>(schema: unknown): JsonSchema<T> | undefined;
+declare function extractJsonSchema(schema: unknown): JsonSchema | undefined;
+/**
+ * Resolves the concrete source variant for a schema source input.
+ *
+ * @param input - The schema source input to inspect.
+ * @returns The resolved schema source variant.
+ * @throws Will throw an error when the input cannot be mapped to a supported source variant.
+ */
 declare function extractResolvedVariant(input: SchemaSourceInput): SchemaSourceVariant;
-declare function extractVariant<T = unknown>(input: SchemaInput<T>): SchemaInputVariant;
+/**
+ * Determines the top-level input variant for schema extraction.
+ *
+ * @param input - The schema input to classify.
+ * @returns The resolved schema input variant.
+ */
+declare function extractVariant(input: SchemaInput): SchemaInputVariant;
+/**
+ * Extracts and normalizes a JSON Schema from a concrete schema source input.
+ *
+ * @param input - The schema source input to extract from.
+ * @param variant - Optional source variant override. When omitted, the variant is inferred from the input.
+ * @returns A promise that resolves to a bundled JSON Schema.
+ * @throws Will throw an error if no valid JSON Schema can be extracted from the input.
+ */
+declare function extractSchema(input: SchemaSourceInput, variant?: SchemaInputVariant): Promise<JsonSchema>;
+/**
+ * Builds source metadata for a schema input using a known source variant.
+ *
+ * @param variant - The schema source variant associated with the input.
+ * @param input - The schema source input to wrap.
+ * @returns The normalized schema source payload, including the source hash and variant.
+ * @throws Will throw an error if the provided variant is unsupported.
+ */
 declare function extractSource(variant: SchemaSourceVariant, input: SchemaSourceInput): SchemaSource;
 /**
- * Extracts a JSON Schema from a given schema definition input, which can be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object. If the input is a type definition reference (e.g. a file path with an export), it will be resolved and bundled using ESBuild to obtain the actual schema definition before extraction.
+ * Extracts a JSON Schema from a given schema definition input, which can be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a Deepkit Type object. If the input is a type definition reference (e.g. a file path with an export), it will be resolved and bundled using Rolldown to obtain the actual schema definition before extraction.
  *
  * @example
  * ```ts
@@ -34,20 +71,21 @@ declare function extractSource(variant: SchemaSourceVariant, input: SchemaSource
  * const schema4 = await extract(context, reflectionType);
  * ```
  *
- * @see https://github.com/colinhacks/zod
+ * @see https://zod.dev/
+ * @see https://valibot.dev/
  * @see https://standardschema.dev/json-schema#what-schema-libraries-support-this-spec
  * @see https://json-schema.org/
  * @see https://ajv.js.org/json-type-definition.html
  * @see https://deepkit.io/en/documentation/runtime-types/reflection
  *
  * @param context - The context object providing access to the file system and cache path.
- * @param input - The schema definition input to extract, which can be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object. If the input is a string or a type definition reference, it will be resolved and bundled to obtain the actual schema definition before extraction.
- * @param options - Optional overrides for the ESBuild configuration used during extraction. This can include custom plugins, loaders, or other build options to control how the schema definition is resolved and bundled when the input is a type definition reference.
+ * @param input - The schema definition input to extract, which can be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a reflected Deepkit Type object. If the input is a string or a type definition reference, it will be resolved and bundled to obtain the actual schema definition before extraction.
+ * @param options - Optional overrides for the Rolldown configuration used during extraction. This can include custom plugins, loaders, or other build options to control how the schema definition is resolved and bundled when the input is a type definition reference.
  * @returns A promise that resolves to the extracted and normalized schema as a JSON Schema object. The function will attempt to extract a valid JSON Schema from the provided input, and if successful, it will return the schema. If the extraction process fails or if the input is not a valid schema definition, it will throw an error indicating the failure.
  */
-declare function extractSchema<T = unknown>(context: Context, input: SchemaInput, options?: Partial<BuildOptions>): Promise<ExtractedSchema<T>>;
+declare function extractSchemaWithSource(context: Context, input: SchemaInput, options?: Partial<BuildOptions>): Promise<ExtractedSchema>;
 /**
- * Extracts a JSON Schema from a given schema definition input, which can be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object. If the input is a type definition reference (e.g. a file path with an export), it will be resolved and bundled using ESBuild to obtain the actual schema definition before extraction.
+ * Extracts a JSON Schema from a given schema definition input, which can be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a Deepkit Type object. If the input is a type definition reference (e.g. a file path with an export), it will be resolved and bundled using Rolldown to obtain the actual schema definition before extraction.
  *
  * @example
  * ```ts
@@ -61,7 +99,8 @@ declare function extractSchema<T = unknown>(context: Context, input: SchemaInput
  * const schema4 = await extract(context, reflectionType);
  * ```
  *
- * @see https://github.com/colinhacks/zod
+ * @see https://zod.dev/
+ * @see https://valibot.dev/
  * @see https://standardschema.dev/json-schema#what-schema-libraries-support-this-spec
  * @see https://json-schema.org/
  * @see https://ajv.js.org/json-type-definition.html
@@ -70,12 +109,12 @@ declare function extractSchema<T = unknown>(context: Context, input: SchemaInput
  * @see https://www.typescriptlang.org/docs/handbook/2/types-from-types.html
  *
  * @param context - The context object providing access to the file system and cache path.
- * @param input - The schema definition input to extract, which can be a Zod schema, a Standard JSON Schema, a JSON Schema object, an untyped schema, or a reflected Deepkit Type object.
- * @param options - Optional overrides for the ESBuild configuration used during extraction.
+ * @param input - The schema definition input to extract, which can be a Zod schema, a Valibot schema, any Standard JSON Schema type, a plain JSON Schema object, an untyped schema, or a reflected Deepkit Type object.
+ * @param options - Optional overrides for the Rolldown configuration used during extraction.
  * @returns A promise that resolves to the extracted and normalized schema as a JSON Schema object.
  * @throws Will throw an error if the input is not a valid schema definition or if the extraction process fails to produce a valid schema.
  */
-declare function extract<T = unknown>(context: Context, input: SchemaInput, options?: Partial<BuildOptions>): Promise<Schema<T>>;
+declare function extract(context: Context, input: SchemaInput, options?: Partial<BuildOptions>): Promise<Schema>;
 //#endregion
-export { extract, extractHash, extractJsonSchema, extractReflection, extractResolvedVariant, extractSchema, extractSource, extractVariant };
+export { bundleReferences, extract, extractHash, extractJsonSchema, extractReflection, extractResolvedVariant, extractSchema, extractSchemaWithSource, extractSource, extractVariant };
 //# sourceMappingURL=extract.d.mts.map

package/dist/extract.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"extract.d.mts","names":[],"sources":["../src/extract.ts"],"mappings":";;;;;;;;AAqOA;iBAAgB,WAAA,aAAA,CACd,OAAA,EAAS,kBAAA,EACT,KAAA,EAAO,WAAA,CAAY,CAAA;;;;iBAuCL,iBAAA,aAAA,CACd,UAAA,EAAY,IAAA,GACX,UAAA,CAAW,CAAA;;;;iBAWE,iBAAA,aAAA,CACd,MAAA,YACC,UAAU,CAAC,CAAA;AAAA,iBA2BE,sBAAA,CACd,KAAA,EAAO,iBAAA,GACN,mBAAmB;AAAA,iBAsBN,cAAA,aAAA,CACd,KAAA,EAAO,WAAA,CAAY,CAAA,IAClB,kBAAA;AAAA,iBAwCa,aAAA,CACd,OAAA,EAAS,mBAAA,EACT,KAAA,EAAO,iBAAA,GACN,YAAA;;;AAtJoB;AAuCvB;;;;;;;;;;;;;;AAEe;AAWf;;;;;;;;iBAwKsB,aAAA,aAAA,CACpB,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,WAAA,EACP,OAAA,GAAS,OAAA,CAAQ,YAAA,IAChB,OAAA,CAAQ,eAAA,CAAgB,CAAA;AA1KZ;AA2Bf;;;;;;;;AAEsB;AAsBtB;;;;;;;;;;;;;;AAEqB;AAwCrB;;;;AA7Fe,iBAqQO,OAAA,aAAA,CACpB,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,WAAA,EACP,OAAA,GAAS,OAAA,CAAQ,YAAA,IAChB,OAAA,CAAQ,MAAA,CAAO,CAAA"}
+{"version":3,"file":"extract.d.mts","names":[],"sources":["../src/extract.ts"],"mappings":";;;;;;;;AAuOA;;;;iBAAgB,gBAAA,CAAiB,MAAA,EAAQ,UAAA,GAAa,UAAU;;;;iBAgMhD,WAAA,CACd,OAAA,EAAS,kBAAA,EACT,KAAA,EAAO,WAAW;AAFpB;;;AAAA,iBA2CgB,iBAAA,CAAkB,UAAA,EAAY,IAAA,GAAO,UAAU;;;;iBAW/C,iBAAA,CAAkB,MAAA,YAAkB,UAAU;;AApD1C;AAyCpB;;;;;iBA6CgB,sBAAA,CACd,KAAA,EAAO,iBAAA,GACN,mBAAmB;;;AA/CyC;AAW/D;;;iBAoEgB,cAAA,CAAe,KAAA,EAAO,WAAA,GAAc,kBAAkB;AApER;AAkC9D;;;;;;;AAlC8D,iBAoFxC,aAAA,CACpB,KAAA,EAAO,iBAAA,EACP,OAAA,GAAU,kBAAA,GACT,OAAA,CAAQ,UAAA;AAnDW;AAgCtB;;;;;;;AAhCsB,iBAwFN,aAAA,CACd,OAAA,EAAS,mBAAA,EACT,KAAA,EAAO,iBAAA,GACN,YAAA;AA3DmE;AAgBtE;;;;;;;;;;;;;;;;AAGqB;AAqCrB;;;;;;;;;AAxDsE,iBAkIhD,uBAAA,CACpB,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,WAAA,EACP,OAAA,GAAS,OAAA,CAAQ,YAAA,IAChB,OAAA,CAAQ,eAAA;;;;;AA3EI;AAuEf;;;;;;;;;;;;;;;;;;;;;AAI0B;AA6F1B;;;iBAAsB,OAAA,CACpB,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,WAAA,EACP,OAAA,GAAS,OAAA,CAAQ,YAAA,IAChB,OAAA,CAAQ,MAAA"}