Nothing Plus Modules

    te-flow

    0.4.0 • Public • Published

    teFlow A pipeline for control and flow

    No Maintenance Intendedlicense npm Dependencies Status wercker status

    Important!!!!

    I wrote this package early in my career because I needed a better way to control Functions and data flow. At the time of creation, I thought this was what functional programming entailed or was? Nevertheless, while I do not recommend you use this package it is an interesting concept, and it works, it fucking works hella magic considering I created this at a time when I had little idea what I was doing. (I still don’t know what I’m doing, but I do have a little better idea.) It’s the backbone of ctr, and it did the job for the time, but like I said previously I don’t recommend you use this package.

    Intro

    A function wrapper which creates a pipeline to help you organize your code in a cleaner functional manner. In a nutshell teFlow creates an argument pipeline/stream through apply so you can be functional with your thoughts and code.

    //The native way
    let res1 = one();
    let res2 = two.apply(null, res1);
    let res3 = three.apply(null, res2);
     
    //The teFlow way
    let res = teFlow(
      one,
      two,
      three
    );

    Usage

    Install

    npm install te-flow --save-dev
    
    yarn add te-flow
    

    Use

    var teFlow = require('te-flow');
    
    Alternative

    Download the te-flow.js or te-flow-browsers.js file depending on your use in the /lib folder and drop it into your project. The difference between the two files is the -browser injects all the dependencies into one file while the default uses require to include the dependencies.

    Compressed Files

    I recommend you use webpack to manage your Js assets but I understand this is sometimes not an option so in the lib folder I have also included compressed and non-webpacked files.

    Commands

    First, make sure you have yarn installed.

    SetUp

    yarn run link
    yarn install
    

    Test

    yarn test
    

    Development

    yarn run dev
    

    Build

    yarn run bulid
    

    Api

    Init Options

    • args || initArgs
      • Value: Object, Method, Object Methods
      • Sets the initial arguments which will be passed to the first function that is invoked.
    • this
      • Value: Object
      • Default: null
      • Sets the value of this that will be applied to your functions otherwise your functions will be applied with null ex:fn.apply(null, [args])
    • objReturn
      • Value: Boolean
      • Default: true
      • Allows you to return an object whose values are mapped and passed onto the next function as arguments instead of having to return an array or the arguments object making your code much more readable.
    • objKeep
      • Value: Boolean
      • Default: false
      • This is a particularly dangerous option, but useful in some use cases. What is does is process the first object returned and maps out those key/values pairs as separate individual object arguments. This can be quite useful with reduce and the like with certain data structures. But do note order in objects are not guaranteed in JavaScript
    • flow
      • Value:Boolean
      • Default:false
      • An interesting option, basically every return from each invoked function is pushed into the argument pipeline.
    • flatten
      • Value: Boolean
      • Default: false
      • Flattens any sub-arrays in the stream.

    Return Options

    Note: These options need to be passed as the initial object argument in the return.

    • _return
      • Value: Boolean
      • It will immediately return the values at hand and not call the next functions in line.
    • _kill
      • Value: Boolean
      • It will immediately return undefined and not call the next functions in line.
    • _objReturn
      • Value: Boolean
      • Temporarily alter the default setting for said function. _ _objKeep
      • Value: Boolean
      • Temporarily alter the default setting for said function.

    Control Options

    Note: Still it bit unsure how I want to handle these options yet.

    • start
      • Value: Object Methods
      • Arguments before applied to function.
    • end
      • Value: Object Methods
      • Arguments after applied to function.
    • res
      • Value: Object Methods
      • The value that is returned from all functions.
    • memoize
      • Value: Boolean
      • Default: true
      • Uses lodash memoize to reduce overhead.

    Examples

    Note: These examples are using ECMAScript 2015 syntax.

    Basic Concept

    The basic concept is that each function will be invoked and then the return will be passed onto the next function as the argument.

    const one = function () {
      return 1;
    };
     
    //oneVal the value returned from fn one
    //oneVal === 1
    const two = function (oneVal) {
      return oneVal + 1;
    };
     
    //oneVal the value returned from fn two
    //twoVal === 2
    const three = function (twoVal) {
      return twoVal + 1;
    };
     
    let res = teFlow(
      one,
      two,
      three
    );
    //res === 3

    Setting The Options

    Options are set via a call object argument or as a object being the first argument. If your using object method the option keys must be prefixed with _.

    //call
    let res = teFlow.call({
      this: self,
      flow: true,
      args: {
        argOne: 1,
        cool: 'dog'
      }},
      fnOne,
      fnTwo,
      fnThree
    );
     
    //obj
    let res = teFlow({
      _this: self,
      _flow: true,
      _args: {
        argOne: 1,
        cool: 'sorta'
      }},
      fnOne,
      fnTwo,
      fnThree
    );

    Ps. for the rest of these examples I will be using the call methodology.

    Passing Initial Arguments - args

    The args option allows you to set the initial arguments which in turn are applied to the first function.

    //All methods will produce the same arguments
    const fnOne = function (one, two, three) {
      //one === 1
      //two === true
      //three === 'three'
    };
     
    //Object
    teFlow.call({
      args: {
        one: 1,
        two: true,
        three: 'three'
      }},
      fnOne
    );
     
    //Method
    teFlow.call({
      args: function () {
        return {
          one: 1,
          two: true,
          three: 'three'
        };
      }},
      fnOne
    );
     
    //Object with methods
    teFlow.call({
      args: {
        one: function () {
          return 1;
        },
        two: function () {
          return true;
        },
        three: function () {
          return 'three';
        }
      }},
      fnOne
    );
     

    Object Return - objReturn

    By default the objReturn option is set to true to help you better organize and visualize what your are passing onto the next function. That being said, if you were to return a non object it will reset the argument stream to that value.

    const one = function () {
      return 1;
    };
     
    //oneVal === 1
    const two = function (oneVal) {
      let twoVal = oneVal++;
      return {
        oneVal,
        twoVal
      };
    };
     
    //oneVal === 1
    //twoVal === 2
    const three = function (oneVal, twoVal) {
      let threeVal = twoVal++;
      return {
        oneVal,
        twoVal,
        threeVal
      };
    };
     
    //oneVal === 1
    //twoVal === 2
    //threeVal === 3
    const addOne = function (oneVal, twoVal, threeVal) {
      oneVal++;
      twoVal++;
      threeVal++;
      return {
        oneVal,
        twoVal,
        threeVal
      };
    };
     
    let res = teFlow(
      one,
      two,
      three,
      addOne
    );
    //res === [2, 3, 4]

    Specified Return Object Method

    For convenience, readability, and a bit of extra control if you have a Object Method with the key of return as your last value it will be the final function that is invoked and whatever is return will be the results.

    //oneVal === 1
    const one = function (oneVal) {
      return {
        oneVal
      };
    };
     
    //oneVal === 1
    const two = function (oneVal) {
      let twoVal = 2;
      return {
        oneVal,
        twoVal
      };
    };
     
    //oneVal === 1
    //twoVal === 2
    const three = function (oneVal, twoVal) {
      let threeVal = 3;
      return {
        oneVal,
        twoVal,
        threeVal
      };
    };
     
     
    let res = teFlow.call({
      args: {
        oneVal: 1
      }},
      one,
      two,
      three, {
        //oneVal === 1
        //twoVal === 2
        //threeVal === 3
        return: function (oneVal, twoVal, threeVal) {
          // res will equale whatever is returned here
          return 'Beer Me!'
        }
      }
    );
    //res === 'Beer Me!'

    Object Keep - objKeep

    By default the objKeep option is set to false, nevertheless, as I said previously this is a particularly dangerous option, but useful in some use cases. What is does is process the first object returned and maps out those key/values pairs as separate individual object arguments. This can be quite useful with reduce and the like when dealing with certain data structures.

    Note: The order in objects are not guaranteed in JavaScript.

    //Merge helper
    const _ = require('lodash');
     
    const one = function () {
      return {
        keyOne: 1
      };
    };
     
    //oneVal === {keyOne: 1}
    const two = function (oneVal) {
      return _.merge(oneVal, {keyTwo: 2});
    };
     
    //oneVal === {keyOne: 1}
    //twoVal === {keyTwo: 2}
    const three = function (oneVal, twoVal) {
      return _.merge(oneVal, twoVal, {keyThree: 3});
    };
     
    let res = teFlow.call({objKeep: true},
      one,
      two,
      three
    );
    //res === [{keyOne: 1}, {keyTwo: 2}, {keyThree: 3}]

    While objKeep is great and all there will be times when you will not want it to be returned as such. Good news, you can override the set default on a individual function basis through your return and passing _objKeep as the first argument. This action is only temporary and after the return it will revert back to the set default.

    //using the same code as above just overriding the _objKeep
    const three = function (oneVal, twoVal) {
      //oneVal === {keyOne: 1}
      //twoVal === {keyTwo: 2}
      return {
        _objKeep: false,
        //make note of the key value pair
        one: _.merge(oneVal, twoVal, {keyThree: 3})
      };
    };
    //You might have expected a result like below but since
    //the obj is assinged to the `one` obj we are only passing
    //along one argument here
    //res === [{keyOne: 1, keyTwo: 2, keyThree: 3}]
     
    //Alternativly if you want to pass only the values just dont
    //assing the objs to a key
    const three = function (oneVal, twoVal) {
      //oneVal === {keyOne: 1}
      //twoVal === {keyTwo: 2}
      return {
        _objKeep: false,
        _.merge(oneVal, twoVal, {keyThree: 3})
      };
    };
     
    //res === [1, 2, 3,]

    Specified Return Object Method Example Two

    Long story short, I accidentally made another example for the specified return but rather than omitting it I will leave it here because it demonstrates a somewhat different use case. There might be times when you would like to specify your return to a certain global variable or something of the sort. Don't you fret my friend you can do so via passing an object as the last argument that has the key of return and then the corresponding value will be what is returned. The return can be a specified object or method.

    //To Be returned
    let globalArray = [];
    let staticStr = 'Static';
    let string = null;
     
    //oneVal === 'Did you'
    const two = function (oneVal) {
      globalArray.push(oneVal + ' say,');
      string = oneVal + ' say, ';
      return 'you';
    };
     
    //oneVal === 'you'
    const three = function (twoVal) {
      globalArray.push(twoVal + ' needed to');
      string += twoVal + ' needed to';
      return {
        key1: 'specify',
        key2: 'your',
        key3: 'return?',
        space: ' '
      };
    };
     
    //k1 === 'specify'
    //k2 === 'your'
    //k3 === 'return?'
    //sp === ' '
    const four = function (k1, k2, k3, sp) {
      globalArray.push(k1 + sp + k2 + sp + k3);
      string += sp + k1 + sp + k2 + sp + k3;
      return true;
    };
     
    let res = teFlow(
      one,
      two,
      three,
      four, {
        return: function (cool) {
          //cool === true
          return {
            static: staticStr,
            globalArray: globalArray,
            string: string,
            cool: cool
          };
        }
      }
    );
    // res = {
    //  static: 'Static',
    //  globalArray: ["Did you say,", "you needed to", "specify your return?"],
    //  string: "Did you say, you needed to specify your return?",
    //  cool: true
    // }
     

    This - this

    By default each function is invoked via fn.apply(null, [args]) so of course you have the ability to set this. In addition, you can reassign this in you return object via the _this key and the corresponding value will be reassigned to this.

    //A Little Module Pattern
    const beThis = (function () {
      let count = 0;
      let cool = function (obj) {
        this.name = obj.name;
        this.getName = function () {
          return this.name;
        };
        this.changeName = function (newName) {
          this.name = newName;
        };
        this.returnThis = function () {
          return this;
        };
        this.incNum = function () {
          count++;
        };
        this.rtnNum = function() {
          return count;
        };
      };
      return cool;
    })();
     
    const addMe = function () {
      return this.getName();
    };
     
    //name === '</artisin>'
    //bump shared count
    const changeMe = function (name) {
      this.incNum();
      //change name
      this.changeName('Te');
      return {
        oldName: name,
        newName: this.getName()
      };
    };
     
    //oldName === '</artisin>'
    //newName === 'Te'
    const addYou = function (oldName, newName) {
      //Add you
      var you = new beThis({
        name: 'You'
      });
      //bind me to current this ref for latter use
      var me = function() {
        return this;
      };
      me = me.call(this);
      return {
        //reassign this
        _this: you,
        me: me
      };
    };
     
    let res = teFlow.call({
      //set the `this` ref for `addMe`
      this: new beThis({
        name: '</artisin>'
      })},
      addMe,
      changeMe,
      addYou, {
        return: function (me) {
          //me ref to me this
          return {
            count: this.rtnNum(),
            myName: me.getName(),
            //reassigned this from prv fn
            yourName: this.getName()
          };
        }
      }
    );
     
    // res = {
    //   count: 1,
    //   myName: 'Te',
    //   yourName: 'You'
    // }

    Flow - flow

    With this option set to true every return will be added to a single return array. Additionally, you can pass flatten: true which will flatten any sub-arrays that are returned.

    const one = function () {
      return 1;
    };
    const two = function () {
      return 2;
    };
    const three = function () {
      //no return
    };
    const four = function () {
      return 4;
    };
     
    let res = teFlow.call({flow: true},
      one,
      two,
      three,
      four
    );
    // res === [1, 2, 4];

    Return - _return

    Returns values at said point and does not call the next functions in line. Note: If you have a return method in teFlow it will return the values to that return method.

    //oneVal === 1
    const one = function (oneVal) {
      return {
        oneVal: oneVal
      };
    };
     
    //oneVal === 1
    const two = function (oneVal) {
      let twoVal = 2;
      //return said vaules at this point
      return {
        _return: true,
        oneVal: oneVal,
        twoVal: twoVal
      };
    };
     
    const three = function (oneVal, twoVal) {
      let threeVal = 3;
      return {
        oneVal: oneVal,
        twoVal: twoVal,
        threeVal: threeVal
      };
    };
     
    const res = teFlow.call({
      args: {
        oneVal: 1
      }},
      one,
      two,
      three
    );
    // res === [1, 2];

    Kill - _kill

    Stops everything and returns undefined

    //oneVal === 1
    const one = function (oneVal) {
      return {
        oneVal: oneVal
      };
    };
     
    //oneVal === 1
    const two = function (oneVal) {
      let twoVal = 2;
      //return said vaules at this point
      return {
        _kill: true,
        oneVal: oneVal,
        twoVal: twoVal
      };
    };
     
    const three = function (oneVal, twoVal) {
      let threeVal = 3;
      return {
        oneVal: oneVal,
        twoVal: twoVal,
        threeVal: threeVal
      };
    };
     
    const res = teFlow.call({
      args: {
        oneVal: 1
      }},
      one,
      two,
      three
    );
    // res === undefined;

    Control Methods

    Docs Coming Soon, need to do some cogitating Note: I did write some early test for these methods if you would like a better picture.

    These methods will be invoked every start, end, or as the result of the current function. The functions will be applied in order as listed. For example if your end arguments look something like this [1, 2, 3] and you had two function it would do the following: fn1(arg[0]), fn2(arg[0]), fn1(arg[1]), fn2(arg[1]), ...

    Install

    npm i te-flow

    DownloadsWeekly Downloads

    7

    Version

    0.4.0

    License

    MIT

    Last publish

    Collaborators

    • artisin