Suggestion: making exports visible only to the same directory with JSDoc @package tag

Search Terms

JSDoc package directory package-private

Suggestion

If an export is annotated with @package, that export is visible only to files in the same directory.

I can think of two levels of @package support: a soft one would remove these exports from auto completion if not visible. A hard one would also emit a compile error.

See also: Use JSDoc: @package

Use Cases

We organize source code using directory structure. We often make exports that are meant to be referenced only by sibling modules. However, JavaScript/TypeScript has no idea of scoping based on file system, so we are free to import such "local" exports everywhere. TypeScript could help us do file system-based scoping.

Examples

// ----- src/foo/bar.ts
/**
 * @package
 */
export fooBar = "fooBar";

// ----- src/foo/index.ts
// Can import fooBar from "./bar"
import { fooBar } from "./bar";

// ----- index.ts
// CANNOT import fooBar from "./foo/bar"
import { fooBar } from "./foo/bar";

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Start by reviewing the proposed JSDoc @package behavior and the linked JSDoc documentation. Clarify whether package visibility should affect only auto-completion or also produce compile errors, and define how directory boundaries and imports should behave. Done means the feature's semantics and implementation scope are settled well enough to identify the relevant compiler work and validation cases.