atma-io

FileSystem Module

Features:

• File Class.
• Directory Class.
• File IO Middlewares to preprocess reads and writes actions.
• File Transport middleware for custom file protocols, e.g. s3://uploads/avatar.png
• Sync and Async
• Safe Files to ensure thread-safe and process-safe file writes.
• File-locks to make custom process-safe actions easy to implement.
• File watcher: cross-platform file watchers.
• AES-256 Encryption
• HTTP Transport: get, post, put, head and delete methods to handle files.

📚 API Documentation

In comparison to NodeJS sync-async contract: all functions with generic name are synchronous, and the **Async are asynchronous with the same interface. Sync versions never throw exceptions and are designed to be used in not performance critical applications, like bash scripts, etc. Go Async.

• File
  • API
  • Cache
  • Middleware
  • Virtual File
• Directory
  • API

File

File methods

File constructor

import { File } from 'atma-io'

const file = new File('./test.txt');

Path is relative to the cwd (except windows os, when drive letter is used). To specify system absolute path, use file:// protocol.

read readAsync

Read file's content. If encoding is set to null raw Buffer is returned. For each read middleware pipeline is used, to skip it, set skipHooks to true.

Hooks will be per default executed. For example, when reading from *.json file the string will be deserialized to json object

let content = file.read<TOut = string>( options?: {
    encoding?: 'buffer' | 'utf8' //> default 'utf8'
    skipHooks?: boolean //> false
    aes256?: { secret: string }
});

let content = await file.readAsync <TOut = string> (options?: {
    encoding?: 'buffer' | 'utf8', //> 'utf8'
    skipHooks?: boolean //> false
    aes256?: { secret: string }
});

readRange readRangeAsync

Get bytes or string for a range from the file

let content = file.readRange(position, length);

let content = await file.readRangeAsync(position, length)

write writeAsync

Hooks will be per default executed. For example, when writing to *.json file and providing an object, this object will be serialized to json string

file.write(string | Buffer | any, options?: {
    skipHooks?: boolean
    aes256?: { secret: string }
})

file
    .writeAsync(content: string | Buffer | any, options?: {
        skipHooks?: boolean
        aes256?: { secret: string }
    })
    .then(() => {}, (err) => {})

append appendAsync

file.append(content: string)

await file.appendAsync(string);

exists existsAsync

let b: boolean = file.exists()

let b: boolean = await file.existsAsync();

copyTo copyToAsync

interface IFileCopyOpts {
    silent?: boolean
    baseSource?: string
}
/**
 * @param path: Target file path or directory, when ends with slash
 */
file.copyTo(path: string, opts?: IFileCopyOpts): boolean

file.copyToAsync(path: string, opts?: IFileCopyOpts): Promise<boolean>

rename renameAsync

file.rename(filename: string)

file.renameAsync(filename: string): Promise<void>

replace replaceAsync

Reads the content as string, replaces the matches and writes the result. Expected arguments are the same as for JavaScripts string replace. Returns new content.

file.replace(search: string | RegExp, replacer: string | Function): string

file.replaceAsync(search: string | RegExp, replacer: string | Function): Promise<string>

remove removeAsync

file.remove(): boolean

file.removeAsync(): Promise<boolean>

watch

Watch file for changes

file.watch(cb: (path) => void)

unwatch

file.unwatch(cb?: (path) => void): boolean

Cache

Each read will be cached. To control cache behavior use next methods:

clearCache

File.clearCache(<?string> path);

When path is null, then all cache is dropped.

disableCache

File.disableCache();

enableCache

File.disableCache();

short forms

There are some static methods, so that there is no need to initialize the File instance.

File[method] //> Function(filepath, [..args])
// methods:
        'exists'
        'existsAsync'
        'read'
        'readAsync'
        'readRange'
        'readRangeAsync'
        'write'
        'writeAsync'
        'append'
        'appendAsync'
        'remove'
        'removeAsync'
        'replace'
        'replaceAsync'
        'rename'
        'renameAsync'
        'copyTo'
        'copyToAsync'

// sample
File
    .readAsync('/baz.txt')
    .done(function(content){
        console.log(content);
    })
    .fail(function(error){
        console.error(error);
    })
    ;

File Middleware

Middleware pattern is used for all reads and writes. It can be used, for example, to compile coffee script to javascript on the fly. Or when reading *.yml file, the resulted content is not a YAML string, but already parsed object.

