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 import { Callback } from './@ohos.base'; 21 import emitter from './@ohos.events.emitter'; 22 23 /** 24 * The stream module provides a comprehensive set of stream processing capabilities, including four types of streams: 25 * - Writable: streams designed for writing data to. 26 * - Readable: streams designed for reading data from. 27 * - Duplex: streams that are both readable and writable. 28 * - Transform: a specialized type of duplex stream that can modify or transform data as it's being written and read. 29 * 30 * @namespace stream 31 * @syscap SystemCapability.Utils.Lang 32 * @crossplatform 33 * @since 12 34 */ 35declare namespace stream { 36 /** 37 * Streams to which data can be written. 38 * 39 * @syscap SystemCapability.Utils.Lang 40 * @crossplatform 41 * @since 12 42 */ 43 class Writable { 44 /** 45 * The Writable constructor. 46 * 47 * @syscap SystemCapability.Utils.Lang 48 * @crossplatform 49 * @since 12 50 */ 51 constructor(); 52 /** 53 * writes a chunk to Writable and invokes callback when the chunk is flushed. The return value indicates 54 * whether the internal buffer of the Writable reaches the hightWaterMark. If true is returned, the buffer 55 * does not reach the hightWaterMark. If false is returned, the buffer has been reached. The write function 56 * should be called after the drain event is triggered. If the write function is called continuously, 57 * the chunk is still added to the buffer until the memory overflows 58 * 59 * @param { string | Uint8Array } [chunk] - Data to be written. 60 * @param { string } [encoding] - Encoding type. 61 * @param { Function } [callback] - Callback after writing. 62 * @returns { boolean } Write success returns true, write failure returns false. 63 * @throws { BusinessError } 401 - An input parameter is invalid. 64 * @throws { BusinessError } 10200035 - The doWrite method has not been implemented. 65 * @throws { BusinessError } 10200036 - The stream has been ended. 66 * @throws { BusinessError } 10200037 - The callback is invoked multiple times consecutively. 67 * @syscap SystemCapability.Utils.Lang 68 * @crossplatform 69 * @since 12 70 */ 71 write(chunk?: string | Uint8Array, encoding?: string, callback?: Function): boolean; 72 /** 73 * Write the last chunk to Writable. 74 * 75 * @param { string | Uint8Array } [chunk] - Data to be written. 76 * @param { string } [encoding] - Encoding type. 77 * @param { Function } [callback] - Callback after writing. 78 * @returns { Writable } Returns the Writable object. 79 * @throws { BusinessError } 401 - An input parameter is invalid. 80 * @throws { BusinessError } 10200035 - The doWrite method has not been implemented. 81 * @syscap SystemCapability.Utils.Lang 82 * @crossplatform 83 * @since 12 84 */ 85 end(chunk?: string | Uint8Array, encoding?: string, callback?: Function): Writable; 86 /** 87 * Set the default encoding mode. 88 * 89 * @param { string } [encoding] - Encoding type.Default: utf8. 90 * @returns { boolean } Setting successful returns true, setting failed returns false. 91 * @throws { BusinessError } 401 - if the input parameters are invalid. 92 * @syscap SystemCapability.Utils.Lang 93 * @crossplatform 94 * @since 12 95 */ 96 setDefaultEncoding(encoding?: string): boolean; 97 /** 98 * After the call, all Write operations will be forced to write to the buffer instead of being flushed. 99 * 100 * @returns { boolean } Setting successful returns true, setting failed returns false. 101 * @syscap SystemCapability.Utils.Lang 102 * @crossplatform 103 * @since 12 104 */ 105 cork(): boolean; 106 /** 107 * After calling, flush all buffers. 108 * 109 * @returns { boolean } Setting successful returns true, setting failed returns false. 110 * @syscap SystemCapability.Utils.Lang 111 * @crossplatform 112 * @since 12 113 */ 114 uncork(): boolean; 115 /** 116 * Registering Event Messages. 117 * 118 * @param { string } event - Register Event. 119 * @param { Callback<emitter.EventData> } callback - event callbacks. 120 * @throws { BusinessError } 401 - if the input parameters are invalid. 121 * @syscap SystemCapability.Utils.Lang 122 * @crossplatform 123 * @since 12 124 */ 125 on(event: string, callback: Callback<emitter.EventData>): void; 126 /** 127 * Cancel event message. 128 * 129 * @param { string } event - Register Event. 130 * @param { Callback<emitter.EventData> } callback - event callbacks. 131 * @throws { BusinessError } 401 - An input parameter is invalid. 132 * @syscap SystemCapability.Utils.Lang 133 * @crossplatform 134 * @since 12 135 */ 136 off(event: string, callback?: Callback<emitter.EventData>): void; 137 /** 138 * This method is invoked by the Writable method during initialization and must not be invoked directly. 139 * After the resource is initialized in the doInitialize method, the callback () method is invoked. 140 * 141 * @param { Function } callback - Callback when the stream has completed the initial. 142 * @throws { BusinessError } 401 - if the input parameters are invalid. 143 * @syscap SystemCapability.Utils.Lang 144 * @crossplatform 145 * @since 12 146 */ 147 doInitialize(callback: Function): void; 148 /** 149 * Implemented by subclass inheritance. The implementation logic of flushing chunks in the buffer must not be 150 * directly called. The call is controlled by Writable.write. 151 * 152 * @param { string | Uint8Array } [chunk] - Data to be written. 153 * @param { string } [encoding] - Encoding type. 154 * @param { Function } [callback] - Callback after writing. 155 * @throws { BusinessError } 401 - if the input parameters are invalid. 156 * @syscap SystemCapability.Utils.Lang 157 * @crossplatform 158 * @since 12 159 */ 160 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function): void; 161 /** 162 * The implementation logic of flushing chunks in the buffer in batches should not be actively called. 163 * The call is controlled by Writable.write. 164 * 165 * @param { string[] | Uint8Array[] } [chunks] - Data to be written. 166 * @param { Function } [callback] - Callback after writing. 167 * @throws { BusinessError } 401 - if the input parameters are invalid. 168 * @syscap SystemCapability.Utils.Lang 169 * @crossplatform 170 * @since 12 171 */ 172 doWritev(chunks: string[] | Uint8Array[], callback: Function): void; 173 /** 174 * Returns boolean indicating whether it is in ObjectMode. 175 * 176 * @type { boolean } 177 * @readonly 178 * @syscap SystemCapability.Utils.Lang 179 * @crossplatform 180 * @since 12 181 */ 182 readonly writableObjectMode: boolean; 183 /** 184 * Value of highWatermark. 185 * 186 * @type { number } 187 * @readonly 188 * @syscap SystemCapability.Utils.Lang 189 * @crossplatform 190 * @since 12 191 */ 192 readonly writableHighWatermark: number; 193 /** 194 * Is true if it is safe to call writable.write(), which means the stream has not been destroyed, error or end. 195 * 196 * @type { boolean } 197 * @readonly 198 * @syscap SystemCapability.Utils.Lang 199 * @crossplatform 200 * @since 12 201 */ 202 readonly writable: boolean; 203 /** 204 * Size of data that can be flushed, in bytes or objects. 205 * 206 * @type { number } 207 * @readonly 208 * @syscap SystemCapability.Utils.Lang 209 * @crossplatform 210 * @since 12 211 */ 212 readonly writableLength: number; 213 /** 214 * Number of times writable.uncork() needs to be called in order to fully uncork the stream. 215 * 216 * @type { number } 217 * @readonly 218 * @syscap SystemCapability.Utils.Lang 219 * @crossplatform 220 * @since 12 221 */ 222 readonly writableCorked: number; 223 /** 224 * Whether Writable.end has been called. 225 * 226 * @type { boolean } 227 * @readonly 228 * @syscap SystemCapability.Utils.Lang 229 * @crossplatform 230 * @since 12 231 */ 232 readonly writableEnded: boolean; 233 /** 234 * Whether Writable.end has been called and all buffers have been flushed. 235 * 236 * @type { boolean } 237 * @readonly 238 * @syscap SystemCapability.Utils.Lang 239 * @crossplatform 240 * @since 12 241 */ 242 readonly writableFinished: boolean; 243 } 244 /** 245 * Transform stream is a Duplex stream where the output is computed in some way from the input. 246 * Transform implementations must implement the doTransform() method and may also implement the doFlush() method. 247 * 248 * @extends Duplex 249 * @syscap SystemCapability.Utils.Lang 250 * @crossplatform 251 * @since 12 252 */ 253 class Transform extends Duplex { 254 /** 255 * The Transform constructor. 256 * 257 * @syscap SystemCapability.Utils.Lang 258 * @crossplatform 259 * @since 12 260 */ 261 constructor(); 262 /** 263 * Convert the input data. After the conversion, Transform.push can be called to send the input to the read stream. 264 * Transform.push should not be called Transform.write to call. 265 * 266 * @param { string } chunk - Input data to be converted. 267 * @param { string } encoding - If the chunk is a string, then this is the encoding type. If chunk is a buffer, 268 * then this is the special value 'buffer'. Ignore it in that case. 269 * @param { Function } callback - Callback after conversion. 270 * @throws { BusinessError } 401 - if the input parameters are invalid. 271 * @syscap SystemCapability.Utils.Lang 272 * @crossplatform 273 * @since 12 274 */ 275 doTransform(chunk: string, encoding: string, callback: Function): void; 276 /** 277 * After all data is flushed to the write stream, you can use the Transform.doFlush writes some extra data, must 278 * not be called directly, only called by Writable after flushing all data. 279 * 280 * @param { Function } callback - Callback after flush completion. 281 * @throws { BusinessError } 401 - if the input parameters are invalid. 282 * @syscap SystemCapability.Utils.Lang 283 * @crossplatform 284 * @since 12 285 */ 286 doFlush(callback: Function): void; 287 } 288 /** 289 * The stream from which data can be read. 290 * 291 * @syscap SystemCapability.Utils.Lang 292 * @crossplatform 293 * @since 12 294 */ 295 class Readable { 296 /** 297 * The Readable constructor. 298 * 299 * @syscap SystemCapability.Utils.Lang 300 * @crossplatform 301 * @since 12 302 */ 303 constructor(); 304 /** 305 * Reads a buffer of a specified size from the buffer. If the available buffer is sufficient, the result 306 * of the specified size is returned. Otherwise, if Readable has ended, all remaining buffers are returned. 307 * 308 * @param { number } size - Expected length of the data to be read. 309 * @returns { string | null } If no data is available to read, null is returned. 310 * @throws { BusinessError } 401 - An input parameter is invalid. 311 * @throws { BusinessError } 10200038 - The doRead method has not been implemented. 312 * @syscap SystemCapability.Utils.Lang 313 * @crossplatform 314 * @since 12 315 */ 316 read(size?: number): string | null; 317 /** 318 * Switch Readable to Streaming Mode. 319 * 320 * @returns { Readable } Return this object. 321 * @syscap SystemCapability.Utils.Lang 322 * @crossplatform 323 * @since 12 324 */ 325 resume(): Readable; 326 /** 327 * Toggle Readable to Suspend Mode. 328 * 329 * @returns { Readable } Return this object. 330 * @syscap SystemCapability.Utils.Lang 331 * @crossplatform 332 * @since 12 333 */ 334 pause(): Readable; 335 /** 336 * Sets the encoding format of the input binary data.Default: utf8. 337 * 338 * @param { string } [encoding] - Original Data Encoding Type. 339 * @returns { boolean } Setting successful returns true, setting failed returns false. 340 * @throws { BusinessError } 401 - if the input parameters are invalid. 341 * @syscap SystemCapability.Utils.Lang 342 * @crossplatform 343 * @since 12 344 */ 345 setEncoding(encoding?: string): boolean; 346 /** 347 * Query whether it is in pause state. 348 * 349 * @returns { boolean } Pause state returns true, otherwise returns false. 350 * @syscap SystemCapability.Utils.Lang 351 * @crossplatform 352 * @since 12 353 */ 354 isPaused(): boolean; 355 /** 356 * Concatenated a Writable to a Readable and switches the Readable to stream mode. 357 * 358 * @param { Writable } destination - Output writable stream. 359 * @param { Object } [options] - Pipeline Options. 360 * @returns { Writable } Returns the Writable object. 361 * @throws { BusinessError } 401 - if the input parameters are invalid. 362 * @syscap SystemCapability.Utils.Lang 363 * @crossplatform 364 * @since 12 365 */ 366 pipe(destination: Writable, options?: Object): Writable; 367 /** 368 * Disconnect Writable from Readable. 369 * 370 * @param { Writable } [destination] - Writable Streams Needing to Be Disconnected. 371 * @returns { Readable } Returns the Readable object. 372 * @throws { BusinessError } 401 - if the input parameters are invalid. 373 * @syscap SystemCapability.Utils.Lang 374 * @crossplatform 375 * @since 12 376 */ 377 unpipe(destination?: Writable): Readable; 378 /** 379 * Registering Event Messages. 380 * 381 * @param { string } event - Registering Events. 382 * @param { Callback<emitter.EventData> } callback - Event callback. 383 * @throws { BusinessError } 401 - if the input parameters are invalid. 384 * @syscap SystemCapability.Utils.Lang 385 * @crossplatform 386 * @since 12 387 */ 388 on(event: string, callback: Callback<emitter.EventData>): void; 389 /** 390 * Cancel event message. 391 * 392 * @param { string } event - Registering Events. 393 * @param { Callback<emitter.EventData> } callback - Event callback. 394 * @throws { BusinessError } 401 - An input parameter is invalid. 395 * @syscap SystemCapability.Utils.Lang 396 * @crossplatform 397 * @since 12 398 */ 399 off(event: string, callback?: Callback<emitter.EventData>): void; 400 /** 401 * It may be implemented by child classes, and if so, will be called by the Readable class methods only. 402 * It must not be called directly. 403 * 404 * @param { Function } callback - Callback when the stream has completed the initial. 405 * @throws { BusinessError } 401 - if the input parameters are invalid. 406 * @syscap SystemCapability.Utils.Lang 407 * @crossplatform 408 * @since 12 409 */ 410 doInitialize(callback: Function): void; 411 /** 412 * The specific implementation of data production. It must not be actively called. 413 * After data production, Readable.push should be called to push the produced data into the buffer. 414 * If push is not called, doRead will not be called again. 415 * 416 * @param { number } size - Expected length of the data to be read. 417 * @throws { BusinessError } 401 - if the input parameters are invalid. 418 * @syscap SystemCapability.Utils.Lang 419 * @crossplatform 420 * @since 12 421 */ 422 doRead(size: number): void; 423 /** 424 * Adds the generated data to the buffer. The return value indicates whether the data in the buffer has not 425 * reached the highWaterMark (similar to Writable.write). If the chunk is null, all data has been generated. 426 * 427 * @param { Uint8Array | string | null } chunk - Binary data to be stored in the buffer. 428 * @param { string } [encoding] - Binary data encoding type. 429 * @returns { boolean } If true is returned, the data in the buffer reaches the highWaterMark. Otherwise, the 430 * data in the buffer does not reach the highWaterMark. 431 * @throws { BusinessError } 401 - if the input parameters are invalid. 432 * @syscap SystemCapability.Utils.Lang 433 * @crossplatform 434 * @since 12 435 */ 436 push(chunk: Uint8Array | string | null, encoding?: string): boolean; 437 /** 438 * Returns boolean indicating whether it is in ObjectMode. 439 * 440 * @type { boolean } 441 * @readonly 442 * @syscap SystemCapability.Utils.Lang 443 * @crossplatform 444 * @since 12 445 */ 446 readonly readableObjectMode: boolean; 447 /** 448 * Is true if it is safe to call readable.read(), which means 449 * the stream has not been destroyed or emitted 'error' or 'end'. 450 * 451 * @type { boolean } 452 * @readonly 453 * @syscap SystemCapability.Utils.Lang 454 * @crossplatform 455 * @since 12 456 */ 457 readonly readable: boolean; 458 /** 459 * Returns the value of highWatermark passed when creating this Readable. 460 * 461 * @type { number } 462 * @readonly 463 * @syscap SystemCapability.Utils.Lang 464 * @crossplatform 465 * @since 12 466 */ 467 readonly readableHighWatermark: number 468 /** 469 * This property reflects the current state of the readable stream null/true/false. 470 * 471 * @type { boolean | null } 472 * @readonly 473 * @syscap SystemCapability.Utils.Lang 474 * @crossplatform 475 * @since 12 476 */ 477 readonly readableFlowing: boolean | null; 478 /** 479 * Size of the data that can be read, in bytes or objects. 480 * 481 * @type { number } 482 * @readonly 483 * @syscap SystemCapability.Utils.Lang 484 * @crossplatform 485 * @since 12 486 */ 487 readonly readableLength: number; 488 /** 489 * Getter for the property encoding of a given Readable stream. The encoding property can be set using the 490 * readable.setEncoding() method. 491 * 492 * @type { string | null } 493 * @readonly 494 * @syscap SystemCapability.Utils.Lang 495 * @crossplatform 496 * @since 12 497 */ 498 readonly readableEncoding: string | null; 499 /** 500 * Whether all data has been generated. 501 * 502 * @type { boolean } 503 * @readonly 504 * @syscap SystemCapability.Utils.Lang 505 * @crossplatform 506 * @since 12 507 */ 508 readonly readableEnded: boolean; 509 } 510 /** 511 * Duplex streams are streams that implement both the Readable streams and Writable streams interfaces. 512 * 513 * @extends Readable 514 * @syscap SystemCapability.Utils.Lang 515 * @crossplatform 516 * @since 12 517 */ 518 class Duplex extends Readable { 519 /** 520 * The Duplex constructor. 521 * 522 * @syscap SystemCapability.Utils.Lang 523 * @crossplatform 524 * @since 12 525 */ 526 constructor(); 527 /** 528 * writes a chunk to Writable and invokes callback when the chunk is flushed. The return value indicates 529 * whether the internal buffer of the Writable reaches the hightWaterMark. If true is returned, the buffer 530 * does not reach the hightWaterMark. If false is returned, the buffer has been reached. The write function 531 * should be called after the drain event is triggered. If the write function is called continuously, 532 * the chunk is still added to the buffer until the memory overflows 533 * 534 * @param { string | Uint8Array } [chunk] - Data to be written. 535 * @param { string } [encoding] - Encoding type. 536 * @param { Function } [callback] - Callback after writing. 537 * @returns { boolean } Write success returns true, write failure returns false. 538 * @throws { BusinessError } 401 - An input parameter is invalid. 539 * @throws { BusinessError } 10200036 - The stream has been ended. 540 * @throws { BusinessError } 10200037 - The callback is invoked multiple times consecutively. 541 * @throws { BusinessError } 10200039 - The doTransform method has not been implemented for a class that inherits from Transform. 542 * @syscap SystemCapability.Utils.Lang 543 * @crossplatform 544 * @since 12 545 */ 546 write(chunk?: string | Uint8Array, encoding?: string, callback?: Function): boolean; 547 /** 548 * Write the last chunk to Writable. 549 * 550 * @param { string | Uint8Array } [chunk] - Data to be written. 551 * @param { string } [encoding] - Encoding type. 552 * @param { Function } [callback] - Callback after writing. 553 * @returns { Writable } Returns the Writable object. 554 * @throws { BusinessError } 401 - An input parameter is invalid. 555 * @throws { BusinessError } 10200039 - The doTransform method has not been implemented for a class that inherits from Transform. 556 * @syscap SystemCapability.Utils.Lang 557 * @crossplatform 558 * @since 12 559 */ 560 end(chunk?: string | Uint8Array, encoding?: string, callback?: Function): Writable; 561 /** 562 * Set the default encoding mode. 563 * 564 * @param { string } [encoding] - Encoding type.Default: utf8. 565 * @returns { boolean } Setting successful returns true, setting failed returns false. 566 * @throws { BusinessError } 401 - if the input parameters are invalid. 567 * @syscap SystemCapability.Utils.Lang 568 * @crossplatform 569 * @since 12 570 */ 571 setDefaultEncoding(encoding?: string): boolean; 572 /** 573 * After the call, all Write operations will be forced to write to the buffer instead of being flushed. 574 * 575 * @returns { boolean } Setting successful returns true, setting failed returns false. 576 * @syscap SystemCapability.Utils.Lang 577 * @crossplatform 578 * @since 12 579 */ 580 cork(): boolean; 581 /** 582 * After calling, flush all buffers. 583 * 584 * @returns { boolean } Setting successful returns true, setting failed returns false. 585 * @syscap SystemCapability.Utils.Lang 586 * @crossplatform 587 * @since 12 588 */ 589 uncork(): boolean; 590 /** 591 * Implemented by subclass inheritance. The implementation logic of flushing chunks in the buffer must not be 592 * directly called. The call is controlled by Writable.write. 593 * 594 * @param { string | Uint8Array } [chunk] - Data to be written. 595 * @param { string } [encoding] - Encoding type. 596 * @param { Function } [callback] - Callback after writing. 597 * @throws { BusinessError } 401 - if the input parameters are invalid. 598 * @syscap SystemCapability.Utils.Lang 599 * @crossplatform 600 * @since 12 601 */ 602 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function): void; 603 /** 604 * The implementation logic of flushing chunks in the buffer in batches should not be actively called. 605 * The call is controlled by Writable.write. 606 * 607 * @param { string[] | Uint8Array[] } [chunks] - Data to be written. 608 * @param { Function } [callback] - Callback after writing. 609 * @throws { BusinessError } 401 - if the input parameters are invalid. 610 * @syscap SystemCapability.Utils.Lang 611 * @crossplatform 612 * @since 12 613 */ 614 doWritev(chunks: string[] | Uint8Array[], callback: Function): void; 615 /** 616 * Returns boolean indicating whether it is in ObjectMode. 617 * 618 * @type { boolean } 619 * @readonly 620 * @syscap SystemCapability.Utils.Lang 621 * @crossplatform 622 * @since 12 623 */ 624 readonly writableObjectMode: boolean; 625 /** 626 * Value of highWatermark. 627 * 628 * @type { number } 629 * @readonly 630 * @syscap SystemCapability.Utils.Lang 631 * @crossplatform 632 * @since 12 633 */ 634 readonly writableHighWatermark: number; 635 /** 636 * Is true if it is safe to call writable.write(), which means the stream has not been destroyed, error or end. 637 * 638 * @type { boolean } 639 * @readonly 640 * @syscap SystemCapability.Utils.Lang 641 * @crossplatform 642 * @since 12 643 */ 644 readonly writable: boolean; 645 /** 646 * Size of data that can be flushed, in bytes or objects. 647 * 648 * @type { number } 649 * @readonly 650 * @syscap SystemCapability.Utils.Lang 651 * @crossplatform 652 * @since 12 653 */ 654 readonly writableLength: number; 655 /** 656 * Number of times writable.uncork() needs to be called in order to fully uncork the stream. 657 * 658 * @type { number } 659 * @readonly 660 * @syscap SystemCapability.Utils.Lang 661 * @crossplatform 662 * @since 12 663 */ 664 readonly writableCorked: number; 665 /** 666 * Whether Writable.end has been called. 667 * 668 * @type { boolean } 669 * @readonly 670 * @syscap SystemCapability.Utils.Lang 671 * @crossplatform 672 * @since 12 673 */ 674 readonly writableEnded: boolean; 675 /** 676 * Whether Writable.end has been called and all buffers have been flushed. 677 * 678 * @type { boolean } 679 * @readonly 680 * @syscap SystemCapability.Utils.Lang 681 * @crossplatform 682 * @since 12 683 */ 684 readonly writableFinished: boolean; 685 } 686} 687export default stream;