/*
 * Copyright (C) 2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
/**
 * @file State management API file
 * @kit ArkUI
 */
 
import contextConstant from '@ohos.app.ability.contextConstant';

/**
 * Function that returns default creator.
 *
 * @typedef { function } StorageDefaultCreator<T>
 * @returns { T } default creator
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 12
 */
export declare type StorageDefaultCreator<T> = () => T;

/**
 * Define class constructor with arbitrary parameters.
 * @interface TypeConstructorWithArgs<T>
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 12
 */
export interface TypeConstructorWithArgs<T> {
  /**
   * @param { any } args the arguments of the constructor.
   * @returns { T } return class instance.
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 12
   */
  new(...args: any): T;
}

/**
 * Define  ConnectOptions class.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @atomicservice
 * @since 18
 */
export class ConnectOptions<T extends object> {
  /**
   * @type { TypeConstructorWithArgs<T> } type class type of the stored value.
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @atomicservice
   * @since 18
   */
  type: TypeConstructorWithArgs<T>;

  /**
   * Defines alias name of the key, or the function generating the default value.
   * @type { ?string } 
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @atomicservice
   * @since 18
  */
  key?: string;

  /**
   * Define the function generating the default value.
   * @type { ?StorageDefaultCreator<T>} 
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @atomicservice
   * @since 18
  */
  defaultCreator?: StorageDefaultCreator<T>;

  /**
   * Define encrypted partition for data storage.
   * if not passed in, the defaule value is El2
   * 
   * @type { ?contextConstant.AreaMode} 
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @atomicservice
   * @since 18
  */
  areaMode?: contextConstant.AreaMode;
}

/**
 * AppStorageV2 is for UI state of app-wide access, has same life cycle as the app,
 * and saves database content only in memory.
 *
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 12
 */
export declare class AppStorageV2 {
  /**
   * If used by persistenceV2, module-level storage path, different modules will have their own storage paths.
   * If the value for the given key is already available, return the value.
   * If not, add the key with value generated by calling defaultFunc and return it to caller.
   *
   * @param { TypeConstructorWithArgs<T> } type class type of the stored value.
   * @param { string | StorageDefaultCreator<T> } [keyOrDefaultCreator] alias name of the key, or the function generating the default value.
   * @param { StorageDefaultCreator<T> } [defaultCreator] the function generating the default value
   * @returns { T | undefined } the value of the existed key or the default value
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 12
   */
  static connect<T extends object>(
    type: TypeConstructorWithArgs<T>,
    keyOrDefaultCreator?: string | StorageDefaultCreator<T>,
    defaultCreator?: StorageDefaultCreator<T>
  ): T | undefined;

  /**
   * Removes data with the given key or given class type.
   *
   * @param { string | TypeConstructorWithArgs<T> } keyOrType key or class type removing
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 12
   */
  static remove<T>(keyOrType: string | TypeConstructorWithArgs<T>): void;

  /**
   * Return the array of all keys.
   *
   * @returns { Array<string> } the array of all keys
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 12
   */
  static keys(): Array<string>;
}
 
/**
 * Function that returns reason type when error.
 *
 * @typedef { function } PersistenceErrorCallback
 * @param { string } key persisted key when error
 * @param { 'quota' | 'serialization' | 'unknown' } reason reason type when error
 * @param { string } message more message when error
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 12
 */
export declare type PersistenceErrorCallback = (key: string, reason: 'quota' | 'serialization' | 'unknown', message: string) => void;
 
/**
 * PersistenceV2 is for UI state of app-wide access, available on app re-start,
 * and saves database content in disk.
 *
 * @extends AppStorageV2
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 12
 */
export declare class PersistenceV2 extends AppStorageV2 {
  /**
   * Application-level storage path, sharing a storage path for all modules under the application.
   * If the value for the given key is already available, return the value.
   * If not, add the key with value generated by calling defaultFunc and return it to caller.
   *
   * @param { ConnectOptions<T> } type Application level storage parameters.                                     
   * @returns { T | undefined } the value of the existed key or the default value
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @atomicservice
   * @since 18
   */
  static globalConnect<T extends object>(
    type: ConnectOptions<T>
  ): T | undefined;

  /**
   * Used to manually persist data changes to disks.
   *
   * @param { string | TypeConstructorWithArgs<T> } keyOrType key or class type need to persist.
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 12
   */
  static save<T>(keyOrType: string | TypeConstructorWithArgs<T>): void;

  /**
   * Be called when persisting has encountered an error.
   *
   * @param { PersistenceErrorCallback | undefined } callback called when error
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 12
   */
  static notifyOnError(callback: PersistenceErrorCallback | undefined): void;
}
 
/**
 * Define TypeConstructor type.
 *
 * @interface TypeConstructor<T>
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 12
 */
export interface TypeConstructor<T> {
  /**
   * @returns { T }
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 12
   */
  new(): T;
}
 
/**
 * Function that returns PropertyDecorator.
 *
 * @typedef { function } TypeDecorator
 * @param { TypeConstructor<T> } type type info
 * @returns { PropertyDecorator } Type decorator
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 12
 */
export declare type TypeDecorator = <T>(type: TypeConstructor<T>) => PropertyDecorator;
 
/**
 * Define Type PropertyDecorator, adds type information to an object.
 *
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 12
 */
export declare const Type: TypeDecorator;

/**
 * UIUtils is a state management tool class for operating the observed data.
 *
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 12
 */
