Application
===========

|GitHub stars| |npm version| |Changelog|

.. code-block:: sh

   $ npm install @feathersjs/feathers --save

The core ``@feathersjs/feathers`` module provides the ability to initialize new Feathers application instances.
It works in Node, React Native and the browser (see the :doc:`./client` chapter for more information).
Each instance allows for registration and retrieval of :doc:`./hooks`, plugin configuration, and getting and setting configuration options.
An initialized Feathers application is referred to as the **app object**.

.. code:: js

   const feathers = require('@feathersjs/feathers');
   const app = feathers();

.use(path, service)
-------------------

:doc:`./services` on a given ``path``.

.. code:: js

   // Add a service.
   app.use('/messages', {
     get(id) {
       return Promise.resolve({
         id,
         text: `This is the ${id} message!`
       });
     }
   });

..

.. note::
   ``path`` can be ``/`` to register a service at the root level.

.. _api_application_servicepath:

.service(path)
--------------

:doc:`./services` for the given path.
Feathers internally creates a new object from each registered service.
This means that the object returned by ``app.service(path)`` will provide the same methods
and functionality as your original service object
but also functionality added by Feathers and its plugins like :doc:`./events` and :ref:`services_feathers-functionality`.
``path`` can be the service name with or without leading and trailing slashes.

.. code:: js

   const messageService = app.service('messages');
   messageService.get('test').then(message => console.log(message));
   app.use('/my/todos', {
     create(data) {
       return Promise.resolve(data);
     }
   });
   const todoService = app.service('my/todos');
   // todoService is an event emitter
   todoService.on('created', todo =>
     console.log('Created todo', todo)
   );

.hooks(hooks)
-------------

``app.hooks(hooks) -> app`` allows registration of application-level hooks. For more information see the :ref:`hooks_application-hooks`.

.publish([event, ] publisher)
-----------------------------

``app.publish([event, ] publisher) -> app`` registers a global event publisher. For more information see the :ref:`channels_publishing` chapter.

.. _api_application_configure-callback:

.configure(callback)
--------------------

``app.configure(callback) -> app`` runs a ``callback`` function that gets passed the application object.
It is used to initialize plugins or services.

.. code:: js

   function setupService(app) {
     app.use('/todos', todoService);
   }
   app.configure(setupService);

.listen(port)
-------------

``app.listen([port]) -> HTTPServer`` starts the application on the given
port. It will set up all configured transports (if any) and then run
``app.setup(server)`` (see below) with the server object and then return
the server object.

``listen`` will only be available if a server side transport (REST,
Socket.io or Primus) has been configured.

.. _application_setupserver:

.setup([server])
----------------

``app.setup([server]) -> app`` is used to initialize all services by
calling each :doc:`services#setupapp-path`
method (if available). It will also use the ``server`` instance passed
(e.g. through ``http.createServer``) to set up SocketIO (if enabled) and
any other provider that might require the server instance.

Normally ``app.setup`` will be called automatically when starting the application via ``app.listen([port])`` but there are cases when it needs to be called explicitly.

.set(name, value)
-----------------

``app.set(name, value) -> app`` assigns setting ``name`` to ``value``.

.get(name)
----------

``app.get(name) -> value`` retrieves the setting ``name``.
For more information on server side Express settings see the `Express documentation <http://expressjs.com/en/4x/api.html#app.set>`_.

.. code:: js

   app.set('port', 3030);

   app.listen(app.get('port'));

.on(eventname, listener)
------------------------

Provided by the core `NodeJS EventEmitter .on <https://nodejs.org/api/events.html#events_emitter_on_eventname_listener>`_.
Registers a ``listener`` method (``function(data) {}``) for the given ``eventname``.

.. code:: js

   app.on('login', user => console.log('Logged in', user));

.emit(eventname, data)
----------------------

Provided by the core `NodeJS EventEmitter .emit <https://nodejs.org/api/events.html#events_emitter_emit_eventname_args>`_.
Emits the event ``eventname`` to all event listeners.

.. code:: js

   app.emit('myevent', {
     message: 'Something happened'
   });

   app.on('myevent', data => console.log('myevent happened', data));

.removeListener(eventname, [ listener ])
----------------------------------------

Provided by the core `NodeJS EventEmitter .removeListener <https://nodejs.org/api/events.html#events_emitter_removelistener_eventname_listener>`_.
Removes all or the given listener for ``eventname``.

.mixins
-------

``app.mixins`` contains a list of service mixins.
A mixin is a callback (``(service, path) => {}``) that gets run for every service that is being registered.
Adding your own mixins allows to add functionality to every registered service.

.. code:: js

   const feathers = require('@feathersjs/feathers');
   const app = feathers();
   // Mixins have to be added before registering any services
   app.mixins.push((service, path) => {
     service.sayHello = function() {
       return `Hello from service at '${path}'`;
     }
   });
   app.use('/todos', {
     get(id) {
       return Promise.resolve({ id });
     }
   });
   app.service('todos').sayHello();
   // -> Hello from service at 'todos'

.services
---------

:doc:`./services` keyed by the path they have been registered via ``app.use(path, service)``.
This allows to return a list of all available service names:

.. code:: js

   const servicePaths = Object.keys(app.services);
   servicePaths.forEach(path => {
     const service = app.service(path);
     console.log(path, service);
   });

..

.. note::
   To retrieve services, the `app.service(path) <#servicepath>`_ method should be used (not ``app.services.path`` directly).

A Feathers :doc:`client` does not know anything about the server it is connected to.
This means that ``app.services`` will *not* automatically contain all services available on the server.
Instead, the server has to provide the list of its services, e.g. through a :doc:`./services`.

.. code:: js

   app.use('/info', {
     async find() {
       return {
         services: Object.keys(app.services)
       }
     }
   });

.defaultService
---------------

``app.defaultService`` can be a function that returns an instance of a new standard service for ``app.service(path)`` if there isn’t one registered yet.

.. code:: js

   const memory = require('feathers-memory');

   // For every `path` that doesn't have a service automatically return a new in-memory service
   app.defaultService = function(path) {
     return memory();
   }

This is used by the :doc:`./client` to automatically register client side services that talk to a Feathers server.

.. |GitHub stars| image:: https://img.shields.io/github/stars/feathersjs/feathers.png?style=social&label=Star
   :target: https://github.com/feathersjs/feathers/
.. |npm version| image:: https://img.shields.io/npm/v/feathers.png?style=flat-square
   :target: https://www.npmjs.com/package/feathers
.. |Changelog| image:: https://img.shields.io/badge/changelog-.md-blue.png?style=flat-square
   :target: https://github.com/feathersjs/feathers/blob/master/packages/feathers/CHANGELOG.md