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

1 ...
2 "dependencies": {
3   "@capacitor-filesystem": "npm:@tachibana-shin/capacitor-filesystem"
4 }
5 ...

Usage

createFilesystem(Filesystem, opts?)

First, create or open a "filesystem".

1import { createFilesystem } from "capacitor-fs";
2import { Filesystem, Directory } from "@capacitor/filesystem";
3
4const fs = createFilesystem(Filesystem, {
5   rootDir: "/",
6   directory: Directory.Documents,
7   base64Alway: false,
8})

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:

1fs.isEqual("src/index.ts", "/src/index.ts") // true
2fs.isEqual("src/index.ts", "src/posix/index.ts") // false
3fs.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

1fs.isEqual("src", "src/index.ts") // true
2fs.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

1import type { Filesystem as CFS, Directory } from "@capacitor/filesystem";
2import minimatch from "minimatch";
3import { Stat, StatBigInt } from "./Stat";
4declare type EncodingBuffer = "buffer";
5declare type EncodingString = "utf8" | "utf16" | "ascii" | "base64";
6declare type Encoding = EncodingString | EncodingBuffer;
7export declare type Events = {
8    readonly "write:file": string;
9    readonly "remove:file": string;
10    readonly "create:dir": string;
11    readonly "remove:dir": string;
12    readonly "*": string;
13    readonly "move:file": {
14        readonly from: string;
15        readonly to: string;
16    };
17    readonly "move:dir": {
18        readonly from: string;
19        readonly to: string;
20    };
21};
22declare type OptionsConstructor = {
23    readonly rootDir?: string;
24    readonly directory: Directory;
25    readonly base64Alway?: boolean;
26    readonly watcher?: boolean;
27};
28export declare function createFilesystem(Filesystem: typeof CFS, options: OptionsConstructor): {
29    promises: {
30        init: (autofix?: boolean) => Promise<void>;
31        clear: () => Promise<void>;
32        relatively: (path: string) => string;
33        relative: (from: string, to: string) => string;
34        isEqual: (path1: string, path2: string) => boolean;
35        isParentDir: (parent: string, path: string) => boolean;
36        replaceParentDir: (path: string, from: string, to: string) => string;
37        mkdir: (path: string, options?: {
38            readonly recursive?: boolean | undefined;
39        } | undefined) => Promise<void>;
40        rmdir: (path: string, options?: {
41            readonly recursive?: boolean | undefined;
42        } | undefined) => Promise<void>;
43        readdir: (path: string) => Promise<readonly string[]>;
44        writeFile: (path: string, data: ArrayBuffer | Blob | string, options?: Encoding | {
45            readonly recursive?: boolean | undefined;
46            readonly encoding?: Encoding | undefined;
47        } | undefined) => Promise<void>;
48        readFile: {
49            (path: string, options?: "buffer" | {
50                readonly encoding?: "buffer" | undefined;
51            } | undefined): Promise<ArrayBuffer>;
52            (path: string, options: {
53                readonly encoding: EncodingString;
54            } | EncodingString): Promise<string>;
55            (path: string, options: {
56                readonly encoding: Encoding;
57            } | Encoding): Promise<string | ArrayBuffer>;
58        };
59        unlink: (path: string) => Promise<void>;
60        rename: (oldPath: string, newPath: string) => Promise<void>;
61        copy: (oldPath: string, newPath: string) => Promise<void>;
62        stat: {
63            (path: string): Promise<Stat>;
64            (path: string, options: {
65                readonly bigint: false;
66            }): Promise<Stat>;
67            (path: string, options: {
68                readonly bigint: true;
69            }): Promise<StatBigInt>;
70            (path: string, options: {
71                readonly bigint: boolean;
72            }): Promise<Stat | StatBigInt>;
73        };
74        exists: (path: string) => Promise<boolean>;
75        isDirectory: (path: string) => Promise<boolean>;
76        isFile: (path: string) => Promise<boolean>;
77        lstat: (path: string, options?: {
78            readonly bigint: boolean;
79        } | undefined) => Promise<Stat | StatBigInt>;
80        symlink: (target: string, path: string) => Promise<void>;
81        readlink: (path: string) => Promise<string>;
82        backFile: (filepath: string) => Promise<number>;
83        du: (path: string) => Promise<number>;
84        getUri: (path: string) => Promise<string>;
85        appendFile: (path: string, data: ArrayBuffer | Blob | string, options?: Encoding | {
86            readonly encoding?: Encoding | undefined;
87        } | undefined) => Promise<void>;
88        on: <Type extends keyof Events>(type: Type, cb: (param: Events[Type]) => void) => {
89            (): void;
90        };
91        watch: (path: string | readonly string[] | (() => string | readonly string[]), cb: (param: {
92            readonly path: string;
93            readonly action: keyof Events;
94        }) => void | Promise<void>, { mode, type, miniOpts, immediate, exists, dir, }?: {
95            readonly mode?: "absolute" | "relative" | "abstract" | undefined;
96            readonly type?: "*" | "file" | "dir" | undefined;
97            readonly miniOpts?: minimatch.IOptions | undefined;
98            readonly immediate?: boolean | undefined;
99            readonly exists?: boolean | undefined;
100            readonly dir?: string | (() => string | null) | null | undefined;
101        }) => {
102            (): void;
103        };
104    };
105    init: (autofix?: boolean) => Promise<void>;
106    clear: () => Promise<void>;
107    relatively: (path: string) => string;
108    relative: (from: string, to: string) => string;
109    isEqual: (path1: string, path2: string) => boolean;
110    isParentDir: (parent: string, path: string) => boolean;
111    replaceParentDir: (path: string, from: string, to: string) => string;
112    mkdir: (path: string, options?: {
113        readonly recursive?: boolean | undefined;
114    } | undefined) => Promise<void>;
115    rmdir: (path: string, options?: {
116        readonly recursive?: boolean | undefined;
117    } | undefined) => Promise<void>;
118    readdir: (path: string) => Promise<readonly string[]>;
119    writeFile: (path: string, data: ArrayBuffer | Blob | string, options?: Encoding | {
120        readonly recursive?: boolean | undefined;
121        readonly encoding?: Encoding | undefined;
122    } | undefined) => Promise<void>;
123    readFile: {
124        (path: string, options?: "buffer" | {
125            readonly encoding?: "buffer" | undefined;
126        } | undefined): Promise<ArrayBuffer>;
127        (path: string, options: {
128            readonly encoding: EncodingString;
129        } | EncodingString): Promise<string>;
130        (path: string, options: {
131            readonly encoding: Encoding;
132        } | Encoding): Promise<string | ArrayBuffer>;
133    };
134    unlink: (path: string) => Promise<void>;
135    rename: (oldPath: string, newPath: string) => Promise<void>;
136    copy: (oldPath: string, newPath: string) => Promise<void>;
137    stat: {
138        (path: string): Promise<Stat>;
139        (path: string, options: {
140            readonly bigint: false;
141        }): Promise<Stat>;
142        (path: string, options: {
143            readonly bigint: true;
144        }): Promise<StatBigInt>;
145        (path: string, options: {
146            readonly bigint: boolean;
147        }): Promise<Stat | StatBigInt>;
148    };
149    exists: (path: string) => Promise<boolean>;
150    isDirectory: (path: string) => Promise<boolean>;
151    isFile: (path: string) => Promise<boolean>;
152    lstat: (path: string, options?: {
153        readonly bigint: boolean;
154    } | undefined) => Promise<Stat | StatBigInt>;
155    symlink: (target: string, path: string) => Promise<void>;
156    readlink: (path: string) => Promise<string>;
157    backFile: (filepath: string) => Promise<number>;
158    du: (path: string) => Promise<number>;
159    getUri: (path: string) => Promise<string>;
160    appendFile: (path: string, data: ArrayBuffer | Blob | string, options?: Encoding | {
161        readonly encoding?: Encoding | undefined;
162    } | undefined) => Promise<void>;
163    on: <Type extends keyof Events>(type: Type, cb: (param: Events[Type]) => void) => {
164        (): void;
165    };
166    watch: (path: string | readonly string[] | (() => string | readonly string[]), cb: (param: {
167        readonly path: string;
168        readonly action: keyof Events;
169    }) => void | Promise<void>, { mode, type, miniOpts, immediate, exists, dir, }?: {
170        readonly mode?: "absolute" | "relative" | "abstract" | undefined;
171        readonly type?: "*" | "file" | "dir" | undefined;
172        readonly miniOpts?: minimatch.IOptions | undefined;
173        readonly immediate?: boolean | undefined;
174        readonly exists?: boolean | undefined;
175        readonly dir?: string | (() => string | null) | null | undefined;
176    }) => {
177        (): void;
178    };
179};
180export default createFilesystem;
181export { Stat, StatBigInt };

License

MIT (c) 2021 Tachibana Shin