Merge pull request #38 from ipfs/make-mtime-and-mode-optional

fix: allow mtime and mode to be optional

Author: achingbrain

README.md

@@ -1,4 +1,4 @@
-# ipfs-unixfs JavaScript Implementation
+# ipfs-unixfs JavaScript Implementation <!-- omit in toc -->
 
 [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io)
 [![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/)
@@ -10,36 +10,34 @@
 ![](https://img.shields.io/badge/npm-%3E%3D3.0.0-orange.svg?style=flat-square)
 ![](https://img.shields.io/badge/Node.js-%3E%3D8.0.0-orange.svg?style=flat-square)
 
-> JavaScript implementation of IPFS' unixfs (a Unix FileSystem files representation on top of a MerkleDAG)
+> 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](http://github.com/ipfs/specs)
+The UnixFS spec can be found inside the [ipfs/specs repository](http://github.com/ipfs/specs)
 
-## Lead Maintainer
+## Lead Maintainer <!-- omit in toc -->
 
 [Alex Potsides](https://github.com/achingbrain)
 
-## Table of Contents
-
-- [ipfs-unixfs JavaScript Implementation](#ipfs-unixfs-javascript-implementation)
-  - [Lead Maintainer](#lead-maintainer)
-  - [Table of Contents](#table-of-contents)
-  - [Install](#install)
-    - [npm](#npm)
-    - [Use in Node.js](#use-in-nodejs)
-    - [Use in a browser with browserify, webpack or any other bundler](#use-in-a-browser-with-browserify--webpack-or-any-other-bundler)
-    - [Use in a browser Using a script tag](#use-in-a-browser-using-a-script-tag)
-  - [Usage](#usage)
-    - [Examples](#examples)
-      - [Create a file composed by several blocks](#create-a-file-composed-by-several-blocks)
-      - [Create a directory that contains several files](#create-a-directory-that-contains-several-files)
-  - [API](#api)
-      - [unixfs Data Structure](#unixfs-data-structure)
-      - [create an unixfs Data element](#create-an-unixfs-data-element)
-      - [add and remove a block size to the block size list](#add-and-remove-a-block-size-to-the-block-size-list)
-      - [get total fileSize](#get-total-filesize)
-      - [marshal and unmarshal](#marshal-and-unmarshal)
-  - [Contribute](#contribute)
-  - [License](#license)
+## Table of Contents <!-- omit in toc -->
+
+- [Install](#install)
+  - [npm](#npm)
+  - [Use in Node.js](#use-in-nodejs)
+  - [Use in a browser with browserify, webpack or any other bundler](#use-in-a-browser-with-browserify-webpack-or-any-other-bundler)
+  - [Use in a browser Using a script tag](#use-in-a-browser-using-a-script-tag)
+- [Usage](#usage)
+  - [Examples](#examples)
+    - [Create a file composed by several blocks](#create-a-file-composed-by-several-blocks)
+    - [Create a directory that contains several files](#create-a-directory-that-contains-several-files)
+- [API](#api)
+    - [UnixFS Data Structure](#unixfs-data-structure)
+    - [create an unixfs Data element](#create-an-unixfs-data-element)
+    - [add and remove a block size to the block size list](#add-and-remove-a-block-size-to-the-block-size-list)
+    - [get total fileSize](#get-total-filesize)
+    - [marshal and unmarshal](#marshal-and-unmarshal)
+    - [is this UnixFS entry a directory?](#is-this-unixfs-entry-a-directory)
+- [Contribute](#contribute)
+- [License](#license)
 
 ## Install
 
@@ -52,20 +50,20 @@
 ### Use in Node.js
 
 ```JavaScript
-var Unixfs = require('ipfs-unixfs')
+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.
 
 ```JavaScript
-var Unixfs = require('ipfs-unixfs')
+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.
+Loading this module through a script tag will make the `UnixFS` obj available in the global namespace.
 
 ```html
 <script src="https://npmcdn.com/ipfs-unixfs/dist/index.min.js"></script>
@@ -80,7 +78,7 @@ Loading this module through a script tag will make the `Unixfs` obj available in
 #### Create a file composed by several blocks
 
 ```JavaScript
-var data = new Unixfs('file')
+const data = new UnixFS({ type: 'file' })
 data.addBlockSize(256) // add the size of each block
 data.addBlockSize(256)
 // ...
@@ -91,14 +89,16 @@ data.addBlockSize(256)
 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.
 
 ```JavaScript
-var data = new Unixfs('directory')
+const data = new UnixFS({ type: 'directory' })
 ```
 
 ## API
 
-#### unixfs Data Structure
+#### UnixFS Data Structure
 
 ```protobuf
+syntax = "proto2";
+
 message Data {
   enum DataType {
     Raw = 0;
@@ -113,9 +113,10 @@ message Data {
   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 int64 mtime = 8;
 }
 
 message Metadata {
@@ -126,10 +127,22 @@ message Metadata {
 #### create an unixfs Data element
 
 ```JavaScript
-var data = new UnixFS(<type>, [<content>])
+const data = new UnixFS([options])
 ```
 
-Type can be: `['raw', 'directory', 'file', 'metadata', 'symlink', 'hamt-sharded-directory']`
+`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 (Buffer): 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, default `0`): The modification time of this node
 
 #### add and remove a block size to the block size list
 
@@ -149,9 +162,19 @@ data.fileSize() // => size in bytes
 
 #### marshal and unmarshal
 
+```javascript
+const marshaled = data.marshal()
+const unmarshaled = Unixfs.unmarshal(marshaled)
 ```
-var marshaled = data.marshal()
-var unmarshaled = Unixfs.unmarshal(marshaled)
+
+#### is this UnixFS entry a directory?
+
+```JavaScript
+const dir = new Data({ type: 'directory' })
+dir.isDirectory() // true
+
+const file = new Data({ type: 'file' })
+file.isDirectory() // false
 ```
 
 ## Contribute

package.json

@@ -38,11 +38,10 @@
   "devDependencies": {
     "aegir": "^20.4.1",
     "chai": "^4.2.0",
-    "dirty-chai": "^2.0.1",
-    "safe-buffer": "^5.1.2"
+    "dirty-chai": "^2.0.1"
   },
   "dependencies": {
-    "protons": "^1.0.1"
+    "protons": "^1.1.0"
   },
   "contributors": [
     "David Dias <daviddias.p@gmail.com>",

src/index.js

@@ -2,9 +2,7 @@
 
 const protons = require('protons')
 const pb = protons(require('./unixfs.proto'))
-// encode/decode
 const unixfsData = pb.Data
-// const unixfsMetadata = pb.MetaData // encode/decode
 
 const types = [
   'raw',
@@ -20,37 +18,94 @@ const dirTypes = [
   'hamt-sharded-directory'
 ]
 
-function Data (type, data) {
-  if (!(this instanceof Data)) {
-    return new Data(type, data)
+const DEFAULT_FILE_MODE = parseInt('0644', 8)
+const DEFAULT_DIRECTORY_MODE = parseInt('0755', 8)
+
+function parseArgs (args) {
+  if (args.length === 0) {
+    return {
+      type: 'file'
+    }
+  }
+
+  if (args.length === 2) {
+    // support old-style constructor
+    return {
+      type: args[0],
+      data: args[1]
+    }
+  }
+
+  if (typeof args[0] === 'string' || args[0] instanceof String) {
+    return {
+      type: args[0]
+    }
   }
-  if (types.indexOf(type) === -1) {
-    throw new Error('Type: ' + type + ' is not valid')
+
+  return args[0]
+}
+
+class Data {
+  // decode from protobuf https://github.com/ipfs/specs/blob/master/UNIXFS.md
+  static unmarshal (marshaled) {
+    const decoded = unixfsData.decode(marshaled)
+
+    return new Data({
+      type: types[decoded.Type],
+      data: decoded.hasData() ? decoded.Data : undefined,
+      blockSizes: decoded.blocksizes,
+      mode: decoded.hasMode() ? decoded.mode : undefined,
+      mtime: decoded.hasMtime() ? new Date(decoded.mtime * 1000) : undefined
+    })
   }
 
-  this.type = type
-  this.data = data
-  this.blockSizes = []
+  constructor (...args) {
+    const {
+      type,
+      data,
+      blockSizes,
+      hashType,
+      fanout,
+      mtime,
+      mode
+    } = parseArgs(args)
+
+    if (!types.includes(type)) {
+      throw new Error('Type: ' + type + ' is not valid')
+    }
+
+    this.type = type
+    this.data = data
+    this.hashType = hashType
+    this.fanout = fanout
+    this.blockSizes = blockSizes || []
+    this.mtime = mtime || new Date(0)
+    this.mode = mode
+
+    if (this.mode === undefined && type === 'file') {
+      this.mode = DEFAULT_FILE_MODE
+    }
 
-  if (this.type === 'file') {
-    this.mode = parseInt('0644', 8)
+    if (this.mode === undefined && this.isDirectory()) {
+      this.mode = DEFAULT_DIRECTORY_MODE
+    }
   }
 
-  if (this.type === 'directory' || this.type === 'hamt-sharded-directory') {
-    this.mode = parseInt('0755', 8)
+  isDirectory () {
+    return dirTypes.includes(this.type)
   }
 
-  this.addBlockSize = (size) => {
+  addBlockSize (size) {
     this.blockSizes.push(size)
   }
 
-  this.removeBlockSize = (index) => {
+  removeBlockSize (index) {
     this.blockSizes.splice(index, 1)
   }
 
   // data.length + blockSizes
-  this.fileSize = () => {
-    if (dirTypes.indexOf(this.type) >= 0) {
+  fileSize () {
+    if (this.isDirectory()) {
       // dirs don't have file size
       return undefined
     }
@@ -59,14 +114,16 @@ function Data (type, data) {
     this.blockSizes.forEach((size) => {
       sum += size
     })
-    if (data) {
-      sum += data.length
+
+    if (this.data) {
+      sum += this.data.length
     }
+
     return sum
   }
 
   // encode to protobuf
-  this.marshal = () => {
+  marshal () {
     let type
 
     switch (this.type) {
@@ -92,12 +149,28 @@ function Data (type, data) {
       blockSizes = undefined
     }
 
-    if ((this.type === 'directory' || this.type === 'hamt-sharded-directory') && this.mode === parseInt('0755', 8)) {
-      delete this.mode
+    let mode
+
+    if (!isNaN(parseInt(this.mode))) {
+      mode = this.mode
+
+      if (mode === DEFAULT_FILE_MODE && this.type === 'file') {
+        mode = undefined
+      }
+
+      if (mode === DEFAULT_DIRECTORY_MODE && this.isDirectory()) {
+        mode = undefined
+      }
     }
 
-    if (this.type === 'file' && this.mode === parseInt('0644', 8)) {
-      delete this.mode
+    let mtime
+
+    if (this.mtime) {
+      mtime = Math.round(this.mtime.getTime() / 1000)
+
+      if (mtime === 0) {
+        mtime = undefined
+      }
     }
 
     return unixfsData.encode({
@@ -107,30 +180,10 @@ function Data (type, data) {
       blocksizes: blockSizes,
       hashType: this.hashType,
       fanout: this.fanout,
-      mode: this.mode,
-      mtime: this.mtime
+      mode,
+      mtime
     })
   }
 }
 
-// decode from protobuf https://github.com/ipfs/go-ipfs/blob/master/unixfs/format.go#L24
-Data.unmarshal = (marsheled) => {
-  const decoded = unixfsData.decode(marsheled)
-  if (!decoded.Data) {
-    decoded.Data = undefined
-  }
-  const obj = new Data(types[decoded.Type], decoded.Data)
-  obj.blockSizes = decoded.blocksizes
-
-  if (decoded.mode) {
-    obj.mode = decoded.mode
-  }
-
-  if (decoded.mtime) {
-    obj.mtime = decoded.mtime
-  }
-
-  return obj
-}
-
-exports = module.exports = Data
+module.exports = Data