fix: Use subpath imports to choose Node or vanilla JS environment (#88)

ukstv · achingbrain · web-flow · commit e43f1f47bdf7 · 2024-03-13T14:20:27.000+01:00
Import buffer from `node:buffer` instead of using `globalThis.Buffer` to prevent accidentally using janky polyfills and allow bundlers to cleanly supply valid versions. Fixes: #87 --------- Co-authored-by: achingbrain <alex@achingbrain.net>
diff --git a/README.md b/README.md
@@ -5,6 +5,21 @@
 
 # About
 
+<!--
+
+!IMPORTANT!
+
+Everything in this README between "# About" and "# Install" is automatically
+generated and will be overwritten the next time the doc generator is run.
+
+To make changes to this section, please update the @packageDocumentation section
+of src/index.js or src/index.ts
+
+To experiment with formatting, please run "npm run docs" from the root of this
+repo and examine the changes made.
+
+-->
+
 `Uint8Array`s bring memory-efficient(ish) byte handling to browsers - they are similar to Node.js `Buffer`s but lack a lot of the utility methods present on that class.
 
 This module exports a number of function that let you do common operations - joining Uint8Arrays together, seeing if they have the same contents etc.
@@ -13,7 +28,7 @@ Since Node.js `Buffer`s are also `Uint8Array`s, it falls back to `Buffer` intern
 
 ## alloc(size)
 
-Create a new `Uint8Array`. If `globalThis.Buffer` is defined, it will be used in preference to `globalThis.Uint8Array`.
+Create a new `Uint8Array`. When running under Node.js, `Buffer` will be used in preference to `Uint8Array`.
 
 ### Example
 
@@ -25,7 +40,7 @@ const buf = alloc(100)
 
 ## allocUnsafe(size)
 
-Create a new `Uint8Array`. If `globalThis.Buffer` is defined, it will be used in preference to `globalThis.Uint8Array`.
+Create a new `Uint8Array`. When running under Node.js, `Buffer` will be used in preference to `Uint8Array`.
 
 On platforms that support it, memory referenced by the returned `Uint8Array` will not be initialized.
 
diff --git a/benchmarks/alloc.js b/benchmarks/alloc.js
@@ -6,7 +6,7 @@ $ npx playwright-test benchmarks/alloc.js --runner benchmark
 */
 
 import Benchmark from 'benchmark'
-import { alloc, allocUnsafe } from '../src/dist/alloc.js'
+import { alloc, allocUnsafe } from '#alloc'
 
 const LENGTH = 1024
 
diff --git a/benchmarks/concat.js b/benchmarks/concat.js
@@ -6,9 +6,9 @@ $ npx playwright-test benchmarks/concat.js --runner benchmark
 */
 
 import Benchmark from 'benchmark'
-import { allocUnsafe } from '../dist/src/alloc.js'
-import { concat } from '../dist/src/concat.js'
-import { fromString } from '../dist/src/from-string.js'
+import { allocUnsafe } from '#alloc'
+import { concat } from '#concat'
+import { fromString } from '#from-string'
 
 const string = 'Hello world, this is a Uint8Array created from a string'
 const DATA1 = fromString(string)
diff --git a/benchmarks/from-string.js b/benchmarks/from-string.js
@@ -6,7 +6,7 @@ $ npx playwright-test benchmarks/from-string.js --runner benchmark
 */
 
 import Benchmark from 'benchmark'
-import { fromString } from '../dist/src/from-string.js'
+import { fromString } from '#from-string'
 
 const string = 'Hello world, this is a Uint8Array created from a string'
 const DATA = fromString(string)
diff --git a/benchmarks/to-string.js b/benchmarks/to-string.js
@@ -6,8 +6,8 @@ $ npx playwright-test benchmarks/to-string.js --runner benchmark
 */
 
 import Benchmark from 'benchmark'
-import { fromString } from '../dist/src/from-string.js'
-import { toString } from '../dist/src/to-string.js'
+import { fromString } from '#from-string'
+import { toString } from '#to-string'
 
 const string = 'Hello world, this is a Uint8Array created from a string'
 const DATA = fromString(string)
diff --git a/package.json b/package.json
@@ -47,14 +47,17 @@
     },
     "./alloc": {
       "types": "./dist/src/alloc.d.ts",
+      "node": "./dist/src/alloc.node.js",
       "import": "./dist/src/alloc.js"
     },
     "./compare": {
       "types": "./dist/src/compare.d.ts",
+      "node": "./dist/src/compare.node.js",
       "import": "./dist/src/compare.js"
     },
     "./concat": {
       "types": "./dist/src/concat.d.ts",
+      "node": "./dist/src/concat.node.js",
       "import": "./dist/src/concat.js"
     },
     "./equals": {
@@ -63,17 +66,51 @@
     },
     "./from-string": {
       "types": "./dist/src/from-string.d.ts",
+      "node": "./dist/src/from-string.node.js",
       "import": "./dist/src/from-string.js"
     },
     "./to-string": {
       "types": "./dist/src/to-string.d.ts",
+      "node": "./dist/src/to-string.node.js",
       "import": "./dist/src/to-string.js"
     },
     "./xor": {
       "types": "./dist/src/xor.d.ts",
       "import": "./dist/src/xor.js"
     }
   },
