Merge pull request #214 from agile-ts/add_migration_callback

add migration callback

Author: bennobuilder

packages/core/src/collection/collection.persistent.ts

@@ -101,7 +101,8 @@ export class CollectionPersistent<
       // Persist default Group and load its value manually to be 100% sure
       // that it was loaded completely
       defaultGroup.loadedInitialValue = false;
-      defaultGroup.persist(defaultGroupStorageKey, {
+      defaultGroup.persist({
+        key: defaultGroupStorageKey,
         loadValue: false,
         defaultStorageKey: this.config.defaultStorageKey || undefined,
         storageKeys: this.storageKeys,
@@ -121,7 +122,8 @@ export class CollectionPersistent<
         // Persist an already present Item and load its value manually to be 100% sure
         // that it was loaded completely
         if (item != null) {
-          item.persist(itemStorageKey, {
+          item.persist({
+            key: itemStorageKey,
             loadValue: false,
             defaultStorageKey: this.config.defaultStorageKey || undefined,
             storageKeys: this.storageKeys,
@@ -135,17 +137,18 @@ export class CollectionPersistent<
         // that it was loaded completely.
         // After a successful loading assign the now valid Item to the Collection.
         else {
-          const placeholderItem =
-            this.collection().getItemWithReference(itemKey);
-          placeholderItem?.persist(itemStorageKey, {
+          const placeholderItem = this.collection().getItemWithReference(
+            itemKey
+          );
+          placeholderItem?.persist({
+            key: itemStorageKey,
             loadValue: false,
             defaultStorageKey: this.config.defaultStorageKey as any,
             storageKeys: this.storageKeys,
             followCollectionPersistKeyPattern: false, // Because of the dynamic 'storageItemKey', the key is already formatted above
           });
           if (placeholderItem?.persistent?.ready) {
-            const loadedPersistedValueIntoItem =
-              await placeholderItem.persistent.loadPersistedValue();
+            const loadedPersistedValueIntoItem = await placeholderItem.persistent.loadPersistedValue();
 
             // If successfully loaded Item value, assign Item to Collection
             if (loadedPersistedValueIntoItem) {
@@ -202,7 +205,8 @@ export class CollectionPersistent<
     getSharedStorageManager()?.set(_storageItemKey, true, this.storageKeys);
 
     // Persist default Group
-    defaultGroup.persist(defaultGroupStorageKey, {
+    defaultGroup.persist({
+      key: defaultGroupStorageKey,
       defaultStorageKey: this.config.defaultStorageKey || undefined,
       storageKeys: this.storageKeys,
       followCollectionPersistKeyPattern: false, // Because of the dynamic 'storageItemKey', the key is already formatted above
@@ -215,7 +219,8 @@ export class CollectionPersistent<
         itemKey,
         _storageItemKey
       );
-      item?.persist(itemStorageKey, {
+      item?.persist({
+        key: itemStorageKey,
         defaultStorageKey: this.config.defaultStorageKey || undefined,
         storageKeys: this.storageKeys,
         followCollectionPersistKeyPattern: false, // Because of the dynamic 'storageItemKey', the key is already formatted above
@@ -348,7 +353,8 @@ export class CollectionPersistent<
         _storageItemKey
       );
       if (item != null && !item.isPersisted)
-        item.persist(itemStorageKey, {
+        item.persist({
+          key: itemStorageKey,
           defaultStorageKey: this.config.defaultStorageKey || undefined,
           storageKeys: this.storageKeys,
           followCollectionPersistKeyPattern: false, // Because of the dynamic 'storageItemKey', the key is already formatted above

packages/core/src/collection/collection.ts

@@ -20,7 +20,7 @@ import {
   TrackedChangeMethod,
 } from './group';
 import { GroupIngestConfigInterface } from './group/group.observer';
-import { StorageKey } from '../storages';
+import { CreatePersistentConfigInterface, StorageKey } from '../storages';
 import { CollectionPersistent } from './collection.persistent';
 
 export class Collection<DataType extends DefaultItem = DefaultItem> {
@@ -936,53 +936,16 @@ export class Collection<DataType extends DefaultItem = DefaultItem> {
    * @public
    * @param config - Configuration object
    */
-  public persist(config?: CollectionPersistentConfigInterface): this;
-  /**
-   * Preserves the Collection `value` in the corresponding external Storage.
-   *
-   * The specified key is used as the unique identifier for the Persistent.
-   *
-   * [Learn more..](https://agile-ts.org/docs/core/collection/methods/#persist)
-   *
-   * @public
-   * @param key - Key/Name identifier of Persistent.
-   * @param config - Configuration object
-   */
-  public persist(
-    key?: StorageKey,
-    config?: CollectionPersistentConfigInterface
-  ): this;
-  public persist(
-    keyOrConfig: StorageKey | CollectionPersistentConfigInterface = {},
-    config: CollectionPersistentConfigInterface = {}
-  ): this {
-    let _config: CollectionPersistentConfigInterface;
-    let key: StorageKey | undefined;
-
-    if (isValidObject(keyOrConfig)) {
-      _config = keyOrConfig as CollectionPersistentConfigInterface;
-      key = this._key;
-    } else {
-      _config = config || {};
-      key = keyOrConfig as StorageKey;
-    }
-
-    _config = defineConfig(_config, {
-      loadValue: true,
-      storageKeys: [],
-      defaultStorageKey: null as any,
+  public persist(config: CreatePersistentConfigInterface = {}): this {
+    config = defineConfig(config, {
+      key: this.key,
     });
 
     // Check if Collection is already persisted
     if (this.persistent != null && this.isPersisted) return this;
 
     // Create Persistent (-> persist value)
-    this.persistent = new CollectionPersistent<DataType>(this, {
-      loadValue: _config.loadValue,
-      storageKeys: _config.storageKeys,
-      key: key,
-      defaultStorageKey: _config.defaultStorageKey,
-    });
+    this.persistent = new CollectionPersistent<DataType>(this, config);
 
     return this;
   }
@@ -1218,7 +1181,9 @@ export class Collection<DataType extends DefaultItem = DefaultItem> {
    * @public
    * @param itemKeys - Item/s with identifier/s to be removed.
    */
-  public remove(itemKeys: ItemKey | Array<ItemKey>): {
+  public remove(
+    itemKeys: ItemKey | Array<ItemKey>
+  ): {
     fromGroups: (groups: Array<ItemKey> | ItemKey) => Collection<DataType>;
     everywhere: (config?: RemoveItemsConfigInterface) => Collection<DataType>;
   } {
@@ -1553,12 +1518,13 @@ export interface CreateCollectionConfigImpl<
   initialData?: Array<DataType>;
 }
 
-export type CreateCollectionConfig<DataType extends DefaultItem = DefaultItem> =
-
-    | CreateCollectionConfigImpl<DataType>
-    | ((
-        collection: Collection<DataType>
-      ) => CreateCollectionConfigImpl<DataType>);
+export type CreateCollectionConfig<
+  DataType extends DefaultItem = DefaultItem
+> =
+  | CreateCollectionConfigImpl<DataType>
+  | ((
+      collection: Collection<DataType>
+    ) => CreateCollectionConfigImpl<DataType>);
 
 export interface CollectionConfigInterface {
   /**
@@ -1636,31 +1602,6 @@ export interface HasConfigInterface {
   notExisting?: boolean;
 }
 
-export interface CollectionPersistentConfigInterface {
-  /**
-   * Whether the Persistent should automatically load
-   * the persisted value into the Collection after its instantiation.
-   * @default true
-   */
-  loadValue?: boolean;
-  /**
-   * Key/Name identifier of Storages
-   * in which the Collection value should be or is persisted.
-   * @default [`defaultStorageKey`]
-   */
-  storageKeys?: StorageKey[];
-  /**
-   * Key/Name identifier of the default Storage of the specified Storage keys.
-   *
-   * The Collection value is loaded from the default Storage by default
-   * and is only loaded from the remaining Storages (`storageKeys`)
-   * if the loading from the default Storage failed.
-   *
-   * @default first index of the specified Storage keys or the AgileTs default Storage key
-   */
-  defaultStorageKey?: StorageKey;
-}
-
 export interface RemoveItemsConfigInterface {
   /**
    * Whether to remove not officially existing Items (such as placeholder Items).

packages/core/src/collection/group/index.ts

@@ -1,27 +1,20 @@
-import {
-  copy,
-  defineConfig,
-  isValidObject,
-  normalizeArray,
-} from '@agile-ts/utils';
+import { copy, defineConfig, normalizeArray } from '@agile-ts/utils';
 import { logCodeManager } from '../../logCodeManager';
 import {
+  CreateStatePersistentConfigInterface,
   EnhancedState,
   StateIngestConfigInterface,
   StateObserver,
   StateObserversInterface,
-  StatePersistentConfigInterface,
 } from '../../state';
 import { Collection, DefaultItem, ItemKey } from '../collection';
 import { GroupIngestConfigInterface, GroupObserver } from './group.observer';
 import { ComputedTracker } from '../../computed';
 import { Item } from '../item';
-import { PersistentKey } from '../../storages';
 import { CollectionPersistent } from '../collection.persistent';
 
 export class Group<
-  DataType extends DefaultItem = DefaultItem,
-  ValueType = Array<ItemKey> // To extract the Group Type Value in Integration methods like 'useAgile()'
+  DataType extends DefaultItem = DefaultItem
 > extends EnhancedState<Array<ItemKey>> {
   // Collection the Group belongs to
   collection: () => Collection<DataType>;
@@ -322,58 +315,22 @@ export class Group<
    * @public
    * @param config - Configuration object
    */
-  public persist(config?: GroupPersistConfigInterface): this;
-  /**
-   * Preserves the Group `value` in the corresponding external Storage.
-   *
-   * The specified key is used as the unique identifier for the Persistent.
-   *
-   * [Learn more..](https://agile-ts.org/docs/core/state/methods/#persist)
-   *
-   * @public
-   * @param key - Key/Name identifier of Persistent.
-   * @param config - Configuration object
-   */
-  public persist(
-    key?: PersistentKey,
-    config?: GroupPersistConfigInterface
-  ): this;
-  public persist(
-    keyOrConfig: PersistentKey | GroupPersistConfigInterface = {},
-    config: GroupPersistConfigInterface = {}
-  ): this {
-    let _config: GroupPersistConfigInterface;
-    let key: PersistentKey | undefined;
-
-    if (isValidObject(keyOrConfig)) {
-      _config = keyOrConfig as GroupPersistConfigInterface;
-      key = this._key;
-    } else {
-      _config = config || {};
-      key = keyOrConfig as PersistentKey;
-    }
-
-    _config = defineConfig(_config, {
-      loadValue: true,
+  public persist(config: GroupPersistConfigInterface = {}): this {
+    config = defineConfig(config, {
+      key: this._key,
       followCollectionPersistKeyPattern: true,
-      storageKeys: [],
-      defaultStorageKey: null as any,
     });
 
     // Create storageItemKey based on Collection key/name identifier
-    if (_config.followCollectionPersistKeyPattern) {
-      key = CollectionPersistent.getGroupStorageKey(
-        key || this._key,
+    if (config.followCollectionPersistKeyPattern) {
+      config.key = CollectionPersistent.getGroupStorageKey(
+        config.key || this._key,
         this.collection()._key
       );
     }
 
     // Persist Group
-    super.persist(key, {
-      loadValue: _config.loadValue,
-      storageKeys: _config.storageKeys,
-      defaultStorageKey: _config.defaultStorageKey,
-    });
+    super.persist(config);
 
     return this;
   }
@@ -524,7 +481,7 @@ export interface GroupConfigInterface {
 }
 
 export interface GroupPersistConfigInterface
-  extends StatePersistentConfigInterface {
+  extends CreateStatePersistentConfigInterface {
   /**
    * Whether to format the specified Storage key following the Collection Group Storage key pattern.
    * `_${collectionKey}_group_${groupKey}`

packages/core/src/collection/item.ts

@@ -1,8 +1,8 @@
-import { defineConfig, isValidObject } from '@agile-ts/utils';
+import { defineConfig } from '@agile-ts/utils';
 import {
+  CreateStatePersistentConfigInterface,
   EnhancedState,
   StateKey,
-  StatePersistentConfigInterface,
   StateRuntimeJobConfigInterface,
 } from '../state';
 import { Collection, DefaultItem } from './collection';
@@ -96,59 +96,21 @@ export class Item<
    * @public
    * @param config - Configuration object
    */
-  public persist(config?: ItemPersistConfigInterface): this;
-  /**
-   * Preserves the Item `value` in the corresponding external Storage.
-   *
-   * The specified key is used as the unique identifier for the Persistent.
-   *
-   * [Learn more..](https://agile-ts.org/docs/core/state/methods/#persist)
-   *
-   * @public
-   * @param key - Key/Name identifier of Persistent.
-   * @param config - Configuration object
-   */
-  public persist(
-    key?: PersistentKey,
-    config?: ItemPersistConfigInterface
-  ): this;
-  public persist(
-    keyOrConfig: PersistentKey | ItemPersistConfigInterface = {},
-    config: ItemPersistConfigInterface = {}
-  ): this {
-    let _config: ItemPersistConfigInterface;
-    let key: PersistentKey | undefined;
-
-    if (isValidObject(keyOrConfig)) {
-      _config = keyOrConfig as ItemPersistConfigInterface;
-      key = this._key;
-    } else {
-      _config = config || {};
-      key = keyOrConfig as PersistentKey;
-    }
-
-    _config = defineConfig(_config, {
-      loadValue: true,
+  public persist(config: ItemPersistConfigInterface = {}): this {
+    config = defineConfig(config, {
+      key: this._key,
       followCollectionPersistKeyPattern: true,
-      storageKeys: [],
-      defaultStorageKey: null as any,
     });
 
     // Create storageItemKey based on Collection key/name identifier
-    if (_config.followCollectionPersistKeyPattern) {
-      key = CollectionPersistent.getItemStorageKey(
-        key || this._key,
+    if (config.followCollectionPersistKeyPattern) {
+      config.key = CollectionPersistent.getItemStorageKey(
+        config.key || this._key,
         this.collection()._key
       );
     }
 
-    // Persist Item
-    super.persist(key, {
-      loadValue: _config.loadValue,
-      storageKeys: _config.storageKeys,
-      defaultStorageKey: _config.defaultStorageKey,
-    });
-
+    super.persist(config);
     return this;
   }
 
@@ -181,7 +143,7 @@ export interface ItemConfigInterface {
 }
 
 export interface ItemPersistConfigInterface
-  extends StatePersistentConfigInterface {
+  extends CreateStatePersistentConfigInterface {
   /**
    * Whether to format the specified Storage key following the Collection Item Storage key pattern.
    * `_${collectionKey}_item_${itemKey}`