@flamework-experimental/core 2.0.0-alpha.2 → 2.0.0-alpha.4

package/docs/guide/02-modules.md

@@ -0,0 +1,254 @@
+# 2. Modules
+
+A **module** is the object `Flamework.createModule()` builds. It is two things at once:
+
+1. **A dependency-injection container.** It holds a set of providers, and gives each provider the
+   other providers it depends on.
+2. **A lifecycle unit.** It starts (*ignites*) as a whole and stops (*extinguishes*) as a whole.
+
+In v1 there was exactly one module, and it was global and implicit. In v2 you create it yourself,
+which is what makes tests and tools possible. But **most games have exactly one module per realm and
+never extinguish it**. If that is your game, the second half of this page is optional reading.
+
+## The one-module case
+
+```ts
+Flamework.createModule()
+    .registerProviders("src/server/services")
+    .ignite();
+```
+
+That is all a typical game needs. You never call `build()` or `extinguish`, and `Dependency<T>()`
+reaches this module from anywhere.
+
+## The builder
+
+`Flamework.createModule()` returns a `ModuleBuilder`. Every method except `build()` and `ignite()`
+returns the builder, so those calls chain. `build()` returns a `ModuleDefinition`, and `ignite()`
+returns the ignited `Module`.
+
+| Method | Does |
+|---|---|
+| `registerProviders(path)` | Registers every `@Provider()` class defined in the files under a source folder, exported or not. |
+| `registerProvidersGlob(glob)` | The same, for every folder a glob matches, resolved when you build. |
+| `registerClassProvider(Class)` | Registers one class explicitly. |
+| `registerProvider<T>(config, id?)` | Registers a class, function or alias provider. |
+| `includePlugin(plugin)` | Adds a plugin, which can hook into this module. |
+| `disableDefaultLifecycle()` | Leaves out the `LifecyclePlugin` every module starts with. |
+| `setDebugName(name)` | Names the module in error messages. |
+| `apply(fn)` | Runs `fn(builder)` without breaking the chain. |
+| `build()` | Finishes the builder and returns a `ModuleDefinition`. |
+| `ignite(options?)` | Shorthand for `.build().ignite()`. `{ default: true }` makes this the module `Dependency<T>()` answers from. |
+
+### `build()` vs `ignite()`
+
+`ignite()` is `build().ignite()`. Use `build()` when the module is going to be ignited later, or more
+than once:
+
+```ts
+// Full form
+const definition = Flamework.createModule().registerClassProvider(Economy).build();
+const module = definition.ignite();
+
+// Shorthand, when you do not need the definition
+const module = Flamework.createModule().registerClassProvider(Economy).ignite();
+```
+
+You can ignite a definition many times, and **each ignition gets its own provider instances**. That
+makes a module a clean unit for tests: build the definition once, and ignite a fresh module for each
+test.
+
+## What ignition does
+
+In order:
+
+1. Plugins are set up. Each plugin's setup function runs against this module and registers
+   providers, hooks and observers into it. A plugin reached twice is set up once.
+2. `onPreIgnite` hooks run.
+3. Every registered provider is constructed, and its constructor dependencies are resolved.
+4. `onPostIgnite` hooks run. This is where `LifecyclePlugin` calls `onInit` on everything that
+   implements it. An error raised up to this point fails the ignition.
+5. The module is now ignited, and `onIgnited` hooks run. This is where `LifecyclePlugin` calls
+   `onStart` on everything that implements it, and then starts its `RunService` connections. So an
+   `onStart` sees `isIgnited()` return `true`, may `extinguish()` the module, and may ignite a module
+   that imports it.
+
+Within step 3, providers are constructed on demand: resolving a dependency constructs it if it does
+not exist yet. So a provider's constructor can safely use anything injected into it.
+
+## Resolving by hand
+
+```ts
+const shop = module.resolveDependency<Shop>();
+```
+
+Use this where Flamework meets code that it does not manage. Inside a provider, take a constructor
+parameter instead.
+
+Some code has no module handle at hand: a UI component, a script, a callback registered with
+something outside Flamework. There, `Dependency<T>()` resolves against the **default module**:
+
+```ts
+import { Dependency } from "@flamework-experimental/core";
+
+const shop = Dependency<Shop>();
+```
+
+The first module ignited in a realm is the default. In a game, that is the one the entry point
+ignites. To make a later module the default instead, pass `{ default: true }`:
+
+```ts
+const module = definition.ignite({ default: true });
+```
+
+Extinguishing the default module releases it, and the next module ignited becomes the default. So a
+test that ignites and extinguishes a module per case never leaks one into the next. A module that
+fails to ignite never becomes the default: if one ignited with `{ default: true }` raises, the
+previous default stays as it was. With no default, `Dependency<T>()` raises
+`Dependency<T>() was called before any module was ignited`.
+
+With more than one module running, pass the one to resolve from. This is the same as
+`module.resolveDependency<T>()`, for code that has the handle but prefers the shape of the global
+function:
+
+```ts
+const shop = Dependency<Shop>(worldModule);
+```
+
+A provider can also inject the module itself:
+
+```ts
+@Provider()
+class Registry {
+    constructor(private module: Module) {}
+
+    public spawnSession() {
+        return this.module.createClassInstance(Session);
+    }
+}
+```
+
+## Tearing down
+
+```ts
+module.extinguish();
+```
+
+This runs the `onExtinguished` hooks, releases the instances the module created, and unregisters
+them from every plugin observing them. So the lifecycle plugin stops ticking providers that are gone.
+
+Games rarely call this. Tests do, and so do tools that mount and unmount.
+
+## More than one module?
+
+A second module is a second container. Nothing in one module can inject anything from the other
+unless it imports it, and `Dependency<T>()` answers from only one of them. Use a second module only
+when you want that separation:
+
+- **Tests**, where each case wants a fresh container. Build the definition once, and ignite it for
+  each case.
+- **A tool** that lives for less time than the game, and is extinguished when it closes.
+- **A scenario** that runs against the game, such as a test rig or a debug world, and is torn down on
+  its own. It imports the game module (see below).
+
+### Importing a module
+
+A module ignited with `imports` can inject and resolve the providers of the modules it lists. It
+looks in its own providers first:
+
+```ts
+const game = Flamework.createModule()
+    .registerProviders("src/server/services")
+    .ignite();
+
+const rig = Flamework.createModule()
+    .registerProviders("src/server/Testing/rig")
+    .ignite({ imports: [game] });
+```
+
+A provider in `rig` can take `DataService` in its constructor, just as a provider in `game` can.
+Resolution looks in `rig` first, then in each import in order, and each import also searches its own
+imports. When nothing is found, the error names the imports it searched. Nothing is copied: the
+import keeps its providers, their lifecycle, their observers and their extinguish, and `rig` only
+resolves them. A lazy provider of the import is constructed by the import, the first time either
+module asks for it.
+
+Every import has to be ignited first. `ignite()` is synchronous, so in one entry script this is just
+the order of the lines. If you get it wrong, `ignite()` raises `imported module '...' is not ignited`
+before anything in the importer is constructed.
+
+Two rules decide what happens when both modules register the same id (the string Flamework uses to
+identify a class):
+
+- **The same class is shared.** If the importer registers a class that an import already resolves
+  to, the importer's registration is dropped and the import's instance answers. So a folder that
+  both modules' paths match does not produce two of everything.
+  `registerClassProvider(Class, { isolated: true })` keeps a separate instance in the importer
+  instead.
+- **A different class wins.** `rig.registerProvider<DataService>({ type: "class", value: FakeDataService })`
+  is kept, and answers before the import's `DataService`. This is how a scenario replaces one of the
+  game's providers with a fake, for itself only. The game keeps the real one.
+
+Extinguishing an import first extinguishes every module that imports it, deepest first. So
+`game.extinguish()` takes `rig` down before the game. An importer extinguished on its own detaches,
+and the import keeps running.
+
+Some things that used to need a second module are now a [plugin](08-plugins.md): a library that
+ships providers, or code both realms share. A plugin's setup registers the providers into whichever
+module includes it. A plugin that two other plugins both include is set up once.
+
+```ts
+// src/shared/plugins/core.ts
+export const CorePlugin = Flamework.createPlugin("Core", (target) => {
+    target.registerProviders("src/shared/services");
+});
+
+// both entry points
+.includePlugin(CorePlugin)
+```
+
+Each realm ignites its own module, which is what you want: the server and the client are different
+processes.
+
+## Patterns
+
+**A module per test.** Build the definition once, ignite it for each case, and extinguish it
+afterwards:
+
+```ts
+const definition = Flamework.createModule().registerClassProvider(Shop).build();
+
+const module = definition.ignite();
+// ...assert...
+module.extinguish();
+```
+
+**`apply` for conditional wiring**, so the chain stays readable:
+
+```ts
+Flamework.createModule()
+    .apply((builder) => (RunService.IsStudio() ? builder.registerClassProvider(DebugTools) : builder))
+    .ignite();
+```
+
+## Caveats
+
+- **A module ignites once and extinguishes once.** Igniting a `Module` twice, or extinguishing it
+  twice, raises `module is in invalid state when transitioning to '...'`. If you want a second
+  container, ignite the *definition* again.
+- **You cannot resolve during plugin setup or `onPreIgnite`.** Providers do not exist yet. The error
+  `module is in pre-ignite phase, dependency cannot be resolved` means a plugin tried. Register state
+  early, and resolve in `onPostIgnite`.
+- **`Dependency<T>()` answers from one module.** It uses the first module ignited, unless a later one
+  was ignited with `{ default: true }`. A realm with two running modules (tests, tools) should say
+  which one, or resolve through the module handle.
+- **Duplicate registration raises at ignition.** `provider ID was registered more than once` usually
+  means two `registerProviders` paths overlap. It can also mean a class is registered both by path
+  and by hand, or by both the module and a plugin. Two registrations are fine when their
+  [scope conditions](11-scopes.md) keep at most one of them.
+- **Imports are one way.** A module sees its imports' providers, but an import never sees the
+  importer's. A fake registered in the importer replaces nothing in the import.
+
+---
+
+Previous: [Getting started](01-getting-started.md) · Next: [Providers](03-providers.md)

