assertNoRootAppElm(rootAppElm, className)

When this constraint is not met, and error is thrown, after emitting applicable context in the console log.

For more information, please refer to Injecting DOM Content.

createFeature(name, [enabled], [fassets], [appWillStart], [appInit], [appDidStart], [extendedAspect]) ⇒ Feature

For more information, please refer to Feature & aspect content.

Please Note this function uses named parameters.

Returns: Feature - a new Feature object (to be consumed by launchApp()).

extendFeatureProperty(name, owner)

feature-u keeps track of the agent that owns this extension (using the owner parameter). This is used to prevent exceptions when duplicate extension requests are made by the same owner. This can happen when multiple instances of an aspect type are supported, and also in unit testing.

Throws:

• Error when supplied name is already reserved by a different owner

expandWithFassets(expandWithFassetsCB) ⇒ expandWithFassetsCB

Features may communicate AspectContent directly, or through a expandWithFassetsCB(). In other words, the AspectContent can either be the actual content itself (ex: reducer, logic modules, etc.), or a function that returns the content. The latter:

1. supports Cross Feature Communication (through fassets object injection), and
2. minimizes circular dependency issues (of ES6 modules).

Managed Expansion Callbacks are used when a fully resolved Fassets object is required during in-line code expansion. They are merely functions that when invoked (under the control of feature-u), are supplied the Fassets object and return the expanded AspectContent (ex: reducer, logic modules, etc.).

For more information (with examples), please refer to Managed Code Expansion.

The expandWithFassetsCB() function should conform to the following signature:

API: expandWithFassetsCB(fassets): AspectContent

Returns: expandWithFassetsCB - the supplied expandWithFassetsCB, marked as a "managed expansion callback".

launchApp(features, [aspects], registerRootAppElm, [showStatus]) ⇒ Fassets

For more information (with examples), please refer to Launching Your Application.

Please Note this function uses named parameters.

Returns: Fassets - the Fassets object used in cross-feature-communication.

useFassets(p) ⇒ Fassets | fassets-resource | fassetsProps

Hooks allow you to "hook into" React state and lifecycle aspects from functional components. They greatly simplify the UI implementation as opposed to the alternative of Higher Order Components (see: withFassets()).

There are three ways to invoke useFassets() (examples can be found at UI Composition):

1. Passing NO parameters, returns the Fassets object:

   + useFassets(): fassets
   

2. Passing a fassetsKey (a string), returns the resolved fassets resource:

   + useFassets('MainPage.*.link@withKeys'): [] ... an array of cataloged links
   

   The fassetsKey parameter is identical (in usage) to the Fassets.get() method.

3. Passing a mapFassetsToPropsStruct, returns a set of resolved fassetsProps:

   + useFassets({
       mainBodies: 'MainPage.*.body',
       mainLinks:  'MainPage.*.link@withKeys'
     }): {  // ... return structure:
       mainBodies: ... resolved cataloged resource
       mainLinks:  ... ditto
     }
   

   The mapFassetsToPropsStruct allows you to return more than one resolved fassets resources.

SideBar: For useFassets() to operate, <FassetsContext.Provider> must be rendered at the root of your application DOM. This is really a moot point, because feature-u automatically performs this initialization, so you really don't have to worry about this detail (automating configuration is a Hallmark of feature-u - reducing boilerplate code).

Returns: Fassets | fassets-resource | fassetsProps - see explanation above.

withFassets(mapFassetsToProps, [component]) ⇒ HoC | HoF

Central to this process, a Higher-order Function (HoF) is created that encapsulates this "mapping knowledge". Ultimately, this HoF must be invoked (passing component), which exposes the HoC (the "wrapped" Component).

+ withFassetsHoF(component): HoC

There are two ways to use withFassets():

1. By directly passing the component parameter, the HoC will be returned (internally invoking the HoF). This is the most common use case.

2. By omitting the component parameter, the HoF will be returned. This is useful to facilitate "functional composition" (in functional programming). In this case it is the client's responsibility to invoke the HoF (either directly or indirectly) in order to expose the HoC.

SideBar: For withFassets() to operate, <FassetsContext.Provider> must be rendered at the root of your application DOM. This is really a moot point, because feature-u automatically performs this initialization, so you really don't have to worry about this detail (automating configuration is a Hallmark of feature-u - reducing boilerplate code).

