From 5d62fbc26851679faf3daf27c2c517c14a129b36 Mon Sep 17 00:00:00 2001 From: David Humphrey Date: Thu, 20 Dec 2018 20:29:19 -0500 Subject: [PATCH] Update docs and build scripts --- README.md | 34 ++++++++---------- package-lock.json | 87 +++++++++++++++++++++++++++++++++++++++++++++++ package.json | 8 +++-- 3 files changed, 107 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 6c1d046..d3f01c9 100644 --- a/README.md +++ b/README.md @@ -103,7 +103,7 @@ section below. Filer also supports node's Path module. See the [Filer.Path](#FilerPath) section below. In addition, common shell operations (e.g., rm, touch, cat, etc.) are supported via the -`FileSystemShell` object, which can be obtained from, and used with a `FileSystem`. +`FileSystemShell` object, which can be used with a `FileSystem`. See the[FileSystemShell](#FileSystemShell) section below. ### API Reference @@ -113,6 +113,7 @@ you omit the callback, errors will be thrown as exceptions). The first callback reserved for passing errors. It will be `null` if no errors occurred and should always be checked. #### Support for Promises + The Promise based API mimics the way Node [implements](https://nodejs.org/api/fs.html#fs_fs_promises_api) them. Both `Shell` and `FileSystem` now have a `promises` object attached alongside the regular callback style methods. Method names are identical to their callback counterparts with the difference that instead of receiving a final argument as a callback, they return a Promise that is resolved or rejected based on the success of method execution. > Please note that `exists` method will always throw, since it was [deprecated](https://nodejs.org/api/fs.html#fs_fs_exists_path_callback) by Node. @@ -1295,34 +1296,27 @@ and provides augmented features. Many separate `FileSystemShell` objects can exi `FileSystem`, but each `FileSystemShell` is bound to a single instance of a `FileSystem` for its lifetime. -A `FileSystemShell` is created by instantiating `Filer.FileSystem().Shell`: +> NOTE: previous versions of Filer (`v0.44` and before) bundled the `Shell` with `Filer`. This is no longer done, because it added too much size to the bundle. + +To use the `FileSystemShell`, first include the separate `shell.js` dependency. +This allows you to create new instances with `new Shell(fs, options)`: ```javascript var fs = new Filer.FileSystem(); -var sh = new fs.Shell(options); -var sh2 = new fs.Shell(options); +var sh = new Shell(fs, options); +var sh2 = new Shell(fs, options); // sh and sh2 are two separate shells, each bound to fs ``` -In addition, the constructor function can be accessed through `Filer`: - -```javascript -var fs = new Filer.FileSystem(); -var sh = new fs.Shell(); - -Filer.Shell.prototype.newFunction = ...; - -sh.newFunction(); -``` - -The `FileSystemShell` can take an optional `options` object. The `options` object -can include `env`, which is a set of environment variables. Currently supported variables +In addition to the `fs` instance, The `Shell` constructor can take an optional +`options` object. The `options` object can include `env` (an `Object`), which is +a set of environment variables. Currently supported variables include `TMP` (the path to the temporary directory), and `PATH` (the list of known paths) and others may be added in the future. You can also add your own, or update existing variables. ```javascript var fs = new Filer.FileSystem(); -var sh = new fs.Shell({ +var sh = new Shell(fs, { env: { TMP: '/tempdir', PATH: '/one:/two' @@ -1348,7 +1342,7 @@ Example: ```javascript var fs = new Filer.FileSystem(); -var sh = new fs.Shell(); +var sh = new Shell(fs); var p = sh.env.get('PATH'); // Store the current location @@ -1368,7 +1362,7 @@ examples below assume a `FileSystemShell` instance named `sh` has been created l ```javascript var fs = new Filer.FileSystem(); -var sh = new fs.Shell(); +var sh = new Shell(fs); ``` * [sh.cd(path, callback)](#cd) diff --git a/package-lock.json b/package-lock.json index c6b6757..f5fd561 100644 --- a/package-lock.json +++ b/package-lock.json @@ -995,12 +995,30 @@ "integrity": "sha1-45sJrqne+Gao8gbiiK9jkZuuOcQ=", "dev": true }, + "array-filter": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/array-filter/-/array-filter-0.0.1.tgz", + "integrity": "sha1-fajPLiZijtcygDWB/SH2fKzS7uw=", + "dev": true + }, "array-find-index": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/array-find-index/-/array-find-index-1.0.2.tgz", "integrity": "sha1-3wEKoSh+Fku9pvlyOwqWoexBh6E=", "dev": true }, + "array-map": { + "version": "0.0.0", + "resolved": "https://registry.npmjs.org/array-map/-/array-map-0.0.0.tgz", + "integrity": "sha1-iKK6tz0c97zVwbEYoAP2b2ZfpmI=", + "dev": true + }, + "array-reduce": { + "version": "0.0.0", + "resolved": "https://registry.npmjs.org/array-reduce/-/array-reduce-0.0.0.tgz", + "integrity": "sha1-FziZ0//Rx9k4PkR5Ul2+J4yrXys=", + "dev": true + }, "array-slice": { "version": "0.2.3", "resolved": "https://registry.npmjs.org/array-slice/-/array-slice-0.2.3.tgz", @@ -5533,6 +5551,12 @@ } } }, + "jsonify": { + "version": "0.0.0", + "resolved": "https://registry.npmjs.org/jsonify/-/jsonify-0.0.0.tgz", + "integrity": "sha1-LHS27kHZPKUbe1qu6PUDYx0lKnM=", + "dev": true + }, "karma": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/karma/-/karma-3.0.0.tgz", @@ -5829,6 +5853,12 @@ "integrity": "sha1-hxDXrwqmJvj/+hzgAWhUUmMlV0g=", "dev": true }, + "memorystream": { + "version": "0.3.1", + "resolved": "https://registry.npmjs.org/memorystream/-/memorystream-0.3.1.tgz", + "integrity": "sha1-htcJCzDORV1j+64S3aUaR93K+bI=", + "dev": true + }, "meow": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/meow/-/meow-5.0.0.tgz", @@ -6188,6 +6218,34 @@ "integrity": "sha512-U+JJi7duF1o+u2pynbp2zXDW2/PADgC30f0GsHZtRh+HOcXHnw137TrNlyxxRvWW5fjKd3bcLHPxofWuCjaeZg==", "dev": true }, + "npm-run-all": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/npm-run-all/-/npm-run-all-4.1.5.tgz", + "integrity": "sha512-Oo82gJDAVcaMdi3nuoKFavkIHBRVqQ1qvMb+9LHk/cF4P6B2m8aP04hGf7oL6wZ9BuGwX1onlLhpuoofSyoQDQ==", + "dev": true, + "requires": { + "ansi-styles": "^3.2.1", + "chalk": "^2.4.1", + "cross-spawn": "^6.0.5", + "memorystream": "^0.3.1", + "minimatch": "^3.0.4", + "pidtree": "^0.3.0", + "read-pkg": "^3.0.0", + "shell-quote": "^1.6.1", + "string.prototype.padend": "^3.0.0" + }, + "dependencies": { + "ansi-styles": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", + "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", + "dev": true, + "requires": { + "color-convert": "^1.9.0" + } + } + } + }, "nth-check": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-1.0.2.tgz", @@ -7936,6 +7994,12 @@ "integrity": "sha1-GN4vl+S/epVRrXURlCtUlverpmA=", "dev": true }, + "pidtree": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/pidtree/-/pidtree-0.3.0.tgz", + "integrity": "sha512-9CT4NFlDcosssyg8KVFltgokyKZIFjoBxw8CTGy+5F38Y1eQWrt8tRayiUOXE+zVKQnYu5BR8JjCtvK3BcnBhg==", + "dev": true + }, "pify": { "version": "2.3.0", "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", @@ -10013,6 +10077,18 @@ "integrity": "sha1-2kL0l0DAtC2yypcoVxyxkMmO/qM=", "dev": true }, + "shell-quote": { + "version": "1.6.1", + "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.6.1.tgz", + "integrity": "sha1-9HgZSczkAmlxJ0MOo7PFR29IF2c=", + "dev": true, + "requires": { + "array-filter": "~0.0.0", + "array-map": "~0.0.0", + "array-reduce": "~0.0.0", + "jsonify": "~0.0.0" + } + }, "sigmund": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/sigmund/-/sigmund-1.0.1.tgz", @@ -10453,6 +10529,17 @@ "regexp.prototype.flags": "^1.2.0" } }, + "string.prototype.padend": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/string.prototype.padend/-/string.prototype.padend-3.0.0.tgz", + "integrity": "sha1-86rvfBcZ8XDF6rHDK/eA2W4h8vA=", + "dev": true, + "requires": { + "define-properties": "^1.1.2", + "es-abstract": "^1.4.3", + "function-bind": "^1.0.2" + } + }, "string_decoder": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz", diff --git a/package.json b/package.json index a5ac1be..3edeca5 100644 --- a/package.json +++ b/package.json @@ -26,8 +26,11 @@ "pretest": "npm run lint", "test": "npm run karma-mocha", "posttest": "npm run test:migrations", - "prebuild": "parcel build --global Filer src/index.js --no-minify --out-file filer.js", - "build": "parcel build --global Filer src/index.js --out-file filer.min.js --detailed-report", + "build": "npm-run-all -n build-filer build-shell", + "prebuild-filer": "parcel build --global Filer src/index.js --no-minify --out-file filer.js", + "build-filer": "parcel build --global Filer src/index.js --out-file filer.min.js --detailed-report", + "prebuild-shell": "parcel build --global Shell src/shell/index.js --no-minify --out-file shell.js", + "build-shell": "parcel build --global Shell src/shell/index.js --out-file shell.min.js --detailed-report", "build-tests": "parcel build tests/index.js --no-source-maps --out-dir tests/dist", "prekarma-mocha-firefox": "npm run build-tests", "karma-mocha-firefox": "karma start karma.conf.js --browsers FirefoxHeadless", @@ -59,6 +62,7 @@ "karma-summary-reporter": "^1.5.1", "meow": "^5.0.0", "mocha": "^5.2.0", + "npm-run-all": "^4.1.5", "nyc": "^13.1.0", "parcel-bundler": "^1.10.3", "pretty-bytes": "^5.1.0",