package/docs/guide/03-providers.md

@@ -0,0 +1,423 @@
+# 3. Providers
+
+A **provider** is usually a class that its module creates once: a singleton within that module.
+(Other kinds are covered under [Other kinds of provider](#other-kinds-of-provider).) You write most
+of your game as providers.
+
+```ts
+import { Provider } from "@flamework-experimental/core";
+
+@Provider()
+export class Economy {
+    public balance = 0;
+}
+```
+
+`@Provider()` does two things. It marks the class as a provider, and it tells the transformer to
+attach the metadata that dependency injection needs: the class's identifier (id), its constructor
+parameter types, and the interfaces it implements.
+
+## Registration
+
+**You do not list your providers by hand.** `registerProviders` takes a folder:
+
+```ts
+Flamework.createModule().registerProviders("src/server/services").ignite();
+```
+
+This is v2's version of v1's `Flamework.addPaths(...)`. Use it for ordinary game code.
+
+### How it actually works
+
+It helps to know this, because the caveats follow from it:
+
+1. **At compile time**, the transformer uses your Rojo project file to turn `"src/server/services"`
+   into the Rojo path that the folder ends up at. This is why the argument must be a string literal,
+   and why the folder must be mapped.
+2. **At runtime**, Flamework finds that instance with `WaitForChild` and requires every
+   `ModuleScript` under it. It collects every Flamework class those ModuleScripts define, **exported
+   or not**. It also collects anything they export that carries Flamework metadata, such as a
+   re-export of a class from elsewhere. A registration whose own scope condition does not hold
+   skips this step: the folder is not looked up and nothing is required. See [Scopes](11-scopes.md).
+3. It keeps the classes marked as providers, and registers each one once under its generated id,
+   however many ways it was found.
+
+So registration means "require everything in this folder and see what comes out", as it did in v1.
+
+Unexported classes are found because the transformer records each class against the ModuleScript
+that defines it (`script`). The id plays no part in this, so it works in every `idGenerationMode`
+and with obfuscation on.
+
+Only a class that the ModuleScript creates once, as it loads, is recorded: one declared at the top
+level of the file, or at the top level of a namespace in it. A class declared inside a function is
+created again by every call, so it is never recorded. That way, a later path registration never
+picks up a class that belongs to a test case or a factory. Such a class is found only if its file
+exports it.
+
+Only classes that carry `@Provider()` **themselves** are registered. Metadata is inherited through
+the class hierarchy, but an exported, undecorated subclass of a provider is still skipped, rather
+than registered under its parent's id. Registering one explicitly raises an error.
+
+### Registering by glob
+
+When your providers are spread over folders whose paths share a pattern, a glob saves listing each
+folder:
+
+```ts
+Flamework.createModule().registerProvidersGlob("src/server/**/services").ignite();
+```
+
+The glob is resolved at **compile time** against your source tree, and the matching Rojo paths are
+written to `include/flamework/globs.json`, which the runtime reads. Two consequences: the include
+directory must be part of your Rojo project (it is in a default roblox-ts project), and only game
+projects emit the file -- a published package cannot use globs. This is v1's `Flamework.addPathsGlob`.
+
+A glob that matches no files is not an error, since a folder can be empty on purpose. It registers
+nothing, and the build prints a warning with the glob and the file and line that use it.
+
+### Explicit registration
+
+To register one specific class, such as a library's provider, a test double or something
+conditional:
+
+```ts
+// Shorthand: uses the class's generated identifier
+.registerClassProvider(Economy)
+
+// Full form: the same thing spelled out
+.registerProvider<Economy>({ type: "class", value: Economy })
+```
+
+Both raise `class 'X' is missing the @Provider() decorator` if the class is not decorated itself,
+even when it inherits the decorator from a parent class.
+
+## Dependency injection
+
+Constructor parameters are resolved by type:
+
+```ts
+@Provider()
+export class Shop {
+    constructor(
+        private economy: Economy,
+        private logger: Logger,
+    ) {}
+}
+```
+
+There is nothing to annotate. The transformer records each parameter's id, and the module resolves
+them, constructing anything that does not exist yet.
+
+Resolution looks in the module first: its own providers, and whatever its plugins registered or
+provided. Then it looks in the modules this one imports, in order (see
+[Importing a module](02-modules.md#importing-a-module)). Nothing else is searched.
+
+You can also inject `Module` (the module doing the resolving) and anything a plugin provided. See
+[Plugins](08-plugins.md).
+
+### Outside a provider
+
+Code with no constructor, such as a UI component, a script or a signal handler, reaches a provider
+through `Dependency<T>()`. It resolves against the default module: the first one ignited, or the one
+ignited with `{ default: true }` (see [Modules](02-modules.md#resolving-by-hand)).
+
+```ts
+import { Dependency } from "@flamework-experimental/core";
+
+const economy = Dependency<Economy>();
+```
+
+Prefer a constructor parameter wherever you can use one. It declares the dependency where readers can
+see it, and it makes the module construct the dependency first. `Dependency<T>()` inside a
+provider's constructor works, as it did in v1, but the module cannot see that dependency.
+
+### Circular dependencies
+
+Two providers that inject each other cannot both be constructed first, and Flamework will not
+untangle this for you. Break the cycle: inject `Module` into one of them, and resolve the other
+lazily, only when it is used:
+
+```ts
+@Provider()
+class A {
+    constructor(private module: Module) {}
+
+    private get b() {
+        return this.module.resolveDependency<B>();
+    }
+}
+```
+
+Better still, look for the third provider: a cycle usually means one is trying to exist.
+
+### Asking for something that is not a provider
+
+`Dependency<T>()`, `resolveDependency<T>()` and constructor injection resolve only **providers**. v1
+built any decorated class on demand, but v2 does not. Asking for a class that is not a provider
+fails:
+
+- **A component** (`@Component()`) is built by `Components` on the instances it is attached to, never
+  by a module. When you build, the transformer refuses `Dependency<T>()`,
+  `module.resolveDependency<T>()` and a `@Provider()`'s constructor parameter when the type is a
+  component: `'QuestsUI' is a component (@Component), not a provider`. Make it a `@Provider()`: a
+  provider cannot extend `BaseComponent`, so move what callers need into a provider. Or get the
+  component from the instance: `components.getComponent<QuestsUI>(instance)`.
+- **A `@Provider()` that nothing registers** raises at runtime. The error says so, and says where the
+  class is defined: `'Shop' (ServerScriptService.TS.shop) is a @Provider() that nothing in this
+  module registers or provides`. Register its folder, register the class, include the plugin that
+  provides it, or import a module that has it.
+- **An `@Injectable()` class** is built with `createClassInstance`, never resolved:
+  `'Session' (...) is not a provider`.
+
+The check made when you build covers only what the type makes certain. It never refuses:
+
+- an id passed by hand (`Dependency<T>(undefined, id)`)
+- an interface or abstract class, since a function or alias provider may stand behind it
+- `Dependency<Components>()`, and anything else a plugin provides
+- a `@Provider()` class
+- a macro of your own that takes a `Modding.Target.Dependency<T>`
+
+A component's own constructor may take another component: that is a component dependency. An
+`@Injectable()`'s constructor may take one too, and `overrideDependency` can answer it. At runtime,
+the full explanation is given only for a class that has loaded and was defined at the top level of
+its file. Anything else gets the plain `could not resolve dependency 'X'`.
+
+## Other kinds of provider
+
+A provider does not have to be a class.
+
+### Function providers
+
+The callback is called on **every** resolution: once per constructor parameter that asks for it, and
+once per `resolveDependency`. Nothing is cached for you, so if you want a singleton, cache it in the
+callback:
+
+```ts
+interface Config {
+    readonly maxPlayers: number;
+}
+
+.registerProvider<Config>({
+    type: "function",
+    callback: () => ({ maxPlayers: 8 }),
+})
+```
+
+The callback receives an `InjectionContext` describing *who asked*:
+
+| Field | Is |
+|---|---|
+| `injectionId` | The id being resolved. |
+| `dependencyInfo` | The id plus any metadata carried on the type. |
+| `module` | The module resolving the dependency. |
+| `origin` | The class being constructed, if any. |
+
+`origin` lets you give each consumer its own logger:
+
+```ts
+.registerProvider<Logger>({
+    type: "function",
+    callback: (context) => new Logger(tostring(context.origin)),
+})
+```
+
+Every class that injects a `Logger` gets one tagged with its own name. That is why the callback runs
+on every resolution. For a shared value, create it outside the callback and close over it:
+
+```ts
+const config = { maxPlayers: 8 };
+.registerProvider<Config>({ type: "function", callback: () => config })
+```
+
+### Alias providers
+
+An alias provider resolves one id to another. This is how an interface gets an implementation:
+
+```ts
+.registerClassProvider(DataStoreStorage)
+.registerProvider<Storage>({ type: "alias", injectionId: Flamework.id<DataStoreStorage>() })
+```
+
+Anything that injects `Storage` now gets the `DataStoreStorage` instance: the same instance, not a
+second one. In tests, swap the alias to swap the implementation.
+
+### Lazy providers
+
+A provider is normally constructed during ignition, whether or not anything uses it. Mark it lazy to
+construct it only when something first resolves it:
+
+```ts
+@Provider({ lazy: true })
+export class Telemetry implements OnStart {}
+```
+
+A lazy provider that nothing ever resolves is never created. One that is resolved after ignition
+still gets `onInit` and `onStart`, on the next resume point after it is constructed. From then on it
+behaves like any other provider. One resolved during ignition, from another provider's `onInit`, is
+initialised in order, before anything starts. This is v1's `@Optional()`. There is no equivalent
+of `includeOptionalClass`, because resolving a lazy provider is how you include it.
+
+### Load order
+
+`loadOrder` sets when a provider's `onInit` and `onStart` run, compared with the other providers of
+the same ignition, as v1's `@Service({ loadOrder })` did. Lower values go first, and the default is
+`1`. Providers with the same value keep the order they would have without one.
+
+```ts
+@Provider({ loadOrder: 0 })
+export class CameraShake implements OnStart {
+    public onStart() {} // started before the providers left at 1
+}
+
+@Provider({ loadOrder: 5 })
+export class Interface implements OnStart {
+    public onStart() {} // started after them
+}
+```
+
+Dependencies still come first. A provider is constructed and initialised after what its constructor
+takes, even when that has a higher `loadOrder`. So a low `loadOrder` pulls the provider's
+dependencies forward with it. See [Lifecycle events](04-lifecycle-events.md#load-order) for the
+exact order.
+
+`loadOrder` has no effect on a lazy provider, which starts when it is first resolved. It also has no
+effect across modules: an imported module ignites, and starts, before the module that imports it.
+Any finite number is accepted. Anything else raises an error when the ModuleScript that defines the
+class loads.
+
+### Scoped providers
+
+A provider can be tied to the build's *scopes*, the names a build is compiled with. Then a test
+scenario or a debug tool exists only in the builds that ask for it:
+
+```ts
+@Provider({ activeIn: ["components"] })
+export class ComponentProbe {}
+```
+
+The same `activeIn`/`inactiveIn` pair also goes on a registration
+(`registerProviders(path, { ... })`, `registerClassProvider(Class, { ... })`, or the config of
+`registerProvider`) and on `ignite`. The conditions combine by AND: all of them must hold. A
+provider that is left out is not registered at all. A path or glob registration whose own
+condition does not hold does not even load its folder. See [Scopes](11-scopes.md).
+
+## Classes that are not providers
+
+Sometimes you want dependency injection for a class you create yourself, such as a session, a
+request or a per-player object. You do not want it to be a singleton, or to be picked up by
+`registerProviders`. Use `@Injectable()`:
+
+```ts
+import { Injectable } from "@flamework-experimental/core";
+
+@Injectable()
+class Session {
+    constructor(private economy: Economy) {}
+}
+```
+
+```ts
+const session = module.createClassInstance(Session);
+```
+
+`@Injectable()` attaches the same metadata as `@Provider()`, but does **not** mark the class as a
+provider. So path registration skips it, and it cannot be resolved by id.
+
+The module owns the instance. The instance is attached to any lifecycle events it implements, and
+released when the module extinguishes or when you release it yourself:
+
+```ts
+module.removeClassInstance(session);
+```
+
+Removing twice is safe and does nothing the second time.
+
+### Passing arguments
+
+`createClassInstance` resolves every constructor parameter through the module, so there is no
+argument list to pass. To hand the instance something of your own, declare it as a parameter and
+intercept its id:
+
+```ts
+interface SessionContext {
+    readonly player: Player;
+}
+
+@Injectable()
+class Session {
+    constructor(
+        private economy: Economy,
+        private context: SessionContext,
+    ) {}
+}
+
+const session = module.createClassInstance(Session, {
+    overrideDependency: (info) => (info.id === Flamework.id<SessionContext>() ? { player } : undefined),
+});
+```
+
+Returning `undefined` falls back to the module's normal resolution, so you intercept only what you
+mean to. This is how `@flamework-experimental/components` gives every component its `instance` and
+`attributes`.
+
+## Realms
+
+There is no `@Service` / `@Controller` split. A provider is not bound to a realm. The module that
+registers it decides:
+
+```ts
+// server entry point
+.registerProviders("src/server/services")
+
+// client entry point
+.registerProviders("src/client/controllers")
+```
+
+Shared providers go in a shared folder registered by both, or in a shared plugin included by both.
+
+## Patterns
+
+**Interface plus alias for swappable implementations.** Declare the interface, register the concrete
+class, and alias the interface to it. Tests register a different class under the same alias.
+
+**A config provider at the top.** A function provider returning a frozen object is the simplest way
+to get configuration into everything without a global.
+
+**Factories over service locators.** If a provider needs to make many short-lived objects, inject
+`Module` and use `createClassInstance` rather than passing the module around.
+
+## Caveats
+
+- **Path registration takes every provider a file defines, exported or not.** Sometimes a
+  `@Provider()` class must stay out of the module that registers its folder, such as a fixture that
+  a test registers in a module of its own. Put that class in a folder no module registers, or inside
+  the function that uses it. A class declared inside a function is found only through its file's
+  exports.
+- **A path is resolved in the project that compiles it.** The transformer turns it into a Rojo
+  path with that project's Rojo file. So a published package cannot register its own folders:
+  `registerProviders("src/...")` in a package gets a path in the package's project, which a game's
+  place does not have, and fails at runtime. In a package, register classes one by one with
+  `registerClassProvider`. See [Macros › Paths](07-macros.md#paths).
+- **Path registration requires every ModuleScript in the folder**, so their import side effects
+  run. A ModuleScript that throws while loading fails the ignition with its path and error, as in v1.
+  Otherwise, a provider that silently failed to register would only show up later, as a missing
+  dependency. A registration whose own scope condition does not hold requires nothing.
+- **Subclasses need their own decorator.** `class Fake extends Economy {}` without `@Provider()` is
+  not a provider; registering it explicitly raises, and path registration skips it.
+- **`WaitForChild` yields.** If the folder has not replicated yet, ignition waits. A folder that
+  never comes (missing or misspelled, or empty in a fresh clone, which git leaves without it) is
+  warned about when you build, where the path is written, and at runtime after five seconds, by the
+  registration's name; the wait goes on. An empty folder that is there registers nothing.
+- **Overlapping paths raise.** Registering `src/server` and `src/server/services` will hit
+  `provider ID was registered more than once`.
+- **`@Injectable()` classes are not resolvable.** `resolveDependency<Session>()` will not find one.
+  That is the point of the decorator.
+- **A missing dependency is a runtime error, not a compile error.** The exception is a component,
+  which the transformer refuses. `module could not resolve dependency 'X'` means the type was never
+  registered in this module or in anything it includes. For a class that has loaded, the message goes
+  on to say what the class is and what to do.
+- **Constructor injection only.** There is no property or method injection.
+
+---
+
+Previous: [Modules](02-modules.md) · Next: [Lifecycle events](04-lifecycle-events.md)