1/*
2 * Copyright (c) 2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * AppStorageV2
18 *
19 * The AppStorageV2 provides a key-value database in memory.
20 *
21 * Main Features:
22 * - Can be imported from anywhere in the app to access the same keys and their values.
23 * - Database content in memory only.
24 * - When app terminates the database content is lows.
25 *
26 * Usage Scenarios:
27 * - Store the object in memory.
28 * - Store the key-value pairs in state management observable view models (e.g., @ObservedV2 class objects).
29 *
30 * The name 'AppStorageV2' is derived from the 'AppStorage', reflecting its purpose to enhance AppStorage.
31 *
32 */
33class AppStorageV2 {
34  /**
35   * If the value for the given key is already available, return the value.
36   * If not, add the key with value generated by calling defaultFunc and return it to caller.
37   *
38   * @template T - The original object.
39   * @param { { new(...args: any): T } } type - The type of the stored value.
40   * @param { string | StorageDefaultCreator<T> } [keyOrDefaultCreator] - The alias name of the key, or function generating the default value.
41   * @param { StorageDefaultCreator<T> } [defaultCreator] - The function generating the default value.
42   * @returns { T } The value of the existed key or the default value.
43   */
44  static connect(type, keyOrDefaultCreator, defaultCreator) {
45    return AppStorageV2.appStorageV2Impl_.connect(type, keyOrDefaultCreator, defaultCreator);
46  }
47
48  /**
49   * Removes the given key. Return false if the given key does not exist.
50   *
51   * @param { string | { new(...args: any): T } } keyOrType - Key or class type removing.
52   */
53  static remove(keyOrType) {
54    AppStorageV2.appStorageV2Impl_.remove(keyOrType);
55  }
56
57  /**
58   * Return the array of all keys.
59   *
60   * @returns { Array<string> } The array of all keys.
61   */
62  static keys() {
63    return AppStorageV2.appStorageV2Impl_.getMemoryKeys();
64  }
65}
66
67AppStorageV2.appStorageV2Impl_ = AppStorageV2Impl.instance();
68
69/**
70 * PersistenceV2
71 *
72 * The PersistenceV2 provides a key-value database in disk.
73 *
74 * Main Features:
75 * - Key and their values are written to disk.
76 * - Keys and values will be available on application re-start.
77 *
78 * Usage Scenarios:
79 * - It is only for @ObservedV2 class objects.
80 *
81 * The name 'PersistenceV2' is derived from the 'PersistentStorage', reflecting its purpose to enhance PersistentStorage.
82 *
83 */
84class PersistenceV2 extends AppStorageV2 {
85  /**
86   * Instructs to persis given (nested) @ObservedV2 class object whenever one of its @Trace decorated properties changes.
87   * If value for given key is available already, return its value. if not, add key with value generated by callling defaultCreator and return it.
88   * It is also allowed to supply an object other than @ObservedV2 class object to connect.
89   * Only in this case need to call the save function manually.
90   *
91   * @template T - The original object.
92   * @param { { new(...args: any): T } } type - The type of the stored value.
93   * @param { string | StorageDefaultCreator<T> } [keyOrDefaultCreator] - The alias name of the key, or function generating the default value.
94   * @param { StorageDefaultCreator<T> } [defaultCreator] - The function generating the default value.
95   * @returns { T } The value of the existed key or the default value.
96   */
97  static connect(type, keyOrDefaultCreator, defaultCreator) {
98    return PersistenceV2.persistenceV2Impl_.connect(type, keyOrDefaultCreator, defaultCreator);
99  }
100
101  /**
102   * The purpose of the save function is request to persist non-observed object changes.
103   * For example, change to object properties without @Trace decotration.
104   * The app needs to call save each time after an object has been changes.
105   *
106   * @param { string | { new(...args: any): T } } keyOrType key or class type need to save, that persist non-observed object changes
107   */
108  static save(keyOrType) {
109    PersistenceV2.persistenceV2Impl_.save(keyOrType);
110  }
111
112  /**
113   * Removes the persistence of given key.
114   * It remove given key from memory cache and from disk.
115   *
116   * @param { string | { new(...args: any): T } } keyOrType - Key or class type removing.
117   */
118  static remove(keyOrType) {
119    PersistenceV2.persistenceV2Impl_.remove(keyOrType);
120  }
121
122  /**
123   * Return the array of all persisted keys.
124   *
125   * @returns { Array<string> } The array of all keys.
126   */
127  static keys() {
128    return PersistenceV2.persistenceV2Impl_.keys();
129  }
130
131  /**
132   * Application can use the function to register its own callback function.
133   * The framework will call the function when persisting has encoutered an error.
134   * The supplied parameters in function call are:
135   * key: of the key-value pair that caused the error
136   * reason: quota or serialisation or unknown failure reason in enum format
137   * message: more explanation of the reason of failure
138   * Calling notifyOnError with undefined unregisters from receiving callback.
139   *
140   * @param { PersistenceErrorCallback } callback called when error
141   */
142  static notifyOnError(callback = undefined) {
143    PersistenceV2.persistenceV2Impl_.notifyOnError(callback);
144  }
145}
146
147PersistenceV2.persistenceV2Impl_ = PersistenceV2Impl.instance();
148
149const Type = __Type__;
150
151/**
152 * UIUtils is a state management tool class for operating the observed data.
153 *
154 * @syscap SystemCapability.ArkUI.ArkUI.Full
155 * @crossplatform
156 * @atomicservice
157 * @since 12
158 */
159class UIUtils {
160  /**
161   * Get raw object from the Object wrapped with Proxy added by statemanagement framework.
162   * If input parameter is a regular Object without Proxy, return Object itself.
163   *
164   * 1. For StateManagement V1, when source is a @Observed decorated object,
165   * or a Object/Array/Map/Set/Date decorated by state decorators like @State,
166   * getTarget will return its raw object without Proxy.
167   * 2. For StateManagement V2, when source is a Array/Map/Set/Date decorated by state decorators
168   * like @Trace or @Local, getTarget will return its raw object without Proxy.
169   * 3. For other situation, getTarget will return the source directly.
170   *
171   * @param { T } source input source Object data.
172   * @returns { T } raw object from the Object wrapped with an ObservedObject.
173   * @syscap SystemCapability.ArkUI.ArkUI.Full
174   * @crossplatform
175   * @atomicservice
176   * @since 12
177   */
178  static getTarget(source) {
179    return UIUtils.uiUtilsImpl_.getTarget(source);
180  }
181
182  /**
183   * Make non-observed data into observed data.
184   * Support non-observed class, JSON.parse, and collection.Set, collection.Map, collection.Array.
185   *
186   * @param { T } source input source object data.
187   * @returns { T } proxy object from the source object data.
188   * @syscap SystemCapability.ArkUI.ArkUI.Full
189   * @crossplatform
190   * @atomicservice
191   * @since 12
192   */
193  static makeObserved(source) {
194    return UIUtils.uiUtilsImpl_.makeObserved(source);
195  }
196}
197
198UIUtils.uiUtilsImpl_ = UIUtilsImpl.instance();
199
200export default {
201  AppStorageV2,
202  PersistenceV2,
203  Type,
204  UIUtils
205};
206