+  "imports": {
+    "#util/as-uint8array": {
+      "types": "./dist/src/util/as-uint8array.d.ts",
+      "node": "./dist/src/util/as-uint8array.node.js",
+      "import": "./dist/src/util/as-uint8array.js"
+    },
+    "#alloc": {
+      "types": "./dist/src/alloc.d.ts",
+      "node": "./dist/src/alloc.node.js",
+      "import": "./dist/src/alloc.js"
+    },
+    "#compare": {
+      "types": "./dist/src/compare.d.ts",
+      "node": "./dist/src/compare.node.js",
+      "import": "./dist/src/compare.js"
+    },
+    "#concat": {
+      "types": "./dist/src/concat.d.ts",
+      "node": "./dist/src/concat.node.js",
+      "import": "./dist/src/concat.js"
+    },
+    "#from-string": {
+      "types": "./dist/src/from-string.d.ts",
+      "node": "./dist/src/from-string.node.js",
+      "import": "./dist/src/from-string.js"
+    },
+    "#to-string": {
+      "types": "./dist/src/to-string.d.ts",
+      "node": "./dist/src/to-string.node.js",
+      "import": "./dist/src/to-string.js"
+    }
+  },
   "eslintConfig": {
     "extends": "ipfs",
     "parserOptions": {
@@ -187,5 +224,13 @@
     "@types/benchmark": "^2.1.1",
     "aegir": "^42.2.3",
     "benchmark": "^2.1.4"
+  },
+  "react-native": {
+    "#util/as-uint8array": "./dist/src/util/as-uint8array.js",
+    "#alloc": "./dist/src/alloc.js",
+    "#compare": "./dist/src/compare.js",
+    "#concat": "./dist/src/concat.js",
+    "#from-string": "./dist/src/from-string.js",
+    "#to-string": "./dist/src/to-string.js"
   }
 }
