react-app-modules - npm Package Compare versions

Comparing version 1.0.2 to 1.0.3

package.json

 {
   "name": "react-app-modules",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "main": "dist/index.js",
@@ -5,0 +5,0 @@ "types": "dist/index.d.ts",

README.md

@@ -45,9 +45,8 @@ # react-app-modules
 - [Api](#api)
+  - [AppContext](#appcontext)
+  - [createContainer](#createcontainer)
+  - [createProvider](#createprovider)
+  - [useModule](#usemodule)
 - [Development](#development)
-  - [Dependencies](#dependencies)
-  - [Build](#build)
-  - [Test](#test)
-  - [Publish](#publish)
 - [Misc](#misc)
-  - [Update README Table of Contents](#update-readme-table-of-contents)
 
@@ -94,3 +93,3 @@ <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-![Directory Structure](media/tutorial/directory-structure.png)
+![Directory Structure](https://raw.githubusercontent.com/rrogowski/react-app-modules/HEAD/media/tutorial/directory-structure.png)
 
@@ -190,3 +189,3 @@ ### Defining a Module
 
-![Type Safety](media/tutorial/type-safety.png)
+![Type Safety](https://raw.githubusercontent.com/rrogowski/react-app-modules/HEAD/media/tutorial/type-safety.png)
 
@@ -204,2 +203,3 @@ Oh yeah.
 ```typescript
+// src/App.tsx
 import React from 'react';
@@ -233,27 +233,185 @@ import { AppContext, createContainer } from 'react-app-modules';
 
-![Module Loading](media/tutorial/module-loading.png)
+![Module Loading](https://raw.githubusercontent.com/rrogowski/react-app-modules/HEAD/media/tutorial/module-loading.png)
 
 And then displays a result:
 
-![Finished Result](media/tutorial/finished-result.png)
+![Finished Result](https://raw.githubusercontent.com/rrogowski/react-app-modules/HEAD/media/tutorial/finished-result.png)
 
 ## Api
 
-TODO: More detailed overview of the Api methods.
+The examples that follow in this section assume that the following
+modules are defined (extending the `react-app-modules` internal types):
 
+```typescript
+// src/modules/symbols.ts
+export const Api = Symbol('Api');
+export const Logger = Symbol('Logger');
+
+declare module 'react-app-modules' {
+  interface Types {
+    AppModules: {
+      [Api]: {
+        doSomething(): Promise<void>;
+      };
+      [Logger]: {
+        log(message: string): void;
+      };
+    };
+  }
+}
+```
+
+### AppContext
+
+**Description**
+
+Provides module implementations to your components at
+runtime without having to pass props around. For more information,
+see: [Context](https://reactjs.org/docs/context.html).
+
+**Props**
+
+- `value`: a container created via `createContainer`
+
+**Example Usage**
+
+```typescript
+// src/App.tsx
+import React from 'react';
+import { AppContext } from 'react-app-modules';
+
+import Example from './components/example';
+import { container } from './modules/container';
+
+const App = () => (
+  <AppContext.Provider value={container}>
+    <Example />
+  </AppContext.Provider>
+);
+
+export default App;
+```
+
+### createContainer
+
+**Description**
+
+Maps a set of module symbols to their respective providers.
+The result is passed to the `AppContext.Provider` component
+as a `value` prop.
+
+**Params**
+
+- `providers`: an object whose keys are the set of all defined module symbols
+and whose values are a set of providers for those modules
+
+**Example Usage**
+
+```typescript
+// src/modules/container.ts
+import { createContainer } from 'react-app-modules';
+
+import { Api, Logger } from './symbols';
+import { provideApi, provideLogger } from './providers';
+
+export const container = createContainer({
+  [Api]: provideApi,
+  [Logger]: provideLogger,
+});
+```
+
+### createProvider
+
+**Description**
+
+Defines an implementation associated with a module symbol. Modules
+may have dependencies on other modules, but circular dependencies are
+prohibited.
+
+**Params**
+
+- `symbol`: the module symbol that we are defining an implementation for
+- `dependencySymbols`: an array of module symbols that this module depends on
+- `implementation`: a callback function returning an observable whose value
+implements this module's interface
+
+`implementation` is called when all `dependencySymbols` have been resolved.
+It can take the following parameters:
+
+  - `dependencies`: an object whose keys are the set of all `dependencySymbols`
+  and whose values implement the dependency interfaces
+
+**Example Usage**
+
+```typescript
+// src/modules/providers.ts
+import { createProvider } from 'react-app-modules';
+
+import { Api, Logger } from './symbols';
+
+// Provider without dependencies
+export const provideLogger = createProvider(Logger, [], () => of({
+  log: (message) => console.log(message),
+}));
+
+// Provider with dependencies
+export const provideApi = createProvider(Api, [Logger], ({ [Logger]: logger }) => of({
+  doSomething: () => {
+    logger.log('doing something...');
+     return Promise.resolve();
+  },
+}));
+```
+
+### useModule
+
+**Description**
+
+React hook that returns an object implementing the interface defined
+for the provided module symbol. Returns `null` if the module has not
+been resolved yet.
+
+**Params**
+
+- `symbol`: the module symbol we want to use in this component
+
+**Example Usage**
+
+```typescript
+// src/components/example.tsx
+import React from 'react';
+import { useModule } from 'react-app-modules';
+
+import { Logger } from '../modules/symbols';
+
+const Example = () => {
+  const logger = useModule(Logger);
+
+  if (logger === null) {
+    return <span>Loading Logger Module...</span>;
+  }
+
+  logger.log(' :) ');
+
+  return <span>Check the console!</span>;
+};
+
+export default Example;
+```
+
 ## Development
 
-### Dependencies
+**Dependencies**
 
     yarn
 
-### Build
+**Build**
 
     yarn build
 
-### Test
+**Test**
 
     yarn test
 
-### Publish
+**Publish**
 
@@ -264,4 +422,4 @@ yarn publish
 
-### Update README Table of Contents
+**Update README Table of Contents**
 
     npx doctoc README.md

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

17923

increased by27.54%

Number of lines in readme file

420

increased by60.31%

No dependency changes