Feature/base64 support

packages/types/index.ts

@@ -3,3 +3,4 @@ export * from './http';
 export * from './crypto';
 export * from './protocol';
 export * from './response';
+export * from './util';

packages/types/util.ts

@@ -0,0 +1,23 @@
+/**
+ * A function that, given a TypedArray of bytes, can produce a string
+ * representation thereof.
+ *
+ * @example An encoder function that converts bytes to hexadecimal
+ * representation would return `'deadbeef'` when given `new
+ * Uint8Array([0xde, 0xad, 0xbe, 0xef])`.
+ */
+export interface Encoder {
+    (input: Uint8Array): string;
+}
+
+/**
+ * A function that, given a string, can derive the bytes represented by that
+ * string.
+ *
+ * @example A decoder function that converts bytes to hexadecimal
+ * representation would return `new Uint8Array([0xde, 0xad, 0xbe, 0xef])` when
+ * given the string `'deadbeef'`.
+ */
+export interface Decoder {
+    (input: string): Uint8Array;
+}

packages/util-base64-browser/.gitignore

@@ -0,0 +1,4 @@
+/node_modules/
+*.js
+*.js.map
+*.d.ts

packages/util-base64-browser/__tests__/index.ts

@@ -0,0 +1,50 @@
+import {
+    fromBase64,
+    toBase64,
+} from "../";
+
+const doublePadded = new Uint8Array([0xde, 0xad, 0xbe, 0xef]);
+const b64DoublePadded = '3q2+7w==';
+
+const singlePadded = new Uint8Array([0xde, 0xad, 0xbe, 0xef, 0xfa]);
+const b64SinglePadded = '3q2+7/o=';
+
+const unpadded = new Uint8Array([0xde, 0xad, 0xbe, 0xef, 0xfa, 0xce]);
+const b64Unpadded = '3q2+7/rO';
+
+describe('toBase64', () => {
+    it(
+        'should convert Uint8Arrays with byte lengths divisible by 3 to unpadded base64 strings',
+        () => {
+            expect(toBase64(unpadded)).toBe(b64Unpadded);
+        }
+    );
+
+    it(
+        'should convert Uint8Arrays whose byte lengths mod 3 === 2 to single-padded base64 strings',
+        () => {
+            expect(toBase64(singlePadded)).toBe(b64SinglePadded);
+        }
+    );
+
+    it(
+        'should convert Uint8Arrays whose byte lengths mod 3 === 1 to double-padded base64 strings',
+        () => {
+            expect(toBase64(doublePadded)).toBe(b64DoublePadded);
+        }
+    );
+});
+
+describe('fromBase64', () => {
+    it('should convert unpadded base64 strings to Uint8Arrays', () => {
+        expect(fromBase64(b64Unpadded)).toEqual(unpadded);
+    });
+
+    it('should convert single padded base64 strings to Uint8Arrays', () => {
+        expect(fromBase64(b64SinglePadded)).toEqual(singlePadded);
+    });
+
+    it('should convert double padded base64 strings to Uint8Arrays', () => {
+        expect(fromBase64(b64DoublePadded)).toEqual(doublePadded);
+    });
+});

packages/util-base64-browser/index.ts

