[Documentation] No documented public API for `Owner`

As briefly discussed in #19914, there is not (and to my knowledge has never been) a definition of the public API of the Owner as expected by getOwner and setOwner. The API docs specify only Object as the type for the owner object returned by getOwner or expected as the second param to setOwner:

• getOwner
• setOwner

Additionally, while the getOwner docs include a short snippet showing the use of lookup, there is no further documentation anywhere in Ember’s API docs (as far as I can tell) of what exactly an Owner is.

On #19914, @ef4 suggested that the types within Ember represent the intended public API:

https://github.com/emberjs/ember.js/blob/6b77e9b940a23698201a9d16d1fe420507f048b0/packages/%40ember/-internals/owner/index.ts#L30-L39

If that is true, we should:

1. Document that as a public type, so that we can
2. Have something authoritative to point to when we open a PR to DefinitelyTyped addressing this.

---

Some context:

1. Past (verbal) discussions with various folks have never been conclusive here, so I’m opening this to get us as quickly as possible to an agreed-upon answer that we can document and publish—this is causing folks some pain as they upgrade to the v4 types. Earlier versions of the types returned any here, because they predated better tools like unknown, and in the absence of a publicly-documented API, unknown (or perhaps the equally useless to end users object) are the only options on offer.

2. Typed Ember has always maintained a policy that we do not publish types on DefinitelyTyped which do not correspond to documented public API for Ember. We are absolutely not in the business of defining the public API for Ember! Rather, we are in the business of accurately representing it in the types.

[chriskrycho]

For what it’s worth, I totally agree with you, but: (a) that’s true of a lot of internal APIs, and (b) that therefore would normally make it “intimate” rather than public by definition. Everyone in the Typed Ember team thinks the basic Owner interface as defined should simply be public (mind, with some tweaks to get rid of unsafe casts), but that’s not our call to make. Thus the issue! 😅 If Core folks are comfortable promoting it to public API (really: acknowledging that it’s functionally already been that for ages), let’s document it and ship it.

[chriskrycho]

We need to implement the actual Ember side of this, but initial support has landed for the types and docs via DefinitelyTyped now that RFC 821 is merged, so: progress is happening! I expect to open a PR landing the rest of the implementation details against Ember next week (after we land #20092).