Module organization in `lib/utils`?

[RunDevelopment]

So I have a question about code organization in lib/utils: how does it work/what is the structure behind it?

I wondered this for a long time. From my perspective, it just looks like a mess. Of course, I never understood the file layout, so I very much contributed to that mess.

What confuses me the most are index.ts files with function/class/type definitions. index.ts files in my projects typically only re-export other modules to define an API. I pretty much never put definitions in index.ts files, because e.g. a/b.ts cannot import a function from a/index.ts (cyclic import).

---

As an example: I want to add new util function:

function assertNever(value: never): never {
  throw new Error("Unsupport value: " + value)
}

This might be most util of util method. It has no dependencies, and I will need it in a lot of places (see #575 for more info).

Importantly, many util methods also need this, so I can't define it in lib/util/index.ts (cyclic import). But I also don't really want to make a lib/util/util.ts. Where should I put this function?

Also, we have around 5 copies of assertNever in various files already.

---

Maybe a bit of background. In my JS/TS projects, I typically go for a flat hierarchy for internal modules (= files that don't define functions/classes/types of the public API). So each of those internal modules just exports their functions/classes/types and that's it. Those internal modules might be in different folders, but there is no hierarchy between them. So internal modules never re-export things from other internal modules and there are no internal index.ts files.

I do this because it makes it easy to extract out common functionality into a module. I don't have to worry about internal hierarchies and can just create a new file.

Again, I'm only talking about internal modules. I use index.ts files and re-exports to define the public API of a package like everybody else. Although my index.ts files only re-export other modules, I don't define any functions/classes/types in them.