yapm/README.md

npm wrapper allowing to use package.yaml instead of package.json

**WARNING: this is pre-release, wait a few days**

There is a couple of quite annoying bugs to be fixed.

## What is it?

This is npm wrapper allowing to use `package.yaml` instead of `package.json`. It converts `package.yaml` to `package.json` and back on the fly.

## How?

It performs active MitM attack (so to speak) between *node* and *npm*.

Technically speaking, it monkey-patches standard library, so *npm* **thinks** it is working with `package.json`, and *node* **thinks** that *npm* is working with `package.yaml`. And this module act as a middleman and converts this thing back and forth on the fly. Pretty nice little hack, huh?

1. If *npm* asks filesystem to READ a file named `package.json` **AND** if there is no such file **AND** there is a file named `package.yaml`, we compile it and return resulting json to *npm* pretending that we just read what we was asked for.

2. If *npm* asks filesystem to WRITE a file named `package.json` **AND** if this file doesn't exist already, we write it to a file named `package.yaml` instead. This option is designed specifically for *npm init* command.

## Why not just use JSON?

JSON is created to easily parse it in javascript with well-known ev**i**l function. Sad but true. It is human-readable, just like XML. But it isn't human-writable so to speak, just like XML.

1. JSON have no comments, you can't comment out why did you put some dependency, but not the other.
2. JSON have no trailing comma. So you can't easily remove an item, add an item or interchange two arbitrary lines in a list.
3. JSON require ugly enquoting both keys and values in object. Javascript require enquoting values only, and YAML doesn't require quotes in most cases.

Guys, seriously, JSON is designed to be written by computers, not humans. Humans could read it easily, but maintaining JSON is a pain. Don't do it.

## Why YAML?

YAML is widely used for configuration files in Ruby on Rails. I remind you that most cool node.js things were inspired by RoR world, including express (sinatra), coffee-script (ruby), and node.js itself (rails).

When I started thinking about this in year 2012, I didn't know what it is. I was thinking about other things...

YAML is just as safe as JSON:

1. it can't include arbitrary files (there is no "include" or something in spec)
2. it can't execute arbitrary code (you can extend it of course, but by default it won't do that)
3. it can't produce arbitrary data-types (at least when using SAFE\_SCHEMA option for [js-yaml](https://github.com/nodeca/js-yaml) parser).


PS: note that `js-yaml.load()` with default (unsafe) parser is [just as safe](http://www.kalzumeus.com/2013/01/31/what-the-rails-security-issue-means-for-your-startup/) as `var x = eval(JSON)`. Choose your parser carefully. ;)

## package.yaml in npm registry

`package.json` will be created before packing/publishing a package to the npm registry. It is technically possible to avoid doing it, but to ensure interoperability we must compile this file.

By the way, the same thing goes for coffee-script guys. There's nothing wrong with using .coffee files in development, but they should be compiled before publishing.

Git repositories on the other hand can be keep clear of all that autogenerated stuff if you update your npm package often enough.

## Discussions in node.js mailing lists

1. "comments in package.json" ([1](https://groups.google.com/forum/?fromgroups#!topic/nodejs/NmL7jdeuw0M), [2](http://markmail.org/message/prat4277mnz56mgt))