npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@gauravachhani/filesystem

v1.0.5

Published

The Filesystem API provides a NodeJS-like API for working with files on the device.

Downloads

16

Readme

@gauravachhani/filesystem

The Filesystem API provides a NodeJS-like API for working with files on the device.

Install

npm install @gauravachhani/filesystem
npx cap sync

Android

If using Directory.Documents or Directory.ExternalStorage, this API requires the following permissions be added to your AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Read about Setting Permissions in the Android Guide for more information on setting Android permissions.

Note that Directory.Documents and Directory.ExternalStorage are only available on Android 9 or older.

Understanding Directories and Files

iOS and Android have additional layers of separation between files, such as special directories that are backed up to the Cloud, or ones for storing Documents. The Filesystem API offers a simple way to scope each operation to a specific special directory on the device.

Additionally, the Filesystem API supports using full file:// paths, or reading content:// files on Android. Simply leave out the directory param to use a full file path.

Example

import { Filesystem, Directory, Encoding } from '@gauravachhani/filesystem';

const writeSecretFile = async () => {
  await Filesystem.writeFile({
    path: 'secrets/text.txt',
    data: "This is a test",
    directory: Directory.Documents,
    encoding: Encoding.UTF8,
  });
};

const readSecretFile = async () => {
  const contents = await Filesystem.readFile({
    path: 'secrets/text.txt',
    directory: Directory.Documents,
    encoding: Encoding.UTF8,
  });

  console.log('secrets:', contents);
};

const deleteSecretFile = async () => {
  await Filesystem.deleteFile({
    path: 'secrets/text.txt',
    directory: Directory.Documents,
  });
};

const readFilePath = async () => {
  // Here's an example of reading a file with a full file path. Use this to
  // read binary data (base64 encoded) from plugins that return File URIs, such as
  // the Camera.
  const contents = await Filesystem.readFile({
    path: 'file:///var/mobile/Containers/Data/Application/22A433FD-D82D-4989-8BE6-9FC49DEA20BB/Documents/text.txt'
  });

  console.log('data:', contents);
};

API

readFile(...)

readFile(options: ReadFileOptions) => Promise<ReadFileResult>

Read a file from disk

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | ReadFileOptions |

Returns: Promise<ReadFileResult>

Since: 1.0.0


writeFile(...)

writeFile(options: WriteFileOptions) => Promise<WriteFileResult>

Write a file to disk in the specified location on device

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | WriteFileOptions |

Returns: Promise<WriteFileResult>

Since: 1.0.0


appendFile(...)

appendFile(options: AppendFileOptions) => Promise<void>

Append to a file on disk in the specified location on device

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | AppendFileOptions |

Since: 1.0.0


deleteFile(...)

deleteFile(options: DeleteFileOptions) => Promise<void>

Delete a file from disk

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | DeleteFileOptions |

Since: 1.0.0


mkdir(...)

mkdir(options: MkdirOptions) => Promise<void>

Create a directory.

| Param | Type | | ------------- | ----------------------------------------------------- | | options | MkdirOptions |

Since: 1.0.0


rmdir(...)

rmdir(options: RmdirOptions) => Promise<void>

Remove a directory

| Param | Type | | ------------- | ----------------------------------------------------- | | options | RmdirOptions |

Since: 1.0.0


readdir(...)

readdir(options: ReaddirOptions) => Promise<ReaddirResult>

Return a list of files from the directory (not recursive)

| Param | Type | | ------------- | --------------------------------------------------------- | | options | ReaddirOptions |

Returns: Promise<ReaddirResult>

Since: 1.0.0


getUri(...)

getUri(options: GetUriOptions) => Promise<GetUriResult>

Return full File URI for a path and directory

| Param | Type | | ------------- | ------------------------------------------------------- | | options | GetUriOptions |

Returns: Promise<GetUriResult>

Since: 1.0.0


stat(...)

stat(options: StatOptions) => Promise<StatResult>

Return data about a file

| Param | Type | | ------------- | --------------------------------------------------- | | options | StatOptions |

Returns: Promise<StatResult>

Since: 1.0.0


rename(...)

rename(options: RenameOptions) => Promise<void>

Rename a file or directory

| Param | Type | | ------------- | --------------------------------------------------- | | options | CopyOptions |

Since: 1.0.0


copy(...)

copy(options: CopyOptions) => Promise<void>

Copy a file or directory

| Param | Type | | ------------- | --------------------------------------------------- | | options | CopyOptions |

Since: 1.0.0


checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check read/write permissions. Required on Android, only when using Directory.Documents or Directory.ExternalStorage.

Returns: Promise<PermissionStatus>

Since: 1.0.0


requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request read/write permissions. Required on Android, only when using Directory.Documents or Directory.ExternalStorage.

Returns: Promise<PermissionStatus>

Since: 1.0.0


Interfaces

ReadFileResult

| Prop | Type | Description | Since | | ---------- | ------------------- | ----------------------------------------------------------- | ----- | | data | string | The string representation of the data contained in the file | 1.0.0 |

ReadFileOptions

| Prop | Type | Description | Since | | --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | path | string | The path of the file to read | 1.0.0 | | directory | Directory | The Directory to read the file from | 1.0.0 | | encoding | Encoding | The encoding to read the file in, if not provided, data is read as binary and returned as base64 encoded. Pass Encoding.UTF8 to read data as string | 1.0.0 |

WriteFileResult

| Prop | Type | Description | Since | | --------- | ------------------- | --------------------------------------- | ----- | | uri | string | The uri where the file was written into | 1.0.0 |

WriteFileOptions

