Awesome

stamp-utils 

Essential Stamp Utilities

Composition > Class Inheritance

Stamp utils is a collection of utilities for the creation of stamps: Composable factory functions.

Stamps contain a method called .compose() which has properties attached to it that form a stamp descriptor. A stamp descriptor is a metadata object that tells the stamp how to create object instances. The stamp descriptor is like a recipe that tells any stamp-compatible function everything it needs to know to compose the stamp with other composables.

The compose method takes any number of composables and combines them with the current stamp to produce a new stamp with the properties and behaviors of all the combined stamps.

Status

Very new, but should be usable and API stable. Try it. Kick the tires. If you find any problems, please open an issue or pull request.

What's a composable?

A composable is any factory function or Plain Old JavaScript Object (POJO) with a stamp descriptor.

Reading Function Signatures

This documentation uses the rtype specification. (param: Type) => ReturnType

What's included here?

compose()

import compose from 'stamp-utils/compose';

Take any number of stamps or descriptors (or both), and return a new stamp with the composed behaviors and properties.

compose(...composables: [...Composable]) => Stamp

Example: Create a music player that supports several music sources:

// Create the MusicPlayer factory
const MusicPlayer = compose(playerUI, soundCloud, youtube, spotify);

// Create a MusicPlayer instance
const myPlayer = MusicPlayer();

isComposable()

import {isComposable} from 'stamp-utils';

Take an any object and return true if the object is a composable, e.g. POJO descriptor or stamp. Return false otherwise.

(obj: Any) => Boolean

isDescriptor()

import {isDescriptor} from 'stamp-utils';

Take an any object and return true if the object is a stamp descriptor. Return false otherwise.

(obj: Any) => Boolean

isStamp()

import {isStamp} from 'stamp-utils';

Take an any object and return true if the object is a stamp. Return false otherwise.

(obj: Any) => Boolean

Example:

import {isStamp} from 'stamp-utils';

const foo = compose();
const isFooAStamp = isStamp(foo); // true

const bar = {};
const isBarAStamp = isStamp(bar); // false

init()

import {init} from 'stamp-utils';

Easily add initializer functions to your stamps. Take a function (or many functions) and return a stamp that runs the function when an instance is created.

(...functions: Function|[...Function]) => Stamp

Example: Log to the console every time a new instance is created.

const InstanceLogger = init(({ name }) => {
  console.log(`Created new instance: ${ name }`);
});

const george = InstanceLogger({ name: 'George' }); // Created new instance: George

assignToInstance()

import {assignToInstance} from 'stamp-utils';

Assign the stamp options properties to the instantiated object.

(...keys?: String|[...String]) => Stamp

Example: Assign all properties:

const Uri = assignToInstance();

const uri = Uri({host: 'example.com', port: 80, protocol: 'http://'});
console.log(uri); // { host: 'example.com', port: 80, protocol: 'http://' }

Example: Assign only two properties:

const Uri = assignToInstance('host', 'port');

const uri = Uri({host: 'example.com', port: 80, protocol: 'http://'});
console.log(uri); // { host: 'example.com', port: 80 }

Check out Fun with Stamps for example of use case scenario.

namespaced()

import {namespaced} from 'stamp-utils';

Takes the stamp's options, passes them by name to the given "child" stamps, and assigns the obtained results back to the original instance.

(options: {String: Stamp}) => Stamp

Example: Create uri property from the Uri stamp:

const Uri = assignToInstance('host', 'port');
const Connection = namespaced({uri: Uri}); // create 'uri' property from 'Uri' stamp

const connection = Connection({uri: {
  host: 'example.com', port: 80, protocol: 'http://' // pass this to 'Uri' stamp
}});
console.log(connection); // { uri: { host: 'example.com', port: 80 } }

methods()

import {methods} from 'stamp-utils';

Easily add methods to your stamps. Take an object (or many object) and return a stamp that adds those methods to a prototype when instance is created.

(...methods: [...Object]) => Stamp

Example: Add stringify method to instance

const Stringifiable = methods({ stringify() {
  return JSON.stringify(this);
}});

const Named = compose(Stringifiable, assignToInstance('name'));
const george = Named({ name: 'George' });
console.log(george.stringify()); // '{"name":"George"}'