DX-1205: throw on legacy v1 ably/promises and ably/callbacks imports

[umair-ably]

Summary

• Adds ./promises and ./callbacks subpath exports to package.json, each pointing at a tiny .js shim that throws on module load. The throw is a structured Error whose message names the dropped v1 entry point and whose hint directs the user at the v2 import and the migration guide.
• Closes the v1→v2 self-heal gap on the import surface, complementing DX-1204 which closed it on the call surface (v1 trailing-callback shapes). The message (what failed) / hint (how to fix) split matches the convention DX-1204 / DX-1209 use for ErrorInfo throws elsewhere in the SDK.
• Today these imports fail with Node's generic ERR_PACKAGE_PATH_NOT_EXPORTED, which gives an agent or migrating user no signal that the path was renamed. The shim turns that into an actionable error naming the new entry point.

Background — were these real?

Yes. Both were genuine v1 entry points at the package root, removed as separate commits during v2 prep:

• ably/callbacks — callbacks.js removed in 2a2ed49e ("Remove the callbacks public API", Jun 2023). The v1 file re-exported ./build/ably-node.
• ably/promises — promises.js removed in 6cf248fb ("Remove promises.js / .d.ts", Jun 2023). The v1 file wrapped the constructors to set options.internal.promises = true.

docs/migration-guides/v2/lib.md:68-70 already documents both as v1 spellings users would have written.

Implementation notes

• Single .js file per subpath: works for both require and import because the package is not "type": "module". Module-evaluation throw propagates synchronously out of both.
• Shim files live at the package root (promises.js, callbacks.js) alongside their .d.ts siblings — hand-written, kept separate from build/ so they aren't wiped by grunt build. Added to files[] individually so they ship in the npm package.
• The thrown value is a plain Error with err.hint stamped on, rather than an ErrorInfo. Pulling in ErrorInfo would mean requireing the built bundle just to throw out of an alias path, defeating the point of a top-level shim. The err.message + err.hint shape is what LLM-eval tooling already inspects everywhere else, so the structural alignment with ErrorInfo-based throws is preserved without the runtime cost.
• The matching .d.ts files (promises.d.ts, callbacks.d.ts) declare each subpath as @deprecated never so TypeScript users get a strikethrough at the import site and an IDE-rendered migration message before the runtime throw ever fires.
• URL points at the in-repo migration guide (https://github.com/ably/ably-js/blob/main/docs/migration-guides/v2/lib.md), matching the convention introduced by DX-1204 in src/common/lib/util/utils.ts:293.

Base branch

⚠️ This PR targets DX-1204/v1-callback-overloads, not main. Merge DX-1204 first; this branch will then auto-retarget to main or can be rebased.

Test plan

• npx mocha test/unit/legacy-import-shims.test.js → 4 passing:
  • ably/promises shim throws naming the v1 entry point, with a hint pointing at the migration guide
  • ably/callbacks shim throws naming the v1 callback API, with a hint pointing at the migration guide
  • package.json exports map wires the legacy subpaths to the shim files and their types
  • files[] ships the legacy shim .js / .d.ts files in the published package
• Smoke-test the published exports resolution (e.g. npm pack + require('ably/promises') from a temp project) — optional, the unit-level wiring test already covers the mapping.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores

  • Removed legacy v1 callback and promises entry points and added explicit legacy shims that throw at import with migration guidance directing consumers to the v2 promise-only API; type declarations for those shims are marked as unavailable.
  • Updated package exports and published files list to expose the legacy shim entrypoints and their type artifacts.

• Tests

  • Added unit tests verifying shim behavior, error messages, and package export/files configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c9823aa1-6d98-497d-a054-fd849bed0d87

📥 Commits

Reviewing files that changed from the base of the PR and between 1ff768b and 924f85a.

📒 Files selected for processing (6)

• callbacks.d.ts
• callbacks.js
• package.json
• promises.d.ts
• promises.js
• test/unit/legacy-import-shims.test.js

✅ Files skipped from review due to trivial changes (1)

• callbacks.js

🚧 Files skipped from review as they are similar to previous changes (5)

• promises.d.ts
• promises.js
• callbacks.d.ts
• package.json
• test/unit/legacy-import-shims.test.js

---

Walkthrough

Replaces v1 subpath imports ably/promises and ably/callbacks with modules that throw on load, provides never-typed .d.ts placeholders, exposes the shims via package exports and files, and adds tests validating the shims and package metadata.

Changes

Legacy Entry Point Deprecation

Layer / File(s)	Summary
Runtime and type error shims for promises and callbacks callbacks.d.ts, callbacks.js, promises.d.ts, promises.js	Both promises and callbacks subpaths now export never-typed declarations and runtime modules that unconditionally throw an Error on import; errors and JSDoc include v2 migration guidance.
Package export map and files configuration package.json	Adds exports["./promises"] and exports["./callbacks"] pointing to their .d.ts and .js shims; expands files to include the new artifacts for publishing.
Legacy import shim validation tests test/unit/legacy-import-shims.test.js	Adds tests that import the shim modules and assert they throw migration-guidance errors, and that package.json exports and files contain the shim entries.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• ably/ably-js#2226: Related v1→v2 migration handling changes that add migration hints/errors around callback-style APIs.

Suggested reviewers

• AndyTWF

Poem

🐇 I hopped the old paths to see,

shims now bloom where callbacks used to be.
"Use v2's promises," the errors sing,
onward I hop — a migration spring.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and accurately describes the main change: adding error-throwing shims for legacy v1 entry points ably/promises and ably/callbacks to improve the developer experience when users attempt to import from these removed subpaths.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DX-1205/legacy-import-shims

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[umair-ably]

I expect the delta to be much smaller in an agent behaving differently with and without this hint, however, it is low hanging fruit and more beneficial for weaker models as testing in other PRs is highlighting e.g. #2233