fix(ts-sdk): emit v0 root-import deprecation via process.emitWarning

[sushaan-k]

Hi! Picking up #3915.

Importing @hatchet-dev/typescript-sdk from the root specifier currently prints seven red console.warn lines on every process start, because index.ts re-exports both ./workflow and ./step and each of those fires raw console.warn calls at module evaluation. They:

• can't be suppressed via Node's standard flags (--no-deprecation, --no-warnings, --no-warnings=DeprecationWarning),
• have no stable code, so process.on('warning', ...) handlers can't match on them,
• duplicate themselves once for each of the two submodules.

Change

Added a small helper emitV0RemovedWarning(submodule, detail?) in sdks/typescript/src/util/v0-deprecation-warning.ts. It:

1. Dedupes per submodule via a module-scoped Set.
2. Routes through process.emitWarning(..., { type: 'DeprecationWarning', code: 'HATCHET_V0_REMOVED' }) when available, so the standard Node flags work and process.on('warning', e => e.code === 'HATCHET_V0_REMOVED') is a stable filter.
3. Checks process.throwDeprecation (set by --throw-deprecation or directly) up front and routes to console.warn instead when true. Without this guard the root import would abort for transitive v0 consumers, because emitWarning queues throw warning on the next tick after it returns — a try/catch around the call cannot catch it. Same fallback runs on runtimes that don't expose process.emitWarning at all.

A try/catch around the emit remains as defense-in-depth for non-Node hosts where a polyfilled emitWarning could throw synchronously.

workflow.ts and step.ts each replace their four-line console.warn block with a single call to the helper. The migration nag is still visible by default.

Testing

cd sdks/typescript
pnpm exec jest src/util/v0-deprecation-warning.test.ts   # 7/7 pass
pnpm lint:check                                          # clean
pnpm exec tsc                                            # clean

Tests cover:

• emit shape and the HATCHET_V0_REMOVED code,
• optional detail pass-through,
• per-submodule dedupe across repeated calls,
• separate warnings for distinct submodules,
• process.throwDeprecation = true → bypasses emitWarning, goes to console.warn, no crash,
• synchronous-throw fallback for non-Node hosts,
• console.warn fallback when process.emitWarning is unavailable.

Also smoke-tested against real Node 24 with each of the relevant flags. Output for each invocation, exit code 0 in every case:

=== default ===
(node:46692) [HATCHET_V0_REMOVED] DeprecationWarning: The v0 SDK, including the workflow module, has been deprecated and was removed in v1.14.0. Please migrate to the v1 SDK: https://docs.hatchet.run/home/v1-sdk-improvements
warning fired: code=HATCHET_V0_REMOVED type=DeprecationWarning

=== --no-deprecation ===
(silent)

=== --no-warnings=DeprecationWarning ===
warning fired: code=HATCHET_V0_REMOVED type=DeprecationWarning
(Node suppresses its own print but process.on('warning') still fires — documented Node behaviour)

=== --throw-deprecation ===
[HATCHET_V0_REMOVED] The v0 SDK, including the workflow module, has been deprecated and was removed in v1.14.0. Please migrate to the v1 SDK: https://docs.hatchet.run/home/v1-sdk-improvements
[HATCHET_V0_REMOVED] The v0 SDK, including the step module, has been deprecated and was removed in v1.14.0. Please migrate to the v1 SDK: https://docs.hatchet.run/home/v1-sdk-improvements
import completed without crash

A note on shape

Matched the HATCHET_V0_REMOVED code the issue suggested to keep review easy. Happy to split into per-submodule codes (HATCHET_V0_WORKFLOW_REMOVED, HATCHET_V0_STEP_REMOVED) if you'd prefer finer-grained filtering.

I considered the existing emitDeprecationNotice helper in v1/client/worker/deprecated/deprecation.ts, but it takes a Logger instance and the v0 warnings fire at module-evaluation time with no logger context. The issue also explicitly called for process.emitWarning, so a small dedicated helper felt cleaner than threading a logger into module scope.

Closes #3915

[vercel]

@sushaan-k is attempting to deploy a commit to the Hatchet Team on Vercel.

A member of the Team first needs to authorize it.

[Copilot]

Pull request overview

Updates the TypeScript SDK’s root-import v0 deprecation messaging to use Node’s standard warning mechanism (process.emitWarning) so consumers can suppress/dedupe/filter warnings using built-in Node flags and warning handlers.

Changes:

• Introduces a emitV0RemovedWarning(submodule, detail?) helper that emits DeprecationWarning with code HATCHET_V0_REMOVED (with a console.warn fallback).
• Replaces the module-evaluation console.warn blocks in workflow.ts and step.ts with a single helper call each.
• Adds unit tests covering the warning shape, code, per-submodule dedupe, and fallback behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
sdks/typescript/src/workflow.ts	Replaces v0 root-import console.warn banner with a single structured deprecation warning emission.
sdks/typescript/src/step.ts	Replaces v0 root-import console.warn banner with a single structured deprecation warning emission.
sdks/typescript/src/util/v0-deprecation-warning.ts	Adds centralized warning emission + per-submodule dedupe and fallback logic.
sdks/typescript/src/util/v0-deprecation-warning.test.ts	Adds Jest coverage for emission, code, dedupe, and fallback paths.

[BloggerBust]

@sushaan-k I agree this is technically deep-importable because the package has no exports map, but I do not see it as a practical blocker since it is not re-exported from the root package and the function is only a harmless test reset hook.

Non-blocking suggestion: adding @internal to the JSDoc would make that intent clearer in the generated declarations.

[BloggerBust]

non-blocking suggestion: I don’t think this source comment needs to enumerate the exact Node CLI flags. Since those are Node-owned behavior and can vary by version, I would slightly prefer keeping the source comment focused on the reason for process.emitWarning: it gives consumers structured warning metadata and a stable HATCHET_V0_REMOVED code that standard Node warning controls can filter or suppress. That would also avoid teaching the undocumented --no-warnings=DeprecationWarning form in source.

[BloggerBust]

@sushaan-k thank you for the PR, this looks good to me. I validated the warning behavior locally and this addresses #3915:

• root import now emits structured DeprecationWarnings with the stable HATCHET_V0_REMOVED code instead of the previous raw console.warn banner lines
• the warnings are deduplicated per submodule

I also confirmed the warnings can be suppressed through standard Node warning mechanisms such as --no-deprecation and --no-warnings; on Node versions that support warning-code suppression, --disable-warning=HATCHET_V0_REMOVED works as expected.

I left two non-blocking suggestions to improve JSDoc and to mark the test reset helper as internal, but neither blocks approval from my perspective.

[BloggerBust]

@sushaan-k one release housekeeping request before merge: could you bump the TypeScript SDK package version in sdks/typescript/package.json to 1.23.0 and add a changelog entry for the v0 root-import deprecation warning fix in sdks/typescript/CHANGELOG.md?

PR #3932 can add its own separate changelog entry under the same version.