objectize-fs

• honeo/objectize-fs
• objectize-fs

なにこれ

ファイル・ディレクトリを抽象化してNode.js APIで扱うやつ。
JScriptのFileSystemObjectとは一切関係ない。

使い方

# v1までは仕様がコロコロ変わるため
$ npm i -E objectize-fs

const {Directory, File, ZIP, RAR, Utility} = require('objectize-fs');

// $ rm *.txt
const dir = await new Directory('./');
const files = await dir.getFiles();
for(let file of files){
	if(file.ext==='txt'){
		await file.delete();
	}
}

API

• 属性は、書き込み例のあるもの以外は読み取り専用。
• いくつかの関数は第二引数で再利用するStatsを受け取れる。

Directory, File共通

Constractor#copy(outputPath [, overwrite])

自身を引数1パスにコピーする。
コピーした実体から作ったインスタンスを引数に解決するpromiseを返す。
引数2がtrueなら上書きを許可する。

// dir => dir, dir2
const dir = new Directory('dir');
const dir2 = await dir.copy('dir2');

// fileA.ext => fileA.ext, fileB.ext
const fileA = await new File('fileA.ext');
const fileB = await file.copy('fileB.ext');

Constractor#date()

自身の日付情報を含むオブジェクトを取得する。
取得したオブジェクトを引数に解決するpromiseを返す。

// date {a, m, c, birth}
const date = await dir.date();

Constractor#delete()

自身の実体を削除する。
削除後に解決するpromiseを返す。

await instance.delete();

Constractor#getParentDirectory()

自身の親ディレクトリのDirectoryインスタンスを取得する。 取得したインスタンスを引数に解決するpromiseを返す。

const parentDir = await instance.getParentDirectory();

• Alias
  • Constractor#getParentDir()

Constractor#isLive()

自身の実体が存在するかのbooleanを取得する。
取得したbooleanを引数に解決するpromiseを返す。

const bool = await instance.isLive();

Constractor#move(dirPath [, overwrite])

自身の実体を引数パスのディレクトリに移動する。
引数2がtrueなら上書きを許可する。
移動後に解決するpromiseを返す。

// bar => foo/bar
await dir.move('foo');

// filename => foo/filename
await file.move('foo');

注意

inodeナンバーが変化する。

Constractor#open()

自身の実体を開く。
子プロセスを引数に解決するpromiseを返す。

const child_process = await dir.open();

const child_process = await file.open();

• GitHub - domenic/opener: Opens stuff, like webpages and files and executables, cross-platform

Constractor#rename(string [, overwrite])

自身と実体を引数文字列に改名する。
自身を引数に解決するpromiseを返す。

await dir.rename('new-dirname');

await file.rename('new-filename.ext');

// overwrite
await file.rename('new-filename.ext', true);

Constractor#trash()

自身の実体をゴミ箱に移動する。
移動後に解決するpromiseを返す。

await dir.trash();

await file.trash();

Constractor#zip([path])

自身の実体を圧縮する。
圧縮した.zipファイルのZIPインスタンスを引数に解決するpromiseを返す。

// dir => dir.zip
const zip = await dir.zip();

// dir => hoge.zip
const zip = await dir.zip('./hoge.zip');

// file.ext => file.zip
const zip = await file.zip();

// file.ext => hoge.zip
const zip = await file.zip('hoge.zip');

Constractor#base

読み取り専用。
自身の親ディレクトリの絶対パス文字列。

instance.base; // Win: "C:\\Users\\username"

Constractor#name

読み取り専用。
自身のファイル・ディレクトリ名の文字列。

dir.name; // "dirname"
file.name; // "filename.ext"

Constractor#path

自身の絶対パスの文字列。

dir.path; // Win: "C:\\Users\\username\\dirname"

file.path; // Win: "C:\\Users\\username\\filename.ext"

Directory

options

いくつかの関数は引数に渡すオブジェクトで挙動を制御できる。

