Skip to content

Add web-compatible parsePackageExports API - #20

Draft
privatenumber wants to merge 68 commits into
developfrom
parse-package-exports
Draft

Add web-compatible parsePackageExports API#20
privatenumber wants to merge 68 commits into
developfrom
parse-package-exports

Conversation

@privatenumber

Copy link
Copy Markdown
Owner

Summary

Adds parsePackageExports() function for parsing package.json#exports without filesystem dependencies, enabling web-based playground/visualization tools.

  • New API: parsePackageExports(exports) returns array of ParsedExport objects
  • Web-compatible: Zero filesystem dependencies
  • Wildcard support: Splits patterns into arrays for dynamic path generation
  • Null tracking: Tracks blocked exports (target: null) for playground blocking logic
  • Type-safe: Exports ParsedExport type for TypeScript consumers

Key Features

  1. Parses all export types: string, conditions object, fallback arrays, wildcards
  2. Wildcard splitting: './dist/*'['./dist/', ''] for easy .join(match)
  3. Validation: Enforces Node.js constraint (max 1 wildcard per subpath)
  4. Null blocking: Returns target: null entries to enable blocking logic in playgrounds

Use Case

Enables building a package.json#exports playground where users can:

  • Paste their exports config
  • See all possible entry points
  • Visualize wildcard patterns with synthetic examples
  • Understand which paths are blocked

Test Plan

  • 13 new tests covering all features (string, null, wildcards, arrays, validation, etc.)
  • All 93 tests pass
  • Type definitions generated correctly
  • Build succeeds

- Update ParsedExport type to allow target: null
- Modify traverseExports to create entries for null targets instead of filtering them out
- Add test for null blocking wildcard patterns
- Update existing tests to expect null entries in output

This allows playground/visualization tools to:
1. Know which patterns are blocked
2. Apply blocking logic (more specific blocks override broader wildcards)
3. Match the behavior of analyzeExportsWithFiles for eventual internal use
Refactored the internal implementation of getPackageEntryPoints and
getPackageEntryPointsSync to use the new parsePackageExports function.

Created analyze-exports-with-files.ts that:
- Calls parsePackageExports to get a flat list of export entries
- Separates wildcard-generated entries from static entries
- Validates file existence for all target paths
- Applies proper precedence: static entries override wildcards
- Handles null blocking for both static and wildcard patterns
- Supports wildcard-to-static path mapping with '_' substitution
- Handles static subpaths with wildcard targets (e.g., '.': './file-*.js')

Key features:
- First-wins within same type (wildcard vs static)
- Static always wins over wildcard for same subpath+conditions
- Null targets create blocks that filter out matching entries
- Files with literal '*' in name are handled correctly

All 93 tests passing.
Reduced from 128 to 89 lines (30% reduction) by:
- Combining null and string handling (same logic)
- Removing duplicate wildcard validation
- Using cleaner ternary chains for target assignment
- Inlining simple conditions

All 93 tests passing.
Changed analyzeExportsWithFiles to accept ParsedExport[] as first
argument instead of PackageJson.Exports.

This makes the separation cleaner:
- parsePackageExports: parsing logic (web-compatible)
- analyzeExportsWithFiles: file validation logic
- getPackageEntryPoints: orchestrates both

All 93 tests passing.
@privatenumber
privatenumber marked this pull request as draft October 15, 2025 11:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant