feat(ts): add TypeScript typings and type-check tests by UmbraCi · Pull Request #657 · hizzgdev/jsmind

UmbraCi · 2025-08-08T19:11:47Z

Summary

Introduce first-class TypeScript support for jsMind, publish official typings for core and plugins, and ensure typings are continuously validated in CI via a Jest-based type-check.

What’s in this PR

Publish .d.ts for core and plugins: es6/jsmind.d.ts, es6/jsmind.draggable-node.d.ts, es6/jsmind.screenshot.d.ts
Add Jest-based type-check (tsc noEmit) at tests/unit/typescript.types.test.js, validating tsconfig.json includes example/typescript-test.ts and es6/*.d.ts
Update package.json to expose types and exports.types entries
Add bilingual CHANGELOG.md (2025-08-09) documenting the TS support and testing
All tests pass locally (13 test suites, 95 tests)

Why

Provide official TypeScript types to improve DX (IntelliSense, static checks, safer refactors).
Ensure typings do not regress by adding compile-time validation in the existing test pipeline.

How

Publish .d.ts files under es6/ and wire them via package.json types and exports fields.
Add a Jest test that runs TypeScript compiler API in noEmit mode, equivalent to tsc --noEmit, so CI can fail fast on type regressions.
Include example/typescript-test.ts in tsconfig.json#includes to validate real-world API usage.

Backward Compatibility

No runtime API changes; ESM/CJS exports remain compatible.
This is an additive change that exposes typings to TypeScript users.

Testing

Run all tests:
- npm test → 13 suites, 95 tests passing locally.
Type-check:
- tests/unit/typescript.types.test.js invokes typescript compiler API to validate .d.ts and example usage.

Documentation

Added bilingual CHANGELOG.md (2025-08-09) noting TS support and tests.
No public API docs changed.

Checklist

Tests pass locally
Type-checking added and enforced in tests (tsc noEmit)
Exposed types via package.json and exports.types
Change log updated
Code formatted (npm run format) and consistent with repo style

Additional Notes

If maintainers prefer running type-check directly in CI without Jest, the logic can be moved to a dedicated script (tsc -p tsconfig.json --noEmit) and invoked in CI. Current approach keeps everything inside Jest for consistency with the repo’s test flow.

- Publish .d.ts for core and plugins: es6/jsmind.d.ts, es6/jsmind.draggable-node.d.ts, es6/jsmind.screenshot.d.ts - Add Jest-based type-check (tsc noEmit) at tests/unit/typescript.types.test.js, validating tsconfig.json includes example/typescript-test.ts and es6/*.d.ts - Update package.json to expose types and exports types entries - Add bilingual CHANGELOG.md (2025-08-09) documenting the TS support and testing - Remove temporary TS docs: TYPESCRIPT.md, TYPESCRIPT-INTEGRATION-SUMMARY.md, typescript-integration-progress.md - All tests pass locally (13 suites, 95 tests)

- Move .d.ts files from es6/ to types/ directory (es6/ is build output) - Update package.json types and exports.types to point to types/ - Update tsconfig.json include and add baseUrl/paths for package name resolution - Update examples to import from package name 'jsmind' instead of relative paths - Remove old .d.ts files from es6/ - All tests pass (13 suites, 95 tests including TypeScript type checking)

- 将错误的 'export default interface jsMind' 改为正确的 'interface jsMind' - 解决 VSCode 中显示 jsMind 有两处定义的问题 - 使用正确的接口合并语法进行类型扩展

UmbraCi · 2025-08-09T12:02:23Z

试了下单测是通过的，不过有一些之前你写的legacy的有些warning，我没有修改这些代码 @hizzgdev

hizzgdev

非常感谢，留了几个评论。麻烦看一下哈，有问题我们可以继续讨论。谢谢！

…omments\n\n- switch declare module target from './jsmind' to 'jsmind' for plugins\n- convert test descriptions and comments to English per review\n- slim tsconfig include to typings + typescript-test only\n- keep example/typescript-test.ts for type-check coverage (no runtime)

…nused examples\n\n- move example/typescript-test.ts -> tests/fixtures/typescript-test.ts\n- remove example/js/typescript-demo.js and example/typescript-example.ts (no HTML)\n- update tsconfig include to point to fixtures

UmbraCi · 2025-08-09T13:35:19Z

非常感谢，留了几个评论。麻烦看一下哈，有问题我们可以继续讨论。谢谢！

修改提交回复了，你看看

hizzgdev

代码里还有几处中文可能需要你帮忙处理一下，在文档和 example 中可以使用中文，在用于生产环境的代码里，我们还是尽量只使用 ASCII 字符以避免潜在的字符解析风险。谢谢。

…dd tsconfig.decls.json (emitDeclarationOnly, allowJs)\n- add npm scripts: gen:dts, gen:dts:check\n- initial generated declarations under types/generated/

… JSDoc-based generation

…e no Chinese in non-generated files

…n\n- add JSDoc to generate (string | Node) input and (Node | null) return in generated .d.ts\n- regen declarations via tsc allowJs

- Add comprehensive JSDoc annotations to all JavaScript source files - Add prepublishOnly script to automatically generate .d.ts files before npm publish - Regenerate TypeScript declarations with improved type information - Ensure type definitions are always up-to-date for releases

…re sources - Move declarations to types/generated and add central types/index.d.ts - Remove legacy types under types/ (jsmind.d.ts, draggable-node.d.ts, screenshot.d.ts) - Update tsconfig for declaration output; tweak strictness - Update package.json types entry and related scripts - Sync core modules and plugins with typings (dom/format/mind/node/shortcut/util/view_provider, draggable-node) - Update tests/fixtures/typescript-test.ts to reflect new types

… deps)

…ore; update changelog - Regenerate types under types/generated for core and plugins - Improve in-source JSDoc to enhance emitted d.ts (data_provider/format/graph/mind/node/option/plugin/shortcut_provider/view_provider) - Update CHANGELOG.md entry for 2025-08-10

hizzgdev

考虑一下能否从代码库中移除 .types 这个目录里的所有文件。

另外好奇问一下这个 PR 你是纯手写还是用了一些工具？能介绍一下你是如何短时间里修改了这么多行吗？谢谢。

UmbraCi · 2025-08-10T16:28:05Z

考虑一下能否从代码库中移除 .types 这个目录里的所有文件。

另外好奇问一下这个 PR 你是纯手写还是用了一些工具？能介绍一下你是如何短时间里修改了这么多行吗？谢谢。

你的意思是把.types加入git ignore，不然它们在源码中，交给publish命令打包构建出来是吗？我理解这些代码其实也不会影响到库的大小，还可以帮助开发者快速查看方法的ide提醒，后续你也可以考虑breakChange把库重构成TS版本；

考虑一下能否从代码库中移除 .types 这个目录里的所有文件。

另外好奇问一下这个 PR 你是纯手写还是用了一些工具？能介绍一下你是如何短时间里修改了这么多行吗？谢谢。

肝了两天，你可以看到提交记录半夜三点还在提交，当然用了GPT5辅助写jsDoc，行数多，但是.d.ts文件其实占了很多，实际上源码的修改不多，只是加jsDoc的注释，以及自动生成.d.ts的工程化配置 @hizzgdev ；

…blish; add npm files whitelist

…named exports Add output.name for draggable-node and screenshot UMD outputs Set exports: 'named' to avoid mixed default/named export warning No runtime/export path changes; only build stability

UmbraCi · 2025-08-10T17:03:36Z

考虑一下能否从代码库中移除 .types 这个目录里的所有文件。

另外好奇问一下这个 PR 你是纯手写还是用了一些工具？能介绍一下你是如何短时间里修改了这么多行吗？谢谢。

已经去掉了

…ypes/generated)

…o ignore file

hizzgdev

我理解这些代码其实也不会影响到库的大小，还可以帮助开发者快速查看方法的ide提醒

保留它的问题在于如果只修改了 .js 而没有 gen:tds 的话，发布后 repo 里的 t.ds 文件可能会跟 npm 上的文件不一致。

后续你也可以考虑breakChange把库重构成TS版本

说实话并没有此想法，后面如果有新版本的话，应该还是会 ES 版本，jsDoc 会写更详细一些。对于其它语言（方言）的支持就交给大家了。

肝了两天，你可以看到提交记录半夜三点还在提交

太感动了。后面我来搞吧，我可能会修改一些命名或者路径，并且把 types/index.d.ts 也从PR中移除，因为它也是生成出来的。谢谢！

UmbraCi · 2025-08-10T17:49:49Z

其它语言（方言）

其它语言（方言）是什么意思

UmbraCi · 2025-08-10T17:51:43Z

并且把 types/index.d.ts 也从PR中移除

入口文件应该还是需要的，可以从PR中移除，但是需要最后生成出来，因为package.json中的type入口文件需要指定，不然使用库的时候import，编辑器和TS不知道关联的type文件是什么

…written index.d.ts Add src/types-index.ts and emit types/generated/types-index.d.ts via tsconfig.decls.json; point package.json exports.types and top-level types to the generated file; remove types/index.d.ts from VCS

hizzgdev · 2025-08-10T18:01:37Z

其它语言（方言）是什么意思

这么说可能不太准确，我把 jsMind 的其它语言版本（如 ts）看作是 jsMind 的方言版本。 😂

UmbraCi · 2025-08-10T18:02:48Z

并且把 types/index.d.ts 也从PR中移除

我又提交了一版本，将手写的 types/index.d.ts 改为由 src/types-index.ts 自动生成 types/generated/types-index.d.ts，并更新了入口与映射。
这样做一致性更好：所有 .d.ts 都来源于 src 的 JSDoc/TS 源，避免手写入口漂移与维护成本。

UmbraCi · 2025-08-11T07:34:42Z

@hizzgdev 这个PR大概什么时候能发布

UmbraCi · 2025-08-11T14:38:37Z

@hizzgdev 是不是因为版本号没改，所以没有触发新的打包

hizzgdev · 2025-08-11T14:48:54Z

release才会触发发布，晚点儿我操作一下。

UmbraCi added 4 commits August 9, 2025 03:05

fix: 修复 jsmind.screenshot.d.ts 中的模块扩展语法错误

7a93628

- 将错误的 'export default interface jsMind' 改为正确的 'interface jsMind' - 解决 VSCode 中显示 jsMind 有两处定义的问题 - 使用正确的接口合并语法进行类型扩展

fix: run prettier lint

f1a789c

hizzgdev reviewed Aug 9, 2025

View reviewed changes

Comment thread example/js/typescript-demo.js Outdated

Comment thread example/typescript-test.ts Outdated

Comment thread tests/unit/typescript.types.test.js Outdated

Comment thread types/jsmind.d.ts Outdated

UmbraCi added 3 commits August 9, 2025 21:19

test(typings): update test title to fixtures path after file move

f56b662

hizzgdev reviewed Aug 9, 2025

View reviewed changes

Comment thread tests/fixtures/typescript-test.ts Outdated

Comment thread types/jsmind.d.ts Outdated

Comment thread types/jsmind.d.ts Outdated

UmbraCi added 3 commits August 10, 2025 10:07

build(types): add JSDoc-based .d.ts generation via tsc allowJs\n\n- a…

5768f9d

…dd tsconfig.decls.json (emitDeclarationOnly, allowJs)\n- add npm scripts: gen:dts, gen:dts:check\n- initial generated declarations under types/generated/

docs(typings): convert comments to English and exclude js-legacy from…

70f1085

… JSDoc-based generation

chore: 安装自动生成.d.ts依赖

0854a0d

hizzgdev reviewed Aug 10, 2025

View reviewed changes

Comment thread types/generated/jsmind.d.ts Outdated

UmbraCi added 7 commits August 10, 2025 10:48

chore: replace remaining Chinese comment in typings fixture and ensur…

9a9372c

…e no Chinese in non-generated files

docs(jsdoc): annotate jsMind.find_node_before param and return types\…

fd1777d

…n\n- add JSDoc to generate (string | Node) input and (Node | null) return in generated .d.ts\n- regen declarations via tsc allowJs

docs(changelog): document PR changes (typings migration, CI, scripts,…

a52076a

… deps)

chore: format code

ad21b4a

hizzgdev reviewed Aug 10, 2025

View reviewed changes

Comment thread package.json Outdated

UmbraCi requested a review from hizzgdev August 10, 2025 16:31

UmbraCi added 2 commits August 11, 2025 00:52

chore(types): ignore generated d.ts; auto-generate on test/prepare/pu…

b867eaf

…blish; add npm files whitelist

chore(build): fix UMD plugin bundles by adding output.name and using …

121c28c

…named exports Add output.name for draggable-node and screenshot UMD outputs Set exports: 'named' to avoid mixed default/named export warning No runtime/export path changes; only build stability

UmbraCi added 2 commits August 11, 2025 01:12

chore: format package.json

f1dbc0c

chore(ci): exclude generated declaration files from Prettier check (t…

fc4c4a7

…ypes/generated)

chore(ci): fix Prettier ignore paths for CI by using paths relative t…

6e57fb6

…o ignore file

hizzgdev approved these changes Aug 10, 2025

View reviewed changes

Comment thread package.json

chore: format types-index.ts

d082861

hizzgdev merged commit b6784d3 into hizzgdev:master Aug 11, 2025
3 checks passed

Uh oh!

Conversation

UmbraCi commented Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What’s in this PR

Why

How

Backward Compatibility

Testing

Documentation

Checklist

Additional Notes

Uh oh!

UmbraCi commented Aug 9, 2025

Uh oh!

hizzgdev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

UmbraCi commented Aug 9, 2025

Uh oh!

hizzgdev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hizzgdev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

UmbraCi commented Aug 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

UmbraCi commented Aug 10, 2025

Uh oh!

hizzgdev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

UmbraCi commented Aug 10, 2025

Uh oh!

UmbraCi commented Aug 10, 2025

Uh oh!

hizzgdev commented Aug 10, 2025

Uh oh!

UmbraCi commented Aug 10, 2025

Uh oh!

UmbraCi commented Aug 11, 2025

Uh oh!

Uh oh!

UmbraCi commented Aug 11, 2025

Uh oh!

hizzgdev commented Aug 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

UmbraCi commented Aug 8, 2025 •

edited

Loading

UmbraCi commented Aug 10, 2025 •

edited

Loading