react-obsidian 1.1.0 → 1.2.0

package/documentation/docs/documentation/usage/Reactivity.mdx

@@ -1,116 +0,0 @@
----
-sidebar_position: 5
-title: "Reactivity"
----
-
-Obsidian is first and foremost a dependency injection library. But it also includes reactive programming features that allow you to observe changes in your data and react to them. This is useful for things like updating the UI when a value changes.
-
-## Observable
-Making a class field reactive is as simple as wrapping it with the `Observable` decorator. Observable is a data holder classes that also allows you to subscribe to changes in the data.
-
-### Create observables
-In the example below, we declare a boolean observable called `isLoggedIn`. We can then subscribe to changes in the `isLoggedIn` value and update the UI accordingly.
-
-```ts
-import { Observable } from 'react-obsidian';
-
-class UserService {
-  public isLoggedIn = new Observable(false); // The initial value is false
-}
-
-export default new UserService();
-```
-
-### Observe changes
-#### Observe changes in hooks or components
-Once you have declared an observable, you can subscribe to changes in the value by using the `useObserver` hook. This hook will return the current value of the observable and subscribe to changes in the value. When the value changes, the hook will re-render the component.
-
-```ts
-import { useObserver } from 'react-obsidian';
-import userService from './UserService';
-
-const useLogin = () => {
-  const [isLoggedIn] = useObserver(userService.isLoggedIn);
-
-  return {isLoggedIn};
-}
-```
-
-#### Observe changes imperatively
-You can also subscribe to changes in an observable imperatively by calling the `subscribe` method on the observable. This method returns a function that can be called to unsubscribe from the observable.
-
-```ts
-import userService from './UserService';
-
-const unsubscribe = userService.isLoggedIn.subscribe((isLoggedIn: boolean) => {
-  // Do something with the isLoggedIn value
-});
-```
-
-### Update Observables
-Observables expose the data they hold via a `value` property. You can update the value of an observable by setting the value of the `value` property.
-This will also trigger any subscribers to the observable.
-
-```ts
-import userService from './UserService';
-
-userService.isLoggedIn.value = true; // Update the value and notify all subscribers
-```
-
-#### Update Observables from hooks or components
-The `useObserver` hook also returns a setter function that can be used to update the value of the observable.
-
-```ts
-import { useObserver } from 'react-obsidian';
-import userService from './UserService';
-
-const useLogin = () => {
-  const [isLoggedIn, setIsLoggedIn] = useObserver(userService.isLoggedIn);
-  const onLogoutButtonPress = useCallback(() => {
-    setIsLoggedIn(false);
-  }, [setIsLoggedIn]);
-
-  return {isLoggedIn, onLogoutButtonPress};
-}
-```
-
-### Avoid recreating the initial observable
-When using the `useObserver` hook, it is important to avoid recreating the initial observable.
-
-```ts title="Avoid instantiating observables in hooks"
-const useLogin = () => {
-  const [isLoggedIn] = useObserver(new Observable(false));
-}
-```
-
-Even if the value of the observable is the same, this can cause unexpected behavior since it's instantiated on every render.
-
-To solve this, you can pass a generator function to the useObserver hook instead:
-```ts
-const useLogin = () => {
-  const [isLoggedIn] = useObserver(() => new Observable(false));
-}
-```
-
-If you pass a function to the useObserver hook, it will only be called on the first render. This ensures that the observable is only instantiated once.
-
-### Merge multiple observable sources
-`MediatorObservable` is a special type of observable that allows you to merge multiple observable sources into a single observable. This is useful for creating side effect from one or more observables.
-
-In the example below, we create a `MediatorObservable` called `downloadStatus` that will be updated when either the `networkConditions` or `batteryLevel` observables are updated. We can then subscribe to changes in the `downloadStatus` observable to update the UI or perform other side effects.
-
-```ts
-import { MediatorObservable, Observable } from 'react-obsidian';
-
-const networkConditions = new Observable<'poor' | 'strong'>();
-const batteryLevel = new Observable<'low' | 'normal'>();
-
-const downloadStatus = new MediatorObservable<'paused' | 'active'>('active')
-  .addSource(networkConditions, (condition: 'poor' | 'strong') => {
-    this.value = condition === 'poor' ? 'paused' : 'active';
-  })
-  .addSource(batteryLevel, (level: 'low' | 'normal') => {
-    this.value = level === 'low' ? 'paused' : 'active';
-  });
-
-```

