@mtcute/core 0.27.3 → 0.27.4

package/highlevel/client.d.cts

@@ -2035,7 +2035,16 @@ export interface TelegramClient extends ITelegramClient {
      *
      * @param params  Download parameters
      */
-    downloadAsIterable(input: FileDownloadLocation, params?: FileDownloadParameters): AsyncIterableIterator<Uint8Array>;
+    downloadAsIterable(input: FileDownloadLocation, params?: FileDownloadParameters & {
+        /**
+         * A function to apply backpressure to the download.
+         *
+         * If the consumer isn't keeping up, the function is supposed to return a promise that resolves when the consumer is ready to receive more data.
+         *
+         * Note that this function will likely get called multiple times simultaneously, since the download is parallelized.
+         */
+        throttle?: (chunkSize: number) => MaybePromise<void>;
+    }): AsyncIterableIterator<Uint8Array>;
     /**
      * Download a remote file as a Node.js Readable stream.
      *
@@ -2045,14 +2054,25 @@ export interface TelegramClient extends ITelegramClient {
      */
     downloadAsNodeStream(location: FileDownloadLocation, params?: FileDownloadParameters): import('node:stream').Readable;
     /**
-     * Download a file and return it as a `@fuman/io` stream,
+     * Download a file and return it as a Web Stream,
      * streaming file contents.
      *
      * **Available**: ✅ both users and bots
      *
      * @param params  File download parameters
      */
-    downloadAsStream(location: FileDownloadLocation, params?: FileDownloadParameters): ReadableStream<Uint8Array>;
+    downloadAsStream(location: FileDownloadLocation, params?: FileDownloadParameters & {
+        /**
+         * If passed, the maximum number of bytes that can be buffered in the stream.
+         *
+         * If the consumer isn't keeping up, the stream will pause until the buffer is below this limit.
+         *
+         * Note that this parameter is not guaranteed to be strictly the maximum number of bytes
+         * buffered at once, since the underlying download is parallelized, and is treated merely as a hint.
+         * The actual number of bytes buffered at once can be as much as `partSize * numWorkers`
+         */
+        highWaterMark?: number;
+    }): ReadableStream<Uint8Array>;
     /**
      * Normalize a {@link InputFileLike} to `InputFile`,
      * uploading it if needed.

package/highlevel/client.d.ts

@@ -2035,7 +2035,16 @@ export interface TelegramClient extends ITelegramClient {
      *
      * @param params  Download parameters
      */
-    downloadAsIterable(input: FileDownloadLocation, params?: FileDownloadParameters): AsyncIterableIterator<Uint8Array>;
+    downloadAsIterable(input: FileDownloadLocation, params?: FileDownloadParameters & {
+        /**
+         * A function to apply backpressure to the download.
+         *
+         * If the consumer isn't keeping up, the function is supposed to return a promise that resolves when the consumer is ready to receive more data.
+         *
+         * Note that this function will likely get called multiple times simultaneously, since the download is parallelized.
+         */
+        throttle?: (chunkSize: number) => MaybePromise<void>;
+    }): AsyncIterableIterator<Uint8Array>;
     /**
      * Download a remote file as a Node.js Readable stream.
      *
@@ -2045,14 +2054,25 @@ export interface TelegramClient extends ITelegramClient {
      */
     downloadAsNodeStream(location: FileDownloadLocation, params?: FileDownloadParameters): import('node:stream').Readable;
     /**
-     * Download a file and return it as a `@fuman/io` stream,
+     * Download a file and return it as a Web Stream,
      * streaming file contents.
      *
      * **Available**: ✅ both users and bots
      *
      * @param params  File download parameters
      */
-    downloadAsStream(location: FileDownloadLocation, params?: FileDownloadParameters): ReadableStream<Uint8Array>;
+    downloadAsStream(location: FileDownloadLocation, params?: FileDownloadParameters & {
+        /**
+         * If passed, the maximum number of bytes that can be buffered in the stream.
+         *
+         * If the consumer isn't keeping up, the stream will pause until the buffer is below this limit.
+         *
+         * Note that this parameter is not guaranteed to be strictly the maximum number of bytes
+         * buffered at once, since the underlying download is parallelized, and is treated merely as a hint.
+         * The actual number of bytes buffered at once can be as much as `partSize * numWorkers`
+         */
+        highWaterMark?: number;
+    }): ReadableStream<Uint8Array>;
     /**
      * Normalize a {@link InputFileLike} to `InputFile`,
      * uploading it if needed.

package/highlevel/methods/files/download-iterable.cjs

@@ -121,6 +121,10 @@ async function* downloadAsIterable(client, input, params) {
     if (ended) {
       return;
     }
+    const throttlePromise = params?.throttle?.(chunkSize);
+    if (throttlePromise) {
+      await throttlePromise;
+    }
     try {
       result = await client.call(
         {

package/highlevel/methods/files/download-iterable.d.cts

@@ -1,3 +1,4 @@
+import { MaybePromise } from '@fuman/utils';
 import { ITelegramClient } from '../../client.types.js';
 import { FileDownloadLocation, FileDownloadParameters } from '../../types/index.js';
 import { tl } from '@mtcute/tl';
@@ -13,4 +14,13 @@ export declare function _normalizeFileDownloadLocation(client: ITelegramClient,
  *
  * @param params  Download parameters
  */
-export declare function downloadAsIterable(client: ITelegramClient, input: FileDownloadLocation, params?: FileDownloadParameters): AsyncIterableIterator<Uint8Array>;
+export declare function downloadAsIterable(client: ITelegramClient, input: FileDownloadLocation, params?: FileDownloadParameters & {
+    /**
+     * A function to apply backpressure to the download.
+     *
+     * If the consumer isn't keeping up, the function is supposed to return a promise that resolves when the consumer is ready to receive more data.
+     *
+     * Note that this function will likely get called multiple times simultaneously, since the download is parallelized.
+     */
+    throttle?: (chunkSize: number) => MaybePromise<void>;
+}): AsyncIterableIterator<Uint8Array>;

package/highlevel/methods/files/download-iterable.d.ts

@@ -1,3 +1,4 @@
+import { MaybePromise } from '@fuman/utils';
 import { ITelegramClient } from '../../client.types.js';
 import { FileDownloadLocation, FileDownloadParameters } from '../../types/index.js';
 import { tl } from '@mtcute/tl';
@@ -13,4 +14,13 @@ export declare function _normalizeFileDownloadLocation(client: ITelegramClient,
  *
  * @param params  Download parameters
  */
-export declare function downloadAsIterable(client: ITelegramClient, input: FileDownloadLocation, params?: FileDownloadParameters): AsyncIterableIterator<Uint8Array>;
+export declare function downloadAsIterable(client: ITelegramClient, input: FileDownloadLocation, params?: FileDownloadParameters & {
+    /**
+     * A function to apply backpressure to the download.
+     *
+     * If the consumer isn't keeping up, the function is supposed to return a promise that resolves when the consumer is ready to receive more data.
+     *
+     * Note that this function will likely get called multiple times simultaneously, since the download is parallelized.
+     */
+    throttle?: (chunkSize: number) => MaybePromise<void>;
+}): AsyncIterableIterator<Uint8Array>;

package/highlevel/methods/files/download-iterable.js

@@ -114,6 +114,10 @@ async function* downloadAsIterable(client, input, params) {
     if (ended) {
       return;
     }
+    const throttlePromise = params?.throttle?.(chunkSize);
+    if (throttlePromise) {
+      await throttlePromise;
+    }
     try {
       result = await client.call(
         {

package/highlevel/methods/files/download-stream.cjs

@@ -5,6 +5,7 @@ if (typeof globalThis !== "undefined" && !globalThis._MTCUTE_CJS_DEPRECATION_WAR
 }
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("@fuman/utils");
 const downloadIterable = require("./download-iterable.cjs");
 const fileLocation = require("../../types/files/file-location.cjs");
 function downloadAsStream(client, location, params) {
@@ -23,18 +24,31 @@ function downloadAsStream(client, location, params) {
       cancel.abort();
     });
   }
+  const backpressureCv = new utils.ConditionVariable();
   return new ReadableStream({
     start(controller) {
       (async () => {
+        const params_ = params ?? {};
+        params_.throttle = () => {
+          if (controller.desiredSize != null && controller.desiredSize <= 0) {
+            return backpressureCv.wait();
+          }
+        };
         for await (const chunk of downloadIterable.downloadAsIterable(client, location, params)) {
           controller.enqueue(chunk);
         }
         controller.close();
       })().catch((e) => controller.error(e));
     },
+    pull() {
+      backpressureCv.notify();
+    },
     cancel() {
       cancel.abort();
     }
+  }, {
+    highWaterMark: params?.highWaterMark,
+    size: (chunk) => chunk?.length ?? 0
   });
 }
 exports.downloadAsStream = downloadAsStream;

package/highlevel/methods/files/download-stream.d.cts

@@ -1,9 +1,20 @@
 import { ITelegramClient } from '../../client.types.js';
 import { FileDownloadLocation, FileDownloadParameters } from '../../types/index.js';
 /**
- * Download a file and return it as a `@fuman/io` stream,
+ * Download a file and return it as a Web Stream,
  * streaming file contents.
  *
  * @param params  File download parameters
  */
-export declare function downloadAsStream(client: ITelegramClient, location: FileDownloadLocation, params?: FileDownloadParameters): ReadableStream<Uint8Array>;
+export declare function downloadAsStream(client: ITelegramClient, location: FileDownloadLocation, params?: FileDownloadParameters & {
+    /**
+     * If passed, the maximum number of bytes that can be buffered in the stream.
+     *
+     * If the consumer isn't keeping up, the stream will pause until the buffer is below this limit.
+     *
+     * Note that this parameter is not guaranteed to be strictly the maximum number of bytes
+     * buffered at once, since the underlying download is parallelized, and is treated merely as a hint.
+     * The actual number of bytes buffered at once can be as much as `partSize * numWorkers`
+     */
+    highWaterMark?: number;
+}): ReadableStream<Uint8Array>;

package/highlevel/methods/files/download-stream.d.ts

@@ -1,9 +1,20 @@
 import { ITelegramClient } from '../../client.types.js';
 import { FileDownloadLocation, FileDownloadParameters } from '../../types/index.js';
 /**
- * Download a file and return it as a `@fuman/io` stream,
+ * Download a file and return it as a Web Stream,
  * streaming file contents.
  *
  * @param params  File download parameters
  */
-export declare function downloadAsStream(client: ITelegramClient, location: FileDownloadLocation, params?: FileDownloadParameters): ReadableStream<Uint8Array>;
+export declare function downloadAsStream(client: ITelegramClient, location: FileDownloadLocation, params?: FileDownloadParameters & {
+    /**
+     * If passed, the maximum number of bytes that can be buffered in the stream.
+     *
+     * If the consumer isn't keeping up, the stream will pause until the buffer is below this limit.
+     *
+     * Note that this parameter is not guaranteed to be strictly the maximum number of bytes
+     * buffered at once, since the underlying download is parallelized, and is treated merely as a hint.
+     * The actual number of bytes buffered at once can be as much as `partSize * numWorkers`
+     */
+    highWaterMark?: number;
+}): ReadableStream<Uint8Array>;

package/highlevel/methods/files/download-stream.js

@@ -1,3 +1,4 @@
+import { ConditionVariable } from "@fuman/utils";
 import { downloadAsIterable } from "./download-iterable.js";
 import { FileLocation as FileLocation$1 } from "../../types/files/file-location.js";
 function downloadAsStream(client, location, params) {
@@ -16,18 +17,31 @@ function downloadAsStream(client, location, params) {
       cancel.abort();
     });
   }
+  const backpressureCv = new ConditionVariable();
   return new ReadableStream({
     start(controller) {
       (async () => {
+        const params_ = params ?? {};
+        params_.throttle = () => {
+          if (controller.desiredSize != null && controller.desiredSize <= 0) {
+            return backpressureCv.wait();
+          }
+        };
         for await (const chunk of downloadAsIterable(client, location, params)) {
           controller.enqueue(chunk);
         }
         controller.close();
       })().catch((e) => controller.error(e));
     },
+    pull() {
+      backpressureCv.notify();
+    },
     cancel() {
       cancel.abort();
     }
+  }, {
+    highWaterMark: params?.highWaterMark,
+    size: (chunk) => chunk?.length ?? 0
   });
 }
 export {

package/highlevel/types/media/document-utils.cjs

@@ -28,7 +28,7 @@ function parseDocument(doc, media) {
     switch (attr._) {
       case "documentAttributeAudio":
         if (attr.voice) {
-          return new voice.Voice(doc, attr);
+          return new voice.Voice(doc, attr, media);
         }
         return new audio.Audio(doc, attr);
       case "documentAttributeVideo":

package/highlevel/types/media/document-utils.js

@@ -21,7 +21,7 @@ function parseDocument(doc, media) {
     switch (attr._) {
       case "documentAttributeAudio":
         if (attr.voice) {
-          return new Voice$2(doc, attr);
+          return new Voice$2(doc, attr, media);
         }
         return new Audio$2(doc, attr);
       case "documentAttributeVideo":

package/highlevel/types/media/voice.cjs

@@ -11,9 +11,10 @@ const voiceUtils = require("../../utils/voice-utils.cjs");
 const document = require("./document.cjs");
 const inspectable = require("../../utils/inspectable.cjs");
 class Voice extends document.RawDocument {
-  constructor(doc, attr) {
+  constructor(doc, attr, media) {
     super(doc);
     this.attr = attr;
+    this.media = media;
   }
   type = "voice";
   _fileIdType() {
@@ -34,6 +35,10 @@ class Voice extends document.RawDocument {
   get waveform() {
     return voiceUtils.decodeWaveform(this.attr.waveform);
   }
+  /** For self-destructing voice notes, TTL in seconds */
+  get ttlSeconds() {
+    return this.media?.ttlSeconds ?? null;
+  }
 }
 const Voice$1 = /* @__PURE__ */ memoize.memoizeGetters(Voice, ["fileName", "thumbnails", "fileId", "uniqueFileId", "waveform"]);
 const Voice$2 = /* @__PURE__ */ inspectable.makeInspectable(Voice$1, ["fileSize", "dcId"], ["inputMedia", "inputDocument", "waveform"]);

package/highlevel/types/media/voice.d.cts

@@ -6,9 +6,10 @@ import { RawDocument } from './document.js';
  */
 export declare class Voice extends RawDocument {
     readonly attr: tl.RawDocumentAttributeAudio;
+    readonly media?: tl.RawMessageMediaDocument | undefined;
     readonly type: "voice";
     protected _fileIdType(): tdFileId.FileType;
-    constructor(doc: tl.RawDocument, attr: tl.RawDocumentAttributeAudio);
+    constructor(doc: tl.RawDocument, attr: tl.RawDocumentAttributeAudio, media?: tl.RawMessageMediaDocument | undefined);
     /**
      * Duration of the voice note in seconds.
      */
@@ -20,4 +21,6 @@ export declare class Voice extends RawDocument {
      * usually has length of 100
      */
     get waveform(): number[];
+    /** For self-destructing voice notes, TTL in seconds */
+    get ttlSeconds(): number | null;
 }

package/highlevel/types/media/voice.d.ts

@@ -6,9 +6,10 @@ import { RawDocument } from './document.js';
  */
 export declare class Voice extends RawDocument {
     readonly attr: tl.RawDocumentAttributeAudio;
+    readonly media?: tl.RawMessageMediaDocument | undefined;
     readonly type: "voice";
     protected _fileIdType(): tdFileId.FileType;
-    constructor(doc: tl.RawDocument, attr: tl.RawDocumentAttributeAudio);
+    constructor(doc: tl.RawDocument, attr: tl.RawDocumentAttributeAudio, media?: tl.RawMessageMediaDocument | undefined);
     /**
      * Duration of the voice note in seconds.
      */
@@ -20,4 +21,6 @@ export declare class Voice extends RawDocument {
      * usually has length of 100
      */
     get waveform(): number[];
+    /** For self-destructing voice notes, TTL in seconds */
+    get ttlSeconds(): number | null;
 }

package/highlevel/types/media/voice.js

@@ -4,9 +4,10 @@ import { decodeWaveform } from "../../utils/voice-utils.js";
 import { RawDocument } from "./document.js";
 import { makeInspectable } from "../../utils/inspectable.js";
 class Voice extends RawDocument {
-  constructor(doc, attr) {
+  constructor(doc, attr, media) {
     super(doc);
     this.attr = attr;
+    this.media = media;
   }
   type = "voice";
   _fileIdType() {
@@ -27,6 +28,10 @@ class Voice extends RawDocument {
   get waveform() {
     return decodeWaveform(this.attr.waveform);
   }
+  /** For self-destructing voice notes, TTL in seconds */
+  get ttlSeconds() {
+    return this.media?.ttlSeconds ?? null;
+  }
 }
 const Voice$1 = /* @__PURE__ */ memoizeGetters(Voice, ["fileName", "thumbnails", "fileId", "uniqueFileId", "waveform"]);
 const Voice$2 = /* @__PURE__ */ makeInspectable(Voice$1, ["fileSize", "dcId"], ["inputMedia", "inputDocument", "waveform"]);

package/network/network-manager.cjs

@@ -225,7 +225,7 @@ class NetworkManager {
       _: "initConnection",
       deviceModel,
       systemVersion: "1.0",
-      appVersion: "0.27.3",
+      appVersion: "0.27.4",
       systemLangCode: "en",
       langPack: "",
       // "langPacks are for official apps only"

package/network/network-manager.js

@@ -218,7 +218,7 @@ class NetworkManager {
       _: "initConnection",
       deviceModel,
       systemVersion: "1.0",
-      appVersion: "0.27.3",
+      appVersion: "0.27.4",
       systemLangCode: "en",
       langPack: "",
       // "langPacks are for official apps only"

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@mtcute/core",
     "type": "module",
-    "version": "0.27.3",
+    "version": "0.27.4",
     "description": "Type-safe library for MTProto (Telegram API)",
     "license": "MIT",
     "scripts": {},