# Lifecycle Events

# Introduction

An "event" as it relates to this plugin is any external event which will (or has the potential to) have an impact on state. Both "actions" and "mutations" are not events themselves but are involved in managing events to the appropriate state change.

Actions typically originate from Firemodel but can also originate from this plugin too. They are the first responders to an event which is driven by some externality (database change, user action, etc.). While actions are the first responder, they actually don't change the Vuex state tree themselves but instead call one or more mutations to achieve state change.

Mutations are synchronous functions -- equivalent to a "reducer" in Redux parlance -- that directly manipulate state. Also another key distinction between Actions and Mutations is that while Actions can see and act on the whole state tree, Mutations are isolated to their scope of the state tree (see assumptions).

# Assumptions

When using this plugin it is assumed that you will be using Vuex's modules with namespacing. For any project beyond a simple one this is considered best practice as namespace collisions will start to be hard to avoid.
We also expect that you will define all of your state -- at least that which is backed by your Firebase database -- with Firemodel Model classes

# Mutations and Actions

The mutations and actions we need to concern ourselves with when using this plugin are:

Config Mutations - mutations which work on the @firemodel part of the state tree; this state is somewhat "meta" but is still important to most apps
CRUD Mutations - mutations which reflect change to the core state of the app
Firemodel Actions - the Firemodel library dispatches a set of actions defined by the exported enumeration FmEvents; this plugin responds to all of them by creating mutations. As a consumer of this plugin you will not be directly exposed to these actions (unless you want to be) but it is worth understanding what they are.

We will now go through each of these sections in more detail.

# Config Mutations

The config mutations are those which vuex-plugin-firemodel uses to manage it's own section of the state tree (aka, @firemodel). Mutations originate from either Firemodel actions or this plugin's actions firing off commit() calls to Vuex.

All mutations are defined by the FmConfigMutation enumeration which is exported by this plugin. You can see it's definition below (it is also available as an export to this library):

export const enum FmConfigMutation {
  queueHook = "QUEUE_EVENT_HOOK",
  queueWatcher = "QUEUE_WATCHER",
  /** the DB configuration */
  configure = "CONFIGURE",
  /** starting the DB connection process */
  connecting = "CONNECTING",
  /** the DB has been connected to */
  connected = "CONNECTED",
  /** the DB has been disconnected from */
  disconnected = "DISCONNECTED",
  /** there was a connection error while performing an operation */
  connectionError = "CONNECTION_ERROR",
  /** there was an application error */
  appErr = "APP_ERROR",
  /** clear the errors which were being stored locally */
  clearErrors = "CLEAR_ERRORS",
  /** the "current user" has changed, user identity details have been set */
  setCurrentUser = "SET_CURRENT_USER",
  /** a user has logged in */
  userLoggedIn = "USER_LOGGED_IN",
  /** a user who was previously an "anonymous" user was _upgraded_ to a **known** user */
  userUpgraded = "USER_UPGRADED",
  /** an anonymous user was abaandoned in favor of a logged in user */
  userAbandoned = "USER_ABANDONED",
  /** a user has logged out */
  userLoggedOut = "USER_LOGGED_OUT",
  /** a lifecycle event's hooks have all fired */
  lifecycleEventCompleted = "LIFECYCLE_EVENT_COMPLETED",
  /** all core plugin services have started */
  coreServicesStarted = "CORE_SERVICES_STARTED",

  // watchers

  /** Firebase -- via Firemodel -- has been asked to watch a new path in DB */
  watcherStarting = "WATCHER_STARTING",
  /** Firebase -- via Firemodel -- has started watching a new path in the DB */
  watcherStarted = "WATCHER_STARTED",
  /** When attempting to start a watcher there was a failure (usually permission based) */
  watcherFailed = "WATCHER_FAILED",
  /** Firebase -- via Firemodel -- has stopped watching a new path in the DB */
  watcherStopped = "WATCHER_STOPPED",
  //** All Firebase watchers have been stopped */
  watcherAllStopped = "WATCHER_STOPPED_ALL",
  /**
   * When a "largePayload" has been declared, all SERVER_ADD events from the given
   * watcher are muted for a short period to ensure that Vuex is not bombarded with
   * a mutation for every record.
   */
  watcherMuted = "WATCHER_MUTED",
  /**
   * Once the initial set of SERVER_ADD events, the watcher must be _un_muted to
   * the SERVER_ADD mutations.
   */
  watcherUnmuted = "WATCHER_UNMUTED"
}

Typically these mutations are self-managed and consumers of this plugin can largely ignore the mutations themselves but the "state" which is created by these mutations is often quite useful for consumers.

# CRUD Mutations

# Description

CRUD (Create, Update, and Delete) mutations are mutations which originate from Firemodel actions but specifically from changes to state in the database (or "predicted" change to the database). These changes to state take place throughout the Vuex state tree. Anywhere except the @firemodel state tree.

Because mutations can only operate on their module's area of the state tree you will need to define each Firemodel Model which your app is using as a module in the Vuex store. Fortunately the "state" for that module is defined by the Model and you can leverage the mutations that this plugin provides.

This means that these mutations are defined by this plugin but in order to use them you will need import them into your state modules.

# CRUD Mutations List

The list of CRUD mutations that this plugin will fire into Vuex is defined by the FmCrudMutation enumeration and listed below:

export const enum FmCrudMutation {
  // Client originated changes
  changedLocally = "CHANGED_LOCALLY",
  addedLocally = "ADDED_LOCALLY",
  removedLocally = "REMOVED_LOCALLY",

  relationshipAddedLocally = "RELATIONSHIP_ADDED_LOCALLY",
  relationshipRemovedLocally = "RELATIONSHIP_REMOVED_LOCALLY",
  relationshipSetLocally = "RELATIONSHIP_SET_LOCALLY",

  relationshipAddConfirmation = "RELATIONSHIP_ADDED_CONFIRMATION",
  relationshipRemovedConfirmation = "RELATIONSHIP_REMOVED_CONFIRMATION",
  relationshipSetConfirmation = "RELATIONSHIP_SET_CONFIRMATION",

  relationshipAddRollback = "RELATIONSHIP_ADDED_ROLLBACK",
  relationshipRemovedRollback = "RELATIONSHIP_REMOVED_ROLLBACK",
  relationshipSetRollback = "RELATIONSHIP_SET_ROLLBACK",

  // Client originated changes CONFIRMED
  serverAddConfirm = "ADD_CONFIRMATION",
  serverChangeConfirm = "CHANGE_CONFIRMATION",
  serverRemoveConfirm = "REMOVE_CONFIRMATION",
  // ROLLBACKS
  serverAddRollback = "ROLLBACK_ADD",
  serverChangeRollback = "ROLLBACK_CHANGE",
  serverRemoveRollback = "ROLLBACK_REMOVE",

  // Server originated changes
  serverAdd = "SERVER_ADD",
  serverChange = "SERVER_CHANGE",
  serverRemove = "SERVER_REMOVE",
  /**
   * when a watcher -- which was configured with `largePayload` -- starts,
   * it first sends an array of values that exist on the server so that the
   * server and client are in _sync_.
   */
  serverStateSync = "SERVER_STATE_SYNC",

  /**
   * Allows state modules to be "reset" which involves removing the data
   * in the given module.
   */
  reset = "RESET"
}

Note: that each of these mutations, when actually committed will be committed into a namespace which is defined for the given Model which has changed

# Importing CRUD Mutations

# Firemodel Actions

← Plugin Configuration Mock DB →