yukon - npm Package Compare versions
Comparing version 1.4.2 to 1.4.3
| { | ||
| "name": "yukon", | ||
| "version": "1.4.2", | ||
| "version": "1.4.3", | ||
| "description": "Self-discovering API-driven web components", | ||
@@ -5,0 +5,0 @@ "main": "yukon.js", |
@@ -1,15 +0,15 @@ | ||
| # yukon API framework | ||
|  | ||
| # yukon component framework | ||
| [![NPM Version][npm-image]][npm-url] | ||
| [![NPM Downloads][downloads-image]][downloads-url] | ||
| yukon is a component-based framework built on top of node/express - which makes 0-n asynchronous REST API calls in parallel to provide back-end data for each express request. It extends the [nodulejs component framework](https://github.com/jackspaniel/nodulejs). | ||
| yukon is a component-based, datasource-agnostic framework for serving web content. It extends the [nodulejs component framework](https://github.com/jackspaniel/nodulejs) - to include back-end data gathering, standardized slots for app-defined middleware and template management. | ||
| Note: The API behavior of yukon can be overriden by specifying your own config.middlewares.getData function. See Config section below for more details. | ||
| Back-end data-gathering is achieved through plugins. Currently the only fully-fleshed out plugin makes 0-n REST API calls in parallel - as that was our need. I have made some starts on mysql and solr plugins, but would like a real - world implementation to battle-test them on. So by all means if you stumble across this repository, shoot me an email and I will work with you to get it up and running for your needs. | ||
| __TODO: I'm working on making yukon data source agnostic and splitting off the API stuff into a plugin. In that way yukon can support any type or amount of eithr plugin or one-off data-gathering middleware. ETA: Jan 13th, 2015__ | ||
| Data-gathering plugins can also be bypassed entirely by specifying a custom config.middlewares.getData function. See Config section below for more details. | ||
| __UPDATE: data gathering via plugins have been implemented. mysql and solr are still a WIP in progress though. Some of the stuff below is out of date__ | ||
| A really simple yukon component looks like this: | ||
| A really simple yukon component (using the parallel-api plugin) looks like this: | ||
| ```js | ||
@@ -53,3 +53,3 @@ module.exports = function(app) { | ||
| A *__yukon nodule__* extends the base nodule behavior to include REST API data gathering, stub-handling and template-rendering. Yukon attaches data returned from the API(s) as the res.yukon object, and sends res.yukon.renderData to the template or straight back to the client as JSON. | ||
| A *__yukon nodule__* extends the base nodule behavior to include data gathering, stub-handling and template-rendering. It also allows custom app-defined middleware to be declared between each step of the request/response chain. Yukon attaches data returned as the res.yukon object, and sends res.yukon.renderData to the template or straight back to the client as JSON. | ||
@@ -78,3 +78,3 @@ *Nodulejs was split off from yukon to separate out the core self-discovery and initialization features, which can potentially be a building block for a wide variety of node applications or frameworks.* | ||
| 1. Nodule-specific properties | ||
| 2. API-specific properties | ||
| 2. Data plugin-specific properties | ||
| 3. App-defined middleware functions and global settings | ||
@@ -98,11 +98,13 @@ | ||
| 3. __contentType:__ 'html' and 'json' are the only current values | ||
| 4. __preProcessor:__ use this function to manipulate query params or other business logic before api call | ||
| 5. __postProcessor__: use this function to process data returned from the API before calling template or sending back to client as JSON | ||
| 4. __preProcessor:__ use this function to manipulate query params or other business logic before back-end data-gathering | ||
| 5. __postProcessor__: use this function to process data returned from back-end data-gathering, before calling template or sending back to client as JSON | ||
| 6. __error:__ set to a string or an Error() instance to get the framework to call next(error) | ||
| *this property is added to nodule defaults by the parallel-api plugin* | ||
| 7. __apiCalls:__ array of API calls to made in parallel for this nodule, see the section below for details what constitutes an API call. | ||
| <br>NOTE: global or semi-global calls like getProfile, getGlobalNav, etc. can be added to this array in the preData middleware. | ||
| ### API-specific properties (config.apiDefaults) | ||
| ### API-specific properties added by the parallel-api plugin (plugins/parallel-api/index.js - config.apiDefaults) | ||
| Yukon defines the following properties for each API call. It is important to understand that these exist in a one-to-many relationship with nodules. | ||
| The yukon parallel-api plugin defines the following properties for each API call. It is important to understand that these exist in a one-to-many relationship with nodules. | ||
@@ -121,2 +123,7 @@ 1. __path:__ path to API (not including server). | ||
| The parallel-api plugin also allows 2 optional app-defined functions, which are executed before and after every API call. It's important to understand that there can be several API calls per express request. So these functions are not in the standard middleware chain, although the api callback does make use of the middleware paradigm. | ||
| 1. __apiCallBefore:__ a synchronous function executed before of every api call. Do any common API pre-processing here. | ||
| 2. __apiCallback:__ an asynchronous function executed after every api call, must execute next() if defined. Do error handling and other common post-API processing here. To do: consider moving error handling to framework and making this call synchronous. | ||
| ### App-defined middlware | ||
@@ -127,11 +134,6 @@ | ||
| 1. __start:__ called at start of middleware, before nodule.preProcessor | ||
| 2. __preData:__ called after nodule.preProcessor, before API call(s) | ||
| 3. __getData:__ middleware which gets all data (currently yukon uses doParallelApi by default, plan is to split that off into a plugin) | ||
| 4. __postData:__ called after API call(s), before nodule.postProcessor | ||
| 2. __preData:__ called after nodule.preProcessor, before data-gathering | ||
| 3. __getData:__ middleware which gets all data (Note: if specified in the app config, this function will bypass all plugin behavior) | ||
| 4. __postData:__ called after data gathering, before nodule.postProcessor | ||
| 5. __finish:__ called after nodule.postProcessor, before res.send() or res.render() | ||
| An app can also create 2 global functions, which are executed before and after every API call. It's important to understand that there can be several API calls per express request. So these functions are not in the standard middleware chain, although the api callback does make use of the middleware paradigm. | ||
| 1. __apiCallBefore:__ a synchronous function executed before of every api call. Do any common API pre-processing here. | ||
| 2. __apiCallback:__ an asynchronous function executed after every api call, must execute next() if defined. Do error handling and other common post-API processing here. | ||
@@ -153,12 +155,9 @@ ### Global properties | ||
| ## To Do | ||
| 1. Split off doApi into a plugin so other forms of data gathering middleware can be used. | ||
| 2. Reconsider stub behavior. Should all stubs move to apiSim behavior? What about brand new nodules where nothing is known about the API yet? | ||
| 3. Get demoApp working as standalone. | ||
| 4. Write more detailed unit tests? | ||
| 5. Hook up Travis CI and code coverage. | ||
| 1. Reconsider stub behavior for parallel-api. Should all stubs move to apiSim behavior? What about brand new nodules where nothing is known about the API yet? | ||
| 2. Get demoApp working as standalone. | ||
| 3. Hook up Travis CI and code coverage. | ||
| ## Features for future consideration | ||
| + __Other forms of async data gathering.__ See To Do #1. Currently yukon only knows how to make REST API calls. But it woudn't take much work to extend this behavior to any sort of asynchronous data store - such as a Mongo DB or Redis cache. | ||
| + __Sequential API calls.__ Currently yukon makes all API calls in parallel. We've been fortunate in that we haven't needed dependent API calls yet. | ||
| + __API error handling.__ It seems that there can be a huge variation in error behavior, and even in what constitutes an API error (status code-based?), from web-app to web-app. So for now I've punted on advanced API error handling, and let the app deal with it in the API callback. But if something like a standard is more or less agreed-upon, I will be happy to add flexible error handling. | ||
| + __Flesh out more plugins.__ Currently only the paralle-api plugin is fully operational. I need real-world sites to test this out on. (Free consulting!) | ||
| + __API error handling for parallel-api plugin.__ It seems that there can be a huge variation in error behavior, and even in what constitutes an API error (status code-based?), from web-app to web-app. So for now I've punted on advanced API error handling, and let the app deal with it in the API callback. But if something like a standard is more or less agreed-upon, I will be happy to add flexible error handling. | ||
@@ -165,0 +164,0 @@ ## Examples: |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by283.22%
159255
- Number of package files
- increased by5.88%
18
Worsened metrics
- Number of lines in readme file
- decreased by-0.3%
332
No dependency changes