xref: /interface/sdk-js/arkts/@arkts.utils.d.ets (revision 61847f8e) 
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 Defines the utils for ArkTS
18 * @kit ArkTS
19 */
20
21import lang from './@arkts.lang';
22
23/**
24 * @namespace utils
25 * @syscap SystemCapability.Utils.Lang
26 * @atomicservice
27 * @since 12
28 */
29declare namespace utils {
30  /**
31   * Asynchronous lock.
32   *
33   * @namespace locks
34   * @syscap SystemCapability.Utils.Lang
35   * @atomicservice
36   * @since 12
37   */
38  namespace locks {
39    /**
40     * Type of callback for asyncLock operation.
41     *
42     * @syscap SystemCapability.Utils.Lang
43     * @atomicservice
44     * @since 12
45     */
46    type AsyncLockCallback<T> = () => T | Promise<T>;
47
48    /**
49     * Class to execute an asynchronous operation under lock.
50     *
51     * @syscap SystemCapability.Utils.Lang
52     * @atomicservice
53     * @since 12
54     */
55    @Sendable
56    class AsyncLock {
57      /**
58       * Default constructor.
59       *
60       * @syscap SystemCapability.Utils.Lang
61       * @atomicservice
62       * @since 12
63       */
64      constructor();
65      /**
66       * Find or create an instance of AsyncLock using the specified name.
67       *
68       * @param { string } name - name of the lock to find or create.
69       * @returns { AsyncLock } Returns an instance of AsyncLock.
70       * @static
71       * @syscap SystemCapability.Utils.Lang
72       * @atomicservice
73       * @since 12
74       */
75      static request(name: string): AsyncLock;
76
77      /**
78       * Query information about the specified lock.
79       *
80       * @param { string } name - name of the lock.
81       * @returns { AsyncLockState } Returns an instance of AsyncLockState.
82       * @throws { BusinessError } 401 - The input parameters are invalid.
83       * @throws { BusinessError } 10200030 - The lock does not exist.
84       * @static
85       * @syscap SystemCapability.Utils.Lang
86       * @atomicservice
87       * @since 12
88       */
89      static query(name: string): AsyncLockState;
90
91      /**
92       * Query information about all locks.
93       *
94       * @returns { AsyncLockState[] } Returns an array of AsyncLockState.
95       * @static
96       * @syscap SystemCapability.Utils.Lang
97       * @atomicservice
98       * @since 12
99       */
100      static queryAll(): AsyncLockState[];
101
102      /**
103       * Perform an operation with the acquired lock exclusively.
104       * The method acquires the lock first, then calls the callback, and then releases the lock.
105       * The callback is called asynchronously in the same thread where lockAsync was called.
106       *
107       * @param { AsyncLockCallback<T> } callback - function to call when the lock gets acquired.
108       * @returns { Promise<T> } Promise that will be resolved after the callback gets executed.
109       * @throws { BusinessError } 401 - The input parameters are invalid.
110       * @throws { BusinessError } 10200030 - The lock does not exist.
111       * @syscap SystemCapability.Utils.Lang
112       * @atomicservice
113       * @since 12
114       */
115      lockAsync<T>(callback: AsyncLockCallback<T>): Promise<T>;
116
117      /**
118       * Perform an operation with the acquired lock.
119       * The method acquires the lock first, then calls the callback, and then releases the lock.
120       * The callback is called asynchronously in the same thread where lockAsync was called.
121       *
122       * @param { AsyncLockCallback<T> } callback - function to call when the lock gets acquired.
123       * @param { AsyncLockMode } mode - mode of the lock operation.
124       * @returns { Promise<T> } Promise that will be resolved after the callback gets executed or rejected.
125       * @throws { BusinessError } 401 - The input parameters are invalid.
126       * @throws { BusinessError } 10200030 - The lock does not exist.
127       * @syscap SystemCapability.Utils.Lang
128       * @atomicservice
129       * @since 12
130       */
131      lockAsync<T>(callback: AsyncLockCallback<T>, mode: AsyncLockMode): Promise<T>;
132
133      /**
134       * Perform an operation with the acquired lock.
135       * The method acquires the lock first, then calls the callback, and then releases the lock.
136       * The callback is called asynchronously in the same thread where lockAsync was called.
137       * An optional timeout value can be provided in {@link AsyncLockOptions}. In this case, lockAsync will reject the
138       * resulting promise with a BusinessError instance if the lock is not acquired before timeout exceeds.
139       * The error message, in this case, will contain the held and waited locks information and possible deadlock
140       * warnings.
141       *
142       * @param { AsyncLockCallback<T> } callback - function to call when the lock gets acquired.
143       * @param { AsyncLockMode } mode - mode of the lock operation.
144       * @param { AsyncLockOptions<U> } options - lock operation options.
145       * @returns { Promise<T | U> } Promise that will be resolved after the callback gets executed or rejected in case
146       *     timeout exceeded.
147       * @throws { BusinessError } 401 - The input parameters are invalid.
148       * @throws { BusinessError } 10200030 - The lock does not exist.
149       * @throws { BusinessError } 10200031 - Timeout exceeded.
150       * @syscap SystemCapability.Utils.Lang
151       * @atomicservice
152       * @since 12
153       */
154      lockAsync<T, U>(callback: AsyncLockCallback<T>, mode: AsyncLockMode,
155        options: AsyncLockOptions<U>): Promise<T | U>;
156
157      /**
158       * Name of the lock.
159       *
160       * @type { string }
161       * @readonly
162       * @syscap SystemCapability.Utils.Lang
163       * @atomicservice
164       * @since 12
165       */
166      readonly name: string;
167    }
168
169    /**
170     * Mode of lock operations.
171     *
172     * @enum { number } AsyncLockMode
173     * @syscap SystemCapability.Utils.Lang
174     * @atomicservice
175     * @since 12
176     */
177    enum AsyncLockMode {
178      /**
179       * Shared lock operation.
180       * The operation could reenter if this mode is specified. 
181       *
182       * @syscap SystemCapability.Utils.Lang
183       * @atomicservice
184       * @since 12
185       */
186      SHARED = 1,
187      /**
188       * Exclusive lock operation.
189       * If this mode is specified, the operation is executed only when the lock is acquired exclusively.
190       *
191       * @syscap SystemCapability.Utils.Lang
192       * @atomicservice
193       * @since 12
194       */
195      EXCLUSIVE = 2,
196    }
197
198    /**
199     * Lock operation's options
200     *
201     * @syscap SystemCapability.Utils.Lang
202     * @atomicservice
203     * @since 12
204     */
205    class AsyncLockOptions<T> {
206      /**
207       * Default constructor.
208       *
209       * @syscap SystemCapability.Utils.Lang
210       * @atomicservice
211       * @since 12
212       */
213      constructor();
214
215      /**
216       * If the value is true and lockAsync cannot acquire the lock immediately, the operation is canceled.
217       *
218       * @type { boolean }
219       * @syscap SystemCapability.Utils.Lang
220       * @atomicservice
221       * @since 12
222       */
223      isAvailable: boolean;
224      /**
225       * The object used to abort the async operation. If signal.aborted is true, the callback will not be called.
226       *
227       * @type { AbortSignal<T> | null }
228       * @syscap SystemCapability.Utils.Lang
229       * @atomicservice
230       * @since 12
231       */
232      signal: AbortSignal<T> | null;
233      /**
234       * Lock operation timeout in milliseconds. If it is greater than zero, lockAsync will reject the resulting promise
235       * when the timeout is exceeded.
236       *
237       * @type { number }
238       * @syscap SystemCapability.Utils.Lang
239       * @atomicservice
240       * @since 12
241       */
242      timeout: number;
243    }
244
245    /**
246     * Information about all lock operations on the AsyncLock instance.
247     *
248     * @syscap SystemCapability.Utils.Lang
249     * @atomicservice
250     * @since 12
251     */
252    class AsyncLockState {
253      /**
254       * Held locks information.
255       *
256       * @type { AsyncLockInfo[] }
257       * @syscap SystemCapability.Utils.Lang
258       * @atomicservice
259       * @since 12
260       */
261      held: AsyncLockInfo[];
262      /**
263       * Pending locks information.
264       *
265       * @type { AsyncLockInfo[] }
266       * @syscap SystemCapability.Utils.Lang
267       * @atomicservice
268       * @since 12
269       */
270      pending: AsyncLockInfo[];
271    }
272
273    /**
274     * Information about a lock.
275     *
276     * @syscap SystemCapability.Utils.Lang
277     * @atomicservice
278     * @since 12
279     */
280    class AsyncLockInfo {
281      /**
282       * Name of the lock.
283       *
284       * @type { string }
285       * @syscap SystemCapability.Utils.Lang
286       * @atomicservice
287       * @since 12
288       */
289      name: string;
290      /**
291       * Lock operation mode.
292       *
293       * @type { AsyncLockMode }
294       * @syscap SystemCapability.Utils.Lang
295       * @atomicservice
296       * @since 12
297       */
298      mode: AsyncLockMode;
299      /**
300       * lockAsync caller's execution context identifier.
301       *
302       * @type { number }
303       * @syscap SystemCapability.Utils.Lang
304       * @atomicservice
305       * @since 12
306       */
307      contextId: number;
308    }
309
310    /**
311     * Object used to abort an async operation.
312     * An instance of this class must be accessed in the same thread where the instance is created.
313     * Access to fields of this class from another thread is undefined behaviour.
314     *
315     * @syscap SystemCapability.Utils.Lang
316     * @atomicservice
317     * @since 12
318     */
319    class AbortSignal<T> {
320      /**
321       * Set to true to abort an operation.
322       *
323       * @type { boolean }
324       * @syscap SystemCapability.Utils.Lang
325       * @atomicservice
326       * @since 12
327       */
328      aborted: boolean;
329
330      /**
331       * Reason for the abort. This value will be used to reject the promise returned from lockAsync.
332       *
333       * @type { T }
334       * @syscap SystemCapability.Utils.Lang
335       * @atomicservice
336       * @since 12
337       */
338      reason: T
339    }
340  }
341  /**
342   * ArkTS JSON utils.
343   *
344   * @namespace ASON
345   * @syscap SystemCapability.Utils.Lang
346   * @atomicservice
347   * @since 12
348   */
349  namespace ASON {
350    /**
351     * Redefines ISendable for convenience.
352     *
353     * @typedef { lang.ISendable } ISendable
354     * @syscap SystemCapability.Utils.Lang
355     * @atomicservice
356     * @since 12
357     */
358    type ISendable = lang.ISendable;
359    /**
360    * The type of conversion result function.
361    *
362    * @typedef { function } Transformer
363    * @param { ISendable } this - The ISendable to which the parsed key value pair belongs.
364    * @param { string } key - Attribute name.
365    * @param { ISendable | undefined | null } value - The value of the parsed key value pair.
366    * @returns { ISendable | undefined | null } Return the modified ISendable or undefined or null.
367    * @syscap SystemCapability.Utils.Lang
368    * @atomicservice
369    * @since 12
370    */
371    type Transformer = (this: ISendable, key: string,
372      value: ISendable | undefined | null) => ISendable | undefined | null
373    /**
374     * Converts a JavaScript Object Notation (JSON) string into an ArkTS Value.
375     *
376     * @param { string } text - A valid JSON string.
377     * @param { Transformer } [reviver] - A function that transforms the results.
378     * @param {ParseOptions} [options] - The config of parse.
379     * @returns { ISendable | null } Return an ArkTS Value.
380     * @throws { BusinessError } 401 - Parameter error. Invalid JSON string.
381     * @syscap SystemCapability.Utils.Lang
382     * @atomicservice
383     * @since 12
384     */
385    function parse(text: string, reviver?: Transformer, options?: ParseOptions): ISendable | null;
386    /**
387     * Converts an ArkTS value to a JavaScript Object Notation (JSON) string.
388     *
389     * @param { ISendable | null | undefined } value - The value to stringify.
390     * @returns { string } The JSON string representation of the value.
391     * @throws { BusinessError } 401 - Parameter error. Invalid ArkTS value.
392     * @syscap SystemCapability.Utils.Lang
393     * @atomicservice
394     * @since 12
395     */
396    function stringify(value: ISendable | null | undefined): string;
397
398    /**
399    * Enum defining modes for handling bigint.
400    *
401    * @enum { number } BigIntMode
402    * @syscap SystemCapability.Utils.Lang
403    * @atomicservice
404    * @since 12
405    */
406    const enum BigIntMode {
407      /**
408      * BigInt is not supported.
409      *
410      * @syscap SystemCapability.Utils.Lang
411      * @atomicservice
412      * @since 12
413      */
414      DEFAULT = 0,
415      /**
416      * Parse as BigInt when number less than -(2^53 – 1) or greater than (2^53 – 1).
417      *
418      * @syscap SystemCapability.Utils.Lang
419      * @atomicservice
420      * @since 12
421      */
422      PARSE_AS_BIGINT = 1,
423      /**
424      * All numbers parse as BigInt.
425      *
426      * @syscap SystemCapability.Utils.Lang
427      * @atomicservice
428      * @since 12
429      */
430      ALWAYS_PARSE_AS_BIGINT = 2,
431    }
432
433    /**
434    * The return types for parsing.
435    *
436    * @enum { number } ParseReturnType
437    * @syscap SystemCapability.Utils.Lang
438    * @atomicservice
439    * @since 12
440    */
441    const enum ParseReturnType {
442      /**
443      * Return type is object.
444      *
445      * @syscap SystemCapability.Utils.Lang
446      * @atomicservice
447      * @since 12
448      */
449      OBJECT = 0,
450      /**
451      * Return type is map.
452      *
453      * @syscap SystemCapability.Utils.Lang
454      * @atomicservice
455      * @since 13
456      */
457      MAP = 1,
458    }
459    /**
460    * Parse's options
461    *
462    * @typedef ParseOptions
463    * @syscap SystemCapability.Utils.Lang
464    * @atomicservice
465    * @since 12
466    */
467    interface ParseOptions {
468      /**
469      * Enum defining modes for handling bigint.
470      *
471      * @type { BigIntMode }
472      * @syscap SystemCapability.Utils.Lang
473      * @atomicservice
474      * @since 12
475      */
476      bigIntMode: BigIntMode;
477      /**
478      * The return types for parsing.
479      *
480      * @type { ParseReturnType }
481      * @syscap SystemCapability.Utils.Lang
482      * @atomicservice
483      * @since 12
484      */
485      parseReturnType: ParseReturnType;
486    }
487  }
488
489  /**
490  * Checks whether an ArkTS value is sendable.
491  * 
492  * @param { Object | null | undefined } value - The value to check.
493  * @returns { boolean } True if the value is sendable, false otherwise.
494  * @syscap SystemCapability.Utils.Lang
495  * @stagemodelonly
496  * @atomicservice
497  * @since 12
498  */
499  function isSendable(value: Object | null | undefined): boolean;
500}
501export default utils;
502