export declare class UIUtils {
  /**
   * Get raw object from the Object wrapped with an ObservedObject.
   * If input parameter is a regular Object without ObservedObject, return Object itself.
   *
   * @param { T } source input source Object data.
   * @returns { T } raw object from the Object wrapped with an ObservedObject.
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 12
   */
  static getTarget<T extends object>(source: T): T;

   /**
   * Make non-observed data into V2 observed data.
   * Support non-observed class, JSON.parse Object and Sendable class.
   *
   * @param { T } source input source object data.
   * @returns { T } V2 proxy object from the source object data.
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 12
   */
   static makeObserved<T extends object>(source: T): T;

  /**
   * Make non-observed data into V1 observed data.
   * Support JS object, interface, class (non-@Observed, non-ObservedV2).
   *
   * @param { T } source input source object data.
   * @returns { T } V1 proxy object from the source object data.
   * @static
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 19
   */
   static makeV1Observed<T extends object>(source: T): T;

  /**
   * Enables V2 compatibility on given viewmodel object or nested viewmodels, which are V1 observed object already.
   *
   * @param {T} source - The object to be made V2-compatible.
   * @returns {T} The processed object with V2 compatibility enabled.
   * @static
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 19
   */
   static enableV2Compatibility<T extends object>(source: T): T;

  /**
   * Dynamically add monitor for state variable change.
   *
   * @param { object } target class instance or custom component instance.
   * @param { string | string[] } path  monitored change for state variable.
   * @param { MonitorCallback } monitorCallback the function that triggers the callback when state variable change.
   * @param { MonitorOptions} [options] the monitor configuration parameter.
   * @throws { BusinessError } 130000 - The target is not a custom component instance or V2 class instance.
   * @throws { BusinessError } 130001 - The path is invalid.
   * @throws { BusinessError } 130002 - monitorCallback is not a function or an anonymous function.
   * @static
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 20
   */
  static addMonitor(target: object, path: string | string[], monitorCallback: MonitorCallback, options?: MonitorOptions): void;

  /**
   * Dynamically clear monitor callback for state variable change.
   *
   * @param { object } target class instance or custom component instance.
   * @param { string | string[] } path  monitored change for state variable.
   * @param { MonitorCallback } [monitorCallback] the function that triggers the callback when state variable change.
   * @throws { BusinessError } 130000 - The target is not a custom component instance or V2 class instance.
   * @throws { BusinessError } 130001 - The path is invalid.
   * @throws { BusinessError } 130002 - monitorCallback is not a function or an anonymous function.
   * @static
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 20
   */
  static clearMonitor(target: object, path: string | string[], monitorCallback?: MonitorCallback) : void;

   /**
   * Creates read-only data binding.
   * Example. UIUtils.makeBinding<number>(()=>this.num);
   *
   * Supports simple getters for read-only data.
   * Intended for primitive value parameters when calling a @Builder function where arguments are of type Binding.
   *
   * @param { GetterCallback<T> } getter - A value or a function that returns the current value of type T.
   * @returns { Binding<T> } read-only data binding value
   * @static
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 20
   */
  static makeBinding<T>(getter: GetterCallback<T>): Binding<T>;

  /**
   * Creates a mutable data binding.
   *
   * Two functions to implement function overloading.
   *
   * Example. UIUtils.makeBinding<number>(()=>this.num, val => this.num = val);
   *
   * Supports getter-setter pairs for mutable data.
   * Intended for primitive value parameters when calling a @Builder
   * function where arguments are of type MutableBinding.
   *
   * @param { GetterCallback<T> } getter - A value or a function that returns the current value of type T.
   * @param { SetterCallback<T> } setter - A function to set a new value of type T. 
   * If provided, a MutableBinding is created.
   * @returns { MutableBinding<T> } mutable data binding value
   * @static
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 20
   */
  static makeBinding<T>(getter: GetterCallback<T>, setter: SetterCallback<T>): MutableBinding<T>;
}

/**
 * Function that returns monitor instance value when state variable is changed.
 *
 * @typedef { function } MonitorCallback
 * @param { IMonitor} monitorValue monitor instance value when state variable is changed.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 20
 */
export declare type MonitorCallback = (monitorValue: IMonitor) => void;

/**
 * Define Monitor options.
 *
 * @interface MonitorOptions
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 20
 */
export interface MonitorOptions {
  /**
   * Used to determine whether the state variable change is
   * triggered synchronously or asynchronously. The default value is false.
   *
   * @type { ?boolean } isSynchronous parameter
   * @default false
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 20
   */
  isSynchronous?: boolean;
}

/**
 * Getter callback type. It is used to get value.
 *
 * @typedef { function } GetterCallback
 * @returns { T }
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 20
 */
export declare type GetterCallback<T> = () => T;

/**
 * Setter callback type. It is used to assign a new value.
 *
 * @typedef { function } SetterCallback
 * @param { T } newValue - update the value with newValue.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 20
 */
export declare type SetterCallback<T> = (newValue: T) => void;

/**
 * Represents a read-only data binding.
 * Use with @Builder argument list for primitive types. Use makeBinding to pass values when calling the function.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 20
 */
export declare class Binding<T> {
  /**
   * Get function that can acquire the value.
   * @returns T
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 20
   */
  get value(): T;
}

/**
 * Represents a mutable data binding allowing both read and write operations.
 * Use with @Builder argument list for primitive types. Use makeBinding to pass values when calling the function.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @crossplatform
 * @atomicservice
 * @since 20
 */
export declare class MutableBinding<T> {
  /**
   * Get function that can acquire the value.
   * @returns T
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 20
   */
  get value(): T;
  /**
   * Set function that can set the new value.
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @crossplatform
   * @atomicservice
   * @since 20
   */
  set value(newValue: T);
}