@joist/di 4.0.1-next.0 → 4.0.1

package/README.md

@@ -16,10 +16,10 @@ Allows you to inject services into other class instances (including custom eleme
 - [Hierarchical Injectors](#hierarchical-injectors)
 - [Custom Elements](#custom-elements)
 
-## Installation:
+## Installation
 
 ```BASH
-npm i @joist/di
+npm i @joist/di@next
 ```
 
 ## Injectors
@@ -53,7 +53,7 @@ Singleton services are great but the real benefit can be seen when passing insta
 `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
+@injectable()
 class App {
   #counter = inject(Counter);
 
@@ -80,7 +80,7 @@ class HttpService {
   }
 }
 
-@injectable
+@injectable()
 class ApiService {
   #http = inject(HttpService);
 
@@ -102,7 +102,9 @@ test('should return json', async () => {
     }
   }
 
-  const app = new Injector([{ provide: HttpService, use: MockHttpService }]);
+  const app = new Injector({
+    providers: [[HttpService, { use: MockHttpService }]]
+  });
   const api = app.inject(ApiService);
 
   const res = await api.getData();
@@ -114,7 +116,7 @@ test('should return json', async () => {
 
 ### 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.
+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.
 
@@ -129,10 +131,10 @@ class ConsoleLogger implements Logger {
   }
 }
 
-@injectable
-class MyService {
-  static providers = [{ provide: Logger, use: ConsoleLogger }];
-}
+@injectable({
+  providers: [[Logger, { use: ConsoleLogger }]]
+})
+class MyService {}
 ```
 
 ### Factories
@@ -180,14 +182,16 @@ class Feature {
 }
 
 const app = new Injector([
-  {
-    provide: Feature,
-    factory(i) {
-      const logger = i.inject(Logger);
+  [
+    Feature,
+    {
+      factory(i) {
+        const logger = i.inject(Logger);
 
-      return new Feature(logger);
+        return new Feature(logger);
+      }
     }
-  }
+  ]
 ]);
 ```
 
@@ -200,10 +204,12 @@ In most cases a token is any constructable class. There are cases where you migh
 const URL_TOKEN = new StaticToken<string>('app_url');
 
 const app = new Injector([
-  {
-    provide: URL_TOKEN,
-    factory: () => '/my-app-url/'
-  }
+  [
+    URL_TOKEN,
+    {
+      factory: () => '/my-app-url/'
+    }
+  ]
 ]);
 ```
 
@@ -228,17 +234,43 @@ const app = new Injector();
 const url: string = await app.inject(URL_TOKEN);
 ```
 
+This allows you to dynamically import services
+
+```ts
+const HttpService = new StaticToken('HTTP_SERVICE', () => {
+  return import('./http.service.js').then((m) => new m.HttpService());
+});
+
+class HackerNewsService {
+  #http = inject(HttpService);
+
+  async getData() {
+    const http = await this.#http();
+
+    const url = new URL('https://hacker-news.firebaseio.com/v0/beststories.json');
+    url.searchParams.set('limitToFirst', count.toString());
+    url.searchParams.set('orderBy', '"$key"');
+
+    return http.fetchJson<string[]>(url);
+  }
+}
+
+const url: string = await app.inject(URL_TOKEN);
+```
+
 ## LifeCycle
 
 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 {
-  [LifeCycle.onInit]() {
+  @created()
+  onCreated() {
     // called the first time a service is created. (not pulled from cache)
   }
 
-  [LifeCycle.onInject]() {
+  @injected()
+  onInjected() {
     // called every time a service is returned, whether it is from cache or not
   }
 }
@@ -246,12 +278,16 @@ class MyService {
 
 ## 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.
+Injectors can be defined with a parent. 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.
 
 1. Do I have a cached instance locally?
 2. Do I have a local provider definition for the token?
-3. Do I have a parent? Check parent for 1 and 2
-4. All clear, go ahead and construct and cache the requested service
+3. Do I have a parent?
+4. Does parent have a local instance or provider definition?
+5. If parent exists but no instance found, create instance in parent.
+6. If not parent, All clear, go ahead and construct and cache the requested service.
+
+Having injectors resolve this way means that all children have access to services created by their parents.
 
 ```mermaid
 graph TD
@@ -286,7 +322,7 @@ class Colors {
   secodnary = 'green';
 }
 
-@injectable
+@injectable()
 class MyElement extends HTMLElement {
   #colors = inject(Colors);
 
@@ -302,35 +338,38 @@ 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.
+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. The `provideSelfAs` property will provide the current class for the tokens given.
+This also makes it easy to attributes to define values for the service.
 
 ```TS
 const app = new DOMInjector();
 
 app.attach(document.body);
 
-class Colors {
-  primary = 'red';
-  secodnary = 'green';
+interface ColorCtx {
+  primary: string;
+  secondary: string;
 }
 
-@injectable
-class ColorCtx extends HTMLElement {
-  // services can be scoped to a particular injectable
-  static providers = [
-    {
-      provide: Colors,
-      use: class implements Colors {
-        primary = 'orange';
-        secondary = 'purple';
-      },
-    },
-  ]
+const COLOR_CTX = new StaticToken<ColorCtx>('COLOR_CTX')
+
+@injectable({
+  provideSelfAs: [COLOR_CTX]
+})
+class ColorCtx extends HTMLElement implements ColorCtx {
+  get primary() {
+    return this.getAttribute("primary") ?? "red"
+  }
+
+  get secondary() {
+    return this.getAttribute("secondary") ?? "green"
+  }
 }
 
-@injectable
+@injectable()
 class MyElement extends HTMLElement {
-  #colors = inject(Colors);
+  #colors = inject(COLOR_CTX);
 
   connectedCallback() {
     const { primary } = this.#colors();
@@ -339,28 +378,17 @@ class MyElement extends HTMLElement {
   }
 }
 
-// Note: To use parent providers, the parent elements need to be defined first in correct order!
+// Note: To use parent providers, the parent elements need to be defined first!
 customElements.define('color-ctx', ColorCtx);
 customElements.define('my-element', MyElement);
 ```
 
 ```HTML
-<!-- Default Colors -->
+<!-- Error: No colors provided -->
 <my-element></my-element>
 
-<!-- Special color ctx -->
-<color-ctx>
+<!-- colors come from ctx -->
+<color-ctx primary="orange" secondard="blue">
   <my-element></my-element>
 </color-ctx>
 ```
-
-### 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.
-
-```ts
-import { defineEnvironment } from '@joist/di';
-
-defineEnvironment([{ provide: MyService, use: SomeOtherService }]);
-```

package/package.json

@@ -1,16 +1,13 @@
 {
   "name": "@joist/di",
-  "version": "4.0.1-next.0",
+  "version": "4.0.1",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",
   "exports": {
-    ".": {
-      "import": "./target/lib.js"
-    },
-    "./*": {
-      "import": "./target/lib/*"
-    }
+    ".": "./target/lib.js",
+    "./*": "./target/lib/*",
+    "./package.json": "./package.json"
   },
   "files": [
     "src",
@@ -20,7 +17,7 @@
   "description": "Dependency Injection for Vanilla JS classes",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/deebloo/joist.git"
+    "url": "git+https://github.com/joist-framework/joist.git"
   },
   "keywords": [
     "TypeScript",
@@ -31,7 +28,7 @@
   "author": "deebloo",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/deebloo/joist/issues"
+    "url": "https://github.com/joist-framework/joist/issues"
   },
   "publishConfig": {
     "access": "public"
@@ -57,17 +54,7 @@
     "test": {
       "command": "wtr --config wtr.config.mjs",
       "files": [
-        "target/**"
-      ],
-      "output": [],
-      "dependencies": [
-        "build",
-        "test:node"
-      ]
-    },
-    "test:node": {
-      "command": "node --test target/**/*.test-node.js",
-      "files": [
+        "wtr.config.mjs",
         "target/**"
       ],
       "output": [],

package/src/lib/context/injector.ts

@@ -0,0 +1,6 @@
+import { type Context, createContext } from "./protocol.js";
+
+import type { Injector } from "../injector.js";
+
+export const INJECTOR_CTX: Context<"injector", Injector> =
+  createContext("injector");

package/src/lib/context/protocol.ts

@@ -0,0 +1,78 @@
+/**
+ * A context key.
+ *
+ * A context key can be any type of object, including strings and symbols. The
+ *  Context type brands the key type with the `__context__` property that
+ * carries the type of the value the context references.
+ */
+export type Context<KeyType, ValueType> = KeyType & { __context__: ValueType };
+
+/**
+ * An unknown context type
+ */
+export type UnknownContext = Context<unknown, unknown>;
+
+/**
+ * A helper type which can extract a Context value type from a Context type
+ */
+export type ContextType<T extends UnknownContext> = T extends Context<
+  infer _,
+  infer V
+>
+  ? V
+  : never;
+
+/**
+ * A function which creates a Context value object
+ */
+
+export function createContext<KeyType, ValueType>(key: KeyType) {
+  return key as Context<KeyType, ValueType>;
+}
+
+/**
+ * A callback which is provided by a context requester and is called with the value satisfying the request.
+ * This callback can be called multiple times by context providers as the requested value is changed.
+ */
+export type ContextCallback<ValueType> = (
+  value: ValueType,
+  unsubscribe?: () => void,
+) => void;
+
+/**
+ * An event fired by a context requester to signal it desires a named context.
+ *
+ * A provider should inspect the `context` property of the event to determine if it has a value that can
+ * satisfy the request, calling the `callback` with the requested value if so.
+ *
+ * If the requested context event contains a truthy `subscribe` value, then a provider can call the callback
+ * multiple times if the value is changed, if this is the case the provider should pass an `unsubscribe`
+ * function to the callback which requesters can invoke to indicate they no longer wish to receive these updates.
+ */
+export class ContextRequestEvent<T extends UnknownContext> extends Event {
+  context: T;
+  callback: ContextCallback<ContextType<T>>;
+  subscribe?: boolean;
+
+  public constructor(
+    context: T,
+    callback: ContextCallback<ContextType<T>>,
+    subscribe?: boolean,
+  ) {
+    super("context-request", { bubbles: true, composed: true });
+
+    this.context = context;
+    this.callback = callback;
+    this.subscribe = subscribe;
+  }
+}
+
+declare global {
+  interface HTMLElementEventMap {
+    /**
+     * A 'context-request' event can be emitted by any element which desires
+     * a context value to be injected by an external provider.
+     */
+    "context-request": ContextRequestEvent<Context<unknown, unknown>>;
+  }
+}

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

@@ -1,30 +1,64 @@
-import { expect } from '@open-wc/testing';
+import { assert } from "chai";
 
-import { DOMInjector } from './dom-injector.js';
-import { INJECTABLE_MAP } from './injectable.js';
+import { INJECTOR_CTX } from "./context/injector.js";
+import {
+  ContextRequestEvent,
+  type UnknownContext,
+} from "./context/protocol.js";
+import { DOMInjector } from "./dom-injector.js";
+import { Injector } from "./injector.js";
 
-describe('DOMInjector', () => {
-  it('should attach an injector to a dom element', () => {
-    const root = document.createElement('div');
-    const app = new DOMInjector();
+describe("DOMInjector", () => {
+  it("should respond to elements looking for an injector", () => {
+    const injector = new DOMInjector();
+    injector.attach(document.body);
 
-    app.attach(root);
+    const host = document.createElement("div");
+    document.body.append(host);
 
-    const injector = INJECTABLE_MAP.get(root);
+    let parent: Injector | null = null;
 
-    expect(injector).to.equal(app);
+    host.dispatchEvent(
+      new ContextRequestEvent(INJECTOR_CTX, (i) => {
+        parent = i;
+      }),
+    );
+
+    assert.equal(parent, injector);
+
+    injector.detach();
+    host.remove();
   });
 
-  it('should remove an injector associated with a dom element', () => {
-    const root = document.createElement('div');
-    const app = new DOMInjector();
+  it("should send request looking for other injector contexts", () => {
+    const parent = new Injector();
+    const injector = new DOMInjector();
+
+    const cb = (e: ContextRequestEvent<UnknownContext>) => {
+      if (e.context === INJECTOR_CTX) {
+        e.callback(parent);
+      }
+    };
+
+    document.body.addEventListener("context-request", cb);
+
+    injector.attach(document.body);
+
+    assert.equal(injector.parent, parent);
+
+    injector.detach();
+    document.body.removeEventListener("context-request", cb);
+  });
 
-    app.attach(root);
+  it("should throw an error if attempting to attach an already attached DOMInjector", () => {
+    const injector = new DOMInjector();
 
-    expect(INJECTABLE_MAP.get(root)).to.equal(app);
+    const el = document.createElement("div");
 
-    app.detach(root);
+    injector.attach(el);
 
-    expect(INJECTABLE_MAP.get(root)).to.equal(undefined);
+    assert.throw(() => {
+      injector.attach(el);
+    });
   });
 });

package/src/lib/dom-injector.ts

@@ -1,12 +1,54 @@
-import { INJECTABLE_MAP } from './injectable.js';
-import { Injector } from './injector.js';
+import { INJECTOR_CTX } from "./context/injector.js";
+import {
+  ContextRequestEvent,
+  type UnknownContext,
+} from "./context/protocol.js";
+import { Injector } from "./injector.js";
 
 export class DOMInjector extends Injector {
-  attach(root: HTMLElement) {
-    INJECTABLE_MAP.set(root, this);
+  #element: HTMLElement | null = null;
+  #controller: AbortController | null = null;
+
+  get isAttached(): boolean {
+    return this.#element !== null && this.#controller !== null;
+  }
+
+  attach(element: HTMLElement): void {
+    if (this.isAttached) {
+      throw new Error(
+        `This DOMInjector is already attached to ${this.#element}. Detach first before attaching again`,
+      );
+    }
+
+    this.#element = element;
+    this.#controller = new AbortController();
+
+    this.#element.addEventListener(
+      "context-request",
+      (e: ContextRequestEvent<UnknownContext>) => {
+        if (e.context === INJECTOR_CTX) {
+          if (e.target !== element) {
+            e.stopPropagation();
+
+            e.callback(this);
+          }
+        }
+      },
+      { signal: this.#controller.signal },
+    );
+
+    this.#element.dispatchEvent(
+      new ContextRequestEvent(INJECTOR_CTX, (parent) => {
+        this.parent = parent;
+      }),
+    );
   }
 
-  detach(root: HTMLElement) {
-    INJECTABLE_MAP.delete(root);
+  detach(): void {
+    if (this.#controller) {
+      this.#controller.abort();
+    }
+
+    this.#element = null;
   }
 }

package/src/lib/inject.test.ts

@@ -1,30 +1,17 @@
-import { expect } from '@open-wc/testing';
+import { assert } from "chai";
 
-import { inject } from './inject.js';
-import { injectable } from './injectable.js';
-import { Injector } from './injector.js';
-import { StaticToken } from './provider.js';
+import { inject } from "./inject.js";
+import { injectable } from "./injectable.js";
+import { Injector } from "./injector.js";
+import { StaticToken } from "./provider.js";
 
-describe('inject', () => {
-  it('should work', () => {
-    class HelloService {}
-
-    @injectable
-    class HelloWorld extends HTMLElement {
-      hello = inject(HelloService);
-    }
-
-    customElements.define('inject-1', HelloWorld);
-
-    expect(new HelloWorld().hello()).to.be.instanceOf(HelloService);
-  });
-
-  it('should throw error if called in constructor', () => {
+it("should throw error if called in constructor", () => {
+  assert.throws(() => {
     class FooService {
-      value = '1';
+      value = "1";
     }
 
-    @injectable
+    @injectable()
     class BarService {
       foo = inject(FooService);
 
@@ -35,49 +22,53 @@ describe('inject', () => {
 
     const parent = new Injector();
 
-    try {
-      parent.inject(BarService);
-
-      throw new Error('Should not succeed');
-    } catch (err) {
-      const error = err as Error;
+    parent.inject(BarService);
+  }, "BarService is either not injectable or a service is being called in the constructor.");
+});
 
-      expect(error.message).to.equal(
-        `BarService is either not injectable or a service is being called in the constructor. \n Either add the @injectable to your class or use the [LifeCycle.onInject] callback method.`
-      );
-    }
-  });
+it("should throw error if static token is unavailable", () => {
+  assert.throws(() => {
+    const TOKEN = new StaticToken("test");
 
-  it('should use the calling injector as parent', () => {
-    class FooService {
-      value = '1';
-    }
-
-    @injectable
-    class BarService {
-      foo = inject(FooService);
-    }
+    const parent = new Injector();
 
-    const parent = new Injector([
-      {
-        provide: FooService,
-        use: class extends FooService {
-          value = '100';
-        }
-      }
-    ]);
+    parent.inject(TOKEN);
+  }, 'Provider not found for "test"');
+});
 
-    expect(parent.inject(BarService).foo().value).to.equal('100');
+it("should use the calling injector as parent", () => {
+  class FooService {
+    value = "1";
+  }
+
+  @injectable()
+  class BarService {
+    foo = inject(FooService);
+  }
+
+  const parent = new Injector({
+    providers: [
+      [
+        FooService,
+        {
+          use: class extends FooService {
+            value = "100";
+          },
+        },
+      ],
+    ],
   });
 
-  it('should inject a static token', () => {
-    const TOKEN = new StaticToken('test', () => 'Hello World');
+  assert.strictEqual(parent.inject(BarService).foo().value, "100");
+});
 
-    @injectable
-    class HelloWorld {
-      hello = inject(TOKEN);
-    }
+it("should inject a static token", () => {
+  const TOKEN = new StaticToken("test", () => "Hello World");
 
-    expect(new HelloWorld().hello()).to.equal('Hello World');
-  });
+  @injectable()
+  class HelloWorld {
+    hello = inject(TOKEN);
+  }
+
+  assert.strictEqual(new HelloWorld().hello(), "Hello World");
 });