| Prop | Type | Description | Default | Since | | --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | | path | string | The path of the file to write | | 1.0.0 | | data | string | The data to write | | 1.0.0 | | directory | Directory | The Directory to store the file in | | 1.0.0 | | encoding | Encoding | The encoding to write the file in. If not provided, data is written as base64 encoded. Pass Encoding.UTF8 to write data as string | | 1.0.0 | | recursive | boolean | Whether to create any missing parent directories. | false | 1.0.0 |

AppendFileOptions

| Prop | Type | Description | Since | | --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | path | string | The path of the file to append | 1.0.0 | | data | string | The data to write | 1.0.0 | | directory | Directory | The Directory to store the file in | 1.0.0 | | encoding | Encoding | The encoding to write the file in. If not provided, data is written as base64 encoded. Pass Encoding.UTF8 to write data as string | 1.0.0 |

DeleteFileOptions

| Prop | Type | Description | Since | | --------------- | ----------------------------------------------- | ---------------------------------------------------------------- | ----- | | path | string | The path of the file to delete | 1.0.0 | | directory | Directory | The Directory to delete the file from | 1.0.0 |

MkdirOptions

| Prop | Type | Description | Default | Since | | --------------- | ----------------------------------------------- | --------------------------------------------------------------------- | ------------------ | ----- | | path | string | The path of the new directory | | 1.0.0 | | directory | Directory | The Directory to make the new directory in | | 1.0.0 | | recursive | boolean | Whether to create any missing parent directories as well. | false | 1.0.0 |

RmdirOptions

| Prop | Type | Description | Default | Since | | --------------- | ----------------------------------------------- | --------------------------------------------------------------------- | ------------------ | ----- | | path | string | The path of the directory to remove | | 1.0.0 | | directory | Directory | The Directory to remove the directory from | | 1.0.0 | | recursive | boolean | Whether to recursively remove the contents of the directory | false | 1.0.0 |

ReaddirResult

| Prop | Type | Description | Since | | ----------- | --------------------- | -------------------------------------------------- | ----- | | files | string[] | List of files and directories inside the directory | 1.0.0 |

ReaddirOptions

| Prop | Type | Description | Since | | --------------- | ----------------------------------------------- | ----------------------------------------------------------- | ----- | | path | string | The path of the directory to read | 1.0.0 | | directory | Directory | The Directory to list files from | 1.0.0 |

GetUriResult

| Prop | Type | Description | Since | | --------- | ------------------- | ------------------- | ----- | | uri | string | The uri of the file | 1.0.0 |

GetUriOptions

| Prop | Type | Description | Since | | --------------- | ----------------------------------------------- | -------------------------------------------------------------- | ----- | | path | string | The path of the file to get the URI for | 1.0.0 | | directory | Directory | The Directory to get the file under | 1.0.0 |

StatResult

| Prop | Type | Description | Since | | ----------- | ------------------- | ------------------------------------------------------------------------------------ | ----- | | type | string | Type of the file | 1.0.0 | | size | number | Size of the file | 1.0.0 | | ctime | number | Time of creation in milliseconds. It's not available on Android 7 and older devices. | 1.0.0 | | mtime | number | Time of last modification in milliseconds. | 1.0.0 | | uri | string | The uri of the file | 1.0.0 |

StatOptions

| Prop | Type | Description | Since | | --------------- | ----------------------------------------------- | -------------------------------------------------------------- | ----- | | path | string | The path of the file to get data about | 1.0.0 | | directory | Directory | The Directory to get the file under | 1.0.0 |

CopyOptions

| Prop | Type | Description | Since | | ----------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | from | string | The existing file or directory | 1.0.0 | | to | string | The destination file or directory | 1.0.0 | | directory | Directory | The Directory containing the existing file or directory | 1.0.0 | | toDirectory | Directory | The Directory containing the destination file or directory. If not supplied will use the 'directory' parameter as the destination | 1.0.0 |

PermissionStatus

| Prop | Type | | ------------------- | ----------------------------------------------------------- | | publicStorage | PermissionState |

Type Aliases

RenameOptions

CopyOptions

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Enums

Directory

| Members | Value | Description | Since | | --------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | Documents | 'DOCUMENTS' | The Documents directory On iOS it's the app's documents directory. Use this directory to store user-generated content. On Android it's the Public Documents folder, so it's accessible from other apps. It's not accesible on Android 10 unless the app enables legacy External Storage by adding android:requestLegacyExternalStorage="true" in the application tag in the AndroidManifest.xml. It's not accesible on Android 11 or newer. | 1.0.0 | | Data | 'DATA' | The Data directory On iOS it will use the Documents directory On Android it's the directory holding application files. Files will be deleted when the application is uninstalled. | 1.0.0 | | Cache | 'CACHE' | The Cache directory Can be deleted in cases of low memory, so use this directory to write app-specific files that your app can re-create easily. | 1.0.0 | | External | 'EXTERNAL' | The external directory On iOS it will use the Documents directory On Android it's the directory on the primary shared/external storage device where the application can place persistent files it owns. These files are internal to the applications, and not typically visible to the user as media. Files will be deleted when the application is uninstalled. | 1.0.0 | | ExternalStorage | 'EXTERNAL_STORAGE' | The external storage directory On iOS it will use the Documents directory On Android it's the primary shared/external storage directory. It's not accesible on Android 10 unless the app enables legacy External Storage by adding android:requestLegacyExternalStorage="true" in the application tag in the AndroidManifest.xml. It's not accesible on Android 11 or newer. | 1.0.0 |

Encoding

| Members | Value | Description | Since | | ----------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----- | | UTF8 | 'utf8' | Eight-bit UCS Transformation Format | 1.0.0 | | ASCII | 'ascii' | Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set This encoding is only supported on Android. | 1.0.0 | | UTF16 | 'utf16' | Sixteen-bit UCS Transformation Format, byte order identified by an optional byte-order mark This encoding is only supported on Android. | 1.0.0 |