1/* 2 * Copyright (c) 2024-2025 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 */ 29/** 30 * @namespace utils 31 * @syscap SystemCapability.Utils.Lang 32 * @crossplatform 33 * @atomicservice 34 * @since 18 35 */ 36declare namespace utils { 37 /** 38 * Asynchronous lock. 39 * 40 * @namespace locks 41 * @syscap SystemCapability.Utils.Lang 42 * @atomicservice 43 * @since 12 44 */ 45 /** 46 * Asynchronous lock. 47 * 48 * @namespace locks 49 * @syscap SystemCapability.Utils.Lang 50 * @crossplatform 51 * @atomicservice 52 * @since 18 53 */ 54 namespace locks { 55 /** 56 * Type of callback for asyncLock operation. 57 * 58 * @syscap SystemCapability.Utils.Lang 59 * @atomicservice 60 * @since 12 61 */ 62 /** 63 * Type of callback for asyncLock operation. 64 * 65 * @syscap SystemCapability.Utils.Lang 66 * @crossplatform 67 * @atomicservice 68 * @since 18 69 */ 70 type AsyncLockCallback<T> = () => T | Promise<T>; 71 72 /** 73 * Class to execute an asynchronous operation under lock. 74 * 75 * @syscap SystemCapability.Utils.Lang 76 * @atomicservice 77 * @since 12 78 */ 79 /** 80 * Class to execute an asynchronous operation under lock. 81 * 82 * @syscap SystemCapability.Utils.Lang 83 * @crossplatform 84 * @atomicservice 85 * @since 18 86 */ 87 @Sendable 88 class AsyncLock { 89 /** 90 * Default constructor. 91 * 92 * @syscap SystemCapability.Utils.Lang 93 * @atomicservice 94 * @since 12 95 */ 96 /** 97 * Default constructor. 98 * 99 * @syscap SystemCapability.Utils.Lang 100 * @crossplatform 101 * @atomicservice 102 * @since 18 103 */ 104 constructor(); 105 /** 106 * Find or create an instance of AsyncLock using the specified name. 107 * 108 * @param { string } name - name of the lock to find or create. 109 * @returns { AsyncLock } Returns an instance of AsyncLock. 110 * @static 111 * @syscap SystemCapability.Utils.Lang 112 * @atomicservice 113 * @since 12 114 */ 115 /** 116 * Find or create an instance of AsyncLock using the specified name. 117 * 118 * @param { string } name - name of the lock to find or create. 119 * @returns { AsyncLock } Returns an instance of AsyncLock. 120 * @static 121 * @syscap SystemCapability.Utils.Lang 122 * @crossplatform 123 * @atomicservice 124 * @since 18 125 */ 126 static request(name: string): AsyncLock; 127 128 /** 129 * Query information about the specified lock. 130 * 131 * @param { string } name - name of the lock. 132 * @returns { AsyncLockState } Returns an instance of AsyncLockState. 133 * @throws { BusinessError } 401 - The input parameters are invalid. 134 * @throws { BusinessError } 10200030 - The lock does not exist. 135 * @static 136 * @syscap SystemCapability.Utils.Lang 137 * @atomicservice 138 * @since 12 139 */ 140 /** 141 * Query information about the specified lock. 142 * 143 * @param { string } name - name of the lock. 144 * @returns { AsyncLockState } Returns an instance of AsyncLockState. 145 * @throws { BusinessError } 401 - The input parameters are invalid. 146 * @throws { BusinessError } 10200030 - The lock does not exist. 147 * @static 148 * @syscap SystemCapability.Utils.Lang 149 * @crossplatform 150 * @atomicservice 151 * @since 18 152 */ 153 static query(name: string): AsyncLockState; 154 155 /** 156 * Query information about all locks. 157 * 158 * @returns { AsyncLockState[] } Returns an array of AsyncLockState. 159 * @static 160 * @syscap SystemCapability.Utils.Lang 161 * @atomicservice 162 * @since 12 163 */ 164 /** 165 * Query information about all locks. 166 * 167 * @returns { AsyncLockState[] } Returns an array of AsyncLockState. 168 * @static 169 * @syscap SystemCapability.Utils.Lang 170 * @crossplatform 171 * @atomicservice 172 * @since 18 173 */ 174 static queryAll(): AsyncLockState[]; 175 176 /** 177 * Perform an operation with the acquired lock exclusively. 178 * The method acquires the lock first, then calls the callback, and then releases the lock. 179 * The callback is called asynchronously in the same thread where lockAsync was called. 180 * 181 * @param { AsyncLockCallback<T> } callback - function to call when the lock gets acquired. 182 * @returns { Promise<T> } Promise that will be resolved after the callback gets executed. 183 * @throws { BusinessError } 401 - The input parameters are invalid. 184 * @throws { BusinessError } 10200030 - The lock does not exist. 185 * @syscap SystemCapability.Utils.Lang 186 * @atomicservice 187 * @since 12 188 */ 189 /** 190 * Perform an operation with the acquired lock exclusively. 191 * The method acquires the lock first, then calls the callback, and then releases the lock. 192 * The callback is called asynchronously in the same thread where lockAsync was called. 193 * 194 * @param { AsyncLockCallback<T> } callback - function to call when the lock gets acquired. 195 * @returns { Promise<T> } Promise that will be resolved after the callback gets executed. 196 * @throws { BusinessError } 401 - The input parameters are invalid. 197 * @throws { BusinessError } 10200030 - The lock does not exist. 198 * @syscap SystemCapability.Utils.Lang 199 * @crossplatform 200 * @atomicservice 201 * @since 18 202 */ 203 lockAsync<T>(callback: AsyncLockCallback<T>): Promise<T>; 204 205 /** 206 * Perform an operation with the acquired lock. 207 * The method acquires the lock first, then calls the callback, and then releases the lock. 208 * The callback is called asynchronously in the same thread where lockAsync was called. 209 * 210 * @param { AsyncLockCallback<T> } callback - function to call when the lock gets acquired. 211 * @param { AsyncLockMode } mode - mode of the lock operation. 212 * @returns { Promise<T> } Promise that will be resolved after the callback gets executed or rejected. 213 * @throws { BusinessError } 401 - The input parameters are invalid. 214 * @throws { BusinessError } 10200030 - The lock does not exist. 215 * @syscap SystemCapability.Utils.Lang 216 * @atomicservice 217 * @since 12 218 */ 219 /** 220 * Perform an operation with the acquired lock. 221 * The method acquires the lock first, then calls the callback, and then releases the lock. 222 * The callback is called asynchronously in the same thread where lockAsync was called. 223 * 224 * @param { AsyncLockCallback<T> } callback - function to call when the lock gets acquired. 225 * @param { AsyncLockMode } mode - mode of the lock operation. 226 * @returns { Promise<T> } Promise that will be resolved after the callback gets executed or rejected. 227 * @throws { BusinessError } 401 - The input parameters are invalid. 228 * @throws { BusinessError } 10200030 - The lock does not exist. 229 * @syscap SystemCapability.Utils.Lang 230 * @crossplatform 231 * @atomicservice 232 * @since 18 233 */ 234 lockAsync<T>(callback: AsyncLockCallback<T>, mode: AsyncLockMode): Promise<T>; 235 236 /** 237 * Perform an operation with the acquired lock. 238 * The method acquires the lock first, then calls the callback, and then releases the lock. 239 * The callback is called asynchronously in the same thread where lockAsync was called. 240 * An optional timeout value can be provided in {@link AsyncLockOptions}. In this case, lockAsync will reject the 241 * resulting promise with a BusinessError instance if the lock is not acquired before timeout exceeds. 242 * The error message, in this case, will contain the held and waited locks information and possible deadlock 243 * warnings. 244 * 245 * @param { AsyncLockCallback<T> } callback - function to call when the lock gets acquired. 246 * @param { AsyncLockMode } mode - mode of the lock operation. 247 * @param { AsyncLockOptions<U> } options - lock operation options. 248 * @returns { Promise<T | U> } Promise that will be resolved after the callback gets executed or rejected in case 249 * timeout exceeded. 250 * @throws { BusinessError } 401 - The input parameters are invalid. 251 * @throws { BusinessError } 10200030 - The lock does not exist. 252 * @throws { BusinessError } 10200031 - Timeout exceeded. 253 * @syscap SystemCapability.Utils.Lang 254 * @atomicservice 255 * @since 12 256 */ 257 /** 258 * Perform an operation with the acquired lock. 259 * The method acquires the lock first, then calls the callback, and then releases the lock. 260 * The callback is called asynchronously in the same thread where lockAsync was called. 261 * An optional timeout value can be provided in {@link AsyncLockOptions}. In this case, lockAsync will reject the 262 * resulting promise with a BusinessError instance if the lock is not acquired before timeout exceeds. 263 * The error message, in this case, will contain the held and waited locks information and possible deadlock 264 * warnings. 265 * 266 * @param { AsyncLockCallback<T> } callback - function to call when the lock gets acquired. 267 * @param { AsyncLockMode } mode - mode of the lock operation. 268 * @param { AsyncLockOptions<U> } options - lock operation options. 269 * @returns { Promise<T | U> } Promise that will be resolved after the callback gets executed or rejected in case 270 * timeout exceeded. 271 * @throws { BusinessError } 401 - The input parameters are invalid. 272 * @throws { BusinessError } 10200030 - The lock does not exist. 273 * @throws { BusinessError } 10200031 - Timeout exceeded. 274 * @syscap SystemCapability.Utils.Lang 275 * @crossplatform 276 * @atomicservice 277 * @since 18 278 */ 279 lockAsync<T, U>(callback: AsyncLockCallback<T>, mode: AsyncLockMode, 280 options: AsyncLockOptions<U>): Promise<T | U>; 281 282 /** 283 * Name of the lock. 284 * 285 * @type { string } 286 * @readonly 287 * @syscap SystemCapability.Utils.Lang 288 * @atomicservice 289 * @since 12 290 */ 291 /** 292 * Name of the lock. 293 * 294 * @type { string } 295 * @readonly 296 * @syscap SystemCapability.Utils.Lang 297 * @crossplatform 298 * @atomicservice 299 * @since 18 300 */ 301 readonly name: string; 302 } 303 304 /** 305 * Mode of lock operations. 306 * 307 * @enum { number } AsyncLockMode 308 * @syscap SystemCapability.Utils.Lang 309 * @atomicservice 310 * @since 12 311 */ 312 /** 313 * Mode of lock operations. 314 * 315 * @enum { number } AsyncLockMode 316 * @syscap SystemCapability.Utils.Lang 317 * @crossplatform 318 * @atomicservice 319 * @since 18 320 */ 321 enum AsyncLockMode { 322 /** 323 * Shared lock operation. 324 * The operation could reenter if this mode is specified. 325 * 326 * @syscap SystemCapability.Utils.Lang 327 * @atomicservice 328 * @since 12 329 */ 330 /** 331 * Shared lock operation. 332 * The operation could reenter if this mode is specified. 333 * 334 * @syscap SystemCapability.Utils.Lang 335 * @crossplatform 336 * @atomicservice 337 * @since 18 338 */ 339 SHARED = 1, 340 /** 341 * Exclusive lock operation. 342 * If this mode is specified, the operation is executed only when the lock is acquired exclusively. 343 * 344 * @syscap SystemCapability.Utils.Lang 345 * @atomicservice 346 * @since 12 347 */ 348 /** 349 * Exclusive lock operation. 350 * If this mode is specified, the operation is executed only when the lock is acquired exclusively. 351 * 352 * @syscap SystemCapability.Utils.Lang 353 * @crossplatform 354 * @atomicservice 355 * @since 18 356 */ 357 EXCLUSIVE = 2, 358 } 359 360 /** 361 * Lock operation's options 362 * 363 * @syscap SystemCapability.Utils.Lang 364 * @atomicservice 365 * @since 12 366 */ 367 /** 368 * Lock operation's options 369 * 370 * @syscap SystemCapability.Utils.Lang 371 * @crossplatform 372 * @atomicservice 373 * @since 18 374 */ 375 class AsyncLockOptions<T> { 376 /** 377 * Default constructor. 378 * 379 * @syscap SystemCapability.Utils.Lang 380 * @atomicservice 381 * @since 12 382 */ 383 /** 384 * Default constructor. 385 * 386 * @syscap SystemCapability.Utils.Lang 387 * @crossplatform 388 * @atomicservice 389 * @since 18 390 */ 391 constructor(); 392 393 /** 394 * If the value is true and lockAsync cannot acquire the lock immediately, the operation is canceled. 395 * 396 * @type { boolean } 397 * @syscap SystemCapability.Utils.Lang 398 * @atomicservice 399 * @since 12 400 */ 401 /** 402 * If the value is true and lockAsync cannot acquire the lock immediately, the operation is canceled. 403 * 404 * @type { boolean } 405 * @syscap SystemCapability.Utils.Lang 406 * @crossplatform 407 * @atomicservice 408 * @since 18 409 */ 410 isAvailable: boolean; 411 /** 412 * The object used to abort the async operation. If signal.aborted is true, the callback will not be called. 413 * 414 * @type { AbortSignal<T> | null } 415 * @syscap SystemCapability.Utils.Lang 416 * @atomicservice 417 * @since 12 418 */ 419 /** 420 * The object used to abort the async operation. If signal.aborted is true, the callback will not be called. 421 * 422 * @type { AbortSignal<T> | null } 423 * @syscap SystemCapability.Utils.Lang 424 * @crossplatform 425 * @atomicservice 426 * @since 18 427 */ 428 signal: AbortSignal<T> | null; 429 /** 430 * Lock operation timeout in milliseconds. If it is greater than zero, lockAsync will reject the resulting promise 431 * when the timeout is exceeded. 432 * 433 * @type { number } 434 * @syscap SystemCapability.Utils.Lang 435 * @atomicservice 436 * @since 12 437 */ 438 /** 439 * Lock operation timeout in milliseconds. If it is greater than zero, lockAsync will reject the resulting promise 440 * when the timeout is exceeded. 441 * 442 * @type { number } 443 * @syscap SystemCapability.Utils.Lang 444 * @crossplatform 445 * @atomicservice 446 * @since 18 447 */ 448 timeout: number; 449 } 450 451 /** 452 * Information about all lock operations on the AsyncLock instance. 453 * 454 * @syscap SystemCapability.Utils.Lang 455 * @atomicservice 456 * @since 12 457 */ 458 /** 459 * Information about all lock operations on the AsyncLock instance. 460 * 461 * @syscap SystemCapability.Utils.Lang 462 * @crossplatform 463 * @atomicservice 464 * @since 18 465 */ 466 class AsyncLockState { 467 /** 468 * Held locks information. 469 * 470 * @type { AsyncLockInfo[] } 471 * @syscap SystemCapability.Utils.Lang 472 * @atomicservice 473 * @since 12 474 */ 475 /** 476 * Held locks information. 477 * 478 * @type { AsyncLockInfo[] } 479 * @syscap SystemCapability.Utils.Lang 480 * @crossplatform 481 * @atomicservice 482 * @since 18 483 */ 484 held: AsyncLockInfo[]; 485 /** 486 * Pending locks information. 487 * 488 * @type { AsyncLockInfo[] } 489 * @syscap SystemCapability.Utils.Lang 490 * @atomicservice 491 * @since 12 492 */ 493 /** 494 * Pending locks information. 495 * 496 * @type { AsyncLockInfo[] } 497 * @syscap SystemCapability.Utils.Lang 498 * @crossplatform 499 * @atomicservice 500 * @since 18 501 */ 502 pending: AsyncLockInfo[]; 503 } 504 505 /** 506 * Information about a lock. 507 * 508 * @syscap SystemCapability.Utils.Lang 509 * @atomicservice 510 * @since 12 511 */ 512 /** 513 * Information about a lock. 514 * 515 * @syscap SystemCapability.Utils.Lang 516 * @crossplatform 517 * @atomicservice 518 * @since 18 519 */ 520 class AsyncLockInfo { 521 /** 522 * Name of the lock. 523 * 524 * @type { string } 525 * @syscap SystemCapability.Utils.Lang 526 * @atomicservice 527 * @since 12 528 */ 529 /** 530 * Name of the lock. 531 * 532 * @type { string } 533 * @syscap SystemCapability.Utils.Lang 534 * @crossplatform 535 * @atomicservice 536 * @since 18 537 */ 538 name: string; 539 /** 540 * Lock operation mode. 541 * 542 * @type { AsyncLockMode } 543 * @syscap SystemCapability.Utils.Lang 544 * @atomicservice 545 * @since 12 546 */ 547 /** 548 * Lock operation mode. 549 * 550 * @type { AsyncLockMode } 551 * @syscap SystemCapability.Utils.Lang 552 * @crossplatform 553 * @atomicservice 554 * @since 18 555 */ 556 mode: AsyncLockMode; 557 /** 558 * lockAsync caller's execution context identifier. 559 * 560 * @type { number } 561 * @syscap SystemCapability.Utils.Lang 562 * @atomicservice 563 * @since 12 564 */ 565 /** 566 * lockAsync caller's execution context identifier. 567 * 568 * @type { number } 569 * @syscap SystemCapability.Utils.Lang 570 * @crossplatform 571 * @atomicservice 572 * @since 18 573 */ 574 contextId: number; 575 } 576 577 /** 578 * Object used to abort an async operation. 579 * An instance of this class must be accessed in the same thread where the instance is created. 580 * Access to fields of this class from another thread is undefined behaviour. 581 * 582 * @syscap SystemCapability.Utils.Lang 583 * @atomicservice 584 * @since 12 585 */ 586 /** 587 * Object used to abort an async operation. 588 * An instance of this class must be accessed in the same thread where the instance is created. 589 * Access to fields of this class from another thread is undefined behaviour. 590 * 591 * @syscap SystemCapability.Utils.Lang 592 * @crossplatform 593 * @atomicservice 594 * @since 18 595 */ 596 class AbortSignal<T> { 597 /** 598 * Set to true to abort an operation. 599 * 600 * @type { boolean } 601 * @syscap SystemCapability.Utils.Lang 602 * @atomicservice 603 * @since 12 604 */ 605 /** 606 * Set to true to abort an operation. 607 * 608 * @type { boolean } 609 * @syscap SystemCapability.Utils.Lang 610 * @crossplatform 611 * @atomicservice 612 * @since 18 613 */ 614 aborted: boolean; 615 616 /** 617 * Reason for the abort. This value will be used to reject the promise returned from lockAsync. 618 * 619 * @type { T } 620 * @syscap SystemCapability.Utils.Lang 621 * @atomicservice 622 * @since 12 623 */ 624 /** 625 * Reason for the abort. This value will be used to reject the promise returned from lockAsync. 626 * 627 * @type { T } 628 * @syscap SystemCapability.Utils.Lang 629 * @crossplatform 630 * @atomicservice 631 * @since 18 632 */ 633 reason: T 634 } 635 636 /** 637 * Object used for thread synchronization. 638 * 639 * @syscap SystemCapability.Utils.Lang 640 * @atomicservice 641 * @since 18 642 */ 643 @Sendable 644 class ConditionVariable { 645 /** 646 * Default constructor. 647 * 648 * @syscap SystemCapability.Utils.Lang 649 * @atomicservice 650 * @since 18 651 */ 652 constructor() 653 /** 654 * Find or create an instance of ConditionVariable using the specified name. 655 * 656 * @param { string } name - Name of the ConditionVariable to find or create. 657 * @returns { ConditionVariable } Returns an instance of ConditionVariable. 658 * @static 659 * @syscap SystemCapability.Utils.Lang 660 * @atomicservice 661 * @since 18 662 */ 663 static request(name: string): ConditionVariable; 664 /** 665 * Waits for the ConditionVariable to be notified. 666 * 667 * @returns { Promise<void> } A promise will be resolved once the ConditionVariable is notified.. 668 * @syscap SystemCapability.Utils.Lang 669 * @atomicservice 670 * @since 18 671 */ 672 wait(): Promise<void>; 673 /** 674 * Waits for the ConditionVariable to be notified, or until the specified time limit is reached. 675 * 676 * @param { number } timeout - The maximum time to wait. 677 * @returns { Promise<void> } A promise that will be resolved once the ConditionVariable is notified or the 678 * specified time limit is reached. 679 * @syscap SystemCapability.Utils.Lang 680 * @atomicservice 681 * @since 18 682 */ 683 waitFor(timeout: number): Promise<void>; 684 /** 685 * Notify all waiting promise. 686 * 687 * @syscap SystemCapability.Utils.Lang 688 * @atomicservice 689 * @since 18 690 */ 691 notifyAll(): void; 692 /** 693 * Notify one waiting promise. 694 * 695 * @syscap SystemCapability.Utils.Lang 696 * @atomicservice 697 * @since 18 698 */ 699 notifyOne(): void; 700 } 701 } 702 /** 703 * ArkTS JSON utils. 704 * 705 * @namespace ASON 706 * @syscap SystemCapability.Utils.Lang 707 * @atomicservice 708 * @since 12 709 */ 710 /** 711 * ArkTS JSON utils. 712 * 713 * @namespace ASON 714 * @syscap SystemCapability.Utils.Lang 715 * @crossplatform 716 * @atomicservice 717 * @since 18 718 */ 719 namespace ASON { 720 /** 721 * Redefines ISendable for convenience. 722 * 723 * @typedef { lang.ISendable } ISendable 724 * @syscap SystemCapability.Utils.Lang 725 * @atomicservice 726 * @since 12 727 */ 728 /** 729 * Redefines ISendable for convenience. 730 * 731 * @typedef { lang.ISendable } ISendable 732 * @syscap SystemCapability.Utils.Lang 733 * @crossplatform 734 * @atomicservice 735 * @since 18 736 */ 737 type ISendable = lang.ISendable; 738 /** 739 * The type of conversion result function. 740 * 741 * @typedef { function } Transformer 742 * @param { ISendable } this - The ISendable to which the parsed key value pair belongs. 743 * @param { string } key - Attribute name. 744 * @param { ISendable | undefined | null } value - The value of the parsed key value pair. 745 * @returns { ISendable | undefined | null } Return the modified ISendable or undefined or null. 746 * @syscap SystemCapability.Utils.Lang 747 * @atomicservice 748 * @since 12 749 */ 750 /** 751 * The type of conversion result function. 752 * 753 * @typedef { function } Transformer 754 * @param { ISendable } this - The ISendable to which the parsed key value pair belongs. 755 * @param { string } key - Attribute name. 756 * @param { ISendable | undefined | null } value - The value of the parsed key value pair. 757 * @returns { ISendable | undefined | null } Return the modified ISendable or undefined or null. 758 * @syscap SystemCapability.Utils.Lang 759 * @crossplatform 760 * @atomicservice 761 * @since 18 762 */ 763 type Transformer = (this: ISendable, key: string, 764 value: ISendable | undefined | null) => ISendable | undefined | null 765 /** 766 * Converts a JavaScript Object Notation (JSON) string into an ArkTS Value. 767 * 768 * @param { string } text - A valid JSON string. 769 * @param { Transformer } [reviver] - A function that transforms the results. 770 * @param {ParseOptions} [options] - The config of parse. 771 * @returns { ISendable | null } Return an ArkTS Value. 772 * @throws { BusinessError } 401 - Parameter error. Invalid JSON string. 773 * @syscap SystemCapability.Utils.Lang 774 * @atomicservice 775 * @since 12 776 */ 777 /** 778 * Converts a JavaScript Object Notation (JSON) string into an ArkTS Value. 779 * 780 * @param { string } text - A valid JSON string. 781 * @param { Transformer } [reviver] - A function that transforms the results. 782 * @param {ParseOptions} [options] - The config of parse. 783 * @returns { ISendable | null } Return an ArkTS Value. 784 * @throws { BusinessError } 401 - Parameter error. Invalid JSON string. 785 * @syscap SystemCapability.Utils.Lang 786 * @crossplatform 787 * @atomicservice 788 * @since 18 789 */ 790 function parse(text: string, reviver?: Transformer, options?: ParseOptions): ISendable | null; 791 /** 792 * Converts an ArkTS value to a JavaScript Object Notation (JSON) string. 793 * 794 * @param { ISendable | null | undefined } value - The value to stringify. 795 * @returns { string } The JSON string representation of the value. 796 * @throws { BusinessError } 401 - Parameter error. Invalid ArkTS value. 797 * @syscap SystemCapability.Utils.Lang 798 * @atomicservice 799 * @since 12 800 */ 801 /** 802 * Converts an ArkTS value to a JavaScript Object Notation (JSON) string. 803 * Extra supports Map and Set. 804 * 805 * @param { Object | null | undefined } value - The value to stringify. 806 * @returns { string } The JSON string representation of the value. 807 * @throws { BusinessError } 401 - Parameter error. Invalid ArkTS value. 808 * @syscap SystemCapability.Utils.Lang 809 * @atomicservice 810 * @crossplatform 811 * @since 18 812 */ 813 function stringify(value: Object | null | undefined): string; 814 815 /** 816 * Enum defining modes for handling bigint. 817 * 818 * @enum { number } BigIntMode 819 * @syscap SystemCapability.Utils.Lang 820 * @atomicservice 821 * @since 12 822 */ 823 /** 824 * Enum defining modes for handling bigint. 825 * 826 * @enum { number } BigIntMode 827 * @syscap SystemCapability.Utils.Lang 828 * @crossplatform 829 * @atomicservice 830 * @since 18 831 */ 832 const enum BigIntMode { 833 /** 834 * BigInt is not supported. 835 * 836 * @syscap SystemCapability.Utils.Lang 837 * @atomicservice 838 * @since 12 839 */ 840 /** 841 * BigInt is not supported. 842 * 843 * @syscap SystemCapability.Utils.Lang 844 * @crossplatform 845 * @atomicservice 846 * @since 18 847 */ 848 DEFAULT = 0, 849 /** 850 * Parse as BigInt when number less than -(2^53 – 1) or greater than (2^53 – 1). 851 * 852 * @syscap SystemCapability.Utils.Lang 853 * @atomicservice 854 * @since 12 855 */ 856 /** 857 * Parse as BigInt when number less than -(2^53 – 1) or greater than (2^53 – 1). 858 * 859 * @syscap SystemCapability.Utils.Lang 860 * @crossplatform 861 * @atomicservice 862 * @since 18 863 */ 864 PARSE_AS_BIGINT = 1, 865 /** 866 * All numbers parse as BigInt. 867 * 868 * @syscap SystemCapability.Utils.Lang 869 * @atomicservice 870 * @since 12 871 */ 872 /** 873 * All numbers parse as BigInt. 874 * 875 * @syscap SystemCapability.Utils.Lang 876 * @crossplatform 877 * @atomicservice 878 * @since 18 879 */ 880 ALWAYS_PARSE_AS_BIGINT = 2, 881 } 882 883 /** 884 * The return types for parsing. 885 * 886 * @enum { number } ParseReturnType 887 * @syscap SystemCapability.Utils.Lang 888 * @atomicservice 889 * @since 12 890 */ 891 /** 892 * The return types for parsing. 893 * 894 * @enum { number } ParseReturnType 895 * @syscap SystemCapability.Utils.Lang 896 * @crossplatform 897 * @atomicservice 898 * @since 18 899 */ 900 const enum ParseReturnType { 901 /** 902 * Return type is object. 903 * 904 * @syscap SystemCapability.Utils.Lang 905 * @atomicservice 906 * @since 12 907 */ 908 /** 909 * Return type is object. 910 * 911 * @syscap SystemCapability.Utils.Lang 912 * @crossplatform 913 * @atomicservice 914 * @since 18 915 */ 916 OBJECT = 0, 917 /** 918 * Return type is map. 919 * 920 * @syscap SystemCapability.Utils.Lang 921 * @atomicservice 922 * @since 13 923 */ 924 /** 925 * Return type is map. 926 * 927 * @syscap SystemCapability.Utils.Lang 928 * @crossplatform 929 * @atomicservice 930 * @since 18 931 */ 932 MAP = 1, 933 } 934 /** 935 * Parse's options 936 * 937 * @typedef ParseOptions 938 * @syscap SystemCapability.Utils.Lang 939 * @atomicservice 940 * @since 12 941 */ 942 /** 943 * Parse's options 944 * 945 * @typedef ParseOptions 946 * @syscap SystemCapability.Utils.Lang 947 * @crossplatform 948 * @atomicservice 949 * @since 18 950 */ 951 interface ParseOptions { 952 /** 953 * Enum defining modes for handling bigint. 954 * 955 * @type { BigIntMode } 956 * @syscap SystemCapability.Utils.Lang 957 * @atomicservice 958 * @since 12 959 */ 960 /** 961 * Enum defining modes for handling bigint. 962 * 963 * @type { BigIntMode } 964 * @syscap SystemCapability.Utils.Lang 965 * @crossplatform 966 * @atomicservice 967 * @since 18 968 */ 969 bigIntMode: BigIntMode; 970 /** 971 * The return types for parsing. 972 * 973 * @type { ParseReturnType } 974 * @syscap SystemCapability.Utils.Lang 975 * @atomicservice 976 * @since 12 977 */ 978 /** 979 * The return types for parsing. 980 * 981 * @type { ParseReturnType } 982 * @syscap SystemCapability.Utils.Lang 983 * @crossplatform 984 * @atomicservice 985 * @since 18 986 */ 987 parseReturnType: ParseReturnType; 988 } 989 } 990 991 /** 992 * Object used for store least recently used sendable Object. 993 * 994 * @syscap SystemCapability.Utils.Lang 995 * @atomicservice 996 * @since 18 997 */ 998 @Sendable 999 class SendableLruCache<K, V> { 1000 /** 1001 * The length of the SendableLruCache. 1002 * 1003 * @type { number } 1004 * @readonly 1005 * @syscap SystemCapability.Utils.Lang 1006 * @atomicservice 1007 * @since 18 1008 */ 1009 readonly length: number; 1010 /** 1011 * Default constructor. 1012 * 1013 * @param { number } capacity - The capacity of the SendableLruCache. 1014 * @syscap SystemCapability.Utils.Lang 1015 * @atomicservice 1016 * @since 18 1017 */ 1018 constructor(capacity?: number); 1019 /** 1020 * Update the capacity of the SendableLruCache. 1021 * 1022 * @param { number } newCapacity - The new capacity of the SendableLruCache. 1023 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1024 * 1.Mandatory parameters are left unspecified; 1025 * 2.Incorrect parameter types. 1026 * @syscap SystemCapability.Utils.Lang 1027 * @atomicservice 1028 * @since 18 1029 */ 1030 updateCapacity(newCapacity: number): void; 1031 /** 1032 * Get the value associated with a specified key in the SendableLruCache. 1033 * 1034 * @param { K } key - The key to query. 1035 * @returns { V | undefined } The value associated with the key if the specified key is present; 1036 * returns undefined otherwise. 1037 * @syscap SystemCapability.Utils.Lang 1038 * @atomicservice 1039 * @since 18 1040 */ 1041 get(key: K): V | undefined; 1042 /** 1043 * Adds a key-value pair to the SendableLruCache. 1044 * 1045 * @param { K } key - The key to add. 1046 * @param { V } value - The value associated with the key to add. 1047 * @returns { V } The value associated with the added key or the original value 1048 * if the key to add already exists. 1049 * @syscap SystemCapability.Utils.Lang 1050 * @atomicservice 1051 * @since 18 1052 */ 1053 put(key: K, value: V): V; 1054 /** 1055 * Remove a specified key and its associated value from the SendableLruCache. 1056 * 1057 * @param { K } key - The key to delete. 1058 * @returns { V | undefined } The deleted value or undefined. 1059 * @syscap SystemCapability.Utils.Lang 1060 * @atomicservice 1061 * @since 18 1062 */ 1063 remove(key: K): V | undefined; 1064 /** 1065 * Check whether the given key exists in the SendableLruCache. If exists, returns true; otherwise, returns false. 1066 * 1067 * @param { K } key - The key to check. 1068 * @returns { boolean } The result of the checked. 1069 * @syscap SystemCapability.Utils.Lang 1070 * @atomicservice 1071 * @since 18 1072 */ 1073 contains(key: K): boolean; 1074 /** 1075 * Get the number of times createDefault in the SendableLruCache. 1076 * 1077 * @returns { number } The number of times createDefault. 1078 * @syscap SystemCapability.Utils.Lang 1079 * @atomicservice 1080 * @since 18 1081 */ 1082 getCreateCount(): number; 1083 /** 1084 * Get the number of times that the queried values are not matched in the SendableLruCache. 1085 * 1086 * @returns { number } The number of times that the queried values are unmatched. 1087 * @syscap SystemCapability.Utils.Lang 1088 * @atomicservice 1089 * @since 18 1090 */ 1091 getMissCount(): number; 1092 /** 1093 * Get the number of times that values are removed from the SendableLruCache. 1094 * 1095 * @returns { number } The number of times that values are removed. 1096 * @syscap SystemCapability.Utils.Lang 1097 * @atomicservice 1098 * @since 18 1099 */ 1100 getRemoveCount(): number; 1101 /** 1102 * Get the number of times that the queried values are matched in the SendableLruCache. 1103 * 1104 * @returns { number } The number of times that the queried values are matched. 1105 * @syscap SystemCapability.Utils.Lang 1106 * @atomicservice 1107 * @since 18 1108 */ 1109 getMatchCount(): number; 1110 /** 1111 * Get the number of times that values are added to SendableLruCache. 1112 * 1113 * @returns { number } The number of times that values are added. 1114 * @syscap SystemCapability.Utils.Lang 1115 * @atomicservice 1116 * @since 18 1117 */ 1118 getPutCount(): number; 1119 /** 1120 * Get the Capacity of the SendableLruCache. 1121 * 1122 * @returns { number } The Capacity of the SendableLruCache. 1123 * @syscap SystemCapability.Utils.Lang 1124 * @atomicservice 1125 * @since 18 1126 */ 1127 getCapacity(): number; 1128 /** 1129 * Clear all key-value pairs from the SendableLruCache. 1130 * 1131 * @syscap SystemCapability.Utils.Lang 1132 * @atomicservice 1133 * @since 18 1134 */ 1135 clear(): void; 1136 /** 1137 * Checks whether the SendableLruCache is empty. 1138 * 1139 * @returns { boolean } true if the SendableLruCache is empty, otherwise false. 1140 * @syscap SystemCapability.Utils.Lang 1141 * @atomicservice 1142 * @since 18 1143 */ 1144 isEmpty(): boolean; 1145 /** 1146 * Returns a string which repesents all elements in SendableLruCache in the format "key: value". 1147 * 1148 * @returns { string } A new string contains all elements. 1149 * @syscap SystemCapability.Utils.Lang 1150 * @atomicservice 1151 * @since 18 1152 */ 1153 toString(): string; 1154 /** 1155 * Returns a list of all values in the SendableLruCache. 1156 * 1157 * @returns { V[] } An array of all values. 1158 * @syscap SystemCapability.Utils.Lang 1159 * @atomicservice 1160 * @since 18 1161 */ 1162 values(): V[]; 1163 /** 1164 * Returns a list of all keys in the SendableLruCache. 1165 * 1166 * @returns { K[] } An array of all keys. 1167 * @syscap SystemCapability.Utils.Lang 1168 * @atomicservice 1169 * @since 18 1170 */ 1171 keys(): K[]; 1172 /** 1173 * Returns an iterable of key-value pairs for each element in the SendableLruCache. 1174 * 1175 * @returns { IterableIterator<[K, V]> } A new iterable iterator object. 1176 * @syscap SystemCapability.Utils.Lang 1177 * @atomicservice 1178 * @since 18 1179 */ 1180 entries(): IterableIterator<[K, V]>; 1181 } 1182 1183 /** 1184 * Checks whether an ArkTS value is sendable. 1185 * 1186 * @param { Object | null | undefined } value - The value to check. 1187 * @returns { boolean } True if the value is sendable, false otherwise. 1188 * @syscap SystemCapability.Utils.Lang 1189 * @stagemodelonly 1190 * @atomicservice 1191 * @since 12 1192 */ 1193 /** 1194 * Checks whether an ArkTS value is sendable. 1195 * 1196 * @param { Object | null | undefined } value - The value to check. 1197 * @returns { boolean } True if the value is sendable, false otherwise. 1198 * @syscap SystemCapability.Utils.Lang 1199 * @crossplatform 1200 * @stagemodelonly 1201 * @atomicservice 1202 * @since 18 1203 */ 1204 function isSendable(value: Object | null | undefined): boolean; 1205} 1206export default utils; 1207