Implement cleaner API names and streaming downloads for iOS

Agent-Logs-Url: https://github.com/nativescript-community/https/sessions/99200ca0-c02e-437d-bbdc-d3c5f6f221c3

Co-authored-by: farfromrefug <655344+farfromrefug@users.noreply.github.com>

Author: Copilot

packages/https/platforms/ios/src/AlamofireWrapper.swift

@@ -60,7 +60,8 @@ public class AlamofireWrapper: NSObject {
 
     // MARK: - Request Methods
 
-    @objc public func dataTaskWithHTTPMethodURLStringParametersHeadersUploadProgressDownloadProgressSuccessFailure(
+    // Clean API: New shorter method name
+    @objc public func request(
         _ method: String,
         _ urlString: String,
         _ parameters: NSDictionary?,
@@ -149,9 +150,9 @@ public class AlamofireWrapper: NSObject {
 
     // MARK: - Multipart Form Data
 
-    @objc public func POSTParametersHeadersConstructingBodyWithBlockProgressSuccessFailure(
+    // Clean API: New shorter method name for multipart upload
+    @objc public func uploadMultipart(
         _ urlString: String,
-        _ parameters: NSDictionary?,
         _ headers: NSDictionary?,
         _ constructingBodyWithBlock: @escaping (MultipartFormDataWrapper) -> Void,
         _ progress: ((Progress) -> Void)?,
@@ -233,7 +234,8 @@ public class AlamofireWrapper: NSObject {
 
     // MARK: - Upload Tasks
 
-    @objc public func uploadTaskWithRequestFromFileProgressCompletionHandler(
+    // Clean API: Upload file
+    @objc public func uploadFile(
         _ request: URLRequest,
         _ fileURL: URL,
         _ progress: ((Progress) -> Void)?,
@@ -280,7 +282,8 @@ public class AlamofireWrapper: NSObject {
         return afRequest.task
     }
 
-    @objc public func uploadTaskWithRequestFromDataProgressCompletionHandler(
+    // Clean API: Upload data
+    @objc public func uploadData(
         _ request: URLRequest,
         _ bodyData: Data,
         _ progress: ((Progress) -> Void)?,
@@ -327,6 +330,82 @@ public class AlamofireWrapper: NSObject {
         return afRequest.task
     }
 
+    // MARK: - Download Tasks
+    
+    // Clean API: Download file with streaming to disk (optimized, no memory loading)
+    @objc public func downloadToFile(
+        _ urlString: String,
+        _ destinationPath: String,
+        _ headers: NSDictionary?,
+        _ progress: ((Progress) -> Void)?,
+        _ completionHandler: @escaping (URLResponse?, String?, Error?) -> Void
+    ) -> URLSessionDownloadTask? {
+        
+        guard let url = URL(string: urlString) else {
+            let error = NSError(domain: "AlamofireWrapper", code: -1, userInfo: [NSLocalizedDescriptionKey: "Invalid URL"])
+            completionHandler(nil, nil, error)
+            return nil
+        }
+        
+        var request: URLRequest
+        do {
+            request = try requestSerializer.createRequest(
+                url: url,
+                method: .get,
+                parameters: nil,
+                headers: headers
+            )
+        } catch {
+            completionHandler(nil, nil, error)
+            return nil
+        }
+        
+        // Create destination closure that moves file to the specified path
+        let destination: DownloadRequest.Destination = { temporaryURL, response in
+            let destinationURL = URL(fileURLWithPath: destinationPath)
+            
+            // Ensure parent directory exists
+            let parentDirectory = destinationURL.deletingLastPathComponent()
+            try? FileManager.default.createDirectory(at: parentDirectory, withIntermediateDirectories: true, attributes: nil)
+            
+            return (destinationURL, [.removePreviousFile, .createIntermediateDirectories])
+        }
+        
+        var downloadRequest = session.download(request, to: destination)
+        
+        // Apply server trust evaluation if security policy is set
+        if let secPolicy = securityPolicy, let host = url.host {
+            downloadRequest = downloadRequest.validate { _, response, _ in
+                do {
+                    try secPolicy.evaluate(response.serverTrust!, forHost: host)
+                    return .success(Void())
+                } catch {
+                    return .failure(error)
+                }
+            }
+        }
+        
+        // Download progress
+        if let progress = progress {
+            downloadRequest = downloadRequest.downloadProgress { progressInfo in
+                progress(progressInfo)
+            }
+        }
+        
+        // Response handling
+        downloadRequest.response(queue: .main) { response in
+            if let error = response.error {
+                completionHandler(response.response, nil, error)
+                return
+            }
+            
+            // Return the destination path on success
+            completionHandler(response.response, destinationPath, nil)
+        }
+        
+        return downloadRequest.task as? URLSessionDownloadTask
+    }
+    
     // MARK: - Helper Methods
 
     private func createNSError(from error: Error, response: HTTPURLResponse?, data: Data?) -> NSError {

src/https/request.d.ts

@@ -71,6 +71,12 @@ export interface HttpsRequestOptions extends HttpRequestOptions {
      * default to true. Android and iOS only store cookies in memory! it will be cleared after an app restart
      */
     cookiesEnabled?: boolean;
+    
+    /**
+     * iOS: When set, downloads will be streamed directly to the specified file path without loading into memory.
+     * This is more memory efficient for large files.
+     */
+    downloadFilePath?: string;
 }
 
 export interface HttpsResponse<T = any> {

src/https/request.ios.ts

@@ -413,6 +413,58 @@ export function createRequest(opts: HttpsRequestOptions, useLegacy: boolean = tr
         },
         cancel: () => task && task.cancel(),
         run(resolve, reject) {
+            // Handle streaming download if downloadFilePath is specified
+            if (opts.downloadFilePath && opts.method === 'GET') {
+                const downloadTask = manager.downloadToFile(
+                    opts.url,
+                    opts.downloadFilePath,
+                    headers,
+                    progress,
+                    (response: NSURLResponse, filePath: string, error: NSError) => {
+                        clearRunningRequest();
+                        if (error) {
+                            reject(error);
+                            return;
+                        }
+                        
+                        const httpResponse = response as NSHTTPURLResponse;
+                        const contentLength = httpResponse?.expectedContentLength || 0;
+                        
+                        // Create a File object pointing to the downloaded file
+                        const file = File.fromPath(filePath);
+                        
+                        let getHeaders = () => ({});
+                        const sendi = {
+                            content: useLegacy ? { toFile: () => Promise.resolve(file) } : filePath,
+                            contentLength,
+                            get headers() {
+                                return getHeaders();
+                            }
+                        } as any as HttpsResponse;
+                        
+                        if (!Utils.isNullOrUndefined(httpResponse)) {
+                            sendi.statusCode = httpResponse.statusCode;
+                            getHeaders = function () {
+                                const dict = httpResponse.allHeaderFields;
+                                if (dict) {
+                                    const headers = {};
+                                    dict.enumerateKeysAndObjectsUsingBlock((k, v) => (headers[k] = v));
+                                    return headers;
+                                }
+                                return null;
+                            };
+                        }
+                        resolve(sendi);
+                    }
+                );
+                
+                task = downloadTask as any;
+                if (task && tag) {
+                    runningRequests[tag] = task;
+                }
+                return;
+            }
+            
             const success = function (task: NSURLSessionDataTask, data?: any) {
                 clearRunningRequest();
                 // TODO: refactor this code with failure one.
@@ -455,9 +507,8 @@ export function createRequest(opts: HttpsRequestOptions, useLegacy: boolean = tr
                     case 'POST':
                         // we need to remove the Content-Type or the boundary wont be set correctly
                         headers.removeObjectForKey('Content-Type');
-                        task = manager.POSTParametersHeadersConstructingBodyWithBlockProgressSuccessFailure(
+                        task = manager.uploadMultipart(
                             opts.url,
-                            null,
                             headers,
                             (formData) => {
                                 (opts.body as HttpsFormDataParam[]).forEach((param) => {
@@ -502,7 +553,7 @@ export function createRequest(opts: HttpsRequestOptions, useLegacy: boolean = tr
                     Object.keys(heads).forEach((k) => {
                         request.setValueForHTTPHeaderField(heads[k], k);
                     });
-                    task = manager.uploadTaskWithRequestFromFileProgressCompletionHandler(
+                    task = manager.uploadFile(
                         request,
                         NSURL.fileURLWithPath(opts.body.path),
                         progress,
@@ -530,7 +581,7 @@ export function createRequest(opts: HttpsRequestOptions, useLegacy: boolean = tr
                     Object.keys(heads).forEach((k) => {
                         request.setValueForHTTPHeaderField(heads[k], k);
                     });
-                    task = manager.uploadTaskWithRequestFromDataProgressCompletionHandler(request, data, progress, (response: NSURLResponse, responseObject: any, error: NSError) => {
+                    task = manager.uploadData(request, data, progress, (response: NSURLResponse, responseObject: any, error: NSError) => {
                         if (error) {
                             failure(task, error);
                         } else {
@@ -550,7 +601,7 @@ export function createRequest(opts: HttpsRequestOptions, useLegacy: boolean = tr
                 } else if (typeof opts.content === 'string') {
                     dict = NSJSONSerialization.JSONObjectWithDataOptionsError(NSString.stringWithString(opts.content).dataUsingEncoding(NSUTF8StringEncoding), 0 as any);
                 }
-                task = manager.dataTaskWithHTTPMethodURLStringParametersHeadersUploadProgressDownloadProgressSuccessFailure(opts.method, opts.url, dict, headers, progress, progress, success, failure);
+                task = manager.request(opts.method, opts.url, dict, headers, progress, progress, success, failure);
                 task.resume();
             }
             if (task && tag) {

src/https/typings/objc!AlamofireWrapper.d.ts

@@ -12,7 +12,8 @@ declare class AlamofireWrapper extends NSObject {
 
     setDataTaskWillCacheResponseBlock(block: (session: NSURLSession, task: NSURLSessionDataTask, cacheResponse: NSCachedURLResponse) => NSCachedURLResponse): void;
 
-    dataTaskWithHTTPMethodURLStringParametersHeadersUploadProgressDownloadProgressSuccessFailure(
+    // New clean API methods
+    request(
         method: string,
         urlString: string,
         parameters: NSDictionary<string, any>,
@@ -23,29 +24,36 @@ declare class AlamofireWrapper extends NSObject {
         failure: (task: NSURLSessionDataTask, error: NSError) => void
     ): NSURLSessionDataTask;
 
-    POSTParametersHeadersConstructingBodyWithBlockProgressSuccessFailure(
+    uploadMultipart(
         urlString: string,
-        parameters: NSDictionary<string, any>,
         headers: NSDictionary<string, any>,
         constructingBodyWithBlock: (formData: MultipartFormDataWrapper) => void,
         progress: (progress: NSProgress) => void,
         success: (task: NSURLSessionDataTask, data: any) => void,
         failure: (task: NSURLSessionDataTask, error: NSError) => void
     ): NSURLSessionDataTask;
 
-    uploadTaskWithRequestFromFileProgressCompletionHandler(
+    uploadFile(
         request: NSMutableURLRequest,
         fileURL: NSURL,
         progress: (progress: NSProgress) => void,
         completionHandler: (response: NSURLResponse, responseObject: any, error: NSError) => void
     ): NSURLSessionDataTask;
 
-    uploadTaskWithRequestFromDataProgressCompletionHandler(
+    uploadData(
         request: NSMutableURLRequest,
         bodyData: NSData,
         progress: (progress: NSProgress) => void,
         completionHandler: (response: NSURLResponse, responseObject: any, error: NSError) => void
     ): NSURLSessionDataTask;
+    
+    downloadToFile(
+        urlString: string,
+        destinationPath: string,
+        headers: NSDictionary<string, any>,
+        progress: (progress: NSProgress) => void,
+        completionHandler: (response: NSURLResponse, filePath: string, error: NSError) => void
+    ): NSURLSessionDownloadTask;
 }
 
 declare class RequestSerializer extends NSObject {