capacitor-fs

This is a lightning-fs based library created to support the use of filesystem on framework capacitor.

Important: If you are using version @capacitor/filesystem@1.1.0 or low please use version 0.0.41-b5 or below

If you are targeting the web i recommend using @tachibana-shin/capacitor-filesystem to avoid weird web behavior package.json
 ...
 "dependencies": {
   "@capacitor-filesystem": "npm:@tachibana-shin/capacitor-filesystem"
 }
 ...

Usage

`createFilesystem(Filesystem, opts?)`

First, create or open a "filesystem".

import { createFilesystem } from "capacitor-fs";
import { Filesystem, Directory } from "@capacitor/filesystem";

const fs = createFilesystem(Filesystem, {
   rootDir: "/",
   directory: Directory.Documents,
   base64Alway: false,
})

Note: It is better not to create multiple FS instances using the same name in a single thread. Memory usage will be higher as each instance maintains its own cache, and throughput may be lower as each instance will have to compete over the mutex for access to the IndexedDb store.

Options object:

Param	Type [= default]	Description
`rootDir`	string = "/"	Top level directory where is will work
`directory`	Directory = Directory.Documents	What kind of directory rootDir is in. View it
`base64Alway`	boolean = false	Allow fs to do full base64 permissions. this option will take care of all the silly errors about saving text files and buffer(image, audio, video, pdf...) of capacitor/filesystem. but it makes the `encoding` option of the writeFile function useless. When true it will save all data types in base64 with encoding = void 0 and preserve their encoding

Advanced usage

Make directory

Options object:

Param	Type [= default]	Description
`recursive`	recursive = false	Whether to recursively remove the contents of the directory

`fs.rmdir(path: string, { recursive?: boolean }): Promise<void>`

Remove directory

`fs.readdir(path: string): Promise<string[]>`

Read directory

