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 * @file 18 * @kit ArkTS 19 */ 20 21/** 22 * JSON is a syntax for serializing objects, arrays, numbers, strings, booleans, and null. 23 * 24 * @namespace json 25 * @syscap SystemCapability.Utils.Lang 26 * @crossplatform 27 * @atomicservice 28 * @since arkts {'1.1':'12', '1.2':'20'} 29 * @arkts 1.1&1.2 30 */ 31declare namespace json { 32 /** 33 * The type of conversion result function. 34 * 35 * @typedef { function } Transformer 36 * @param { Object } this - The object to which the parsed key value pair belongs. 37 * @param { string } key - Attribute name. 38 * @param { Object } value - The value of the parsed key value pair. 39 * @returns { Object | undefined | null } Return an Object, undefined or null value 40 * @syscap SystemCapability.Utils.Lang 41 * @atomicservice 42 * @since arkts {'1.1':'12', '1.2':'20'} 43 * @arkts 1.1&1.2 44 */ 45 type Transformer = (this: Object, key: string, value: Object) => Object | undefined | null; 46 47 /** 48 * Parses a JSON string into an ArkTS object or null. 49 * 50 * @param { string } text - Valid JSON string. 51 * @param { Transformer } [reviver] - Conversion function. This parameter can be used to modify the value generated 52 * after parsing. The default value is undefined. 53 * @param {ParseOptions} options - Parsing options. This parameter is used to control the type of the parsing result. 54 * The default value is undefined. 55 * @returns { Object | null } Return an Object, array, string, number, boolean, or null value corresponding to JSON text. 56 * @throws { BusinessError } 401 - Parameter error. Possible causes: 57 * 1.Mandatory parameters are left unspecified; 58 * 2.Incorrect parameter types; 59 * 3.Parameter verification failed. 60 * @syscap SystemCapability.Utils.Lang 61 * @crossplatform 62 * @atomicservice 63 * @since 12 64 */ 65 function parse(text: string, reviver?: Transformer, options?: ParseOptions): Object | null; 66 67 /** 68 * Converts a JavaScript Object Notation (JSON) string into an Object or null. 69 * 70 * @param { string } text - A valid JSON string. 71 * @param { Type } type - A constructor or class representing the expected type of the parsed result. 72 * @param { Transformer } [reviver] - A function that transforms the results. 73 * @param {ParseOptions} [options] - The config of parse. 74 * @returns { T | null | undefined } Return an Object, array, string, number, boolean, undefined, or null value corresponding to JSON text. 75 * @syscap SystemCapability.Utils.Lang 76 * @crossplatform 77 * @atomicservice 78 * @since 20 79 * @arkts 1.2 80 */ 81 function parse<T>(text: string, type: Type, reviver?: Transformer, options?: ParseOptions): T | null | undefined; 82 83 /** 84 * Converts an ArkTS object or array into a JSON string. In the case of a container, linear containers are supported, 85 * but non-linear containers are not. 86 * 87 * @param { Object } value - ArkTS object or array. In the case of a container, linear containers are supported, but 88 * non-linear containers are not. 89 * @param { (number | string)[] | null } [replacer] - If an array is passed in, only the keys in the array are 90 * serialized to the final JSON string. If null is passed in, all keys of the object are serialized. The default 91 * value is undefined. 92 * @param { string | number } [space] - Indentation, white space, or line break characters inserted into the output 93 * JSON string for readability purposes. If a number is passed in, it indicates the number of space characters to be 94 * used as indentation. If a string is passed in, the string is inserted before the output JSON string. If null is 95 * passed in, no white space is used. The default value is an empty string. 96 * @returns { string } Return a JSON text. 97 * @throws { BusinessError } 401 - Parameter error. Possible causes: 98 * 1.Mandatory parameters are left unspecified; 99 * 2.Incorrect parameter types; 100 * 3.Parameter verification failed. 101 * @syscap SystemCapability.Utils.Lang 102 * @crossplatform 103 * @atomicservice 104 * @since 12 105 */ 106 function stringify(value: Object, replacer?: (number | string)[] | null, space?: string | number): string; 107 108 /** 109 * Converts a JavaScript value to a JavaScript Object Notation (JSON) string. 110 * 111 * @param { NullishType } value - A JavaScript value, usually an NullishType or array. 112 * @param { Transformer | ((number | string)[]) | null } [replacer] - An array of strings and numbers that acts as an approved list 113 * for selecting the object properties that will be stringify. 114 * @param { string | number } [space] - Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read. 115 * @returns { string } Return a JSON text. 116 * @syscap SystemCapability.Utils.Lang 117 * @crossplatform 118 * @atomicservice 119 * @since 20 120 * @arkts 1.2 121 */ 122 function stringify(value: NullishType, replacer?: Transformer | ((number | string)[]) | null, space?: string | number): string; 123 124 /** 125 * Converts an ArkTS object or array into a JSON string. In the case of a container, linear containers are supported, 126 * but non-linear containers are not. 127 * 128 * @param { Object } value - ArkTS object or array. In the case of a container, linear containers are supported, but 129 * non-linear containers are not. 130 * @param { Transformer } [replacer] - During serialization, each key of the serialized value is converted and 131 * processed by this function. The default value is undefined. 132 * @param { string | number } [space] - Indentation, white space, or line break characters inserted into the output 133 * JSON string for readability purposes. If a number is passed in, it indicates the number of space characters to be 134 * used as indentation. If a string is passed in, the string is inserted before the output JSON string. If null is 135 * passed in, no white space is used. The default value is an empty string. 136 * @returns { string } Return a JSON text. 137 * @throws { BusinessError } 401 - Parameter error. Possible causes: 138 * 1.Mandatory parameters are left unspecified; 139 * 2.Incorrect parameter types; 140 * 3.Parameter verification failed. 141 * @syscap SystemCapability.Utils.Lang 142 * @crossplatform 143 * @atomicservice 144 * @since 12 145 */ 146 function stringify(value: Object, replacer?: Transformer, space?: string | number): string; 147 148 /** 149 * Checks whether an ArkTS object contains a key. 150 * 151 * @param { object } obj - The object parsed from a JSON string. 152 * @param { string } property - Determine whether the object contains the property. 153 * @returns { boolean } Return true if the key is in the object, otherwise return false. 154 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. 155 * @syscap SystemCapability.Utils.Lang 156 * @crossplatform 157 * @atomicservice 158 * @since arkts {'1.1':'12', '1.2':'20'} 159 * @arkts 1.1&1.2 160 */ 161 function has(obj: object, property: string): boolean; 162 163 /** 164 * Removes a key from an ArkTS object. 165 * 166 * @param { object } obj - The object parsed from a JSON string. 167 * @param { string } property - The property to be removed. 168 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. 169 * @syscap SystemCapability.Utils.Lang 170 * @crossplatform 171 * @atomicservice 172 * @since 12 173 */ 174 function remove(obj: object, property: string): void; 175 176 /** 177 * Enum defining modes for handling bigint. 178 * 179 * @enum { number } BigIntMode 180 * @syscap SystemCapability.Utils.Lang 181 * @crossplatform 182 * @atomicservice 183 * @since arkts {'1.1':'12', '1.2':'20'} 184 * @arkts 1.1&1.2 185 */ 186 const enum BigIntMode { 187 /** 188 * BigInt is not supported. 189 * 190 * @syscap SystemCapability.Utils.Lang 191 * @crossplatform 192 * @atomicservice 193 * @since arkts {'1.1':'12', '1.2':'20'} 194 * @arkts 1.1&1.2 195 */ 196 DEFAULT = 0, 197 /** 198 * Parse as BigInt when number less than -(2^53 – 1) or greater than (2^53 – 1). 199 * 200 * @syscap SystemCapability.Utils.Lang 201 * @crossplatform 202 * @atomicservice 203 * @since arkts {'1.1':'12', '1.2':'20'} 204 * @arkts 1.1&1.2 205 */ 206 PARSE_AS_BIGINT = 1, 207 /** 208 * All numbers parse as BigInt. 209 * 210 * @syscap SystemCapability.Utils.Lang 211 * @crossplatform 212 * @atomicservice 213 * @since arkts {'1.1':'12', '1.2':'20'} 214 * @arkts 1.1&1.2 215 */ 216 ALWAYS_PARSE_AS_BIGINT = 2, 217 } 218 219 /** 220 * Parse's options 221 * 222 * @typedef ParseOptions 223 * @syscap SystemCapability.Utils.Lang 224 * @crossplatform 225 * @atomicservice 226 * @since arkts {'1.1':'12', '1.2':'20'} 227 * @arkts 1.1&1.2 228 */ 229 interface ParseOptions { 230 /** 231 * Enum defining modes for handling bigint. 232 * @type { BigIntMode } 233 * @syscap SystemCapability.Utils.Lang 234 * @crossplatform 235 * @atomicservice 236 * @since arkts {'1.1':'12', '1.2':'20'} 237 * @arkts 1.1&1.2 238 */ 239 bigIntMode: BigIntMode; 240 } 241} 242export default json; 243