@joist/di 3.9.0 → 3.9.1

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()).
+
+```ts
+const app = new Injector();
 
-class Engine {
-  type: 'gas' | 'electric' = 'gas';
+class Counter {
+  value = 0;
 
-  accelerate() {
-    return 'vroom';
+  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);
+
+  const res = await api.getData();
+
+  assert.equals(res.fname, 'Danny');
+  assert.equals(res.lname, 'Blue');
+});
+```
+
+### 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.
+
+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);
+  }
+}
 
-//hmmmmmmmm, 20
-console.log(car2.accelerate(), car2.tires().size);
+@injectable
+class MyService {
+  static providers = [{ provide: Logger, use: ConsoleLogger }];
+}
 ```
 
-## Factories
+### Factories
 
-In addition to defining providers with classes you can also use factory functions.
+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.
 
@@ -257,11 +272,9 @@ This behavior allows for services to be "scoped" within a certain branch of the
 
 ## Custom Elements:
 
-Joist is built to work with custom elements. Since the document is a tree we can search up that tree for providers.
+Joist is built to work with custom elements. Since the document is a tree we can search up that tree for providers. This is where Hierarchical Injectors can really shine as they allow you to defined React/Preact esq "context" elements.
 
 ```TS
-import { injectable, inject } from '@joist/di';
-
 class Colors {
   primary = 'red';
   secodnary = 'green';
@@ -307,7 +320,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 +330,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": "3.9.1",
   "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/inject.ts

@@ -1,11 +1,9 @@
+import { INJECTABLE_MAP } from './injector.js';
 import { InjectionToken } from './provider.js';
-import { INJECTABLE_MAP } from './injectable.js';
 
 export type Injected<T> = () => T;
 
-export function inject<This extends object, T>(
-  token: InjectionToken<T>
-): Injected<T> {
+export function inject<This extends object, T>(token: InjectionToken<T>): Injected<T> {
   return function (this: This) {
     const injector = INJECTABLE_MAP.get(this);
 

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,44 +1,39 @@
 import { ConstructableToken } from './provider.js';
-import { Injector } from './injector.js';
+import { INJECTABLE_MAP, Injector } from './injector.js';
 import { environment } from './environment.js';
-import { InjectableMap } from './injectable-map.js';
-
-export const INJECTABLE_MAP = new InjectableMap();
 
 export function injectable<T extends ConstructableToken<any>>(Base: T, _?: unknown) {
   return class InjectableNode extends Base {
     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);
+          } else {
+            injector.setParent(environment());
+          }
+        });
+      }
     }
 
     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() {

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

@@ -0,0 +1,187 @@
+import test from 'node:test';
+import assert from 'node:assert';
+
+import { Injector } from './injector.js';
+import { inject } from './inject.js';
+import { injectable } from './injectable.js';
+import { Provider, StaticToken } from './provider.js';
+
+test('should create a new instance of a single provider', () => {
+  class A {}
+
+  const app = new Injector();
+
+  assert(app.inject(A) instanceof A);
+
+  assert.equal(app.inject(A), app.inject(A));
+});
+
+test('should inject providers in the correct order', () => {
+  class A {}
+  class B {}
+
+  @injectable
+  class MyService {
+    a = inject(A);
+    b = inject(B);
+  }
+
+  const app = new Injector();
+  const instance = app.inject(MyService);
+
+  assert(instance.a() instanceof A);
+  assert(instance.b() instanceof B);
+});
+
+test('should create a new instance of a provider that has a full dep tree', () => {
+  class A {}
+
+  @injectable
+  class B {
+    a = inject(A);
+  }
+
+  @injectable
+  class C {
+    b = inject(B);
+  }
+
+  @injectable
+  class D {
+    c = inject(C);
+  }
+
+  @injectable
+  class E {
+    d = inject(D);
+  }
+
+  const app = new Injector();
+  const instance = app.inject(E);
+
+  assert(instance.d().c().b().a() instanceof A);
+});
+
+test('should override a provider if explicitly instructed', () => {
+  class A {}
+
+  @injectable
+  class B {
+    a = inject(A);
+  }
+
+  class AltA extends A {}
+  const app = new Injector([{ provide: A, use: AltA }]);
+
+  assert(app.inject(B).a() instanceof AltA);
+});
+
+test('should return an existing instance from a parent injector', () => {
+  class A {}
+
+  const parent = new Injector();
+
+  const app = new Injector([], parent);
+
+  assert.equal(parent.inject(A), app.inject(A));
+});
+
+test('should use a factory if provided', () => {
+  class Service {
+    hello() {
+      return 'world';
+    }
+  }
+
+  const injector = new Injector([
+    {
+      provide: Service,
+      factory() {
+        return {
+          hello() {
+            return 'world';
+          }
+        };
+      }
+    }
+  ]);
+
+  assert.equal(injector.inject(Service).hello(), 'world');
+});
+
+test('should throw an error if provider is missing both factory and use', () => {
+  class Service {
+    hello() {
+      return 'world';
+    }
+  }
+
+  const injector = new Injector([
+    {
+      provide: Service
+    }
+  ]);
+
+  assert.throws(
+    () => injector.inject(Service),
+    new Error("Provider for Service found but is missing either 'use' or 'factory'")
+  );
+});
+
+test('should pass factories and instance of the injector', async () => {
+  class Service {
+    hello() {
+      return 'world';
+    }
+  }
+
+  let factoryInjector: Injector | null = null;
+
+  const injector = new Injector([
+    {
+      provide: Service,
+      factory(i) {
+        factoryInjector = i;
+      }
+    }
+  ]);
+
+  injector.inject(Service);
+
+  assert.equal(factoryInjector, injector);
+});
+
+test('should create an instance from a StaticToken factory', () => {
+  const TOKEN = new StaticToken('test', () => 'Hello World');
+  const injector = new Injector();
+
+  const res = injector.inject(TOKEN);
+
+  assert.equal(res, 'Hello World');
+});
+
+test('should create an instance from an async StaticToken factory', async () => {
+  const TOKEN = new StaticToken('test', () => Promise.resolve('Hello World'));
+  const injector = new Injector();
+
+  const res = await injector.inject(TOKEN);
+
+  assert.equal(res, 'Hello World');
+});
+
+test('should allow static token to be overridden', () => {
+  const TOKEN = new StaticToken<string>('test');
+
+  const provider: Provider<string> = {
+    provide: TOKEN,
+    factory() {
+      return 'Hello World';
+    }
+  };
+
+  const injector = new Injector([provider]);
+
+  const res = injector.inject(TOKEN);
+
+  assert.equal(res, 'Hello World');
+});