API Quick Reference

Implied Types

Note that the Map type referenced further below refers to the native ES2015 Map type. ListOptions, ComponentType, and ComponentInstance are defined further below.

type Key: String
type KeyValueMap<A>: { [key: Key]: A, ... }
type Stream: most.Stream
type Sources: KeyValueMap<any>
type Sinks: KeyValueMap<Stream>
type Component: (Sources) => Sinks
type Identifier: String|Number
type ComponentTypeIdentifier: Identifier
type InstanceIdentifier: Identifier
type ComponentDefinition: Component|ComponentType
type Input: Sources|any

Collection API

// # CONSTRUCTION

// New collection, optionally with a default component type, or specify further options
Collection: () => ICollection
Collection: (fn: ComponentFunction) => ICollection
Collection: (type: ComponentTypeIdentifier, fn: ComponentFunction) => ICollection
Collection: (options: ComponentDefinition) => ICollection
Collection: (options: ListOptions) => ICollection

// # STATIC METHODS FOR MANAGING LIST STREAMS

// Check if a value is an ICollection instance
Collection.isCollection: (arg: any) => Boolean

// Merge the specified sink from each collection item into a single resultant stream
Collection.merge: (key: Key, list$: Stream<ICollection>) => Stream

// Merge each of the specified sinks in each collection item into a single unified sinks object
Collection.merge: ([key: Key, ...], list$: Stream<ICollection>) => Sinks

// Merge the streams from each of two or more sinks objects into a single unified sinks object
Collection.merge: (a: Sinks, b: Sinks, ... n: Sinks) => Sinks

// Similar behaviour to that of most.combineArray, with input streams taken by mapping the specified
// sink key from each component in the collection.
Collection.combineArray: (key: Key, list$: Stream<ICollection>) => Stream<Array<any>>
Collection.combineArray: (keys: Key[], list$: Stream<ICollection>) => Stream<Array<KeyValueMap<any>>>

// As above, but emits a native `Map` instead of a plain object
Collection.combineObject: (key: Key, list$: Stream<ICollection>) => Stream<KeyValueMap<any>>
Collection.combineObject: (keys: Key[], list$: Stream<ICollection>) => Stream<KeyValueMap<KeyValueMap<any>>>

// Equality comparison
Collection.isEqual: (a: ICollection, b: ICollection) => Boolean
Collection.areItemsEqual: (a: ICollection, b: ICollection) => Boolean

// # COLLECTION INSTANCE TYPES AND METHODS

type ICollection: {
  // Most overloads for the `collection` function are aliases for the `define` method
  define: (fn: ComponentFunction) => ICollection
  define: (type: ComponentTypeIdentifier, fn: ComponentFunction) => ICollection
  define: (type: ComponentTypeIdentifier, options: ComponentDefinition) => ICollection
  define: (options: ComponentDefinition) => ICollection

  // Append an instance of either the default or a specified component type`
  add: (input?: Input) => ICollection
  add: (type: ComponentTypeIdentifier, input: Input) => ICollection
  addInstance: (type?: ComponentTypeIdentifier, instance: Sinks) => ICollection

  // Set a keyed instance of either the default or a specified component type
  set: (key: InstanceIdentifier, type?: ComponentTypeIdentifier, input: Input) => ICollection
  setAt: (index: Number, type?: ComponentTypeIdentifier, input: Input) => ICollection
  setInstance: (key: InstanceIdentifier, type?: ComponentTypeIdentifier, instance: Sinks) => ICollection
  setInstanceAt: (index: Number, type?: ComponentTypeIdentifier, instance: Sinks) => ICollection

  get: (key: InstanceIdentifier) => ComponentInstance
  getAt: (index: Number) => ComponentInstance

  // Remove a component by key or index
  remove: (key: InstanceIdentifier) => ICollection
  removeAt: (index: Number) => ICollection

  // Remove all items from the collection
  clear: () => ICollection

  // The number of elements in the list
  size: Number

  // Collection-specific versions of the same-named static methods
  merge: (key: Key) => Stream
  merge: (keys: Key[]) => Sinks
  combineArray: (key: Key) => Stream<Array<any>>
  combineArray: (keys: Key[]) => Stream<Array<KeyValueMap<any>>>
  combineObject: (key: Key) => Stream<KeyValueMap<any>>
  combineObject: (keys: Key[]) => Stream<KeyValueMap<KeyValueMap<any>>>
}

// A list can be initialized with predefined types and custom behaviour
type ListOptions: {
  sources?: Sources
  types?: [ComponentDefinition, ...]
}

// A component type can be defined with optional custom behaviour per type
type ComponentType: {
  sources?: Sources
  key: ComponentTypeIdentifier
  fn?: ComponentFunction
  instantiate?: (input: Input, type: TypeDefinition, list: ICollection) => Sinks
}

// The following values are retained for each active component instance in the collection:
type ComponentInstance: {
  key: InstanceIdentifier
  type: ComponentTypeIdentifier
  input: Input
  sinks: Sinks
}