@jsdocs-io/extractor/dist/get-package-api.js

The API extractor for npm packages powering jsdocs.io

var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
    if (value !== null && value !== void 0) {
        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
        var dispose, inner;
        if (async) {
            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
            dispose = value[Symbol.asyncDispose];
        }
        if (dispose === void 0) {
            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
            dispose = value[Symbol.dispose];
            if (async) inner = dispose;
        }
        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
        env.stack.push({ value: value, dispose: dispose, async: async });
    }
    else if (async) {
        env.stack.push({ async: true });
    }
    return value;
};
var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
    return function (env) {
        function fail(e) {
            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
            env.hasError = true;
        }
        var r, s = 0;
        function next() {
            while (r = env.stack.pop()) {
                try {
                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
                    if (r.dispose) {
                        var result = r.dispose.call(r.value);
                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
                    }
                    else s |= 1;
                }
                catch (e) {
                    fail(e);
                }
            }
            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
            if (env.hasError) throw env.error;
        }
        return next();
    };
})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
    var e = new Error(message);
    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
});
import { performance } from "node:perf_hooks";
import { join } from "pathe";
import { Bun } from "./bun.js";
import { getPackageDeclarations } from "./get-package-declarations.js";
import { getPackageJson } from "./get-package-json.js";
import { getPackageOverview } from "./get-package-overview.js";
import { getPackageTypes } from "./get-package-types.js";
import { getProject } from "./get-project.js";
import { tempDir } from "./temp-dir.js";
/**
`getPackageApi` extracts the API from a package.

If the extraction succeeds, `getPackageApi` returns a {@link PackageApi} object.
If the extraction fails, `getPackageApi` throws an error.

Warning: The extraction process is slow and blocks the main thread, using workers is recommended.

@example
```ts
const packageApi = await getPackageApi({
  pkg: "foo",    // Extract API from npm package `foo` [Required]
  subpath: ".",  // Select subpath `.` (root subpath) [Optional]
  maxDepth: 5,   // Maximum depth for analyzing nested namespaces [Optional]
  bun: new Bun() // Bun package manager instance [Optional]
});
console.log(JSON.stringify(packageApi, null, 2));
```

@param options - {@link GetPackageApiOptions}

@returns A {@link PackageApi} object
*/
export async function getPackageApi({ pkg, subpath = ".", maxDepth = 5, bun = new Bun(), }) {
    const env_1 = { stack: [], error: void 0, hasError: false };
    try {
        // Normalize options.
        pkg = pkg.trim();
        subpath = subpath.trim() || ".";
        maxDepth = Math.max(1, Math.round(maxDepth));
        // Start performance timer.
        const start = performance.now();
        // Create a temporary directory where to install the package.
        const dir = __addDisposableResource(env_1, await tempDir(), true);
        const cwd = dir.path;
        // Install the package and its direct and third-party dependencies.
        const dependencies = await bun.add(pkg, cwd);
        // Read the package's `package.json`.
        const pkgName = await getInstalledPackageName(cwd);
        const pkgDir = join(cwd, "node_modules", pkgName);
        const pkgJson = await getPackageJson(pkgDir);
        const { name, version } = pkgJson;
        // Find the package's types entry point file, if any.
        const types = getPackageTypes({ pkgJson, subpath });
        if (!types) {
            return {
                name,
                version,
                subpath,
                types: undefined,
                overview: undefined,
                declarations: [],
                dependencies,
                analyzedAt: analyzedAt(),
                analyzedIn: analyzedIn(start),
            };
        }
        // Create TypeScript project.
        const pkgTypes = join(pkgDir, types);
        const { project, indexFile } = getProject({ indexFilePath: pkgTypes, typeRoots: cwd });
        // Get overview.
        const overview = getPackageOverview(indexFile);
        // Extract the declarations exported by the package.
        const declarations = await getPackageDeclarations({ pkgName, project, indexFile, maxDepth });
        // Return the data extracted from the package.
        return {
            name,
            version,
            subpath,
            types,
            overview,
            declarations,
            dependencies,
            analyzedAt: analyzedAt(),
            analyzedIn: analyzedIn(start),
        };
    }
    catch (e_1) {
        env_1.error = e_1;
        env_1.hasError = true;
    }
    finally {
        const result_1 = __disposeResources(env_1);
        if (result_1)
            await result_1;
    }
}
async function getInstalledPackageName(cwd) {
    // Since `pkg` can contain any argument accepted by Bun's `add` command
    // (e.g., URLs), get the package name from the only dependency listed in
    // the `package.json` file created by Bun in the `cwd` on install.
    const pkgJson = await getPackageJson(cwd);
    return Object.keys(pkgJson.dependencies).at(0);
}
function analyzedAt() {
    return new Date().toISOString();
}
function analyzedIn(start) {
    return Math.round(performance.now() - start);
}