stamp-specification

by stampit-org

stampit-org /stamp-specification

The Stamp Specification: Composables

429 Stars 14 Forks Last release: about 1 year ago (v.1.6.0) 249 Commits 16 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Stamp Specification v1.6

Gitter Greenkeeper Badge

Introduction

This specification exists in order to define a standard format for composable factory functions (called stamps), and ensure compatibility between different stamp implementations.

Status

The specification is currently used by the following officially supported implementations:

Reading Function Signatures

This document uses the Rtype specification for function signatures:

(param: Type) => ReturnType

Composable

interface Composable: Stamp|Descriptor

A composable is one of:

  • A stamp.
  • A POJO (Plain Old JavaScript Object) stamp descriptor.

Stamp

A stamp is a composable factory function that returns object instances based on its descriptor.

stamp(options?: Object, ...args?: [...Any]) => instance: object
const newObject = stamp();

Stamps have a method called

.compose()
:
Stamp.compose(...args?: [...Composable]) => Stamp

When called the

.compose()
method creates new stamp using the current stamp as a base, composed with a list of composables passed as arguments:
const combinedStamp = baseStamp.compose(composable1, composable2, composable3);

The

.compose()
method doubles as the stamp's descriptor. In other words, descriptor properties are attached to the stamp
.compose()
method, e.g.
stamp.compose.methods
.

Overriding
.compose()
method

It is possible to override the

.compose()
method of a stamp using
staticProperties
. Handy for debugging purposes.
import differentComposeImplementation from 'different-compose-implementation';
const composeOverriddenStamp = stamp.compose({
  staticProperties: {
    compose: differentComposeImplementation
  }
});  

Descriptor

Composable descriptor (or just descriptor) is a meta data object which contains the information necessary to create an object instance.

Standalone
compose()
pure function (optional)

(...args?: [...Composable]) => Stamp

Creates stamps. Take any number of stamps or descriptors. Return a new stamp that encapsulates combined behavior. If nothing is passed in, it returns an empty stamp.

Detached
compose()
method

The

.compose()
method of any stamp can be detached and used as a standalone
compose()
pure function.
const compose = thirdPartyStamp.compose;
const myStamp = compose(myComposable1, myComposable2);

Implementation details

Stamp

Stamp(options?: Object, ...args?: [...Any]) => Instance: Object

Creates object instances. Take an options object and return the resulting instance.

Stamp.compose(...args?: [...Composable]) => Stamp

Creates stamps.

A method exposed by all stamps, identical to

compose()
, except it prepends
this
to the stamp parameters. Stamp descriptor properties are attached to the
.compose
method, e.g.
stamp.compose.methods
.

The Stamp Descriptor

interface Descriptor {
  methods?: Object,
  properties?: Object,
  deepProperties?: Object,
  propertyDescriptors?: Object,
  staticProperties?: Object,
  staticDeepProperties?: Object,
  staticPropertyDescriptors?: Object,
  initializers?: [...Function],
  composers?: [...Function],
  configuration?: Object,
  deepConfiguration?: Object
}

The names and definitions of the fixed properties that form the stamp descriptor. The stamp descriptor properties are made available on each stamp as

stamp.compose.*
  • methods
    - A set of methods that will be added to the object's delegate prototype.
  • properties
    - A set of properties that will be added to new object instances by assignment.
  • deepProperties
    - A set of properties that will be added to new object instances by deep property merge.
  • propertyDescriptors
    - A set of object property descriptors used for fine-grained control over object property behaviors.
  • staticProperties
    - A set of static properties that will be copied by assignment to the stamp.
  • staticDeepProperties
    - A set of static properties that will be added to the stamp by deep property merge.
  • staticPropertyDescriptors
    - A set of object property descriptors to apply to the stamp.
  • initializers
    - An array of functions that will run in sequence while creating an object instance from a stamp. Stamp details and arguments get passed to initializers.
  • composers
    - An array of functions that will run in sequence while creating a new stamp from a list of composables. The resulting stamp and the composables get passed to composers.
  • configuration
    - A set of options made available to the stamp and its initializers during object instance creation. These will be copied by assignment.
  • deepConfiguration
    - A set of options made available to the stamp and its initializers during object instance creation. These will be deep merged.

