feat: nodemodule and global types

NodeModule type lets you resolve a NodeModule using just a type
Global type lets you resolve a global variable using just a type

closes #90

Author: Jack Ellis

README.md

@@ -17,6 +17,7 @@ Jpex is an Inversion of Control framework. Register dependencies on a container,
 - [Consuming Dependencies](#consuming-dependencies)
 - [API](#api)
   - [jpex](#jpex)
+  - [types](#types)
 - [caveats](#caveats)
 - [react](#react)
 - [Vanilla JS mode](#vanilla-js-mode)
@@ -303,6 +304,46 @@ Clears the cache of resolved factories. If you provide a type, that specific fac
 
 Under the hood jpex converts types into strings for runtime resolution. If you want to get that calculated string for whatever reason, you can use `jpex.infer`
 
+### Types
+#### Jpex
+This is the type definition for the jpex container
+
+#### NodeModule
+This is a special type that lets you automatically inject a node module with type inference.
+
+For example:
+```ts
+import jpex, { NodeModule } from 'jpex';
+
+// this will resolve to the fs module without you having to explicitly register it as a dependency
+const fs = jpex.resolve<NodeModule<'fs'>>();
+```
+
+The default return type will be `any` but you can specify one explicitly with the second type parameter:
+```ts
+import type fstype from 'fs';
+import jpex, { NodeModule } from 'jpex';
+
+const fs = jpex.resolve<NodeModule<'fs', typeof fstype>>();
+```
+
+#### Global
+This is another special type that lets you automatically inject a global property with type inference.
+
+For built-in types you can do this without any helpers:
+```ts
+import jpex from 'jpex';
+
+const navigator = jpex.resolve<Navigator>();
+```
+
+But for custom globals, or properties that don't have built-in types, you can use the `Global` type:
+```ts
+import jpex, { Global } from 'jpex';
+
+const analytics = jpex.resolve<Global<'ga', Function>>();
+```
+
 ## caveats
 There are a few caveats to be aware of:
 - Only named types/interfaces are supported so you can't do `jpex.factory<{}>()`
@@ -335,22 +376,18 @@ const MyComponent = (props) => {
 And this pattern also makes it really easy to isolate a component from its side effects when writing tests:
 
 ```tsx
-import { Provider, useJpex } from 'jpex';
+import base, { Provider, useJpex } from 'jpex';
 // create a stub for the SaveData dependency
 const saveData = stub();
+// create a new container
+const jpex = base.extend();
+// register our stub dependency
+jpex.constant<SaveData>(saveData);
 
 render(
-  // the Provider component will create a new jpex instance
-  <Provider>
-    {() => {
-      // grab jpex - it will be isolated to this context only
-      const jpex = useJpex();
-      // register our stub dependency
-      jpex.constant<SaveData>(saveData);
-
-      // when we render MyComponent, it will be given our stubbed dependency
-      return (<MyComponent/>);
-    }}
+  <Provider value={jpex}>
+      {/* when we render MyComponent, it will be given our stubbed dependency */}
+    <MyComponent/>
   </Provider>
 );
 
@@ -364,6 +401,8 @@ expect(saveData.called).to.be.true;
 Perhaps you hate typescript, or babel, or both. Or perhaps you don't have the luxury of a build pipeline in your application. That's fine because jpex supports vanilla js as well, you just have to explicitly state your dependencies up front:
 
 ```ts
+const { jpex } = require('jpex');
+
 jpex.constant('foo', 'foo');
 jpex.factory('bah', [ 'foo' ], (foo) => foo + 'bah');
 

src/__tests__/js/resolve.test.ts

@@ -127,6 +127,19 @@ test('prefers a registered dependency over a node module', (t) => {
   t.is(value, fakeFs);
 });
 
+test('does not resolve a node module when disabled', (t) => {
+  const { jpex: base } = t.context;
+  const jpex = base.extend({
+    nodeModules: false,
+    optional: true,
+  });
+
+  const value = jpex.resolve('fs');
+
+  t.not(value, fs);
+  t.is(value, void 0);
+});
+
 test('resolves a global property', (t) => {
   const { jpex } = t.context;
 

src/__tests__/ts/resolve.test.ts

@@ -2,12 +2,7 @@
 /* eslint-disable no-invalid-this */
 import anyTest, { TestInterface } from 'ava';
 import fs from 'fs';
-import base, { JpexInstance } from '../..';
-
-/* eslint-disable @typescript-eslint/no-unused-vars*/
-type NodeModuleType<S extends string, T = any> = T;
-type GlobalType<S extends string, T = any> = T;
-/* eslint-enable @typescript-eslint/no-unused-vars*/
+import base, { JpexInstance, NodeModule, Global } from '../..';
 
 const test: TestInterface<{
   jpex: JpexInstance,
@@ -139,26 +134,38 @@ test('resolves array-like dependencies', (t) => {
   t.is(value, 'hello');
 });
 
-test.failing('resolves a node module', (t) => {
+test('resolves a node module', (t) => {
   const { jpex } = t.context;
-  type Fs = NodeModuleType<'fs', typeof fs>;
-  const value = jpex.resolve<Fs>();
+
+  const value = jpex.resolve<NodeModule<'fs'>>();
 
   t.is(value, fs);
 });
 
 test('prefers a registered dependency over a node module', (t) => {
   const { jpex } = t.context;
-  type Fs = NodeModuleType<'fs', typeof fs>;
   const fakeFs = {};
-  jpex.factory<Fs>(() => fakeFs as any);
+  jpex.factory<NodeModule<'fs'>>(() => fakeFs);
 
-  const value = jpex.resolve<Fs>();
+  const value = jpex.resolve<NodeModule<'fs'>>();
 
   t.not(value, fs);
   t.is(value, fakeFs);
 });
 
+test('does not resolve a node module when disabled', (t) => {
+  const { jpex: base } = t.context;
+  const jpex = base.extend({
+    nodeModules: false,
+    optional: true,
+  });
+
+  const value = jpex.resolve<NodeModule<'fs'>>();
+
+  t.not(value, fs);
+  t.is(value, void 0);
+});
+
 test('resolves a global property', (t) => {
   const { jpex } = t.context;
 
@@ -178,13 +185,12 @@ test('prefers a registered dependency over a global', (t) => {
   t.is(value, fakeWindow);
 });
 
-test.failing('allows a custom global variable', (t) => {
+test('allows a custom global variable', (t) => {
   const { jpex } = t.context;
   // @ts-ignore
   global.foo = 'hello';
-  type Foo = GlobalType<'foo', any>;
 
-  const value = jpex.resolve<Foo>();
+  const value = jpex.resolve<Global<'foo'>>();
 
   t.is(value, 'hello');
 });

src/index.ts

@@ -8,6 +8,8 @@ import type {
   FactoryOpts,
   ResolveOpts,
   ServiceOpts,
+  NodeModule,
+  Global,
 } from './types';
 
 const jpex = new Jpex() as JpexInstance;
@@ -19,12 +21,15 @@ export {
 export type {
   Lifecycle,
   JpexInstance,
+  JpexInstance as Jpex,
   SetupConfig,
   NamedParameters,
   Precedence,
   FactoryOpts,
   ServiceOpts,
   ResolveOpts,
+  NodeModule,
+  Global,
 };
 
 export default jpex;

src/resolver/utils.ts

@@ -11,7 +11,10 @@ import {
   isString,
   hasLength,
 } from '../utils';
-import { GLOBAL_TYPE_PREFIX, VOID } from '../constants';
+import {
+  GLOBAL_TYPE_PREFIX,
+  VOID,
+} from '../constants';
 
 const getFromNodeModules = (jpex: JpexInstance, target: string): Factory => {
   // in order to stop webpack environments from including every possible
@@ -63,7 +66,8 @@ const getGlobalProperty = (name: string) => {
   if (name.startsWith(GLOBAL_TYPE_PREFIX)) {
     // most global types will just be the name of the property in pascal case
     // i.e. window = Window / document = Document
-    const inferredName = name.charAt(12).toLowerCase() + name.substr(13);
+    const len = GLOBAL_TYPE_PREFIX.length;
+    const inferredName = name.charAt(len).toLowerCase() + name.substr(len + 1);
     return global[inferredName];
   }
 };

src/types/custom.ts

@@ -0,0 +1,3 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+export type NodeModule<S extends string, T = any> = T;
+export type Global<S extends string, T = any> = T;

src/types/index.ts

@@ -1,5 +1,6 @@
 export * from './JpexInstance';
 export * from './BuiltIns';
+export * from './custom';
 
 export type Lifecycle = 'application' | 'class' | 'instance' | 'none';