#353, #392 Form data enhancements (#398)

* eslint improvements

* #388: removing ~ from dist folder

* v5.2.1

* new form-data usage PoC

* code formatting and fixes

* test fixes

Author: MrRefactoring

src/node/createAttachmentFromPath.ts

@@ -0,0 +1,18 @@
+import { open } from 'fs/promises';
+import { basename } from 'path';
+import type { Attachment } from '../version2/parameters';
+
+export async function createAttachmentFromPath(path: string, contentType?: string): Promise<Attachment> {
+  const filename = basename(path);
+
+  const fileHandle = await open(path, 'r');
+
+  const { size } = await fileHandle.stat();
+
+  return {
+    filename,
+    content: fileHandle.readableWebStream(),
+    contentType,
+    contentLength: size,
+  };
+}

src/services/formDataService/formDataService.ts

@@ -0,0 +1,78 @@
+import mime from 'mime';
+import type { ReadableStream as ReadableNodeStream } from 'node:stream/web';
+
+type FormDataValue = string | Blob | ArrayBuffer | ReadableStream | ReadableNodeStream;
+
+class FileWithSize extends File {
+  size: number = 0;
+}
+
+interface AppendOptions {
+  contentLength?: number;
+  contentType?: string;
+}
+
+export class FormDataService {
+  formData: FormData;
+
+  constructor() {
+    this.formData = new FormData();
+  }
+
+  async append(value: FormDataValue, filename: string, options: AppendOptions = {}) {
+    const blobOptions = {
+      type: options.contentType ?? mime.getType(filename) ?? undefined,
+    };
+
+    if (typeof value === 'string') {
+      this.formData.append('file', new Blob([value], blobOptions), filename);
+    } else if (value instanceof Blob) {
+      this.formData.append('file', new Blob([value], blobOptions), filename);
+    } else if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+      this.formData.append('file', new Blob([value], blobOptions), filename);
+    } else if (value instanceof ReadableStream) {
+      const file = new FileWithSize([], filename, blobOptions);
+
+      if (options.contentLength != undefined) {
+        file.size = options.contentLength;
+        file.stream = () => value as ReadableStream;
+      } else {
+        const [streamForSize, streamForContent] = value.tee();
+
+        file.size = await this.getStreamSize(streamForSize);
+        file.stream = () => streamForContent as ReadableStream;
+      }
+
+      this.formData.append('file', file);
+    } else {
+      throw new Error('Invalid value'); // todo error handling
+    }
+  }
+
+  private async getStreamSize(stream: ReadableStream | ReadableNodeStream): Promise<number> {
+    let totalSize = 0;
+    const reader = stream.getReader();
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      if (value instanceof Uint8Array) {
+        totalSize += value.length;
+      } else if (typeof value === 'string') {
+        totalSize += new TextEncoder().encode(value).length;
+      } else if (value instanceof Blob) {
+        totalSize += value.size;
+      } else if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+        totalSize += value.byteLength;
+      } else if (value === null || value === undefined) {
+        continue;
+      } else {
+        throw new Error(`Unsupported value type: ${typeof value}`);
+      }
+    }
+
+    return totalSize;
+  }
+}

src/services/formDataService/index.ts

@@ -0,0 +1 @@
+export * from './formDataService';

src/version2/issueAttachments.ts

@@ -1,10 +1,9 @@
-import type { Mime } from 'mime';
-import mime from 'mime';
 import type * as Models from './models';
 import type * as Parameters from './parameters';
 import type { Client } from '../clients';
 import type { Callback } from '../callback';
 import type { Request } from '../request';