| key | type | description | |:--------- |:-------- | -------------------------------------------------------------------- | | directory | boolean | 結果にDirectoryインスタンスを含むか。 | | file | boolean | 結果にFileインスタンスを含むか。 | | filter | function | 走査中のインスタンス毎にそれを引数に実行し、trueを返したものを結果に含む。 | | greedy | boolean | 一部メソッドのみ。下位ディレクトリに対して同じ処理を繰り返すか。 | | global | boolean | 一部メソッドのみ。全てのコンテンツを走査して結果を配列で取得するか。 |

new Directory(dirpath [, config])

引数パスのディレクトリを基にインスタンスを作る。
作成したインスタンスを引数に解決するpromiseを返す。

const dir = await new Directory('path');

// config
const dir = await new Directory('path', {
	stats: fs.statSync(path)
});

Directory.make(path [, mode])

引数1パスのディレクトリが存在しなければ作成する。
作成したディレクトリのDirectoryインスタンスを引数に解決するpromiseを返す。

const dir = await Directory.make('hoge');

• 引数2について
  • File System | Node.js Documentationを参照。

Directory#cd()

自身の実体をプロセスのカレントディレクトリにする。
変更後に解決するPromiseを返す。

await dir.cd();

Directory#clear()

自身の実体が含むファイル・ディレクトリを全て削除する。
削除後に解決するpromiseを返す。

await dir.clear();

Directory#get(string [, options])

自身が直接含む、引数文字列と一致する名前のファイル・ディレクトリのインスタンスかnullを取得する。
取得した結果を引数に解決するpromiseを返す。

const file = await dir.get('file.txt');

// options
const dir_foobar_empty = await dir.get('foobar', {
	file: false,
	directory: true,
	async filter(dir){
		const list = await dir.list();
		return list.length===0;
	}
});

Directory#getContents([options])

自身が直接含むファイル・ディレクトリインスタンスを配列で取得する。
取得した配列を引数に解決するpromiseを返す。

const arr = await dir.getContents();

// options
const fileArr_deep_under1KB = await dir.getContents({
	directory: false,
	file: true,
	greedy: true,
	async filter(file){
		const size = await file.size();
		return size < 1024;
	}}
);

Directory#getDirectories([options])

自身が含むディレクトリインスタンスを配列で取得する。
取得した配列を引数に解決するpromiseを返す。

const dirs = await dir.getDirectories();

// options
const dirArr_deep_over1KB = await dir.getDirectories({
	greedy: true,
	async filter(dir){
		const size = await dir.size();
		return size > 1024;
	}}
);

• Alias
  • Directory#getDirs()

Directory#getFiles(greedy)

自身が含むファイルインスタンスを配列で取得する。
取得した配列を引数に解決するpromiseを返す。

const files = await dir.getFiles();

// options
const fileArr_deep_txt = await dir.getDirectories({
	greedy: true,
	filter(file){
		return file.ext==='txt';
	}}
);

Directory#has(string [, options])

自身が引数文字列名のファイル・ディレクトリを直接含んでいるか調べる。 結果のbooleanを引数に解決するpromiseを返す。

const bool = await dir.has('hoge');

// options
const hasSecretTextFile = await dir.has('fuga', {
	file: true,
	directory: false,
	async filter(file){
		const string = await file.read();
		return string.includes('password');
	}
});

Directory#list()

自身が直接含んでいるファイル・ディレクトリ名の配列を取得する。
取得した配列を引数に解決するpromiseを返す。

const nameArr = await dir.list();

Directory#search(rule, [, options])

自身の含む、引数1の条件と一致する名前を持つファイル・ディレクトリインスタンスを取得する。
取得したインスタンスかnullを引数に解決するpromiseを返す。

const file = await dir.search('hoge.txt');
const dir = await dir.search(/fuga|piyo/);
const file_txt = await dir.search( (instance)=>{
	return instance.isFile && instance.ext==='txt';
});

// options
const dirArr_deep_notEmpty = await dir.search(/./, {
	file: false,
	directory: true,
	global: true,
	greedy: true,
	async filter(dir){
		const list = dir.list();
		return list!==0;
	}
});