diff --git a/src/alloc.node.ts b/src/alloc.node.ts
@@ -0,0 +1,19 @@
+import { Buffer } from 'node:buffer'
+import { asUint8Array } from '#util/as-uint8array'
+
+/**
+ * Returns a `Uint8Array` of the requested size. Referenced memory will
+ * be initialized to 0.
+ */
+export function alloc (size: number = 0): Uint8Array {
+  return asUint8Array(Buffer.alloc(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`.
+ */
+export function allocUnsafe (size: number = 0): Uint8Array {
+  return asUint8Array(Buffer.allocUnsafe(size))
+}
diff --git a/src/alloc.ts b/src/alloc.ts
@@ -1,14 +1,8 @@
-import { asUint8Array } from './util/as-uint8array.js'
-
 /**
  * Returns a `Uint8Array` of the requested size. Referenced memory will
  * be initialized to 0.
  */
 export function alloc (size: number = 0): Uint8Array {
-  if (globalThis.Buffer?.alloc != null) {
-    return asUint8Array(globalThis.Buffer.alloc(size))
-  }
-
   return new Uint8Array(size)
 }
 
@@ -18,9 +12,5 @@ export function alloc (size: number = 0): Uint8Array {
  * overwrite every value in the returned `Uint8Array`.
  */
 export function allocUnsafe (size: number = 0): Uint8Array {
-  if (globalThis.Buffer?.allocUnsafe != null) {
-    return asUint8Array(globalThis.Buffer.allocUnsafe(size))
-  }
-
   return new Uint8Array(size)
 }
diff --git a/src/compare.node.ts b/src/compare.node.ts
@@ -0,0 +1,8 @@
+import { Buffer } from 'node:buffer'
+
+/**
+ * Can be used with Array.sort to sort and array with Uint8Array entries
+ */
+export function compare (a: Uint8Array, b: Uint8Array): number {
+  return Buffer.compare(a, b)
+}
diff --git a/src/compare.ts b/src/compare.ts
@@ -2,10 +2,6 @@
  * Can be used with Array.sort to sort and array with Uint8Array entries
  */
 export function compare (a: Uint8Array, b: Uint8Array): number {
-  if (globalThis.Buffer != null) {
-    return globalThis.Buffer.compare(a, b)
-  }
-
   for (let i = 0; i < a.byteLength; i++) {
     if (a[i] < b[i]) {
       return -1
diff --git a/src/concat.node.ts b/src/concat.node.ts
@@ -0,0 +1,9 @@
+import { Buffer } from 'node:buffer'
+import { asUint8Array } from '#util/as-uint8array'
+
+/**
+ * Returns a new Uint8Array created by concatenating the passed Uint8Arrays
+ */
+export function concat (arrays: Uint8Array[], length?: number): Uint8Array {
+  return asUint8Array(Buffer.concat(arrays, length))
+}
diff --git a/src/concat.ts b/src/concat.ts
@@ -1,14 +1,10 @@
-import { allocUnsafe } from './alloc.js'
-import { asUint8Array } from './util/as-uint8array.js'
+import { allocUnsafe } from '#alloc'
+import { asUint8Array } from '#util/as-uint8array'
 
 /**
  * Returns a new Uint8Array created by concatenating the passed Uint8Arrays
  */
 export function concat (arrays: Uint8Array[], length?: number): Uint8Array {
-  if (globalThis.Buffer != null) {
-    return asUint8Array(globalThis.Buffer.concat(arrays, length))
-  }
-
   if (length == null) {
     length = arrays.reduce((acc, curr) => acc + curr.length, 0)
   }
diff --git a/src/from-string.node.ts b/src/from-string.node.ts
@@ -0,0 +1,27 @@
+import { Buffer } from 'node:buffer'
+import bases, { type SupportedEncodings } from './util/bases.js'
+import { asUint8Array } from '#util/as-uint8array'
+
+export type { SupportedEncodings }
+
+/**
+ * Create a `Uint8Array` from the passed string
+ *
+ * Supports `utf8`, `utf-8`, `hex`, and any encoding supported by the multiformats module.
+ *
+ * Also `ascii` which is similar to node's 'binary' encoding.
+ */
+export function fromString (string: string, encoding: SupportedEncodings = 'utf8'): Uint8Array {
+  const base = bases[encoding]
+
+  if (base == null) {
+    throw new Error(`Unsupported encoding "${encoding}"`)
+  }
+
+  if (encoding === 'utf8' || encoding === 'utf-8') {
+    return asUint8Array(Buffer.from(string, 'utf-8'))
+  }
+
+  // add multibase prefix
+  return base.decoder.decode(`${base.prefix}${string}`) // eslint-disable-line @typescript-eslint/restrict-template-expressions
+}
diff --git a/src/from-string.ts b/src/from-string.ts
@@ -1,4 +1,3 @@
-import { asUint8Array } from './util/as-uint8array.js'
 import bases, { type SupportedEncodings } from './util/bases.js'
 
 export type { SupportedEncodings }
@@ -17,10 +16,6 @@ export function fromString (string: string, encoding: SupportedEncodings = 'utf8
     throw new Error(`Unsupported encoding "${encoding}"`)
   }
 
-  if ((encoding === 'utf8' || encoding === 'utf-8') && globalThis.Buffer != null && globalThis.Buffer.from != null) {
-    return asUint8Array(globalThis.Buffer.from(string, 'utf-8'))
-  }
-
   // add multibase prefix
   return base.decoder.decode(`${base.prefix}${string}`) // eslint-disable-line @typescript-eslint/restrict-template-expressions
 }
diff --git a/src/index.ts b/src/index.ts
@@ -9,7 +9,7 @@
  *
  * ## alloc(size)
  *
- * Create a new `Uint8Array`. If `globalThis.Buffer` is defined, it will be used in preference to `globalThis.Uint8Array`.
+ * Create a new `Uint8Array`. When running under Node.js, `Buffer` will be used in preference to `Uint8Array`.
  *
  * ### Example
  *
@@ -21,7 +21,7 @@
  *
  * ## allocUnsafe(size)
  *
- * Create a new `Uint8Array`. If `globalThis.Buffer` is defined, it will be used in preference to `globalThis.Uint8Array`.
+ * Create a new `Uint8Array`. When running under Node.js, `Buffer` will be used in preference to `Uint8Array`.
  *
  * On platforms that support it, memory referenced by the returned `Uint8Array` will not be initialized.
  *
@@ -143,12 +143,12 @@
  * ```
  */
 
-import { compare } from './compare.js'
-import { concat } from './concat.js'
 import { equals } from './equals.js'
-import { fromString } from './from-string.js'
-import { toString } from './to-string.js'
 import { xor } from './xor.js'
+import { compare } from '#compare'
+import { concat } from '#concat'
+import { fromString } from '#from-string'
+import { toString } from '#to-string'
 
 export {
   compare,
diff --git a/src/to-string.node.ts b/src/to-string.node.ts
@@ -0,0 +1,26 @@
+import { Buffer } from 'node:buffer'
+import bases, { type SupportedEncodings } from './util/bases.js'
+
+export type { SupportedEncodings }
+
+/**
+ * Turns a `Uint8Array` into a string.
+ *
+ * Supports `utf8`, `utf-8` and any encoding supported by the multibase module.
+ *
+ * Also `ascii` which is similar to node's 'binary' encoding.
+ */
+export function toString (array: Uint8Array, encoding: SupportedEncodings = 'utf8'): string {
+  const base = bases[encoding]
+
+  if (base == null) {
+    throw new Error(`Unsupported encoding "${encoding}"`)
+  }
+
+  if (encoding === 'utf8' || encoding === 'utf-8') {
+    return Buffer.from(array.buffer, array.byteOffset, array.byteLength).toString('utf8')
+  }
+
+  // strip multibase prefix
+  return base.encoder.encode(array).substring(1)
+}
diff --git a/src/to-string.ts b/src/to-string.ts
@@ -16,10 +16,6 @@ export function toString (array: Uint8Array, encoding: SupportedEncodings = 'utf
     throw new Error(`Unsupported encoding "${encoding}"`)
   }
 
-  if ((encoding === 'utf8' || encoding === 'utf-8') && globalThis.Buffer != null && globalThis.Buffer.from != null) {
-    return globalThis.Buffer.from(array.buffer, array.byteOffset, array.byteLength).toString('utf8')
-  }
-
   // strip multibase prefix
   return base.encoder.encode(array).substring(1)
 }
diff --git a/src/util/as-uint8array.node.ts b/src/util/as-uint8array.node.ts
@@ -0,0 +1,7 @@
+/**
+ * To guarantee Uint8Array semantics, convert nodejs Buffers
+ * into vanilla Uint8Arrays
+ */
+export function asUint8Array (buf: Uint8Array): Uint8Array {
+  return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)
+}
diff --git a/src/util/as-uint8array.ts b/src/util/as-uint8array.ts
@@ -3,9 +3,5 @@
  * into vanilla Uint8Arrays
  */
 export function asUint8Array (buf: Uint8Array): Uint8Array {
-  if (globalThis.Buffer != null) {
-    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)
-  }
-
   return buf
 }
diff --git a/src/util/bases.ts b/src/util/bases.ts
diff --git a/src/xor.ts b/src/xor.ts
diff --git a/test/alloc.spec.ts b/test/alloc.spec.ts
diff --git a/test/compare.spec.ts b/test/compare.spec.ts
diff --git a/test/concat.spec.ts b/test/concat.spec.ts
diff --git a/test/from-string.spec.ts b/test/from-string.spec.ts
diff --git a/test/to-string.spec.ts b/test/to-string.spec.ts
diff --git a/tsconfig.json b/tsconfig.json
