marklister / base64 Goto Github PK

View Code? Open in Web Editor NEW

25.0 4.0 12.0 73 KB

Tiny scala-js compatible base64 encoder/decoder written in idiomatic scala. Available on Maven central.

License: BSD 2-Clause "Simplified" License

Scala 100.00%

base64's Introduction

Base64

Another Base64 encoder / decoder.

This one is

really small
not very efficient (the latest version is not too bad)
liberal license (BSD)*,
simple API
idiomatic scala, and
need not add a dependency to your project. Just copy the one source file to your project.
Scala-js compatible
no Dom required
works on client or server

Getting Started

Using SBT:

libraryDependencies += "com.github.marklister" %% "base64" % "0.3.0"

or for scala-js

libraryDependencies += "com.github.marklister" %%% "base64" % "0.3.0"

API

Simply invoke toBase64 on an Array[Byte] or Seq[Byte] or ArrayBuffer[Byte] or

toByteArray on a String containing a Base64 representation.

Imports

import com.github.marklister.base64.Base64.Encoder 
import com.github.marklister.base64.Base64.Decoder

or use a wildcard:

import com.github.marklister.base64.Base64._

Base64 Url

Two encoding schemes are provided as default: base64 and base64Url. base64 is the default one. To select base64Url

Using implicits -- just make the encode/decode scheme available via an implicit:

implicit val encoding = base64Url

Or you can provide the scheme as an argument to toByteArray or toBase64 eg toBase64(base64Url) or toByteArray(base64)

Padding

Padding is strict for the base64 encode scheme and non-strict for base64Url

To create a non strict scheme:

implicit val encoding = base64.copy(strictPadding=false)

Efficiency

This implementation began life as a toy implementation that chose simplicity over efficiency. The advent of scalaJs meant that the library has a real world target and warranted improving its efficiency. Version 0.2.1 improves efficiency greatly but some legacy inefficiencies remain.

REPL example

[info] Starting scala interpreter...
[info] 
import com.github.marklister.base64.Base64._
Welcome to Scala version 2.10.2 (OpenJDK Server VM, Java 1.7.0_51).
Type in expressions to have them evaluated.
Type :help for more information.

scala> "ABCDEFG".getBytes.toBase64 //Encodes Array[Byte]=>String
res0: String = QUJDREVGRw==

scala> res0.toByteArray //Decodes base64 String=>Array[Byte]
res1: Array[Byte] = Array(65, 66, 67, 68, 69, 70, 71)

scala> res1.sameElements("ABCDEFG".getBytes)
res2: Boolean = true

At one stage this code was released as public domain but there was some discussion about the validity of public domain licences and they don't work on Maven Central. So now it's BSD. If you need some other licence then raise an issue.

base64's People

Contributors

Stargazers

Watchers

Forkers

l15k4 wenwenlin fedefernandez jonas xuwei-k sethtisue ashawley philippus mdedetrich daenyth yisraelu

base64's Issues

indexOf in decode can cause slowness

Decode would be probably faster if you premake lettercode-to-number array, instead of using indexOf on number-to-letter array.

0.2.5 jars are empty on maven central

Hi @marklister
Thanks for this little compact library! However, I noticed that jars don't contain any class/sjs files. 0.2.4 worked like a charm.

http://central.maven.org/maven2/com/github/marklister/base64_sjs0.6_2.12/0.2.5/base64_sjs0.6_2.12-0.2.5.jar
http://central.maven.org/maven2/com/github/marklister/base64_2.12/0.2.5/base64_2.12-0.2.5.jar

Using '=' for padding does not work for URLs

When coding a query parameter to base64, the padding =s make it invalid. Some other URI compatible character should be used instead.

Document using base64Url better

See #6

Publish the latest version

I could find only 0.1.1 from Maven Central, nothing more recent than that.

Improve performance

Lib began as a concise functional and very inefficient look at Base64. Since scala-js it's probably necessary to improve speed and reduce garbage production.

General approach will be to use some mutable data structures and direct array referencing.

Encoding is not compatible with Browser decoding

Hey, I compiled it to javascript using scala-js and if you do something like :

href = "data:application/octet-stream;base64," + data.stripMargin.getBytes.toBase64

Then the downloaded file ends with some incorrectly decoded characters, otherwise it is alright. So I suspect that the Webkit/Chrome decoding is not compatible with this base64 encoding...

Btw to make this scala-js compatible one just need to comment out the specs2 test suite (that doesn't compile to javascript) or rewrite it using some scala-js compliant testing framework like utest and add plugin :

addSbtPlugin("org.scala-js" % "sbt-scalajs" % "0.6.0-M3")

and enable it :

lazy val base64 = (project in file(".")).enablePlugins(org.scalajs.sbtplugin.ScalaJSPlugin)

base64url

Thing to consider. There are more than one standards of base64. base64url, for example, is increasingly popular, because it makes embedding it in urls easier.

You may want to add support for base64url to your lib, unless you consider it too much bloat.

Strict padding unnecessary -- causes JS interop problem

JS WebCrytpoAPI produces Base64URL encoded strings in jws mode.

See the code here to produce those
http://stackoverflow.com/questions/33642310/is-there-a-way-to-get-the-components-of-an-rsa-key-in-the-webcrypto-api

The following JS code does the trick to convert it

function encodeURL(str){
    return str.replace(/\+/g, '-').replace(/\//g, '_').replace(/\=+$/, '');
}

function decodeUrl(str){
    str = (str + '===').slice(0, str.length + (str.length % 4));
    return str.replace(/-/g, '+').replace(/_/g, '/');
}

and then one can use window.atob

I tried the library here, but it gives an error

def enc not tail recursive.

Could be replaced by a fold or something.

Release with latest scalajs 1.x?

Hi @marklister

I was wondering whether you could release a new version against the latest scalajs? It's actually luckily humming along if it weren't for those big upgrades :-)

Thanks a lot,
Tanju

Consider structures other than `Array[Byte]`

From #6 (@bblfish)

Perhaps there is an extra improvement you can add. Is it possible to abstract somewhat from an array? For example the JS seems to return a ArrayBuffer which I think can be turned into a java.nio.ByteBuffer using TypedArrayBufferBridge.

So it would be useful to have a method that could work with those elements and not just arrays. I am not yet quite sure what the best abstraction here would be... Certainly given that you don't need to change the source object, an Array is too precise.

There is some example code here using a ByteBuffer https://gist.github.com/mseddon/1cfcb0970272cac40497

String concat not preferred

String Concat is a bad idea.