Please Note this function uses named parameters.

Returns: HoC | HoF - either the HoC (the "wrapped" Component) when component is supplied, otherwise the HoF (see discussion above).

Examples:

1. Inject fasset resources from a static structure (mapFassetsToPropsStruct), auto wrapping the MainPage Component ...

   function MainPage({Logo, mainLinks, mainBodies}) {
     return (
       <div>
         <div>
           <Logo/>
         </div>
         <div>
           {mainLinks.map( ([fassetsKey, MainLink]) => <MainLink key={fassetsKey}/>)}
         </div>
         <div>
           {mainBodies.map( (MainBody, indx) => <MainBody key={indx}/>)}
         </div>
       </div>
     );
   }
   
   export default withFassets({
     component: MainPage,  // NOTE: auto wrap MainPage
     mapFassetsToProps: {   // NOTE: static structure (mapFassetsToPropsStruct)
       Logo:       'company.logo',
                   // Logo:  companyLogoResource,
   
       mainLinks:  'MainPage.*.link@withKeys',
                   // mainLinks:  [['MainPage.cart.link',   cartLinkResource],
                   //              ['MainPage.search.link', searchLinkResource]],
       mainBodies: 'MainPage.*.body'
                   // mainBodies: [cartBodyResource, searchBodyResource],
     }
   });
   

2. Inject fasset resources from a functional directive (mapFassetsToPropsFn), returning the HoF - immediately invoked ...

   function MainPage({mainLinks, mainBodies}) {
     return (
       ... same as prior example
     );
   }
   
   export default withFassets({
     mapFassetsToProps(ownProps) { // NOTE: functional directive (mapFassetsToPropsFn)
       ... some conditional logic based on ownProps
       return {
         Logo:       'company.logo',
                     // Logo:  companyLogoResource,
   
         mainLinks:  'MainPage.*.link@withKeys',
                     // mainLinks:  [['MainPage.cart.link',   cartLinkResource],
                     //              ['MainPage.search.link', searchLinkResource]],
         mainBodies: 'MainPage.*.body'
                     // mainBodies: [cartBodyResource, searchBodyResource],
       };
     }
   })(MainPage); // NOTE: immediately invoke the HoF, emitting the wrapped MainPage Component
   

createAspect(name, [genesis], validateFeatureContent, [expandFeatureContent], assembleFeatureContent, [assembleAspectResources], [initialRootAppElm], [injectRootAppElm], [config], [additionalMethods]) ⇒ Aspect

The Aspect object promotes a series of life-cycle methods that feature-u invokes in a controlled way. This life-cycle is controlled by launchApp() ... it is supplied the Aspects, and it invokes their methods.

The essential characteristics of the Aspect life-cycle is to:

• accumulate AspectContent across all features
• perform the desired setup and configuration
• expose the framework in some way (by injecting a component in the root DOM, or some Aspect Cross Communication mechanism)

The Extending feature-u section provides more insight on how Aspects are created and used.

Please Note this function uses named parameters. The order in which these items are presented represents the same order they are executed.

Returns: Aspect - a new Aspect object (to be consumed by launchApp()).

extendAspectProperty(name, owner)

feature-u keeps track of the agent that owns this extension (using the owner parameter). This is used to prevent exceptions when duplicate extension requests are made by the same owner. This can happen when multiple instances of an aspect type are supported, and also in unit testing.

Throws:

• Error when supplied name is already reserved by a different owner

Fassets : Object

SideBar: The term fassets is a play on words. While it is pronounced "facet" and is loosely related to this term, it is spelled fassets (i.e. feature assets).

There are 3 different ways to reference the resources contained in the fassets object:

1. You may directly dereference them. As an example, an 'action.openView' resource can be dereferenced as follows:

   fassets.action.openView('mainView');
   

2. You may use the Fassets.get() method, which can collect multiple resources (using Wildcards).

3. Your UI components may indirectly access fassets resources through the withFassets() Higher-order Component (HoC).

SideBar: There are several ways to get a handle to the fassets object (see Obtaining fassets object).

For more information, please refer to Cross Feature Communication and Basic Concepts: fassets.

