victorb/js-ipfs-unixfs

JavaScript implementation of IPFS' unixfs (a Unix FileSystem representation on top of a MerkleDAG)

ipfs-unixfs JavaScript Implementation

JavaScript implementation of IPFS' unixfs (a Unix FileSystem representation on top of a MerkleDAG)

The unixfs spec can be found inside the ipfs/specs repository

Table of Contents

• Install
  • npm
  • Use in Node.js
  • Use in a browser with browserify, webpack or any other bundler
  • Use in a browser Using a script tag
• Usage
  • Examples
    • Create a file composed by several blocks
    • Create a directory that contains several files
• API
  • unixfs Data Structure
  • create an unixfs Data element
  • add and remove a block size to the block size list
  • get total fileSize
  • marshal and unmarshal
• Contribute
• License

Install

npm

> npm i ipfs-unixfs

Use in Node.js

var Unixfs = require('ipfs-unixfs')

Use in a browser with browserify, webpack or any other bundler

The code published to npm that gets loaded on require is in fact a ES5 transpiled version with the right shims added. This means that you can require it and use with your favourite bundler without having to adjust asset management process.

var Unixfs = require('ipfs-unixfs')

Use in a browser Using a script tag

Loading this module through a script tag will make the Unixfs obj available in the global namespace.

<script src="https://npmcdn.com/ipfs-unixfs/dist/index.min.js"></script>
<!-- OR -->
<script src="https://npmcdn.com/ipfs-unixfs/dist/index.js"></script>

Usage

Examples

Create a file composed by several blocks

var data = new Unixfs('file')
data.addBlockSize(256) // add the size of each block
data.addBlockSize(256)
// ...

Create a directory that contains several files

Creating a directory that contains several files is achieve by creating a unixfs element that identifies a MerkleDAG node as a directory. The links of that MerkleDAG node are the files that are contained in this directory.

var data = new Unixfs('directory')

API

unixfs Data Structure

message Data {
  enum DataType {
    Raw = 0;
    Directory = 1;
    File = 2;
    Metadata = 3;
    Symlink = 4;
  }

  required DataType Type = 1;
  optional bytes Data = 2;
  optional uint64 filesize = 3;
  repeated uint64 blocksizes = 4;
}

message Metadata {
  required string MimeType = 1;
}

create an unixfs Data element

var data = new UnixFS(<type>, [<content>])

Type can be: ['raw', 'directory', 'file', 'metadata', 'symlink']

add and remove a block size to the block size list

data.addBlockSize(<size in bytes>)

data.removeBlockSize(<index>)

get total fileSize

data.fileSize() // => size in bytes

marshal and unmarshal

var marsheled = data.marshal()
var unmarsheled = Unixfs.unmarshal(marsheled)

Contribute

Feel free to join in. All welcome. Open an issue!

This repository falls under the IPFS Code of Conduct.

License

MIT