Repluggable

APIs are the only allowed way for packages to interact. They allow provider packages to offer services to consumer packages.

Providing an API

A provider package must:

1. Declare and export an API interface and an API key (the key is a constant object exported from the package).
2. Implement an API object that satisfies the interface.
3. Contribute that API object under the specific API key.

Consuming an API

A consumer package must:

1. Import the API key and API interface from the provider package.
2. Declare a dependency on that API within its relevant entry points.
3. Retrieve the API object by calling getAPI(apiKey) (the exact retrieval mechanism is provided by the AppHost context).

Note: Because APIs are part of entry points, they may be temporarily unavailable during lazy loading. AppHost handles this by putting dependent entry points 'on hold' until the required API is available.

The AppHost allows for flexible, non-blocking package loading to ensure fast application startup.

Loading Mechanisms

• Abstraction: Loading is abstracted from the module system. To add a package, you provide a Promise that resolves to the package's default export.
• Timing: Packages can be added:
  • During AppHost initialization.
  • Immediately after the first render of AppMainView.
  • Lazily at any time during the application lifecycle.

Entry Point Separation

Packages can be split into multiple entry points. Some entry points can be added immediately, while others (which might require heavy dependencies or data fetching) can be added later. This allows the application to become functional incrementally.

Removal

AppHost supports removing previously added entry points or entire packages at any time. Removing a package automatically removes all its entry points and all contributions made by those entry points.

Because entry points can be loaded lazily, an entry point might attempt to load before its required APIs are available. AppHost manages this via explicit dependency declarations.

Dependency Lifecycle

1. Declaration: Every entry point must declare which APIs it depends on.
2. On Hold (Missing API): If an entry point is added but its required APIs are not yet available, the entry point is put on hold. It will be automatically activated as soon as all required APIs are contributed.
3. On Hold (API Removal): If an entry point is already running but one of its required APIs becomes unavailable (e.g., due to package removal), the entry point and all its contributions are removed and put on hold. It will be re-added once the required APIs become available again.

This mechanism guarantees that code depending on an API will only execute when that API is guaranteed to be present.

APIs allow packages to communicate. Follow these five steps to implement an API:

1. Define the Interface: Create a standard TypeScript interface for your API methods.
2. Define the SlotKey: Create a const named after the interface using SlotKey<T>. Set public: true if the API needs to be exported outside your package.
3. Implement the API: Write a factory function (e.g., createFooAPI(shell: Shell)) that returns the interface implementation.
4. Contribute via attach: In your EntryPoint.attach(shell) hook, call shell.contributeAPI(YourAPI, () => implementation).
5. Export the Key: Export the SlotKey from your package's entry point so other packages can reference it.

// 1. Interface
export interface FooAPI {
   doSomething(): void
}

// 2. SlotKey
import { SlotKey } from 'repluggable'
export const FooAPI: SlotKey<FooAPI> = {
   name: 'Foo API',
   public: true
}

// 3. Implementation
export function createFooAPI(shell: Shell): FooAPI {
   return {
       doSomething() { /* ... */ }
   }
}

// 4. Contribution in EntryPoint
attach(shell: Shell) {
   shell.contributeAPI(FooAPI, () => createFooAPI(shell))
}

// 5. Export
export { FooAPI } from './fooApi'

When building React components that need to consume APIs or state, use connectWithShell instead of the standard connect.

connectWithShell provides the Shell object as the first argument to both mapStateToProps and mapDispatchToProps. This allows components to access APIs from other packages without manual prop drilling.

Pattern:

1. Define StateProps (from local state) and DispatchProps (from local actions or external APIs).
2. Create a stateless functional component (SFC).
3. Wrap the SFC with connectWithShell(mapStateToProps, mapDispatchToProps, boundShell).

Note: The Shell is extracted from the EntryPointContext automatically.

// 1. Prop Types
type FooStateProps = { xyzzy: string; bar: number }
type FooDispatchProps = { setXyzzy(v: string): void; createNewBar(): void }

// 2. Stateless Component
const FooSfc: React.SFC<FooStateProps & FooDispatchProps> = (props) => (
  <div>{props.xyzzy}</div>
)

// 3. Connected Container
export const createFoo = (boundShell: Shell) => connectWithShell(
  (shell, state) => ({
    xyzzy: state.baz.xyzzy,
    bar: shell.getAPI(BarAPI).getCurrentBar()
  }),
  (shell, dispatch) => ({
    setXyzzy: (val) => dispatch(setXyzzy(val)),
    createNewBar: () => shell.getAPI(BarAPI).createNewBar()
  }),
  boundShell
)(FooSfc)