metamagical-interface/lib/stability.js

An interface for attaching metadata to JavaScript objects.

'use strict';

var _moduleStability, _fromIdentifier, _index, _deprecated, _experimental, _stable, _locked;

//----------------------------------------------------------------------
//
// This source file is part of the Meta:Magical project.
//
// See LICENCE for licence information.
// See CONTRIBUTORS for the list of contributors to the project.
//
//----------------------------------------------------------------------

// -- DEPENDENCIES -----------------------------------------------------
var Refinable = require('refinable');

// -- IMPLEMENTATION ---------------------------------------------------

/*~
 * Handles describing and normalising stability identifiers.
 *
 * ---------------------------------------------------------------------
 * name        : module stability
 * module      : metamagical-interface/lib/stability
 * copyright   : (c) 2016 Quildreen Motta
 * licence     : MIT
 * repository  : https://github.com/origamitower/metamagical
 *
 * category    : Metadata
 * portability : portable
 * platforms:
 *   - ECMAScript 5
 *   - ECMAScript 3, with es5-shim
 *
 * maintainers:
 *   - Quildreen Motta <queen@robotlolita.me>
 */
module.exports = (_moduleStability = Refinable.refine({
  /*~
   * Converts a textual identifier of stability to a structured
   * representation of the stability.
   *
   * -------------------------------------------------------------------
   * category  : Converting to other types
   * stability : stable
   *
   * signature: .fromIdentifier(id)
   * type: |
   *   Stability.(String) => StabilityEntry
   */

  fromIdentifier: (_fromIdentifier = function fromIdentifier(id) {
    if (this.index.hasOwnProperty(id)) {
      return this.index[id];
    } else {
      throw new Error('No stability with id "' + id + '"');
    }
  }, _fromIdentifier[Symbol.for('@@meta:magical')] = {
    'name': 'fromIdentifier',
    'category': 'Converting to other types',
    'stability': 'stable',
    'signature': '.fromIdentifier(id)',
    'type': 'Stability.(String) => StabilityEntry\n \n',
    'documentation': 'Converts a textual identifier of stability to a structured\nrepresentation of the stability.'
  }, _fromIdentifier),


  /*~
   * An index of valid stability identifiers.
   *
   * ---
   * stability : stable
   * category  : Data
   */
  index: (_index = {
    /*~
     * ---
     * stability : stable
     * category  : Data
     */
    deprecated: (_deprecated = Refinable.refine({
      index: 0,
      name: 'Deprecated',
      description: '\nThis feature is known to be problematic, and will either be entirely\nremoved from the system, or completely redesigned. You should not rely\non it.'
    }), _deprecated[Symbol.for('@@meta:magical')] = {
      'name': 'deprecated',
      'documentation': '---\nstability : stable\ncategory  : Data\n     '
    }, _deprecated),

    /*~
     * ---
     * stability : stable
     * category  : Data
     */
    experimental: (_experimental = Refinable.refine({
      index: 1,
      name: 'Experimental',
      description: '\nThis feature is experimental and likely to change (or be removed) in the\nfuture.'
    }), _experimental[Symbol.for('@@meta:magical')] = {
      'name': 'experimental',
      'documentation': '---\nstability : stable\ncategory  : Data\n     '
    }, _experimental),

    /*~
     * ---
     * stability : stable
     * category  : Data
     */
    stable: (_stable = Refinable.refine({
      index: 2,
      name: 'Stable',
      description: '\nThis feature is stable, and its API is unlikely to change (unless deemed\nnecessary for security or other important reasons). You should expect\nbackwards compatibility with the system, and a well-defined and automated\n(if possible) migration path if it changes.'
    }), _stable[Symbol.for('@@meta:magical')] = {
      'name': 'stable',
      'documentation': '---\nstability : stable\ncategory  : Data\n     '
    }, _stable),

    /*~
     * ---
     * stability : stable
     * category  : Data
     */
    locked: (_locked = Refinable.refine({
      index: 3,
      name: 'Locked',
      description: '\nThis API will not change, however security and other bug fixes will still\nbe applied.'
    }), _locked[Symbol.for('@@meta:magical')] = {
      'name': 'locked',
      'documentation': '---\nstability : stable\ncategory  : Data\n     '
    }, _locked)
  }, _index[Symbol.for('@@meta:magical')] = {
    'name': 'index',
    'stability': 'stable',
    'category': 'Data',
    'documentation': 'An index of valid stability identifiers.'
  }, _index)
}), _moduleStability[Symbol.for('@@meta:magical')] = {
  'name': 'module stability',
  'module': 'metamagical-interface/lib/stability',
  'copyright': '(c) 2016 Quildreen Motta',
  'licence': 'MIT',
  'repository': 'https://github.com/origamitower/metamagical',
  'category': 'Metadata',
  'portability': 'portable',
  'platforms': ['ECMAScript 5', 'ECMAScript 3, with es5-shim'],
  'maintainers': ['Quildreen Motta <queen@robotlolita.me>'],
  'documentation': 'Handles describing and normalising stability identifiers.'
}, _moduleStability);