@@ -0,0 +1,113 @@
+const alphabetByEncoding: {[key: string]: number} = {};
+const alphabetByValue: Array<string> = new Array(64);
+
+for (
+    let i = 0, start = 'A'.charCodeAt(0), limit = 'Z'.charCodeAt(0);
+    i + start <= limit;
+    i++
+) {
+    const char = String.fromCharCode(i + start);
+    alphabetByEncoding[char] = i;
+    alphabetByValue[i] = char;
+}
+
+for (
+    let i = 0, start = 'a'.charCodeAt(0), limit = 'z'.charCodeAt(0);
+    i + start <= limit;
+    i++
+) {
+    const char = String.fromCharCode(i + start);
+    const index = i + 26;
+    alphabetByEncoding[char] = index;
+    alphabetByValue[index] = char;
+}
+
+for (let i = 0; i < 10; i++) {
+    alphabetByEncoding[i.toString(10)] = i + 52;
+    const char = i.toString(10);
+    const index = i + 52;
+    alphabetByEncoding[char] = index;
+    alphabetByValue[index] = char;
+}
+
+alphabetByEncoding['+'] = 62;
+alphabetByValue[62] = '+';
+alphabetByEncoding['/'] = 63;
+alphabetByValue[63] = '/';
+
+const bitsPerLetter = 6;
+const bitsPerByte = 8;
+const maxLetterValue = 0b111111;
+
+/**
+ * Converts a base-64 encoded string to a Uint8Array of bytes.
+ *
+ * @param input The base-64 encoded string
+ *
+ * @see https://tools.ietf.org/html/rfc4648#section-4
+ */
+export function fromBase64(input: string): Uint8Array {
+    let totalByteLength = input.length / 4 * 3;
+    if (input.substr(-2) === '==') {
+        totalByteLength -= 2;
+    } else if (input.substr(-1) === '=') {
+        totalByteLength--;
+    }
+    const out = new ArrayBuffer(totalByteLength);
+    const dataView = new DataView(out);
+    for (let i = 0; i < input.length; i += 4) {
+        let bits = 0;
+        let bitLength = 0;
+        for (let j = i, limit = i + 3; j <= limit; j++) {
+            if (input[j] !== '=') {
+                bits |= alphabetByEncoding[input[j]] << ((limit - j) * bitsPerLetter);
+                bitLength += bitsPerLetter;
+            } else {
+                bits >>= bitsPerLetter;
+            }
+        }
+
+        const chunkOffset = i / 4 * 3;
+        bits >>= bitLength % bitsPerByte;
+        const byteLength = Math.floor(bitLength / bitsPerByte);
+        for (let k = 0; k < byteLength; k++) {
+            const offset = (byteLength - k - 1) * bitsPerByte;
+            dataView.setUint8(
+                chunkOffset + k,
+                (bits & (255 << offset)) >> offset
+            );
+        }
+    }
+
+    return new Uint8Array(out);
+}
+
+/**
+ * Converts a Uint8Array of binary data to a base-64 encoded string.
+ *
+ * @param input The binary data to encode
+ *
+ * @see https://tools.ietf.org/html/rfc4648#section-4
+ */
+export function toBase64(input: Uint8Array): string {
+    let str = '';
+    for (let i = 0; i < input.length; i += 3) {
+        let bits = 0;
+        let bitLength = 0;
+        for (let j = i, limit = Math.min(i + 3, input.length); j < limit; j++) {
+            bits |= input[j] << (limit - j - 1) * bitsPerByte;
+            bitLength += bitsPerByte;
+        }
+
+        const bitClusterCount = Math.ceil(bitLength / bitsPerLetter);
+        bits <<= bitClusterCount * bitsPerLetter - bitLength;
+        for (let k = 1; k <= bitClusterCount; k++) {
+            const offset = (bitClusterCount - k) * bitsPerLetter;
+            str += alphabetByValue[(bits & (maxLetterValue << offset)) >> offset];
+        }
+
+        str += '=='.slice(0, 4 - bitClusterCount);
+    }
+
+    return str;
+}

packages/util-base64-browser/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@aws/util-base64-browser",
+  "private": true,
+  "version": "0.0.1",
+  "description": "A pure JS Base64 <-> UInt8Array converter",
+  "main": "index.js",
+  "scripts": {
+    "prepublishOnly": "tsc",
+    "pretest": "tsc",
+    "test": "jest"
+  },
+  "author": "[email protected]",
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "@types/jest": "^19.2.2",
+    "@types/node": "^7.0.12",
+    "jest": "^19.0.2",
+    "typescript": "^2.3"
+  }
+}

packages/util-base64-browser/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "module": "commonjs",
+    "declaration": true,
+    "sourceMap": true,
+    "strict": true
+  }
+}

packages/util-base64-node/.gitignore

@@ -0,0 +1,4 @@
+/node_modules/
+*.js
+*.js.map
+*.d.ts

packages/util-base64-node/__tests__/index.ts

