repluggable-core 1.302.63 → 1.302.65

package/src/API.ts

@@ -1,3 +1,5 @@
+import * as Redux from 'redux'
+
 export interface AnySlotKey {
     readonly name: string
     readonly public?: boolean // TODO: Move to new interface - APIKey
@@ -28,4 +30,498 @@ export interface SlotKey<T> extends AnySlotKey {
      * Version of the API that will be part of the API key unique identification
      */
     readonly version?: number // TODO: Move to new interface - APIKey
-}
+}
+
+export type ReactComponentContributor<TProps = {}> = (props?: TProps) => React.ReactNode
+export type ReducersMapObjectContributor<TState = {}, TAction extends Redux.AnyAction = Redux.AnyAction> = () => Redux.ReducersMapObject<
+    TState,
+    TAction
+>
+export type ContributionPredicate = () => boolean
+export interface EntryPointTags {
+    [name: string]: string
+}
+export type LazyEntryPointFactory = () => Promise<EntryPoint> //TODO: get rid of these
+export type ShellsChangedCallback = (shellNames: string[]) => void
+export type DeclarationsChangedCallback = () => void
+export type UnsubscribeFromDeclarationsChanged = () => void
+export type ShellBoundaryAspect = React.FunctionComponent<React.PropsWithChildren<unknown>>
+
+export interface LazyEntryPointDescriptor {
+    readonly name: string
+    readonly factory: LazyEntryPointFactory
+}
+
+
+
+/**
+ * Application part that will receive a {Shell} when loaded into the {AppHost}
+ * @export
+ * @interface EntryPoint
+ */
+export interface EntryPoint {
+    /**
+     * Unique name that will represent this entry point in the host
+     */
+    readonly name: string
+    readonly tags?: EntryPointTags
+    /**
+     * Application layer / layers that will restrict usage of APIs contributed by this entry point.
+     * Layers hierarchy is defined in the host options
+     * See {AppHostOptions.layers}
+     */
+    readonly layer?: string | string[]
+    /**
+     * Define which API keys (a.k.a. contracts) are mandatory for this entry point to be executed
+     * @return {SlotKey<any>[]} API keys to wait for implementation
+     */
+    getDependencyAPIs?(): SlotKey<any>[]
+    /**
+     * Define which API keys (a.k.a. contracts) this entry point is going to implement and contribute
+     * @return {SlotKey<any>[]} API keys that will be contributed
+     */
+    declareAPIs?(): SlotKey<any>[]
+    /**
+     * Execute logic that is independent from other entry points
+     * Most commonly - contribute APIs and state
+     * @param {Shell} shell
+     */
+    attach?(shell: Shell): void
+    /**
+     * Execute logic that is dependent on other entry points
+     * @param {Shell} shell
+     */
+    extend?(shell: Shell): void
+    /**
+     * Clean side effects
+     * @param {Shell} shell
+     */
+    detach?(shell: Shell): void
+}
+
+export type AnyEntryPoint = EntryPoint | LazyEntryPointDescriptor
+export type EntryPointOrPackage = AnyEntryPoint | AnyEntryPoint[]
+export interface EntryPointOrPackagesMap {
+    [name: string]: EntryPointOrPackage
+}
+
+export type ExtensionItemFilter<T> = (extensionItem: ExtensionItem<T>) => boolean
+/**
+ * A slot/container for holding any contribution of shape T
+ * Access to the slot is scoped to the {Shell}
+ *
+ * @export
+ * @interface ExtensionSlot
+ * @template T
+ */
+export interface ExtensionSlot<T> {
+    /**
+     * a unique identifier for the slot
+     */
+    readonly name: string
+    readonly host: AppHost
+    /**
+     * Which {Shell} owns this slot
+     */
+    readonly declaringShell?: Shell
+    /**
+     * Add an item to the slot
+     *
+     * @param {Shell} shell Who owns the contributed item
+     * @param {T} item Extension item to be added to the slot
+     * @param {ContributionPredicate} [condition] A predicate to condition the retrieval of the item when slot items are requested with {ExtensionSlot<T>.getItems}
+     */
+    contribute(shell: Shell, item: T, condition?: ContributionPredicate): void
+    /**
+     * Get all items contributed to the slot
+     *
+     * @param {boolean} [forceAll] Ignore items' contribution predicates and get all anyway
+     * @return {ExtensionItem<T>[]} All items contributed to the slot
+     */
+    getItems(forceAll?: boolean): ExtensionItem<T>[]
+    /**
+     * Get the first item in the slot
+     *
+     * @return {ExtensionItem<T>} The first item in the slot
+     */
+    getSingleItem(): ExtensionItem<T> | undefined
+    /**
+     * Get a specific item in the slot
+     *
+     * @param {string} name Extension item name
+     * @return {ExtensionItem<T> | undefined} Extension item
+     */
+    getItemByName(name: string): ExtensionItem<T> | undefined
+    /**
+     * Remove items from the slot by predicate
+     *
+     * @param {ExtensionItemFilter<T> | undefined} predicate Remove all items matching this predicate
+     */
+    discardBy(predicate: ExtensionItemFilter<T>): void
+}
+
+export interface PrivateExtensionSlot<T> extends ExtensionSlot<T> {
+    subscribe(callback: () => void): () => void
+}
+
+export interface CustomExtensionSlotHandler<T> {
+    contribute(fromShell: Shell, item: T, condition?: ContributionPredicate): void
+    discardBy(predicate: ExtensionItemFilter<T>): void
+}
+
+export interface CustomExtensionSlot<T> extends CustomExtensionSlotHandler<T> {
+    readonly name: string
+    readonly host: AppHost
+    readonly declaringShell?: Shell
+}
+
+/**
+ * Item of shape T that is contributed to a slot of shape T
+ *
+ * @export
+ * @interface ExtensionItem
+ * @template T
+ */
+export interface ExtensionItem<T> {
+    readonly name?: string
+    /**
+     * Which {Shell} owns this item
+     */
+    readonly shell: Shell
+    /**
+     * Contribution content
+     */
+    readonly contribution: T
+    /**
+     * Condition for the retrieval of this item by {ExtensionSlot<T>.getItems}
+     */
+    readonly condition: ContributionPredicate
+    readonly uniqueId: string
+}
+
+// addEntryPoints(entryPoints: EntryPoint[])
+// addPackages(packages: EntryPointOrPackage[])
+//
+
+/**
+ * An application content container that will accept {EntryPoint} and provide registry for contracts
+ *
+ * @export
+ * @interface AppHost
+ */
+export interface AppHost {
+    /**
+     * Get an implementation of API previously contributed to the {AppHost}
+     *
+     * @template TAPI
+     * @param {SlotKey<TAPI>} key API Key
+     * @return {*}  {TAPI}
+     */
+    getAPI<TAPI>(key: SlotKey<TAPI>): TAPI
+    /**
+     * Get an extension slot defined on the host
+     *
+     * @template TItem
+     * @param {SlotKey<TItem>} key
+     * @return {ExtensionSlot<TItem>}
+     */
+    getSlot<TItem>(key: SlotKey<TItem>): ExtensionSlot<TItem>
+    /**
+     * Get all the extension slots defined on the host
+     *
+     * @return {*}  {AnySlotKey[]}
+     */
+    getAllSlotKeys(): AnySlotKey[]
+    /**
+     * Get all {EntryPoint}s addded to the {AppHost}
+     *
+     * @return {EntryPointsInfo[]}
+     */
+    getAllEntryPoints(): EntryPointsInfo[]
+    /**
+     * Does the {AppHost} contain a specific {Shell}
+     *
+     * @param {string} name
+     * @return {boolean}
+     */
+    hasShell(name: string): boolean
+    // TODO: Deprecate
+    isLazyEntryPoint(name: string): boolean
+    /**
+     * Dynamically add {Shell}s after the host is created
+     *
+     * @param {EntryPointOrPackage[]} entryPointsOrPackages New packages or entry points to be added to the {AppHost}
+     * @return {Promise<void>}
+     */
+    addShells(entryPointsOrPackages: EntryPointOrPackage[]): Promise<void>
+    /**
+     * Dynamically remove {Shell}s after the host is created
+     *
+     * @param {string[]} names {Shell} names to be removed
+     * @return {Promise<void>}
+     */
+    removeShells(names: string[]): Promise<void>
+        /**
+     * Subscribe to changes in host declarations. This includes:
+     * - API additions and removals
+     * - Extension slot additions and removals
+     *
+     * @param {DeclarationsChangedCallback} callback Function to be called when host declarations change
+     * @return {UnsubscribeFromDeclarationsChanged} Function to unsubscribe from host declarations changes
+     */
+
+    onDeclarationsChanged(callback: DeclarationsChangedCallback): UnsubscribeFromDeclarationsChanged
+    onShellsChanged(callback: ShellsChangedCallback): string
+    removeShellsChangedCallback(callbackId: string): void
+    readonly log: HostLogger
+    readonly options: AppHostOptions
+}
+
+export interface PrivateAppHost extends AppHost {
+    executeWhenFree(identifier: string, callback: () => void): void
+}
+
+export interface MonitoringOptions {
+    enablePerformance?: boolean
+    readonly disableMonitoring?: boolean
+    readonly disableMemoization?: boolean
+    readonly debugMemoization?: boolean
+}
+
+export interface Trace {
+    name: string
+    duration: number
+    startTime: number
+    res: any
+    args: any[]
+}
+
+export interface APILayer {
+    level: number
+    name: string
+}
+
+export interface AppHostOptions {
+    readonly logger?: HostLogger
+    readonly monitoring: MonitoringOptions
+    readonly layers?: APILayer[] | APILayer[][]
+    readonly disableLayersValidation?: boolean
+    readonly disableCheckCircularDependencies?: boolean
+    readonly enableStickyErrorBoundaries?: boolean
+    readonly enableReduxDevtoolsExtension?: boolean
+    readonly experimentalCyclicMode?: boolean
+    readonly shouldScopeReducers?: boolean
+}
+
+export interface MemoizeMissHit {
+    miss: number
+    calls: number
+    hit: number
+    printHitMiss(): void
+}
+
+export type enrichedMemoizationFunction = MemoizeMissHit & AnyFunction & _.MemoizedFunction
+
+export interface StatisticsMemoization {
+    func: enrichedMemoizationFunction
+    name: string
+}
+
+export interface ContributeAPIOptions<TAPI> {
+    includesNamespaces?: boolean
+    disableMonitoring?: boolean | (keyof TAPI)[]
+}
+
+export type StateObserverUnsubscribe = () => void
+export type StateObserver<TSelectorAPI> = (next: TSelectorAPI) => void
+export interface ObservableState<TSelectorAPI> {
+    subscribe(fromShell: Shell, callback: StateObserver<TSelectorAPI>): StateObserverUnsubscribe
+    current(allowUnsafeReading?: boolean): TSelectorAPI
+}
+
+export type AnyFunction = (...args: any[]) => any
+export type FunctionWithSameArgs<F extends AnyFunction> = (...args: Parameters<F>) => any
+
+export interface Lazy<T> {
+    get(): T
+}
+
+/**
+ * An scoped communication terminal provided for an {EntryPoint}
+ * in order to contribute its application content to the {AppHost}
+ *
+ * @export
+ * @interface Shell
+ * @extends {(Pick<AppHost, Exclude<keyof AppHost, 'getStore' | 'log' | 'options'>>)}
+ */
+export interface Shell extends Pick<AppHost, Exclude<keyof AppHost, 'getStore' | 'log' | 'options'>> {
+    /**
+     * Are APIs ready to be requested
+     *
+     * @return {*}  {boolean}
+     */
+    canUseAPIs(): boolean
+    /**
+     * Is store ready to be requested
+     *
+     * @return {*}  {boolean}
+     */
+    canUseStore(): boolean
+    /**
+     * Did the execution of {EntryPoint}s' lifecycle phases (attach, detach) are done
+     *
+     * @return {*}  {boolean}
+     */
+    wasInitializationCompleted(): boolean
+    runLateInitializer<T>(initializer: () => T): T
+    /**
+     * Create an {ExtensionSlot}
+     *
+     * @template TItem
+     * @param {SlotKey<TItem>} key Key that will represent the slot (an will be used for retrieval)
+     * @return {ExtensionSlot<TItem>} Actual slot
+     */
+    declareSlot<TItem>(key: SlotKey<TItem>): ExtensionSlot<TItem>
+    declareCustomSlot<TItem>(key: SlotKey<TItem>, handler: CustomExtensionSlotHandler<TItem>): CustomExtensionSlot<TItem>
+
+    // TODO: Fix contributeAPI factory type not to resort to lowest common
+    /**
+     * Contribute an implementation of an API (a.k.a contract)
+     *
+     * @template TAPI
+     * @param {SlotKey<TAPI>} key API Key that represents an interface TAPI
+     * @param {() => TAPI} factory Create an implementation of TAPI
+     * @param {ContributeAPIOptions<TAPI>} [options] Contribution options {ContributeAPIOptions}
+     * @return {TAPI} Result of the factory execution
+     */
+    contributeAPI<TAPI>(key: SlotKey<TAPI>, factory: () => TAPI, options?: ContributeAPIOptions<TAPI>): TAPI
+    /**
+     * Contribute a Redux reducer that will be added to the host store.
+     * Use it for slowly changing state (e.g. not changing because of mouse movement)
+     *
+     * @template TState
+     * @param {ReducersMapObjectContributor<TState>} contributor
+     */
+    contributeState<TState, TAction extends Redux.AnyAction = Redux.AnyAction>(
+        contributor: ReducersMapObjectContributor<TState, TAction>
+    ): void
+
+    /**
+     * Contribute a Redux reducer that will be added to the host store
+     * Use it for rapidly changing state (e.g. changing on every mouse movement event)
+     * Changes to this state won't trigger the usual subscribers.
+     * In order to subscribe to changes in this state, use the observer object returned by this function.
+     *
+     * @template TState
+     * @param {ReducersMapObjectContributor<TState>} contributor
+     * @return {TAPI} Observer object for subscribing to state changes. The observer can also be passed to {connectWithShell}.
+     */
+    contributeObservableState<TState, TSelector, TAction extends Redux.AnyAction = Redux.AnyAction>(
+        contributor: ReducersMapObjectContributor<TState, TAction>,
+        selectorFactory: (state: TState) => TSelector
+    ): ObservableState<TSelector>
+
+    /**
+     * Contribute the main view (root) of the application
+     * Intended to be used by a single {Shell} in an application
+     *
+     * @param {Shell} fromShell Who owns the main view
+     * @param {ReactComponentContributor} contributor Create the main view component
+     */
+    contributeMainView(fromShell: Shell, contributor: ReactComponentContributor): void
+    contributeBoundaryAspect(component: ShellBoundaryAspect): void
+    /**
+     * Create a function with internal cache until any state change in the {AppHost} store
+     *
+     * @template T
+     * @param {T} func Function to build cache for
+     * @param {FunctionWithSameArgs<T>} resolver Key creator to index results by
+     * @param {() => boolean} [shouldClear] Custom clear condition (if not provided, behaves like () => true)
+     * @return {*}  {(((...args: Parameters<T>) => ReturnType<T>) & Partial<_.MemoizedFunction> & Partial<MemoizeMissHit>)}
+     */
+    memoizeForState<T extends AnyFunction>(
+        func: T,
+        resolver: FunctionWithSameArgs<T>,
+        shouldClear?: () => boolean
+    ): ((...args: Parameters<T>) => ReturnType<T>) & Partial<_.MemoizedFunction> & Partial<MemoizeMissHit>
+    /**
+     * Manually trigger clear condition for function memoized with {Shell.memoizeForState}
+     */
+    flushMemoizedForState(): void
+    /**
+     * Create a function with internal cache
+     *
+     * @template T
+     * @param {T} func Function to build cache for
+     * @param {FunctionWithSameArgs<T>} resolver Key creator to index results by
+     * @return {*}  {(((...args: Parameters<T>) => ReturnType<T>) & Partial<_.MemoizedFunction> & Partial<MemoizeMissHit>)}
+     */
+    memoize<T extends AnyFunction>(
+        func: T,
+        resolver: FunctionWithSameArgs<T>
+    ): ((...args: Parameters<T>) => ReturnType<T>) & Partial<_.MemoizedFunction> & Partial<MemoizeMissHit>
+    /**
+     * Clear cache of a memoized function
+     *
+     * @param {(Partial<_.MemoizedFunction> & Partial<MemoizeMissHit>)} memoizedFunction
+     */
+    clearCache(memoizedFunction: Partial<_.MemoizedFunction> & Partial<MemoizeMissHit>): void
+    /**
+     * Creates a lazy-evaluated value. The function `func` is only executed once when `get` is called for the first time,
+     * and the result is cached for subsequent calls.
+     *
+     * @template T
+     * @param {F} func - The function that will be lazily evaluated. It should not take any arguments.
+     * @returns {Lazy<T>} An object with a `get` method that returns the lazily evaluated value of type `T`.
+     */
+    lazyEvaluator<F extends AnyFunction, T extends ReturnType<F>>(func: F): Lazy<T>
+}
+
+export interface PrivateShell extends Shell {
+    readonly entryPoint: EntryPoint
+    setDependencyAPIs(APIs: AnySlotKey[]): void
+    setLifecycleState(enableStore: boolean, enableAPIs: boolean, initCompleted: boolean): void
+    getBoundaryAspects(): ShellBoundaryAspect[]
+    getHostOptions(): AppHostOptions
+    wrapWithShellRenderer(component: JSX.Element): JSX.Element
+}
+
+export interface EntryPointsInfo {
+    readonly name: string
+    readonly lazy: boolean
+    readonly attached: boolean
+}
+
+export interface EntryPointInterceptor {
+    interceptName?(innerName: string): string
+    interceptTags?(innerTags?: EntryPointTags): EntryPointTags
+    interceptGetDependencyAPIs?(innerGetDependencyAPIs?: EntryPoint['getDependencyAPIs']): EntryPoint['getDependencyAPIs']
+    interceptDeclareAPIs?(innerDeclareAPIs?: EntryPoint['declareAPIs']): EntryPoint['declareAPIs']
+    interceptAttach?(innerAttach?: EntryPoint['attach']): EntryPoint['attach']
+    interceptDetach?(innerDetach?: EntryPoint['detach']): EntryPoint['detach']
+    interceptExtend?(innerExtend?: EntryPoint['extend']): EntryPoint['extend']
+}
+
+export type LogSeverity = 'debug' | 'info' | 'event' | 'warning' | 'error' | 'critical'
+export type LogSpanFlag = 'begin' | 'end' //TODO:deprecated-kept-for-backward-compat
+
+export interface HostLogger {
+    log(severity: LogSeverity, id: string, error?: Error, keyValuePairs?: Object): void
+    spanChild(messageId: string, keyValuePairs?: Object): ShellLoggerSpan
+    spanRoot(messageId: string, keyValuePairs?: Object): ShellLoggerSpan
+}
+
+export interface ShellLogger extends HostLogger {
+    debug(messageId: string, keyValuePairs?: Object): void
+    info(messageId: string, keyValuePairs?: Object): void
+    warning(messageId: string, keyValuePairs?: Object): void
+    error(messageId: string, error?: Error, keyValuePairs?: Object): void
+    critical(messageId: string, error?: Error, keyValuePairs?: Object): void
+    spanChild(messageId: string, keyValuePairs?: Object): ShellLoggerSpan
+    spanRoot(messageId: string, keyValuePairs?: Object): ShellLoggerSpan
+    monitor<T>(messageId: string, keyValuePairs: Object, monitoredCode: () => T): T
+}
+
+export interface ShellLoggerSpan {
+    end(success: boolean, error?: Error, keyValuePairs?: Object): void
+}

package/src/__internal.ts

@@ -0,0 +1,4 @@
+/**
+ * This symbol is only for internal use of repluggable mono-repo.
+ */
+export const INTERNAL_DONT_USE_SHELL_GET_APP_HOST: unique symbol = Symbol('SHELL_GET_APP_HOST')

package/src/index.ts

@@ -1,4 +1,6 @@
 export {
     AnySlotKey,
     SlotKey
-} from './API'
+} from './API'
+
+export * from './__internal'