package/documentation/docs/documentation/usage/ServiceLocator.mdx

@@ -1,38 +0,0 @@
----
-sidebar_position: 6
-title: "Service locator"
----
-
-## Obtaining dependencies imperatively
-
-Obsidian is an Inversion of Control container. This means that it will automatically resolve dependencies for you, and you don't need to worry about how to obtain them. However, there are times when you need to obtain a dependency imperatively, for example when you need to pass a dependency to a third-party library that doesn't support dependency injection.
-
-For these cases, you can obtain a graph instance and access the dependencies it provides imperatively. This is done by using the `Obsidian.obtain()` function which allows you to treat the graph as a Service Locator.
-
-### Example
-Consider the following graph which provides two dependencies: `fooService` and `barService` where `barService` depends on `fooService`:
-
-```ts
-import {Singleton, Graph, ObjectGraph, Provides} from 'react-obsidian';
-
-@Singleton() @Graph()
-export class SomeGraph extends ObjectGraph {
-  @Provides()
-  fooService(): FooService {
-    return new FooService();
-  }
-
-  @Provides()
-  barService(fooService: FooService): AppInitializer {
-    return new BarService(fooService);
-  }
-}
-```
-
-Obtaining the dependencies directly from the graph is straight forward:
-```ts Obtaining a dependency imperatively
-Obsidian.obtain(ApplicationGraph).fooService();
-
-// Even though barService depends on fooService, you don't need to provide its dependency
-Obsidian.obtain(ApplicationGraph).barService();
-```

package/documentation/docs/documentation/usage/_category_.json

@@ -1,9 +0,0 @@
-{
-  "label": "Usage",
-  "position": 2,
-  "collapsed": false,
-  "link": {
-    "type": "generated-index",
-    "description": "Learn how to inject hooks, components and classes with Obsidian."
-  }
-}

package/documentation/docs/guides/configurableApplications.mdx