Extensions

To get the idea, look at the hook definition sample:

import { File } from 'atma-io'
File.registerExtensions({
    'coffee':[
        'conditions:read',
        'coffee-compiler:read',
        'uglify:write'
    ]
});

Each middleware has unique name and is registered in this way:

import { File } from 'atma-io'
File.middleware['coffee'] = {
    read: function(<io.File> file, <Object> config){
        let coffee = require('coffee-script');
        file.content = coffee.compile(file.content);
    },
    write: function(<io.File> file, <Object> config){
        // ... do smth with `content` before disk write
    }
};

Advanced middleware

import { File } from 'atma-io'
File
    .getHookHandler()
    .register({
        regexp: <RegExp>,
        method: <'read'|'write'>,
        handler: <Function | Object> handler,
        zIndex: <?Number> // default: 0
    });

Path is matched by the regexp. The greater zIndex is, the later it is called in the pipeline, otherwise the handlers are called in the order they were registered.

Embedded middlewares

Lately will be converted into plugins, @see Plugins

• read

  • coffee ( -> javascript )
  • markdown ( -> html )
  • jshint ( -> run jshint )
  • json ( -> JSON.parse is used )
  • yml ( -> YAML parser is used )

• write

  • uglify ( -> Minify source before write)
  • cssmin ( -> Minify source before write)
  • yml ( -> stringify object to yml string )
  • json ( -> stringify object to json )

Middleware Plugins

There additional read/write middlewares as atma plugins:

atma plugin install NAME

• atma-loader-ts - Compiles [Typescript]
• atma-loader-less - Compiles Less
• atma-loader-sass - Compiles SASS
• atma-io-middleware-yml - Parse YML and returns the Object
• atma-io-transport-s3 - Read/Save s3:// files paths from/to S3 storage

Combined middlewares

For example, you want to use Traceur middelware and jshint for reading js files: via javascript

File.registerExtensions({
    js: ['hint:read', 'atma-loader-ts:read' /* ... */],
})

via package.json

...
"atma": {
    "settings" : {
        "io": {
            "extensions": {
                "js": [ "hint:read", "atma-loader-ts:read" ]
            }
        }
    }
}

Virtual Files

Define with RegExp a File Handler to completely override the read/write/exists/remove behavior.

import { File } from 'atma-io'
File
    .getFactory()
    .registerHandler(/defaults\.json$/i, class {
        exists (){
            return true;
        },
        read (){
            return { foo: 'bar' };
        }
    });

Directory

Directory methods

Constructor

import { Directory } from 'atma-io'
let dir = new Directory('src/');

Path is always relative to the cwd (except windows os, when drive letter is used). To specify system absolute path, use file:// protocol.

exists

dir.exists()//> boolean

existsAsync

dir.existsAsync()//> Deferred

readFiles

dir.readFiles(<?string> pattern).files // Array<io.Files>

Get list of all files in the directory. pattern is a glob pattern.

// all javascript files, also from sub-directories
pattern = '*.js';
// only from base directory
pattern = '/*.js'
// only from sub-directories
pattern = '**/*.js'

dir.readFiles(pattern).files

readFilesAsync

let files: File[] = await dir.readFilesAsync(globPattern?);

copyTo

Copy files to destination directory. Before copying dir.readFiles can be called to copy only specific files.

dir.copyTo(destination: string)

copyToAsync

dir.copyToAsync(destination: string) //> Deferred

rename

dir.rename(<string> folderName);

renameAsync

dir.renameAsync(<string> folderName) //> Deferred

remove

Removes all content recursively and the folder itself

dir.remove() //> boolean

removeAsync

dir.removeAsync()

ensure

dir.ensure()

Creates directory structure, if not already exists.

ensureAsync

dir.ensureAsync()

watch

dir.watch(callback)

Watch directory for changes

unwatch

dir.unwatch(callback)

short forms

There are some static methods, so that there is no need to initialize the Directory instance.

Directory[method] //> Function(dirpath, [..args])
// methods:
    'exists'
    'existsAsync'
    'readFiles'
    'readFilesAsync'
    'ensure'
    'ensureAsync'
    'remove'
    'removeAsync'
    'copyTo'
    'copyToAsync'

// sample
io
    .Directory
    .readFilesAsync('sub/', '**.js')
    .done(function(files))
    .fail(function(error))

(c) MIT - Atma.js Project