feat: add implementation

Author: achingbrain

.aegir.js

@@ -0,0 +1,7 @@
+'use strict'
+
+module.exports = {
+  webpack: {
+    entry: './index.js'
+  }
+}

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

README.md

@@ -0,0 +1,112 @@
+# Uint8Arrays <!-- omit in toc -->
+
+Some utility functions to make dealing with `Uint8Array`s more pleasant.
+
+- [API](#api)
+  - [compare(a, b)](#comparea-b)
+    - [Example](#example)
+  - [concat(arrays, [length])](#concatarrays-length)
+    - [Example](#example-1)
+  - [equals(a, b)](#equalsa-b)
+    - [Example](#example-2)
+  - [fromString(string, encoding = 'utf8')](#fromstringstring-encoding--utf8)
+    - [Example](#example-3)
+  - [toString(array, encoding = 'utf8')](#tostringarray-encoding--utf8)
+    - [Example](#example-4)
+
+## API
+
+### compare(a, b)
+
+Compare two `Uint8Arrays`
+
+#### Example
+
+```js
+const compare = require('uint8arrays/compare')
+
+const arrays = [
+  Uint8Array.from([3, 4, 5]),
+  Uint8Array.from([0, 1, 2])
+]
+
+const sorted = arrays.sort(compare)
+
+console.info(sorted)
+// [
+//    Uint8Array[0, 1, 2]
+//    Uint8Array[3, 4, 5]
+// ]
+```
+
+### concat(arrays, [length])
+
+Concatenate one or more array-likes and return a `Uint8Array` with their contents.
+
+If you know the length of the arrays, pass it as a second parameter, otherwise it will be calculated by traversing the list of arrays.
+
+#### Example
+
+```js
+const concat = require('uint8arrays/concat')
+
+const arrays = [
+  Uint8Array.from([0, 1, 2]),
+  Uint8Array.from([3, 4, 5])
+]
+
+const all = concat(arrays, 6)
+
+console.info(all)
+// Uint8Array[0, 1, 2, 3, 4, 5]
+```
+
+### equals(a, b)
+
+Returns true if the two arrays are the same array or if they have the same length and contents.
+
+#### Example
+
+```js
+const equals = require('uint8arrays/equals')
+
+const a = Uint8Array.from([0, 1, 2])
+const b = Uint8Array.from([3, 4, 5])
+const c = Uint8Array.from([0, 1, 2])
+
+console.info(equals(a, b)) // false
+console.info(equals(a, c)) // true
+console.info(equals(a, a)) // true
+```
+
+### fromString(string, encoding = 'utf8')
+
+Returns a new `Uint8Array` created from the passed string and interpreted as the passed encoding.
+
+Supports `utf8` and any of the [multiformats encodings](https://www.npmjs.com/package/multibase#supported-encodings-see-srcconstantsjs).
+
+#### Example
+
+```js
+const fromString = require('uint8arrays/from-string')
+
+console.info(fromString('hello world')) // Uint8Array[104, 101 ...
+console.info(fromString('00010203aabbcc', 'base16')) // Uint8Array[0, 1 ...
+console.info(fromString('AAECA6q7zA', 'base64')) // Uint8Array[0, 1 ...
+```
+
+### toString(array, encoding = 'utf8')
+
+Returns a string created from the passed `Uint8Array` in the passed encoding.
+
+Supports `utf8` and any of the [multiformats encodings](https://www.npmjs.com/package/multibase#supported-encodings-see-srcconstantsjs).
+
+#### Example
+
+```js
+const fromString = require('uint8arrays/from-string')
+
+console.info(toString(Uint8Array.from([104, 101...]))) // 'hello world'
+console.info(toString(Uint8Array.from([0, 1, 2...]), 'base16')) // '00010203aabbcc'
+console.info(toString(Uint8Array.from([0, 1, 2...]), 'base64')) // 'AAECA6q7zA'
+```

compare.js

@@ -0,0 +1,32 @@
+'use strict'
+
+/**
+ * Can be used with Array.sort to sort and array with Uint8Array entries
+ *
+ * @param {Uint8Array} a
+ * @param {Uint8Array} b
+ * @returns {Number}
+ */
+function compare (a, b) {
+  for (let i = 0; i < a.byteLength; i++) {
+    if (a[i] < b[i]) {
+      return -1
+    }
+
+    if (a[i] > b[i]) {
+      return 1
+    }
+  }
+
+  if (a.byteLength > b.byteLength) {
+    return 1
+  }
+
+  if (a.byteLength < b.byteLength) {
+    return -1
+  }
+
+  return 0
+}
+
+module.exports = compare

concat.js

@@ -0,0 +1,26 @@
+'use strict'
+
+/**
+ * Returns a new Uint8Array created by concatenating the passed ArrayLikes
+ *
+ * @param {Array<ArrayLike<number>>} arrays
+ * @param {Number} length
+ * @returns {Uint8Array}
+ */
+function concat (arrays, length) {
+  if (!length) {
+    length = arrays.reduce((acc, curr) => acc + curr.length, 0)
+  }
+
+  const output = new Uint8Array(length)
+  let offset = 0
+
+  for (const arr of arrays) {
+    output.set(arr, offset)
+    offset += arr.length
+  }
+
+  return output
+}
+
+module.exports = concat

equals.js

@@ -0,0 +1,28 @@
+'use strict'
+
+/**
+ * Returns true if the two passed Uint8Arrays have the same content
+ *
+ * @param {Uint8Array} a
+ * @param {Uint8Array} b
+ * @returns {boolean}
+ */
+function equals (a, b) {
+  if (a === b) {
+    return true
+  }
+
+  if (a.byteLength !== b.byteLength) {
+    return false
+  }
+
+  for (let i = 0; i < a.byteLength; i++) {
+    if (a[i] !== b[i]) {
+      return false
+    }
+  }
+
+  return true
+}
+
+module.exports = equals

from-string.js

@@ -0,0 +1,29 @@
+'use strict'
+
+const { names } = require('multibase/src/constants')
+const { TextEncoder } = require('web-encoding')
+const utf8Encoder = new TextEncoder()
+
+/**
+ * Create a `Uint8Array` from the passed string
+ *
+ * @param {String} string
+ * @param {String} [encoding=utf8] utf8, base16, base64, base64urlpad, etc
+ * @returns {Uint8Array}
+ * @see {@link https://www.npmjs.com/package/multibase|multibase} for supported encodings other than `utf8`
+ */
+function fromString (string, encoding = 'utf8') {
+  if (encoding === 'utf8' || encoding === 'utf-8') {
+    return utf8Encoder.encode(string)
+  }
+
+  const codec = names[encoding]
+
+  if (!codec) {
+    throw new Error('Unknown base')
+  }
+
+  return codec.decode(string)
+}
+
+module.exports = fromString

index.js

@@ -0,0 +1,9 @@
+'use strict'
+
+module.exports = {
+  compare: require('./compare'),
+  concat: require('./concat'),
+  equals: require('./equals'),
+  fromString: require('./from-string'),
+  toString: require('./to-string')
+}