Nero Punished Miscreants

    @buttercup/file-interface
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    File Interface

    Client request library interface and explorer

    build status npm version

    About

    Reading, writing and exploring file systems within Buttercup has typically been a complex process with differing approaches on the different application platforms. This library is intended to provide a common API with which to build the following tools:

    • File explorer interface (between client and UI)
    • File creation (new vault feature)
    • File selection (UI, returing identifier)

    The API provided by this library is common across all data providers:

    None of these packages are included in this repository and are expected to be provided at runtime.

    To create each of the interfaces, run the following:

    import { instantiateInterface } from "@buttercup/file-interface";
    
    const fsInterface = instantiateInterface("fs", { fs });
    const googleDriveInterface = instantiateInterface("googledrive", { googleDriveClient });
    const dropboxInterface = instantiateInterface("dropbox", { dropboxClient });
    const webdavInterface = instantiateInterface("webdav", { webdavClient });

    Installation

    Install by running: npm install @buttercup/file-interface --save

    Environment support

    This library supports NodeJS version 10 and above.

    Usage

    An interface is created when required, once you have the necessary components for the interface to function:

    import { instantiateInterface } from "@buttercup/file-interface";
    import fs from "fs";
    
    const fsInterface = instantiateInterface("fs", { fs });
    fsInterface.getDirectoryContents({ identifier: "./dirname" }).then(results => {
        // Returns something like the following:
        // [{
        //     identifier: "/root/dirname/testfile.txt",
        //     name: "testfile.txt",
        //     type: "file",
        //     size: 231,
        //     created: "Mon, 10 Oct 2011 23:24:11 GMT",
        //     modified: "Mon, 11 Oct 2011 10:57:44 GMT"
        // }]
    });

    You'll notice a lot of identifier usage when calling methods provided by this library. As some remote systems require more information, the API for this project uses identifier objects (parent and file) to collect information that better describes remote objects in enough detail to be usable across file systems. Google Drive, for example, doesn't use typical paths - instead files and directories are referred to by IDs:

    import { instantiateInterface } from "@buttercup/file-interface";
    import { createClient } from "@buttercup/googledrive-client";
    
    const googleDriveClient = createClient(myToken);
    const fsInterface = instantiateInterface("googledrive", { googleDriveClient });
    
    fsInterface.getDirectoryContents({ identifier: "<dir-id>" }).then(results => {
        // Returns something like the following:
        // [{
        //     identifier: "0BxOS7mTBMR_bMHZRUjJ5NU1ZOWs",
        //     name: "testfile.txt",
        //     type: "file",
        //     size: 231,
        //     created: "Mon, 10 Oct 2011 23:24:11 GMT",
        //     modified: "Mon, 11 Oct 2011 10:57:44 GMT"
        // }]
    });
    
    // Update existing file
    fsInterface.putFileContents(
        { identifier: "<dir-id>" },
        { identifier: "0BxOS7mTBMR_bMHZRUjJ5NU1ZOWs", name: "testfile.txt" },
        "some data"
    );
    
    // Write new file
    fsInterface.putFileContents(
        { identifier: "<dir-id>" },
        { identifier: null, name: "newfile.txt" },
        "some data"
    ).then(result => {
        // `result` is like:
        // {
        //     identifier: "0BxOS7mTBMR_bMHZRUjJ5NU1ZOWs",
        //     name: "newfile.txt"
        // }
    });

    Supported fields

    When calling getDirectoryContents, some base fields are always available:

    • identifier: The identifying path or ID of the file/directory
    • filename: The base filename of the file/directory
    • type: Either "file" or "directory"
    • size: The size, in bytes, of the item (always 0 for directories)

    Other additional fields are sometimes returned, based upon what the remote system supports. These can be detected by calling the getSupportedFeatures method on the interface instance. It returns an array of strings that indicate what is specified on each returned file item:

    • created indicates that a field called created is present on every file item, which is the creation date of the file.
    • modified indicates that a field called modified is present on every file item, which is the modification date of the file.
    • mime indicates that a field called mime is present on each file item, containing the MIME type of the item.

    Install

    npm i @buttercup/file-interface

    DownloadsWeekly Downloads

    44

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    68.2 kB

    Total Files

    18

    Last publish

    Collaborators

    • perrymitchell
    • sallar