Giter VIP home page Giter VIP logo

yearn's Introduction

yearn

NPM Version NPM License NPM Downloads

Dependencies Dev Dependencies

Build Status Coverage Status GitHub issues

Overview

yearn is a library that injects functionality into Node's require mechanism providing the ability to transform the require before it's passed to load. A default mechanism is injected so that all requires look for ./node_modules/module/version instead of node's default ./node_modules/module location. There is also support for orgs, which allows for a more central placement of all modules or separation of public and private modules (default org points to ./node_modules for backward compatibility). yearn also provides wrappers around node (ynode) and npm (ynpm) to automaticaly enforce yearn requiring.

Installation

Local installation:

$ npm install yearn

Global installation:

$ npm install yearn -g

Local Usage

To use yearn for a single project it needs to be installed locally. Due to the fact that it needs to be bootstrapped it must be installed in the traditional npm structure. All other modules may be installed in any way compatible with the yearn implementation.

Once installed locally require it and provide initialization options before using the new require mechanism.

Example initialization with a few options and then some requires:

var yearn = require( 'yearn' )({ 
	orgs: {
		test: '/usr/bin/test_modules'
		local: '/usr/bin/my_modules'
	},
	override: true
});

// Simple backward compatible yearning 
var log4js = yearn( 'log4js' );

// Explicit yearning for a semantic version with modern syntax
var nodeunit = yearn( { org: 'test', module: 'nodeunit', version: '0.9.x' } );

// Implicit require for a specific version with string syntax
var lodash = require( '[email protected]' );

// Explicit require without org or version (default with pull version and org from package.json) 
var loca_module = require( { module: 'my_local_module' } );

Global Usage

See ynode and ynpm below for the global scripts that are provided with yearn.

YEARN_CONFIG is an evironment variable that is read when ever ynode and ynpm are started up. This environment variable should point to a .json file containing the global yearn config. All the options for local yearn below are supported.

Options

var yearn = require( 'yearn' )({
	orgs: { '', './node_modules' },
	override: true,
	prompt: 'ynode> ',
	delimiters: {
		org: ':',
		semver: '@',
		file: '/'
	},
	aliases: [
	],
	npmconfig: {
	}
});
  • orgs: The orgs config object is a mapping of organization names to their locations. The default location ( '' ) will point to the module's local node_modules folder (./node_modules) unless overridden.

    Example:

      var yearn = require( 'yearn' )({
      	orgs: { 
      		'', '//usr/bin/default_node_modules_location' 
      		'other_loc': '//some/other/location'	
      	}
      });
    
      // require looking in '//usr/bin/default_node_modules_location/module1' for a version specified in the package.json for module1.
      var regular_module = require( 'module1' );  
    
      // require looking in '//some/other/location/module2' for a version specified in the package.json for module2.
      var other_modules = require( 'other:module2' );
    
  • override: This boolean specifies if yearn should override Node's require mechanism or should only return the yearn functionality. Additionaly if a function is provided than yearn will ignore all of it's default functionality and override require with that functionality instead.

    There are a few thing that one should know if your going to override the functionality yourself. Firstly this does not override the most outer form of require and thus you end up limited to two arguments getting passed to your function (what the user passes to require or resolve and the parent module of the call). The function you are infact overriding is module.constructor._resolveFilename so that your code works in both the require and require.resolve contexts. Yearn will also override some functionality in require so that it doesn't restrict passed arguments to strings. Secondly yearn does not load or compile the modules itself it is only overriding the resolve aspect, node's internal compiler and loader should take it from there. The result of your override functionality should be the full path to the module's file.

  • prompt: Set the prompt of the ynode REPL. Defaults to ynode>.

  • delimiters: The delimiters option is a way to set the delimiters between org, module, version and specific file parts of a string based require. By default these values are : between org and module, @ between module and version similarly to how semver does their versioning and / to state that the require is for a particular file in the module. These should not be the same delimiter (prior to version 0.2.0 of yearn they were all / and that lead to problems with pre existing modules like npm and grunt).

    • org: the separator between an org and module (defaults to :).
    • semver: the separator between a module and the desired semver to match (defaults to @).
    • file: the separator to determine the path to find the file within the found module (defaults to /).
  • aliases: This option allows for globally mapping whole orgs, specific modules or even specific versions of modules to other orgs, modules or versions. These aliases not only affect runtime but also are applied when installing new modules via ynpm.

    Example:

      var yearn = require( 'yearn' )({
      	orgs: { 
      		'', '//usr/bin/default_node_modules_location' 
      		'other_loc': '//some/other/location'	
      	},
      	aliases: [
      		{
      			from: { org: 'other_loc' },
      			to: { org: '' }
      		},{
      			from: { module: 'nodeunit', version: '<0.9.0' },
      			to: { module: 'nodeunit', version: '^0.9.1' }
      		}		
      	]
      });
    
  • npmconfig: This option only pertains to ynpm. This object can be populated with parameters that ynpm should initialize it's internal npm library with when it executes npm commands.

