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');
Copy

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 }
});
Copy

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)
Copy

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) => {})
Copy

append appendAsync

file.append(content: string)

await file.appendAsync(string);
Copy

exists existsAsync

let b: boolean = file.exists()

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

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>
Copy

rename renameAsync

file.rename(filename: string)

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

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>
Copy

remove removeAsync

file.remove(): boolean

file.removeAsync(): Promise<boolean>
Copy

watch

Watch file for changes

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

unwatch

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

Cache

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

clearCache

File.clearCache(<?string> path);
Copy

When path is null, then all cache is dropped.

disableCache

File.disableCache();
Copy

enableCache

File.disableCache();
Copy

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);
    })
    ;
Copy

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'
    ]
});
Copy

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
    }
};
Copy

Advanced middleware

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

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,