The callback return value is an Array of strings. NOTE: To save time, it is NOT SORTED. (Fun fact: Node.js' readdir output is not guaranteed to be sorted either. I learned that the hard way.)

`fs.writeFile(path: string, data: ArrayBuffer | Uint8Array | Blob | string, { encoding?: Encoding | "buffer", recursive: boolean }): Promise<void>`

Options object:

Param	Type [= default]	Description
`recursive`	boolean = false	Whether to create any missing parent directories.
`encoding`	string = Encoding.UTF8	The encoding to write the file in. If not provided, data is written as base64 encoded. Pass Encoding.UTF8 to write data as string. If `base64Alway = true` this option is useless.

`fs.readFile(path: string, { encoding?: Encoding | "buffer" }): Promise<string | ArrayBuffer>`

The result value will be a Uint8Array (if encoding is 'buffer') or (if encoding is Encoding) a string.

If opts is a string, it is interpreted as { encoding: opts }.

Options object:

Param	Type [= default]	Description
`encoding`	Encoding	"buffer" = Encoding.UTF8

`fs.unlink(path: string): Promise<void>`

Delete a file

`fs.rename(oldPath: string, newPath: string): Promise<void>`

Rename a file or directory

`fs.stat(path: string, { bigint?: boolean }): Promise<Stat | StatBigInt>`

The result is a Stat object similar to the one used by Node but with fewer and slightly different properties and methods. The included properties are:

type ("file" or "dir")
mode
size
ino
mtimeMs
ctimeMs
uid (fixed value of 1)
gid (fixed value of 1)
dev (fixed value of 1)

The included methods are:

isFile()
isDirectory()
isSymbolicLink()

Options object:

Param	Type [= default]	Description
`bigint`	boolean = false	result StatBigInt

`fs.exists(path: string): Promise<boolean>`

Check file is exists

`fs.lstat(path: string): Promise<Stat | StatBigInt>`

Like fs.stat except that paths to symlinks return the symlink stats not the file stats of the symlink's target.

`fs.symlink(target: string, path: string): Promise<void>`

Create a symlink at path that points to target.

`fs.readlink(path: string, opts?)`

Read the target of a symlink.

`fs.backFile(filepath)`

Create or change the stat data for a file backed by HTTP. Size is fetched with a HEAD request. Useful when using an HTTP backend without urlauto set, as then files will only be readable if they have stat data. Note that stat data is made automatically from the file /.superblock.txt if found on the server. /.superblock.txt can be generated or updated with the included standalone script.

Options object:

Param	Type [= default]	Description
`mode`	number = 0o666	Posix mode permissions

`fs.du(path: string): Promise<number>`

Returns the size of a file or directory in bytes.

`fs.promises`

All the same functions as above, but instead of passing a callback they return a promise.

fs.promises = fs

Other methods

`fs.init(autofix?: boolean): Promise<void>`

Implement rootDir directory initialization if it does not exist. Options autofix removed rootDir if this is file.

`fs.clear(): Promise<void>`

Empty rootDir

`fs.relatively(path: string): string`

Returns the monotonic path of path. same as path.resolve but for createFilesystem

`fs.relative(from: string, to: string): string`

Returns the relative path of to relative to from, same as path.relative but for createFilesystem

`fs.isEqual(path1: string, path2: string): boolean`

Compare if 2 paths are the same. based on fs.relative. Example:

fs.isEqual("src/index.ts", "/src/index.ts") // true
fs.isEqual("src/index.ts", "src/posix/index.ts") // false
fs.isEqual("src/index.ts", "src/posix/../index.ts") // true

`fs.isParentDir(parent: string, path: string): boolean`

Compare if path is a child of parent. Example

fs.isEqual("src", "src/index.ts") // true
fs.isEqual("src", "src/posix/../index.ts") // true

`fs.replaceParentDir(path: string, parent: string, replace: string): string`

Replace parent path. based on fs.isParentDir

`fs.isDirectory(path: string): Promise<boolean>`

Return true if path exists and is directory.

`fs.isFile(path: string): Promise<boolean>`

Return 'true' if path exists and is file.

`fs.appendFile(path: string, data: ArrayBuffer | Uint8Array | Blob | string, { encoding?: Encoding | "buffer", recursive: boolean }): Promise<void>`

Same as fs.writeFile but writes further to the file.

`fs.on(type: Type, cb: (param: Events[Type]) => void) => () => void`

Listen for file system interaction events like write:file, remove:file, create:dir, remove:dir. Return function call cancel listener.

`fs.watch(path, cb, options?: WatchOptions) => () => void)`

A listener function like fs.on but more powerful and versatile

path: string | string[] | () => string | string[] what are we going to listen to. the input parameter is the expression pattern path shell or absolute path. Example projects/*/.git/index
cb: is a function that accepts as parameter { path: string, action: string }

Options object:

Param and type	Description
`mode?: "absolute"	"relative"
`type: ("file"	"dir"
`miniOpts?: minimatch.IOptions` = { dot: true }	minoptions for minimatch. only works if `options.mode = void 0`
`immediate?: boolean`	if set to `true`, cbr will be called as soon as tracking is registered
`exists?: boolean`	if set to `true`, `cb` will only be called when tracking objects exist
`dir?: null	string
`exclude?: string[]	(() => string[])`

Typescript

import type { Filesystem as CFS, Directory } from "@capacitor/filesystem";
import minimatch from "minimatch";
import { Stat, StatBigInt } from "./Stat";
declare type EncodingBuffer = "buffer";
declare type EncodingString = "utf8" | "utf16" | "ascii" | "base64";
declare type Encoding = EncodingString | EncodingBuffer;
export declare type Events = {
    readonly "write:file": string;
    readonly "remove:file": string;
    readonly "create:dir": string;
    readonly "remove:dir": string;
    readonly "*": string;
    readonly "move:file": {
        readonly from: string;
        readonly to: string;
    };
    readonly "move:dir": {
        readonly from: string;
        readonly to: string;
    };
};
declare type OptionsConstructor = {
    readonly rootDir?: string;
    readonly directory: Directory;
    readonly base64Alway?: boolean;
    readonly watcher?: boolean;
};
export declare function createFilesystem(Filesystem: typeof CFS, options: OptionsConstructor): {
    promises: {
        init: (autofix?: boolean) => Promise<void>;
        clear: () => Promise<void>;
        relatively: (path: string) => string;
        relative: (from: string, to: string) => string;
        isEqual: (path1: string, path2: string) => boolean;
        isParentDir: (parent: string, path: string) => boolean;
        replaceParentDir: (path: string, from: string, to: string) => string;
        mkdir: (path: string, options?: {
            readonly recursive?: boolean | undefined;
        } | undefined) => Promise<void>;
        rmdir: (path: string, options?: {
            readonly recursive?: boolean | undefined;
        } | undefined) => Promise<void>;
        readdir: (path: string) => Promise<readonly string[]>;
        writeFile: (path: string, data: ArrayBuffer | Blob | string, options?: Encoding | {
            readonly recursive?: boolean | undefined;
            readonly encoding?: Encoding | undefined;
        } | undefined) => Promise<void>;
        readFile: {
            (path: string, options?: "buffer" | {
                readonly encoding?: "buffer" | undefined;
            } | undefined): Promise<ArrayBuffer>;
            (path: string, options: {
                readonly encoding: EncodingString;
            } | EncodingString): Promise<string>;
            (path: string, options: {
                readonly encoding: Encoding;
            } | Encoding): Promise<string | ArrayBuffer>;
        };
        unlink: (path: string) => Promise<void>;
        rename: (oldPath: string, newPath: string) => Promise<void>;
        copy: (oldPath: string, newPath: string) => Promise<void>;
        stat: {
            (path: string): Promise<Stat>;
            (path: string, options: {
                readonly bigint: false;
            }): Promise<Stat>;
            (path: string, options: {
                readonly bigint: true;
            }): Promise<StatBigInt>;
            (path: string, options: {
                readonly bigint: boolean;
            }): Promise<Stat | StatBigInt>;
        };
        exists: (path: string) => Promise<boolean>;
        isDirectory: (path: string) => Promise<boolean>;
        isFile: (path: string) => Promise<boolean>;
        lstat: (path: string, options?: {
            readonly bigint: boolean;
        } | undefined) => Promise<Stat | StatBigInt>;
        symlink: (target: string, path: string) => Promise<void>;
        readlink: (path: string) => Promise<string>;
        backFile: (filepath: string) => Promise<number>;
        du: (path: string) => Promise<number>;
        getUri: (path: string) => Promise<string>;
        appendFile: (path: string, data: ArrayBuffer | Blob | string, options?: Encoding | {
            readonly encoding?: Encoding | undefined;
        } | undefined) => Promise<void>;
        on: <Type extends keyof Events>(type: Type, cb: (param: Events[Type]) => void) => {
            (): void;
        };
        watch: (path: string | readonly string[] | (() => string | readonly string[]), cb: (param: {
            readonly path: string;
            readonly action: keyof Events;
        }) => void | Promise<void>, { mode, type, miniOpts, immediate, exists, dir, }?: {
            readonly mode?: "absolute" | "relative" | "abstract" | undefined;
            readonly type?: "*" | "file" | "dir" | undefined;
            readonly miniOpts?: minimatch.IOptions | undefined;
            readonly immediate?: boolean | undefined;
            readonly exists?: boolean | undefined;
            readonly dir?: string | (() => string | null) | null | undefined;
        }) => {
            (): void;
        };
    };
    init: (autofix?: boolean) => Promise<void>;
    clear: () => Promise<void>;
    relatively: (path: string) => string;
    relative: (from: string, to: string) => string;
    isEqual: (path1: string, path2: string) => boolean;
    isParentDir: (parent: string, path: string) => boolean;
    replaceParentDir: (path: string, from: string, to: string) => string;
    mkdir: (path: string, options?: {
        readonly recursive?: boolean | undefined;
    } | undefined) => Promise<void>;
    rmdir: (path: string, options?: {
        readonly recursive?: boolean | undefined;
    } | undefined) => Promise<void>;
    readdir: (path: string) => Promise<readonly string[]>;
    writeFile: (path: string, data: ArrayBuffer | Blob | string, options?: Encoding | {
        readonly recursive?: boolean | undefined;
        readonly encoding?: Encoding | undefined;
    } | undefined) => Promise<void>;
    readFile: {
        (path: string, options?: "buffer" | {
            readonly encoding?: "buffer" | undefined;
        } | undefined): Promise<ArrayBuffer>;
        (path: string, options: {
            readonly encoding: EncodingString;
        } | EncodingString): Promise<string>;
        (path: string, options: {
            readonly encoding: Encoding;
        } | Encoding): Promise<string | ArrayBuffer>;
    };
    unlink: (path: string) => Promise<void>;
    rename: (oldPath: string, newPath: string) => Promise<void>;
    copy: (oldPath: string, newPath: string) => Promise<void>;
    stat: {
        (path: string): Promise<Stat>;
        (path: string, options: {
            readonly bigint: false;
        }): Promise<Stat>;
        (path: string, options: {
            readonly bigint: true;
        }): Promise<StatBigInt>;
        (path: string, options: {
            readonly bigint: boolean;
        }): Promise<Stat | StatBigInt>;
    };
    exists: (path: string) => Promise<boolean>;
    isDirectory: (path: string) => Promise<boolean>;
    isFile: (path: string) => Promise<boolean>;
    lstat: (path: string, options?: {
        readonly bigint: boolean;
    } | undefined) => Promise<Stat | StatBigInt>;
    symlink: (target: string, path: string) => Promise<void>;
    readlink: (path: string) => Promise<string>;
    backFile: (filepath: string) => Promise<number>;
    du: (path: string) => Promise<number>;
    getUri: (path: string) => Promise<string>;
    appendFile: (path: string, data: ArrayBuffer | Blob | string, options?: Encoding | {
        readonly encoding?: Encoding | undefined;
    } | undefined) => Promise<void>;
    on: <Type extends keyof Events>(type: Type, cb: (param: Events[Type]) => void) => {
        (): void;
    };
    watch: (path: string | readonly string[] | (() => string | readonly string[]), cb: (param: {
        readonly path: string;
        readonly action: keyof Events;
    }) => void | Promise<void>, { mode, type, miniOpts, immediate, exists, dir, }?: {
        readonly mode?: "absolute" | "relative" | "abstract" | undefined;
        readonly type?: "*" | "file" | "dir" | undefined;
        readonly miniOpts?: minimatch.IOptions | undefined;
        readonly immediate?: boolean | undefined;
        readonly exists?: boolean | undefined;
        readonly dir?: string | (() => string | null) | null | undefined;
    }) => {
        (): void;
    };
};
export default createFilesystem;
export { Stat, StatBigInt };

capacitor-fs

capacitor-fs

Usage

createFilesystem(Filesystem, opts?)

Advanced usage

fs.rmdir(path: string, { recursive?: boolean }): Promise<void>

fs.readdir(path: string): Promise<string[]>

fs.writeFile(path: string, data: ArrayBuffer | Uint8Array | Blob | string, { encoding?: Encoding | "buffer", recursive: boolean }): Promise<void>

fs.readFile(path: string, { encoding?: Encoding | "buffer" }): Promise<string | ArrayBuffer>

fs.unlink(path: string): Promise<void>

fs.rename(oldPath: string, newPath: string): Promise<void>

fs.stat(path: string, { bigint?: boolean }): Promise<Stat | StatBigInt>

fs.exists(path: string): Promise<boolean>

fs.lstat(path: string): Promise<Stat | StatBigInt>

fs.symlink(target: string, path: string): Promise<void>

fs.readlink(path: string, opts?)

fs.backFile(filepath)

fs.du(path: string): Promise<number>

fs.promises

Other methods

fs.init(autofix?: boolean): Promise<void>

fs.clear(): Promise<void>

fs.relatively(path: string): string

fs.relative(from: string, to: string): string

fs.isEqual(path1: string, path2: string): boolean

fs.isParentDir(parent: string, path: string): boolean

fs.replaceParentDir(path: string, parent: string, replace: string): string

fs.isDirectory(path: string): Promise<boolean>

fs.isFile(path: string): Promise<boolean>

fs.appendFile(path: string, data: ArrayBuffer | Uint8Array | Blob | string, { encoding?: Encoding | "buffer", recursive: boolean }): Promise<void>

fs.on(type: Type, cb: (param: Events[Type]) => void) => () => void

fs.watch(path, cb, options?: WatchOptions) => () => void)

Typescript

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`createFilesystem(Filesystem, opts?)`

`fs.rmdir(path: string, { recursive?: boolean }): Promise<void>`

`fs.readdir(path: string): Promise<string[]>`

`fs.writeFile(path: string, data: ArrayBuffer | Uint8Array | Blob | string, { encoding?: Encoding | "buffer", recursive: boolean }): Promise<void>`

`fs.readFile(path: string, { encoding?: Encoding | "buffer" }): Promise<string | ArrayBuffer>`

`fs.unlink(path: string): Promise<void>`

`fs.rename(oldPath: string, newPath: string): Promise<void>`

`fs.stat(path: string, { bigint?: boolean }): Promise<Stat | StatBigInt>`

`fs.exists(path: string): Promise<boolean>`

`fs.lstat(path: string): Promise<Stat | StatBigInt>`

`fs.symlink(target: string, path: string): Promise<void>`

`fs.readlink(path: string, opts?)`

`fs.backFile(filepath)`

`fs.du(path: string): Promise<number>`

`fs.promises`

`fs.init(autofix?: boolean): Promise<void>`

`fs.clear(): Promise<void>`

`fs.relatively(path: string): string`

`fs.relative(from: string, to: string): string`

`fs.isEqual(path1: string, path2: string): boolean`

`fs.isParentDir(parent: string, path: string): boolean`

`fs.replaceParentDir(path: string, parent: string, replace: string): string`

`fs.isDirectory(path: string): Promise<boolean>`

`fs.isFile(path: string): Promise<boolean>`

`fs.appendFile(path: string, data: ArrayBuffer | Uint8Array | Blob | string, { encoding?: Encoding | "buffer", recursive: boolean }): Promise<void>`

`fs.on(type: Type, cb: (param: Events[Type]) => void) => () => void`

`fs.watch(path, cb, options?: WatchOptions) => () => void)`

Weekly Downloads