ynode

ynode is a small wrapper around node itself that will enforce a YEARN_CONFIG. Running with arguments will interpret the first as a script and perform a require of it. Executing ynode without any arguments will open a REPL with a YEARN_CONFIG already interpreted.

If one wants to force the use of ynode over node then change the globally installed scripts from ynode and ynode.cmd to node and node.cmd. Then make sure that the folder where the scripts appears before the folder where node is installed. Finally go into the altered ynode script and change the #! to point to the actual node instead of /usr/bin/env node. Then whenever node is called or a node script is run it will be run through the ynode script.

ynpm

ynpm is a small wrapper around some of npm's functionality. This script can be used to install modules into the org/module/version structure that yearn uses by default. There are only a few functionalities supported thus far:

  • ynpm check [orgs_or_specific_modules...]: Print the modules that need to be updated and to what version.

  • ynpm help: Print the ynpm usage information.

  • ynpm install [module]: Search for and list all available versions of the module.

  • ynpm list [args](IN DEVELOPMENT): Manage npm configuration.

  • ynpm orgs: Print the current orgs as specified by the YEARN_CONFIG.

  • ynpm version: Print the version of yearn currently associated with ynpm.

yearn's People

Contributors

doctorrustynelson avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

yearn's Issues

ynpm package manager skeleton

Skeleton for the ynpm ( ynpm is not an acronym for yearn node package manager ). This should include the most basic check features:

  • ynpm version
  • ynpm help

ynode --recordDependencies

The --recordDependencies option should force ynode to fill in the package.json (or shrinkwrap.json) with the correct dependencies as requires occure.

ynode --legacy

This command line option should force yearn to fallback to legacy package resolution if all else fails even if legacy requires are not allowed in the config.

ynpm check <org>

Check that all the modules in the specified org are up to date (informing user if their not).

ynpm preinstall and postinstall hooks

First set of hooks. Need to conceive of a generic way to add these so they are always picked up and it's easier to specify others. Maybe using the package.json scripts as npm does.

ynpm install <module>

Install the specified module into the default org. That module's dependency tree should also be installed to the default org.

Yearn.resolve

This will probably require a refactoring of the code base especially when supporting overriding.

yearn.revert()

Undo a yearn config and revert back to legacy dependency resolution. YEARN_CONFIG should have an option to disable this functionality.

ynpm check

Check that all modules in all the orgs are up to date. Informing the user if their not.

ynpm install --org <org>

Install modules from the package.json to the specified org. When ynpm starts to install to those module's depencencies it should fall back to the default org. ( Should probably warn if the either org is a relative path ).

ynpm install

Raw ynpm install command should read in the package.json of the current module and install it's dependencies into the default org. It should also install the next level's dependencies so on and so forth.
(Suggest a warning if default org is not an absolute path).

Allow user specified logging interface

yearn's log config should take a string ( legacy logger minus the color to remove dependency on chalk ) or an object of the form (similar to console) :

{
    log: function( msg ){},
    info: function( msg ){},
    warn: function( msg ){},
    error: function( msg ){},
}

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.