@helia/unixfs 1.4.2 → 2.0.0

package/README.md

@@ -4,7 +4,7 @@
   </a>
 </p>
 
-# @helia/unixfs <!-- omit in toc -->
+# @helia/unixfs
 
 [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech)
 [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech)
@@ -13,21 +13,56 @@
 
 > A Helia-compatible wrapper for UnixFS
 
-## Table of contents <!-- omit in toc -->
+# About
 
-- [Install](#install)
-  - [Browser `<script>` tag](#browser-script-tag)
-- [API Docs](#api-docs)
-- [License](#license)
-- [Contribute](#contribute)
+`@helia/unixfs` is an implementation of a filesystem compatible with Helia.
 
-## Install
+See the interface for all available operations.
+
+## Example - Creating files and directories
+
+```typescript
+import { createHelia } from 'helia'
+import { unixfs } from '@helia/unixfs'
+
+const helia = createHelia({
+  // ... helia config
+})
+const fs = unixfs(helia)
+
+// create an empty dir and a file, then add the file to the dir
+const emptyDirCid = await fs.addDirectory()
+const fileCid = await fs.addBytes(Uint8Array.from([0, 1, 2, 3]))
+const updateDirCid = await fs.cp(fileCid, emptyDirCid, 'foo.txt')
+
+// or doing the same thing as a stream
+for await (const entry of fs.addAll([{
+  path: 'foo.txt',
+  content: Uint8Array.from([0, 1, 2, 3])
+}])) {
+  console.info(entry)
+}
+```
+
+## Example - Recursively adding a directory
+
+Node.js-compatibly environments only:
+
+```typescript
+import { globSource } from '@helia/unixfs'
+
+for await (const entry of fs.addAll(globSource('path/to/containing/dir', 'glob-pattern'))) {
+  console.info(entry)
+}
+```
+
+# Install
 
 ```console
 $ npm i @helia/unixfs
 ```
 
-### Browser `<script>` tag
+## Browser `<script>` tag
 
 Loading this module through a script tag will make it's exports available as `HeliaUnixfs` in the global namespace.
 
@@ -35,18 +70,18 @@ Loading this module through a script tag will make it's exports available as `He
 <script src="https://unpkg.com/@helia/unixfs/dist/index.min.js"></script>
 ```
 
-## API Docs
+# API Docs
 
 - <https://ipfs.github.io/helia-unixfs/modules/_helia_unixfs.html>
 
-## License
+# 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>)
 
-## Contribute
+# Contribute
 
 Contributions welcome! Please check out [the issues](https://github.com/ipfs/helia-unixfs/issues).