@openpkg-ts/spec 0.19.0 → 0.23.0

package/dist/index.d.ts

@@ -112,7 +112,7 @@ type SpecSchemaRef = {
 type SpecSchemaFallback = {
 	type: string;
 };
-type SpecSchemaGeneric = Record<string, unknown>;
+type SpecSchemaGeneric = Record<string, unknown> & Partial<JSONSchemaExtensions>;
 type SpecSchema = string | SpecSchemaPrimitive | SpecSchemaComposite | SpecSchemaCombinator | SpecSchemaRef | SpecSchemaFallback | SpecSchemaGeneric;
 type SpecExampleLanguage = "ts" | "js" | "tsx" | "jsx" | "shell" | "json";
 type SpecExample = {
@@ -163,6 +163,50 @@ type SpecSignature = {
 	isImplementation?: boolean;
 	throws?: SpecThrows[];
 };
+/**
+* JSON Schema extension fields for TypeScript-specific type information.
+*
+* These extensions use the `x-` prefix which is valid JSON Schema for vendor extensions.
+* They allow consumers to preserve TypeScript-specific information while still having
+* valid JSON Schema. The extensions are optional - a consumer can ignore them for pure
+* JSON Schema usage.
+*
+* Extension semantics:
+* | Extension            | Purpose                                                              |
+* |----------------------|----------------------------------------------------------------------|
+* | `x-ts-type`          | Preserves original TS type for types that map to JSON Schema but    |
+* |                      | lose fidelity (bigint → integer, symbol → string)                   |
+* | `x-ts-function`      | Marks a schema as representing a function type                      |
+* | `x-ts-signatures`    | Contains function/method signatures for callable types              |
+* | `x-ts-type-arguments`| Preserves generic type arguments for parameterized types            |
+*/
+type JSONSchemaExtensions = {
+	/**
+	* Preserves the original TypeScript type when mapping to JSON Schema loses fidelity.
+	* Examples:
+	* - bigint → { type: "integer", "x-ts-type": "bigint" }
+	* - symbol → { type: "string", "x-ts-type": "symbol" }
+	* - void → { type: "null", "x-ts-type": "void" } (optionally)
+	* - never, any, unknown, undefined also supported
+	*/
+	"x-ts-type"?: "bigint" | "symbol" | "void" | "never" | "any" | "unknown" | "undefined" | string;
+	/**
+	* Marks a schema as representing a function type.
+	* When true, the schema represents a callable TypeScript function.
+	*/
+	"x-ts-function"?: boolean;
+	/**
+	* Contains function/method signatures for callable types.
+	* Used in conjunction with `x-ts-function` to preserve full signature information.
+	*/
+	"x-ts-signatures"?: SpecSignature[];
+	/**
+	* Preserves generic type arguments for parameterized types.
+	* Used with $ref to maintain generic instantiation information.
+	* Example: Map<string, number> → { "$ref": "#/$defs/Map", "x-ts-type-arguments": [...] }
+	*/
+	"x-ts-type-arguments"?: SpecSchema[];
+};
 type SpecMember = {
 	id?: string;
 	name?: string;
@@ -447,4 +491,4 @@ declare function assertSpec(spec: unknown, version?: SchemaVersion): asserts spe
 * @returns Array of validation errors (empty if valid)
 */
 declare function getValidationErrors(spec: unknown, version?: SchemaVersion): SpecError[];
-export { validateSpec, recommendSemverBump, normalize, getValidationErrors, getAvailableVersions, diffSpec, dereference, categorizeBreakingChanges, calculateNextVersion, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecTypeAliasKind, SpecType, SpecThrows, SpecTagParam, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecPresentationMeta, SpecMember, SpecMappedType, SpecGenerationMeta, SpecGenerationInfo, SpecExtensions, SpecExtension, SpecExportKind, SpecExport, SpecExampleLanguage, SpecExample, SpecDiff, SpecDecorator, SpecConditionalType, SemverRecommendation, SemverBump, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, GenerationIssueSeverity, GenerationIssue, EntryPointDetectionMethod, CategorizedBreaking, BreakingSeverity };
+export { validateSpec, recommendSemverBump, normalize, getValidationErrors, getAvailableVersions, diffSpec, dereference, categorizeBreakingChanges, calculateNextVersion, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecTypeAliasKind, SpecType, SpecThrows, SpecTagParam, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecPresentationMeta, SpecMember, SpecMappedType, SpecGenerationMeta, SpecGenerationInfo, SpecExtensions, SpecExtension, SpecExportKind, SpecExport, SpecExampleLanguage, SpecExample, SpecDiff, SpecDecorator, SpecConditionalType, SemverRecommendation, SemverBump, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, JSONSchemaExtensions, GenerationIssueSeverity, GenerationIssue, EntryPointDetectionMethod, CategorizedBreaking, BreakingSeverity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/spec",
-  "version": "0.19.0",
+  "version": "0.23.0",
   "description": "Shared schema, validation, and diff utilities for OpenPkg specs",
   "keywords": [
     "openpkg",