+import { FormDataService } from '../services/formDataService';
 
 export class IssueAttachments {
   constructor(private client: Client) {}
@@ -121,6 +120,7 @@ export class IssueAttachments {
   async getAttachmentThumbnail<T = Buffer>(parameters: Parameters.GetAttachmentThumbnail | string): Promise<void | T> {
     const id = typeof parameters === 'string' ? parameters : parameters.id;
 
+    // todo
     const config: Request = {
       url: `/rest/api/2/attachment/thumbnail/${id}`,
       method: 'GET',
@@ -381,112 +381,29 @@ export class IssueAttachments {
    */
   async addAttachment<T = Models.Attachment[]>(parameters: Parameters.AddAttachment, callback?: never): Promise<T>;
   async addAttachment<T = Models.Attachment[]>(parameters: Parameters.AddAttachment): Promise<void | T> {
-    const formData = new FormData();
+    const formDataService = new FormDataService();
     const attachments = Array.isArray(parameters.attachment) ? parameters.attachment : [parameters.attachment];
 
-    // eslint-disable-next-line @typescript-eslint/consistent-type-imports
-    let Readable: typeof import('stream').Readable | undefined;
-
-    if (typeof window === 'undefined') {
-      const { Readable: NodeReadable } = await import('stream');
-
-      Readable = NodeReadable;
-    }
-
-    for await (const attachment of attachments) {
-      const file = await this._convertToFile(attachment, mime, Readable);
-
-      if (!(file instanceof File || file instanceof Blob)) {
-        throw new Error(`Unsupported file type for attachment: ${typeof file}`);
-      }
-
-      formData.append('file', file, attachment.filename);
-    }
+    await Promise.all(
+      attachments.map(attachment =>
+        formDataService.append(attachment.content, attachment.filename, {
+          contentLength: attachment.contentLength,
+          contentType: attachment.contentType,
+        }),
+      ),
+    );
 
     const config: Request = {
       url: `/rest/api/2/issue/${parameters.issueIdOrKey}/attachments`,
       method: 'POST',
       headers: {
         'X-Atlassian-Token': 'no-check',
-        // 'Content-Type': 'multipart/form-data',
       },
-      body: formData,
-      // maxBodyLength: Infinity, // todo
-      // maxContentLength: Infinity, // todo
+      body: formDataService.formData,
+      // maxBodyLength: Infinity, // todo needed?
+      // maxContentLength: Infinity, // todo needed?
     };
 
     return this.client.sendRequest(config);
   }
-
-  private async _convertToFile(
-    attachment: Parameters.Attachment,
-    mime: Mime,
-    // eslint-disable-next-line @typescript-eslint/consistent-type-imports
-    Readable?: typeof import('stream').Readable,
-  ): Promise<File | Blob> {
-    const mimeType = attachment.mimeType ?? (mime.getType(attachment.filename) || undefined);
-
-    if (attachment.file instanceof Blob || attachment.file instanceof File) {
-      return attachment.file;
-    }
-
-    if (typeof attachment.file === 'string') {
-      return new File([attachment.file], attachment.filename, { type: mimeType });
-    }
-
-    if (Readable && attachment.file instanceof Readable) {
-      return this._streamToBlob(attachment.file, attachment.filename, mimeType);
-    }
-
-    if (attachment.file instanceof ReadableStream) {
-      return this._streamToBlob(attachment.file, attachment.filename, mimeType);
-    }
-
-    if (ArrayBuffer.isView(attachment.file) || attachment.file instanceof ArrayBuffer) {
-      return new File([attachment.file], attachment.filename, { type: mimeType });
-    }
-
-    throw new Error('Unsupported attachment file type.');
-  }
-
-  private async _streamToBlob(
-    // eslint-disable-next-line @typescript-eslint/consistent-type-imports
-    stream: import('stream').Readable | ReadableStream,
-    filename: string,
-    mimeType?: string,
-  ): Promise<File> {
-    if (typeof window === 'undefined' && stream instanceof (await import('stream')).Readable) {
-      return new Promise((resolve, reject) => {
-        const chunks: Uint8Array[] = [];
-
-        stream.on('data', chunk => chunks.push(chunk));
-        stream.on('end', () => {
-          const blob = new Blob(chunks, { type: mimeType });
-
-          resolve(new File([blob], filename, { type: mimeType }));
-        });
-        stream.on('error', reject);
-      });
-    }
-
-    if (stream instanceof ReadableStream) {
-      const reader = stream.getReader();
-      const chunks: Uint8Array[] = [];
-
-      let done = false;
-
-      while (!done) {
-        const { value, done: streamDone } = await reader.read();
-
-        if (value) chunks.push(value);
-        done = streamDone;
-      }
-
-      const blob = new Blob(chunks, { type: mimeType });
-
-      return new File([blob], filename, { type: mimeType });
-    }
-
-    throw new Error('Unsupported stream type.');
-  }
 }

src/version2/parameters/addAttachment.ts

@@ -1,4 +1,4 @@
-import type { Readable } from 'node:stream';
+import type { ReadableStream as ReadableNodeStream } from 'node:stream/web';
 
 /**
  * Represents an attachment to be added to an issue.
@@ -13,6 +13,7 @@ import type { Readable } from 'node:stream';
  *   ```
  */
 export interface Attachment {
+  // todo JSDoc
   /**
    * The name of the attachment file.
    *
@@ -37,22 +38,20 @@ export interface Attachment {
    *   const fileContent = fs.readFileSync('./document.pdf');
    *   ```
    */
-  file: Buffer | ReadableStream | Readable | string | Blob | File;
+  content: ArrayBuffer | ReadableStream | ReadableNodeStream | string | Blob;
 
   /**
-   * Optional MIME type of the attachment. Example values include:
-   *
-   * - 'application/pdf'
-   * - 'image/png'
+   * Optional MIME type of the attachment.
    *
    * If not provided, the MIME type will be automatically detected based on the filename.
    *
    * @example
    *   ```typescript
-   *   const mimeType = 'application/pdf';
+   *   'application/pdf'
    *   ```
    */
-  mimeType?: string;
+  contentType?: string;
+  contentLength?: number; // todo JSDoc
 }
 
 /**
@@ -99,5 +98,5 @@ export interface AddAttachment {
    *   ];
    *   ```
    */
-  attachment: Attachment | Attachment[];
+  attachment: Attachment | Attachment[]; // todo JSDoc
 }