Skip to content

[types] Use @import instead of @typedef - #686

Merged
MysteryBlokHed merged 6 commits into
mainfrom
types/use-import-jsdoc
Oct 23, 2025
Merged

MysteryBlokHed merged 6 commits into
mainfrom
types/use-import-jsdoc

Conversation

@MysteryBlokHed

@MysteryBlokHed MysteryBlokHed commented Oct 19, 2025 •

Copy link
Copy Markdown
Member

Closes #685

There are some files for which the @typedefs' re-exporting behavior was deliberate (e.g. everything in index-fn), while for most cases it was just a way of mimicking an import. For any files where the re-export behaviour was deliberate, the @typedefs have been left alone.

To allow us to use the `@import` keyword. Also bumps TypeDoc to a
version that supports TypeScript v5.5.
@netlify

netlify Bot commented Oct 19, 2025 •

Copy link
Copy Markdown

βœ… Deploy Preview for colorjs ready!

Name Link
πŸ”¨ Latest commit 9c66361
πŸ” Latest deploy log https://app.netlify.com/projects/colorjs/deploys/68fa3bc090456500077bfcf7
😎 Deploy Preview https://deploy-preview-686--colorjs.netlify.app
πŸ“± Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@MysteryBlokHed
MysteryBlokHed force-pushed the types/use-import-jsdoc branch 2 times, most recently from bbc9812 to 7d93dd3 Compare October 22, 2025 21:42
As of now, the latest TypeScript version has no export equivalent of
`@import`, so the only way to expose a type from another file seems to
be through `@typedef`s.
Mostly adding/removing whitespace that Prettier didn't change.
@MysteryBlokHed

Copy link
Copy Markdown
Member Author

The majority of the re-exported types here are types that would make more sense to define directly within the re-exporting files, rather than in types.d.ts. At some point, it might be worth going through and migrating any such type definitions from the types.d.ts file to @typedef directives directly within the source file. That way we'll both reduce duplicated exports, and make sure that the types are defined within the file to which they're actually relevant.

For example: any functions that take complex options as parameters currently have their options interfaces defined in types.d.ts and then re-export those, when it would probably make more sense to define them directly within the source file.

Semantically the same, but matches the typical way of importing ESM
defaults.
@MysteryBlokHed
MysteryBlokHed marked this pull request as ready for review October 22, 2025 21:55
@MysteryBlokHed
MysteryBlokHed requested a review from lloydk October 22, 2025 21:55

@lloydk lloydk left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

LGTM with some minor nitpicks.

I did notice that these types are re-exported but not exported in index.d.ts or index-fn.ts:

  • Algorithms
  • Methods
  • ArgumentMeta
  • ParseFunctionReturn
  • OKCoeff
  • ToGamutOptions
  • TryColorOptions

I think those could be addressed in a separate PR as I think there are additional types in types.d.ts that should be exported at the top level.

Comment thread src/clone.js Resolved
Comment thread src/deltas.js Resolved
Comment thread src/to.js Resolved
Co-Authored-By: Lloyd Kupchanko <lloyd@lloydk.ca>

@lloydk lloydk left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

LGTM

@MysteryBlokHed

Copy link
Copy Markdown
Member Author

@LeaVerou requesting review in case you want to look at the dependency version changes in package.json

@MysteryBlokHed
MysteryBlokHed merged commit 1c457dd into main Oct 23, 2025
1 check passed
@MysteryBlokHed
MysteryBlokHed deleted the types/use-import-jsdoc branch October 23, 2025 18:21
@AviVahl

AviVahl commented Nov 6, 2025 •

Copy link
Copy Markdown

This PR completely broke the generated .d.ts files. See issue: #692
EDIT: after further investigation it might be the publishing process. not the PR itself.

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.

Use TypeScript 5.5's @import for JSDoc type imports

4 participants