Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
Update "What is stamp" section. See #90 for details.
  • Loading branch information
koresar committed Jun 4, 2015
1 parent e508c8e commit 0bfa98e
Showing 1 changed file with 17 additions and 3 deletions.
20 changes: 17 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,15 +73,29 @@ or by [downloading the latest release](https://github.com/ericelliott/stampit/re

## What is a Stamp?

A stamp is a composable factory function created by calling `stampit()`. When invoked the factory function creates and returns object instances assigning:
A stamp is a composable factory function. Stamps allow you to inherit easily from multiple ancestors by composing multiple source stamps. You can combine properties, methods, and initializers (with closures) from any number of stamps to produce a new stamp. Stamps are more flexible than traditional factory functions or classical multiple inheritance. Traditional factory functions can't be composed together to produce new factory functions. Class inheritance does not provide a standardized mechanism for class composition.

Stamp composition takes advantage of three different kinds of prototypal inheritance:

* Differential inheritance, aka delegation (e.g., JavaScript's [[Prototype]]),
* Mixins/cloning with optional deep merge, aka concatenative inheritance (e.g., JavaScript's `Object.assign()`),
* Functional / closure inheritance (for initialization or privacy/encapsulation)

When invoked the stamp factory function creates and returns object instances assigning:
```js
var myStamp = stampit().
methods({ doSomething: function(){} }). // methods each new object instance will have
refs({ myObj: myObjByRef }). // properties to be set by reference to object instances
init(function(context){ }). // add an init function to be called when an object instance is created
props({ foo: {bar: 'bam'} }); // properties to be cloned and assigned to object instances
init(function(context){ }). // init function(s) to be called when an object instance is created
props({ foo: {bar: 'bam'} }); // properties to be deeply merged to object instances
```

### How are Stamps Different from Classes?

* It's easy to combine multiple stamps to create a new stamp with all of the source stamp capabilities
* Stamps are factory functions, so they don't need to be invoked with `new` (which couples callers to the implementation of object instantiation)
* Stamps don't create parent-child class hierarchies. Class hierarchies create "is-a" relationships between classes. Stamp composition creates "has-a" or "uses-a" relationships, instead. For that reason, stamp inheritance is less brittle than class inheritance.

All of these stampit methods may be called multiple times to add more elements to the factory.

## What's the Point?
Expand Down

0 comments on commit 0bfa98e

Please sign in to comment.