filer - npm Package Compare versions

Comparing version 1.0.2 to 1.1.0

package.json

@@ -14,3 +14,3 @@ {
   ],
-  "version": "1.0.2",
+  "version": "1.1.0",
   "author": "Alan K <[e-mail]> (http://blog.modeswitch.org)",
@@ -25,2 +25,5 @@ "homepage": "http://filerjs.github.io/filer",
     "lint:fix": "eslint --fix src tests",
+    "test:node": "mocha --timeout 5000 tests",
+    "pretest:node-debug": "echo \"Open Chrome to chrome://inspect to debug tests...\"",
+    "test:node-debug": "mocha --timeout 5000 --inspect-brk tests",
     "test:manual": "parcel tests/index.html --out-dir tests/dist",
@@ -48,11 +51,10 @@ "test:migrations": "mocha tests/filesystems/migrations",
   "dependencies": {
-    "base64-arraybuffer": "^0.1.5",
-    "es6-promisify": "^6.0.0",
+    "es6-promisify": "^6.0.1",
     "minimatch": "^3.0.4"
   },
   "devDependencies": {
-    "chai": "^4.1.2",
+    "chai": "^4.2.0",
     "chai-datetime": "^1.5.0",
-    "eslint": "^5.0.1",
-    "karma": "^3.0.0",
+    "eslint": "^5.10.0",
+    "karma": "^3.1.4",
     "karma-chai": "^0.1.0",
@@ -63,9 +65,9 @@ "karma-chrome-launcher": "^2.2.0",
     "karma-mocha-reporter": "^2.2.5",
-    "karma-summary-reporter": "^1.5.1",
+    "karma-summary-reporter": "^1.5.2",
     "meow": "^5.0.0",
     "mocha": "^5.2.0",
     "nyc": "^13.1.0",
-    "parcel-bundler": "^1.10.3",
+    "parcel-bundler": "^1.11.0",
     "pretty-bytes": "^5.1.0",
-    "release-it": "^9.2.0",
+    "release-it": "^9.3.0",
     "run.env": "^1.1.0",
@@ -72,0 +74,0 @@ "unused-filename": "^1.0.0",

README.md

@@ -7,20 +7,20 @@ [![NPM](https://nodei.co/npm/filer.png?downloads=true&stars=true)](https://nodei.co/npm/filer/)
 
-Filer is a POSIX-like file system for browsers.
+Filer is a drop-in replacement for node's `fs` module, a POSIX-like file system
+for browsers.
 
 ### Compatibility
 
-Filer is known to work in the following browsers/versions, with the specified [Storage Providers](#providers):
+Filer uses [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
+and is [known to work in the following browsers/versions](https://caniuse.com/#feat=indexeddb):
 
 * node.js: v0.10.*+
-* IE: 10+ (IndexedDB)
-* Firefox: 26+ (IndexedDB)
-* Chrome: 31+ (IndexedDB, WebSQL)
-* Safari: 7.0+ (WebSQL)
-* Opera: 19+ (IndexedDB, WebSQL)
-* iOS: 3.2+ (WebSQL)
-* Android Browser: 2.1-4.4 (WebSQL), 4.4+ (IndexedDB)
+* IE: 10+
+* Edge: 12+
+* Firefox: 10+
+* Chrome: 23+
+* Safari: 10+
+* Opera: 15+
+* iOS: 10+
+* Android Browser: 4.4+
 
-NOTE: if you're interested in maximum compatibility, use the `Fallback` provider instead of `Default`.
-See the section on [Storage Providers](#providers).
-
 ### Contributing
@@ -35,3 +35,3 @@
 1. Via npm: `npm install filer`
-3. Via unpkg: `<script src="https://unpkg.com/filer"></script>` or specify a version directly, for example: [https://unpkg.com/filer@1.0.1/dist/filer.min.js](https://unpkg.com/filer@1.0.1/dist/filer.min.js)
+1. Via unpkg: `<script src="https://unpkg.com/filer"></script>` or specify a version directly, for example: [https://unpkg.com/filer@1.0.1/dist/filer.min.js](https://unpkg.com/filer@1.0.1/dist/filer.min.js)
 
@@ -81,15 +81,28 @@ ### Loading and Usage
 database is created for each file system. The file system can also use other
-backend storage providers, for example [WebSQL](http://en.wikipedia.org/wiki/Web_SQL_Database)
-or even RAM (i.e., for temporary storage). See the section on [Storage Providers](#providers).
+backend storage providers, for example `Memory`. See the section on [Storage Providers](#providers).
+
 <a name="overviewExample"></a>
 
-```javascript
-var fs = new Filer.FileSystem();
-fs.open('/myfile', 'w+', function(err, fd) {
-  if (err) throw err;
-  fs.close(fd, function(err) {
-    if (err) throw err;
-    fs.stat('/myfile', function(err, stats) {
-      if (err) throw err;
-      console.log('stats: ' + JSON.stringify(stats));
+```js
+const { fs, path } = require('filer');
+
+fs.mkdir('/docs', (err) => {
+  if (err) {
+    return console.error('Unable to create /docs dir', err);
+  }
+  
+  const filename = path.join('/docs', 'first.txt');
+  const data = 'Hello World!\n';
+
+  fs.writeFile(filename, data, (err) => {
+    if (err) {
+      return console.error('Unable to write /docs/first.txt', err);
+    }
+
+    fs.stat(filename, (err, stats) =>  {
+      if (err) {
+        return console.error('Unable to stat /docs/first.txt', err);
+      }
+
+      console.log('Stats for /docs/first.txt:', stats);
     });
@@ -131,6 +144,10 @@ });
 
-File system constructor, invoked to open an existing file system or create a new one.
-Accepts two arguments: an `options` object, and an optional `callback`. The `options`
-object can specify a number of optional arguments, including:
+In most cases, using `Filer.fs` will be sufficient, and provide a working filesystem.
+However, if you need more control over the filesystem, you can also use the `FileSystem`
+constructor, invoked to open an existing file system or create a new one.
 
+`Filer.FileSystem()` It accepts two arguments: an `options` object, and an optional
+`callback` function. The `options` object can specify a number of optional arguments,
+including:
+
 * `name`: the name of the file system, defaults to `'"local'`
@@ -169,11 +186,13 @@ * `flags`: an Array of one or more flags to use when creating/opening the file system:
 
-Filer can be configured to use a number of different storage providers. The provider object encapsulates all aspects
-of data access, making it possible to swap in different backend storage options.  There are currently 4 different
-providers to choose from:
+Filer can be configured to use a number of different storage providers. The provider object encapsulates all aspects of data access, making it possible to swap in different backend storage options.  There are currently 2 providers to choose from:
 
 * `FileSystem.providers.IndexedDB()` - uses IndexedDB
-* `FileSystem.providers.WebSQL()` - uses WebSQL
-* `FileSystem.providers.Fallback()` - attempts to use IndexedDB if possible, falling-back to WebSQL if necessary
+if necessary
 * `FileSystem.providers.Memory()` - uses memory (not suitable for data that needs to survive the current session)
 
+**NOTE**: previous versions of Filer also supported `FileSystem.providers.WebSQL()` and
+`FileSystem.providers.Fallback()`, which could be used in browsers that supported
+WebSQL but not IndexedDB.  [WebSQL has been deprecated](https://www.w3.org/TR/webdatabase/),
+and this functionality was removed in `v1.0.0`.  If for some reason you still need it, use [`v0.0.44`](https://github.com/filerjs/filer/releases/tag/v0.0.44).
+
 You can choose your provider when creating a `FileSystem`:
@@ -188,7 +207,4 @@
 
-// Example 2: Explicitly use IndexedDB
-var fs2 = new FileSystem({ provider: new providers.IndexedDB() });
-
-// Example 3: Use one of IndexedDB or WebSQL, whichever is supported
-var fs3 = new FileSystem({ provider: new providers.Fallback() });
+// Example 2: Use the Memory provider
+var fs2 = new FileSystem({ provider: new providers.Memory() });
 ```
@@ -199,4 +215,4 @@
 ```javascript
-if( Filer.FileSystem.providers.WebSQL.isSupported() ) {
-  // WebSQL provider will work in current environment...
+if( Filer.FileSystem.providers.IndexedDB.isSupported() ) {
+  // IndexedDB provider will work in current environment...
 }
@@ -207,7 +223,2 @@ ```
 
-A number of other providers have been written, including:
-
-* node.js fs provider: https://github.com/humphd/filer-fs
-* node.js Amazon S3 provider: https://github.com/alicoding/filer-s3
-
 #### Filer.Buffer<a name="FilerBuffer"></a>
@@ -245,11 +256,12 @@
 
-The node.js [path module](http://nodejs.org/api/path.html) is available via the `Filer.Path` object. It is
-identical to the node.js (see [https://github.com/browserify/path-browserify](https://github.com/browserify/path-browserify)) version with the following differences:
+The node.js [path module](http://nodejs.org/api/path.html) is available via `Filer.path` or
+`Filer.Path` (both are supported for historical reasons, and to match node). The Filer `path`
+module is identical to the node.js version (see [https://github.com/browserify/path-browserify](https://github.com/browserify/path-browserify)), with the following differences:
 
 * The CWD always defaults to `/`
-* No support for Windows style paths
+* No support for Windows style paths (assume you are on a POSIX system)
 * Additional utility methods (see below)
 
 ```javascript
-var path = Filer.Path;
+var path = Filer.path;
 var dir = path.dirname('/foo/bar/baz/asdf/quux');
@@ -285,2 +297,17 @@ // dir is now '/foo/bar/baz/asdf'
 
+[As with node.js](https://nodejs.org/api/fs.html#fs_file_paths), all methods below that
+accept a `path` argument as a `String` can also take a [`file://` URL](https://nodejs.org/api/fs.html#fs_url_object_support)
+or a `Buffer`. For example, all of the following cases will work the same way with Filer:
+
+```js
+// 1. path as a String
+fs.writeFile('/dir/file.txt', 'data', function(err) {...});
+
+// 2. path as a URL
+fs.writeFile(new URL('file:///dir/file.txt'), 'data', function(err) {...});
+
+// 3. path as a Buffer
+fs.writeFile(Buffer.from('/dir/file.txt'), 'data', function(err) {...});
+```
+
 #### Filer.Errors<a name="Errors"></a>
@@ -328,3 +355,7 @@
 ```javascript
-var fs = new Filer.FileSystem();
+// 1. Using Filer.fs for a default filesystem
+const { fs } = require('filer');
+
+// 2. Or via the FileSystem constructor with specified options
+const fs = new Filer.FileSystem(options, callback);
 ```
@@ -733,3 +764,3 @@
 
-Tests a user's permissions for the file or directory supplied in `path` argument. Asynchronous [access(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/access.html). Callback gets no additional arguments. The `mode` argument can be one of the following (constants are available on `fs.constants`):
+Tests a user's permissions for the file or directory supplied in `path` argument. Asynchronous [access(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/access.html). Callback gets no additional arguments. The `mode` argument can be one of the following (constants are available on `fs.constants` and `fs`):
 
@@ -747,3 +778,3 @@ * `F_OK`: Test for existence of file.
 // Check if the file exists in the current directory.
-fs.access(file, fs.constants.F_OK, function(err) {
+fs.access(file, fs.F_OK, function(err) {
   console.log(`${file} ${err ? 'does not exist' : 'exists'}`);
@@ -750,0 +781,0 @@ });

src/filesystem/interface.js

 var { promisify } = require('es6-promisify');
 
-var isNullPath = require('../path.js').isNull;
+var Path = require('../path.js');
 var nop = require('../shared.js').nop;
@@ -25,3 +25,2 @@
 var STDERR = Constants.STDERR;
-var FIRST_DESCRIPTOR = Constants.FIRST_DESCRIPTOR;
 
@@ -50,3 +49,58 @@ // The core fs operations live on impl
 }
+// Get a path (String) from a file:// URL. Support URL() like objects
+// https://github.com/nodejs/node/blob/968e901aff38a343b1de4addebf79fd8fa991c59/lib/internal/url.js#L1381
+function toPathIfFileURL(fileURLOrPath) {
+  if(!(fileURLOrPath &&
+       fileURLOrPath.protocol &&
+       fileURLOrPath.pathname)) {
+    return fileURLOrPath;
+  }
 
+  if(fileURLOrPath.protocol !== 'file:') {
+    throw new Errors.EINVAL('only file: URLs are supported for paths', fileURLOrPath);
+  }
+
+  var pathname = fileURLOrPath.pathname;
+  for (var n = 0; n < pathname.length; n++) {
+    if (pathname[n] === '%') {
+      var third = pathname.codePointAt(n + 2) | 0x20;
+      if (pathname[n + 1] === '2' && third === 102) {
+        throw new Errors.EINVAL('file: URLs must not include encoded / characters', fileURLOrPath);
+      }
+    }
+  }
+
+  return decodeURIComponent(pathname);
+}
+
+// Allow Buffers for paths. Assumes we want UTF8.
+function toPathIfBuffer(bufferOrPath) {
+  return Buffer.isBuffer(bufferOrPath) ? bufferOrPath.toString() : bufferOrPath;
+}
+
+function validatePath(path, allowRelative) {
+  if(!path) {
+    return new Errors.EINVAL('Path must be a string', path);
+  } else if(Path.isNull(path)) {
+    return new Errors.EINVAL('Path must be a string without null bytes.', path);
+  } else if(!allowRelative && !Path.isAbsolute(path)) {
+    return new Errors.EINVAL('Path must be absolute.', path);
+  }
+}
+
+function processPathArg(args, idx, allowRelative) {
+  var path = args[idx];
+  path = toPathIfFileURL(path);
+  path = toPathIfBuffer(path);
+
+  // Some methods specifically allow for rel paths (eg symlink with srcPath)
+  var err = validatePath(path, allowRelative);
+  if(err) {
+    throw err;
+  }
+
+  // Overwrite path arg with converted and validated path
+  args[idx] = path;
+}
+
 /**
@@ -102,2 +156,7 @@ * FileSystem
   fs.constants = Constants.fsConstants;
+  // Node also forwards the access mode flags onto fs
+  fs.F_OK = Constants.fsConstants.F_OK;
+  fs.R_OK = Constants.fsConstants.R_OK;
+  fs.W_OK = Constants.fsConstants.W_OK;
+  fs.X_OK = Constants.fsConstants.X_OK;
 
@@ -107,18 +166,2 @@ // Expose Shell constructor
 
-  // Safely expose the list of open files and file
-  // descriptor management functions
-  var openFiles = {};
-  var nextDescriptor = FIRST_DESCRIPTOR;
-  Object.defineProperty(this, 'openFiles', {
-    get: function() { return openFiles; }
-  });
-  this.allocDescriptor = function(openFileDescription) {
-    var fd = nextDescriptor ++;
-    openFiles[fd] = openFileDescription;
-    return fd;
-  };
-  this.releaseDescriptor = function(fd) {
-    delete openFiles[fd];
-  };
-
   // Safely expose the operation queue
@@ -148,3 +191,3 @@ var queue = [];
   this.watch = function(filename, options, listener) {
-    if(isNullPath(filename)) {
+    if(Path.isNull(filename)) {
       throw new Error('Path must be a string without null bytes.');
@@ -213,2 +256,3 @@ }
         var context = provider[methodName]();
+        context.name = name;
         context.flags = flags;
@@ -272,47 +316,58 @@ context.changes = [];
   FileSystem.prototype.promises = {};
+
   /**
-   * Public API for FileSystem. All node.js methods that are
-   * exposed on fs.promises include `promise: true`.  We also
-   * include our own extra methods, but skip the fd versions
-   * to match node.js, which puts these on a FileHandle object.
+   * Public API for FileSystem. All node.js methods that are exposed on fs.promises
+   * include `promise: true`.  We also include our own extra methods, but skip the
+   * fd versions to match node.js, which puts these on a `FileHandle` object.
+   * Any method that deals with path argument(s) also includes the position of
+   * those args in one of `absPathArgs: [...]` or `relPathArgs: [...]`, so they
+   * can be processed and validated before being passed on to the method.
    */
   [
-    { name: 'open', promises: true },
-    { name: 'access', promises: true },
-    { name: 'chmod', promises: true },
+    { name: 'appendFile', promises: true, absPathArgs: [ 0 ] },
+    { name: 'access', promises: true, absPathArgs: [ 0 ] },
+    { name: 'chown', promises: true, absPathArgs: [ 0 ] },
+    { name: 'chmod', promises: true, absPathArgs: [ 0 ] },
+    { name: 'close' },
+    // copyFile - https://github.com/filerjs/filer/issues/436
+    { name: 'exists', absPathArgs: [ 0 ] },
+    { name: 'fchown' },
     { name: 'fchmod' },
-    { name: 'chown', promises: true },
-    { name: 'fchown' },
-    { name: 'close' },
-    { name: 'mknod', promises: true },
-    { name: 'mkdir', promises: true },
-    { name: 'mkdtemp', promises: true },
-    { name: 'rmdir', promises: true },
-    { name: 'stat', promises: true },
+    // fdatasync - https://github.com/filerjs/filer/issues/653
+    { name: 'fgetxattr' },
+    { name: 'fremovexattr' },
+    { name: 'fsetxattr' },
     { name: 'fstat' },
     { name: 'fsync' },
-    { name: 'link', promises: true },
-    { name: 'unlink', promises: true },
-    { name: 'read' },
-    { name: 'readFile', promises: true },
-    { name: 'write' },
-    { name: 'writeFile', promises: true },
-    { name: 'appendFile', promises: true },
-    { name: 'exists' },
+    { name: 'ftruncate' },
+    { name: 'futimes' },
+    { name: 'getxattr', promises: true, absPathArgs: [ 0 ] },
+    // lchown - https://github.com/filerjs/filer/issues/620
+    // lchmod - https://github.com/filerjs/filer/issues/619
+    { name: 'link', promises: true, absPathArgs: [0, 1] },
     { name: 'lseek' },
-    { name: 'readdir', promises: true },
-    { name: 'rename', promises: true },
-    { name: 'readlink', promises: true },
-    { name: 'symlink', promises: true },
     { name: 'lstat', promises: true },
-    { name: 'truncate', promises: true },
-    { name: 'ftruncate' },
-    { name: 'utimes', promises: true },
-    { name: 'futimes' },
-    { name: 'setxattr', promises: true },
-    { name: 'getxattr', promises: true },
-    { name: 'fsetxattr' },
-    { name: 'fgetxattr' },
-    { name: 'removexattr', promises: true },
-    { name: 'fremovexattr' }
+    { name: 'mkdir', promises: true, absPathArgs: [ 0 ] },
+    { name: 'mkdtemp', promises: true },
+    { name: 'mknod', promises: true, absPathArgs: [ 0 ] },
+    { name: 'open', promises: true, absPathArgs: [ 0 ] },
+    { name: 'readdir', promises: true, absPathArgs: [ 0 ] },
+    { name: 'read' },
+    { name: 'readFile', promises: true, absPathArgs: [ 0 ] },
+    { name: 'readlink', promises: true, absPathArgs: [ 0 ] },
+    // realpath - https://github.com/filerjs/filer/issues/85
+    { name: 'removexattr', promises: true, absPathArgs: [ 0 ] },
+    { name: 'rename', promises: true, absPathArgs: [0, 1] },
+    { name: 'rmdir', promises: true, absPathArgs: [ 0 ] },
+    { name: 'setxattr', promises: true, absPathArgs: [ 0 ] },
+    { name: 'stat', promises: true, absPathArgs: [ 0 ] },
+    { name: 'symlink', promises: true, relPathArgs: [ 0 ], absPathArgs: [ 1 ] },
+    { name: 'truncate', promises: true, absPathArgs: [ 0 ] },
+    // unwatchFile - https://github.com/filerjs/filer/pull/553
+    { name: 'unlink', promises: true, absPathArgs: [ 0 ] },
+    { name: 'utimes', promises: true, absPathArgs: [ 0 ] },
+    // watch - implemented above in `this.watch`
+    // watchFile - https://github.com/filerjs/filer/issues/654
+    { name: 'writeFile', promises: true, absPathArgs: [ 0 ] },
+    { name: 'write' }
   ].forEach(function(method) {
@@ -332,2 +387,10 @@ var methodName = method.name;
 
+      // Deal with path arguments, validating and normalizing Buffer and file:// URLs
+      if(method.absPathArgs) {
+        method.absPathArgs.forEach(pathArg => processPathArg(args, pathArg, false));
+      }
+      if(method.relPathArgs) {
+        method.relPathArgs.forEach(pathArg => processPathArg(args, pathArg, true));
+      }
+
       var error = fs.queueOrRun(function() {
@@ -359,3 +422,3 @@ var context = fs.provider.openReadWriteContext();
         // fn(fs, context, arg0, arg1, ... , complete);
-        var fnArgs = [fs, context].concat(args);
+        var fnArgs = [context].concat(args);
         impl[methodName].apply(null, fnArgs);
@@ -362,0 +425,0 @@ });

src/index.js

@@ -1,7 +0,24 @@
-module.exports = {
+let fs = null;
+let Filer = null;
+
+module.exports = Filer = {
   FileSystem: require('./filesystem/interface.js'),
   Buffer: Buffer,
+  // We previously called this Path, but node calls it path. Do both
   Path: require('./path.js'),
+  path: require('./path.js'),
   Errors: require('./errors.js'),
   Shell: require('./shell/shell.js')
 };
+
+// Add a getter for the `fs` instance, which returns
+// a Filer FileSystem instance, using the default provider/flags.
+Object.defineProperty(Filer, 'fs', {
+  enumerable: true,
+  get() {
+    if(!fs) {
+      fs = new Filer.FileSystem();
+    }
+    return fs;
+  }
+});

src/providers/index.js

@@ -1,35 +0,8 @@
-var IndexedDB = require('./indexeddb.js');
-var WebSQL = require('./websql.js');
-var Memory = require('./memory.js');
+const IndexedDB = require('./indexeddb.js');
+const Memory = require('./memory.js');
 
 module.exports = {
   IndexedDB: IndexedDB,
-  WebSQL: WebSQL,
-  Memory: Memory,
-
-  /**
-   * Convenience Provider references
-   */
-
-  // The default provider to use when none is specified
   Default: IndexedDB,
-
-  // The Fallback provider does automatic fallback checks
-  Fallback: (function() {
-    if(IndexedDB.isSupported()) {
-      return IndexedDB;
-    }
-
-    if(WebSQL.isSupported()) {
-      return WebSQL;
-    }
-
-    function NotSupported() {
-      throw '[Filer Error] Your browser doesn\'t support IndexedDB or WebSQL.';
-    }
-    NotSupported.isSupported = function() {
-      return false;
-    };
-    return NotSupported;
-  }())
+  Memory: Memory
 };

No alert changes

Improved metrics

Dependency count

2

decreased by-33.33%

Number of lines in readme file

1677

increased by1.88%

Worsened metrics

Total package byte prevSize

1297015

decreased by-1.55%

Lines of code

12288

decreased by-2.05%

Dependency changes

• - Removedbase64-arraybuffer@^0.1.5

• - Removedbase64-arraybuffer@0.1.5(transitive)

• Updatedes6-promisify@^6.0.1