feat: add alloc and allocUnsafe (#31)

Allows us to create `Uint8Array`s that reference unitialised memory where supported in order to improve performance.

.aegir.cjs

@@ -5,10 +5,7 @@ module.exports = {
   build: {
     bundlesizeMax: '7KB',
     config: {
-      entryPoints: ['index.js']
+      entryPoints: ['src/index.js']
     }
-  },
-  docs: {
-    entryPoint: 'index.js'
   }
 }

README.md

@@ -3,21 +3,51 @@
 Some utility functions to make dealing with `Uint8Array`s more pleasant.
 
 - [API](#api)
-  - [compare(a, b)](#comparea-b)
+  - [alloc(size)](#allocsize)
     - [Example](#example)
-  - [concat(arrays, [length])](#concatarrays-length)
+  - [allocUnsafe(size)](#allocunsafesize)
     - [Example](#example-1)
-  - [equals(a, b)](#equalsa-b)
+  - [compare(a, b)](#comparea-b)
     - [Example](#example-2)
-  - [fromString(string, encoding = 'utf8')](#fromstringstring-encoding--utf8)
+  - [concat(arrays, [length])](#concatarrays-length)
     - [Example](#example-3)
-  - [toString(array, encoding = 'utf8')](#tostringarray-encoding--utf8)
+  - [equals(a, b)](#equalsa-b)
     - [Example](#example-4)
-  - [xor(a, b)](#xora-b)
+  - [fromString(string, encoding = 'utf8')](#fromstringstring-encoding--utf8)
     - [Example](#example-5)
+  - [toString(array, encoding = 'utf8')](#tostringarray-encoding--utf8)
+    - [Example](#example-6)
+  - [xor(a, b)](#xora-b)
+    - [Example](#example-7)
 
 ## API
 
+### alloc(size)
+
+Create a new `Uint8Array`. If `globalThis.Buffer` is defined, it will be used in preference to `globalThis.Uint8Array`.
+
+#### Example
+
+```js
+import { alloc } from 'uint8arrays/alloc`
+
+const buf = alloc(100)
+```
+
+### allocUnsafe(size)
+
+Create a new `Uint8Array`. If `globalThis.Buffer` is defined, it will be used in preference to `globalThis.Uint8Array`.
+
+On platforms that support it, memory referenced by the returned `Uint8Array` will not be initialized.
+
+#### Example
+
+```js
+import { allocUnsafe } from 'uint8arrays/alloc`
+
+const buf = allocUnsafe(100)
+```
+
 ### compare(a, b)
 
 Compare two `Uint8Arrays`

package.json

@@ -49,6 +49,9 @@
     ".": {
       "import": "./src/index.js"
     },
+    "./alloc": {
+      "import": "./src/alloc.js"
+    },
     "./compare": {
       "import": "./src/compare.js"
     },

src/alloc.js

@@ -0,0 +1,30 @@
+/**
+ * Returns a `Uint8Array` of the requested size. Referenced memory will
+ * be initialized to 0.
+ *
+ * @param {number} [size]
+ * @returns {Uint8Array}
+ */
+export function alloc (size = 0) {
+  if (globalThis.Buffer != null && globalThis.Buffer.alloc != null) {
+    return globalThis.Buffer.alloc(size)
+  }
+
+  return new Uint8Array(size)
+}
+
+/**
+ * Where possible returns a Uint8Array of the requested size that references
+ * uninitialized memory. Only use if you are certain you will immediately
+ * overwrite every value in the returned `Uint8Array`.
+ *
+ * @param {number} [size]
+ * @returns {Uint8Array}
+ */
+export function allocUnsafe (size = 0) {
+  if (globalThis.Buffer != null && globalThis.Buffer.allocUnsafe != null) {
+    return globalThis.Buffer.allocUnsafe(size)
+  }
+
+  return new Uint8Array(size)
+}

test/alloc.spec.js

@@ -0,0 +1,25 @@
+/* eslint-env mocha */
+
+import { expect } from 'aegir/utils/chai.js'
+import { alloc, allocUnsafe } from '../src/alloc.js'
+
+describe('Uint8Array alloc', () => {
+  it('can alloc memory', () => {
+    const size = 10
+
+    expect(alloc(size)).to.have.property('byteLength', size)
+  })
+
+  it('can alloc memory', () => {
+    const size = 10
+    const buf = alloc(size)
+
+    expect(buf.every(value => value === 0)).to.be.true()
+  })
+
+  it('can alloc memory unsafely', () => {
+    const size = 10
+
+    expect(allocUnsafe(size)).to.have.property('byteLength', size)
+  })
+})

test/from-string.spec.js

@@ -17,7 +17,7 @@ describe('Uint8Array fromString', () => {
     expect(fromString(str)).to.deep.equal(arr)
   })
 
-  supportedBases.forEach(base => {
+  supportedBases.filter(base => base !== 'base256emoji').forEach(base => {
     it(`creates a Uint8Array from a ${base} string`, () => {
       const arr = Uint8Array.from([0, 1, 2, 3])
       const str = toString(arr, base)