• Fassets : Object
  • .get(fassetsKey) ⇒ resource | Array.<resource>
  • .hasFeature(featureName) ⇒ boolean

Fassets.get(fassetsKey) ⇒ resource | Array.<resource>

The fassets.get() method is an alternative to directly dereferencing the fassets object ... the advantage being:

1. it can accumulate a series of resources (when Wildcards are used)

2. and it can more gracefully return undefined at any level within the federated namespace path

Regarding the fassetsKey:

• It is case-sensitive (as are the defined resources).

• It may contain Wildcards (*), resulting in a multiple resources being returned (a resource array), matching the supplied pattern

• Matches are restricted to the actual fassetKeys registered through the fassets aspect define/defineUse directives. In other words, the matching algorithm will not drill into the resource itself (assuming it is an object with depth).

• The special dot keyword ('.') will return the fassets object itself (in the same tradition as "current directory").

• '@withKeys':

  In some cases, you may wish to know the corresponding fassetsKey of the returned resource. This is especially true when multiple resources are returned (using wildcards). As an example, JSX requires unique keys for array injections (the fassetsKey is a prime candidate for this, since it is guaranteed to be unique).

  To accomplish this, simply suffix the fassetsKey with the keyword: '@withKeys'. When this is encountered, the resource returned is a two-element array: [fassetsKey, resource]. SideBar: We use this suffix technique (as opposed to an additional parameter) to be consistent with how withFassets() operates.

SideBar: The fassets.get() method is the basis of both the useFassets() React Hook, and the withFassets() Higher-order Component (HoC).

Returns: resource | Array.<resource> - the requested fassets resource(s).

• without wildcards, a single resource is returned (undefined for none).

  'a.b.c':          abcResource
  'a.b.c@withKeys': ['a.b.c', abcResource]
  

• with wildcards, the return is a resource array, in order of feature expansion (empty array for none).

  'a.*':          [ab1Resource, ab2Resource, ...]
  'a.*@withKeys': [ ['a.b1', ab1Resource], ['a.b2', ab2Resource], ... ]
  

Fassets.hasFeature(featureName) ⇒ boolean

Note: As an alternative to using this method, you can conditionally reason over the existence of "well-known fasset resources" specific to a given feature.

