@openpkg-ts/spec 0.19.0 → 0.24.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 = {
@@ -140,6 +140,8 @@ type SpecTypeParameter = {
 	name: string;
 	constraint?: string;
 	default?: string;
+	variance?: "in" | "out" | "inout";
+	const?: boolean;
 };
 type SpecSignatureParameter = {
 	name: string;
@@ -158,11 +160,79 @@ type SpecSignature = {
 	parameters?: SpecSignatureParameter[];
 	returns?: SpecSignatureReturn;
 	description?: string;
+	tags?: SpecTag[];
+	examples?: SpecExample[];
 	typeParameters?: SpecTypeParameter[];
 	overloadIndex?: number;
 	isImplementation?: boolean;
 	throws?: SpecThrows[];
 };
+/**
+* Type predicate information for type guard functions.
+* Preserved in x-ts-type-predicate extension.
+*/
+type SpecTypePredicate = {
+	/** The parameter name that the type guard narrows */
+	parameterName: string;
+	/** The type that the parameter is narrowed to */
+	type: SpecSchema;
+};
+/**
+* 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            |
+* | `x-ts-type-predicate`| Preserves type guard narrowing information                          |
+* | `x-ts-package`       | Package name for external type references                           |
+*/
+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[];
+	/**
+	* Preserves type guard narrowing information for type predicate functions.
+	* Example: (value: unknown) => value is string → { "x-ts-type-predicate": { parameterName: "value", type: { type: "string" } } }
+	*/
+	"x-ts-type-predicate"?: SpecTypePredicate;
+	/**
+	* Package name for external type references from node_modules.
+	* Example: AnyRouter from @trpc/server → { "$ref": "#/types/AnyRouter", "x-ts-package": "@trpc/server" }
+	*/
+	"x-ts-package"?: string;
+};
 type SpecMember = {
 	id?: string;
 	name?: string;
@@ -175,6 +245,10 @@ type SpecMember = {
 	signatures?: SpecSignature[];
 	decorators?: SpecDecorator[];
 };
+type SpecInheritedMember = SpecMember & {
+	/** Name of the class this member was inherited from */
+	inheritedFrom: string;
+};
 type SpecExportKind = "function" | "class" | "variable" | "interface" | "type" | "enum" | "module" | "namespace" | "reference" | "external";
 type SpecTypeKind = "class" | "interface" | "type" | "enum" | "external";
 type SpecExport = {
@@ -447,4 +521,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, SpecTypePredicate, SpecTypeParameter, SpecTypeKind, SpecTypeAliasKind, SpecType, SpecThrows, SpecTagParam, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecPresentationMeta, SpecMember, SpecMappedType, SpecInheritedMember, 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.24.0",
   "description": "Shared schema, validation, and diff utilities for OpenPkg specs",
   "keywords": [
     "openpkg",