feat(api): typed options object for exec()#253
Merged
Conversation
Adds a `PkgExecOptions` interface and an overload so programmatic consumers can drive builds with a typed object instead of a CLI-style `string[]`. The options path normalizes into argv and feeds the existing minimist pipeline — single source of truth for defaults and validation, zero behavior drift between the two forms. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The options-object path now builds the parsed-argv shape directly and hands it to the rest of exec(), instead of stringifying to CLI argv just to have minimist parse it back. Minimist is still used for the argv overload. Defaults and the flag schema are lifted to module-level constants so both paths share them. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR extends the public Node.js API by adding a typed options-object overload for exec() while preserving the existing argv-array form for backward compatibility, and updates docs/tests accordingly.
Changes:
- Introduces
PkgExecOptionsand a publicPkgCompressTypetype for the programmaticexec()API. - Adds an overload + normalization helper in
lib/index.tsto support both argv-array and options-object entry points. - Documents the new API form and adds a smoke test covering both call styles and basic validation.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| test/test-50-api-options/test-x-index.js | Adds a minimal entry script used by the new API-options smoke test. |
| test/test-50-api-options/main.js | Adds a smoke test for exec({ ... }), argv backward-compat, and input validation. |
| lib/types.ts | Adds exported public types for the new exec() options-object API surface. |
| lib/index.ts | Implements exec() overloads and options-object normalization into the existing minimist pipeline. |
| eslint.config.js | Adjusts ESLint rules to avoid false positives with TypeScript function overloads. |
| docs-site/guide/api.md | Documents both exec() forms and adds a field table for PkgExecOptions. |
- Narrow `targets`, `publicPackages`, `noDictionary` to `string[]` only; the `string | string[]` union blurred the type contract (is `'a,b'` one item or two?). `bakeOptions` keeps the union since CLI-style comma-joined bake flags are conventional. - Drop the `compress: 'None' → undefined` special case; downstream already treats unset as 'None', so the passthrough is uniform with other fields. - Expand test coverage: one build exercises `bakeOptions`, `publicPackages`, `noDictionary` at once (asserting `global.gc` is callable proves `bakeOptions` actually reached the binary — a typo in the flag name in optionsToParsed would surface as 'gc-off'); one build covers `compress: 'Brotli'`. Validation tests now assert on stable substrings and cover `exec(null)`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
viceice
reviewed
Apr 21, 2026
3 tasks
robertsLando
added a commit
that referenced
this pull request
Apr 21, 2026
The `files` whitelist only shipped `lib-es5/index.d.ts`, but that file imports from `./types`, so TypeScript consumers of the typed `exec()` API introduced in #253 couldn't resolve the module. Switch to `lib-es5/*.d.ts` so every generated declaration is published. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PkgExecOptionsinterface for the publicexec()API while preserving the existingstring[]overload for full backward compatibility.PkgExecOptionsandPkgCompressTypefrom the package entry point (surfaces inlib-es5/index.d.ts).Design
The options path normalizes into CLI-style argv via a small
optionsToArgv()helper and then feeds the existing minimist pipeline. Defaults (bytecode,nativeBuild,signature→true) and validation stay in one place — zero behavior drift between the two entry forms.PkgCompressTypeis derived from the existingCompressTypeenum viakeyof typeofso the public union can't drift from the internal representation.PkgExecOptionsis kept distinct from the internalPkgOptions(which models the"pkg"section ofpackage.json). They describe different layers — build content vs. driver knobs — and forcing shared ancestry would either leak internals (patches,dictionary,log) into the public surface or require a contrived shared base with only 2–3 fields.Changes
lib/types.tsPkgExecOptions+PkgCompressType(derived fromCompressType).lib/index.tsoptionsToArgv()+ overloadedexec(); re-export types.eslint.config.jsno-redeclare→@typescript-eslint/no-redeclare(core rule misfires on TS function overloads).docs-site/guide/api.mdtest/test-50-api-options/inputvalidation.Test plan
yarn buildcleanyarn lintcleantest-50-api-optionspasses on hosttest-50-api(existing programmatic-API test using argv form) still passescloses #242
🤖 Generated with Claude Code