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

ipfs-unixfs JavaScript Implementation

Build StatusCodecov

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

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

Lead Maintainer

Alex Potsides

Table of Contents



> 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 UnixFSobj 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>



Create a file composed by several blocks

const data = new UnixFS({ type: 'file' })
data.addBlockSize(256) // add the size of each block
// ...

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.

const data = new UnixFS({ type: 'directory' })


UnixFS Data Structure

syntax = "proto2";

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

  required DataType Type = 1;
  optional bytes Data = 2;
  optional uint64 filesize = 3;
  repeated uint64 blocksizes = 4;
  optional uint64 hashType = 5;
  optional uint64 fanout = 6;
  optional uint32 mode = 7;
  optional UnixTime mtime = 8;

message UnixTime {
  required int64 Seconds = 1;
  optional fixed32 FractionalNanoseconds = 2;

message Metadata {
  optional string MimeType = 1;

create an unixfs Data element

const data = new UnixFS([options])

optionsis an optional object argument that might include the following keys:

  • type (string, default file): The type of UnixFS entry. Can be:
    • raw
    • directory
    • file
    • metadata
    • symlink
    • hamt-sharded-directory
  • data (Buffer): The optional data field for this node
  • blockSizes (Array, default: []): If this is a filenode that is made up of multiple blocks, blockSizesis a list numbers that represent the size of the file chunks stored in each child node. It is used to calculate the total file size.
  • mode (Number, default 0644for files, 0755for directories/hamt-sharded-directories) file mode
  • mtime (Date, { secs, nsecs }, { Seconds, FractionalNanoseconds }, [ secs, nsecs ]): The modification time of this node

add and remove a block size to the block size list

data.addBlockSize(<size in bytes>)

get total fileSize

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

marshal and unmarshal

const marshaled = data.marshal()
const unmarshaled = Unixfs.unmarshal(marshaled)

is this UnixFS entry a directory?

const dir = new Data({ type: 'directory' })
dir.isDirectory() // true

const file = new Data({ type: 'file' })
file.isDirectory() // false

has an mtime been set?

If no modification time has been set, no mtimeproperty will be present on the Datainstance:

const file = new Data({ type: 'file' })
file.mtime // undefined

Object.prototype.hasOwnProperty.call(file, 'mtime') // false

const dir = new Data({ type: 'dir', mtime: new Date() })
dir.mtime // { secs: Number, nsecs: Number }


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

This repository falls under the IPFS Code of Conduct.








扫码加入 JavaScript 社区



欢迎加入 JavaScript 社区