How Does This Not Exist?

Whenever I have an idea my first instinct is "someone must have already solved this." Imposter syndrome maybe. Or maybe there's a good reason it doesn't exist.

I inherited 10+ packages with docs that ranged from outdated to nonexistent. My job was to fix it. Make it digestible, complete, actually useful.

TypeDoc was already in place in a few spots. But the generic HTML output didn't match our brand, it buried you in data, and you couldn't navigate it. Technically "documentation". Nobody could use it.

Managing this by hand wasn't going to work. I needed something that starts from source code, extracts the details, and lets me build whatever views I want on top. Not a docs site. A spec.

And to be fair, the existing tools get close. TypeDoc is really good at generating docs but it's more of a document than a spec. Type refs don't resolve, destructured params lose their structure, generics flatten into strings. API Extractor is closer to an actual API surface spec, but the DX is a big turnoff and it ships with way more than I need.

REST APIs have OpenAPI. GraphQL has introspection. What does TypeScript have?

Nothing. No standard for "here's every export, its signature, its types, its JSDoc." No way to diff two versions and see what broke. No structured output you can feed to an LLM or build tooling around.

A package spec should be simple: every public export, full type info, JSON out, works standalone. One command, no build pipeline.

So I'm building it.

OpenPKG, an OpenAPI-style spec for TypeScript packages.

/** Creates a new client */
export function createClient(config: { baseUrl: string }): void {}

npx @openpkg-ts/cli snapshot src/index.ts

1
{
2
  "openpkg": "0.4.0",
3
  "exports": [
4
    {
5
      "name": "createClient",
6
      "kind": "function",
7
      "description": "Creates a new client",
8
      "signatures": [
9
        {
10
          "parameters": [
11
            {
12
              "name": "config",
13
              "schema": {
14
                "type": "object",
15
                "properties": {
16
                  "baseUrl": { "type": "string" }
17
                }
18
              }
19
            }
20
          ]
21
        }
22
      ]
23
    }
24
  ]
25
}

One command. Structured JSON Schema (2020-12). Every export, every signature, every type,every JSDoc. All extracted and ready for whatever you want to build on top.