Comfy-Org / Comfy-Org/ComfyUI_frontend
comfyui-frontend-types: post-#12231 publish will silently drop LiteGraph.ON_EVENT from the type surface
- Dominant language
- TypeScript
- Stars
- 2k
- Forks
- 699
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 490
Description
After #12231 lands and is released, the next publish of `@comfyorg/comfyui-frontend-types` will mutate the type surface in two non-obvious ways. Filing this so the post-release sweep doesn't miss it.
## What changes in `dist/index.d.ts`
The package is built by `pnpm build:types` (`vite.types.config.mts` + `vite-plugin-dts` with `rollupTypes: true`) and published via `.github/workflows/release-npm-types.yaml`. Today (`v1.45.6`):
```ts
export enum LGraphEventMode {
ALWAYS = 0,
ON_EVENT = 1, // ← will rename
NEVER = 2,
ON_TRIGGER = 3,
BYPASS = 4
}
export class LiteGraphGlobal {
...
ON_EVENT: LGraphEventMode; // ← will disappear
ON_TRIGGER: LGraphEventMode;
...
}
```
After #12231:
1. `LGraphEventMode.ON_EVENT` is renamed to `_UNUSED_1` (numeric slot `1` preserved).
2. `LiteGraph.ON_EVENT` becomes an `Object.defineProperty` getter with default `enumerable: false`. `vite-plugin-dts` rollup will drop it from the published class declaration.
## Why it matters for external `.d.ts` consumers
Custom node packs that vendor their own `litegraph.d.ts` (audit found `crystian/ComfyUI-Crystools/web/comfy/typings/litegraph.d.ts:764-776` and others) declare `mode?:` as a literal union:
```ts
mode?:
| typeof LiteGraph.ON_EVENT
| typeof LiteGraph.ON_TRIGGER
| typeof LiteGraph.NEVER
| typeof LiteGraph.ALWAYS
| 4; // Comfy App "Bypass"
```
If they upgrade their `@comfyorg/comfyui-frontend-types` peer-dep after the post-#12231 publish, `typeof LiteGraph.ON_EVENT` resolves to `any` (missing field) and the union silently widens. Any extension code that `import { LiteGraph } from '@comfyorg/comfyui-frontend-types'` and reads `LiteGraph.ON_EVENT` at the type level will break the same way.
## Action items (after #12231 merges and a release tag exists)
- [ ] Tag the post-#12231 publish as a **patch bump** (per the deprecate-then-delete cycle in #12225 — symbol still present at runtime via the warning getter, just removed from the static type surface).
- [ ] Add a one-line note to the release CHANGELOG: "`LiteGraph.ON_EVENT` is now a deprecation getter; the static field is no longer in the type declaration. Use `LGraphEventMode.NEVER` to mute a node. Numeric slot `1` is preserved."
- [ ] Verify the published `index.d.ts` matches expectations by running `pnpm build:types` locally on the merge SHA, then `grep -n "ON_EVENT" dist/index.d.ts` — should show `_UNUSED_1 = 1` in the enum and **no** `ON_EVENT:` field on `LiteGraphGlobal`.
- [ ] Consider re-adding `ON_EVENT: LGraphEventMode;` to the `LiteGraphGlobal` class declaration via a `// @ts-ignore`-style ambient comment **only if** real-world breakage surfaces. The deprecation getter still returns `1` at runtime, so silent type-level removal is the lesser evil during the deprecation window — but a one-line declaration with `/** @deprecated ... */` would preserve type-level compatibility for one more release.
- [ ] Release N+1 (per #12225): drop the deprecation getter, drop `_UNUSED_1`, and confirm the type surface has fully converged.
## Out of scope
This issue does not change any source files — it's a tracking note for the publish-time consequences of #12231. The actual rename + getter live in #12231.
## Recon trail
- Workspace audit: `LG-FU-6-RECON` (cross-repo workspace `ecs-vue-hoisted-client-state-hook-api`).
- Touch-points database hits: `docs/architecture/extension-api-v2/touch-points-database.yaml:12326` (1 vendored `.d.ts` union in `crystian/ComfyUI-Crystools`).
- Published artifact inspected: `npm pack @comfyorg/comfyui-frontend-types@1.45.6` → `package/index.d.ts` lines 5612, 5614, 7063, 7065.
cc @christian-byrne
┆Issue is synchronized with this [Notion page](https://www.notion.so/Issue-12236-comfyui-frontend-types-post-12231-publish-will-silently-drop-LiteGraph-ON_EVENT-fro-35f6d73d36508155bc0dfe59f13b4520) by [Unito](https://www.unito.io)
Contributor guide
Assessment
This issue has not been assessed yet.