fs-jetpack
Advanced tools
Comparing version 0.10.1 to 0.10.2
@@ -0,1 +1,5 @@ | ||
0.10.2 (2016-11-08) | ||
------------------- | ||
* Fixed `console.log(jetpack)` for node v6.6.0 or newer. | ||
0.10.1 (2016-11-01) | ||
@@ -2,0 +6,0 @@ ------------------- |
@@ -5,2 +5,3 @@ /* eslint no-param-reassign:0 */ | ||
var util = require('util'); | ||
var pathUtil = require('path'); | ||
@@ -67,3 +68,3 @@ var Q = require('q'); | ||
return { | ||
var api = { | ||
cwd: cwd, | ||
@@ -219,4 +220,15 @@ path: getPath, | ||
}; | ||
if (util.inspect.custom !== undefined) { | ||
// Without this console.log(jetpack) throws obscure error. Details: | ||
// https://github.com/szwacz/fs-jetpack/issues/29 | ||
// https://nodejs.org/api/util.html#util_custom_inspection_functions_on_objects | ||
api[util.inspect.custom] = function () { | ||
return '[fs-jetpack CWD: ' + getCwdPath() + ']'; | ||
}; | ||
} | ||
return api; | ||
}; | ||
module.exports = jetpackContext; |
{ | ||
"name": "fs-jetpack", | ||
"description": "Better file system API", | ||
"version": "0.10.1", | ||
"version": "0.10.2", | ||
"author": "Jakub Szwacz <jakub@szwacz.com>", | ||
@@ -6,0 +6,0 @@ "dependencies": { |
160
README.md
@@ -6,3 +6,3 @@ fs-jetpack [![Build Status](https://travis-ci.org/szwacz/fs-jetpack.svg?branch=master)](https://travis-ci.org/szwacz/fs-jetpack) [![Build status](https://ci.appveyor.com/api/projects/status/er206e91fpuuqf58?svg=true)](https://ci.appveyor.com/project/szwacz/fs-jetpack) [![codecov](https://codecov.io/gh/szwacz/fs-jetpack/branch/master/graph/badge.svg)](https://codecov.io/gh/szwacz/fs-jetpack) | ||
#### [Jump to API Docs](#api) | ||
Check out [EXAMPLES](EXAMPLES.md) to see few snippets what it can do. | ||
@@ -20,116 +20,21 @@ ## Installation | ||
# What's cool about jetpack? | ||
# API | ||
## Promises instead of callbacks | ||
API has the same set of synchronous and asynchronous methods. All async methods are promise based. | ||
API has the same set of synchronous and asynchronous methods. All async methods are promise based (no callbacks). | ||
Commonly used naming convention in Node world is reversed in this library (no 'method' and 'methodSync' naming). Asynchronous methods are those with 'Async' suffix, all methods without 'Async' in the name are synchronous. Reason behind this is that it gives very nice look to blocking API, and promise based non-blocking code is verbose anyway, so one more word is not much of a difference. | ||
Thanks to that the API is also coherent... | ||
Also it's just convenient... | ||
```js | ||
// If method has no 'Async' suffix it gives you answer right away. | ||
// If you don't see the word "Async", then method returns value immediately. | ||
var data = jetpack.read('file.txt'); | ||
console.log(data); | ||
// Want to make that call asynchronous? Just add the word "Async" | ||
// and it will give you promise instead of ready value. | ||
// When you see "Async", method returns promise which when resolved returns value. | ||
jetpack.readAsync('file.txt') | ||
.then(function (data) { | ||
console.log(data); | ||
console.log(data); | ||
}); | ||
``` | ||
## Every jetpack instance has its internal CWD | ||
You can create many jetpack objects with different internal working directories (which are independent of `process.cwd()`) and work on directories in a little more object-oriented manner. | ||
```js | ||
var src = jetpack.cwd('path/to/source'); | ||
var dest = jetpack.cwd('path/to/destination'); | ||
src.copy('foo.txt', dest.path('bar.txt')); | ||
``` | ||
## JSON is a first class citizen | ||
You can write JavaScript object directly to disk and it will be transformed to JSON automatically. | ||
```js | ||
var obj = { greet: "Hello World!" }; | ||
jetpack.write('file.json', obj); | ||
``` | ||
Then you can get your object back just by telling read method that it's a JSON. | ||
```js | ||
var obj = jetpack.read('file.json', 'json'); | ||
``` | ||
## Throws errors at you as the last resort | ||
Everyone who did something with files for sure seen (and probably hates) *"ENOENT, no such file or directory"* error. Jetpack tries to recover from that error if possible. | ||
1. For write/creation operations, if any of parent directories doesn't exist jetpack will just create lacking directories. | ||
2. For read/inspect operations, if file or directory doesn't exist `undefined` is returned instead of throwing. | ||
## All methods play nicely with each other (examples) | ||
**Note:** All examples are synchronous. Unfortunately asynchronous equivalents won't be that pretty. | ||
#### Great for build scripts | ||
```js | ||
var src = jetpack.cwd('path/to/source'); | ||
var dest = jetpack.dir('path/to/destination', { empty: true }); | ||
src.copy('.', dest.path(), { | ||
matching: ['./vendor/**', '*.html', '*.png', '*.jpg'] | ||
}); | ||
var config = src.read('config.json', 'json'); | ||
config.env = 'production'; | ||
dest.write('config.json', config); | ||
``` | ||
#### Files creation in declarative style | ||
Let's say you want to create folder structure: | ||
``` | ||
. | ||
|- greets | ||
|- greet.txt | ||
|- greet.json | ||
|- greets-i18n | ||
|- polish.txt | ||
``` | ||
Peace of cake with jetpack! | ||
```js | ||
jetpack | ||
.dir('greets') | ||
.file('greet.txt', { content: 'Hello world!' }) | ||
.file('greet.json', { content: { greet: 'Hello world!' } }) | ||
.cwd('..') | ||
.dir('greets-i18n') | ||
.file('polish.txt', { content: 'Witaj świecie!' }); | ||
``` | ||
#### Delete all tmp files inside directory tree | ||
```js | ||
jetpack.find('my-dir', { | ||
matching: '*.tmp' | ||
}) | ||
.forEach(jetpack.remove); | ||
``` | ||
#### Check if two files have the same content | ||
```js | ||
var file1 = jetpack.inspect('file1', { checksum: 'md5' }); | ||
var file2 = jetpack.inspect('file2', { checksum: 'md5' }); | ||
var areTheSame = (file1.md5 === file2.md5); | ||
``` | ||
# <a name="api"></a> API Docs | ||
API methods have blocking and non-blocking equivalents: | ||
```js | ||
// Synchronous call | ||
var data = jetpack.read('file.txt'); | ||
console.log(data); | ||
// Asynchronous call | ||
jetpack.readAsync('file.txt') | ||
.then(function (data) { | ||
console.log(data); | ||
}); | ||
``` | ||
**Methods:** | ||
@@ -156,10 +61,11 @@ - [append](#appendpath-data-options) | ||
## append(path, data, [options]) | ||
asynchronous: **appendAsync(path, data, [options])** | ||
Appends given data to the end of file. If file (or any parent directory) doesn't exist, creates it (or them). | ||
Appends given data to the end of file. If file (or any parent directory) doesn't exist, creates it/them. | ||
**parameters:** | ||
`path` the path to file. | ||
`data` data to append (could be `String` or `Buffer`). | ||
`data` data to append (can be `String` or `Buffer`). | ||
`options` (optional) `Object` with possible fields: | ||
@@ -181,3 +87,3 @@ * `mode` if the file doesn't exist yet, will be created with given mode. Value could be number (eg. `0700`) or string (eg. `'700'`). | ||
`options` (optional) additional options for customization. Is an `Object` with possible fields: | ||
* `overwrite` (default: `false`) Whether to overwrite destination path if it exists. For directories, source directory is merged with destination directory, so files in destination which are not present in the source, will remain intact. | ||
* `overwrite` (default: `false`) Whether to overwrite destination path if arready exists. For directories, source directory is merged with destination directory, so files in destination which are not present in the source, will remain intact. | ||
* `matching` if defined will actually copy **only** items matching any of specified glob patterns and omit everything else (see examples below). | ||
@@ -202,3 +108,3 @@ | ||
// All patterns are anchored to dir you want to copy, not to CWD. | ||
// All patterns are anchored to directory you want to copy, not to CWD. | ||
// So in this example directory 'dir1/dir2/images' will be copied | ||
@@ -224,3 +130,4 @@ // to 'copied-dir2/images' | ||
## cwd([path...]) | ||
Returns Current Working Directory (CWD) for this instance of jetpack, or creates new jetpack object with given path as its internal CWD. | ||
Returns Current Working Directory (CWD) for this instance of jetpack, or creates new jetpack object with given path as its internal CWD. | ||
**Note:** fs-jetpack never changes value of `process.cwd()`, the CWD we are talking about here is internal value inside every jetpack instance. | ||
@@ -270,3 +177,3 @@ | ||
**returns:** | ||
New CWD context with directory specified in `path` as CWD. | ||
New CWD context with directory specified in `path` as CWD (see docs of `cwd()` method for explanation). | ||
@@ -309,3 +216,3 @@ **examples:** | ||
`criteria` (optional) criteria to be met by the file. Is an `Object` with possible fields: | ||
* `content` sets file content. Could be `String`, `Buffer`, `Object` or `Array`. If `Object` or `Array` given to this parameter data will be written as JSON. | ||
* `content` sets file content. Can be `String`, `Buffer`, `Object` or `Array`. If `Object` or `Array` given to this parameter data will be written as JSON. | ||
* `jsonIndent` (defaults to 2) if writing JSON data this tells how many spaces should one indentation have. | ||
@@ -335,3 +242,3 @@ * `mode` ensures file has specified mode. If not set and file already exists, current mode will be preserved. Value could be number (eg. `0700`) or string (eg. `'700'`). | ||
`searchOptions` is an `Object` with possible fields: | ||
* `matching` glob patterns of files you would like to find. | ||
* `matching` glob patterns of files you want to find. | ||
* `files` (default `true`) whether or not should search for files. | ||
@@ -342,3 +249,3 @@ * `directories` (default `false`) whether or not should search for directories. | ||
**returns:** | ||
`Array` of found files. | ||
`Array` of found paths. | ||
@@ -380,13 +287,13 @@ **examples:** | ||
{ | ||
name: "my_dir", | ||
type: "file", // possible values: "file", "dir" | ||
size: 123, // size in bytes, this is returned only for files | ||
// if checksum option was specified: | ||
md5: '900150983cd24fb0d6963f7d28e17f72', | ||
// if mode option was set to true: | ||
mode: 33204, | ||
// if times option was set to true: | ||
accessTime: [object Date], | ||
modifyTime: [object Date], | ||
changeTime: [object Date] | ||
name: "my_dir", | ||
type: "file", // possible values: "file", "dir" | ||
size: 123, // size in bytes, this is returned only for files | ||
// if checksum option was specified: | ||
md5: '900150983cd24fb0d6963f7d28e17f72', | ||
// if mode option was set to true: | ||
mode: 33204, | ||
// if times option was set to true: | ||
accessTime: [object Date], | ||
modifyTime: [object Date], | ||
changeTime: [object Date] | ||
} | ||
@@ -402,3 +309,3 @@ ``` | ||
**parameters:** | ||
`path` the path to inspect. | ||
`path` the starting path to inspect. | ||
`options` (optional). Possible values: | ||
@@ -533,3 +440,3 @@ * `checksum` if specified will also calculate checksum of every item in the tree. Possible values are strings `'md5'`, `'sha1'` or `'sha256'`. Checksums for directories are calculated as checksum of all children' checksums plus their filenames (see example below). | ||
**parameters:** | ||
`path` path to thing you want to change name. | ||
`path` path to thing you want to change name of. | ||
`newName` new name for this thing (not full path, just a name). | ||
@@ -540,2 +447,7 @@ | ||
**examples:** | ||
```javascript | ||
// The file "my_work/important.md" will be renamed to "my_work/very_important.md" | ||
jetpack.rename('my_work/important.txt', 'very_important.md'); | ||
``` | ||
@@ -542,0 +454,0 @@ ## symlink(symlinkValue, path) |
var fse = require('fs-extra'); | ||
var path = require('./path_assertions'); | ||
var path = require('./assert_path'); | ||
var helper = require('./helper'); | ||
@@ -4,0 +4,0 @@ var jetpack = require('..'); |
var fse = require('fs-extra'); | ||
var expect = require('chai').expect; | ||
var path = require('./path_assertions'); | ||
var path = require('./assert_path'); | ||
var helper = require('./helper'); | ||
@@ -5,0 +5,0 @@ var jetpack = require('..'); |
var fse = require('fs-extra'); | ||
var pathUtil = require('path'); | ||
var expect = require('chai').expect; | ||
var path = require('./path_assertions'); | ||
var path = require('./assert_path'); | ||
var helper = require('./helper'); | ||
@@ -6,0 +6,0 @@ var jetpack = require('..'); |
var fse = require('fs-extra'); | ||
var expect = require('chai').expect; | ||
var path = require('./path_assertions'); | ||
var path = require('./assert_path'); | ||
var helper = require('./helper'); | ||
@@ -5,0 +5,0 @@ var jetpack = require('..'); |
var fse = require('fs-extra'); | ||
var expect = require('chai').expect; | ||
var path = require('./path_assertions'); | ||
var path = require('./assert_path'); | ||
var helper = require('./helper'); | ||
@@ -5,0 +5,0 @@ var jetpack = require('..'); |
var fse = require('fs-extra'); | ||
var expect = require('chai').expect; | ||
var path = require('./path_assertions'); | ||
var path = require('./assert_path'); | ||
var helper = require('./helper'); | ||
@@ -5,0 +5,0 @@ var jetpack = require('..'); |
var fse = require('fs-extra'); | ||
var path = require('./path_assertions'); | ||
var path = require('./assert_path'); | ||
var helper = require('./helper'); | ||
@@ -4,0 +4,0 @@ var jetpack = require('..'); |
var fse = require('fs-extra'); | ||
var path = require('./path_assertions'); | ||
var path = require('./assert_path'); | ||
var helper = require('./helper'); | ||
@@ -4,0 +4,0 @@ var jetpack = require('..'); |
var fse = require('fs-extra'); | ||
var path = require('./path_assertions'); | ||
var path = require('./assert_path'); | ||
var helper = require('./helper'); | ||
@@ -4,0 +4,0 @@ var jetpack = require('..'); |
var Q = require('q'); | ||
var fse = require('fs-extra'); | ||
var expect = require('chai').expect; | ||
var path = require('./path_assertions'); | ||
var path = require('./assert_path'); | ||
var helper = require('./helper'); | ||
@@ -6,0 +6,0 @@ var jetpack = require('..'); |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
201471
58
5789
467