Persisting Data

It's common for applications to store data on the client browser. AgileTs makes it pretty easy to achieve such goal.

MY_STATE.persist({key: 'storage-key-here'});

Besides States, we can persist nearly any Agile Sub Instance.

• Collections

  MY_COLLECTION.persist({key: 'storage-key-here'});

• Selectors

  MY_SELECTOR.persist({key: 'storage-key-here'});

• Groups

  MY_GROUP.persist({key: 'storage-key-here'});

Since many Agile Sub Instance can be persisted, we use AgilePersistInstance and MY_INSTANCE as word placeholder for them.

💻 Web

In a web environment, it is common to use the Local Storage to store values permanently. AgileTs has set up the Local Storage by default.

const storageManager = createStorageManager({ localStorage: false });
assignSharedStorageManager(storageManager);

Therefore, we can use the persist() method out of the box.

📱 Mobile

Since the Local Storage doesn't exist in a mobile environment, we have to resort to an alternative, such as the Async Storage. AgileTs hasn't set up the Async Storage by default. Therefore, we need to create a Storage Interface representing the Async Storage and register it to AgileTs.

storageManager.registerStorage(
  createStorage({
    key: "AsyncStorage",
    async: true,
    methods: {
      get: AsyncStorage.getItem,
      set: AsyncStorage.setItem,
      remove: AsyncStorage.removeItem,
    },
  }), {default: true} // Tells AgileTs that it is the default Storage
);

🔑 Local Storage Key

Thus AgileTs can access and identify the stored value in the appropriate Storage, we have to define a unique storageKey. There are several ways to provide such required storageKey to the persist() method.

• 1. Assign a unique key to the AgilePersistInstance itself. Because if no key is given to the persist() method, it takes the AgilePersistInstance key as storageKey.

  MY_INSTANCE.key = "myCoolKey";
  MY_INSTANCE.persist(); // Success (storageKey = 'myCoolKey')

• 2. Pass the storageKey directly into the persist() method.

  MY_INSTANCE.persist({key: "myCoolPassedKey"}); // Success (storageKey = 'myCoolPassedKey')

If AgileTs couldn't find any fitting storageKey, it throws an error and doesn't persist the AgilePersistInstance value.

MY_INSTANCE.key = undefined;
MY_INSTANCE.persist(); // Error

💾 default Storage

In AgileTs we can register multipe Storages. However only one of these Storages can be the default Storage. The default Storage is used by the persist() method whenever no specific Storage is defined.

MY_INSTANCE.persist(); // persist in default Storage
MY_INSTANCE.persist({
  storageKeys: ["storageA"]
}); // persist in Storage called 'storageA'

📝 Multiple Storages

Sometimes we may store AgilePersistInstances in different Storages. For example, AgilePersistInstance A should be stored in Storage B, and AgilePersistInstance B should be stored in Storage A. Then, we can define with storageKeys in which specific Storage the AgilePersistInstance value should be persisted.

MY_INSTANCE.persist({
  storageKeys: ["myCustomStorage"]
});

By default, the AgilePersistInstance will be stored in the default Storage.

storageManager.config.defaultStorageKey; // Returns key of current default Storage

🌈 Migration

In rare cases it is necessary to format the State value before it is persisted in an external Storage and migrated back later. When working with the Date class such formatting is required, since a javascript class can't be persisted.

const MY_STATE = createState(
    {
      // ..
      birthday: new Date('08.10.202')
    }
    ).persist(
        {
          key: 'jeff', 
          onSave: (value) => {
              value.date = value.date.getTime()
              return value;
          },
          onMigrate: (value) => {
              value.date = new Date(value.date);
              return value
          }
        }
    );