Nanoscale Parts Manufacturing

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

    8.0.0 • Public • Published

    ipfs-unixfs

    ipfs.tech Discuss codecov CI

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

    Table of contents

    Install

    $ npm i ipfs-unixfs

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

    Lead Maintainer

    Alex Potsides

    > npm i ipfs-unixfs

    Use in Node.js

    import { UnixFS } from '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.

    import { UnixFS } from '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

    Licensed under either of

    Contribute

    Contributions welcome! Please check out the issues.

    Also see our contributing document for more information on how we work, and about contributing in general.

    Please be aware that all interactions related to this repo are subject to the IPFS Code of Conduct.

    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.

    Keywords

    Install

    npm i ipfs-unixfs

    DownloadsWeekly Downloads

    71,431

    Version

    8.0.0

    License

    Apache-2.0 OR MIT

    Unpacked Size

    89.2 kB

    Total Files

    13

    Last publish

    Collaborators

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