<commit_before>==================
carbond.Collection
==================

.. js:class:: Collection()
    :hidden:

Carbond ``Collection``\ s provide a high-level abstraction for defining ``Endpoint``\ s that behave like a collection of 
resources. When you define a ``Collection`` you define the following methods:

- ``insert(obj, reqCtx)``
- ``find(query, options, reqCtx)``
- ``update(query, obj, options, reqCtx)``
- ``remove(query, reqCtx)``
- ``findObject(id, reqCtx)``
- ``updateObject(id, reqCtx)``
- ``removeObject(id, reqCtx)``

Which results in the following tree of ``Endpoints`` and ``Operations``:

- ``/<collection>``

  - ``GET`` which maps to ``find``
  - ``POST`` which maps to ``insert``
  - ``PUT`` which maps to ``update``
  - ``DELETE`` which maps to ``remove``
    
- ``/<collection>/:id``

  -  ``GET`` which maps to ``findObject``
  -  ``PUT`` which maps to ``updateObject``
  -  ``DELETE`` which maps to ``removeObject``


Configuration
=============

..  code-block:: javascript

    {
      _type: carbon.carbond.Collection, // extends Endpoint
      
      [parameters: {
        <name> : <OperationParameter>
      }]  
      
      [insert: <function>],
      [find: <function>],
      [update: <function>],
      [remove: <function>],
      [findObject: <function>],
      [updateObject: <function>],
      [removeObject: <function>]
      
      [endpoints: { 
        <path>: <Endpoint>
        ...
      }]
    }

Properties
==========

- ``path`` (read-only): The path to which this ``Collection`` is bound. The path can contain variable patterns (e.g. ``'orgs/:id/members'``). The ``path`` property is not configured directly on ``Collection`` objects but are specified as lvals in enclosing definitions of endpoints such as in an ``ObjectServer`` or a parent ``Endpoint`` object. When retrieved the value of this property will be the absolute path of the endpoint from ``/``. 

- ``parent`` (read-only): The parent ``Endpoint`` of this ``Collection``.

- ``objectserver`` (read-only): The ``ObjectServer`` to which this endpoint belongs.

- ``parameters``: A mapping of parameter names to ``OperationParameter`` objects. Parameters defined for an ``Endpoint`` are inherited by all operations of this ``Endpoint`` as well as by all child ``Endpoint``\ s of this ``Endpoint``.

- ``endpoints``: A set of child ``Endpoint`` definitions. This is an object whose keys are path strings and values are instances of ``Endpoint``. Each path key will be interpreted as relative to this ``Endpoint``\ s ``path`` property. 

Methods
=======

_TBD_

RESTFul interface
=================

- ``/<collection>``
  
  - ``GET`` which maps to ``find``
  - ``POST`` which maps to ``insert``
  - ``PUT`` which maps to ``update``
  - ``DELETE`` which maps to ``remove``
    
- ``/<collection>/:id``
  
  -  ``GET`` which maps to ``findObject``
  -  ``PUT`` which maps to ``updateObject``
  -  ``DELETE`` which maps to ``removeObject``

Examples (synchronous)<commit_msg>Add example changes for domain usage<commit_after>.. js:class:: Collection()
    :heading:

==================
carbond.Collection
==================

Carbond :class:`Collection`\ s provide a high-level abstraction for defining :class:`Endpoint`\ s that behave like a collection of 
resources. When you define a :class:`Collection` you define the following methods:

- ``insert(obj, reqCtx)``
- ``find(query, options, reqCtx)``
- ``update(query, obj, options, reqCtx)``
- ``remove(query, reqCtx)``
- ``findObject(id, reqCtx)``
- ``updateObject(id, reqCtx)``
- ``removeObject(id, reqCtx)``

Which results in the following tree of :class:`Endpoints` and :class:`Operations`:

- ``/<collection>``

  - ``GET`` which maps to ``find``
  - ``POST`` which maps to ``insert``
  - ``PUT`` which maps to ``update``
  - ``DELETE`` which maps to ``remove``
    
- ``/<collection>/:id``

  -  ``GET`` which maps to ``findObject``
  -  ``PUT`` which maps to ``updateObject``
  -  ``DELETE`` which maps to ``removeObject``


Configuration
=============

..  code-block:: javascript

    {
      _type: carbon.carbond.Collection, // extends Endpoint
      
      [parameters: {
        <name> : <OperationParameter>
      }]  
      
      [insert: <function>],
      [find: <function>],
      [update: <function>],
      [remove: <function>],
      [findObject: <function>],
      [updateObject: <function>],
      [removeObject: <function>]
      
      [endpoints: { 
        <path>: <Endpoint>
        ...
      }]
    }

Properties
==========

.. js:class:: Collection()
    :noindex:
    :hidden:

    .. js:attribute:: path

        (read-only): The path to which this :class:`Collection` is bound. The path can contain variable patterns (e.g. ``'orgs/:id/members'``). The :attr:`path` property is not configured directly on :class:`Collection` objects but are specified as lvals in enclosing definitions of endpoints such as in an :class:`ObjectServer` or a parent :class:`Endpoint` object. When retrieved the value of this property will be the absolute path of the endpoint from ``/``.

    .. js:attribute:: parent

        (read-only): The parent :class:`Endpoint` of this :class:`Collection`.

    .. js:attribute:: objectserver

        (read-only): The :class:`ObjectServer` to which this endpoint belongs.

    .. js:attribute:: parameters

        A mapping of parameter names to :class:`OperationParameter` objects. Parameters defined for an :class:`Endpoint` are inherited by all operations of this :class:`Endpoint` as well as by all child :class:`Endpoint`\ s of this :class:`Endpoint`.

    .. js:attribute:: endpoints

        A set of child :class:`Endpoint` definitions. This is an object whose keys are path strings and values are instances of :class:`Endpoint`. Each path key will be interpreted as relative to this :class:`Endpoint`\ s :attr:`path` property.

Methods
=======

_TBD_

RESTFul interface
=================

- ``/<collection>``
  
  - ``GET`` which maps to ``find``
  - ``POST`` which maps to ``insert``
  - ``PUT`` which maps to ``update``
  - ``DELETE`` which maps to ``remove``
    
- ``/<collection>/:id``
  
  -  ``GET`` which maps to ``findObject``
  -  ``PUT`` which maps to ``updateObject``
  -  ``DELETE`` which maps to ``removeObject``

Examples (synchronous)
{'fraction_non_alphanumeric': 0.17989165073295094, 'fraction_numerical': 0.0, 'mean_word_length': 3.5255948089401588, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5605760', 'n_tokens_mistral': 1839, 'n_tokens_neox': 1789, 'n_words': 649}