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.

Inizia esaminando il comportamento proposto di JSDoc @package e la documentazione JSDoc collegata. Chiarisci se la visibilità del package debba influire solo sul completamento automatico o debba anche produrre errori di compilazione, e definisci come debbano comportarsi i confini delle directory e gli import. Il lavoro è considerato completato quando la semantica e l'ambito di implementazione della funzionalità sono definiti abbastanza da poter identificare il lavoro rilevante del compilatore e i casi di validazione.