docs: add example, fix up README

Author: rvagg

README.md

@@ -1,16 +1,55 @@
-# js-sha3
+# @multiformats/sha3
 
-Multiformats hash functions for SHA3.
+SHA3 (and related) multihash hashers for [multiformats](https://github.com/multiformats/js-multiformats).
+
+`MultihashHashers`s are exported from this library, they produce `MultihashDigest`s. Details about these can be found in the [multiformats multihash interface definitions](https://github.com/multiformats/js-multiformats/blob/master/src/hashes/interface.ts).
 
 ```js
-import multiformats from 'multiformats/basics'
-import sha3 from '@multiformats/sha3'
+import * as Block from 'multiformats/block'
+import * as codec from '@ipld/dag-cbor'
+import { sha3256 as hasher } from '@multiformats/sha3'
+
+async function run () {
+  const value = { hello: 'world' }
+  const block = await Block.encode({ value, hasher, codec })
+  console.log(block.cid)
+  // -> CID(bafyrmidyqnbqbeh5lmkwavjizfmsz6ezwvjleweh5frwk56akfyugoio2e)
+}
+
+run().catch(console.error)
+```
+
+## Usage
+
+The `@multiformats/sha3` package exports `sha3*`, `shake*` and `keccak*` `MultihashHasher`s. The Multicodecs [table](https://github.com/multiformats/multicodec/blob/master/table.csv) defines these multihashes.
+
+The following `MultihashHasher`s are exported:
 
-const { multihash } = multiformats
-multihash.add(sha3)
+* `sha3224` - SHA3-224
+* `sha3256` - SHA3-256
+* `sha3384` - SHA3-384
+* `sha3512` - SHA3-512
+* `shake128` - SHAKE-128 (256 output bits)
+* `shake256` - SHAKE-256 (512 output bits)
+* `keccak224` - KECCAK-224
+* `keccak256` - KECCAK-256
+* `keccak384` - KECCAK-384
+* `keccak512` - KECCAK-512
 
-const data = new Uint8Array([...someData])
-const hash = await multihash.hash(data, 'sha3-384')
+
+e.g. he `sha3-384`, multicodec code `0x15`, may be imported as:
+
+```js
+import { sha3384 } from '@multiformats/sha3'
 ```
 
-This package contains hash functions for `sha3-224`, `sha3-256`, `sha3-384`,`sha3-512`, `shake-128`, `shake-256`, `keccak-224`, `keccak-256`, `keccak-384`, and `keccak-512`.
+## License
+
+Licensed under either of
+
+ * Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / http://www.apache.org/licenses/LICENSE-2.0)
+ * MIT ([LICENSE-MIT](LICENSE-MIT) / http://opensource.org/licenses/MIT)
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

example.js

@@ -0,0 +1,12 @@
+import * as Block from 'multiformats/block'
+import * as codec from '@ipld/dag-cbor'
+import { sha3256 as hasher } from '@multiformats/sha3'
+
+async function run () {
+  const value = { hello: 'world' }
+  const block = await Block.encode({ value, hasher, codec })
+  console.log(block.cid)
+  // -> CID(bafyrmidyqnbqbeh5lmkwavjizfmsz6ezwvjleweh5frwk56akfyugoio2e)
+}
+
+run().catch(console.error)

index.js

@@ -11,10 +11,10 @@ function encoder (fn) {
   return (/** @type {Uint8Array} */ b) => new Uint8Array(fn.array(b))
 }
 
-export const sha3512 = from({ code: 0x14, name: 'sha3-512', encode: encoder(sha3.sha3_512) })
-export const sha3384 = from({ code: 0x15, name: 'sha3-384', encode: encoder(sha3.sha3_384) })
-export const sha3256 = from({ code: 0x16, name: 'sha3-256', encode: encoder(sha3.sha3_256) })
 export const sha3224 = from({ code: 0x17, name: 'sha3-224', encode: encoder(sha3.sha3_224) })
+export const sha3256 = from({ code: 0x16, name: 'sha3-256', encode: encoder(sha3.sha3_256) })
+export const sha3384 = from({ code: 0x15, name: 'sha3-384', encode: encoder(sha3.sha3_384) })
+export const sha3512 = from({ code: 0x14, name: 'sha3-512', encode: encoder(sha3.sha3_512) })
 export const shake128 = from({ code: 0x18, name: 'shake-128', encode: (b) => new Uint8Array(sha3.shake128.array(b, 256)) })
 export const shake256 = from({ code: 0x19, name: 'shake-256', encode: (b) => new Uint8Array(sha3.shake256.array(b, 512)) })
 export const keccak224 = from({ code: 0x1a, name: 'keccak-224', encode: encoder(sha3.keccak224) })

package.json

@@ -35,6 +35,7 @@
     "multiformats": "^9.4.1"
   },
   "devDependencies": {
+    "@ipld/dag-cbor": "^6.0.5",
     "c8": "^7.7.3",
     "chai": "^4.3.4",
     "ipjs": "^5.0.2",