Returns: boolean - true: is active, false: is not active (or doesn't exist).

Feature : Object

Each feature within an application promotes a Feature object (using createFeature()) which catalogs the aspects of that feature.

Ultimately, all Feature objects are consumed by launchApp().

Feature content are simple key/value pairs (the key being an Aspect.name with values of AspectContent). These aspects can either be built-in (from core feature-u), or extensions.

Here is an example:

export default createFeature({
  name:     'featureA', // builtin aspect (name must be unique across all features within app)
  enabled:  true,       // builtin aspect enabling/disabling feature

  fassets: {            // builtin aspect promoting Public Face - Cross Feature Communication
    define: {
      'api.openA':  () => ...,
      'api.closeA': () => ...,
    },
  },

  appWillStart: (...) => ..., // builtin aspect (Application Life Cycle Hook)
  appInit:      (...) => ..., // ditto
  appDidStart:  (...) => ..., // ditto

  reducer: ..., // feature redux reducer (extended aspect from the feature-redux plugin)
  logic:   ..., // feature logic modules (extended aspect from the feature-redux-logic plugin)
});

For more information, please refer to Feature & aspect content.

appWillStartCB ⇒ reactElm | void

This life-cycle hook can do any type of general app-specific initialization (for example initializing a PWA service worker).

In addition, it can optionally inject static content in the app's DOM root. Any return is interpreted as the app's new rootAppElm (an accumulative process). IMPORTANT: When this is used, the supplied curRootAppElm MUST be included as part of this definition (accommodating the accumulative process of other feature injections)! More information is available at Injecting DOM Content

For more information (with examples), please refer to the Guide's appWillStart.

Please Note this function uses named parameters.

Returns: reactElm | void - optionally, new top-level content (which in turn must contain the supplied curRootAppElm). Use a void return when top-level content is unchanged.

appInitCB ⇒ Promise | void

This hook is invoked when the app is nearly up-and-running.

• The React Registration has already occurred (via the registerRootAppElm() callback). As a result, you can rely on utilities that require an app-specific rootAppElm to exist.

• You have access to the appState and dispatch() function, assuming you are using redux (when detected by feature-u's plugable aspects).

Just like the appWillStart() hook, you may perform any type of general initialization that is required by your feature.

However the hallmark of this hook is you can block for any asynchronous initialization to complete. By simply returning a promise, feature-u will wait for the process to complete.

The user is kept advised of any long-running async processes. By default an 'initializing feature: {feature.name}' message is used, but you can customize it through the supplied showStatus() function parameter.

For more info with examples, please see the Guide's appInit.

Please Note this function uses named parameters.

Returns: Promise | void - optionally, a promise (for asynchronous processes) - and feature-u will wait for the process to complete. Use a void return (for synchronous processes) - and no blocking will occur.

appDidStartCB ⇒

This life-cycle hook can be used to trigger "the app is running" events. A typical usage is to "kick start" some early application logic.

Because the app is up-and-running at this time, you have access to the appState and dispatch() function ... assuming you are using redux (when detected by feature-u's plugable aspects).

For more info with examples, please see the Guide's appDidStart.

Please Note this function uses named parameters.

Returns: void

fassets : BuiltInAspect

SideBar: The term fassets is a play on words. While it is pronounced "facet" and is loosely related to this term, it is spelled fassets (i.e. feature assets).

Feature resources are accumulated across all features, and exposed through the Fassets object. They can also be referenced via the withFassets() HoC.

The fassets aspect can both define resources, and/or declare a resource contract (i.e. the intention to use a set of fasset resources). This is accomplished via three separate fassets directives: define, use, and defineUse. A good summary of these directives can be found at fassets Recap: Push or Pull.

1. define: define public resources, held in the Fassets object

   fassets: {
     define: {
       '{fassetsKey}': {fassetsValue}
   
       ... 
   
       NOTES:
        - fassetsKey MUST be unique
        - are case-sensitive
        - may contain federated namespace (via dots ".")
          ... normalized in fassets object
          ... ex: 'MainPage.launch'
        - may be any valid JS identifier (less $ support)
        - may NOT contain wildcards
          ... i.e. must be defined completely
   
       // examples ...
       'openView': actions.view.open, // fassets.openView(viewName): Action
   
       // federated namespace example
       'selector.currentView': selector.currentView, // fassets.selector.currentView(appState): viewName
   
       // UI Component example
       'MainPage.cart.link': () => <Link to="/cart">Cart</Link>,
       'MainPage.cart.body': () => <Route path="/cart" component={ShoppingCart}/>,
     }
   }
   

2. use: specify public resource keys that will be used by the containing feature (i.e. a resource contract)

   fassets: {
     use: [
       '{fassetsKey}',
       -or-
       ['$fassetsKey', {required: true/false, type: $validationFn}],
   
       ... 
   
       NOTES:
        - each key will be supplied by other features
        - this is a communication to other features (i.e. a contract)
          ... saying: I plan to "use" these injections
          HOWEVER: feature-u cannot strictly enforce this usage
                   ... enclosed feature should reference this
                       {fassetsKey} through fassets.get(), or withFassets()
        - is case-sensitive
        - may contain federated namespace (with dots ".")
          ... ex: 'MainPage.launch'
        - may be any valid JS identifier (less $ support)
        - may contain wildcards (with "*")
          ... ex: 'MainPage.*.link'
   
       // examples ...
       'MainPage.launch',
   
       // may contain wildcards ...
       'MainPage.*.link',
       'MainPage.*.body',
   
       // optionally supply options object, controlling optionality and data types
       ['MainPage.*.link',  { required: true,   type: any  }], // same as DEFAULTS
       ['MainPage.*.link',  { required: false,             }], // optional of any type
       ['MainPage.*.link',  {                   type: comp }], // required of react component type
       ['MainPage.*.link',  { required: false,  type: comp }], // optional of react component type
     ]
   }
   

3. defineUse: define public resources specified by other features (via the use directive)

   fassets: {
     defineUse: {
       '{fassetsKey}': {fassetsValue}
   
       ... 
   
       NOTES:
        - this is identical to fassets.define EXCEPT:
        - it MUST MATCH a fassets.use directive
          ... using this directive, feature-u will perform additional
              validation to unsure these entries match a use contract
   
       // examples ...
       'MainPage.cart.link': () => <Link to="/cart">Cart</Link>,
       'MainPage.cart.body': () => <Route path="/cart" component={ShoppingCart}/>,
     }
   }
   

For more information, please refer to Cross Feature Communication, Fassets object, the withFassets() HoC, and the fassets Recap: Push or Pull.

expandWithFassetsCB ⇒ AspectContent

For more information (with examples), please refer to Managed Code Expansion.

Returns: AspectContent - The desired AspectContent (ex: reducer, logic module, etc.).

fassetValidations : Object

These validations are available as a convenience. Additional validations can be created as needed.

The validation API should adhere to the following signature:

 + fassetValidationFn(fassetsValue): string || null

A return value of null represents a valid value, while a string specifies a validation error that feature-u will format as follows (see ${returnStr}):

  VALIDATION ERROR in resource: '${fassetsKey}',
    expecting: ${returnStr} ... 
    resource defined in Feature: '${resource.definingFeature}',
    usage contract '${useKey}' found in Feature: '${featureName}'

The following pre-defined validations are promoted through fassetValidations:

• any: any type (except undefined)
• comp: a react component
• fn: a function
• str: a string
• bool: a boolean

Example:

createFeature({
  fassets: {
    use: [
       'MainPage.*.link', // DEFAULT: required of type any
      ['MainPage.*.body', {required: false, type: fassetValidations.comp}],
    ],
  },
});

registerRootAppElmCB ⇒

Because this registration is accomplished by app-specific code, feature-u can operate in any of the React platforms, such as: react web, react-native, expo, etc.

Please refer to React Registration for more details and complete examples.

Returns: void

showStatusCB ⇒

These status messages originate from the blocking that occurs in the asynchronous processes managed by the Feature.appInit() life-cycle-hook.

By design feature-u has no ability to manifest messages to the end user, because this is very app-specific in styling and other heuristics. By default (when NO showStatus parameter is supplied, feature-u will simply console log these messages.

A typical manifestation of this callback is to display a running persistent SplashScreen, seeded with the supplied message. The SplashScreen should be taken down when NO message is supplied (i.e. '').

Please refer to Feature.appInit() for more details and examples.

Returns: void

mapFassetsToPropsStruct : Object

The injected Component properties will reference the fasset resource corresponding to the fassetsKey.

Each fassetsKey is case-sensitive (as are the defined resources).

Matches are restricted to the actual fassetKeys registered through the fassets aspect define/defineUse directives. In other words, the matching algorithm will not drill into the resource itself (assuming it is an object with depth).

The special dot keyword ('.') will yield the fassets object itself (in the same tradition as "current directory"). This is useful if you wish to inject fassets into downstream processes (such as redux connect() via it's ownProps).

Wildcards

Wildcards (*) are supported in the fassetsKey, accumulating multiple resources (a resource array), matching the supplied pattern:

• without wildcards, a single resource is injected (undefined for none).

• with wildcards, a resource array is injected, in order of feature expansion (empty array for none).

Example ...

mapFassetsToProps: {
  Logo:       'company.logo',
              // Logo:  companyLogoResource,

              // NOTE: wildcard usage ...
  mainLinks:  'MainPage.*.link',
              // mainLinks:  [cartLinkResource, searchLinkResource],
  mainBodies: 'MainPage.*.body'
              // mainBodies: [cartBodyResource, searchBodyResource],
}

@withKeys

In some cases, you may wish to know the corresponding fassetsKey of the returned resource. This is especially true when multiple resources are returned (using wildcards).

As an example, React requires a key attribute for array injections (the fassetsKey is a prime candidate for this, since it is guaranteed to be unique).

To accomplish this, simply suffix the fassetsKey with the keyword: '@withKeys'. When this is encountered, the resource returned is a two-element array: [fassetsKey, resource].

Example ...

mapFassetsToProps: {
  Logo:       'company.logo',
              // Logo:  companyLogoResource,

  mainLinks:  'MainPage.*.link@withKeys', // NOTE: @withKeys directive
              // mainLinks:  [['MainPage.cart.link',   cartLinkResource],
              //              ['MainPage.search.link', searchLinkResource]],
  mainBodies: 'MainPage.*.body'
              // mainBodies: [cartBodyResource, searchBodyResource],
}

This topic is discussed in more detail in: React Keys (in array processing).

mapFassetsToPropsFn ⇒ mapFassetsToPropsStruct

Returns: mapFassetsToPropsStruct - the structure defining a prop/fassetsKey mapping, from which fasset resources are injected into a Component.

Aspect : Object

The Aspect object promotes a series of life-cycle methods that feature-u invokes in a controlled way. This life-cycle is controlled by launchApp() ... it is supplied the Aspects, and it invokes their methods.

Typically Aspects are packaged separately (as an external npm feature-u extension), although they can be created locally within a project (if needed).

For more information, please refer to Extendable aspects and Extending feature-u.

AspectContent : Any

The content type is specific to the Aspect. For example, a redux Aspect assembles reducers (via Feature.reducer), while a redux-logic Aspect gathers logic modules (via Feature.logic), etc.

AspectContent can either be defined from built-in aspects (via core feature-u), or extensions (from Aspect).

An Aspect object extends feature-u by accumulating information of interest from Feature objects (indexed by the Aspect name).

Note: Whenever AspectContent definitions require the Fassets object at code expansion time, you can wrap the definition in a expandWithFassets() function. In other words, your aspect content can either be the actual content itself (ex: a reducer), or a function that returns the content.

For more information, please refer to Feature & aspect content.

genesisMeth ⇒ string

This hook can perform Aspect related initialization and validation:

• initialization: this is where where proprietary Aspect/Feature APIs should be registered (if any) - via extendAspectProperty() and extendFeatureProperty() (please see: Aspect Cross Communication).

• validation: this is where an aspect can verify it's own required configuration (if any). Some aspects require certain settings (set by the application) in self for them to operate.

API: genesis(): string

Returns: string - an error message when self is in an invalid state (falsy when valid). Because this validation occurs under the control of launchApp(), any message is prefixed with: 'launchApp() parameter violation: '.

validateFeatureContentMeth ⇒ string

API: validateFeatureContent(feature): string

Returns: string - an error message string when the supplied feature contains invalid content for this aspect (falsy when valid). Because this validation conceptually occurs under the control of createFeature(), any message is prefixed with: 'createFeature() parameter violation: '.

expandFeatureContentMeth ⇒ string

API: expandFeatureContent(fassets, feature): string

The default behavior simply implements the expansion algorithm defined by expandWithFassets():

feature[this.name] = feature[this.name](fassets);

This default behavior rarely needs to change. It however provides a hook for aspects that need to transfer additional content from the expansion function to the expanded content. As an example, the reducer aspect must transfer the slice property from the expansion function to the expanded reducer.

Returns: string - an optional error message when the supplied feature contains invalid content for this aspect (falsy when valid). This is a specialized validation of the expansion function, over-and-above what is checked in the standard validateFeatureContent() hook.

assembleFeatureContentMeth ⇒

API: assembleFeatureContent(fassets, activeFeatures): void

Returns: void

assembleAspectResourcesMeth ⇒

API: assembleAspectResources(fassets, aspects): void

This is an optional second-pass (so-to-speak) of Aspect data gathering, that facilitates Aspect Cross Communication. It allows an extending aspect to gather resources from other aspects, using an additional API (ex: Aspect.getXyz()).

Returns: void

initialRootAppElmMeth ⇒ reactElm

API: initialRootAppElm(fassets, curRootAppElm): rootAppElm

The Defining rootAppElm section highlights when to use initialRootAppElm() verses injectRootAppElm().

NOTE: When this hook is used, the supplied curRootAppElm MUST be included as part of this definition!

Returns: reactElm - a new react app element root (which in turn must contain the supplied curRootAppElm), or simply the supplied curRootAppElm (if no change).

injectRootAppElmMeth ⇒ reactElm

API: injectRootAppElm(fassets, curRootAppElm): rootAppElm

The Defining rootAppElm section highlights when to use initialRootAppElm() verses injectRootAppElm().

NOTE: When this hook is used, the supplied curRootAppElm MUST be included as part of this definition!

Returns: reactElm - a new react app element root (which in turn must contain the supplied curRootAppElm), or simply the supplied curRootAppElm (if no change).