TypeScript export extraction to OpenPkg spec
npm install @openpkg-ts/extractTypeScript API extraction library. Generates OpenPkg specs from TypeScript source code with JSON Schema 2020-12 output.
``bash`
npm install @openpkg-ts/extract
`bashExtract API spec from entry point
tspec src/index.ts -o openpkg.json
Programmatic Usage
`typescript
import { extract } from '@openpkg-ts/extract';const result = await extract({
entryFile: 'src/index.ts',
maxTypeDepth: 4,
resolveExternalTypes: true,
});
console.log(
Extracted ${result.spec.exports.length} exports);
console.log(Found ${result.spec.types?.length ?? 0} types);// Check for diagnostics
for (const diag of result.diagnostics) {
console.warn(
${diag.severity}: ${diag.message});
}
`Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
|
entryFile | string | required | Entry point file path |
| baseDir | string | cwd | Base directory for resolution |
| maxTypeDepth | number | 4 | Max depth for type traversal |
| resolveExternalTypes | boolean | true | Resolve types from node_modules |
| schemaExtraction | 'static' \| 'hybrid' | 'static' | Schema extraction mode |
| schemaTarget | 'draft-2020-12' \| 'draft-07' \| 'openapi-3.0' | 'draft-2020-12' | Target JSON Schema dialect |
| only | string[] | - | Only extract these exports (supports * wildcards) |
| ignore | string[] | - | Ignore these exports (supports * wildcards) |JSON Schema 2020-12 Output
All schema output is normalized to valid JSON Schema 2020-12. This ensures consistency between static TypeScript analysis and runtime schema extraction from libraries like Zod and Valibot.
$3
Interfaces and classes include a
schema property containing a JSON Schema object representation:`json
{
"kind": "interface",
"name": "User",
"schema": {
"type": "object",
"properties": {
"id": { "type": "string" },
"age": { "type": "number" },
"email": { "type": "string" }
},
"required": ["id", "email"]
},
"members": [...]
}
`$3
TypeScript constructs that don't map directly to JSON Schema are preserved using extension fields:
| Extension | Purpose | Example |
|-----------|---------|---------|
|
x-ts-type | Preserves original TypeScript type | { "type": "integer", "x-ts-type": "bigint" } |
| x-ts-function | Marks function types | { "x-ts-function": true, "x-ts-signatures": [...] } |
| x-ts-signatures | Function/method signatures | Array of signature objects with parameters and returns |
| x-ts-type-arguments | Generic type arguments | { "$ref": "#/types/Promise", "x-ts-type-arguments": [{ "type": "string" }] } |
| x-ts-accessor | Getter/setter markers | { "type": "string", "x-ts-accessor": "getter" } |$3
| TypeScript Type | JSON Schema Output |
|-----------------|-------------------|
|
void | { "type": "null" } |
| never | { "not": {} } |
| any | {} |
| unknown | {} |
| undefined | { "type": "null" } |
| bigint | { "type": "integer", "x-ts-type": "bigint" } |
| symbol | { "type": "string", "x-ts-type": "symbol" } |
| [T, U] (tuple) | { "type": "array", "prefixedItems": [...], "minItems": 2, "maxItems": 2 } |
| () => T (function) | { "x-ts-function": true, "x-ts-signatures": [...] } |
| Promise | { "$ref": "#/types/Promise", "x-ts-type-arguments": [ |$3
`json
{
"kind": "function",
"name": "fetchUser",
"signatures": [{
"parameters": [{
"name": "id",
"schema": { "type": "string" },
"required": true
}],
"returns": {
"schema": {
"$ref": "#/types/Promise",
"x-ts-type-arguments": [{ "$ref": "#/types/User" }]
}
}
}]
}
`$3
`json
{
"kind": "interface",
"name": "Repository",
"schema": {
"type": "object",
"properties": {
"id": { "type": "string" },
"find": {
"x-ts-function": true,
"x-ts-signatures": [{
"parameters": [{ "name": "query", "schema": { "type": "string" } }],
"returns": { "schema": { "type": "array", "items": { "$ref": "#/types/Item" } } }
}]
}
},
"required": ["id", "find"]
}
}
`Exports
$3
- extract(options) - Main extraction function$3
- getModuleExports - Get exports from a module
- resolveExportTarget - Resolve re-exports to source$3
- TypeRegistry - Track and dedupe extracted types
- serializeType - Convert TS types to schema$3
- normalizeSchema(schema, options) - Convert SpecSchema to JSON Schema 2020-12
- normalizeExport(exp, options) - Normalize a SpecExport including nested schemas
- normalizeType(type, options) - Normalize a SpecType including nested schemas
- normalizeMembers(members, options) - Convert members array to JSON Schema properties$3
- ZodAdapter, ValibotAdapter` - Runtime schema extraction1. Creates a TypeScript program from the entry file
2. Extracts all exported symbols
3. Serializes each export (functions, classes, types, variables)
4. Resolves type references and builds a type registry
5. Normalizes all schemas to JSON Schema 2020-12
6. Outputs an OpenPkg-compliant JSON spec
MIT