diff --git a/text/0821-public-types.md b/text/0821-public-types.md index 485a106023..767d415216 100644 --- a/text/0821-public-types.md +++ b/text/0821-public-types.md @@ -37,6 +37,7 @@ Introduce public import locations for type-only imports which have previously ha - [`getOwner` and `setOwner`](#getowner-and-setowner) - [`RouteInfo`](#routeinfo) - [`RouteInfoWithAttributes`](#routeinfowithattributes) + - [`Resolver`](#resolver) - [How we teach this](#how-we-teach-this) - [`Owner`](#owner-1) - [`Transition`, `RouteInfo`, and `RouteInfoWithAttributes`](#transition-routeinfo-and-routeinfowithattributes) @@ -392,6 +393,33 @@ function takesRouteInfoWithAttributes(routeInfoWithAttributes) { ``` +### `Resolver` + +The resolver is a contract implemented by libraries outside Ember itself, such as `ember-resolver`, `ember-strict-resolver`, and any number of custom resolvers which exist in apps across the ecosystem. It has never had public documentation, but is fully public API. It is a user-constructible interface with the following definition (using the `Factory` and `FullName` types exported from the new `@ember/owner` module): + +```ts +export type KnownForTypeResult = { + [fullName in `${Name}:${string}`]: boolean | undefined; +}; + +export interface Resolver { + knownForType?: (type: Name) => KnownForTypeResult; + lookupDescription?: (fullName: FullName) => string; + makeToString?: (factory: Factory, fullName: FullName) => string; + normalize?: (fullName: FullName) => string; + resolve(name: string): Factory | object | undefined; +} +``` + +The `KnownForTypeResult` utility type associated with it is also available as a named export. Unfortunately, due to currently limitations with TypeScript, you will generally have to *cast* to it, but it provides some type safety to callers, because it will *only* allow types corresponding to the passed string if users pass a string literal. + +Both are available as named, type-only, user-constructible interfaces from `@ember/owner`: + +```ts +import { Resolver, KnownForTypeResult } from '@ember/owner'; +``` + + ## How we teach this These concepts all already exist, but need updates to and in some cases wholly new pages in Ember's API docs.