Composing Descriptors

Descriptors are composed together to create new descriptors with the following rules:

  • methods
    are copied by assignment
  • properties
    are copied by assignment
  • deepProperties
    are deep merged
  • propertyDescriptors
    are copied by assignment
  • staticProperties
    are copied by assignment
  • staticDeepProperties
    are deep merged
  • staticPropertyDescriptors
    are copied by assignment
  • initializers
    are uniquely concatenated as in
    _.union()
    .
  • composers
    are uniquely concatenated as in
    _.union()
    .
  • configuration
    are copied by assignment
  • deepConfiguration
    are deep merged
Copying by assignment

The special property assignment algorithm shallow merges the following properties: * The regular string key properties

obj.foo = "bla"
* The
Symbol
key properties
obj[Symbol.for('foo')] = "bla"
* The JavaScript getters and setters
{ get foo() { return "bla"; }, set foo(val) { ... } }
Deep merging

Special deep merging algorithm should be used when merging descriptors.

Values: * Plain objects are deeply merged (or cloned if destination metadata property is not a plain object) * Arrays are concatenated using

Array.prototype.concat
which shallow copies elements to a new array instance * All other value types - Functions, Strings, non-plain objects, RegExp, etc. - are copied by reference * The last value type always overwrites the previous value type

Keys: * The

Symbol
object keys are treated as regular string keys * The JavaScript getters and setters are merged as if they are regular functions, i.e. copied by reference

Priority Rules

It is possible for properties to collide, between both stamps, and between different properties of the same stamp. This is often expected behavior, so it must not throw.

Same descriptor property, different stamps: Last in wins.

Different descriptor properties, one or more stamps:

  • Shallow properties override deep properties
  • Property Descriptors override everything

Stamp Arguments

It is recommended that stamps only take one argument: The stamp

options
argument. There are no reserved properties and no special meaning. However, using multiple arguments for a stamp could create conflicts where multiple stamps expect the same argument to mean different things. Using named parameters, it's possible for stamp creator to resolve conflicts with
options
namespacing. For example, if you want to compose a database connection stamp with a message queue stamp:
const db = dbStamp({
  host: 'localhost',
  port: 3000,
  onConnect() {
    console.log('Database connection established.');
  }
});

const queue = messageQueueStamp({ host: 'localhost', port: 5000, onComplete() { console.log('Message queue connection established.'); } });

If you tried to compose these directly, they would conflict with each other, but it's easy to namespace the options at compose time:

const DbQueue = compose({
  initializers: [({db, queue}, { instance }) => {
    instance.db = dbStamp({
      host: db.host,
      port: db.port,
      onConnect: db.onConnect
    });
    instance.queue = messageQueueStamp({
      host: queue.host,
      port: queue.port,
      onConnect: queue.onConnect
    });
  }]
});

myDBQueue = DbQueue({ db: { host: 'localhost', port: 3000, onConnect () { console.log('Database connection established.'); } }, queue: { host: 'localhost', port: 5000, onConnect () { console.log('Message queue connection established.'); } } });

Initializer Parameters

Initializers have the following signature:

(options: Object, { instance: Object, stamp: Stamp, args: Array }) => instance?: Object
  • options
    The
    options
    argument passed into the stamp, containing properties that may be used by initializers.
  • instance
    The object instance being produced by the stamp. If the initializer returns a value other than
    undefined
    , it replaces the instance.
  • stamp
    A reference to the stamp producing the instance.
  • args
    An array of the arguments passed into the stamp, including the
    options
    argument.

Note that if no

options
object is passed to the factory function, an empty object will be passed to initializers.

Composer Parameters

Composers have the following signature:

({ stamp: Stamp, composables: Composable[] }) => stamp?: Object
  • stamp
    The result of the composables composition.
  • composables
    The list of composables the
    stamp
    was just composed of.

Note that it's not recommended to return new stamps from a composer. Instead, it's better to mutate the passed

stamp
.

Similarities With Promises (aka Thenables)

  • Thenable ~ Composable.
  • .then
    ~
    .compose
    .
  • Promise ~ Stamp.
  • new Promise(function(resolve, reject))
    ~
    compose(...composables)

Contributing

To contribute, please refer to the Contributing guide.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.