@joist/di 3.9.0 → 4.0.1-next.0

package/README.md

@@ -1,20 +1,20 @@
 # Di
 
-Dependency Injection in ~800 bytes.
+Small and efficient dependency injection.
 
 Allows you to inject services into other class instances (including custom elements and node).
 
 ## Table of Contents
 
 - [Installation](#installation)
-- [Example Usage](#example)
-- [Factories](#factories)
-- [StaticToken](#statictoken)
-- [Testing](#testing)
-- [LifeCycle](#life-cycle)
-- [Parent/Child Relationship](#parentchild-relationship)
+- [Injectors](#injectors)
+- [Services](#services)
+- [Injectable Services](#injectable-services)
+- [Defining Providers](#defining-providers)
+- [StaticTokens](#statictokens)
+- [LifeCycle](#lifecycle)
+- [Hierarchical Injectors](#hierarchical-injectors)
 - [Custom Elements](#custom-elements)
-- [Environment](#environment)
 
 ## Installation:
 
@@ -22,73 +22,122 @@ Allows you to inject services into other class instances (including custom eleme
 npm i @joist/di
 ```
 
-## Example:
+## Injectors
 
-Classes that are decoratored with `@injectable` can use the `inject()` function to inject a class instance.
+Injectors are what are used to construct new [services](#services). Injectors can manually [provide implementations](#defining-providers) of services. Injectors can also have [parents](#hierarchical-injectors), parent injectors can define services for all of it's children.
 
-Different implementations can be provided for services.
+## Services
 
-```TS
-import { Injector, injectable, inject } from '@joist/di';
+At their simplest, services are classses. Services can be constructed via an `Injector` and treated are singletons (The same instance is returned for each call to Injector.inject()).
 
-class Engine {
-  type: 'gas' | 'electric' = 'gas';
+```ts
+const app = new Injector();
 
-  accelerate() {
-    return 'vroom';
+class Counter {
+  value = 0;
+
+  inc(val: number) {
+    this.value += val;
   }
 }
 
-class Tires {
-  size = 16;
-}
+// these two calls will return the same instance
+const foo = app.inject(Counter);
+const bar = app.inject(Counter);
+```
+
+## Injectable Services
+
+Singleton services are great but the real benefit can be seen when passing instances of one service to another. Services are injected into other services using the `inject()` fuction. In order to use `inject()` classes must be decorated with `@injectable`.
+
+`inject()` returns a function that will then return an instance of the requested service. This means that services are only created when they are needed and not when the class is constructed.
 
+```ts
 @injectable
-class Car {
-  engine = inject(Engine);
-  tires = inject(Tires);
-
-  accelerate() {
-    // the inject function returns a function
-    // this means that services are not initalized until they are called
-    return this.engine().accelerate();
+class App {
+  #counter = inject(Counter);
+
+  update(val: number) {
+    const instance = this.#counter();
+
+    instance.inc(val);
   }
 }
+```
 
-const factory1 = new Injector();
-const car1 = factory1.get(Car);
+## Defining Providers
 
-// vroom, 16
-console.log(car1.accelerate(), car1.tires().size);
+A big reason to use dependency injection is the ability to provide multiple implementations for a particular service. For example we probably want a different http client when running unit tests vs in our main application.
 
-const factory2 = new Injector([
-  {
-    provide: Engine,
-    use: class extends Engine {
-      type = 'electric';
+In the below example we have a defined HttpService that wraps fetch. but for our unit test we will use a custom implementation that returns just the data we want. This also has the benefit of avoiding test framework specific mocks.
 
-      accelerate() {
-        return 'hmmmmmmmm';
-      }
-    }
-  },
-  {
-    provide: Tires,
-    use: class extends Tires {
-      size = 20;
+```ts
+// services.ts
+
+class HttpService {
+  fetch(url: string, init?: RequestInit) {
+    return fetch(url, init);
+  }
+}
+
+@injectable
+class ApiService {
+  #http = inject(HttpService);
+
+  getData() {
+    return this.#http()
+      .fetch('/api/v1/users')
+      .then((res) => res.json());
+  }
+}
+```
+
+```ts
+// services.test.ts
+
+test('should return json', async () => {
+  class MockHttpService extends HttpService {
+    async fetch() {
+      return Response.json({ fname: 'Danny', lname: 'Blue' });
     }
   }
-]);
 
-const car2 = factory2.get(Car);
+  const app = new Injector([{ provide: HttpService, use: MockHttpService }]);
+  const api = app.inject(ApiService);
 
-//hmmmmmmmm, 20
-console.log(car2.accelerate(), car2.tires().size);
+  const res = await api.getData();
+
+  assert.equals(res.fname, 'Danny');
+  assert.equals(res.lname, 'Blue');
+});
 ```
 
-## Factories
+### Service level providers
+
+Under the hood, each service decorated with `@injectable` creates its own injector. This means that it is possible to defined providers from that level down.
 
-In addition to defining providers with classes you can also use factory functions.
+The below example will use this particular instance of Logger as wall as any other services injected into this service.
+
+```ts
+class Logger {
+  log(..._: any[]): void {}
+}
+
+class ConsoleLogger implements Logger {
+  log(...args: any[]) {
+    console.log(...args);
+  }
+}
+
+@injectable
+class MyService {
+  static providers = [{ provide: Logger, use: ConsoleLogger }];
+}
+```
+
+### Factories
+
+In addition to defining providers with classes you can also use factory functions. Factories allow for more flexibility for deciding exactly how a service is created. This is helpful when which instance that is provided depends on some runtime value.
 
 ```ts
 class Logger {
@@ -99,15 +148,21 @@ const app = new Injector([
   {
     provide: Logger,
     factory() {
-      return console;
+      const params = new URLSearchParams(window.location.search);
+
+      if (params.has('debug')) {
+        return console;
+      }
+
+      return new Logger(); // noop logger
     }
   }
 ]);
 ```
 
-### Accessing the injector
+### Accessing the injector in factories
 
-Factories provide more flexibility but often times cannot use the `inject()` function. To get around this all factories are passed an instance of the current injector.
+Factories provide more flexibility but sometimes will require access to the injector itself. For this reason the factory method is passed the injector that is being used to construct the requested service.
 
 ```ts
 class Logger {
@@ -128,13 +183,15 @@ const app = new Injector([
   {
     provide: Feature,
     factory(i) {
-      return new Feature(i.get(Logger));
+      const logger = i.inject(Logger);
+
+      return new Feature(logger);
     }
   }
 ]);
 ```
 
-## StaticToken
+## StaticTokens
 
 In most cases a token is any constructable class. There are cases where you might want to return other data types that aren't objects.
 
@@ -164,58 +221,16 @@ Static tokens can also leverage promises for cases when you need to async create
 
 ```ts
 // StaticToken<Promise<string>>
-const URL_TOKEN = new StaticToken('app_url', () => Promise.resolve('/default-url/'));
+const URL_TOKEN = new StaticToken('app_url', async () => '/default-url/');
 
 const app = new Injector();
 
-const url = await app.get(URL_TOKEN);
+const url: string = await app.inject(URL_TOKEN);
 ```
 
-## Testing
+## LifeCycle
 
-Dependency injection can make testing easy without requiring test framework level mock.
-
-```TS
-import { Injector, injectable, inject } from '@joist/di';
-
-@injectable
-class HttpService {
-  fetch(url: string, init?: RequestInit) {
-    return fetch(url, init);
-  }
-}
-
-@injectable
-class ApiService {
-  #http = inject(HttpService);
-
-  getData() {
-    return this.#http()
-      .fetch('/api/v1/users')
-      .then((res) => res.json());
-  }
-}
-
-// unit test
-const testApp = new Injector([
-  {
-    provide: HttpService,
-    use: class extends HttpService {
-      async fetch() {
-        // return whatever response we like
-        return Response.json({ fname: 'Danny', lname: 'Blue' });
-      }
-    },
-  },
-]);
-
-// our test instance will be using our mock when making http requests
-const api = testApp.get(ApiService);
-```
-
-## Life Cycle
-
-To helo provide more information to services that are being created, joist will call several life cycle hooks as services are created. These hooks are defined using the provided symbols so there is no risk of naming colisions.
+To help provide more information to services that are being created, joist will call several life cycle hooks as services are created. These hooks are defined using the provided symbols so there is no risk of naming colisions.
 
 ```ts
 class MyService {
@@ -229,7 +244,7 @@ class MyService {
 }
 ```
 
-## Parent/Child relationship
+## Hierarchical Injectors
 
 Injectors can be defined with a parent element. The top most parent will (by default) be where services are constructed and cached. Only if manually defined providers are found earlier in the chain will services be constructed lower. The injector resolution algorithm behaves as following.
 
@@ -259,8 +274,40 @@ This behavior allows for services to be "scoped" within a certain branch of the
 
 Joist is built to work with custom elements. Since the document is a tree we can search up that tree for providers.
 
+Setting your web page to work is very similar to any other JavaScript environment. There is a special `DOMInjector` class that will allow you to attach an injector to any location in the dom, in most cases this will be document.body.
+
 ```TS
-import { injectable, inject } from '@joist/di';
+const app = new DOMInjector();
+
+app.attach(document.body); // anything rendered in the body will have access to this injector.
+
+class Colors {
+  primary = 'red';
+  secodnary = 'green';
+}
+
+@injectable
+class MyElement extends HTMLElement {
+  #colors = inject(Colors);
+
+  connectedCallback() {
+    const { primary } = this.#colors();
+
+    this.style.background = primary;
+  }
+}
+
+customElements.define('my-element', MyElement);
+```
+
+### Context Elements:
+
+Context elements are where Hierarchical Injectors can really shine as they allow you to defined React/Preact esq "context" elements. Since custom elements are treated the same as any other class they can define providers for their local scope.
+
+```TS
+const app = new DOMInjector();
+
+app.attach(document.body);
 
 class Colors {
   primary = 'red';
@@ -307,7 +354,7 @@ customElements.define('my-element', MyElement);
 </color-ctx>
 ```
 
-## Environment
+### Environment
 
 When using @joist/di with custom elements a default root injector is created dubbed 'environment'. This is the injector that all other injectors will eventually stop at.
 If you need to define something in this environment you can do so with the `defineEnvironment` method.
@@ -317,32 +364,3 @@ import { defineEnvironment } from '@joist/di';
 
 defineEnvironment([{ provide: MyService, use: SomeOtherService }]);
 ```
-
-#### No decorators no problem:
-
-While this library is built with decorators in mind it is designed so that it can be used without them.
-
-```TS
-import { Injector, injectable, inject } from '@joist/di';
-
-class Engine {
-  type: 'gas' | 'electric' = 'gas';
-}
-
-class Tires {
-  size = 16;
-}
-
-const Car = injectable(
-  class {
-    engine = inject(Engine);
-    tires = inject(Tires);
-  }
-);
-
-const app = new Injector();
-const car = app.get(Car);
-
-// gas, 16
-console.log(car.engine(), car.tires());
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joist/di",
-  "version": "3.9.0",
+  "version": "4.0.1-next.0",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",
@@ -9,7 +9,7 @@
       "import": "./target/lib.js"
     },
     "./*": {
-      "import": "./target/lib/*.js"
+      "import": "./target/lib/*"
     }
   },
   "files": [
@@ -60,6 +60,17 @@
         "target/**"
       ],
       "output": [],
+      "dependencies": [
+        "build",
+        "test:node"
+      ]
+    },
+    "test:node": {
+      "command": "node --test target/**/*.test-node.js",
+      "files": [
+        "target/**"
+      ],
+      "output": [],
       "dependencies": [
         "build"
       ]

package/src/lib/dom-injector.test.ts

@@ -0,0 +1,30 @@
+import { expect } from '@open-wc/testing';
+
+import { DOMInjector } from './dom-injector.js';
+import { INJECTABLE_MAP } from './injectable.js';
+
+describe('DOMInjector', () => {
+  it('should attach an injector to a dom element', () => {
+    const root = document.createElement('div');
+    const app = new DOMInjector();
+
+    app.attach(root);
+
+    const injector = INJECTABLE_MAP.get(root);
+
+    expect(injector).to.equal(app);
+  });
+
+  it('should remove an injector associated with a dom element', () => {
+    const root = document.createElement('div');
+    const app = new DOMInjector();
+
+    app.attach(root);
+
+    expect(INJECTABLE_MAP.get(root)).to.equal(app);
+
+    app.detach(root);
+
+    expect(INJECTABLE_MAP.get(root)).to.equal(undefined);
+  });
+});

package/src/lib/dom-injector.ts

@@ -0,0 +1,12 @@
+import { INJECTABLE_MAP } from './injectable.js';
+import { Injector } from './injector.js';
+
+export class DOMInjector extends Injector {
+  attach(root: HTMLElement) {
+    INJECTABLE_MAP.set(root, this);
+  }
+
+  detach(root: HTMLElement) {
+    INJECTABLE_MAP.delete(root);
+  }
+}

package/src/lib/injectable-map.ts

@@ -1,13 +1,3 @@
 import { Injector } from './injector.js';
 
-export class InjectableMap {
-  #injectables = new WeakMap<object, Injector>();
-
-  get(key: object) {
-    return this.#injectables.get(key);
-  }
-
-  set(key: object, injector: Injector) {
-    return this.#injectables.set(key, injector);
-  }
-}
+export class InjectableMap extends WeakMap<object, Injector> {}

package/src/lib/injectable.test.ts

@@ -2,7 +2,6 @@ import { expect, fixture, html } from '@open-wc/testing';
 
 import { injectable } from './injectable.js';
 import { inject } from './inject.js';
-import { Injector } from './injector.js';
 
 describe('@injectable()', () => {
   it('should allow a custom element to be injected with deps', () => {
@@ -40,21 +39,6 @@ describe('@injectable()', () => {
     expect(el.foo()).to.be.instanceOf(Bar);
   });
 
-  it('should call the onInject lifecycle hook', () => {
-    class A {}
-
-    @injectable
-    class B {
-      a = inject(A);
-
-      onInject() {
-        expect(this.a()).to.be.instanceOf(A);
-      }
-    }
-
-    new Injector().inject(B);
-  });
-
   it('should handle parent HTML Injectors', async () => {
     @injectable
     class A {}

package/src/lib/injectable.ts

@@ -1,6 +1,5 @@
 import { ConstructableToken } from './provider.js';
 import { Injector } from './injector.js';
-import { environment } from './environment.js';
 import { InjectableMap } from './injectable-map.js';
 
 export const INJECTABLE_MAP = new InjectableMap();
@@ -10,35 +9,31 @@ export function injectable<T extends ConstructableToken<any>>(Base: T, _?: unkno
     constructor(..._: any[]) {
       super();
 
+      // Define a new Injector and assiciate it with this instance of the service
       const injector = new Injector(Base.providers);
-
       INJECTABLE_MAP.set(this, injector);
 
-      try {
-        if (this instanceof HTMLElement) {
-          this.addEventListener('finddiroot', (e) => {
-            const parentInjector = findInjectorRoot(e);
+      // If the current injectable instance is a HTMLElement preform additional startup logic
+      // this will find and attach parent injectors
+      if ('HTMLElement' in globalThis && this instanceof HTMLElement) {
+        this.addEventListener('finddiroot', (e) => {
+          const parentInjector = findInjectorRoot(e);
 
-            if (parentInjector !== null) {
-              injector.setParent(parentInjector);
-            } else {
-              injector.setParent(environment());
-            }
-          });
-        }
-      } catch {}
+          if (parentInjector !== null) {
+            injector.setParent(parentInjector);
+          }
+        });
+      }
     }
 
     connectedCallback() {
-      try {
-        if (this instanceof HTMLElement) {
-          this.dispatchEvent(new Event('finddiroot'));
+      if ('HTMLElement' in globalThis && this instanceof HTMLElement) {
+        this.dispatchEvent(new Event('finddiroot'));
 
-          if (super.connectedCallback) {
-            super.connectedCallback();
-          }
+        if (super.connectedCallback) {
+          super.connectedCallback();
         }
-      } catch {}
+      }
     }
 
     disconnectedCallback() {