Error -> RangeError for parameter checking errors; Documents and comments improve

README.md

@@ -1,10 +1,12 @@
-# Azure Storage SDK V10 for JavaScript
+# Azure Storage SDK for JavaScript
+
+* @azure/storage-blob [![npm version](https://badge.fury.io/js/%40azure%2Fstorage-blob.svg)](https://badge.fury.io/js/%40azure%2Fstorage-blob)
 
 ## Introduction
 
 This project provides a SDK in JavaScript that makes it easy to consume Microsoft Azure Storage services.
 
-Please note that this version of the SDK is a compete overhaul of the current [Azure Storage SDK for Node.js and JavaScript in Browsers](https://github.com/azure/azure-storage-node), and is based on the new Storage SDK architecture, also referred to as V10.
+Please note that this version of the SDK is a compete overhaul of the current [Azure Storage SDK for Node.js and JavaScript in Browsers](https://github.com/azure/azure-storage-node), and is based on the new Storage SDK architecture.
 
 ### Features
 
@@ -14,7 +16,7 @@ Please note that this version of the SDK is a compete overhaul of the current [A
   - Create/Read/List/Update/Delete Block Blobs
   - Create/Read/List/Update/Delete Page Blobs
   - Create/Read/List/Update/Delete Append Blobs
-- Features new to V10
+- Features new
   - Asynchronous I/O for all operations using the async methods
   - HttpPipeline which enables a high degree of per-request configurability
   - 1-to-1 correlation with the Storage REST API for clarity and simplicity
@@ -53,9 +55,9 @@ const Azure = require("@azure/storage-blob");
 
 ### JavaScript Bundle
 
-To use the SDK in the browsers, simply add a script tag to your HTML pages pointing to the downloaded JS bundle file(s):
+To use the SDK with JS bundle in the browsers, simply add a script tag to your HTML pages pointing to the downloaded JS bundle file(s):
 
-```
+```html
 <script src="https://mydomain/azure-storage.blob.min.js"></script>
 ```
 

blob/README.md

@@ -1,10 +1,12 @@
-# Azure Storage SDK V10 for JavaScript - Blob
+# Azure Storage SDK for JavaScript - Blob
+
+[![npm version](https://badge.fury.io/js/%40azure%2Fstorage-blob.svg)](https://badge.fury.io/js/%40azure%2Fstorage-blob)
 
 ## Introduction
 
 This project provides a SDK in JavaScript that makes it easy to consume Microsoft Azure Storage services.
 
-Please note that this version of the SDK is a compete overhaul of the current [Azure Storage SDK for Node.js and JavaScript in Browsers](https://github.com/azure/azure-storage-node), and is based on the new Storage SDK architecture, also referred to as V10.
+Please note that this version of the SDK is a compete overhaul of the current [Azure Storage SDK for Node.js and JavaScript in Browsers](https://github.com/azure/azure-storage-node), and is based on the new Storage SDK architecture.
 
 ### Features
 
@@ -14,7 +16,7 @@ Please note that this version of the SDK is a compete overhaul of the current [A
   - Create/Read/List/Update/Delete Block Blobs
   - Create/Read/List/Update/Delete Page Blobs
   - Create/Read/List/Update/Delete Append Blobs
-- Features new to V10
+- Features new
   - Asynchronous I/O for all operations using the async methods
   - HttpPipeline which enables a high degree of per-request configurability
   - 1-to-1 correlation with the Storage REST API for clarity and simplicity
@@ -53,9 +55,9 @@ const Azure = require("@azure/storage-blob");
 
 ### JavaScript Bundle
 
-To use the SDK in the browsers, simply add a script tag to your HTML pages pointing to the downloaded JS bundle file(s):
+To use the SDK with JS bundle in the browsers, simply add a script tag to your HTML pages pointing to the downloaded JS bundle file(s):
 
-```
+```html
 <script src="https://mydomain/azure-storage.blob.min.js"></script>
 ```
 

blob/lib/AccountSASPermissions.ts

@@ -49,7 +49,7 @@ export class AccountSASPermissions {
           accountSASPermissions.process = true;
           break;
         default:
-          throw new Error(`Invalid permission character: ${c}`);
+          throw new RangeError(`Invalid permission character: ${c}`);
       }
     }
 

blob/lib/AccountSASResourceTypes.ts

@@ -35,7 +35,7 @@ export class AccountSASResourceTypes {
           accountSASResourceTypes.object = true;
           break;
         default:
-          throw new Error(`Invalid resource type: ${c}`);
+          throw new RangeError(`Invalid resource type: ${c}`);
       }
     }
 

blob/lib/AccountSASServices.ts

@@ -38,7 +38,7 @@ export class AccountSASServices {
           accountSASServices.table = true;
           break;
         default:
-          throw new Error(`Invalid service character: ${c}`);
+          throw new RangeError(`Invalid service character: ${c}`);
       }
     }
 

blob/lib/AppendBlobURL.ts

@@ -76,8 +76,12 @@ export class AppendBlobURL extends BlobURL {
 
   /**
    * Creates an instance of AppendBlobURL.
-   * @param {string} url
-   * @param {Pipeline} pipeline
+   * @param {string} url A URL string pointing to Azure Storage append blob, such as
+   *                     "https://myaccount.blob.core.windows.net/mycontainer/appendblob". You can
+   *                     append a SAS if using AnonymousCredential, such as
+   *                     "https://myaccount.blob.core.windows.net/mycontainer/appendblob?sasString".
+   * @param {Pipeline} pipeline Call StorageURL.newPipeline() to create a default
+   *                            pipeline, or provide a customized pipeline.
    * @memberof AppendBlobURL
    */
   constructor(url: string, pipeline: Pipeline) {
@@ -118,7 +122,7 @@ export class AppendBlobURL extends BlobURL {
   }
 
   /**
-   * Create creates a 0-length append blob. Call AppendBlock to append data to an append blob.
+   * Creates a 0-length append blob. Call AppendBlock to append data to an append blob.
    * @see https://docs.microsoft.com/rest/api/storageservices/put-blob
    *
    * @param {Aborter} aborter Create a new Aborter instance with Aborter.None or Aborter.timeout(),

blob/lib/BlobSASPermissions.ts

@@ -41,7 +41,7 @@ export class BlobSASPermissions {
           blobSASPermissions.delete = true;
           break;
         default:
-          throw new Error(`Invalid permission: ${char}`);
+          throw new RangeError(`Invalid permission: ${char}`);
       }
     }
 

blob/lib/BlobURL.ts

@@ -112,8 +112,12 @@ export class BlobURL extends StorageURL {
 
   /**
    * Creates an instance of BlobURL.
-   * @param {string} url
-   * @param {Pipeline} pipeline
+   * @param {string} url A URL string pointing to Azure Storage blob, such as
+   *                     "https://myaccount.blob.core.windows.net/mycontainer/blob". You can
+   *                     append a SAS if using AnonymousCredential, such as
+   *                     "https://myaccount.blob.core.windows.net/mycontainer/blob?sasString".
+   * @param {Pipeline} pipeline Call StorageURL.newPipeline() to create a default
+   *                            pipeline, or provide a customized pipeline.
    * @memberof BlobURL
    */
   constructor(url: string, pipeline: Pipeline) {

blob/lib/BlockBlobURL.ts

@@ -90,8 +90,12 @@ export class BlockBlobURL extends BlobURL {
 
   /**
    * Creates an instance of BlockBlobURL.
-   * @param {string} url
-   * @param {Pipeline} pipeline
+   * @param {string} url A URL string pointing to Azure Storage block blob, such as
+   *                     "https://myaccount.blob.core.windows.net/mycontainer/blockblob". You can
+   *                     append a SAS if using AnonymousCredential, such as
+   *                     "https://myaccount.blob.core.windows.net/mycontainer/blockblob?sasString".
+   * @param {Pipeline} pipeline Call StorageURL.newPipeline() to create a default
+   *                            pipeline, or provide a customized pipeline.
    * @memberof BlockBlobURL
    */
   constructor(url: string, pipeline: Pipeline) {

blob/lib/ContainerSASPermissions.ts

@@ -42,7 +42,7 @@ export class ContainerSASPermissions {
           containerSASPermissions.list = true;
           break;
         default:
-          throw new Error(`Invalid permission ${char}`);
+          throw new RangeError(`Invalid permission ${char}`);
       }
     }
 

blob/lib/ContainerURL.ts

@@ -159,8 +159,12 @@ export class ContainerURL extends StorageURL {
 
   /**
    * Creates an instance of ContainerURL.
-   * @param {string} url
-   * @param {Pipeline} pipeline
+   * @param {string} url A URL string pointing to Azure Storage blob container, such as
+   *                     "https://myaccount.blob.core.windows.net/mycontainer". You can
+   *                     append a SAS if using AnonymousCredential, such as
+   *                     "https://myaccount.blob.core.windows.net/mycontainer?sasString".
+   * @param {Pipeline} pipeline Call StorageURL.newPipeline() to create a default
+   *                            pipeline, or provide a customized pipeline.
    * @memberof ContainerURL
    */
   constructor(url: string, pipeline: Pipeline) {
@@ -263,7 +267,7 @@ export class ContainerURL extends StorageURL {
         options.containerAccessConditions.modifiedAccessConditions
           .ifNoneMatch !== ETagNone)
     ) {
-      throw new Error(
+      throw new RangeError(
         "the IfMatch and IfNoneMatch access conditions must have their default\
         values because they are ignored by the service"
       );
@@ -317,7 +321,7 @@ export class ContainerURL extends StorageURL {
         options.containerAccessConditions.modifiedAccessConditions
           .ifNoneMatch !== ETagNone)
     ) {
-      throw new Error(
+      throw new RangeError(
         "the IfUnmodifiedSince, IfMatch, and IfNoneMatch must have their default values\
         because they are ignored by the blob service"
       );

blob/lib/IBlobSASSignatureValues.ts

@@ -159,8 +159,8 @@ export function generateBlobSASQueryParameters(
     !blobSASSignatureValues.identifier &&
     (!blobSASSignatureValues.permissions && !blobSASSignatureValues.expiryTime)
   ) {
-    throw new Error(
-      "Must provide 'identifier' or 'permissions' with 'expiryTime' for Blob SAS generation."
+    throw new RangeError(
+      "Must provide 'permissions' and 'expiryTime' for Blob SAS generation when 'identifier' is not provided."
     );
   }
 

blob/lib/IRange.ts

@@ -35,10 +35,10 @@ export interface IRange {
  */
 export function rangeToString(ipRange: IRange): string {
   if (ipRange.offset < 0) {
-    throw new Error(`IPRange.offset cannot be smaller than 0.`);
+    throw new RangeError(`IPRange.offset cannot be smaller than 0.`);
   }
   if (ipRange.count && ipRange.count <= 0) {
-    throw new Error(
+    throw new RangeError(
       `IPRange.count must be larger than 0. Leave it undefined if you want a range from offset to the end.`
     );
   }

blob/lib/PageBlobURL.ts

@@ -104,8 +104,12 @@ export class PageBlobURL extends BlobURL {
 
   /**
    * Creates an instance of PageBlobURL.
-   * @param {string} url
-   * @param {Pipeline} pipeline
+   * @param {string} url A URL string pointing to Azure Storage page blob, such as
+   *                     "https://myaccount.blob.core.windows.net/mycontainer/pageblob". You can
+   *                     append a SAS if using AnonymousCredential, such as
+   *                     "https://myaccount.blob.core.windows.net/mycontainer/pageblob?sasString".
+   * @param {Pipeline} pipeline Call StorageURL.newPipeline() to create a default
+   *                            pipeline, or provide a customized pipeline.
    * @memberof PageBlobURL
    */
   constructor(url: string, pipeline: Pipeline) {

blob/lib/ServiceURL.ts

@@ -59,8 +59,11 @@ export class ServiceURL extends StorageURL {
 
   /**
    * Creates an instance of ServiceURL.
-   * @param {string} url
-   * @param {Pipeline} pipeline
+   * @param {string} url A URL string pointing to Azure Storage blob service, such as
+   *                     "https://myaccount.blob.core.windows.net". You can Append a SAS
+   *                     if using AnonymousCredential, such as "https://myaccount.blob.core.windows.net?sasString".
+   * @param {Pipeline} pipeline Call StorageURL.newPipeline() to create a default
+   *                            pipeline, or provide a customized pipeline.
    * @memberof ServiceURL
    */
   constructor(url: string, pipeline: Pipeline) {

blob/lib/highlevel.browser.ts

@@ -82,13 +82,13 @@ async function UploadSeekableBlobToBlockBlob(
     options.blockSize < 0 ||
     options.blockSize > BLOCK_BLOB_MAX_UPLOAD_BLOB_BYTES
   ) {
-    throw new Error(
+    throw new RangeError(
       `blockSize option must be >= 0 and <= ${BLOCK_BLOB_MAX_UPLOAD_BLOB_BYTES}`
     );
   }
   if (options.blockSize === 0) {
     if (size > BLOCK_BLOB_MAX_STAGE_BLOCK_BYTES * BLOCK_BLOB_MAX_BLOCKS) {
-      throw new Error(`${size} is too larger to upload to a block blob.`);
+      throw new RangeError(`${size} is too larger to upload to a block blob.`);
     }
     if (size > BLOCK_BLOB_MAX_UPLOAD_BLOB_BYTES) {
       options.blockSize = Math.ceil(size / BLOCK_BLOB_MAX_BLOCKS);
@@ -110,7 +110,7 @@ async function UploadSeekableBlobToBlockBlob(
 
   const numBlocks: number = Math.floor((size - 1) / options.blockSize) + 1;
   if (numBlocks > BLOCK_BLOB_MAX_BLOCKS) {
-    throw new Error(
+    throw new RangeError(
       `The buffer's size is too big or the BlockSize is too small;` +
         `the number of blocks must be <= ${BLOCK_BLOB_MAX_BLOCKS}`
     );

blob/lib/highlevel.node.ts

@@ -96,13 +96,13 @@ async function UploadResetableStreamToBlockBlob(
     options.blockSize < 0 ||
     options.blockSize > BLOCK_BLOB_MAX_UPLOAD_BLOB_BYTES
   ) {
-    throw new Error(
+    throw new RangeError(
       `blockSize option must be >= 0 and <= ${BLOCK_BLOB_MAX_UPLOAD_BLOB_BYTES}`
     );
   }
   if (options.blockSize === 0) {
     if (size > BLOCK_BLOB_MAX_STAGE_BLOCK_BYTES * BLOCK_BLOB_MAX_BLOCKS) {
-      throw new Error(`${size} is too larger to upload to a block blob.`);
+      throw new RangeError(`${size} is too larger to upload to a block blob.`);
     }
     if (size > BLOCK_BLOB_MAX_UPLOAD_BLOB_BYTES) {
       options.blockSize = Math.ceil(size / BLOCK_BLOB_MAX_BLOCKS);
@@ -124,7 +124,7 @@ async function UploadResetableStreamToBlockBlob(
 
   const numBlocks: number = Math.floor((size - 1) / options.blockSize) + 1;
   if (numBlocks > BLOCK_BLOB_MAX_BLOCKS) {
-    throw new Error(
+    throw new RangeError(
       `The buffer's size is too big or the BlockSize is too small;` +
         `the number of blocks must be <= ${BLOCK_BLOB_MAX_BLOCKS}`
     );
@@ -194,18 +194,18 @@ export async function DownloadBlobToBuffer(
     options.blockSize = 0;
   }
   if (options.blockSize < 0) {
-    throw new Error("blockSize option must be >= 0");
+    throw new RangeError("blockSize option must be >= 0");
   }
   if (options.blockSize === 0) {
     options.blockSize = BLOB_DEFAULT_DOWNLOAD_BLOCK_BYTES;
   }
 
   if (offset < 0) {
-    throw new Error("offset option must be >= 0");
+    throw new RangeError("offset option must be >= 0");
   }
 
   if (count && count <= 0) {
-    throw new Error("count option must be > 0");
+    throw new RangeError("count option must be > 0");
   }
 
   if (!options.blobAccessConditions) {
@@ -217,14 +217,14 @@ export async function DownloadBlobToBuffer(
     const response = await blobURL.getProperties(aborter, options);
     count = response.contentLength! - offset;
     if (count < 0) {
-      throw new Error(
+      throw new RangeError(
         `offset ${offset} shouldn't be larger than blob size ${response.contentLength!}`
       );
     }
   }
 
   if (buffer.length < count) {
-    throw new Error(
+    throw new RangeError(
       `The buffer's size should be equal to or larger than the request count of bytes: ${count}`
     );
   }

blob/lib/utils/Batch.ts

@@ -96,7 +96,7 @@ export class Batch {
    */
   public constructor(concurrency: number = 5) {
     if (concurrency < 1) {
-      throw new Error("concurrency must be larger than 0");
+      throw new RangeError("concurrency must be larger than 0");
     }
     this.concurrency = concurrency;
     this.emitter = new EventEmitter();

blob/lib/utils/BufferScheduler.ts

@@ -206,19 +206,19 @@ export class BufferScheduler {
     encoding?: string
   ) {
     if (bufferSize <= 0) {
-      throw new Error(
+      throw new RangeError(
         `bufferSize must be larger than 0, current is ${bufferSize}`
       );
     }
 
     if (maxBuffers <= 0) {
-      throw new Error(
+      throw new RangeError(
         `maxBuffers must be larger than 0, current is ${maxBuffers}`
       );
     }
 
     if (parallelism <= 0) {
-      throw new Error(
+      throw new RangeError(
         `parallelism must be larger than 0, current is ${parallelism}`
       );
     }

blob/lib/utils/polyfills.browser.ts

@@ -31,7 +31,7 @@ if (!String.prototype.repeat) {
       return "";
     }
     const arr: string[] = [];
-    while (count > 0) {
+    while (count-- > 0) {
       arr.push(str);
     }
     return arr.join("");
@@ -56,3 +56,21 @@ if (!String.prototype.padStart) {
     }
   };
 }
+
+/* String.prototype.includes */
+if (!String.prototype.includes) {
+  String.prototype.includes = function(
+    searchString: string,
+    position: number = 0
+  ): boolean {
+    if (typeof position !== "number") {
+      position = 0;
+    }
+
+    if (position + searchString.length > this.length) {
+      return false;
+    } else {
+      return -1 !== this.indexOf(searchString, position);
+    }
+  };
+}

blob/samples/highlevel.sample.ts

@@ -21,7 +21,12 @@ async function executeSample() {
   const accountSas = "accountSas";
   const localFilePath = "localFilePath";
 
-  const pipeline = StorageURL.newPipeline(new AnonymousCredential());
+  const pipeline = StorageURL.newPipeline(new AnonymousCredential(), {
+    // httpClient: MyHTTPClient, // A customized HTTP client implementing IHTTPClient interface
+    // logger: MyLogger, // A customized logger implementing IHTTPPipelineLogger interface
+    retryOptions: { maxTries: 10 }, // Retry options
+    telemetry: { value: "HighLevelSample V1.0.0" } // Customized telemetry string
+  });
 
   const serviceURL = new ServiceURL(
     `https://${account}.blob.core.windows.net${accountSas}`,

blob/test/browser/highlevel.browser.test.ts

@@ -132,6 +132,7 @@ describe("Highelvel", () => {
         true,
         "Skip this case in IE11 which doesn't have enough memory for downloading validation"
       );
+      return;
     }
 
     await UploadBrowserDataToBlockBlob(Aborter.None, tempFile1, blockBlobURL, {

blob/webpack.config.js

@@ -7,63 +7,67 @@ const version = require("./package.json").version;
 const zipFileName = `azurestoragejs.blob-${version}`;
 const banner = [
   `Azure Storage SDK for JavaScript - Blob, ${version}`,
-  "Copyright (c) Microsoft and contributors. All rights reserved.",
+  "Copyright (c) Microsoft and contributors. All rights reserved."
 ].join("\n");
 
 module.exports = {
   mode: "production",
   entry: {
     "azure-storage.blob": "./lib/index.browser.ts",
-    "azure-storage.blob.min": "./lib/index.browser.ts",
+    "azure-storage.blob.min": "./lib/index.browser.ts"
   },
   optimization: {
     minimize: true,
     minimizer: [
       new UglifyJsPlugin({
-        include: /\.min\.js$/,
-      }),
-    ],
+        include: /\.min\.js$/
+      })
+    ]
   },
   // devtool: "source-map",
   output: {
     filename: "[name].js",
     path: path.resolve(__dirname, "browser"),
     libraryTarget: "umd",
-    library: "azblob",
+    library: "azblob"
   },
   module: {
     rules: [
       {
         test: /\.tsx?$/,
         loader: "ts-loader",
-        exclude: /(node_modules|samples)/,
-      },
-    ],
+        exclude: /(node_modules|samples)/
+      }
+    ]
   },
   resolve: {
-    extensions: [".tsx", ".ts", ".js"],
+    extensions: [".tsx", ".ts", ".js"]
   },
   plugins: [
     new webpack.BannerPlugin({
       banner: banner,
-      raw: false,
+      raw: false
     }),
     new ZipPlugin({
       filename: zipFileName,
       pathPrefix: zipFileName,
-      include: ["azure-storage.blob.js", "azure-storage.blob.min.js"],
+      include: [
+        "azure-storage.blob.js",
+        "azure-storage.blob.min.js",
+        "ThirdPartyNotice.txt"
+      ],
       // OPTIONAL: see https://github.com/thejoshwolfe/yazl#addfilerealpath-metadatapath-options
       fileOptions: {
         mtime: new Date(),
         mode: 0o100664,
         compress: true,
-        forceZip64Format: false,
+        forceZip64Format: false
       },
       // OPTIONAL: see https://github.com/thejoshwolfe/yazl#endoptions-finalsizecallback
       zipOptions: {
-        forceZip64Format: false,
-      },
-    }),
+        forceZip64Format: false
+      }
+    })
   ],
   node: {
     fs: false,
@@ -73,11 +77,11 @@ module.exports = {
     tls: false,
     tty: false,
     v8: false,
-    Buffer: false,
+    Buffer: false
   },
   performance: {
     hints: "warning",
     maxAssetSize: 300 * 1024 * 1024,
-    maxEntrypointSize: 400 * 1024 * 1024,
-  },
+    maxEntrypointSize: 400 * 1024 * 1024
+  }
 };