ostrio:base64

v3.0.0Published 2 years ago

Isomorphic Base64 implementation

Highly efficient isomorphic implementation of Base64 string encoding and decoding. With the support of Unicode, and non-blocking execution via WebWorker. This library has 100% tests coverage, including speed tests.

Features

  1. 100% tests coverage;
  2. Isomorphic, same API for Server and Browser;
  3. Blazing fast, see speed tests;
  4. Non-blocking browser experience, via WebWorkers;
  5. No external dependencies;
  6. Can replace default Meteor's base64 package.

Installation

meteor add ostrio:base64

ES6 Import

1import { Base64 } from 'meteor/ostrio:base64';

Native code support

Native code is disabled by default for Browser. Native code represented as atob, btoa (with extension to support Unicode) in a browser, and Buffer at NodeJS.

Although native code is 10x times faster, its support is enabled only on Server, as natively base64 encoding supports only ASCII symbols in a Browser. To enable native code - pass { useNative: true } in constructor:

1import { Base64 } from 'meteor/ostrio:base64';
2const nativeB64 = new Base64({ useNative: true });

Non-blocking via WebWorker

WebWorker is disabled by default, enable it with passing { allowWebWorker: true } in new Base64() constructor. Once enabled it will be used for all encode/decode calls with the callback. WebWorker is used only if supported by a browser, otherwise, it will fall-back to the main thread. In the real-world application WebWorker, usage will gain you extra FPS, and UI will act more smoothly.

API

.encode()

1base64Instance.encode(plainString [, callback]);
1import { Base64 } from 'meteor/ostrio:base64';
2const base64 = new Base64();
3
4base64.encode('My Plain String'); // Returns 'TXkgUGxhaW4gU3RyaW5n'
5
6// Async, non-blocking via WebWorker (if supported) at browser:
7base64.encode('My Plain String', (error, b64) => {
8  // b64 === 'TXkgUGxhaW4gU3RyaW5n'
9});

.decode()

1base64Instance.decode(base64EncodedString [, callback]);
1import { Base64 } from 'meteor/ostrio:base64';
2const base64 = new Base64();
3
4base64.decode('TXkgUGxhaW4gU3RyaW5n'); // Returns 'My Plain String'
5
6// Async, non-blocking via WebWorker (if supported) at browser:
7base64.decode('TXkgUGxhaW4gU3RyaW5n', (error, str) => {
8  // str === 'My Plain String'
9});

Constructor new Base64()

1import { Base64 } from 'meteor/ostrio:base64';
2new Base64({ allowWebWorker, useNative, supportNonASCII, ejsonCompatible });
  • opts.allowWebWorker {Boolean} - Default: false. Use WebWorker in a Browser if available;
  • opts.useNative {Boolean} - Default in Browser: false; Default on Server: true. Use native atob, btoa and Buffer.from, when available;
  • opts.supportNonASCII {Boolean} - Default: true. Decreases speed, but gives support for whole utf-8 table;
  • opts.ejsonCompatible {Boolean} - Default: false. Compatible mode with EJSON "binary" format, .encode() method will result as Uint8Array when ejsonCompatible is true.
1import { Base64 } from 'meteor/ostrio:base64';
2// Native with WebWorker
3const nativeB64 = new Base64({ allowWebWorker: true, useNative: true });
4
5// Native without WebWorker
6const mtNativeB64 = new Base64({ allowWebWorker: false, useNative: true });
7
8// Use main thread, no WebWorker
9const mtB64 = new Base64({ allowWebWorker: false });

Default base64 package replacement

  1. Download base64-replacement package and place into meteor-app/packages directory, that's it. Run meteor update to make sure new package is applied;
  2. In case of version incompatibility, change base64-replacement version, to the latest available on the mainstream channel;
  3. For more info see base64-replacement package

100% Tests coverage

  1. Clone this package
  2. In Terminal (Console) go to directory where package is cloned
  3. Then run:
# Default
meteor test-packages ./

# With custom port
meteor test-packages ./ --port 8888

Tests include synchronous, asynchronous and speed tests for Browser and NodeJS, for cases with/out the Native code and/or WebWorker usage.

Support this project: