{"_id":"@ablestack/inversify-react","_rev":"1-e055238cf158aaa0eaa86165266fda93","name":"@ablestack/inversify-react","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@ablestack/inversify-react","version":"1.0.0","description":"A copy of Kukkimonsuta/inversify-react - Components and decorators to connect react with inversify - only intended for ablestack consumers","main":"./dist/index.js","typings":"./types/index.d.ts","scripts":{"init":"npm ci","dev":"webpack --mode development -w","prod":"npm run copycontent && webpack --mode production","copycontent":"shx rm -f dist/package.json dist/README.md && shx cp package.json README.md dist","prepublishOnly":"npm run prod","pub":"npm publish --access public","test":"jest --no-cache","test:watch":"jest --no-cache --watchAll"},"author":{"name":"jamshally","url":"https://github.com/jamshally"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/ablestack/inversify-react.git"},"keywords":["inversify","react"],"devDependencies":{"@types/jest":"^26.0.23","@types/react":"^17.0.11","@types/react-test-renderer":"^17.0.1","conditional-type-checks":"^1.0.5","inversify":"^5.1.1","jest":"^27.0.5","react":"^17.0.2","react-addons-test-utils":"^15.6.2","react-dom":"^17.0.2","react-test-renderer":"^17.0.2","reflect-metadata":"^0.1.13","shx":"^0.3.3","ts-jest":"^27.0.3","ts-loader":"^9.2.3","typescript":"^4.3.4","webpack":"^5.40.0","webpack-cli":"^4.7.2"},"peerDependencies":{"inversify":"^5.1.1","react":"^16.3.0 || ^17.0.0"},"gitHead":"02fb061850d261a9fc2df7cc1bda0b5f3a0d436f","bugs":{"url":"https://github.com/ablestack/inversify-react/issues"},"homepage":"https://github.com/ablestack/inversify-react#readme","_id":"@ablestack/inversify-react@1.0.0","_nodeVersion":"15.14.0","_npmVersion":"7.7.6","dist":{"integrity":"sha512-+rGLlIfPukfXVL92D1XUWbb5Z5HozFVwigiVIIZNGG+lAmL9fW8KwjfcCEWbc40vfCAYq+QU9oDhXAbjwTPqyQ==","shasum":"d00ff28a3be101a5c6a97a55959c058d8853de5a","tarball":"https://registry.npmjs.org/@ablestack/inversify-react/-/inversify-react-1.0.0.tgz","fileCount":14,"unpackedSize":68976,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJg3aN3CRA9TVsSAnZWagAADs4P/A1ItmsKZRFVt9LKQG2W\njAySlg5UpvdaceD7gftO/TQlhi94OO2xwOwwD6WZVKUZQfZfwsVF+0uH258c\n7VFrEw4/IxlVHEcouXyKLALmwPl+5RbAKmLVFxOKFeHLG2h5YT4r2MM4TUTg\nYKZlAcVaEq2tFM5VDI4FIcwXMyUWvMMjfGIKB163HClB3sGTQ1NW7g7iEY79\nX8QFVsnMptDoaBerj7j13w9fOf9wXiqtP0qVjmIFp0sPB80mZ7Fp6MOoxD2i\njfSjLYzxS+smmSlAIR4WIu6Qkj3a+UyutrDw6L2VVV4jFukHfFKifjrw9MLj\nA1jjj2IYfUcEuidchteZrVfBpZ+6E5eDL58k3qkkMKcyOthBB8LKk4f4n0Ps\nFKbEUabmkWdI27Bfw0q4cSGPBwvdVIPVixFWzZKOpHXM+zK2WA5zD8dvBobl\nSh3zGgUdfM1L8wtYRVqk+A4nTMJ+IKkCmi4hfr8M7RlGcShFRb8W7zQQmIkX\n1pe3Gr2wjHJKoqwXlYC+tEoI8u+HS4MS6XqiNS8M7WsS34wgE8azSvKUs5w5\nPLZdv39JfEHFarhoJpdWQhH5OkbulZowW7KsA8A2JPseYOs5O38ewKnEjLKf\ndZS/QqFTMsHTt0UwhvK8eJx2DcofuZX66wvqKyRRNdmgE1lQ/MZl8y0fjWbj\nseF8\r\n=DxtR\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQD/obZ+HHaP8w/NxLv7TvNRCboO3dxiHw4QhPRiNsDcxQIhAMWRsHTA4/1FYob6Znhlf4LEjxRBUOU1g6BpKGjysgKO"}]},"_npmUser":{"name":"jamshally","email":"ahrndee@gmail.com"},"directories":{},"maintainers":[{"name":"jamshally","email":"ahrndee@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/inversify-react_1.0.0_1625138038524_0.881424646096713"},"_hasShrinkwrap":false}},"time":{"created":"2021-07-01T11:13:58.157Z","1.0.0":"2021-07-01T11:13:58.663Z","modified":"2022-04-04T10:59:49.669Z"},"maintainers":[{"name":"jamshally","email":"ahrndee@gmail.com"}],"description":"A copy of Kukkimonsuta/inversify-react - Components and decorators to connect react with inversify - only intended for ablestack consumers","homepage":"https://github.com/ablestack/inversify-react#readme","keywords":["inversify","react"],"repository":{"type":"git","url":"git+https://github.com/ablestack/inversify-react.git"},"author":{"name":"jamshally","url":"https://github.com/jamshally"},"bugs":{"url":"https://github.com/ablestack/inversify-react/issues"},"license":"Apache-2.0","readme":"# Fork Note\r\n\r\nThis is a forked copy of the excellent [inversify-react library](https://github.com/Kukkimonsuta/inversify-react), intended for ablestack project consumption only. The primary driver for forking this library is change-control. The library is not well-established enough to include in production projects directly without an additional layer of abstraction and code-review (which this fork is intended to provide for ablestack projects)\r\n\r\nAll the following documentation is from the original [inversify-react project](https://github.com/Kukkimonsuta/inversify-react)\r\n\r\n# inversify-react\r\n\r\n[![npm version](https://badge.fury.io/js/inversify-react.svg)](https://badge.fury.io/js/inversify-react)\r\n\r\n![npm peer dependency version](https://img.shields.io/npm/dependency-version/inversify-react/peer/inversify)\r\n![npm peer dependency version](https://img.shields.io/npm/dependency-version/inversify-react/peer/react)\r\n\r\n---\r\n\r\nHooks and decorators for [InversifyJS](http://inversify.io) + [React](https://reactjs.org).\r\n\r\n---\r\n\r\nTable of Contents\r\n\r\n- [Motivation](#motivation)\r\n- [Installation](#installation)\r\n- [Usage overview](#usage-overview)\r\n- [Provider](#provider)\r\n- [React hooks](#react-hooks)\r\n  - [useInjection](#useinjection)\r\n  - [useOptionalInjection](#useoptionalinjection)\r\n  - [useContainer](#usecontainer)\r\n  - [useAllInjections](#useallinjections)\r\n- [React component decorators (for classes)](#react-component-decorators--for-classes-)\r\n  - [@resolve](#-resolve)\r\n  - [@resolve.optional](#-resolveoptional)\r\n- [Notes, tips](#notes--tips)\r\n\r\n## Motivation\r\n\r\n**TL;DR**:\r\n\r\n1. InversifyJS, as IoC container, is great for automatic DI\r\n2. use it also in React\r\n\r\n## Installation\r\n\r\n- `npm install --save inversify-react`\r\n- `yarn add inversify-react`\r\n\r\n...on top of your project with other modules already installed and configured\r\n\r\n```\r\nreact\r\ninversify\r\nreflect-metadata\r\n```\r\n\r\nKeep in mind that Inversify uses decorators, which requires some setup for your build process.\r\n\r\nRead more about decorators:\r\n\r\n- https://github.com/inversify/InversifyJS#installation\r\n- https://github.com/loganfsmyth/babel-plugin-transform-decorators-legacy\r\n- https://www.typescriptlang.org/docs/handbook/decorators.html\r\n\r\n`inversify-react` also uses decorators, but only when used in Class Components.\r\n\r\n## Usage overview\r\n\r\nUsage is pretty similar to [React Context](https://reactjs.org/docs/context.html).\r\n\r\n1. Wrap React component tree with `Provider` and `Container` from `inversify-react` – just like [React Context.Provider](https://reactjs.org/docs/context.html#contextprovider)\r\n\r\n   ```js\r\n   import { Provider } from 'inversify-react';\r\n   ...\r\n\r\n   <Provider container={myContainer}>\r\n       ...\r\n   </Provider>\r\n   ```\r\n\r\n2. Use dependencies from that container in child components\r\n\r\n   ```ts\r\n   import { resolve, useInjection } from 'inversify-react';\r\n   ...\r\n\r\n   // In functional component – via hooks\r\n   const ChildComponent: React.FC = () => {\r\n       const foo = useInjection(Foo);\r\n       ...\r\n   };\r\n\r\n   // or in class component – via decorated fields\r\n   class ChildComponent extends React.Component {\r\n       @resolve\r\n       private readonly foo: Foo;\r\n       ...\r\n   }\r\n   ```\r\n\r\n## Provider\r\n\r\n```js\r\n<Provider container={myContainer}>...</Provider>\r\n```\r\n\r\n- provides contextual IoC container for children, similar to [React Context.Provider](https://reactjs.org/docs/context.html#contextprovider)\r\n- can automatically establish [hierarchy of containers](https://github.com/inversify/InversifyJS/blob/master/wiki/hierarchical_di.md) in React tree when you use multiple Providers (e.g. in a big modular app)\r\n- props:\r\n  - `container` - container instance or container factory function\r\n  - `standalone` - (optional prop, `false` by default) whether to skip [hierarchy of containers](https://github.com/inversify/InversifyJS/blob/master/wiki/hierarchical_di.md). Could be useful if you already control container hierarchy and would like to ignore React-tree-based hierarchy.\r\n\r\n```ts\r\nimport * as React from \"react\";\r\nimport { Container } from \"inversify\";\r\nimport { Provider } from \"inversify-react\";\r\n\r\n// in functional component\r\nconst AppOrModuleRoot: React.FC = () => {\r\n  return (\r\n    <Provider\r\n      container={() => {\r\n        const container = new Container();\r\n        container.bind(Foo).toSelf();\r\n        container.bind(Bar).toSelf();\r\n        return container;\r\n      }}\r\n    >\r\n      {/*...children...*/}\r\n    </Provider>\r\n  );\r\n};\r\n\r\n// or class component\r\nclass AppOrModuleRoot extends React.Component {\r\n  // you can create and store container instance explicitly,\r\n  // or use factory function like in functional component example above\r\n  private readonly container = new Container();\r\n\r\n  constructor(props: {}, context: {}) {\r\n    super(props, context);\r\n\r\n    const { container } = this;\r\n    container.bind(Foo).toSelf();\r\n    container.bind(Bar).toSelf();\r\n  }\r\n\r\n  render() {\r\n    return <Provider container={this.container}>{/*...children...*/}</Provider>;\r\n  }\r\n}\r\n```\r\n\r\n## React hooks\r\n\r\n### useInjection\r\n\r\n```ts\r\nconst foo = useInjection(Foo);\r\n```\r\n\r\n- very similar to [React.useContext](https://reactjs.org/docs/hooks-reference.html#usecontext) hook, resolves dependency by id\r\n\r\n### useOptionalInjection\r\n\r\n```ts\r\n// e.g. Foo and Bar are not bound\r\nconst foo = useOptionalInjection(Foo); // will return undefined\r\n// or\r\nconst bar = useOptionalInjection(Bar, () => \"defaultBar\"); // will return 'defaultBar'\r\n```\r\n\r\n- resolves [optional dependency](https://github.com/inversify/InversifyJS/blob/master/wiki/optional_dependencies.md)\r\n- default value can be defined via lazy resolving function (2nd argument)\r\n  ```ts\r\n  const foo = useOptionalInjection(Foo, () => myDefault);\r\n  // foo === myDefault\r\n  //   ^ Foo | typeof myDefault\r\n  ```\r\n  That function conveniently receives container as argument, so you could instantiate your _default_ using container (e.g. if it has dependencies)\r\n  ```ts\r\n  const foo = useOptionalInjection(Foo, (container) => container.resolve(X));\r\n  ```\r\n\r\n### useContainer\r\n\r\n```ts\r\nconst container = useContainer();\r\n// or\r\nconst foo = useContainer((container) => container.resolve(Foo));\r\n```\r\n\r\n- low-level hook, resolves container itself\r\n- has overload with callback to immediately resolve value from container, so could be used for more exotic API, e.g. [named](https://github.com/inversify/InversifyJS/blob/master/wiki/named_bindings.md) or [tagged](https://github.com/inversify/InversifyJS/blob/master/wiki/tagged_bindings.md) bindings\r\n\r\n### useAllInjections\r\n\r\n```ts\r\nconst bars = useAllInjections(Bar);\r\n```\r\n\r\n- @see [multi-inject](https://github.com/inversify/InversifyJS/blob/master/wiki/multi_injection.md)\r\n\r\nFor more examples, please refer to tests: [test/hooks.tsx](./test/hooks.tsx)\r\n\r\n## React component decorators (for classes)\r\n\r\n### @resolve\r\n\r\n```ts\r\n@resolve\r\nfoo: Foo;\r\n\r\n// or strict and semantic, see tips below\r\n@resolve\r\nprivate readonly foo!: Foo;\r\n```\r\n\r\n- resolves service from container\r\n- requires `reflect-metadata` and `emitDecoratorMetadata`\r\n\r\n```ts\r\n// or pass service identifier explicitly\r\n// e.g. if you deal with interfaces and/or don't want to use field type (via reflect-metadata)\r\n@resolve(IFooServiceId)\r\nprivate readonly foo!: IFoo;\r\n```\r\n\r\n### @resolve.optional\r\n\r\n```ts\r\n@resolve.optional\r\nprivate readonly foo?: Foo;\r\n```\r\n\r\n- tries to resolve service from container, but returns `undefined` if service cannot be obtained\r\n- requires `reflect-metadata` and `emitDecoratorMetadata`\r\n\r\n`@resolve.optional(serviceId, defaultValue?)`\r\n\r\n- obtains service from container passed down in the React tree, returns `defaultValue` if service cannot be obtained\r\n\r\n```ts\r\nclass ChildComponent extends React.Component {\r\n    @resolve\r\n    private readonly foo!: Foo;\r\n\r\n    @resolve(Bar)\r\n    private readonly bar!: Bar;\r\n\r\n    @resolve.optional(Baz)\r\n    private readonly opt?: Baz;\r\n\r\n    ...\r\n}\r\n\r\n// you can also use dependency in constructor,\r\n// just don't forget to call super with context\r\n// @see https://github.com/facebook/react/issues/13944\r\nconstructor(props: {}, context: {}) {\r\n    super(props, context);\r\n    console.log(this.foo.name);\r\n}\r\n```\r\n\r\n## Notes, tips\r\n\r\n1. \\[TypeScript tip\\] `private readonly` for `@resolve`-ed fields is not required, but technically it's more accurate, gives better semantics and all.\r\n2. \\[TypeScript tip\\] `!` for `@resolve`-ed fields is needed for [strictPropertyInitialization](https://www.typescriptlang.org/tsconfig#strictPropertyInitialization) / [strict](https://www.typescriptlang.org/tsconfig#strict) flags (_which are highly recommended_).\r\n3. \\[InversifyJS tip\\] If you're binding against interface, then it might be more comfortable to collocate service identifier and type. With typed service identifier you get better type inference and less imports. Way better DX compared to using strings as identifiers.\r\n\r\n   ```ts\r\n   export interface IFoo {\r\n     // ...\r\n   }\r\n   export namespace IFoo {\r\n     export const $: interfaces.ServiceIdentifier<IFoo> = Symbol(\"IFoo\");\r\n   }\r\n   ```\r\n\r\n   ```ts\r\n   container.bind(IFoo.$).to(...);\r\n   //            ^ no need to specify generic type,\r\n   //              type gets inferred from explicit service identifier\r\n   ```\r\n\r\n   ```ts\r\n   // in constructor injections (not in React Components, but in services/stores/etc)\r\n   constructor(@inject(IFoo.$) foo: IFoo)\r\n\r\n   // in React Class component\r\n   @resolve(IFoo.$)\r\n   private readonly foo!: IFoo; // less imports and less chance of mix-up\r\n\r\n   // in functional component\r\n   const foo = useInjection(IFoo.$); // inferred as IFoo\r\n\r\n   ```\r\n","readmeFilename":"README.md"}