#################
API Documentation
#################


MP
==
The MP object is the central object that programmers will generally direct
all of their requests through. It is almost never instantiated directly,
but instead through the connect method.

.. class:: MP(options)

   :param object options: An object that contains all of the necessary
      initialization information for the MP object.

   .. attribute:: client

      The SOAP client object

   .. attribute:: ext

      An instance of :class:`Extensions` that allows for easily calling
      extensions written for MPJS. For example::

         mp.ext.doSomething();

   .. attribute:: schema

      An instance of :class:`Schema`, which you shouldn't need to interact
      with. Ever.

   .. function:: connect(options)

      :param object options: An object describing how to connect to MP
      :returns: Promise

   .. function:: prototype.sp(name)

      Instantiates and returns a :class:`StoredProcedure` object of the given
      name.

      :param string name: The name of the stored procedure
      :returns: :class:`StoredProcedure` object

   .. function:: prototype.fn(name)

      Returns a :class:`APIFunction` object of the given name. Note that if
      the requested function name is not defined by the WSDL, an error will
      be thrown.

      :param string name: The name of the function to fetch
      :returns: :class:`APIFunction` object

   .. function:: prototype.table(name)

      Fetches a table, as defined by the MP object's :class:`Schema`.

      :param string name: The name of the table to fetch
      :returns: :class:`Table` object

   .. function:: prototype.save(record, [userId])

      Save either a single record or an array of records back to MP. If the
      record is new (does not have a primary key value), then ``AddRecord``
      is called, otherwise ``UpdateRecord`` is used.

      :param mixed record: Either a :class:`Record` object or an array of
         :class:`Record` objects.
      :returns: Promise

   .. function:: prototype.query(table)

      Creates a :class:`Query` object for the given table and returns it.
      
      :param mixed table: Either a string of a valid table name or a table
         object, as returned by :func:`prototype.table`.
      :returns: :class:`Query` object.

   .. function:: prototype.describeFunctions()

      Lists the SOAP API functions described by API.

      :returns: Array of objects


StoredProcedure
===============
Coordinates executing and returning results from stored procedures. These
objects should be created via the main :class:`MP` object by calling
:func:`MP.prototype.sp() <prototype.sp>`.

.. class:: StoredProcedure(mp, name)

   :param MP mp: An MP object
   :param string name: The name of the stored procedure

   .. attribute:: mp

      The :class:`MP` object that this stored procedure belongs to.

   .. attribute:: name

      The stored procedure's name.

   .. function:: prototype.getName()

      :returns: A string representing the name of the stored procedure.

   .. function:: prototype.call(data, [userId])

      Execute the stored procedure and return a promise that, when resolved,
      contains the resulting datasets, if any.

      :param mixed data: Either an object to pass (indirectly) as the
         request string or an array of objects to pass as request strings.
         If the latter, executes the stored procedure for each object.
      :param int userId: The user ID the stored procedure should be executed
         as. Defaults to 1.
      :returns: Promise

   .. function:: prototype.createFunctionCall(data, [userId])

      Creates a function call referencing ``ExecuteStoredProcedure`` and 
      sets the request string as provided by data.

      :param object data: An object that will be rendered into the request
         string
      :returns: :class:`APIFunctionCall` object


APIFunction
===========
Facilitates calling SOAP functions. These objects should always be created
by the MPJS library when a connection is initiated. You should not have to
ever create them yourself. Instead, retrieve them by calling
:func:`MP.prototype.fn() <prototype.fn>`.

.. class:: APIFunction(mp, name, definition)

   :param MP mp: The ``MP`` object

   :param string name: The name of the function

   :param object definition: The definition (input and output) of what the
      SOAP function expects / returns

   .. attribute:: mp

   .. attribute:: name

   .. attribute:: definition

   .. attribute:: args

      An instance of :class:`APIFunctionArguments`, which is used for
      validating, encoding, and providing defaults for arguments passed to
      SOAP function calls

   .. function:: prototype.call(data, [userId])

      Calls the SOAP function with the parameters specified, returning a
      promise that resolves with an :class:`APIFunctionResponse` upon
      completion.

      :param mixed data: Either an object providing arguments for the SOAP
         function or an array of objects. If the latter, the SOAP function
         will be executed once for each item in the array
      :param int userId: The user ID to execute the function as. Defaults to
         1
      :returns: Promise

   .. function:: prototype.createFunctionCall(data, [userId])

      Creates and returns an :class:`APIFunctionCall` object. This method is
      called by the ``call()`` method.

      :param object data: An object providing arguments for the SOAP
         function
      :param int userId: The user ID to execute the function as. Defaults to
         1
      :returns: :class:`APIFunctionCall` object


APIFunctionCall
===============
Basically an interim object that holds an :class:`APIFunction` and the
arguments that it should be called with.