@@ -1,205 +0,0 @@
----
-sidebar_position: 2
-title: 'Configurable applications'
-toc_max_heading_level: 4
----
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-Designing applications to be flexible and configurable makes them more tolerable to changing requirements. The ability to change code frequently and quickly is one of the most important KPIs of any development team. This is generally made possible by a design that facilitates small pull requests, that modify a minimal amount of code across a minimal number of files.
-
-The Dependency Injection pattern helps us write flexible code that is more tolerable to change by addressing three key concerns:
-
-* How can a class be <ins>independent</ins> from the creation of the objects it depends on?
-* How can an application, and the objects it uses support different <ins>configurations</ins>?
-* How can the <ins>behavior</ins> of a piece of code be changed without editing it directly?
-
-In this article we will learn how Obsidian can help us address these concerns.
-
-## Configuring applications with providers
-When using Obsidian, dependencies are declared and constructed in classes called Graphs. Each dependency is constructed by a method called a provider which acts as a **Seam**. Lets see how we can leverage them to make our apps flexible and configurable.
-
-<!-- These providers act as **Seams**. -->
-
-:::tip What are Seams?
-A seam is a place where you can alter behavior in your program without editing in that place.
-
-[Working Effectively with Legacy Code](https://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052) by Michael Feathers
-:::
-
-### Example 1: Interchangeable dependencies according to external configurations
-In this example we'll learn how to change the concrete object returned by a provider according to an external configuration. In a real life scenario, the external configuration would represent an A/B test or a feature toggle.
-
-#### Step 1: Declare a graph
-Lets declare a simple graph that provides a single dependency: an HTTP client used to make network requests.
-
-```ts
-@Singleton() @Graph()
-class ApplicationGraph extends ObjectGraph {
-  @Provides()
-  httpClient(): HttpClient {
-    return new HttpClient();
-  }
-}
-```
-
-Our `HttpClient` is using the standard `fetch` API to make network requests and for the sake of simplicity, it only supports `GET` and `POST` requests.
-
-```ts
-class HttpClient {
-  async get(url: string): Promise<any> {
-    const response = await fetch(url, { method: 'GET' });
-    return await response.json();
-  }
-
-  async post(url: string, body: any): Promise<any> {
-    const response = fetch(url, { method: 'POST', body: JSON.stringify(body) });
-    return await response.json();
-  }
-}
-```
-
-#### Step 2: Implement another HTTP client
-Just like our current HTTP client, the new client will only support `GET` and `POST` requests. The only difference is that it will use the `axios` library to make network requests.
-
-```ts
-class AxiosClient {
-  async get(url: string): Promise<any> {
-    const response = await axios.get(url);
-    return response.data;
-  }
-
-  async post(url: string, body: any): Promise<any> {
-    const response = await axios.post(url, body);
-    return response.data;
-  }
-}
-```
-
-#### Step 3: Make the clients interchangeable
-To easily switch between the two clients, we'll use a well known principle called [Dependency Inversion](https://en.wikipedia.org/wiki/Dependency_inversion_principle). This principle states that high-level modules should not depend on low-level modules. Both the `HttpClient` and the `AxiosClient` are low-level modules, so we'll make the `ApplicationGraph` depend on an abstraction called `NetworkClient` instead.
-
-```ts
-interface NetworkClient {
-  get(url: string): Promise<any>;
-  post(url: string, body: any): Promise<any>;
-}
-```
-
-The two network clients will implement this interface:
-<Tabs>
-  <TabItem value="http" label="HttpClient" default>
-
-```ts
-class HttpClient implements NetworkClient {
-  override async get(url: string): Promise<any> {
-    const response = await fetch(url, { method: 'GET' });
-    return await response.json();
-  }
-
-  override async post(url: string, body: any): Promise<any> {
-    const response = fetch(url, { method: 'POST', body: JSON.stringify(body) });
-    return await response.json();
-  }
-}
-```
-
-  </TabItem>
-  <TabItem value="axios" label="AxiosClient">
-
-```ts
-class AxiosClient implements NetworkClient {
-  override async get(url: string): Promise<any> {
-    const response = await axios.get(url);
-    return response.data.json;
-  }
-
-  override async post(url: string, body: any): Promise<any> {
-    const response = await axios.post(url, body);
-    return response.data.json;
-  }
-}
-```
-  </TabItem>
-</Tabs>
-
-#### Step 4: Return the correct client according to the configuration
-To determine which client to return, we'll use a new dependency called `AppConfig` which will be used to access the application's configuration.
-
-```ts
-@Singleton() @Graph()
-class ApplicationGraph extends ObjectGraph {
-  @Provides()
-  httpClient(appConfig: AppConfig): NetworkClient {
-    return appConfig.shouldUseAxiosClient() ? new AxiosClient() : new HttpClient();
-  }
-
-  @Provides()
-  appConfig(): AppConfig {
-    return new AppConfig();
-  }
-}
-```
-
-We're done! Now we can easily control which network client to use according the application's configuration.
-
-#### Conclusion and after thoughts
-In this example we learned how to make dependencies interchangeable, and how to control which dependency to use according to an external configuration. This is a very common use case in large scale applications where we need an extra layer of assurance that changes can be easily rolled back in case of a bug.
-
-Two important things to note about this example:
-1. The provider's return type was changed to `NetworkClient` instead of `HttpClient`. This change could lead to further changes in the codebase, but it's a small price to pay for the flexibility it provides.
-2.  We wanted to keep the example short and easy to follow, so the two HTTP clients are simplified implementations of an actual client. They also share the same API which made it easy to implement the `NetworkClient` interface and have the two clients implement it. If the two clients had different APIs, perhaps because they supported typed request options and responses, then we would have to create common interfaces that would represent the common parts of the two APIs and adapters that would convert the two clients' APIs to the common API and vice versa.
-
-### Example 2: Mocking dependencies in acceptance/integration tests
-Acceptance and integration tests are a great way to test how an application behaves as a whole. In these type of tests, objects aren't mocked since we're testing how the objects behave when they interact with each other. But because tests also need to be predictable and stable, there are some operations that we do want to simulate. For example, we might want to mock a network client so that we don't make real network requests during the test as that would add an unwanted layer of unpredictability to the test.
-
-In this example we'll learn how to mock a dependency and how to use that mocked instance across all objects involved in the test.
-
-#### Step 1: Declare a graph
-As in the previous example, we'll declare a simple graph that provides a single dependency: an HTTP client used to make network requests.
-
-```ts
-@Singleton() @Graph()
-export class ApplicationGraph extends ObjectGraph {
-  @Provides()
-  httpClient(): HttpClient {
-    return new HttpClient();
-  }
-}
-```
-
-#### Step 2: Mock the HTTP client
-To provide a mocked HTTP client to all objects involved in the test, we'll create a new graph that extends the `ApplicationGraph` and overrides the `httpClient` provider. In the next step we'll learn how to use this graph in our tests.
-
-```ts
-import { mock } from 'jest-mock-extended';
-
-@Singleton() @Graph()
-export class ApplicationGraphForTests extends ApplicationGraph {
-  @Provides()
-  override httpClient(): HttpClient {
-    return mock<HttpClient>();
-  }
-}
-```
-
-#### Step 3: Use the graph in the test
-To use the graph in the test, we'll use Obsidian's test kit to use the `ApplicationGraphForTests` instead of the `ApplicationGraph` whenever it's needed.
-
-```ts
-import {testKit} from 'react-obsidian';
-
-describe('Test suite', () => {
-  beforeEach(() => {
-    testKit.mockGraphs({
-      // Instruct Obsidian to use the ApplicationGraphForTests instead of the ApplicationGraph
-      ApplicationGraph: ApplicationGraphForTests,
-    });
-  });
-
-  it('should do something', () => {
-    // ...
-  });
-});
-```

package/documentation/docs/guides/mockDependencies.mdx

@@ -1,141 +0,0 @@
----
-sidebar_position: 1
-title: 'Mocking dependencies in unit tests'
----
-
-Tests are an integral part of any software project. They let you verify that your code works as expected and that it doesn't break when you make changes. We want our tests to be as clear as possible so that developers don't have to waste time figuring out what the test is doing our how to fix it when it fails.
-
-Obsidian promotes Object Oriented design, a paradigm that focuses on the relationships between objects and how they interact with each other. In this article we'll learn how adopting this approach lets us mock objects more easily and as a result improve the readability and maintainability of our tests.
-
-:::tip On readable tests and developer velocity
-"Every time the developers have to stop and puzzle through a test to figure out what it means, they have less time left to spend on creating new features, and the team velocity drops."
-
-— [Growing Object-Oriented Software, Guided by Tests](https://www.amazon.com/Growing-Object-Oriented-Software-Guided-Tests/dp/0321503627)
-:::
-
-## The problem
-The setup phase of a test is often the most complex part of the test. It involves creating test data, mocking dependencies and instantiating the unit-under-test. We've identified three common problems that make tests brittle, difficult to maintain, and hard to understand:
-1. **Partial mocks** - a unit test is meant to test a single unit of code in isolation. If a dependency is partially mocked, our test is no longer testing a single unit. A bug in the partially mocked dependency can cause this unit test to fail preventing us from quickly identifying the root cause of the failure.
-2. **Dependencies are introduced implicitly to the unit-under-test, usually via imports** - we should always create valid objects. If an object depends on another object, we should pass that dependency explicity in through the constructor. The constructor serves as the contract for the dependencies that a class requires to function. There's no point in creating partially working classes, and the constructor is used to enforces this constraint.
-3. **Manual mocks** - manually mocking dependencies is a tedious and error prone process. It's easy to forget to mock a dependency, or to mock it incorrectly.
-
-To illustrate these problems, let's look at a simple example.
-
-```js showLineNumbers
-describe('Example', () => {
-  const openURL = jest.fn();
-
-  let logger;
-  let foo;
-  let uut;
-
-  beforeEach(() => {
-    // Problem 1: Partial mocks
-    logger = require('./Logger');
-    logger.log = jest.fn();
-    const spy = jest.spyOn(logger, 'warn');
-
-    // Problem 2: Implicit dependencies.
-    // Our UUT uses Linking.openUrl so we mock it on the module level.
-    jest.mock('react-native', () => ({
-      Linking: {
-        openURL  
-      },
-    }));
-    // Problem 3: Manual mocks
-    foo = {
-      doSomething: jest.fn(),
-    }
-    uut = new Example(logger, foo);
-  });
-});
-```
-
-## The solution
-To achieve our goal of reducing boilerplate and improving readability, we'll refactor the above example as follows:
-1. **Convert all dependencies to ES6 classes** - this will allow us to mock them using [jest-mock-extended](https://github.com/marchaos/jest-mock-extended) - a library that lets us create mock classes in a type-safe manner.
-2. **Pass dependencies in through the constructor** - we'll pass the dependencies explicitly to the unit-under-test. This step will require us to declare new classes that will encapsulate interactions with third-party libraries.
-
-<!-- In Object Oriented design, logic is encapsulated in classes that are introduced (injected) to one another in through the constructor.  -->
-<!-- This approach lets us use modern mocking techniques that require less boilerplate and are easier to reason about. -->
-<!-- To achieve our goal, we'll do two things:
-First, 
-First, refactor our code to use dependency injection. 
-
-
-To achieve our goal, we'll use an open-source library called [jest-mock-extended](https://github.com/marchaos/jest-mock-extended) which provides a `mock` function that creates a mock object with all the methods and properties of the original object. This means that we don't have to mock each method and property individually. -->
-
-### Step 1: Encapsulate interactions with third-party dependencies
-Implicit dependencies (dependencies introduced by importing a module) make it difficult to reason about the code and to test it. To avoid this problem, we'll create a new class that encapsulates interactions with the third-party library. We'll see how this approach lets us mock dependencies more easily.
-
-```ts title="Encapsulating the Linking module in a new class responsible for opening URLs"
-import {Linking} from 'react-native';
-
-export class UrlOpener {
-  public async openUrl(url: string) {
-    if (await Linking.canOpenURL(url)) {
-      await Linking.openURL(url);
-    } else {
-      throw new Error(`Can't open URL: ${url}`);
-    }
-  }
-}
-```
-
-:::tip On decoupling third party dependencies
-"Avoid littering direct calls to library classes in your code. You might think that you'll never change them, but that can become a self-fulfilling prophecy."
-
-— [Working Effectively with Legacy Code](https://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052)
-:::
-
-### Step 2: Convert dependencies to ES6 classes
-We'll convert the `Logger` and `Foo` classes to ES6 classes:
-
-```ts title="Logger.ts"
-export class Logger {
-  public log(message: string) {
-    console.log(message);
-  }
-
-  public warn(message: string) {
-    console.warn(message);
-  }
-}
-```
-
-```ts title="Foo.ts"
-export class Foo {
-  public doSomething() {
-    console.log('doing something...');
-    setTimeout(() => {
-      console.log('done!');
-    }, 1000);
-  }
-}
-```
-
-### Step 3: Mock dependencies using jest-mock-extended
-When we mock a dependency using `jest-mock-extended`, we get a mock object that has all the methods and properties of the original object. This means that we don't have to mock each method and property individually. And, because we eliminated the implicit dependency on the `Linking` module, we can use this approach to mock it as well.
-
-```ts showLineNumbers
-import {mock} from 'jest-mock-extended';
-import {Logger} from './Logger';
-import {Foo} from './Foo';
-
-describe('Example', () => {
-  let logger: Logger;
-  let foo: Foo;
-  let urlOpener: UrlOpener;
-  let uut: Example;
-
-  beforeEach(() => {
-    logger = mock<Logger>();
-    foo = mock<Foo>();
-    urlOpener = mock<UrlOpener>();
-    uut = new Example(logger, foo, urlOpener);
-  });
-}
-```
-
-## Wrapping up
-While we didn't use any API from `Obsidian` in this refactor, this change was made possible due to how Obsidian influences the design of our code. Obsidian makes it easy to introduce classes to each other by passing them explicitly in through the constructor. This approach encourages us to split our code into smaller classes that are easier to test.

package/documentation/docusaurus.config.js

@@ -1,151 +0,0 @@
-// @ts-check
-// Note: type annotations allow type checking and IDEs autocompletion
-
-const lightCodeTheme = require('prism-react-renderer/themes/github');
-const darkCodeTheme = require('prism-react-renderer/themes/dracula');
-
-/** @type {import('@docusaurus/types').Config} */
-const config = {
-  title: 'Obsidian',
-  tagline: 'Dependency injection framework for React and React Native applications',
-  url: 'https://wix-incubator.github.io',
-  baseUrl: '/obsidian/',
-  onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
-  favicon: 'img/favicon.ico',
-
-  // GitHub pages deployment config.
-  // If you aren't using GitHub pages, you don't need these.
-  organizationName: 'Wix.com', // Usually your GitHub org/user name.
-  projectName: 'obsidian', // Usually your repo name.
-
-  // Even if you don't use internalization, you can use this field to set useful
-  // metadata like html lang. For example, if your site is Chinese, you may want
-  // to replace "en" with "zh-Hans".
-  i18n: {
-    defaultLocale: 'en',
-    locales: ['en'],
-  },
-
-  presets: [
-    [
-      'classic',
-      /** @type {import('@docusaurus/preset-classic').Options} */
-      ({
-        docs: {
-          sidebarPath: require.resolve('./sidebars.js'),
-          // Please change this to your repo.
-          // Remove this to remove the "edit this page" links.
-          editUrl:
-            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
-        },
-        blog: {
-          showReadingTime: true,
-          // Please change this to your repo.
-          // Remove this to remove the "edit this page" links.
-          editUrl:
-            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
-        },
-        theme: {
-          customCss: require.resolve('./src/css/custom.css'),
-        },
-      }),
-    ],
-  ],
-
-  themeConfig:
-    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
-    ({
-      navbar: {
-        title: 'Obsidian',
-        logo: {
-          alt: 'Obsidian Logo',
-          src: 'img/logo.svg',
-        },
-        items: [
-          {
-            type: 'docSidebar',
-            sidebarId: 'docs2',
-            position: 'left',
-            label: 'Documentation',
-          },
-          {
-            type: 'docSidebar',
-            sidebarId: 'guides',
-            position: 'left',
-            label: 'Guides',
-          },
-          {
-            position: 'left',
-            label: 'Playground',
-            to: '/playground/',
-          },
-          // {to: '/blog', label: 'Blog', position: 'left'},
-          {
-            href: 'https://github.com/wix-incubator/obsidian',
-            label: 'GitHub',
-            position: 'right',
-          },
-        ],
-      },
-      footer: {
-        style: 'dark',
-        links: [
-          {
-            title: 'Docs',
-            items: [
-              {
-                label: 'Tutorial',
-                to: '/docs/documentation#the-2-steps-tutorial-for-injecting-dependencies-with-obsidian',
-              },
-              {
-                label: 'Installation',
-                to: '/docs/documentation/installation',
-              },
-              {
-                label: 'API',
-                to: '/docs/category/usage',
-              }
-            ],
-          },
-          {
-            title: 'Community',
-            items: [
-              // {
-              //   label: 'Stack Overflow',
-              //   href: 'https://stackoverflow.com/questions/tagged/docusaurus',
-              // },
-              {
-                label: 'Discord',
-                href: 'https://discord.gg/2g5vhGQN',
-              },
-              // {
-              //   label: 'Twitter',
-              //   href: 'https://twitter.com/docusaurus',
-              // },
-            ],
-          },
-          {
-            title: 'More',
-            items: [
-              // {
-              //   label: 'Blog',
-              //   to: '/blog',
-              // },
-              {
-                label: 'GitHub',
-                href: 'https://github.com/wix-incubator/obsidian',
-              },
-            ],
-          },
-        ],
-        copyright: `Copyright © ${new Date().getFullYear()} Wix.com. Built with Docusaurus.`,
-      },
-      prism: {
-        theme: lightCodeTheme,
-        darkTheme: darkCodeTheme,
-      },
-    }),
-};
-
-module.exports = config;