feat: add Base64 type support (#8)

Co-authored-by: Pooya Parsa <[email protected]>

README.md

@@ -22,6 +22,7 @@
 ## 👍 Supported Types
 
 - [ArrayBuffer][ArrayBuffer]
+- [Base64][Base64]
 - [Blob][Blob]
 - [DataView][DataView]
 - [Number Array][Number Array]
@@ -132,6 +133,10 @@ assertArrayBuffer(value); // Throws an error if value is not ArrayBuffer
 
 ## Array Buffer
 
+### `arrayBufferToBase64(arrayBuffer, base64Options)`
+
+Convert from [ArrayBuffer][ArrayBuffer] to [Base64][Base64]
+
 ### `arrayBufferToBlob(arrayBuffer, options?)`
 
 Convert from [ArrayBuffer][ArrayBuffer] to [Blob][Blob]
@@ -172,6 +177,52 @@ Test if input is an instance of [ArrayBuffer][ArrayBuffer] and return `true` or
 
 Convert from any value to [ArrayBuffer][ArrayBuffer]
 
+## Base64
+
+### `assertBase64(input, opts?)`
+
+Assert that input is an instance of [String][String] and matches the [Base64][Base64] pattern or throw a `TypeError`.
+
+### `base64ToArrayBuffer(string, base64Options?)`
+
+Convert from [Base64][Base64] to [ArrayBuffer][ArrayBuffer]
+
+### `base64ToBlob(string, opts?)`
+
+Convert from [Base64][Base64] to [Blob][Blob]
+
+### `base64ToDataView(string, base64Options?)`
+
+Convert from [Base64][Base64] to [DataView][DataView]
+
+### `base64ToNumberArray(string, base64Options?)`
+
+Convert from [Base64][Base64] to [Number Array][Number Array]
+
+### `base64ToReadableStream(string, base64Options?)`
+
+Convert from [Base64][Base64] to [ReadableStream][ReadableStream]
+
+### `base64ToResponse(string)`
+
+Convert from [Base64][Base64] to [Response][Response]
+
+### `base64ToString(string, opts?)`
+
+Convert from [Base64][Base64] to [String][String]
+
+### `base64ToUint8Array(string, base64Options?)`
+
+Convert from [Base64][Base64] to [Uint8Array][Uint8Array]
+
+### `isBase64(input, base64Options?)`
+
+Test if input is string and matches the [Base64][Base64] pattern and return `true` or `false`.
+
+### `toBase64(input)`
+
+Convert from any value to [Base64][Base64]
+
 ## Blob
 
 ### `assertBlob(input)`
@@ -182,6 +233,10 @@ Assert that input is an instance of [Blob][Blob] or throw a `TypeError`.
 
 Convert from [Blob][Blob] to [ArrayBuffer][ArrayBuffer]
 
+### `blobToBase64(blob, base64Options)`
+
+Convert from [Blob][Blob] to [Base64][Base64]
+
 ### `blobToDataView(blob)`
 
 Convert from [Blob][Blob] to [DataView][DataView]
@@ -224,6 +279,10 @@ Assert that input is an instance of [DataView][DataView] or throw a `TypeError`.
 
 Convert from [DataView][DataView] to [ArrayBuffer][ArrayBuffer]
 
+### `dataViewToBase64(dataView, base64Options?)`
+
+Convert from [DataView][DataView] to [Base64][Base64]
+
 ### `dataViewToBlob(dataView, options?)`
 
 Convert from [DataView][DataView] to [Blob][Blob]
@@ -270,6 +329,10 @@ Test if input is an instance of [Number Array][Number Array] and return `true` o
 
 Convert from [Number Array][Number Array] to [ArrayBuffer][ArrayBuffer]
 
+### `numberArrayToBase64(numberArray, base64Options?)`
+
+Convert from [Number Array][Number Array] to [Base64][Base64]
+
 ### `numberArrayToBlob(numberArray, options?)`
 
 Convert from [Number Array][Number Array] to [Blob][Blob]
@@ -308,6 +371,10 @@ Test if input is an instance of [ReadableStream][ReadableStream] and return `tru
 
 Convert from [ReadableStream][ReadableStream] to [ArrayBuffer][ArrayBuffer]
 
+### `readableStreamToBase64(readableStream, base64Options?)`
+
+Convert from [ReadableStream][ReadableStream] to [Base64][Base64]
+
 ### `readableStreamToBlob(readableStream, options?)`
 
 Convert from [ReadableStream][ReadableStream] to [Blob][Blob]
@@ -350,6 +417,10 @@ Test if input is an instance of [Response][Response] and return `true` or `false
 
 Convert from [Response][Response] to [ArrayBuffer][ArrayBuffer]
 
+### `responseToBase64(response, base64Options?)`
+
+Convert from [Response][Response] to [Base64][Base64]
+
 ### `responseToBlob(response)`
 
 Convert from [Response][Response] to [Blob][Blob]
@@ -388,6 +459,10 @@ Test if input is an instance of [String][String] and return `true` or `false`.
 
 Convert from [string][string] to [ArrayBuffer][ArrayBuffer]
 
+### `stringToBase64(string, opts?)`
+
+Convert from [string][string] to [Base64][Base64]
+
 ### `stringToBlob(string, options?)`
 
 Convert from [string][string] to [Blob][Blob]
@@ -426,6 +501,10 @@ Convert from any value to [Uint8Array][Uint8Array]
 
 Convert from [Uint8Array][Uint8Array] to [ArrayBuffer][ArrayBuffer]
 
+### `uint8ArrayToBase64(uint8Array, base64Options?)`
+
+Convert from [Uint8Array][Uint8Array] to [Base64][Base64]
+
 ### `uint8ArrayToBlob(uint8Array, options?)`
 
 Convert from [Uint8Array][Uint8Array] to [Blob][Blob]
@@ -506,6 +585,7 @@ _🤖 auto updated with [automd](https://automd.unjs.io)_
 <!-- /automd -->
 
 [ArrayBuffer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
+[Base64]: https://developer.mozilla.org/en-US/docs/Glossary/Base64
 [Blob]: https://developer.mozilla.org/en-US/docs/Web/API/Blob
 [DataView]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView
 [Number Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array

scripts/gen-maps.ts

@@ -2,6 +2,7 @@ import { writeFileSync } from "node:fs";
 
 const types = [
  "arrayBuffer",
+ "base64",
  "blob",
  "dataView",
  "numberArray",

src/convert-maps.ts

@@ -1,15 +1,26 @@
 // Auto generated using gen-maps script
 import {
  assertArrayBuffer,
+ base64ToArrayBuffer,
  blobToArrayBuffer,
  dataViewToArrayBuffer,
  numberArrayToArrayBuffer,
  readableStreamToArrayBuffer,
  responseToArrayBuffer,
  stringToArrayBuffer,
  uint8ArrayToArrayBuffer,
+ assertBase64,
+ arrayBufferToBase64,
+ blobToBase64,
+ dataViewToBase64,
+ numberArrayToBase64,
+ readableStreamToBase64,
+ responseToBase64,
+ stringToBase64,
+ uint8ArrayToBase64,
  assertBlob,
  arrayBufferToBlob,
+ base64ToBlob,
  dataViewToBlob,
  numberArrayToBlob,
  readableStreamToBlob,
@@ -18,6 +29,7 @@ import {
  uint8ArrayToBlob,
  assertDataView,
  arrayBufferToDataView,
+ base64ToDataView,
  blobToDataView,
  numberArrayToDataView,
  readableStreamToDataView,
@@ -26,6 +38,7 @@ import {
  uint8ArrayToDataView,
  assertNumberArray,
  arrayBufferToNumberArray,
+ base64ToNumberArray,
  blobToNumberArray,
  dataViewToNumberArray,
  readableStreamToNumberArray,
@@ -34,6 +47,7 @@ import {
  uint8ArrayToNumberArray,
  assertReadableStream,
  arrayBufferToReadableStream,
+ base64ToReadableStream,
  blobToReadableStream,
  dataViewToReadableStream,
  numberArrayToReadableStream,
@@ -42,6 +56,7 @@ import {
  uint8ArrayToReadableStream,
  assertResponse,
  arrayBufferToResponse,
+ base64ToResponse,
  blobToResponse,
  dataViewToResponse,
  numberArrayToResponse,
@@ -50,6 +65,7 @@ import {
  uint8ArrayToResponse,
  assertString,
  arrayBufferToString,
+ base64ToString,
  blobToString,
  dataViewToString,
  numberArrayToString,
@@ -58,6 +74,7 @@ import {
  uint8ArrayToString,
  assertUint8Array,
  arrayBufferToUint8Array,
+ base64ToUint8Array,
  blobToUint8Array,
  dataViewToUint8Array,
  numberArrayToUint8Array,
@@ -68,6 +85,7 @@ import {
 
 export const _toArrayBuffer = {
  ArrayBuffer: (input: unknown) => (assertArrayBuffer(input), input),
+ Base64: base64ToArrayBuffer,
  Blob: blobToArrayBuffer,
  DataView: dataViewToArrayBuffer,
  NumberArray: numberArrayToArrayBuffer,
@@ -77,8 +95,21 @@ export const _toArrayBuffer = {
  Uint8Array: uint8ArrayToArrayBuffer,
 } as const;
 
+export const _toBase64 = {
+ ArrayBuffer: arrayBufferToBase64,
+ Base64: (input: unknown) => (assertBase64(input), input),
+ Blob: blobToBase64,
+ DataView: dataViewToBase64,
+ NumberArray: numberArrayToBase64,
+ ReadableStream: readableStreamToBase64,
+ Response: responseToBase64,
+ String: stringToBase64,
+ Uint8Array: uint8ArrayToBase64,
+} as const;
+
 export const _toBlob = {
  ArrayBuffer: arrayBufferToBlob,
+ Base64: base64ToBlob,
  Blob: (input: unknown) => (assertBlob(input), input),
  DataView: dataViewToBlob,
  NumberArray: numberArrayToBlob,
@@ -90,6 +121,7 @@ export const _toBlob = {
 
 export const _toDataView = {
  ArrayBuffer: arrayBufferToDataView,
+ Base64: base64ToDataView,
  Blob: blobToDataView,
  DataView: (input: unknown) => (assertDataView(input), input),
  NumberArray: numberArrayToDataView,
@@ -101,6 +133,7 @@ export const _toDataView = {
 
 export const _toNumberArray = {
  ArrayBuffer: arrayBufferToNumberArray,
+ Base64: base64ToNumberArray,
  Blob: blobToNumberArray,
  DataView: dataViewToNumberArray,
  NumberArray: (input: unknown) => (assertNumberArray(input), input),
@@ -112,6 +145,7 @@ export const _toNumberArray = {
 
 export const _toReadableStream = {
  ArrayBuffer: arrayBufferToReadableStream,
+ Base64: base64ToReadableStream,
  Blob: blobToReadableStream,
  DataView: dataViewToReadableStream,
  NumberArray: numberArrayToReadableStream,
@@ -123,6 +157,7 @@ export const _toReadableStream = {
 
 export const _toResponse = {
  ArrayBuffer: arrayBufferToResponse,
+ Base64: base64ToResponse,
  Blob: blobToResponse,
  DataView: dataViewToResponse,
  NumberArray: numberArrayToResponse,
@@ -134,6 +169,7 @@ export const _toResponse = {
 
 export const _toString = {
  ArrayBuffer: arrayBufferToString,
+ Base64: base64ToString,
  Blob: blobToString,
  DataView: dataViewToString,
  NumberArray: numberArrayToString,
@@ -145,6 +181,7 @@ export const _toString = {
 
 export const _toUint8Array = {
  ArrayBuffer: arrayBufferToUint8Array,
+ Base64: base64ToUint8Array,
  Blob: blobToUint8Array,
  DataView: dataViewToUint8Array,
  NumberArray: numberArrayToUint8Array,
@@ -156,6 +193,7 @@ export const _toUint8Array = {
 
 export const _to = {
  ArrayBuffer: _toArrayBuffer,
+ Base64: _toBase64,
  Blob: _toBlob,
  DataView: _toDataView,
  NumberArray: _toNumberArray,

src/convert.ts

@@ -1,7 +1,8 @@
-import { DataType, DataTypeName } from "./types";
+import type { Base64, DataType, DataTypeName } from "./types";
 import { detectType } from "./detect";
 import {
  _toArrayBuffer,
+ _toBase64,
  _toBlob,
  _toDataView,
  _toNumberArray,
@@ -14,6 +15,9 @@ import {
 
 /**
  * Convert from any value to any supported data type
+ * @param toType - The target data type
+ * @param input - The input value
+ * @param fromType - The source data type (optional)
  */
 export function convertTo<T extends DataTypeName>(
  toType: T,
@@ -82,6 +86,13 @@ export const toString = (input: DataType) =>
 export const toUint8Array = (input: DataType) =>
  _convertTo<string>(input, _toUint8Array);
 
+/**
+ * Convert from any value to [Base64][Base64]
+ * @group Base64
+ */
+export const toBase64 = (input: DataType) =>
+ _convertTo<Base64>(input, _toBase64);
+
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 function _convertTo<T extends DataType>(
  input: DataType,

src/data-types/_utils.ts

@@ -1,3 +1,5 @@
+import type { Base64, Base64Options } from "../types";
+
 type TestFn<T> = (input: unknown) => input is T;
 
 export function assertType<T>(
@@ -9,3 +11,19 @@ export function assertType<T>(
  throw new TypeError(`Expected ${name} type but got ${typeof test}.`);
  }
 }
+
+export function _base64Encode(
+ data: Uint8Array | string,
+ base64Options?: Base64Options,
+): Base64 {
+ let encoded = btoa(
+ typeof data === "string" ? data : String.fromCodePoint(...data),
+ );
+ if (base64Options?.urlSafe) {
+ encoded = encoded
+ .replace(/\+/g, "-")
+ .replace(/\//g, "_")
+ .replace(/=+$/, "");
+ }
+ return encoded;
+}