ipfs-unixfs
    TypeScript icon, indicating that this package has built-in type declarations

    6.0.6 • Public • Published

    ipfs-unixfs JavaScript Implementation

    Build Status Codecov

    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

    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

    const data = new UnixFS({ type: '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.

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

    API

    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])

    options is 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 (Uint8Array): The optional data field for this node
    • blockSizes (Array, default: []): If this is a file node that is made up of multiple blocks, blockSizes is 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 0644 for files, 0755 for 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>)
    data.removeBlockSize(<index>)

    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 mtime property will be present on the Data instance:

    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 }

    Contribute

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

    This repository falls under the IPFS Code of Conduct.

    License

    MIT

    Keywords

    Install

    npm i ipfs-unixfs

    DownloadsWeekly Downloads

    53,686

    Version

    6.0.6

    License

    MIT

    Unpacked Size

    122 kB

    Total Files

    19

    Last publish

    Collaborators

    • daviddias
    • achingbrain
    • ipfs-npm-publisher-bot