Feature proposal: add notation to treat parent as the "package" (for "non-encapsulating" directories)

[honey32]

Sometimes my project has a structure like below:

• 📁 app/todo-list/
  • 📁 _internal/
    • 🗎 item-type.ts ... package private export type ItemType = "routine" | "one-shot"
    • 🗎 index.ts ... package private export { ItemType } from "./item-type"
  • 🗎 page.tsx ... import { ItemType } from "./_internal

If I want to keep item-type.ts under _internal and simultaneously can only be available in app/todo-list directory, index.ts barrel-file is necessary.

But, it's なんか嫌 for me. To deal with RSC's magic on bundling, barrel files seem confusing on illustrating in mind an import graph separated by server / client boundary. (actual case: https://qiita.com/kay-adamof/items/8d7324810dd1b051d373)

I know the best way is to prevent using _internal/ directory, which is far from encapsulation.

• 📁 app/todo-list/
  • 🗎 _item-type.ts ... package private export type ItemType = "routine" | "one-shot"
  • 🗎 page.tsx ... import { ItemType } from "./_item-type

But, there could be another way.

• 📁 app/todo-list/
  • 📁 _internal/
    • 🗎 item-type.ts ... package private (for app/todo-list/) export type ItemType = "routine" | "one-shot"
  • 🗎 page.tsx ... import { ItemType } from "./_internal/item-type

0. @package .. for each exports

by, for example, annotating ItemType like:

// app/todo-list/_internal/item-type.ts
/**
 * @package ..
 */ 
export type ItemType = "routine" | "one-shot"

where .. indicates that the parent directory is the actual "package", the folder as a boundary of encapsulation.

[uhyo]

Thanks for suggestion! Yes, barrel files have been the suggested way to solve this kind of problem. However, I see how it's なんか嫌 and I think that we need to find another way.

That said, actually I don't quite like the @package .. solution because you need to repeat this for all exports and also it can't automtically follow file moves.

For now, I've come up with a different approach. How about a config to specify which folders are (or are not) treated as a ″package”?

In your case, we could specify that a directory named _internal isn't treated as a pakage app/todo-list/_internal/*.ts would belong to a package for app-todo-list.

[honey32]

I like this plugin's self-contained design, so I didn't like much config.

However, you made me realize "config" way is very good.

I have come up with allow-list-like config idea, which looks consistent with default behavior and far better than my previous suggestion.

1. Allow-list-like Config

• by default, all the directories are treated as "package"
• if list contains app/todo-list, all the file under that directory treat app/todo-list as "package"
  • e.g. app/todo-list/_internal/item-type.ts treats app/todo-list as its "package", not ./_internal
• maybe, nesting is also available
  • if list contains app/todo-list and app/todo-list/task-form, app/todo-list/task-form is also a "package".
    • e.g. app/todo-list/_internal/item-type.ts STILL treat app/todo-list as "package", not ./_internal
    • e.g. app/todo-list/task-form/_internal/task-form-value-schema.ts treat app/todo-list/task-form as its "package", neither app/todo-list nor app/todo-list/task-form/_internal/

[honey32]

or could be another "special file" approach like Scala's package.scala convention. (package.scala is for )

https://docs.scala-lang.org/ja/tour/package-objects.html

2-1. original special file

// app/todo-list/import-access.ts
export {}

or

empty app/todo-list/.import-access-package file

2-2. index.ts with marker

This is close to package.scala

// app/todo-list/index.ts
/**
 * (some sort of marker here to indicate `todo-list` is a "package")
 */

[uhyo]

Yeah indeed I do want this plugin to be self-contained. The design that lets you mark individual exports with @package, rather than using sophisticated config, is at the core of this plugin. We need to keep this design.

So I'm interested in a “special file” approach, but I need more input (and also time) to land on the best solution.

[uhyo]

@honey32 Hi 👋 sorry for keeping you waiting.

Now I'm leaning towards the config-based approach (let's call it packageDirectory here):

• By default, all directories are treaed as package (packageDirectory: ["**"]).
• You can confiure so that a directory named _internal is not treated as a package (packageDirectory: ["**", "!**/_internal"]).
• Or you could configure so that only directories under a packages directory are packages (packageDirectory: ["packages/*"]).

I'd recommend using those as a ″meta-config”: you'd avoid listing up concrete directory names ( ❌ packageDirectory: ["packages/foo", "packages/bar", ...]), but you should declare path-based “rules” using the new option.

[honey32]

A little different from previous, but maybe it seems to have less unexpected influence for files deep below the specified directory.

LGTM!