@@ -0,0 +1,58 @@
+import {
+    fromBase64,
+    toBase64,
+} from "../";
+
+const doublePadded = new Uint8Array([0xde, 0xad, 0xbe, 0xef]);
+const b64DoublePadded = '3q2+7w==';
+
+const singlePadded = new Uint8Array([0xde, 0xad, 0xbe, 0xef, 0xfa]);
+const b64SinglePadded = '3q2+7/o=';
+
+const unpadded = new Uint8Array([0xde, 0xad, 0xbe, 0xef, 0xfa, 0xce]);
+const b64Unpadded = '3q2+7/rO';
+
+describe('toBase64', () => {
+    it(
+        'should convert Uint8Arrays with byte lengths divisible by 3 to unpadded base64 strings',
+        () => {
+            expect(toBase64(unpadded)).toBe(b64Unpadded);
+        }
+    );
+
+    it(
+        'should convert Uint8Arrays whose byte lengths mod 3 === 2 to single-padded base64 strings',
+        () => {
+            expect(toBase64(singlePadded)).toBe(b64SinglePadded);
+        }
+    );
+
+    it(
+        'should convert Uint8Arrays whose byte lengths mod 3 === 1 to double-padded base64 strings',
+        () => {
+            expect(toBase64(doublePadded)).toBe(b64DoublePadded);
+        }
+    );
+
+    it('should throw when given a number', () => {
+        expect(() => toBase64(0xdeadbeefface as any)).toThrow();
+    });
+});
+
+describe('fromBase64', () => {
+    it('should convert unpadded base64 strings to Uint8Arrays', () => {
+        expect(fromBase64(b64Unpadded)).toEqual(unpadded);
+    });
+
+    it('should convert single padded base64 strings to Uint8Arrays', () => {
+        expect(fromBase64(b64SinglePadded)).toEqual(singlePadded);
+    });
+
+    it('should convert double padded base64 strings to Uint8Arrays', () => {
+        expect(fromBase64(b64DoublePadded)).toEqual(doublePadded);
+    });
+
+    it('should throw when given a number', () => {
+        expect(() => fromBase64(0xdeadbeefface as any)).toThrow();
+    });
+});

packages/util-base64-node/index.ts

@@ -0,0 +1,47 @@
+import {Buffer} from 'buffer';
+
+/**
+ * Converts a base-64 encoded string to a Uint8Array of bytes using Node.JS's
+ * `buffer` module.
+ *
+ * @param input The base-64 encoded string
+ */
+export function fromBase64(input: string): Uint8Array {
+    if (typeof input === 'number') {
+        throw new Error('Cannot base64 decode a number');
+    }
+
+    let buf: Buffer;
+    if (typeof Buffer.from === 'function' && Buffer.from !== Uint8Array.from) {
+        buf = Buffer.from(input, 'base64');
+    } else {
+        buf = new Buffer(input, 'base64')
+    }
+
+    return new Uint8Array(
+        buf.buffer,
+        buf.byteOffset,
+        buf.byteLength / Uint8Array.BYTES_PER_ELEMENT
+    );
+}
+
+/**
+ * Converts a Uint8Array of binary data to a base-64 encoded string using
+ * Node.JS's `buffer` module.
+ *
+ * @param input The binary data to encode
+ */
+export function toBase64(input: Uint8Array): string {
+    if (typeof input === 'number') {
+        throw new Error('Cannot base64 encode a number');
+    }
+
+    let buf: Buffer;
+    if (typeof Buffer.from === 'function' && Buffer.from !== Uint8Array.from) {
+        buf = Buffer.from(input.buffer);
+    } else {
+        buf = new Buffer(input.buffer);
+    }
+
+    return buf.toString('base64');
+}

packages/util-base64-node/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@aws/util-base64-node",
+  "private": true,
+  "version": "0.0.1",
+  "description": "A Node.JS Base64 <-> UInt8Array converter",
+  "main": "index.js",
+  "scripts": {
+    "prepublishOnly": "tsc",
+    "pretest": "tsc",
+    "test": "jest"
+  },
+  "author": "[email protected]",
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "@types/jest": "^19.2.2",
+    "@types/node": "^7.0.12",
+    "jest": "^19.0.2",
+    "typescript": "^2.3"
+  }
+}

packages/util-base64-node/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "module": "commonjs",
+    "declaration": true,
+    "sourceMap": true,
+    "strict": true
+  }
+}

packages/util-base64-universal/.gitignore

@@ -0,0 +1,4 @@
+/node_modules/
+*.js
+*.js.map
+*.d.ts