Skip to content

Fix the return type of precompile - #2199

Open
mtnaskari wants to merge 1 commit into
handlebars-lang:masterfrom
mtnaskari:fix/precompile-return-type
Open

mtnaskari wants to merge 1 commit into
handlebars-lang:masterfrom
mtnaskari:fix/precompile-return-type

Conversation

@mtnaskari

Copy link
Copy Markdown

Summary

types/index.d.ts declares that precompile returns a TemplateSpecification, but at runtime it returns one of two other values:

  • Without srcName, it returns a string of JavaScript source.
  • With srcName, it returns { code, map }, where map is a serialized source map.

This pull request replaces the declaration with overloads that follow srcName:

options Return type
Omitted, or without srcName string
With srcName: string { code: string; map: string }
A PrecompileOptions value, where srcName may or may not be set string | { code: string; map: string }

The third overload goes slightly beyond the suggestion in the issue. Without it, a value typed as PrecompileOptions would either fail to compile or be reported as a string even when it holds a srcName.

Fixes #2198

Compatibility

This changes only the type declarations. Code that relies on the previous return type, for example by assigning the result to a TemplateSpecification variable, continues to compile because TemplateSpecification is an empty interface. For the same reason, passing the result of precompile directly to Handlebars.template() still compiles. Addressing that would mean giving TemplateSpecification a real shape, which I have left out of this change.

Tests

In types/__typetests__/handlebars.tst.ts, I replaced the test that recorded the old return type with tests for each of the three forms above.

Verification

Results on Node.js 22:

  • pnpm run lint:types passes on this branch, with 67 tests passing. The three new tests fail against the previous declaration.
  • oxfmt --check passes on the two changed files.
  • pnpm run build succeeds, and the built package returns the runtime values described above: string without srcName, and an object with the keys code and map with srcName.

I did not run the runtime test suites, as no runtime code changes. I am relying on CI for those.

precompile returns a string, or { code, map } when srcName is set, and never a TemplateSpecification.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The precompile overloads incorrectly guarantee a string map and an object result for empty srcName values, while rejecting valid calls that forward optional options.

No open issues 🎉

What changed in this PR

This PR updates Handlebars’ TypeScript declarations to better reflect precompile’s runtime return values, addressing #2198 without changing runtime code.

Changes:

  • Replaces the TemplateSpecification return type with overloads based on srcName, including a union for broadly typed options.
  • Updates type tests to cover plain source, source-map output, and uncertain options.
File Description
types/​index.d.ts Adds srcName-dependent precompile return-type overloads.
types/​__typetests__/​handlebars.tst.ts Replaces the old return-type assertion with tests for the three overload forms.

Review effort: Balanced

This branch has not been deployed

No deployments
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.

precompile is typed as returning TemplateSpecification, but returns a string (or { code, map } with srcName)

2 participants