引数1

• string: ファイル名との完全一致。
• regexp: ファイル名とのmatch.
• function: インスタンスを引数に実行し、trueを返したもの。

Directory#size()

自身の含むファイル・ディレクトリの総サイズを数値で取得する。
取得した数値を引数に解決するpromiseを返す。

const size = await dir.size();

Directory#isDirectory

dir.isDirectory; // true

• Alias
  • Directory#isDir

File

new File(filepath [, config])

引数パスのファイルを基にfileインスタンスを作る。
作ったインスタンスを引数に解決するpromiseを返す。

const file = await new File('./filename.ext');

// config
const file = await new File('./filename.ext', {
	stats: fs.statSync('./filename.ext')
});

File.make(path, content [, filedataoptions])

引数1のパスに、引数2の内容でファイルを作成する。
作成したファイルのFileインスタンスを引数に解決するpromiseを返す。

const file = await File.make('hoge.txt', 'hogefugapiyo');

• 引数3
  • File System | Node.js Documentation

File#autoExt()

自身の実体から拡張子を推測して、可能なら改名する。
なにもしなければ自身を、改名していれば新しいインスタンスを引数に解決するpromiseを返す。

// filename => filename.ext
await file.autoExt();

// hoge => hoge.jpg
const image = await file.autoExt();

• 対応する拡張子一覧
  • sindresorhus/file-type: Detect the file type of a Buffer/Uint8Array

File#read([encode])

自身の内容を文字列で取得する。
取得した文字列を引数に解決するpromiseを返す。

const str = await file.read();

File#size()

自身のファイルサイズを数値で取得する。
取得した数値を引数に解決するpromiseを返す。

const size = await file.size();

File#write(string [, encode])

自身の内容を引数の文字列で書き換える。
書き換え後に解決するpromiseを返す。

await file.write('hogehoge');

File#basename

自身の拡張子を除いたファイル名の文字列。

const file = await new File('filename.ext');
file.basename; // "filename"

File#ext

自身の拡張子の文字列。

const file = await new File('filename.ext');
file.ext; // "ext"

File#isFile

file.isFile; // true

Image

Fileを継承している。

• 対応形式
  • bmp, jpg, png

new Image()

引数パスの画像ファイルを元にImageインスタンスを作る。
作ったインスタンスを引数に解决するpromiseを返す。

const image = await new Image('hoge.jpg');

Image.make(path, url or buffer)

引数1のパスに、引数2のURLかbufferを元に画像ファイルの実体を作成する。
作成した画像ファイルのImageインスタンスを引数に解决するpromiseを返す。

const image = await Image.make(
	'./hoge.jpg',
	'http://example.com/hoge.jpg'
);

Image#output(path, options)

引数1パスに、引数2の設定で画像ファイルの実体を作成する。
作成した画像ファイルのImageインスタンスを引数に解决するpromiseを返す。

// png, greyscale, auto*250px
const imageB = await imageA.output('./image-b.png', {
	greyscale: true,
	quality: 100,
	resize: ['jimp.AUTO', 250]
});

optionsについては以下を参照。

• oliver-moran/jimp: An image processing library written entirely in JavaScript for Node, with zero external or native dependencies.

Image#isImage

image.isImage; // true

JSON

Fileを継承している。

new JSON(filepath [, stats])

引数パスの.jsonファイルを基にJSONインスタンスを作る。
作ったインスタンスを引数に解決するpromiseを返す。

const json = await new JSON('hoge.json');

JSON.make(path [, object])

引数1パスに.jsonファイルを作成する。
引数2にオブジェクトが渡されていれば.jsonファイルに反映する。
作成したファイルのJSONインスタンスを引数に解決するpromiseを返す。

// => {}
const json = await JSON.make('hoge.json');

// => {"foo":"bar"}
const json = await JSON.make('hoge.json', {foo: 'bar'});

JSON#read()

自身の内容をオブジェクトで取得する。
取得したオブジェクトを引数に解決するpromiseを返す。

