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 v1 promises entry points and replaced them with explicit legacy shims that surface migration guidance and direct consumers to the v2 promise-only API.
  • Updated package exports and published files list to include the legacy shim entrypoints and their type artifacts.

• Tests

  • Added unit tests verifying legacy shim behavior, error messages, and package export/file 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: e1919b3f-7c2f-4184-9327-32b80e0dab07

📥 Commits

Reviewing files that changed from the base of the PR and between 4d23cde and 0e65931.

📒 Files selected for processing (3)

• callbacks.js
• promises.js
• test/unit/legacy-import-shims.test.js

---

Walkthrough

This PR replaces the deprecated v1 ably/promises and ably/callbacks subpath imports with error-throwing stubs. Both subpaths now load modules that immediately throw, instructing users to import from the v2 promise-only main entry point instead. Type declarations export never to prevent compile-time usage. Package exports and file lists are updated to publish these shims, and a test suite validates the behavior.

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 replace their previous implementations with modules that unconditionally throw an error on load, and type declarations that export a never sentinel to prevent compile-time usage. Migration guidance is embedded in error messages and JSDoc comments.
Package export map and files configuration package.json	The package exports map is extended with ./promises and ./callbacks subpath entries, each pointing to their respective .d.ts type file and .js runtime file. The files array is updated to include all four generated artifacts so they are published with the package.
Legacy import shim validation tests test/unit/legacy-import-shims.test.js	Test suite verifies that importing promises.js and callbacks.js throws errors with correct migration guidance, and validates that package.json correctly wires the legacy subpaths and includes shim files in the distribution package.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 I used to call the old paths fine,

now errors bloom where callbacks twine.
"Use v2's promises," the shims implore,
hop forward, friend, and fear no more.

🚥 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 title clearly and specifically describes the main change: adding shims that throw errors on attempts to import the legacy v1 entry points for ably/promises and ably/callbacks.
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.}