@openpkg-ts/sdk 0.33.0 → 0.34.0

package/dist/browser.d.ts

@@ -0,0 +1,678 @@
+import { OpenPkg, SpecExport, SpecMember, SpecSchema, SpecSignature, SpecType, SpecTypeParameter } from "@openpkg-ts/spec";
+interface FormatSchemaOptions {
+	/** Include package attribution for external types */
+	includePackage?: boolean;
+	/** Collapse unions with more than N members (default: no collapse) */
+	collapseUnionThreshold?: number;
+}
+/**
+* Format a schema to a human-readable type string.
+*
+* @param schema - The schema to format
+* @param options - Formatting options
+* @returns Formatted type string
+*
+* @example
+* ```ts
+* formatSchema({ type: 'string' }) // 'string'
+* formatSchema({ $ref: '#/types/User' }) // 'User'
+* formatSchema({ anyOf: [{ type: 'string' }, { type: 'number' }] }) // 'string | number'
+* formatSchema({ type: 'integer', 'x-ts-type': 'bigint' }) // 'bigint'
+* formatSchema({ 'x-ts-type': 'Response', 'x-ts-package': 'express' }, { includePackage: true }) // 'Response (from express)'
+* ```
+*/
+declare function formatSchema(schema: SpecSchema | undefined, options?: FormatSchemaOptions): string;
+/**
+* Format type parameters to a string like `<T, U extends string>`.
+*
+* @param typeParams - Array of type parameters
+* @returns Formatted type parameters string or empty string
+*
+* @example
+* ```ts
+* formatTypeParameters([{ name: 'T' }]) // '<T>'
+* formatTypeParameters([{ name: 'T', constraint: 'object' }]) // '<T extends object>'
+* formatTypeParameters([{ name: 'T', default: 'unknown' }]) // '<T = unknown>'
+* formatTypeParameters([{ name: 'T', variance: 'in' }]) // '<in T>'
+* ```
+*/
+declare function formatTypeParameters(typeParams?: SpecTypeParameter[]): string;
+/**
+* Format function parameters to a string like `(a: string, b?: number)`.
+*
+* @param sig - The signature containing parameters
+* @returns Formatted parameters string
+*
+* @example
+* ```ts
+* formatParameters({ parameters: [{ name: 'id', schema: { type: 'string' } }] })
+* // '(id: string)'
+* ```
+*/
+declare function formatParameters(sig?: SpecSignature): string;
+/**
+* Format return type from signature.
+*
+* @param sig - The signature containing return type
+* @returns Formatted return type string
+*
+* @example
+* ```ts
+* formatReturnType({ returns: { schema: { type: 'Promise', items: { type: 'string' } } } })
+* // 'Promise<string>'
+* ```
+*/
+declare function formatReturnType(sig?: SpecSignature): string;
+/**
+* Build a full signature string for an export.
+*
+* @param exp - The to build a signature for
+* @param sigIndex - Index of signature to use for overloaded functions
+* @returns Complete signature string
+*
+* @example
+* ```ts
+* buildSignatureString({ kind: 'function', name: 'greet', signatures: [...] })
+* // 'function greet(name: string): string'
+*
+* buildSignatureString({ kind: 'class', name: 'Logger', extends: 'EventEmitter' })
+* // 'class Logger extends EventEmitter'
+* ```
+*/
+declare function buildSignatureString(exp: SpecExport, sigIndex?: number): string;
+/**
+* Resolve a type reference to its definition.
+*
+* @param ref - Type reference string (e.g., '#/types/User')
+* @param spec - The OpenPkg spec containing type definitions
+* @returns The resolved type definition or undefined
+*
+* @example
+* ```ts
+* resolveTypeRef('#/types/User', spec)
+* // { id: 'User', name: 'User', kind: 'interface', ... }
+* ```
+*/
+declare function resolveTypeRef(ref: string, spec: OpenPkg): SpecType | undefined;
+/**
+* Check if a member is a method (has signatures).
+*
+* @param member - The member to check
+* @returns True if the member is a method
+*
+* @example
+* ```ts
+* isMethod({ name: 'foo', signatures: [{ parameters: [] }] }) // true
+* isMethod({ name: 'bar', schema: { type: 'string' } }) // false
+* ```
+*/
+declare function isMethod(member: SpecMember): boolean;
+/**
+* Check if a member is a property (no signatures).
+*
+* @param member - The member to check
+* @returns True if the member is a property
+*/
+declare function isProperty(member: SpecMember): boolean;
+/**
+* Get methods from members list.
+*
+* @param members - Array of members to filter
+* @returns Array of method members
+*/
+declare function getMethods(members?: SpecMember[]): SpecMember[];
+/**
+* Get properties from members list.
+*
+* @param members - Array of members to filter
+* @returns Array of property members
+*/
+declare function getProperties(members?: SpecMember[]): SpecMember[];
+/**
+* Group members by visibility (public, protected, private).
+*
+* @param members - Array of members to group
+* @returns Object with public, protected, and private arrays
+*
+* @example
+* ```ts
+* const groups = groupByVisibility(classExport.members)
+* groups.public  // [{ name: 'foo', visibility: 'public' }]
+* groups.private // [{ name: 'bar', visibility: 'private' }]
+* ```
+*/
+declare function groupByVisibility(members?: SpecMember[]): {
+	public: SpecMember[];
+	protected: SpecMember[];
+	private: SpecMember[];
+};
+/**
+* Sort exports alphabetically by name.
+*
+* @param items - Array of items with a name property
+* @returns New sorted array
+*/
+declare function sortByName<T extends {
+	name: string;
+}>(items: T[]): T[];
+/**
+* Conditional type structure from the spec.
+*/
+interface SpecConditionalType {
+	checkType: SpecSchema;
+	extendsType: SpecSchema;
+	trueType: SpecSchema;
+	falseType: SpecSchema;
+}
+/**
+* Mapped type structure from the spec.
+*/
+interface SpecMappedType {
+	keyType: SpecSchema;
+	valueType: SpecSchema;
+	readonly?: boolean | "add" | "remove";
+	optional?: boolean | "add" | "remove";
+}
+/**
+* Format a conditional type to a human-readable string.
+*
+* @param condType - The conditional type structure
+* @returns Formatted conditional type string
+*
+* @example
+* ```ts
+* formatConditionalType({
+*   checkType: { 'x-ts-type': 'T' },
+*   extendsType: { type: 'string' },
+*   trueType: { type: 'boolean', const: true },
+*   falseType: { type: 'boolean', const: false }
+* })
+* // 'T extends string ? true : false'
+* ```
+*/
+declare function formatConditionalType(condType: SpecConditionalType): string;
+/**
+* Format a mapped type to a human-readable string.
+*
+* @param mappedType - The mapped type structure
+* @returns Formatted mapped type string
+*
+* @example
+* ```ts
+* formatMappedType({
+*   keyType: { 'x-ts-type': 'K in keyof T' },
+*   valueType: { 'x-ts-type': 'T[K]' },
+*   readonly: true
+* })
+* // '{ readonly [K in keyof T]: T[K] }'
+* ```
+*/
+declare function formatMappedType(mappedType: SpecMappedType): string;
+import { OpenPkg as OpenPkg2, SpecExport as SpecExport2, SpecExportKind } from "@openpkg-ts/spec";
+type Predicate = (exp: SpecExport2) => boolean;
+/**
+* Chainable query builder for filtering OpenPkg exports.
+* Filters are lazy - predicates only run on execution methods (find, first, count, etc).
+*/
+declare class QueryBuilder {
+	private spec;
+	private predicates;
+	constructor(spec: OpenPkg2);
+	/**
+	* Filter by kind(s)
+	*/
+	byKind(...kinds: SpecExportKind[]): this;
+	/**
+	* Filter by name (exact string or regex pattern)
+	*/
+	byName(pattern: string | RegExp): this;
+	/**
+	* Filter by tag(s) - must have at least one matching tag
+	*/
+	byTag(...tags: string[]): this;
+	/**
+	* Filter by deprecation status
+	* @param include - true = only deprecated, false = exclude deprecated, undefined = all
+	*/
+	deprecated(include?: boolean): this;
+	/**
+	* Filter to exports with descriptions only
+	*/
+	withDescription(): this;
+	/**
+	* Search name and description (case-insensitive)
+	*/
+	search(term: string): this;
+	/**
+	* Custom predicate filter
+	*/
+	where(predicate: Predicate): this;
+	/**
+	* Filter by source module/file path (contains match)
+	*/
+	byModule(modulePath: string): this;
+	private matches;
+	/**
+	* Execute query and return matching exports
+	*/
+	find(): SpecExport2[];
+	/**
+	* Execute query and return first match (or undefined)
+	*/
+	first(): SpecExport2 | undefined;
+	/**
+	* Execute query and return count of matches
+	*/
+	count(): number;
+	/**
+	* Execute query and return IDs of matching exports
+	*/
+	ids(): string[];
+	/**
+	* Execute query and return a new filtered OpenPkg spec
+	*/
+	toSpec(): OpenPkg2;
+}
+/**
+* Create a query builder for the given spec
+*/
+declare function query(spec: OpenPkg2): QueryBuilder;
+import { SpecMember as SpecMember2 } from "@openpkg-ts/spec";
+/**
+* Extract badge strings from a member's visibility and flags.
+* Handles: visibility (if not public), static, readonly, async, abstract
+*/
+declare function getMemberBadges(member: SpecMember2): string[];
+/**
+* Format badges array into a display string (space-separated).
+*/
+declare function formatBadges(badges: string[]): string;
+import { OpenPkg as OpenPkg3, SpecExport as SpecExport3 } from "@openpkg-ts/spec";
+interface DiagnosticItem {
+	exportId: string;
+	exportName: string;
+	issue: string;
+	/** Member name if issue is on a member */
+	member?: string;
+	/** Parameter name if issue is on a parameter */
+	param?: string;
+}
+interface SpecDiagnostics {
+	/** Exports/members without descriptions */
+	missingDescriptions: DiagnosticItem[];
+	/** Exports marked @deprecated but no reason provided */
+	deprecatedNoReason: DiagnosticItem[];
+	/** Function params without descriptions in JSDoc */
+	missingParamDocs: DiagnosticItem[];
+}
+/**
+* Check if has @deprecated tag.
+*/
+declare function hasDeprecatedTag(exp: SpecExport3): boolean;
+/**
+* Get deprecation message from @deprecated tag.
+* Returns undefined if no reason provided.
+*/
+declare function getDeprecationMessage(exp: SpecExport3): string | undefined;
+/**
+* Find params without descriptions in JSDoc.
+*/
+declare function findMissingParamDocs(exp: SpecExport3): string[];
+/**
+* Analyze a spec for quality issues.
+*/
+declare function analyzeSpec(spec: OpenPkg3): SpecDiagnostics;
+import { OpenPkg as OpenPkg4, SpecExportKind as SpecExportKind2 } from "@openpkg-ts/spec";
+interface SearchOptions {
+	/** Base URL for search result links */
+	baseUrl?: string;
+	/** Custom slug generator */
+	slugify?: (name: string) => string;
+	/** Include type signatures in search content */
+	includeSignatures?: boolean;
+	/** Include member names in search content */
+	includeMembers?: boolean;
+	/** Include parameter names in search content */
+	includeParameters?: boolean;
+	/** Weight multipliers for ranking */
+	weights?: {
+		name?: number;
+		description?: number;
+		signature?: number;
+		tags?: number;
+	};
+}
+interface PagefindRecord {
+	url: string;
+	content: string;
+	word_count: number;
+	filters: Record<string, string[]>;
+	meta: {
+		title: string;
+		kind?: string;
+		description?: string;
+		signature?: string;
+	};
+	anchors?: Array<{
+		element: string;
+		id: string;
+		text: string;
+	}>;
+	weighted_sections?: Array<{
+		weight: number;
+		text: string;
+	}>;
+}
+interface AlgoliaRecord {
+	objectID: string;
+	name: string;
+	kind: SpecExportKind2;
+	description?: string;
+	signature: string;
+	content: string;
+	tags: string[];
+	deprecated: boolean;
+	url: string;
+	hierarchy: {
+		lvl0: string;
+		lvl1: string;
+		lvl2?: string;
+	};
+	_rankingInfo?: {
+		nbTypos: number;
+		words: number;
+	};
+}
+interface SearchRecord {
+	id: string;
+	name: string;
+	kind: SpecExportKind2;
+	signature: string;
+	description?: string;
+	content: string;
+	keywords: string[];
+	url: string;
+	deprecated: boolean;
+}
+interface SearchIndex {
+	records: SearchRecord[];
+	version: string;
+	generatedAt: string;
+	packageName: string;
+}
+/**
+* Generate search index from spec.
+*
+* @param spec - The OpenPkg spec to index
+* @param options - Search index configuration
+* @returns Search index with records for each *
+* @example
+* ```ts
+* import { createDocs } from '@openpkg-ts/sdk'
+*
+* const docs = createDocs('./openpkg.json')
+* const index = docs.toSearchIndex({ baseUrl: '/api' })
+* // { records: [...], version: '1.0.0', packageName: 'my-lib' }
+* ```
+*/
+declare function toSearchIndex2(spec: OpenPkg4, options?: SearchOptions): SearchIndex;
+/**
+* Generate Pagefind-compatible records.
+*
+* @param spec - The OpenPkg spec to index
+* @param options - Search configuration including weights
+* @returns Array of Pagefind-compatible search records
+*
+* @example
+* ```ts
+* const records = toPagefindRecords(spec, {
+*   baseUrl: '/docs/api',
+*   weights: { name: 10, description: 5 }
+* })
+* ```
+*/
+declare function toPagefindRecords2(spec: OpenPkg4, options?: SearchOptions): PagefindRecord[];
+/**
+* Generate Algolia-compatible records.
+*
+* @param spec - The OpenPkg spec to index
+* @param options - Search configuration
+* @returns Array of Algolia-compatible search records with hierarchy
+*
+* @example
+* ```ts
+* const records = toAlgoliaRecords(spec, { baseUrl: '/api' })
+* // Upload to Algolia index
+* ```
+*/
+declare function toAlgoliaRecords2(spec: OpenPkg4, options?: SearchOptions): AlgoliaRecord[];
+/**
+* Serialize search index to JSON string.
+*
+* @param spec - The OpenPkg spec to index
+* @param options - Search options plus pretty formatting option
+* @returns JSON string of search index
+*
+* @example
+* ```ts
+* const json = toSearchIndexJSON(spec, { pretty: true })
+* fs.writeFileSync('search-index.json', json)
+* ```
+*/
+declare function toSearchIndexJSON(spec: OpenPkg4, options?: SearchOptions & {
+	pretty?: boolean;
+}): string;
+import { OpenPkg as OpenPkg9, SpecExport as SpecExport5, SpecExportKind as SpecExportKind5, SpecType as SpecType2 } from "@openpkg-ts/spec";
+interface HTMLOptions {
+	/** Page title override */
+	title?: string;
+	/** Include inline styles */
+	includeStyles?: boolean;
+	/** Custom CSS to inject */
+	customCSS?: string;
+	/** Custom head content */
+	headContent?: string;
+	/** Wrap in full HTML document */
+	fullDocument?: boolean;
+	/** Export to render (single mode) */
+	export?: string;
+	/** Exports to render (multi-mode) - overridden by `export` if both provided */
+	exports?: string[];
+}
+import { SpecExportKind as SpecExportKind3 } from "@openpkg-ts/spec";
+interface JSONOptions {
+	/** Include raw spec data alongside simplified data */
+	includeRaw?: boolean;
+	/** Export to render (single mode) */
+	export?: string;
+	/** Exports to render (multi-mode) - overridden by `export` if both provided */
+	exports?: string[];
+	/** Include computed fields (signatures, formatted types) */
+	computed?: boolean;
+	/** Flatten nested structures */
+	flatten?: boolean;
+}
+interface SimplifiedParameter {
+	name: string;
+	type: string;
+	required: boolean;
+	description?: string;
+	default?: unknown;
+	rest?: boolean;
+}
+interface SimplifiedReturn {
+	type: string;
+	description?: string;
+}
+interface SimplifiedSignature {
+	parameters: SimplifiedParameter[];
+	returns?: SimplifiedReturn;
+	description?: string;
+	typeParameters?: string[];
+}
+interface SimplifiedMember {
+	name: string;
+	kind: "property" | "method";
+	type?: string;
+	description?: string;
+	visibility?: "public" | "protected" | "private";
+	signature?: SimplifiedSignature;
+}
+interface SimplifiedExample {
+	code: string;
+	title?: string;
+	description?: string;
+	language?: string;
+}
+interface SimplifiedExport {
+	id: string;
+	name: string;
+	kind: SpecExportKind3;
+	signature: string;
+	description?: string;
+	deprecated: boolean;
+	tags: Array<{
+		name: string;
+		text: string;
+	}>;
+	parameters?: SimplifiedParameter[];
+	returns?: SimplifiedReturn;
+	members?: SimplifiedMember[];
+	examples?: SimplifiedExample[];
+	extends?: string;
+	implements?: string[];
+	sourceFile?: string;
+	sourceLine?: number;
+}
+interface SimplifiedSpec {
+	name: string;
+	version?: string;
+	description?: string;
+	exports: SimplifiedExport[];
+	byKind: Record<SpecExportKind3, SimplifiedExport[]>;
+	totalExports: number;
+}
+interface MarkdownOptions {
+	/** Include frontmatter in output */
+	frontmatter?: boolean;
+	/** Sections to include */
+	sections?: {
+		signature?: boolean;
+		description?: boolean;
+		parameters?: boolean;
+		returns?: boolean;
+		examples?: boolean;
+		members?: boolean;
+		properties?: boolean;
+		methods?: boolean;
+	};
+	/** Custom frontmatter fields */
+	customFrontmatter?: Record<string, unknown>;
+	/** Use code fences for signatures */
+	codeSignatures?: boolean;
+	/** Heading level offset (0 = starts at h1, 1 = starts at h2) */
+	headingOffset?: number;
+	/** Collapse unions with more than N members (default: no collapse) */
+	collapseUnionThreshold?: number;
+}
+interface ExportMarkdownOptions extends MarkdownOptions {
+	/** Export to render (single mode) */
+	export?: string;
+	/** Exports to render (multi-mode) - overridden by `export` if both provided */
+	exports?: string[];
+}
+import { SpecExportKind as SpecExportKind4 } from "@openpkg-ts/spec";
+type NavFormat = "fumadocs" | "docusaurus" | "generic";
+type GroupBy = "kind" | "module" | "tag" | "none";
+interface NavOptions {
+	/** Output format */
+	format?: NavFormat;
+	/** How to group exports */
+	groupBy?: GroupBy;
+	/** Base path for links */
+	basePath?: string;
+	/** Custom slug generator */
+	slugify?: (name: string) => string;
+	/** Include index pages for groups */
+	includeGroupIndex?: boolean;
+	/** Custom kind labels */
+	kindLabels?: Partial<Record<SpecExportKind4, string>>;
+	/** Sort exports alphabetically */
+	sortAlphabetically?: boolean;
+}
+interface NavItem {
+	title: string;
+	href?: string;
+	items?: NavItem[];
+}
+interface NavGroup {
+	title: string;
+	items: NavItem[];
+	index?: string;
+}
+interface GenericNav {
+	title: string;
+	groups: NavGroup[];
+	items: NavItem[];
+}
+interface FumadocsMetaItem {
+	title: string;
+	pages?: string[];
+	defaultOpen?: boolean;
+}
+interface FumadocsMeta {
+	root?: boolean;
+	title?: string;
+	pages?: (string | FumadocsMetaItem)[];
+}
+interface DocusaurusSidebarItem {
+	type: "category" | "doc" | "link";
+	label: string;
+	items?: DocusaurusSidebarItem[];
+	id?: string;
+	href?: string;
+}
+type DocusaurusSidebar = DocusaurusSidebarItem[];
+interface LoadOptions {
+	/** Path to openpkg.json file or the spec object directly */
+	input: string | OpenPkg9;
+}
+interface DocsInstance {
+	/** The parsed OpenPkg spec */
+	spec: OpenPkg9;
+	/** Get an by its ID */
+	getExport(id: string): SpecExport5 | undefined;
+	/** Get a type definition by its ID */
+	getType(id: string): SpecType2 | undefined;
+	/** Get all exports of a specific kind */
+	getExportsByKind(kind: SpecExportKind5): SpecExport5[];
+	/** Get all exports */
+	getAllExports(): SpecExport5[];
+	/** Get all type definitions */
+	getAllTypes(): SpecType2[];
+	/** Get exports by JSDoc tag (e.g., '@beta', '@internal') */
+	getExportsByTag(tagName: string): SpecExport5[];
+	/** Search exports by name or description */
+	search(query: string): SpecExport5[];
+	/** Get exports belonging to a specific module/namespace */
+	getModule(moduleName: string): SpecExport5[];
+	/** Get deprecated exports */
+	getDeprecated(): SpecExport5[];
+	/** Get exports grouped by kind */
+	groupByKind(): Record<SpecExportKind5, SpecExport5[]>;
+	/** Render spec or single to MDX */
+	toMarkdown(options?: ExportMarkdownOptions): string;
+	/** Render spec or single to HTML */
+	toHTML(options?: HTMLOptions): string;
+	/** Render spec or single to JSON structure */
+	toJSON(options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
+	/** Generate navigation structure */
+	toNavigation(options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
+	/** Generate search index */
+	toSearchIndex(options?: SearchOptions): SearchIndex;
+	/** Generate Pagefind-compatible records */
+	toPagefindRecords(options?: SearchOptions): PagefindRecord[];
+	/** Generate Algolia-compatible records */
+	toAlgoliaRecords(options?: SearchOptions): AlgoliaRecord[];
+}
+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 };