@ember-data/store 4.5.0-beta.0 → 4.5.0

package/addon/-private/system/model/states.js

@@ -1,736 +0,0 @@
-/**
-  @module @ember-data/store
-*/
-import { assert } from '@ember/debug';
-
-/*
-  This file encapsulates the various states that a record can transition
-  through during its lifecycle.
-*/
-/**
-  ### State
-
-  Each record has a `currentState` property that explicitly tracks what
-  state a record is in at any given time. For instance, if a record is
-  newly created and has not yet been sent to the adapter to be saved,
-  it would be in the `root.loaded.created.uncommitted` state.  If a
-  record has had local modifications made to it that are in the
-  process of being saved, the record would be in the
-  `root.loaded.updated.inFlight` state. (This state path will be
-  explained in more detail below.)
-
-  Events are sent by the record or its store to the record's
-  `currentState` property. How the state reacts to these events is
-  dependent on which state it is in. In some states, certain events
-  will be invalid and will cause an exception to be raised.
-
-  States are hierarchical and every state is a sub-state of the
-  `RootState`. For example, a record can be in the
-  `root.deleted.uncommitted` state then transitions into the
-  `root.deleted.inFlight` state. If a child state does not implement
-  an event handler, the state manager will attempt to invoke the event
-  on all parent states until the root state is reached. The state
-  hierarchy of a record is described in terms of a path string. You
-  can determine a record's current state by getting the state's
-  `stateName` property:
-
-  ```javascript
-  record.get('currentState.stateName');
-  //=> "root.created.uncommitted"
-   ```
-
-  The hierarchy of valid states that ship with ember data looks like
-  this:
-
-  ```text
-  * root
-    * deleted
-      * saved
-      * uncommitted
-      * inFlight
-    * empty
-    * loaded
-      * created
-        * uncommitted
-        * inFlight
-      * saved
-      * updated
-        * uncommitted
-        * inFlight
-    * loading
-  ```
-
-  The `Model` states are themselves stateless. What that means is
-  that, the hierarchical states that each of *those* points to is a
-  shared data structure. For performance reasons, instead of each
-  record getting its own copy of the hierarchy of states, each record
-  points to this global, immutable shared instance. How does a state
-  know which record it should be acting on? We pass the record
-  instance into the state's event handlers as the first argument.
-
-  The record passed as the first parameter is where you should stash
-  state about the record if needed; you should never store data on the state
-  object itself.
-
-  ### Events and Flags
-
-  A state may implement zero or more events and flags.
-
-  #### Events
-
-  Events are named functions that are invoked when sent to a record. The
-  record will first look for a method with the given name on the
-  current state. If no method is found, it will search the current
-  state's parent, and then its grandparent, and so on until reaching
-  the top of the hierarchy. If the root is reached without an event
-  handler being found, an exception will be raised. This can be very
-  helpful when debugging new features.
-
-  Here's an example implementation of a state with a `myEvent` event handler:
-
-  ```javascript
-  aState: State.create({
-    myEvent: function(manager, param) {
-      console.log("Received myEvent with", param);
-    }
-  })
-  ```
-
-  To trigger this event:
-
-  ```javascript
-  record.send('myEvent', 'foo');
-  //=> "Received myEvent with foo"
-  ```
-
-  Note that an optional parameter can be sent to a record's `send()` method,
-  which will be passed as the second parameter to the event handler.
-
-  Events should transition to a different state if appropriate. This can be
-  done by calling the record's `transitionTo()` method with a path to the
-  desired state. The state manager will attempt to resolve the state path
-  relative to the current state. If no state is found at that path, it will
-  attempt to resolve it relative to the current state's parent, and then its
-  parent, and so on until the root is reached. For example, imagine a hierarchy
-  like this:
-
-      * created
-        * uncommitted <-- currentState
-        * inFlight
-      * updated
-        * inFlight
-
-  If we are currently in the `uncommitted` state, calling
-  `transitionTo('inFlight')` would transition to the `created.inFlight` state,
-  while calling `transitionTo('updated.inFlight')` would transition to
-  the `updated.inFlight` state.
-
-  Remember that *only events* should ever cause a state transition. You should
-  never call `transitionTo()` from outside a state's event handler. If you are
-  tempted to do so, create a new event and send that to the state manager.
-
-  #### Flags
-
-  Flags are Boolean values that can be used to introspect a record's current
-  state in a more user-friendly way than examining its state path. For example,
-  instead of doing this:
-
-  ```javascript
-  var statePath = record.get('stateManager.currentPath');
-  if (statePath === 'created.inFlight') {
-    doSomething();
-  }
-  ```
-
-  You can say:
-
-  ```javascript
-  if (record.get('isNew') && record.get('isSaving')) {
-    doSomething();
-  }
-  ```
-
-  If your state does not set a value for a given flag, the value will
-  be inherited from its parent (or the first place in the state hierarchy
-  where it is defined).
-
-  The current set of flags are defined below. If you want to add a new flag,
-  in addition to the area below, you will also need to declare it in the
-  `Model` class.
-
-
-   * [isEmpty](Model/properties/isEmpty?anchor=isEmpty)
-   * [isLoading](Model/properties/isLoading?anchor=isLoading)
-   * [isLoaded](Model/properties/isLoaded?anchor=isLoaded)
-   * [hasDirtyAttributes](Model/properties/hasDirtyAttributes?anchor=hasDirtyAttributes)
-   * [isSaving](Model/properties/isSaving?anchor=isSaving)
-   * [isDeleted](Model/properties/isDeleted?anchor=isDeleted)
-   * [isNew](Model/properties/isNew?anchor=isNew)
-   * [isValid](Model/properties/isValid?anchor=isValid)
-
-  @class RootState
-  @internal
-*/
-
-function didSetProperty(internalModel, context) {
-  if (context.isDirty) {
-    internalModel.send('becomeDirty');
-  } else {
-    internalModel.send('propertyWasReset');
-  }
-}
-
-// Implementation notes:
-//
-// Each state has a boolean value for all of the following flags:
-//
-// * isLoaded: The record has a populated `data` property. When a
-//   record is loaded via `store.find`, `isLoaded` is false
-//   until the adapter sets it. When a record is created locally,
-//   its `isLoaded` property is always true.
-// * isDirty: The record has local changes that have not yet been
-//   saved by the adapter. This includes records that have been
-//   created (but not yet saved) or deleted.
-// * isSaving: The record has been committed, but
-//   the adapter has not yet acknowledged that the changes have
-//   been persisted to the backend.
-// * isDeleted: The record was marked for deletion. When `isDeleted`
-//   is true and `isDirty` is true, the record is deleted locally
-//   but the deletion was not yet persisted. When `isSaving` is
-//   true, the change is in-flight. When both `isDirty` and
-//   `isSaving` are false, the change has persisted.
-// * isNew: The record was created on the client and the adapter
-//   did not yet report that it was successfully saved.
-// * isValid: The adapter did not report any server-side validation
-//   failures.
-
-// The dirty state is a abstract state whose functionality is
-// shared between the `created` and `updated` states.
-//
-// The deleted state shares the `isDirty` flag with the
-// subclasses of `DirtyState`, but with a very different
-// implementation.
-//
-// Dirty states have three child states:
-//
-// `uncommitted`: the store has not yet handed off the record
-//   to be saved.
-// `inFlight`: the store has handed off the record to be saved,
-//   but the adapter has not yet acknowledged success.
-// `invalid`: the record has invalid information and cannot be
-//   sent to the adapter yet.
-const DirtyState = {
-  initialState: 'uncommitted',
-
-  // FLAGS
-  isDirty: true,
-
-  // SUBSTATES
-
-  // When a record first becomes dirty, it is `uncommitted`.
-  // This means that there are local pending changes, but they
-  // have not yet begun to be saved, and are not invalid.
-  uncommitted: {
-    // EVENTS
-    didSetProperty,
-
-    //TODO(Igor) reloading now triggers a
-    //loadingData event, though it seems fine?
-    loadingData() {},
-
-    propertyWasReset(internalModel, name) {
-      if (!internalModel.hasChangedAttributes()) {
-        internalModel.send('rolledBack');
-      }
-    },
-
-    pushedData(internalModel) {
-      if (!internalModel.hasChangedAttributes()) {
-        internalModel.transitionTo('loaded.saved');
-      }
-    },
-
-    becomeDirty() {},
-
-    willCommit(internalModel) {
-      internalModel.transitionTo('inFlight');
-    },
-
-    reloadRecord(internalModel, { resolve, options }) {
-      resolve(internalModel.store._reloadRecord(internalModel, options));
-    },
-
-    rolledBack(internalModel) {
-      internalModel.transitionTo('loaded.saved');
-    },
-
-    becameInvalid(internalModel) {
-      internalModel.transitionTo('invalid');
-    },
-
-    rollback(internalModel) {
-      internalModel.rollbackAttributes();
-    },
-  },
-
-  // Once a record has been handed off to the adapter to be
-  // saved, it is in the 'in flight' state. Changes to the
-  // record cannot be made during this window.
-  inFlight: {
-    // FLAGS
-    isSaving: true,
-
-    // EVENTS
-    didSetProperty,
-    becomeDirty() {},
-    pushedData() {},
-
-    unloadRecord: assertAgainstUnloadRecord,
-
-    // TODO: More robust semantics around save-while-in-flight
-    willCommit() {},
-
-    didCommit(internalModel) {
-      internalModel.transitionTo('saved');
-      internalModel.send('invokeLifecycleCallbacks', this.dirtyType);
-    },
-
-    rolledBack() {},
-
-    becameInvalid(internalModel) {
-      internalModel.transitionTo('invalid');
-      internalModel.send('invokeLifecycleCallbacks');
-    },
-
-    becameError(internalModel) {
-      internalModel.transitionTo('uncommitted');
-    },
-  },
-
-  // A record is in the `invalid` if the adapter has indicated
-  // the the record failed server-side invalidations.
-  invalid: {
-    // FLAGS
-    isValid: false,
-
-    // EVENTS
-    deleteRecord(internalModel) {
-      internalModel.transitionTo('deleted.uncommitted');
-    },
-
-    didSetProperty(internalModel, context) {
-      internalModel.getRecord().errors._remove(context.name);
-
-      didSetProperty(internalModel, context);
-
-      if (!internalModel.hasErrors()) {
-        this.becameValid(internalModel);
-      }
-    },
-
-    becameInvalid() {},
-    becomeDirty() {},
-    pushedData() {},
-
-    willCommit(internalModel) {
-      clearErrorMessages(internalModel);
-      internalModel.transitionTo('inFlight');
-    },
-
-    rolledBack(internalModel) {
-      clearErrorMessages(internalModel);
-      internalModel.transitionTo('loaded.saved');
-    },
-
-    becameValid(internalModel) {
-      internalModel.transitionTo('uncommitted');
-    },
-
-    invokeLifecycleCallbacks() {},
-  },
-};
-
-// The created and updated states are created outside the state
-// chart so we can reopen their substates and add mixins as
-// necessary.
-
-function deepClone(object) {
-  const clone = {};
-  let value;
-
-  for (let prop in object) {
-    value = object[prop];
-    if (value && typeof value === 'object') {
-      clone[prop] = deepClone(value);
-    } else {
-      clone[prop] = value;
-    }
-  }
-
-  return clone;
-}
-
-function mixin(original, hash) {
-  for (let prop in hash) {
-    original[prop] = hash[prop];
-  }
-
-  return original;
-}
-
-function dirtyState(options) {
-  var newState = deepClone(DirtyState);
-  return mixin(newState, options);
-}
-
-const createdState = dirtyState({
-  dirtyType: 'created',
-  // FLAGS
-  isNew: true,
-
-  setup(internalModel) {
-    internalModel.store.recordArrayManager.recordDidChange(internalModel.identifier);
-  },
-});
-
-createdState.invalid.rolledBack = function (internalModel) {
-  internalModel.transitionTo('deleted.saved');
-};
-
-createdState.uncommitted.rolledBack = function (internalModel) {
-  internalModel.transitionTo('deleted.saved');
-};
-
-const updatedState = dirtyState({
-  dirtyType: 'updated',
-});
-
-function createdStateDeleteRecord(internalModel) {
-  internalModel.transitionTo('deleted.saved');
-  internalModel.send('invokeLifecycleCallbacks');
-}
-
-createdState.uncommitted.deleteRecord = createdStateDeleteRecord;
-
-createdState.invalid.deleteRecord = createdStateDeleteRecord;
-
-createdState.uncommitted.rollback = function (internalModel) {
-  DirtyState.uncommitted.rollback.apply(this, arguments);
-  internalModel.transitionTo('deleted.saved');
-};
-
-createdState.uncommitted.pushedData = function (internalModel) {
-  // TODO @runspired consider where to do this once we kill off state machine
-  internalModel.store._notificationManager.notify(internalModel.identifier, 'identity');
-  internalModel.transitionTo('loaded.updated.uncommitted');
-};
-
-createdState.uncommitted.propertyWasReset = function () {};
-
-function assertAgainstUnloadRecord(internalModel) {
-  assert('You can only unload a record which is not inFlight. `' + internalModel + '`', false);
-}
-
-updatedState.invalid.becameValid = function (internalModel) {
-  // we're eagerly transition into the loaded.saved state, even though we could
-  // be still dirty; but the setup hook of the loaded.saved state checks for
-  // dirty attributes and transitions into the corresponding dirty state
-  internalModel.transitionTo('loaded.saved');
-};
-
-updatedState.inFlight.unloadRecord = assertAgainstUnloadRecord;
-
-updatedState.uncommitted.deleteRecord = function (internalModel) {
-  internalModel.transitionTo('deleted.uncommitted');
-};
-
-updatedState.invalid.rolledBack = function (internalModel) {
-  clearErrorMessages(internalModel);
-  internalModel.transitionTo('loaded.saved');
-};
-
-const RootState = {
-  // FLAGS
-  isEmpty: false,
-  isLoading: false,
-  isLoaded: false,
-  isDirty: false,
-  isSaving: false,
-  isDeleted: false,
-  isNew: false,
-  isValid: true,
-
-  // DEFAULT EVENTS
-
-  // Trying to roll back if you're not in the dirty state
-  // doesn't change your state. For example, if you're in the
-  // in-flight state, rolling back the record doesn't move
-  // you out of the in-flight state.
-  rolledBack() {},
-  unloadRecord(internalModel) {},
-
-  propertyWasReset() {},
-
-  // SUBSTATES
-
-  // A record begins its lifecycle in the `empty` state.
-  // If its data will come from the adapter, it will
-  // transition into the `loading` state. Otherwise, if
-  // the record is being created on the client, it will
-  // transition into the `created` state.
-  empty: {
-    isEmpty: true,
-
-    // EVENTS
-    loadingData(internalModel, promise) {
-      internalModel.transitionTo('loading');
-    },
-
-    loadedData(internalModel) {
-      internalModel.transitionTo('loaded.created.uncommitted');
-    },
-
-    pushedData(internalModel) {
-      internalModel.transitionTo('loaded.saved');
-    },
-
-    // Record is already in an empty state, triggering transition to empty here
-    // produce an error.
-    notFound() {},
-  },
-
-  // A record enters this state when the store asks
-  // the adapter for its data. It remains in this state
-  // until the adapter provides the requested data.
-  //
-  // Usually, this process is asynchronous, using an
-  // XHR to retrieve the data.
-  loading: {
-    // FLAGS
-    isLoading: true,
-
-    exit(internalModel) {
-      internalModel._promiseProxy = null;
-    },
-
-    loadingData() {},
-
-    // EVENTS
-    pushedData(internalModel) {
-      internalModel.transitionTo('loaded.saved');
-      //TODO this seems out of place here
-      internalModel.didCleanError();
-    },
-
-    becameError() {},
-
-    notFound(internalModel) {
-      internalModel.transitionTo('empty');
-    },
-  },
-
-  // A record enters this state when its data is populated.
-  // Most of a record's lifecycle is spent inside substates
-  // of the `loaded` state.
-  loaded: {
-    initialState: 'saved',
-
-    // FLAGS
-    isLoaded: true,
-
-    //TODO(Igor) Reloading now triggers a loadingData event,
-    //but it should be ok?
-    loadingData() {},
-
-    // SUBSTATES
-
-    // If there are no local changes to a record, it remains
-    // in the `saved` state.
-    saved: {
-      setup(internalModel) {
-        if (internalModel.hasChangedAttributes()) {
-          internalModel.adapterDidDirty();
-        }
-      },
-
-      // EVENTS
-      didSetProperty,
-
-      pushedData() {},
-
-      becomeDirty(internalModel) {
-        internalModel.transitionTo('updated.uncommitted');
-      },
-
-      willCommit(internalModel) {
-        internalModel.transitionTo('updated.inFlight');
-      },
-
-      reloadRecord() {},
-
-      deleteRecord(internalModel) {
-        internalModel.transitionTo('deleted.uncommitted');
-      },
-
-      unloadRecord(internalModel) {},
-
-      didCommit() {},
-
-      // loaded.saved.notFound would be triggered by a failed
-      // `reload()` on an unchanged record
-      notFound() {},
-    },
-
-    // A record is in this state after it has been locally
-    // created but before the adapter has indicated that
-    // it has been saved.
-    created: createdState,
-
-    // A record is in this state if it has already been
-    // saved to the server, but there are new local changes
-    // that have not yet been saved.
-    updated: updatedState,
-  },
-
-  // A record is in this state if it was deleted from the store.
-  deleted: {
-    initialState: 'uncommitted',
-    dirtyType: 'deleted',
-
-    // FLAGS
-    isDeleted: true,
-    isLoaded: true,
-    isDirty: true,
-
-    // TRANSITIONS
-    setup(internalModel) {
-      internalModel.store.recordArrayManager.recordDidChange(internalModel.identifier);
-    },
-
-    // SUBSTATES
-
-    // When a record is deleted, it enters the `start`
-    // state. It will exit this state when the record
-    // starts to commit.
-    uncommitted: {
-      // EVENTS
-
-      willCommit(internalModel) {
-        internalModel.transitionTo('inFlight');
-      },
-
-      rollback(internalModel) {
-        internalModel.rollbackAttributes();
-      },
-
-      pushedData() {},
-      becomeDirty() {},
-      deleteRecord() {},
-
-      rolledBack(internalModel) {
-        internalModel.transitionTo('loaded.saved');
-      },
-    },
-
-    // After a record starts committing, but
-    // before the adapter indicates that the deletion
-    // has saved to the server, a record is in the
-    // `inFlight` substate of `deleted`.
-    inFlight: {
-      // FLAGS
-      isSaving: true,
-
-      // EVENTS
-
-      unloadRecord: assertAgainstUnloadRecord,
-
-      // TODO: More robust semantics around save-while-in-flight
-      willCommit() {},
-      didCommit(internalModel) {
-        internalModel.transitionTo('saved');
-
-        internalModel.send('invokeLifecycleCallbacks');
-      },
-
-      becameError(internalModel) {
-        internalModel.transitionTo('uncommitted');
-      },
-
-      becameInvalid(internalModel) {
-        internalModel.transitionTo('invalid');
-      },
-    },
-
-    // Once the adapter indicates that the deletion has
-    // been saved, the record enters the `saved` substate
-    // of `deleted`.
-    saved: {
-      // FLAGS
-      isDirty: false,
-
-      setup(internalModel) {
-        internalModel.removeFromInverseRelationships();
-      },
-
-      invokeLifecycleCallbacks() {},
-
-      willCommit() {},
-      didCommit() {},
-      pushedData() {},
-    },
-
-    invalid: {
-      isValid: false,
-
-      didSetProperty(internalModel, context) {
-        internalModel.getRecord().errors._remove(context.name);
-
-        didSetProperty(internalModel, context);
-
-        if (!internalModel.hasErrors()) {
-          this.becameValid(internalModel);
-        }
-      },
-
-      becameInvalid() {},
-      becomeDirty() {},
-      deleteRecord() {},
-      willCommit() {},
-
-      rolledBack(internalModel) {
-        clearErrorMessages(internalModel);
-        internalModel.transitionTo('loaded.saved');
-      },
-
-      becameValid(internalModel) {
-        internalModel.transitionTo('uncommitted');
-      },
-    },
-  },
-
-  invokeLifecycleCallbacks() {},
-};
-
-function wireState(object, parent, name) {
-  // TODO: Use Object.create and copy instead
-  object = mixin(parent ? Object.create(parent) : {}, object);
-  object.parentState = parent;
-  object.stateName = name;
-
-  for (let prop in object) {
-    if (!Object.prototype.hasOwnProperty.call(object, prop) || prop === 'parentState' || prop === 'stateName') {
-      continue;
-    }
-    if (typeof object[prop] === 'object') {
-      object[prop] = wireState(object[prop], object, name + '.' + prop);
-    }
-  }
-
-  return object;
-}
-
-function clearErrorMessages(internalModel) {
-  internalModel.getRecord().errors._clear();
-}
-
-export default wireState(RootState, null, 'root');