mirror of
https://github.com/flynx/features.js.git
synced 2025-12-27 13:32:04 +00:00
228 lines
4.5 KiB
Markdown
Executable File
228 lines
4.5 KiB
Markdown
Executable File
# `features.js`
|
|
|
|
`features.js` organizes sets of [actions](https://github.com/flynx/actions.js)
|
|
or _object methods_ into features, applies them, manages merging of features via
|
|
inter-feature dependencies and external criteria.
|
|
|
|
|
|
- [`features.js`](#featuresjs)
|
|
- [Basics](#basics)
|
|
- [Organizational structure](#organizational-structure)
|
|
- [Lifecycle](#lifecycle)
|
|
- [How features are loaded](#how-features-are-loaded)
|
|
- [The main entities:](#the-main-entities)
|
|
- [`FeatureSet()`](#featureset)
|
|
- [`<feature-set>.features`](#feature-setfeatures)
|
|
- [`<feature-set>.setup(..)`](#feature-setsetup)
|
|
- [`<feature-set>.remove(..)`](#feature-setremove)
|
|
- [`<feature-set>.gvGraph(..)`](#feature-setgvgraph)
|
|
- [`Feature(..)`](#feature)
|
|
- [Meta-features](#meta-features)
|
|
|
|
|
|
|
|
## Basics
|
|
|
|
```javascript
|
|
var features = require('ig-features')
|
|
```
|
|
|
|
### Organizational structure
|
|
|
|
- `FeatureSet`
|
|
Contains features, defines the main feature manipulation API, acts as the target
|
|
object constructor/factory.
|
|
- `Feature`
|
|
Creates a feature in the feature-set, defines the feature metadata, references
|
|
the feature mixin / action set and configuration.
|
|
- `ActionSet` / mixin
|
|
Contains the actions/methods of the feature mixin.
|
|
|
|
<!-- XXX -->
|
|
|
|
```javascript
|
|
// feature-set...
|
|
var App = new features.FeatureSet()
|
|
|
|
// features...
|
|
App.Feature('A', {
|
|
// ...
|
|
})
|
|
App.Feature('B', {
|
|
// ...
|
|
})
|
|
|
|
// meta-features...
|
|
App.Feature('all', [
|
|
'B',
|
|
'C',
|
|
])
|
|
|
|
// init and start the app...
|
|
var app = App.start(['all'])
|
|
```
|
|
|
|
|
|
### Lifecycle
|
|
|
|
<!-- XXX -->
|
|
|
|
|
|
### How features are loaded
|
|
|
|
<!-- XXX algorithm(s) -->
|
|
|
|
|
|
## The main entities:
|
|
|
|
### `FeatureSet()`
|
|
|
|
```bnf
|
|
FeatureSet()
|
|
-> <feature-set>
|
|
```
|
|
|
|
```javascript
|
|
var feature_set = new features.FeatureSet()
|
|
|
|
|
|
// define features...
|
|
// ...
|
|
|
|
|
|
// setup features...
|
|
feature_set
|
|
.setup([
|
|
'feature-tag',
|
|
//...
|
|
])
|
|
```
|
|
|
|
XXX
|
|
|
|
#### `<feature-set>.features`
|
|
|
|
<!-- XXX -->
|
|
|
|
|
|
#### `<feature-set>.setup(..)`
|
|
|
|
<!-- XXX -->
|
|
|
|
|
|
#### `<feature-set>.remove(..)`
|
|
|
|
<!-- XXX -->
|
|
|
|
|
|
#### `<feature-set>.gvGraph(..)`
|
|
|
|
Get a [Graphvis](https://graphviz.org/) graph spec for the feature dependency graph.
|
|
|
|
<!-- XXX -->
|
|
|
|
|
|
|
|
### `Feature(..)`
|
|
|
|
Standalone feature
|
|
```bnf
|
|
Feature({ tag: <tag>, .. })
|
|
Feature(<tag>, { .. })
|
|
Feature(<tag>, [<suggested-tag>, .. ])
|
|
Feature(<tag>, <actions>)
|
|
-> <feature>
|
|
```
|
|
|
|
Feature-set features
|
|
```bnf
|
|
<feature-set>.Feature({ tag: <tag>, .. })
|
|
<feature-set>.Feature(<tag>, { .. })
|
|
<feature-set>.Feature(<tag>, [<suggested-tag>, .. ])
|
|
<feature-set>.Feature(<tag>, <actions>)
|
|
-> <feature>
|
|
|
|
Feature(<feature-set>, { tag: <tag>, .. })
|
|
Feature(<feature-set>, <tag>, <actions>)
|
|
-> <feature>
|
|
```
|
|
|
|
Examples:
|
|
```javascript
|
|
feature_set.Feature('minimal_feature_example', {})
|
|
```
|
|
|
|
```javascript
|
|
feature_set.Feature({
|
|
// feature unique identifier (required)...
|
|
tag: 'feature_example',
|
|
|
|
// documentation (optional)...
|
|
title: 'Example Feature',
|
|
doc: 'A feature to demo the base API...',
|
|
|
|
// applicability test (optional)
|
|
isApplicable: function(){ /* ... */ },
|
|
|
|
// feature load priority (optional)
|
|
priority: 'medium',
|
|
|
|
// list of feature tags to load if available (optional)
|
|
suggested: [],
|
|
|
|
// list of feature tags required to load before this feature (optional)
|
|
depends: [],
|
|
|
|
// Exclusive tag (optional)
|
|
// NOTE: a feature can be a member of more than one exclusive group,
|
|
// to list more than one use an Array...
|
|
exclusive: 'Example',
|
|
|
|
// feature configuration (optional)
|
|
// NOTE: if not present here this will be taken from .actions.config
|
|
// NOTE: this takes priority over .actions.config, it is not recommended
|
|
// to define both.
|
|
config: {
|
|
option: 'value',
|
|
// ...
|
|
},
|
|
|
|
// actions (optional)
|
|
actions: Actions({
|
|
// alternative configuration location...
|
|
config: {
|
|
// ...
|
|
},
|
|
// ...
|
|
}),
|
|
|
|
// action handlers (optional)
|
|
handlers: [
|
|
['action.pre',
|
|
function(){ /* ... */ }],
|
|
// ...
|
|
],
|
|
})
|
|
```
|
|
|
|
XXX
|
|
|
|
|
|
|
|
### Meta-features
|
|
|
|
```javascript
|
|
// meta-feature...
|
|
feature_set.Feature('meta-feature-tag', [
|
|
'suggested-feature-tag',
|
|
'other-suggested-feature-tag',
|
|
// ...
|
|
])
|
|
```
|
|
|
|
XXX
|
|
|
|
|
|
|
|
<!-- vim:set ts=4 sw=4 spell : -->
|