.. class:: APIFunctionCall(fn, values)
   
   :param APIFunction fn: The function that's being called
   :param object values: The values / arguments the function should be
      called with

   .. attribute:: fn

   .. attribute:: values

   .. function:: prototype.call()

      This is the method that performs the actual call to the SOAP API. It
      returns a promise that is resolved with whatever is returned by the
      resulting :class:`APIFunctionResponse`'s ``getData()``.

      :returns: Promise


APIFunctionResponse
===================
Contains the response from a SOAP function. Helps to facilitate delivery of
that content, providing a seemingly more standard interface to the output
of the raw function. **NOTE: This class is not directly exposed to the public
API**.

.. class:: APIFunctionResponse(fnCall, rawResponse)

   :param APIFunctionCall fnCall: The function call that resulted in the
      response in question
   :param object rawResponse: An object containing the raw response. Well,
      if by raw we mean the response as parsed by the "soap" library

   .. attribute:: fnCall

   .. attribute:: rawResponse

   .. function:: prototype.getData()

      Checks the type of the response. If an "<anyXML>" type result, returns
      an instance of :class:`DataResolver`; otherwise, returns the raw
      response (mostly).

      :returns: Mixed


APIFunctionArguments
====================
**This class is really not a public part of the API**. Just know that it exists
and does magical things. :)

.. class:: APIFunctionArguments(fn, definition)


Table
=====
Stores information about a Ministry Platform table, such as columns, and
constraints. Can be used to create :class:`Record` objects, which reference
the parent table.

In the future, the ``Table`` object will likely play a greater role in
database querying.

.. class:: Table(name, displayName, singularName, pageId)

   :param string name: The actual database table name
   :param string displayName: The "pretty" name used to represent the table in
      the Ministry Platform software
   :param string singularName: The "singular" version of the table name. For
      example, the "Contacts" table has a singular name of "Contact"
   :param int pageId: The Ministry Platform Page_ID for the table

   .. attribute:: columns

      An array of :class:`Column` objects that make up the basic structure of
      the table

   .. attribute:: c

      An object mapping column names to :class:`Column` objects

   .. attribute:: constraints

      An array of :class:`Constraint` objects

   .. function:: prototype.column(name)

      Fetch a :class:`Column` object from table by name

      :param string name: Name of column
      :returns: :class:`Column` object

   .. function:: prototype.getColumnNames()

      :returns: Array of column names

   .. function:: prototype.getPrimaryKey()

      Gets the primary key :class:`Column` object. Throws an error if table
      has no primary key.

      :returns: :class:`Column` object

   .. function:: prototype.record([data])

      Creates a new :class:`Record` object based on the current table

      :param object data: Data to intialize the record object with
      :returns: :class:`Record` object


Record
======
Provides an interface for interacting with table-level data from Ministry
Platform. ``Record`` objects are used to save data to Ministry Platform via
the :func:`MP.prototype.save() <prototype.save>` method. They are almost
always created by calling the
:func:`Table.prototype.record() <prototype.record>` method or via the
:class:`Query` object results parsing. In other words, you should never have
to instantiate a ``Record`` manually.

.. class:: Record(table)

   :param Table table: The table the record belongs to

   .. attribute:: table

   .. attribute:: data

      The raw data that has been stored for the record. No touchy!

   .. function:: prototype.getPrimaryKey()

      Return the value of the record's primary key column. If the record
      belongs to a table that does not have a primary key, an error will be
      thrown.

      :returns: Integer

   .. function:: prototype.setPrimaryKey(value)

      Sets the record's primary key column to the supplied value. If the
      record belongs to a table that does not have a primary key, an error
      will be thrown.

      :param int value: Primary key to set

   .. function:: prototype.isNew()

      Whether or not the record has been saved to the database. This is
      determined by checking if the record's primary key column has been set
      or not.

      :returns: Boolean

   .. function:: prototype.toObject(skipDecode)

      Convert the record to a standard JavaScript object. If ``skipDecode`` is
      truthy, the values are not decoded to their proper JavaScript type
      (normally, primary key will return as an int instead of a string).

      :param boolean skipDecode: Whether or not values should be decoded
      :returns: Object

   .. function:: prototype.toJSON()

      Returns JSON-compatible representation of the record. This method
      simply returns the result of ``toObject()``.

      :returns: Object

   .. function:: prototype.toRequestData()

      Returns a :class:`RequestData` representation of this record.

      :returns: :class:`RequestData` object

   .. function:: prototype.toString()

      Returns stringified version of ``toRequestData()``.

      :returns: String

   .. function:: prototype.update(data)

      For each key in data, set column to corresponding value.

      Example::

         record.update({
            First_Name: 'Tim',
            Last_Name: 'Radke'
         });

      :param object data: Object to set data with
      :returns: Self

   .. function:: fromArray(data)

      Shorthand for::

         new Record(table).update(data);

      :param object data: The data to send to ``update()``
      :returns: :class:`Record` object


