Standardised metadata properties in JavaScript libraries
JavaScript
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
test
README.md

README.md

#A proposal: Standardised metadata properties in JavaScript libraries

##What?

A standard way for developers (be they regular, plugin or library devs) to access things like the version and name of a JavaScript library.

##Example

Yes, it's simplified. Focus on the metadata bits and pretend the rest is pure awesomeness.

var jGrouseLib = (function(G){

  // Metadata
  G.type = 'library';
  G.name = 'Grouse Library';
  G.major_version = 1;
  G.minor_version = 2;
  G.patch_version = 3;
  G.special_version = 'b4';
  G.version = '1.2.3b4';
  G.globals = ['jGrouseLib', 'G'];

  // The rest of the library
  // ...

  return window.G = G;
})(jGrouseLib || {});

##Why?

  • Use cases:
  • plugin developers - checking dependencies
  • library developers - check if another library (or another copy of your own) is using a global you want to
  • regular developers - finding what library is behind $, _ etc.
  • CommonJS is awesome
  • SemVer is awesome

##Why not?

###Bloat Minimal - above example is 167B extra

###Can't split version into separate bits See code samples

###Some libraries (Prototype) don't conform to SemVer They should change, or we should relax it a bit (strip invalid chars etc.)

###Library X uses some of those properties for other things Fair enough, see .meta namespacing discussion.

##Details

###Properties:

  • type, required, string
    • Must be 'library'
  • name, required, string
    • The name of the library
  • major_version, required, number
  • minor_version, required, number
  • patch_version, required, number
  • special_version, required, string
  • version, required, string
    • major_version + '.' + minor_version + '.' + patch_version + special_version
  • globals, optional, array of strings
    • Names of the variables you're sticking in the global namespace (i.e. window)

##How?

  • [backwards compatibilitly]
  • [version splitting & concatting functions]

##References

  1. Common libraries: http://code.google.com/apis/libraries/
  2. CommonJS packages metadata http://wiki.commonjs.org/wiki/Packages/1.1
  3. Semantic Versioning: http://semver.org/
  4. Cross-browser Object.watch(): http://gist.github.com/384583