const obj = await json.read();

JSON#write(object)

引数オブジェクトを基に自身の実体へ書き込む。
書き込み後に解決するpromiseを返す。

await json.write({foo: 'bar'});

JSON#isJSON

json.isJSON; // true

JSON#space

自身の整形に使う値。

json.space = 2;
/*
{
  "key": "value"
}
*/

json.space = '\t';
/*
{
	"key": "value"
}
*/

ZIP

Fileを継承している。

new ZIP(filepath [, stats])

引数パスの.zipファイルを基にZIPインスタンスを作る。
作ったインスタンスを引数に解決するpromiseを返す。

const zip = await new ZIP('hoge.zip');

ZIP.make(...file or dir [, outputZipPath])

引数のFile, Directoryインスタンスの実体を圧縮する。
圧縮したファイルのZIPインスタンスを引数に解決するpromiseを返す。

// file.ext => file.zip
const zip = await ZIP.make(file);

// file.ext & dir => hoge.zip
const zip = await ZIP.make([file, dir], './hoge.zip');

ZIP#unzip(outputDirPath)

自身の実体を同じディレクトリか引数パスのディレクトリへ展開する。
展開先のDirectoryインスタンスを引数に解決するpromiseを返す。

// hoge.zip => ...
const dir = await zip.unzip();

// hoge.zip => output/...
const dir = await zip.unzip('./output');

ZIP#list()

自身の実体が持つコンテンツ一覧を配列で取得する。
取得した配列を引数に解決するpromiseを返す。

// [...'file.ext', 'dir/']
const arr = await zip.list();

ZIP#isZIP

zip.isZIP; // true

RAR

Fileを継承している。

new RAR(filepath [, stats])

引数パスの.rarファイルを基にRARインスタンスを作る。
作ったインスタンスを引数に解決するpromiseを返す。

const rar = await new RAR('hoge.rar');

RAR#extract(targetContent or [..targetContent], outputDirPath [, password])

自身の実体から引数1のコンテンツを、引数2のパスのディレクトリへ展開する。
展開先のDirectoryインスタンスを引数に解決するpromiseを返す。

// hoge.rar => output/dirinrar/file
const dir = await rar.extract('dirinrar/file', 'output');

// multi
const dir = await rar.extract([
	'dirinrar/fileA',
	'dirinrar/fileB'
], 'output');

RAR#extractAll(outputDirPath [, password])

自身の実体から全てのコンテンツを、引数1のパスのディレクトリへ展開する。
展開先のDirectoryインスタンスを引数に解決するpromiseを返す。

// hoge.rar => output/...
const dir = await rar.extractAll('output');

RAR#list([password])

自身の実体が持つコンテンツ一覧を配列で取得する。
取得した配列を引数に解決するpromiseを返す。

// [...'file.ext', 'dir/']
const arr = await rar.list();

RAR#isRAR

rar.isRAR; // true

Utility

コンストラクタじゃないよ。

Utilyti.download(url, filepath)

引数1のURLからファイルをダウンロードして引数2のパスに保存する。
保存したFileインスタンスを引数に解決するpromiseを返す。

const file = await Utility.download('http://example.com/hoge.txt', './hoge.txt');

Utility.getInstance(path [, stats])

引数パスを基に対応するインスタンスを作る。
作ったインスタンスを引数に解決するpromiseを返す。

// dir or file
const instance = await Utility.getInstance('path');

Utility.getDesktop(), getHomeDir(), getTempDir()

それぞれデスクトップ・ユーザー・テンポラリディレクトリのDirectoryインスタンスを作る。
作ったインスタンスを引数に解決するpromiseを返す。

const dir_desktop = await Utility.getDesktop();
const dir_home = await Utility.getHomeDir();
const dir_Temp = await Utility.getTempDir();

Utility.cache

キャッシュを管理するオブジェクト。
詳しくはhoneo/lru-cacheを参照。

// default 1000 => 300
Utility.cache.capacity = 300;

// default 1h => 3m
Utility.cache.expire = 1000*60*3;