Progress

Author: NullVoxPopuli

docs-app/public/docs/6-utils/createAsyncService.md

@@ -0,0 +1,85 @@
+# createAsyncService
+
+This utility will create a service using a class definition similar to what is described in [RFC#502](https://github.com/emberjs/rfcs/pull/502) for explicit service injection -- no longer using strings. This allows module graphs to shake out services that aren't used until they are _needed_.
+
+The difference with `createService` is that `createAsyncService` takes a _stable reference_ to a function that will eventually return a class definition. 
+
+This can be useful for importing services that may themselves import many things, or large dependencies.
+
+
+## Setup
+
+```bash 
+pnpm add ember-primitives
+```
+
+Introduced in [0.47.0](https://github.com/universal-ember/ember-primitives/releases/tag/v0.47.0-ember-primitives)
+
+
+## Usage
+
+```js
+import { createAsyncService } from 'ember-primitives/service';
+
+// This function is the key that all consumers should use to get the same instance
+const getService = async () => {
+  let module = await import('./service/from/somewhere');
+  return module.MyState;
+}
+
+class Demo extends Component {
+  state = createAsyncService(this, getService);
+}
+```
+
+### With Arguments
+
+```js
+import { createAsyncService } from 'ember-primitives/service';
+
+class MyState {
+  constructor(/* .. */ ) { /* ... */ }
+}
+
+// in another file
+
+// This function is the key that all consumers should use to get the same instance
+const getService = async (/* args here */ ) => {
+  let module = await import('./service/from/somewhere');
+  return () => new module.MyState(/* args */ );
+}
+
+class Demo extends Component {
+  state = createAsyncService(this, () => getService(/* ... */));
+}
+```
+
+
+### Accessing Services and handling cleanup 
+
+Like with [`link`][reactiveweb-link], use of services and `registerDestructor` is valid:
+```js
+import { service } from '@ember/service';
+import { createAsyncService } from 'ember-primitives/service';
+
+class MyState {
+  @service router;
+
+  constructor(/* .. */) { 
+    registerDestructor(this, () => {
+      // cleanup runs when Demo is torn down
+    });  
+  }
+}
+
+// in another file
+class Demo extends Component {
+  state = createAsyncService(this, getService);
+}
+```
+
+However, note that the same restrictions as with `link` apply: services may not be accessed in the constructor.
+
+And even that caveat can be undone if what you need is passed in to your service's constructor.
+
+[reactiveweb-link]: https://reactive.nullvoxpopuli.com/functions/link.link.html 

docs-app/public/docs/6-utils/createService.md

@@ -0,0 +1,80 @@
+# createService
+
+This utility will create a service using a class definition similar to what is described in [RFC#502](https://github.com/emberjs/rfcs/pull/502) for explicit service injection -- no longer using strings. This allows module graphs to shake out services that aren't used until they are _needed_.
+
+
+## Setup
+
+```bash 
+pnpm add ember-primitives
+```
+
+Introduced in [0.47.0](https://github.com/universal-ember/ember-primitives/releases/tag/v0.47.0-ember-primitives)
+
+
+## Usage
+
+```js
+import { createService } from 'ember-primitives/service';
+
+class MyState {
+  // @services are allowed here
+}
+
+class Demo extends Component {
+  // lazyily created upon access of `foo`
+  get foo() {
+    return createService(this, MyState);
+  }
+
+  // or eagrly created when `Demo` is created
+  state = createService(this, MyState);
+}
+```
+
+### With Arguments
+
+```js
+import { createService } from 'ember-primitives/service';
+
+class MyState {
+  constructor(/* .. */ ) { /* ... */ }
+}
+
+class Demo extends Component {
+  get state() {
+    return createService(this, () => new MyState(1, 2));
+  }
+}
+```
+
+### Accessing Services and handling cleanup 
+
+Like with [`link`][reactiveweb-link], use of services and `registerDestructor` is valid:
+```js
+import { service } from '@ember/service';
+import { createService } from 'ember-primitives/service';
+
+class MyState {
+  @service router;
+
+  constructor(/* .. */) { 
+    registerDestructor(this, () => {
+      // cleanup runs when Demo is torn down
+    });  
+  }
+}
+
+class Demo extends Component {
+  // or 
+  get foo() {
+    return createService(this, () => new MyState(/* ... */));
+  }
+}
+```
+
+However, note that the same restrictions as with `link` apply: services may not be accessed in the constructor.
+
+And even that caveat can be undone if what you need is passed in to your service's constructor.
+
+[reactiveweb-link]: https://reactive.nullvoxpopuli.com/functions/link.link.html 

ember-primitives/src/service.ts

@@ -1,84 +1,100 @@
 import { assert } from '@ember/debug';
-import { service as emberService } from '@ember/service';
 
+import { getPromiseState } from 'reactiveweb/get-promise-state';
+
+import { createStore } from './store.ts';
+import { findOwner } from './utils.ts';
+
+import type { Newable } from './type-utils.ts';
+
+/*
 import type { Newable } from './type-utils.ts';
 import type { Registry } from '@ember/service';
 import type Service from '@ember/service';
 
 type Decorator = ReturnType<typeof emberService>;
 
-export function service<Key extends keyof Registry>(
-  context: object,
-  serviceName: Key
-): Registry[Key] & Service;
+// export function service<Key extends keyof Registry>(
+//   context: object,
+//   serviceName: Key
+// ): Registry[Key] & Service;
 export function service<Class extends object>(
   context: object,
   serviceDefinition: Newable<Class>
 ): Class;
 export function service<Class extends object>(serviceDefinition: Newable<Class>): Decorator;
-export function service<Key extends keyof Registry>(serviceName: string): Decorator;
-export function service(prototype: object, name: string | symbol, descriptor?: unknown): void;
+export function service<Key extends keyof Registry>(serviceName: Key): Decorator;
+export function service(prototype: object, name: string | symbol, descriptor: unknown): void;
+export function service<Value, Result>(
+  context: object,
+  fn: Parameters<typeof getPromiseState<Value, Result>>[0]
+): ReturnType<typeof getPromiseState<Value, Result>>;
+export function service<Value, Result>(
+  fn: Parameters<typeof getPromiseState<Value, Result>>[0]
+): Decorator;
+*/
 
 /**
- * Lazily instantiate a service
+ * Instantiates a class once per application instance.
+ *
+ *
+ */
+export function createService<Instance extends object>(
+  context: object,
+  theClass: Newable<Instance> | (() => Instance)
+): Instance {
+  const owner = findOwner(context);
+
+  assert(
+    `Could not find owner / application instance. Cannot create a instance tied to the application lifetime without the application`,
+    owner
+  );
+
+  return createStore(owner, theClass);
+}
+
+const promiseCache = new WeakMap<() => any, unknown>();
+
+/**
+ * Lazily instantiate a service.
  *
  * This is a replacement / alternative API for ember's `@service` decorator from `@ember/service`.
  *
  * For example
  * ```js
  * import { service } from 'ember-primitives/service';
  *
- * class State {
- *   @service router; // also works with the traditional string usage
- * }
+ * const loader = () => import('./foo/file/with/class.js');
  *
  * class Demo extends Component {
- *   @service(State) state;
+ *   state = createAsyncService(this, loader);
  * }
  * ```
  *
- * Additionally for better TypeScript type-inference, this alternate invocation syntax is allowed:
- * ```js
- * class Demo extends Component {
- *   state = service(this, State);
- * }
+ * The important thing is for repeat usage of `createAsyncService` the second parameter,
+ * (loader in this case), must be shared between all usages.
+ *
+ * This is an alternative to using `createStore` inside an await'd component,
+ * or a component rendered with [`getPromiseState`](https://reactive.nullvoxpopuli.com/functions/get-promise-state.getPromiseState.html)
  * ```
  */
-export function service(...args: any[]) {
-  /**
-   * Stage 1 / Legacy Decorators (original ember service)
-   */
-  if (args.length === 3) {
-    return emberService(...(args as Parameters<typeof emberService>));
-  }
+export function createAsyncService<Instance extends object>(
+  context: object,
+  theClass: () => Promise<Newable<Instance>> | (() => Promise<() => Instance | Newable<Instance>>)
+): ReturnType<typeof getPromiseState<unknown, Instance>> {
+  let existing = promiseCache.get(theClass);
 
-  /**
-   * This is either:
-   * - spec decorator
-   * - or non-decorator usage (requiring a this parameter to be passed for the first)
-   */
-  if (args.length === 2) {
-    if (typeof args[1] === 'object' && args[1]) {
-      if ('kind' in args[1]) {
-        assert(
-          `TC39 Spec decorators are not yet supported. If you see this error, please open an issue at https://github.com/universal-ember/ember-primitives/ -- also!, congratulations for being an early adopter of real decorators!`
-        );
-      }
-    }
+  if (!existing) {
+    existing = async () => {
+      const result = await theClass();
 
-    return inlineSerice(...args);
-  }
+      // Pay no attention to the lies, I don't know what the right type is here
+      return createStore(context, result as Newable<Instance>);
+    };
 
-  if (args.length === 1) {
-    /**
-     * Traditional string-based service usage
-     */
-    if (typeof args[0] === 'string') {
-      return emberService(...args);
-    }
+    promiseCache.set(theClass, existing);
   }
-}
-
-function concreteService<Class>(definition: Newable<Class>): Decorator {}
 
-function inlineService(context: object, service: string | object | Function) {}
+  // Pay no attention to the TS inference crime here
+  return getPromiseState<unknown, Instance>(existing);
+}