Skip to content

[DOC] Add documentation for RFC 0821 items #20272

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 22, 2022
Merged

[DOC] Add documentation for RFC 0821 items #20272

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
361 changes: 306 additions & 55 deletions packages/@ember/-internals/owner/index.ts
View file
Open in desktop

Large diffs are not rendered by default.

88 changes: 1 addition & 87 deletions packages/@ember/-internals/runtime/lib/mixins/container_proxy.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import type { ContainerProxy } from '@ember/-internals/owner';
container functionality.

@class ContainerProxyMixin
@extends ContainerProxy
@private
*/
interface ContainerProxyMixin extends ContainerProxy {
Expand All @@ -33,50 +34,6 @@ const ContainerProxyMixin = Mixin.create({
return this.__container__.ownerInjection();
},

/**
Given a fullName return a corresponding instance.

The default behavior is for lookup to return a singleton instance.
The singleton is scoped to the container, allowing multiple containers
to all have their own locally scoped singletons.

```javascript
let registry = new Registry();
let container = registry.container();

registry.register('api:twitter', Twitter);

let twitter = container.lookup('api:twitter');

twitter instanceof Twitter; // => true

// by default the container will return singletons
let twitter2 = container.lookup('api:twitter');
twitter2 instanceof Twitter; // => true

twitter === twitter2; //=> true
```

If singletons are not wanted an optional flag can be provided at lookup.

```javascript
let registry = new Registry();
let container = registry.container();

registry.register('api:twitter', Twitter);

let twitter = container.lookup('api:twitter', { singleton: false });
let twitter2 = container.lookup('api:twitter', { singleton: false });

twitter === twitter2; //=> false
```

@public
@method lookup
@param {String} fullName
@param {Object} options
@return {any}
*/
lookup(fullName: string, options: object) {
return this.__container__.lookup(fullName, options);
},
Expand All @@ -94,49 +51,6 @@ const ContainerProxyMixin = Mixin.create({
this._super();
},

/**
Given a fullName return a factory manager.

This method returns a manager which can be used for introspection of the
factory's class or for the creation of factory instances with initial
properties. The manager is an object with the following properties:

* `class` - The registered or resolved class.
* `create` - A function that will create an instance of the class with
any dependencies injected.

For example:

```javascript
import { getOwner } from '@ember/application';

let owner = getOwner(otherInstance);
// the owner is commonly the `applicationInstance`, and can be accessed via
// an instance initializer.

let factory = owner.factoryFor('service:bespoke');

factory.class;
// The registered or resolved class. For example when used with an Ember-CLI
// app, this would be the default export from `app/services/bespoke.js`.

let instance = factory.create({
someProperty: 'an initial property value'
});
// Create an instance with any injections and the passed options as
// initial properties.
```

Any instances created via the factory's `.create()` method *must* be destroyed
manually by the caller of `.create()`. Typically, this is done during the creating
objects own `destroy` or `willDestroy` methods.

@public
@method factoryFor
@param {String} fullName
@param {Object} options
@return {FactoryManager}
*/
factoryFor(fullName: string) {
return this.__container__.factoryFor(fullName);
},
Expand Down
1 change: 1 addition & 0 deletions packages/@ember/-internals/runtime/lib/mixins/registry_proxy.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import Mixin from '@ember/object/mixin';
registry functionality.

@class RegistryProxyMixin
@extends RegistryProxy
@private
*/
interface RegistryProxyMixin extends RegistryProxy {
Expand Down
32 changes: 19 additions & 13 deletions packages/@ember/owner/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,33 @@
/**
@module @ember/owner
Ember’s dependency injection system is built on the idea of an "owner": an
object responsible for managing items which can be registered and looked up
with the system.

An `Owner` is the main object responsible for managing Ember's dependency
injection system. In normal app code, you will encounter `Owner`s via an
`ApplicationInstance` or its superclass, `EngineInstance`, which are the two
major implementers of the `Owner` type.
This module does not provide any concrete instances of owners. Instead, it
defines the core type, `Owner`, which specifies the public API contract for an
owner. The primary concrete implementations of `Owner` are `EngineInstance`,
from `@ember/engine/instance`, and its `ApplicationInstance` subclass, from
`@ember/application/instance`.

Along with the `Owner` itself, this module provides a number of supporting
types related to Ember's DI system:
Along with `Owner` itself, this module provides a number of supporting types
related to Ember's DI system:

- `Factory`, Ember's primary interface for something which can create class
instances registered with the DI system.

- `FactoryManager`, an interface for inspecting a `Factory`'s class.

- `Resolver`, an interface defining the contract for the object responsible
for mapping string names to the corresponding classes. For example, when
you write `@service('session')`, a resolver is responsible to map that back
to the `Session` service class in your codebase. Normally, this is handled
for you automatically with `ember-resolver`, which is the main implementor
of this interface.
for mapping string names to the corresponding classes. For example, when you
write `@service('session')`, a resolver is responsible to map that back to
the `Session` service class in your codebase. Normally, this is handled for
you automatically with `ember-resolver`, which is the main implementor of
this interface.

For more details on each, see their per-item docs.

For more details on each, see their per-item docs!
@module @ember/owner
@public
*/

// We need to provide a narrower public interface to `getOwner` so that we only
Expand Down
232 changes: 3 additions & 229 deletions packages/@ember/routing/lib/route-info.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,230 +1,4 @@
export { RouteInfo, RouteInfoWithAttributes } from 'router_js';

/**
@module @ember/routing
*/

/**
A `RouteInfoWithAttributes` is an object that contains
metadata, including the resolved value from the routes
`model` hook. Like `RouteInfo`, a `RouteInfoWithAttributes`
represents a specific route within a Transition.
It is read-only and internally immutable. It is also not
observable, because a Transition instance is never
changed after creation.

@class RouteInfoWithAttributes
@public
*/

/**
The dot-separated, fully-qualified name of the
route, like "people.index".
@property {String} name
@public
*/

/**
The final segment of the fully-qualified name of
the route, like "index"
@property {String} localName
@public
*/

/**
The values of the route's parameters. These are the
same params that are received as arguments to the
route's model hook. Contains only the parameters
valid for this route, if any (params for parent or
child routes are not merged).
@property {Object} params
@public
*/

/**
The ordered list of the names of the params
required for this route. It will contain the same
strings as `Object.keys(params)`, but here the order
is significant. This allows users to correctly pass
params into routes programmatically.
@property {Array} paramNames
@public
*/

/**
The values of any queryParams on this route.
@property {Object} queryParams
@public
*/

/**
This is the resolved return value from the
route's model hook.
@property {Object|Array|String|undefined} attributes
@public
*/

/**
Will contain the result `Route#buildRouteInfoMetadata`
for the corresponding Route.
@property {Any} metadata
@public
*/

/**
A reference to the parent route's RouteInfo.
This can be used to traverse upward to the topmost
`RouteInfo`.
@property {RouteInfo|null} parent
@public
*/

/**
A reference to the child route's RouteInfo.
This can be used to traverse downward to the
leafmost `RouteInfo`.
@property {RouteInfo|null} child
@public
*/

/**
Allows you to traverse through the linked list
of `RouteInfo`s from the topmost to leafmost.
Returns the first `RouteInfo` in the linked list
for which the callback returns true.

This method is similar to the `find()` method
defined in ECMAScript 2015.

The callback method you provide should have the
following signature (all parameters are optional):

```javascript
function(item, index, array);
```

- `item` is the current item in the iteration.
- `index` is the current index in the iteration.
- `array` is the array itself.

It should return the `true` to include the item in
the results, `false` otherwise.

Note that in addition to a callback, you can also
pass an optional target object that will be set as
`this` on the context.
// Exists to provide runtime exports used in the internals. For the public,
// type-only exports, see `packages/@ember/routing/route-info`.

@method find
@param {Function} callback the callback to execute
@param {Object} [target*] optional target to use
@returns {Object} Found item or undefined
@public
*/

/**
A RouteInfo is an object that contains metadata
about a specific route within a Transition. It is
read-only and internally immutable. It is also not
observable, because a Transition instance is never
changed after creation.

@class RouteInfo
@public
*/

/**
The dot-separated, fully-qualified name of the
route, like "people.index".
@property {String} name
@public
*/

/**
The final segment of the fully-qualified name of
the route, like "index"
@property {String} localName
@public
*/

/**
The values of the route's parameters. These are the
same params that are received as arguments to the
route's `model` hook. Contains only the parameters
valid for this route, if any (params for parent or
child routes are not merged).
@property {Object} params
@public
*/

/**
The ordered list of the names of the params
required for this route. It will contain the same
strings as Object.keys(params), but here the order
is significant. This allows users to correctly pass
params into routes programmatically.
@property {Array} paramNames
@public
*/

/**
The values of any queryParams on this route.
@property {Object} queryParams
@public
*/

/**
Will contain the result `Route#buildRouteInfoMetadata`
for the corresponding Route.
@property {Any} metadata
@public
*/

/**
A reference to the parent route's `RouteInfo`.
This can be used to traverse upward to the topmost
`RouteInfo`.
@property {RouteInfo|null} parent
@public
*/

/**
A reference to the child route's `RouteInfo`.
This can be used to traverse downward to the
leafmost `RouteInfo`.
@property {RouteInfo|null} child
@public
*/

/**
Allows you to traverse through the linked list
of `RouteInfo`s from the topmost to leafmost.
Returns the first `RouteInfo` in the linked list
for which the callback returns true.

This method is similar to the `find()` method
defined in ECMAScript 2015.

The callback method you provide should have the
following signature (all parameters are optional):

```javascript
function(item, index, array);
```

- `item` is the current item in the iteration.
- `index` is the current index in the iteration.
- `array` is the array itself.

It should return the `true` to include the item in
the results, `false` otherwise.

Note that in addition to a callback, you can also
pass an optional target object that will be set as
`this` on the context.

@method find
@param {Function} callback the callback to execute
@param {Object} [target*] optional target to use
@returns {Object} Found item or undefined
@public
*/
export { RouteInfo, RouteInfoWithAttributes } from 'router_js';
Loading