bson 5.2.0 → 5.4.0

package/src/binary.ts

@@ -1,4 +1,3 @@
-import { bufferToUuidHexString, uuidHexStringToBuffer, uuidValidateString } from './uuid_utils';
 import { isUint8Array } from './parser/utils';
 import type { EJSONOptions } from './extended_json';
 import { BSONError } from './error';
@@ -224,8 +223,9 @@ export class Binary extends BSONValue {
   toString(encoding?: 'hex' | 'base64' | 'utf8' | 'utf-8'): string {
     if (encoding === 'hex') return ByteUtils.toHex(this.buffer);
     if (encoding === 'base64') return ByteUtils.toBase64(this.buffer);
-    if (encoding === 'utf8' || encoding === 'utf-8') return ByteUtils.toUTF8(this.buffer);
-    return ByteUtils.toUTF8(this.buffer);
+    if (encoding === 'utf8' || encoding === 'utf-8')
+      return ByteUtils.toUTF8(this.buffer, 0, this.buffer.byteLength);
+    return ByteUtils.toUTF8(this.buffer, 0, this.buffer.byteLength);
   }
 
   /** @internal */
@@ -288,7 +288,7 @@ export class Binary extends BSONValue {
       }
     } else if ('$uuid' in doc) {
       type = 4;
-      data = uuidHexStringToBuffer(doc.$uuid);
+      data = UUID.bytesFromString(doc.$uuid);
     }
     if (!data) {
       throw new BSONError(`Unexpected Binary Extended JSON format ${JSON.stringify(doc)}`);
@@ -311,42 +311,41 @@ export class Binary extends BSONValue {
 export type UUIDExtended = {
   $uuid: string;
 };
+
 const UUID_BYTE_LENGTH = 16;
+const UUID_WITHOUT_DASHES = /^[0-9A-F]{32}$/i;
+const UUID_WITH_DASHES = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
 
 /**
  * A class representation of the BSON UUID type.
  * @public
  */
 export class UUID extends Binary {
-  static cacheHexString: boolean;
-
-  /** UUID hexString cache @internal */
-  private __id?: string;
-
+  /** @deprecated Hex string is no longer cached, this control will be removed in a future major release */
+  static cacheHexString = false;
   /**
-   * Create an UUID type
+   * Create a UUID type
+   *
+   * When the argument to the constructor is omitted a random v4 UUID will be generated.
    *
    * @param input - Can be a 32 or 36 character hex string (dashes excluded/included) or a 16 byte binary Buffer.
    */
   constructor(input?: string | Uint8Array | UUID) {
     let bytes: Uint8Array;
-    let hexStr;
     if (input == null) {
       bytes = UUID.generate();
     } else if (input instanceof UUID) {
       bytes = ByteUtils.toLocalBufferType(new Uint8Array(input.buffer));
-      hexStr = input.__id;
     } else if (ArrayBuffer.isView(input) && input.byteLength === UUID_BYTE_LENGTH) {
       bytes = ByteUtils.toLocalBufferType(input);
     } else if (typeof input === 'string') {
-      bytes = uuidHexStringToBuffer(input);
+      bytes = UUID.bytesFromString(input);
     } else {
       throw new BSONError(
         'Argument passed in UUID constructor must be a UUID, a 16 byte Buffer or a 32/36 character hex string (dashes excluded/included, format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).'
       );
     }
     super(bytes, BSON_BINARY_SUBTYPE_UUID_NEW);
-    this.__id = hexStr;
   }
 
   /**
@@ -359,28 +358,23 @@ export class UUID extends Binary {
 
   set id(value: Uint8Array) {
     this.buffer = value;
-
-    if (UUID.cacheHexString) {
-      this.__id = bufferToUuidHexString(value);
-    }
   }
 
   /**
    * Returns the UUID id as a 32 or 36 character hex string representation, excluding/including dashes (defaults to 36 character dash separated)
    * @param includeDashes - should the string exclude dash-separators.
-   * */
+   */
   toHexString(includeDashes = true): string {
-    if (UUID.cacheHexString && this.__id) {
-      return this.__id;
+    if (includeDashes) {
+      return [
+        ByteUtils.toHex(this.buffer.subarray(0, 4)),
+        ByteUtils.toHex(this.buffer.subarray(4, 6)),
+        ByteUtils.toHex(this.buffer.subarray(6, 8)),
+        ByteUtils.toHex(this.buffer.subarray(8, 10)),
+        ByteUtils.toHex(this.buffer.subarray(10, 16))
+      ].join('-');
     }
-
-    const uuidHexString = bufferToUuidHexString(this.id, includeDashes);
-
-    if (UUID.cacheHexString) {
-      this.__id = uuidHexString;
-    }
-
-    return uuidHexString;
+    return ByteUtils.toHex(this.buffer);
   }
 
   /**
@@ -446,29 +440,24 @@ export class UUID extends Binary {
    * Checks if a value is a valid bson UUID
    * @param input - UUID, string or Buffer to validate.
    */
-  static isValid(input: string | Uint8Array | UUID): boolean {
+  static isValid(input: string | Uint8Array | UUID | Binary): boolean {
     if (!input) {
       return false;
     }
 
-    if (input instanceof UUID) {
-      return true;
-    }
-
     if (typeof input === 'string') {
-      return uuidValidateString(input);
+      return UUID.isValidUUIDString(input);
     }
 
     if (isUint8Array(input)) {
-      // check for length & uuid version (https://tools.ietf.org/html/rfc4122#section-4.1.3)
-      if (input.byteLength !== UUID_BYTE_LENGTH) {
-        return false;
-      }
-
-      return (input[6] & 0xf0) === 0x40 && (input[8] & 0x80) === 0x80;
+      return input.byteLength === UUID_BYTE_LENGTH;
     }
 
-    return false;
+    return (
+      input._bsontype === 'Binary' &&
+      input.sub_type === this.SUBTYPE_UUID &&
+      input.buffer.byteLength === 16
+    );
   }
 
   /**
@@ -476,7 +465,7 @@ export class UUID extends Binary {
    * @param hexString - 32 or 36 character hex string (dashes excluded/included).
    */
   static override createFromHexString(hexString: string): UUID {
-    const buffer = uuidHexStringToBuffer(hexString);
+    const buffer = UUID.bytesFromString(hexString);
     return new UUID(buffer);
   }
 
@@ -485,6 +474,26 @@ export class UUID extends Binary {
     return new UUID(ByteUtils.fromBase64(base64));
   }
 
+  /** @internal */
+  static bytesFromString(representation: string) {
+    if (!UUID.isValidUUIDString(representation)) {
+      throw new BSONError(
+        'UUID string representation must be 32 hex digits or canonical hyphenated representation'
+      );
+    }
+    return ByteUtils.fromHex(representation.replace(/-/g, ''));
+  }
+
+  /**
+   * @internal
+   *
+   * Validates a string to be a hex digit sequence with or without dashes.
+   * The canonical hyphenated representation of a uuid is hex in 8-4-4-4-12 groups.
+   */
+  static isValidUUIDString(representation: string) {
+    return UUID_WITHOUT_DASHES.test(representation) || UUID_WITH_DASHES.test(representation);
+  }
+
   /**
    * Converts to a string representation of this Id.
    *

package/src/bson.ts

@@ -10,8 +10,8 @@ import { MinKey } from './min_key';
 import { ObjectId } from './objectid';
 import { internalCalculateObjectSize } from './parser/calculate_size';
 // Parts of the parser
-import { internalDeserialize, DeserializeOptions } from './parser/deserializer';
-import { serializeInto, SerializeOptions } from './parser/serializer';
+import { internalDeserialize, type DeserializeOptions } from './parser/deserializer';
+import { serializeInto, type SerializeOptions } from './parser/serializer';
 import { BSONRegExp } from './regexp';
 import { BSONSymbol } from './symbol';
 import { Timestamp } from './timestamp';
@@ -70,7 +70,7 @@ let buffer = ByteUtils.allocate(MAXSIZE);
 /**
  * Sets the size of the internal serialization buffer.
  *
- * @param size - The desired size for the internal serialization buffer
+ * @param size - The desired size for the internal serialization buffer in bytes
  * @public
  */
 export function setInternalBufferSize(size: number): void {

package/src/constants.ts

@@ -138,4 +138,4 @@ export const BSONType = Object.freeze({
 } as const);
 
 /** @public */
-export type BSONType = typeof BSONType[keyof typeof BSONType];
+export type BSONType = (typeof BSONType)[keyof typeof BSONType];

package/src/extended_json.ts

@@ -24,11 +24,19 @@ import { Timestamp } from './timestamp';
 
 /** @public */
 export type EJSONOptions = {
-  /** Output using the Extended JSON v1 spec */
+  /**
+   * Output using the Extended JSON v1 spec
+   * @defaultValue `false`
+   */
   legacy?: boolean;
-  /** Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types */
+  /**
+   * Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types
+   * @defaultValue `false` */
   relaxed?: boolean;
-  /** Enable native bigint support */
+  /**
+   * Enable native bigint support
+   * @defaultValue `false`
+   */
   useBigInt64?: boolean;
 };
 

package/src/parser/deserializer.ts

@@ -1,8 +1,8 @@
-import { Binary } from '../binary';
+import { Binary, UUID } from '../binary';
 import type { Document } from '../bson';
 import { Code } from '../code';
 import * as constants from '../constants';
-import { DBRef, DBRefLike, isDBRefLike } from '../db_ref';
+import { DBRef, type DBRefLike, isDBRefLike } from '../db_ref';
 import { Decimal128 } from '../decimal128';
 import { Double } from '../double';
 import { BSONError } from '../error';
@@ -19,21 +19,45 @@ import { validateUtf8 } from '../validate_utf8';
 
 /** @public */
 export interface DeserializeOptions {
-  /** when deserializing a Long will return as a BigInt. */
+  /**
+   * when deserializing a Long return as a BigInt.
+   * @defaultValue `false`
+   */
   useBigInt64?: boolean;
-  /** when deserializing a Long will fit it into a Number if it's smaller than 53 bits. */
+  /**
+   * when deserializing a Long will fit it into a Number if it's smaller than 53 bits.
+   * @defaultValue `true`
+   */
   promoteLongs?: boolean;
-  /** when deserializing a Binary will return it as a node.js Buffer instance. */
+  /**
+   * when deserializing a Binary will return it as a node.js Buffer instance.
+   * @defaultValue `false`
+   */
   promoteBuffers?: boolean;
-  /** when deserializing will promote BSON values to their Node.js closest equivalent types. */
+  /**
+   * when deserializing will promote BSON values to their Node.js closest equivalent types.
+   * @defaultValue `true`
+   */
   promoteValues?: boolean;
-  /** allow to specify if there what fields we wish to return as unserialized raw buffer. */
+  /**
+   * allow to specify if there what fields we wish to return as unserialized raw buffer.
+   * @defaultValue `null`
+   */
   fieldsAsRaw?: Document;
-  /** return BSON regular expressions as BSONRegExp instances. */
+  /**
+   * return BSON regular expressions as BSONRegExp instances.
+   * @defaultValue `false`
+   */
   bsonRegExp?: boolean;
-  /** allows the buffer to be larger than the parsed BSON object. */
+  /**
+   * allows the buffer to be larger than the parsed BSON object.
+   * @defaultValue `false`
+   */
   allowObjectSmallerThanBufferSize?: boolean;
-  /** Offset into buffer to begin reading document from */
+  /**
+   * Offset into buffer to begin reading document from
+   * @defaultValue `0`
+   */
   index?: number;
 
   raw?: boolean;
@@ -212,7 +236,7 @@ function deserializeObject(
     if (i >= buffer.byteLength) throw new BSONError('Bad BSON Document: illegal CString');
 
     // Represents the key
-    const name = isArray ? arrayIndex++ : ByteUtils.toUTF8(buffer.subarray(index, i));
+    const name = isArray ? arrayIndex++ : ByteUtils.toUTF8(buffer, index, i);
 
     // shouldValidateKey is true if the key should be validated, false otherwise
     let shouldValidateKey = true;
@@ -404,7 +428,7 @@ function deserializeObject(
           value = ByteUtils.toLocalBufferType(buffer.slice(index, index + binarySize));
         } else {
           value = new Binary(buffer.slice(index, index + binarySize), subType);
-          if (subType === constants.BSON_BINARY_SUBTYPE_UUID_NEW) {
+          if (subType === constants.BSON_BINARY_SUBTYPE_UUID_NEW && UUID.isValid(value)) {
             value = value.toUUID();
           }
         }
@@ -432,10 +456,11 @@ function deserializeObject(
 
         if (promoteBuffers && promoteValues) {
           value = _buffer;
-        } else if (subType === constants.BSON_BINARY_SUBTYPE_UUID_NEW) {
-          value = new Binary(buffer.slice(index, index + binarySize), subType).toUUID();
         } else {
           value = new Binary(buffer.slice(index, index + binarySize), subType);
+          if (subType === constants.BSON_BINARY_SUBTYPE_UUID_NEW && UUID.isValid(value)) {
+            value = value.toUUID();
+          }
         }
       }
 
@@ -451,7 +476,7 @@ function deserializeObject(
       // If are at the end of the buffer there is a problem with the document
       if (i >= buffer.length) throw new BSONError('Bad BSON Document: illegal CString');
       // Return the C string
-      const source = ByteUtils.toUTF8(buffer.subarray(index, i));
+      const source = ByteUtils.toUTF8(buffer, index, i);
       // Create the regexp
       index = i + 1;
 
@@ -464,7 +489,7 @@ function deserializeObject(
       // If are at the end of the buffer there is a problem with the document
       if (i >= buffer.length) throw new BSONError('Bad BSON Document: illegal CString');
       // Return the C string
-      const regExpOptions = ByteUtils.toUTF8(buffer.subarray(index, i));
+      const regExpOptions = ByteUtils.toUTF8(buffer, index, i);
       index = i + 1;
 
       // For each option add the corresponding one for javascript
@@ -496,7 +521,7 @@ function deserializeObject(
       // If are at the end of the buffer there is a problem with the document
       if (i >= buffer.length) throw new BSONError('Bad BSON Document: illegal CString');
       // Return the C string
-      const source = ByteUtils.toUTF8(buffer.subarray(index, i));
+      const source = ByteUtils.toUTF8(buffer, index, i);
       index = i + 1;
 
       // Get the start search index
@@ -508,7 +533,7 @@ function deserializeObject(
       // If are at the end of the buffer there is a problem with the document
       if (i >= buffer.length) throw new BSONError('Bad BSON Document: illegal CString');
       // Return the C string
-      const regExpOptions = ByteUtils.toUTF8(buffer.subarray(index, i));
+      const regExpOptions = ByteUtils.toUTF8(buffer, index, i);
       index = i + 1;
 
       // Set the object
@@ -653,7 +678,7 @@ function deserializeObject(
           throw new BSONError('Invalid UTF-8 string in BSON document');
         }
       }
-      const namespace = ByteUtils.toUTF8(buffer.subarray(index, index + stringSize - 1));
+      const namespace = ByteUtils.toUTF8(buffer, index, index + stringSize - 1);
       // Update parse index position
       index = index + stringSize;
 
@@ -710,7 +735,7 @@ function getValidatedString(
   end: number,
   shouldValidateUtf8: boolean
 ) {
-  const value = ByteUtils.toUTF8(buffer.subarray(start, end));
+  const value = ByteUtils.toUTF8(buffer, start, end);
   // if utf8 validation is on, do the check
   if (shouldValidateUtf8) {
     for (let i = 0; i < value.length; i++) {

package/src/parser/serializer.ts

@@ -16,15 +16,28 @@ import { isAnyArrayBuffer, isDate, isMap, isRegExp, isUint8Array } from './utils
 
 /** @public */
 export interface SerializeOptions {
-  /** the serializer will check if keys are valid. */
+  /**
+   * the serializer will check if keys are valid.
+   * @defaultValue `false`
+   */
   checkKeys?: boolean;
-  /** serialize the javascript functions **(default:false)**. */
+  /**
+   * serialize the javascript functions
+   * @defaultValue `false`
+   */
   serializeFunctions?: boolean;
-  /** serialize will not emit undefined fields **(default:true)** */
+  /**
+   * serialize will not emit undefined fields
+   * note that the driver sets this to `false`
+   * @defaultValue `true`
+   */
   ignoreUndefined?: boolean;
   /** @internal Resize internal buffer */
   minInternalBufferSize?: number;
-  /** the index in the buffer where we wish to start serializing into */
+  /**
+   * the index in the buffer where we wish to start serializing into
+   * @defaultValue `0`
+   */
   index?: number;
 }
 

package/src/timestamp.ts

@@ -27,7 +27,7 @@ export interface TimestampExtended {
 /**
  * @public
  * @category BSONType
- * */
+ */
 export class Timestamp extends LongWithoutOverridesClass {
   get _bsontype(): 'Timestamp' {
     return 'Timestamp';
@@ -61,24 +61,26 @@ export class Timestamp extends LongWithoutOverridesClass {
       if (typeof low.i !== 'number' && (typeof low.i !== 'object' || low.i._bsontype !== 'Int32')) {
         throw new BSONError('Timestamp constructed from { t, i } must provide i as a number');
       }
-      if (low.t < 0) {
+      const t = Number(low.t);
+      const i = Number(low.i);
+      if (t < 0 || Number.isNaN(t)) {
         throw new BSONError('Timestamp constructed from { t, i } must provide a positive t');
       }
-      if (low.i < 0) {
+      if (i < 0 || Number.isNaN(i)) {
         throw new BSONError('Timestamp constructed from { t, i } must provide a positive i');
       }
-      if (low.t > 0xffff_ffff) {
+      if (t > 0xffff_ffff) {
         throw new BSONError(
           'Timestamp constructed from { t, i } must provide t equal or less than uint32 max'
         );
       }
-      if (low.i > 0xffff_ffff) {
+      if (i > 0xffff_ffff) {
         throw new BSONError(
           'Timestamp constructed from { t, i } must provide i equal or less than uint32 max'
         );
       }
 
-      super(low.i.valueOf(), low.t.valueOf(), true);
+      super(i, t, true);
     } else {
       throw new BSONError(
         'A Timestamp can only be constructed with: bigint, Long, or { t: number; i: number }'

package/src/utils/byte_utils.ts

@@ -26,7 +26,7 @@ export type ByteUtils = {
   /** Create a Uint8Array containing utf8 code units from a string */
   fromUTF8: (text: string) => Uint8Array;
   /** Create a string from utf8 code units */
-  toUTF8: (buffer: Uint8Array) => string;
+  toUTF8: (buffer: Uint8Array, start: number, end: number) => string;
   /** Get the utf8 code unit count from a string if it were to be transformed to utf8 */
   utf8ByteLength: (input: string) => number;
   /** Encode UTF8 bytes generated from `source` string into `destination` at byteOffset. Returns the number of bytes encoded. */

package/src/utils/node_byte_utils.ts

@@ -5,7 +5,7 @@ type NodeJsBuffer = ArrayBufferView &
   Uint8Array & {
     write(string: string, offset: number, length: undefined, encoding: 'utf8'): number;
     copy(target: Uint8Array, targetStart: number, sourceStart: number, sourceEnd: number): number;
-    toString: (this: Uint8Array, encoding: NodeJsEncoding) => string;
+    toString: (this: Uint8Array, encoding: NodeJsEncoding, start?: number, end?: number) => string;
     equals: (this: Uint8Array, other: Uint8Array) => boolean;
   };
 type NodeJsBufferConstructor = Omit<Uint8ArrayConstructor, 'from'> & {
@@ -125,8 +125,8 @@ export const nodeJsByteUtils = {
     return Buffer.from(text, 'utf8');
   },
 
-  toUTF8(buffer: Uint8Array): string {
-    return nodeJsByteUtils.toLocalBufferType(buffer).toString('utf8');
+  toUTF8(buffer: Uint8Array, start: number, end: number): string {
+    return nodeJsByteUtils.toLocalBufferType(buffer).toString('utf8', start, end);
   },
 
   utf8ByteLength(input: string): number {

package/src/utils/web_byte_utils.ts

@@ -172,8 +172,8 @@ export const webByteUtils = {
     return new TextEncoder().encode(text);
   },
 
-  toUTF8(uint8array: Uint8Array): string {
-    return new TextDecoder('utf8', { fatal: false }).decode(uint8array);
+  toUTF8(uint8array: Uint8Array, start: number, end: number): string {
+    return new TextDecoder('utf8', { fatal: false }).decode(uint8array.slice(start, end));
   },
 
   utf8ByteLength(input: string): number {

package/vendor/base64/LICENSE-MIT.txt

@@ -0,0 +1,20 @@
+Copyright Mathias Bynens <https://mathiasbynens.be/>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/vendor/base64/README.md

@@ -0,0 +1,112 @@
+# base64 [![Build status](https://travis-ci.org/mathiasbynens/base64.svg?branch=master)](https://travis-ci.org/mathiasbynens/base64) [![Code coverage status](http://img.shields.io/coveralls/mathiasbynens/base64/master.svg)](https://coveralls.io/r/mathiasbynens/base64)
+
+_base64_ is a robust base64 encoder/decoder that is fully compatible with [`atob()` and `btoa()`](https://html.spec.whatwg.org/multipage/webappapis.html#atob), written in JavaScript. The base64-encoding and -decoding algorithms it uses are fully [RFC 4648](https://tools.ietf.org/html/rfc4648#section-4) compliant.
+
+## Installation
+
+Via [npm](https://www.npmjs.com/):
+
+```bash
+npm install base-64
+```
+
+In a browser:
+
+```html
+<script src="base64.js"></script>
+```
+
+In [Narwhal](http://narwhaljs.org/), [Node.js](https://nodejs.org/), and [RingoJS](http://ringojs.org/):
+
+```js
+var base64 = require('base-64');
+```
+
+In [Rhino](http://www.mozilla.org/rhino/):
+
+```js
+load('base64.js');
+```
+
+Using an AMD loader like [RequireJS](http://requirejs.org/):
+
+```js
+require(
+  {
+    'paths': {
+      'base64': 'path/to/base64'
+    }
+  },
+  ['base64'],
+  function(base64) {
+    console.log(base64);
+  }
+);
+```
+
+## API
+
+### `base64.version`
+
+A string representing the semantic version number.
+
+### `base64.encode(input)`
+
+This function takes a byte string (the `input` parameter) and encodes it according to base64. The input data must be in the form of a string containing only characters in the range from U+0000 to U+00FF, each representing a binary byte with values `0x00` to `0xFF`. The `base64.encode()` function is designed to be fully compatible with [`btoa()` as described in the HTML Standard](https://html.spec.whatwg.org/multipage/webappapis.html#dom-windowbase64-btoa).
+
+```js
+var encodedData = base64.encode(input);
+```
+
+To base64-encode any Unicode string, [encode it as UTF-8 first](https://github.com/mathiasbynens/utf8.js#utf8encodestring):
+
+```js
+var base64 = require('base-64');
+var utf8 = require('utf8');
+
+var text = 'foo © bar 𝌆 baz';
+var bytes = utf8.encode(text);
+var encoded = base64.encode(bytes);
+console.log(encoded);
+// → 'Zm9vIMKpIGJhciDwnYyGIGJheg=='
+```
+
+### `base64.decode(input)`
+
+This function takes a base64-encoded string (the `input` parameter) and decodes it. The return value is in the form of a string containing only characters in the range from U+0000 to U+00FF, each representing a binary byte with values `0x00` to `0xFF`. The `base64.decode()` function is designed to be fully compatible with [`atob()` as described in the HTML Standard](https://html.spec.whatwg.org/multipage/webappapis.html#dom-windowbase64-atob).
+
+```js
+var decodedData = base64.decode(encodedData);
+```
+
+To base64-decode UTF-8-encoded data back into a Unicode string, [UTF-8-decode it](https://github.com/mathiasbynens/utf8.js#utf8decodebytestring) after base64-decoding it:
+
+```js
+var encoded = 'Zm9vIMKpIGJhciDwnYyGIGJheg==';
+var bytes = base64.decode(encoded);
+var text = utf8.decode(bytes);
+console.log(text);
+// → 'foo © bar 𝌆 baz'
+```
+
+## Support
+
+_base64_ is designed to work in at least Node.js v0.10.0, Narwhal 0.3.2, RingoJS 0.8-0.9, PhantomJS 1.9.0, Rhino 1.7RC4, as well as old and modern versions of Chrome, Firefox, Safari, Opera, and Internet Explorer.
+
+## Unit tests & code coverage
+
+After cloning this repository, run `npm install` to install the dependencies needed for development and testing. You may want to install Istanbul _globally_ using `npm install istanbul -g`.
+
+Once that’s done, you can run the unit tests in Node using `npm test` or `node tests/tests.js`. To run the tests in Rhino, Ringo, Narwhal, and web browsers as well, use `grunt test`.
+
+To generate the code coverage report, use `grunt cover`.
+
+## Author
+
+| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
+|---|
+| [Mathias Bynens](https://mathiasbynens.be/) |
+
+## License
+
+_base64_ is available under the [MIT](https://mths.be/mit) license.