Column
======
Tables are made up of columns, so it makes sense that we ought to have a
``Column`` object. And so we do. :)

.. class:: Column(table, name, args)

   .. attribute:: table

   .. attribute:: name

   .. attribute:: type

      The type encoder / decoder for this column.

   .. attribute:: defaultValue

      What the column should default to if no value is provided.

   .. attribute:: nullable

      Whether or not a ``null`` value is acceptable

   .. attribute:: primaryKey

      A boolean that indicates whether this column is the table's primary key

   .. data:: not

      An object that contains a bunch of functions for performing queries
      with the column. These functions are not part of the prototype due to
      the unfortunate nature of nesting an object in a prototype (its child
      functions lose access to the correct "this").

      These methods are used like so::

         var Contacts = mp.table('Contacts')
           , results = mp.query(Contacts).filter(Contacts.not.eq(4)).all();

      .. function:: eq(v)

         Return a :class:`Filter` where ``column <> v``.

         :param mixed v: The value to check equality for
         :returns: :class:`Filter` object

      .. function:: gt(v)

      .. function:: lt(v)

      .. function:: ge(v)

      .. function:: le(v)

      .. function:: like(v)

   .. function:: prototype.getDefault()

      Return an appropriate default for the column.

      :returns: Mixed

   .. function:: prototype.eq(v)

      Return a :class:`Filter` where ``column == v``.

      :param mixed v: The value to check equality for
      :returns: :class:`Filter` object

   .. function:: prototype.gt(v)

   .. function:: prototype.lt(v)

   .. function:: prototype.ge(v)

   .. function:: prototype.le(v)

   .. function:: prototype.like(v)

   .. function:: prototype.asc()

      Return an :class:`OrderBy` with the column in ASC direction.

      :returns: :class:`OrderBy` object

   .. function:: prototype.desc()

      Returns an :class:`OrderBy` with the column in DESC direction.

      :returns: :class:`OrderBy` object


Query
=====
``Query`` objects allow us to build complex Ministry Platform queries on
arbitrary tables. They have a handful of query-modifying methods, such as
``limit()``, ``filter()``, and ``orderBy()`` that actually return new
``Query`` objects with the changes requested. So to be very clear, if you
do the following::

   var query = mp.query('Contacts')
     , query2 = query.limit(5);

... then::

   query === query2;   // false !!

Also it should be noted that you shouldn't have to instantiate these objects
yourself. Instead, grab a new ``Query`` object via your application's main
``MP`` object::

   var query = mp.query('Contacts');

   // or create a query from a Table:

   var query = mp.query(mp.table('Contacts'));

.. class:: Query(mp, table, [opts])

   :param MP mp: The main ``MP`` instance
   :param Table table: The table the query should be based off of
   :param object opts: Query options object

   .. function:: prototype.filter(filter)

      Creates a new query with either provided filter/filters.

      :param mixed filter: Either a :class:`Filter` object or an array of
         :class:`Filter` objects
      :returns: A new :class:`Query` object

   .. function:: prototype.filterBy(filters)

      For each key/value in the ``filters`` object, creates a new filter and
      finally returns a new ``Query`` object with these filters appended.

      Here's what goes on behind the scenes::

         var result = [];

         for (var i in filters) {
           if (filters.hasOwnProperty(i)) {
             result.push(this.table.column(i).eq(filters[i]));
           }
         }

         return modQuery(this, {filters: result});

      :param object filters: The object to make filters from
      :returns: A new :class:`Query` object

   .. function:: prototype.orderBy(orderBy)

      Creates a new query with the provided orderBy object/objects.

      :param mixed orderBy: Either a :class:`OrderBy` object or an array of
         :class:`OrderBy` objects
      :returns: A new :class:`Query` object

   .. function:: prototype.limit(n)

      Creates a new query with the provided row limit.

      :param int n: The number of rows the query should be limited to
      :returns: A new :class:`Query` object

   .. function:: prototype.offset(n)

      Creates a new query with the provided offset.

      :param int n: The offset the query should start from
      :returns: A new :class:`Query` object

   .. function:: prototype.first()

      Creates a new query with ``limit(1)``, executes it and returns a
      promise. The promise is resolved with either a single :class:`Record`
      or, in the event that no results were found, ``null``.

      :returns: Promise

   .. function:: prototype.all()

      Executes the query and returns a promise. The promise is resolved with
      an array of :class:`Record` objects. The array also has a special
      ``first()`` method, which returns the first item in the array or null,
      if the array is empty.

      :returns: Promise


RequestData
===========
**This is another helper class that is generally not publicly visible. As such,
I'm not going to document it at this time.**

.. class:: RequestData(data)


Extensions
==========
.. class:: Extensions(mp, extensions)