Merge pull request #582 from universal-ember/improved-service

Improved service: support dynamic loading, await import services, explicit service RFC, better TS support -- eliminates the need to have a large number of services loaded when the app boots

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

@@ -0,0 +1,103 @@
+import { assert } from '@ember/debug';
+
+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<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: 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;
+*/
+
+/**
+ * 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';
+ *
+ * const loader = () => {
+ *   let module = await import('./foo/file/with/class.js');
+ *   return () => new module.MyState();
+ * }
+ *
+ * class Demo extends Component {
+ *   state = createAsyncService(this, loader);
+ * }
+ * ```
+ *
+ * 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 createAsyncService<Instance extends object>(
+  context: object,
+  theClass: () => Promise<Newable<Instance> | (() => Instance)>
+): ReturnType<typeof getPromiseState<unknown, Instance>> {
+  let existing = promiseCache.get(theClass);
+
+  if (!existing) {
+    existing = async () => {
+      const result = await theClass();
+
+      // Pay no attention to the lies, I don't know what the right type is here
+      return createStore(context, result as Newable<Instance>);
+    };
+
+    promiseCache.set(theClass, existing);
+  }
+
+  // Pay no attention to the TS inference crime here
+  return getPromiseState<unknown, Instance>(existing);
+}