Rename wasp-config userSpec to tsAppSpec for clarity and consistency

[FranjoMindek]

We've had an discussion around the current naming of userSpec, #2690 (comment). The end conses was that the name is misleading and potentially confusing.

Problems with userSpec:

• The word “user” is ambiguous in the context of Wasp. In most places, “user” refers to the auth user or the app user, not the Wasp developer.
• There’s nothing else in the codebase using “user” to refer to Wasp developers, so this usage is inconsistent.
• The name doesn’t clearly convey the role of the structure — it’s not intuitive that this is a TypeScript-friendly representation of AppSpec.

Agreed direction:

• Rename userSpec → tsAppSpec (short for TypeScript App Spec), as that is what it effectively is: a representation of AppSpec tailored for usage in TypeScript.
• Keep appSpec as-is. It is the canonical form and should not be renamed to something like hsAppSpec, since its connection to Haskell is an implementation detail.

[FranjoMindek]

As quoted from another PR:

I think this is great to ponder together with #2737. We have a pattern of matching UserApi.XYZConfig to AppSpec.XYZ

If we want to follow that, then UserApi.App is confusingly named and should be changed. Problem is that UserApi.App is the most imprtant type, as it's the class which is exported for user to use.

It could be a WaspApp or something similar?

const waspApp = new WaspApp();

But this requires a lot of thought, since this type is very important. Should be a group thing.

It might be worthwhile to look into renaming the UserApi.App

[sodic]

It might be worthwhile to look into renaming the UserApi.App

The only thing we should ask, without considering anything else, is What do we want the user to see?

After we decide on that, we should adapt our internal code to work with it. We're the ones who should pay the price for good user DX.

It's generally never desirable do design the public API to make it easier on ourselves. We sometimes make exceptions when the approaches greatly differ in complexity, but that's not the case here.
Btw the price for good DX in this case is pretty cheap, we can easily reexport the class under a different name.

What do we want the user to see?

For me, it's new App().

[FranjoMindek]

Should be user DX first, I agree.
I know that @Martinsos got really confused around having AppSpec.App, UserApi.App and UserApi.AppConfig, hence we brought it up.

If our DX is suffering here we can maybe try different module system:

1. appSpec.ts -> AppSpec.App
2. userApi.ts -> UserApi.App
3. tsAppSpec.ts (a bit weird since it's also part of user api) -> TSAppSpec.AppConfig

In other words, extract ts app spec stuff out of the userApi.ts into its own module.
Let userApi.ts handle user facing exports only.

[sodic]

The confusion comes from the userApi exporting both App (the class for users) and AppConfig (a TS spec equivalent of AppSpec.App). When mapUserSpecToAppSpecDecls imports everything from userApi.ts under the User namespace, it has access to both User.App and User.AppConfig.

The main problem:

• The general mapping pattern is: User.FooConfig maps to AppSpec.Foo.
• Even though User.AppConfig and AppSpec.App follow this pattern, since the User scope also contains User.App, it's easy to mistakenly think that User.App (instead of User.AppConfig) is supposed to map to AppSpec.App.

We can solve this by internally separating the User configs from the App class. The module mapUserSpecToAppSpecDecls then doesn't have to import the App class and the confusion is gone.

At the same time, I don't want to lose information that the App is a part of user (public) API.

So here's an idea:

src/
  userApi/
    App.ts // App class
    tsAppSpec.ts // Everything else from current userApi.ts, types exposed to the user
  index.ts // Reexports everything from userApi/
  mapUserSpecToAppSpecDecls.ts // Imports only `userApi/tsAppSpec.ts`
  appSpec.ts // Remains unchanged

[FranjoMindek]

I agree with the given direction.
The change above + rename should fix most of our own DX issues, while allowing us to keep users DX clean.

[FranjoMindek]

@Martinsos would like if we could rename userApi folder not to include "user" in name. I know you had publicApi idea? @sodic

[sodic]

That works for me. User is an overloaded term in our domain, and public is clear.