@openpkg-ts/sdk 0.35.0 → 0.36.0

package/dist/browser.d.ts

@@ -400,8 +400,12 @@ import { OpenPkg as OpenPkg8, SpecExport as SpecExport4, SpecMember as SpecMembe
 interface FormatSchemaOptions {
 	/** Include package attribution for external types */
 	includePackage?: boolean;
-	/** Collapse unions with more than N members (default: no collapse) */
+	/** Collapse unions with more than N members (default: 5) */
 	collapseUnionThreshold?: number;
+	/** Max recursion depth before returning "..." (default: 3) */
+	maxDepth?: number;
+	/** @internal current recursion depth */
+	_depth?: number;
 }
 /**
 * Format a schema to a human-readable type string.
@@ -606,7 +610,7 @@ declare function formatConditionalType(condType: SpecConditionalType): string;
 * ```
 */
 declare function formatMappedType(mappedType: SpecMappedType): string;
-import { OpenPkg as OpenPkg9, SpecExport as SpecExport5, SpecExportKind as SpecExportKind5 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg9, SpecExport as SpecExport5, SpecExportKind as SpecExportKind6 } from "@openpkg-ts/spec";
 type Predicate = (exp: SpecExport5) => boolean;
 /**
 * Chainable query builder for filtering OpenPkg exports.
@@ -619,7 +623,7 @@ declare class QueryBuilder {
 	/**
 	* Filter by kind(s)
 	*/
-	byKind(...kinds: SpecExportKind5[]): this;
+	byKind(...kinds: SpecExportKind6[]): this;
 	/**
 	* Filter by name (exact string or regex pattern)
 	*/
@@ -675,4 +679,47 @@ declare class QueryBuilder {
 * Create a query builder for the given spec
 */
 declare function query(spec: OpenPkg9): QueryBuilder;
-export { toSearchIndexJSON, toSearchIndex2 as toSearchIndex, toPagefindRecords2 as toPagefindRecords, toAlgoliaRecords2 as toAlgoliaRecords, sortByName, resolveTypeRef, query, isProperty, isMethod, hasDeprecatedTag, groupByVisibility, getProperties, getMethods, getMemberBadges, getDeprecationMessage, formatTypeParameters, formatSchema, formatReturnType, formatParameters, formatMappedType, formatConditionalType, formatBadges, findMissingParamDocs, buildSignatureString, analyzeSpec, SpecMappedType, SpecDiagnostics, SpecConditionalType, SearchRecord, SearchOptions, SearchIndex, QueryBuilder, PagefindRecord, LoadOptions, FormatSchemaOptions, DocsInstance, DiagnosticItem, AlgoliaRecord };
+import { OpenPkg as OpenPkg10, SpecExample, SpecExport as SpecExport6, SpecSchema as SpecSchema2, SpecSignatureParameter } from "@openpkg-ts/spec";
+interface CodeExample {
+	/** Unique identifier */
+	id: string;
+	/** Display label for chip */
+	label: string;
+	/** Code content */
+	code: string;
+	/** Language for highlighting (e.g. 'ts', 'bash') */
+	language?: string;
+}
+interface Language {
+	/** Language identifier (e.g. "typescript", "python") */
+	id: string;
+	/** Display label (e.g. "TypeScript", "Python") */
+	label: string;
+}
+interface APIParameterSchema {
+	/** Type name */
+	type?: string;
+	/** Formatted type string */
+	typeString?: string;
+	/** Description */
+	description?: string;
+	/** Nested properties for object types */
+	properties?: Record<string, APIParameterSchema>;
+	/** Required property names */
+	required?: string[];
+}
+declare function getLangForHighlight(lang: string): string;
+declare function getLanguageLabel(lang: string): string;
+declare function specSchemaToAPISchema(schema: SpecSchema2 | undefined): APIParameterSchema | undefined;
+declare function specParamToAPIParam(param: SpecSignatureParameter): {
+	name: string;
+	type: string;
+	required: boolean;
+	description?: string;
+	children?: APIParameterSchema;
+};
+/** Convert spec examples to CodeExample[] (Shape B: id/label/code/language) */
+declare function specExamplesToCodeExamples(examples: (string | SpecExample)[] | undefined, defaultLang?: string): CodeExample[];
+declare function getLanguagesFromExamples(examples: (string | SpecExample)[] | undefined): Language[];
+declare function buildImportStatement(exp: SpecExport6, spec: OpenPkg10): string;
+export { toSearchIndexJSON, toSearchIndex2 as toSearchIndex, toPagefindRecords2 as toPagefindRecords, toAlgoliaRecords2 as toAlgoliaRecords, specSchemaToAPISchema, specParamToAPIParam, specExamplesToCodeExamples, sortByName, resolveTypeRef, query, isProperty, isMethod, hasDeprecatedTag, groupByVisibility, getProperties, getMethods, getMemberBadges, getLanguagesFromExamples, getLanguageLabel, getLangForHighlight, getDeprecationMessage, formatTypeParameters, formatSchema, formatReturnType, formatParameters, formatMappedType, formatConditionalType, formatBadges, findMissingParamDocs, buildSignatureString, buildImportStatement, analyzeSpec, SpecMappedType, SpecDiagnostics, SpecConditionalType, SearchRecord, SearchOptions, SearchIndex, QueryBuilder, PagefindRecord, LoadOptions, Language, FormatSchemaOptions, DocsInstance, DiagnosticItem, CodeExample, AlgoliaRecord, APIParameterSchema };

package/dist/browser.js

@@ -25,12 +25,121 @@ import {
   toPagefindRecords,
   toSearchIndex,
   toSearchIndexJSON
-} from "./shared/chunk-skapcfq1.js";
+} from "./shared/chunk-hnajr1tb.js";
+// src/core/spec-converters.ts
+function getLangForHighlight(lang) {
+  const langMap = {
+    typescript: "ts",
+    javascript: "js",
+    ts: "ts",
+    js: "js",
+    tsx: "tsx",
+    jsx: "jsx",
+    bash: "bash",
+    shell: "bash",
+    json: "json",
+    python: "python",
+    go: "go",
+    rust: "rust"
+  };
+  return langMap[lang.toLowerCase()] || lang;
+}
+function getLanguageLabel(lang) {
+  const labels = {
+    typescript: "TypeScript",
+    javascript: "JavaScript",
+    ts: "TypeScript",
+    js: "JavaScript",
+    bash: "Bash",
+    json: "JSON",
+    python: "Python",
+    go: "Go",
+    rust: "Rust"
+  };
+  return labels[lang.toLowerCase()] || lang;
+}
+function specSchemaToAPISchema(schema) {
+  if (!schema || typeof schema !== "object")
+    return;
+  const s = schema;
+  const result = {};
+  result.type = formatSchema(schema);
+  result.typeString = result.type;
+  if (typeof s.description === "string") {
+    result.description = s.description;
+  }
+  if (s.type === "object" && s.properties && typeof s.properties === "object") {
+    result.properties = {};
+    for (const [key, value] of Object.entries(s.properties)) {
+      const nested = specSchemaToAPISchema(value);
+      if (nested)
+        result.properties[key] = nested;
+    }
+    if (Array.isArray(s.required)) {
+      result.required = s.required;
+    }
+  }
+  return result;
+}
+function specParamToAPIParam(param) {
+  const type = formatSchema(param.schema);
+  const children = specSchemaToAPISchema(param.schema);
+  const hasNestedProperties = children?.properties && Object.keys(children.properties).length > 0;
+  return {
+    name: param.name ?? "unknown",
+    type,
+    required: param.required !== false,
+    description: param.description,
+    children: hasNestedProperties ? children : undefined
+  };
+}
+function specExamplesToCodeExamples(examples, defaultLang = "typescript") {
+  if (!examples?.length)
+    return [];
+  return examples.map((ex, i) => {
+    const lang = typeof ex === "string" ? defaultLang : ex.language || defaultLang;
+    const code = typeof ex === "string" ? ex : ex.code;
+    const label = typeof ex === "string" ? getLanguageLabel(lang) : ex.title || getLanguageLabel(lang);
+    return {
+      id: `example-${i}`,
+      label,
+      code,
+      language: getLangForHighlight(lang)
+    };
+  });
+}
+function getLanguagesFromExamples(examples) {
+  if (!examples?.length)
+    return [];
+  const seen = new Set;
+  const result = [];
+  for (const ex of examples) {
+    const lang = typeof ex === "string" ? "typescript" : ex.language || "typescript";
+    if (!seen.has(lang)) {
+      seen.add(lang);
+      result.push({ id: lang, label: getLanguageLabel(lang) });
+    }
+  }
+  return result;
+}
+function buildImportStatement(exp, spec) {
+  const packageName = spec.meta?.name || "package";
+  const presentation = spec.extensions?.presentation?.[exp.id];
+  const importPath = presentation?.importPath || packageName;
+  const alias = presentation?.alias || exp.name;
+  if (exp.kind === "type" || exp.kind === "interface") {
+    return `import type { ${alias} } from '${importPath}'`;
+  }
+  return `import { ${alias} } from '${importPath}'`;
+}
 export {
   toSearchIndexJSON,
   toSearchIndex,
   toPagefindRecords,
   toAlgoliaRecords,
+  specSchemaToAPISchema,
+  specParamToAPIParam,
+  specExamplesToCodeExamples,
   sortByName,
   resolveTypeRef,
   query,
@@ -41,6 +150,9 @@ export {
   getProperties,
   getMethods,
   getMemberBadges,
+  getLanguagesFromExamples,
+  getLanguageLabel,
+  getLangForHighlight,
   getDeprecationMessage,
   formatTypeParameters,
   formatSchema,
@@ -51,6 +163,7 @@ export {
   formatBadges,
   findMissingParamDocs,
   buildSignatureString,
+  buildImportStatement,
   analyzeSpec,
   QueryBuilder
 };

package/dist/index.d.ts

@@ -745,8 +745,12 @@ import { OpenPkg as OpenPkg9, SpecExport as SpecExport4, SpecMember as SpecMembe
 interface FormatSchemaOptions {
 	/** Include package attribution for external types */
 	includePackage?: boolean;
-	/** Collapse unions with more than N members (default: no collapse) */
+	/** Collapse unions with more than N members (default: 5) */
 	collapseUnionThreshold?: number;
+	/** Max recursion depth before returning "..." (default: 3) */
+	maxDepth?: number;
+	/** @internal current recursion depth */
+	_depth?: number;
 }
 /**
 * Format a schema to a human-readable type string.
@@ -951,7 +955,7 @@ declare function formatConditionalType(condType: SpecConditionalType): string;
 * ```
 */
 declare function formatMappedType(mappedType: SpecMappedType): string;
-import { OpenPkg as OpenPkg10, SpecExport as SpecExport5, SpecExportKind as SpecExportKind5 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg10, SpecExport as SpecExport5, SpecExportKind as SpecExportKind6 } from "@openpkg-ts/spec";
 type Predicate = (exp: SpecExport5) => boolean;
 /**
 * Chainable query builder for filtering OpenPkg exports.
@@ -964,7 +968,7 @@ declare class QueryBuilder {
 	/**
 	* Filter by kind(s)
 	*/
-	byKind(...kinds: SpecExportKind5[]): this;
+	byKind(...kinds: SpecExportKind6[]): this;
 	/**
 	* Filter by name (exact string or regex pattern)
 	*/
@@ -1043,10 +1047,10 @@ declare function toReactString(spec: OpenPkg11, options?: {
 	variant?: "full" | "index";
 	componentsPath?: string;
 }): string;
-import { OpenPkg as OpenPkg12, SpecExportKind as SpecExportKind6 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg12, SpecExportKind as SpecExportKind7 } from "@openpkg-ts/spec";
 type FilterCriteria = {
 	/** Filter by kinds */
-	kinds?: SpecExportKind6[];
+	kinds?: SpecExportKind7[];
 	/** Filter by names (exact match) */
 	names?: string[];
 	/** Filter by IDs */
@@ -1169,8 +1173,10 @@ interface SerializerContext {
 	resolveExternalTypes: boolean;
 	typeRegistry: TypeRegistry;
 	exportedIds: Set<string>;
-	/** Track visited types to prevent infinite recursion */
+	/** Stack-style recursion guard for buildSchemaInternal (add before recurse, delete after) */
 	visitedTypes: Set<ts.Type>;
+	/** Permanent "already processed" set for registerReferencedTypes */
+	registeredTypes: Set<ts.Type>;
 	/** Flag to indicate we're processing tuple elements - skip Array prototype methods */
 	inTupleElement?: boolean;
 	/** Include private/protected class members (default: false) */
@@ -1218,7 +1224,7 @@ declare function resolveExportTarget(symbol: ts3.Symbol, checker: ts3.TypeChecke
 	targetSymbol: ts3.Symbol;
 	isTypeOnly: boolean;
 };
-import { SpecExample, SpecSource, SpecTag, SpecTypeParameter as SpecTypeParameter2 } from "@openpkg-ts/spec";
+import { SpecExample, SpecExportKind as SpecExportKind8, SpecSource, SpecTag, SpecTypeParameter as SpecTypeParameter2 } from "@openpkg-ts/spec";
 import ts4 from "typescript";
 declare function getJSDocComment(node: ts4.Node, symbol?: ts4.Symbol, checker?: ts4.TypeChecker): {
 	description?: string;
@@ -1248,6 +1254,8 @@ declare function isSymbolDeprecated(symbol: ts4.Symbol | undefined): {
 	deprecated: boolean;
 	reason?: string;
 };
+/** Classify a declaration node into an kind */
+declare function getExportKind(declaration: ts4.Declaration, type: ts4.Type): SpecExportKind8;
 /**
 * Target version for JSON Schema generation.
 * @see https://standardschema.dev/json-schema
@@ -1469,6 +1477,11 @@ declare class CacheManager<
 	*/
 	set(key: K, value: V): void;
 	/**
+	* Get cached value or compute, cache, and return it.
+	* Unlike has()+get(), this correctly updates LRU order in a single operation.
+	*/
+	getOrCompute(key: K, compute: () => V): V;
+	/**
 	* Delete a specific key from the cache.
 	*/
 	delete(key: K): boolean;
@@ -1620,7 +1633,7 @@ import ts14 from "typescript";
 declare function extractParameters(signature: ts14.Signature, ctx: SerializerContext): SpecSignatureParameter[];
 /**
 * Recursively register types referenced by a ts.Type.
-* Uses ctx.visitedTypes to prevent infinite recursion on circular types.
+* Uses ctx.registeredTypes to prevent re-processing already-registered types.
 */
 declare function registerReferencedTypes(type: ts14.Type, ctx: SerializerContext, depth?: number): void;
 import { SpecSchema as SpecSchema2 } from "@openpkg-ts/spec";
@@ -1630,6 +1643,7 @@ import ts15 from "typescript";
 * Used for types that have specific serialization formats.
 */
 declare const BUILTIN_TYPE_SCHEMAS: Record<string, SpecSchema2>;
+declare const PRIMITIVES: Set<string>;
 declare const ARRAY_PROTOTYPE_METHODS: Set<string>;
 /**
 * Check if a name is a primitive type
@@ -1662,7 +1676,7 @@ declare function ensureNonEmptySchema(schema: SpecSchema2, type: ts15.Type, chec
 * Uses $ref for named types and typeArguments for generics.
 * Guarantees non-empty schema output via ensureNonEmptySchema wrapper.
 */
-declare function buildSchema(type: ts15.Type, checker: ts15.TypeChecker, ctx?: SerializerContext, _depth?: number): SpecSchema2;
+declare function buildSchema(type: ts15.Type, checker: ts15.TypeChecker, ctx?: SerializerContext): SpecSchema2;
 /**
 * Check if a schema is a pure $ref (only has $ref property)
 */
@@ -1756,4 +1770,4 @@ declare function normalizeMembers(members: SpecMember3[], options?: NormalizeOpt
 import ts16 from "typescript";
 declare function isExported(node: ts16.Node): boolean;
 declare function getNodeName(node: ts16.Node): string | undefined;
-export { zodAdapter, withDescription2 as withDescription, valibotAdapter, typeboxAdapter, toSearchIndexJSON, toSearchIndex2 as toSearchIndex, toReactString, toReact, toPagefindRecords2 as toPagefindRecords, toNavigation2 as toNavigation, toMarkdown2 as toMarkdown, toJSONString, toJSON2 as toJSON, toHTML2 as toHTML, toFumadocsMetaJSON, toDocusaurusSidebarJS, toAlgoliaRecords2 as toAlgoliaRecords, sortByName, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, schemasAreEqual, schemaIsAny, resolveTypeRef, resolveExportTarget, resolveCompiledPath, registerReferencedTypes, registerAdapter, recommendSemverBump, query, normalizeType, normalizeSchema, normalizeMembers, normalizeExport, mergeConfig, loadSpec, loadConfig, listExports, isTypeReference, isTypeOnlyExport, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isPureRefSchema, isProperty, isPrimitiveName, isMethod, isExported, isBuiltinGeneric, isAnonymous, hasDeprecatedTag, groupByVisibility, getTypeOrigin, getSourceLocation, getProperties, getParamDescription, getNonNullableType, getNodeName, getMethods, getMemberBadges, getJSDocComment, getExport2 as getExport, getDeprecationMessage, toMarkdown2 as generateDocs, formatTypeParameters, formatSchema, formatReturnType, formatParameters, formatMappedType, formatConditionalType, formatBadges, findMissingParamDocs, findDiscriminatorProperty, findAdapter, filterSpec, extractTypeParameters, extractStandardSchemasFromTs, extractStandardSchemasFromProject, extractStandardSchemas, extractSpec, extractSchemaType, extractParameters, extract, exportToMarkdown, ensureNonEmptySchema, diffSpec2 as diffSpecs, diffSpec, detectTsRuntime, deduplicateSchemas, createProgram, createDocs, categorizeBreakingChanges, calculateNextVersion, buildSignatureString, buildSchema, arktypeAdapter, analyzeSpec, TypeRegistry, TypeReference2 as TypeReference, TsRuntime, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, StandardJSONSchemaTarget, StandardJSONSchemaOptions, SpecMappedType, SpecDiff, SpecDiagnostics, SpecConditionalType, SkippedExportDetail, SimplifiedSpec, SimplifiedSignature, SimplifiedReturn, SimplifiedParameter, SimplifiedMember, SimplifiedExport, SimplifiedExample, SerializerContext, SemverRecommendation, SemverBump, SearchRecord, SearchOptions, SearchIndex, SchemaExtractionResult, SchemaAdapter, ReactLayoutOptions, QueryBuilder, ProjectExtractionOutput, ProjectExtractionInfo, ProgramResult, ProgramOptions, PagefindRecord, OpenpkgConfig, NormalizeOptions, NavOptions, NavItem, NavGroup, NavFormat, MemberChangeInfo, MarkdownOptions, LoadOptions, ListExportsResult, ListExportsOptions, JSONSchema, JSONOptions, HTMLOptions, GroupBy, GetExportResult, GetExportOptions, GenericNav, FumadocsMetaItem, FumadocsMeta, FormatSchemaOptions, ForgottenExport, FilterResult, FilterCriteria, ExtractionWarningCode, ExtractionWarning, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, ExtractFromProjectOptions, ExternalsConfig, ExportVerification, ExportTracker, ExportMarkdownOptions, ExportItem, DocusaurusSidebarItem, DocusaurusSidebar, DocsInstance, DiagnosticItem, Diagnostic, CategorizedBreaking, CacheManagerOptions, CacheManager, CONFIG_FILENAME, BreakingSeverity, BUILTIN_TYPE_SCHEMAS, AlgoliaRecord, ARRAY_PROTOTYPE_METHODS };
+export { zodAdapter, withDescription2 as withDescription, valibotAdapter, typeboxAdapter, toSearchIndexJSON, toSearchIndex2 as toSearchIndex, toReactString, toReact, toPagefindRecords2 as toPagefindRecords, toNavigation2 as toNavigation, toMarkdown2 as toMarkdown, toJSONString, toJSON2 as toJSON, toHTML2 as toHTML, toFumadocsMetaJSON, toDocusaurusSidebarJS, toAlgoliaRecords2 as toAlgoliaRecords, sortByName, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, schemasAreEqual, schemaIsAny, resolveTypeRef, resolveExportTarget, resolveCompiledPath, registerReferencedTypes, registerAdapter, recommendSemverBump, query, normalizeType, normalizeSchema, normalizeMembers, normalizeExport, mergeConfig, loadSpec, loadConfig, listExports, isTypeReference, isTypeOnlyExport, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isPureRefSchema, isProperty, isPrimitiveName, isMethod, isExported, isBuiltinGeneric, isAnonymous, hasDeprecatedTag, groupByVisibility, getTypeOrigin, getSourceLocation, getProperties, getParamDescription, getNonNullableType, getNodeName, getMethods, getMemberBadges, getJSDocComment, getExportKind, getExport2 as getExport, getDeprecationMessage, toMarkdown2 as generateDocs, formatTypeParameters, formatSchema, formatReturnType, formatParameters, formatMappedType, formatConditionalType, formatBadges, findMissingParamDocs, findDiscriminatorProperty, findAdapter, filterSpec, extractTypeParameters, extractStandardSchemasFromTs, extractStandardSchemasFromProject, extractStandardSchemas, extractSpec, extractSchemaType, extractParameters, extract, exportToMarkdown, ensureNonEmptySchema, diffSpec2 as diffSpecs, diffSpec, detectTsRuntime, deduplicateSchemas, createProgram, createDocs, categorizeBreakingChanges, calculateNextVersion, buildSignatureString, buildSchema, arktypeAdapter, analyzeSpec, TypeRegistry, TypeReference2 as TypeReference, TsRuntime, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, StandardJSONSchemaTarget, StandardJSONSchemaOptions, SpecMappedType, SpecDiff, SpecDiagnostics, SpecConditionalType, SkippedExportDetail, SimplifiedSpec, SimplifiedSignature, SimplifiedReturn, SimplifiedParameter, SimplifiedMember, SimplifiedExport, SimplifiedExample, SerializerContext, SemverRecommendation, SemverBump, SearchRecord, SearchOptions, SearchIndex, SchemaExtractionResult, SchemaAdapter, ReactLayoutOptions, QueryBuilder, ProjectExtractionOutput, ProjectExtractionInfo, ProgramResult, ProgramOptions, PagefindRecord, PRIMITIVES, OpenpkgConfig, NormalizeOptions, NavOptions, NavItem, NavGroup, NavFormat, MemberChangeInfo, MarkdownOptions, LoadOptions, ListExportsResult, ListExportsOptions, JSONSchema, JSONOptions, HTMLOptions, GroupBy, GetExportResult, GetExportOptions, GenericNav, FumadocsMetaItem, FumadocsMeta, FormatSchemaOptions, ForgottenExport, FilterResult, FilterCriteria, ExtractionWarningCode, ExtractionWarning, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, ExtractFromProjectOptions, ExternalsConfig, ExportVerification, ExportTracker, ExportMarkdownOptions, ExportItem, DocusaurusSidebarItem, DocusaurusSidebar, DocsInstance, DiagnosticItem, Diagnostic, CategorizedBreaking, CacheManagerOptions, CacheManager, CONFIG_FILENAME, BreakingSeverity, BUILTIN_TYPE_SCHEMAS, AlgoliaRecord, ARRAY_PROTOTYPE_METHODS };