@molecule/app-filesystem

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Device filesystem access interface for molecule.dev.

Framework-agnostic core for app-scoped file storage through a swappable FilesystemProvider: read/write/append (text or Blob), directories (mkdir/rmdir/readdir), stat/exists, copy/move, URIs for native viewers, and free-space checks — all addressed relative to well-known base directories ('documents' | 'data' | 'cache' | 'external' | 'library' | 'temp'). Pure path/format helpers (joinPath, getExtension, getBasename, getDirname, getMimeType, formatFileSize) work without a provider.

Quick Start

import { exists, hasProvider, joinPath, readFile, writeFile } from '@molecule/app-filesystem'

async function saveDraft(text: string): Promise<void> {
  if (!hasProvider()) return // no provider wired — use app-storage instead
  const path = joinPath('drafts', 'note.txt')
  await writeFile(path, text, { directory: 'data', recursive: true })
}

async function loadDraft(): Promise<string | null> {
  const path = joinPath('drafts', 'note.txt')
  if (!(await exists(path, { directory: 'data' }))) return null
  return readFile(path, { directory: 'data' })
}

Type

native

Installation

npm install @molecule/app-filesystem @molecule/app-bond @molecule/app-i18n

API

Interfaces

CopyOptions

Copy/move options

interface CopyOptions {
  /** Source directory */
  fromDirectory?: Directory
  /** Destination directory */
  toDirectory?: Directory
  /** Overwrite existing file */
  overwrite?: boolean
}

DeleteOptions

Options for deleting a file or directory (directory type, recursive deletion).

interface DeleteOptions {
  /** Directory type */
  directory?: Directory
  /** Delete directory contents recursively */
  recursive?: boolean
}

FileInfo

Metadata about a file or directory (name, path, size, timestamps, type).

interface FileInfo {
  /** File name */
  name: string
  /** Full path */
  path: string
  /** File URI */
  uri: string
  /** File size in bytes */
  size: number
  /** Creation time (ISO string) */
  createdAt?: string
  /** Modification time (ISO string) */
  modifiedAt?: string
  /** Whether this is a directory */
  isDirectory: boolean
  /** Whether this is a file */
  isFile: boolean
  /** MIME type (if available) */
  mimeType?: string
}

FilesystemCapabilities

Filesystem capabilities

interface FilesystemCapabilities {
  /** Whether filesystem access is supported */
  supported: boolean
  /** Available directories */
  directories: Directory[]
  /** Whether external storage is available */
  hasExternalStorage: boolean
  /** Whether file picking is supported */
  hasPicker: boolean
  /** Maximum file size (if limited) */
  maxFileSize?: number
}

FilesystemProvider

Filesystem provider interface

interface FilesystemProvider {
  /**
   * Read a file as text
   * @param path - File path
   * @param options - Read options
   */
  readFile(path: string, options?: ReadOptions): Promise<string>

  /**
   * Read a file as binary data
   * @param path - File path
   * @param options - Read options
   */
  readFileAsBlob(path: string, options?: Omit<ReadOptions, 'encoding'>): Promise<Blob>

  /**
   * Write text to a file
   * @param path - File path
   * @param data - Content to write
   * @param options - Write options
   */
  writeFile(path: string, data: string, options?: WriteOptions): Promise<void>

  /**
   * Write binary data to a file
   * @param path - File path
   * @param data - Binary data to write
   * @param options - Write options
   */
  writeFileFromBlob(
    path: string,
    data: Blob,
    options?: Omit<WriteOptions, 'encoding'>,
  ): Promise<void>

  /**
   * Append text to a file
   * @param path - File path
   * @param data - Content to append
   * @param options - Write options
   */
  appendFile(path: string, data: string, options?: WriteOptions): Promise<void>

  /**
   * Delete a file
   * @param path - File path
   * @param options - Delete options
   */
  deleteFile(path: string, options?: DeleteOptions): Promise<void>

  /**
   * Create a directory
   * @param path - Directory path
   * @param options - Options
   */
  mkdir(path: string, options?: WriteOptions): Promise<void>

  /**
   * Remove a directory
   * @param path - Directory path
   * @param options - Delete options
   */
  rmdir(path: string, options?: DeleteOptions): Promise<void>

  /**
   * List directory contents
   * @param path - Directory path
   * @param options - List options
   */
  readdir(path: string, options?: ListOptions): Promise<FileInfo[]>

  /**
   * Get file/directory info
   * @param path - Path
   * @param options - Stat options
   */
  stat(path: string, options?: StatOptions): Promise<FileInfo>

  /**
   * Check if file/directory exists
   * @param path - Path
   * @param options - Options
   */
  exists(path: string, options?: StatOptions): Promise<boolean>

  /**
   * Copy a file
   * @param from - Source path
   * @param to - Destination path
   * @param options - Copy options
   */
  copy(from: string, to: string, options?: CopyOptions): Promise<void>

  /**
   * Move/rename a file
   * @param from - Source path
   * @param to - Destination path
   * @param options - Copy options
   */
  move(from: string, to: string, options?: CopyOptions): Promise<void>

  /**
   * Get the platform URI for a file path.
   * @param path - The file path to resolve.
   * @param options - Options including directory type.
   * @returns The file's platform-specific URI string.
   */
  getUri(path: string, options?: StatOptions): Promise<string>

  /**
   * Get available storage space in bytes.
   * @param directory - The directory type to check (defaults to app data).
   * @returns The available space in bytes.
   */
  getAvailableSpace(directory?: Directory): Promise<number>

  /**
   * Get the platform's filesystem capabilities.
   * @returns The capabilities indicating available directories, picker support, and size limits.
   */
  getCapabilities(): Promise<FilesystemCapabilities>
}

ListOptions

Options for listing directory contents (directory type, hidden files).

interface ListOptions {
  /** Directory type */
  directory?: Directory
  /** Whether to include hidden files */
  includeHidden?: boolean
}

ReadOptions

Options for reading a file (target directory and text encoding).

interface ReadOptions {
  /** Directory to read from */
  directory?: Directory
  /** File encoding */
  encoding?: Encoding
}

StatOptions

Options for getting file/directory metadata (target directory type).

interface StatOptions {
  /** Directory type */
  directory?: Directory
}

WriteOptions

Options for writing a file (directory, encoding, recursive creation, append mode).

interface WriteOptions {
  /** Directory to write to */
  directory?: Directory
  /** File encoding */
  encoding?: Encoding
  /** Whether to create parent directories */
  recursive?: boolean
  /** Whether to append to existing file */
  append?: boolean
}

Types

Directory

File system directory type

type Directory =
  | 'documents' // User documents
  | 'data' // App-specific data
  | 'cache' // Temporary cache
  | 'external' // External storage (Android)
  | 'library' // Library (iOS)
  | 'temp'

Encoding

Text encoding for file read/write operations.

type Encoding = 'utf8' | 'ascii' | 'base64'

Functions

appendFile(path, data, options)

Append text content to a file.

function appendFile(path: string, data: string, options?: WriteOptions): Promise<void>

• path — The file path to append to.
• data — The text content to append.
• options — Write options (directory, encoding).

Returns: A promise that resolves when the data is appended.

copy(from, to, options)

Copy a file to a new location.

function copy(from: string, to: string, options?: CopyOptions): Promise<void>

• from — The source file path.
• to — The destination file path.
• options — Copy options (source/dest directories, overwrite).

Returns: A promise that resolves when the file is copied.

deleteFile(path, options)

Delete a file.

function deleteFile(path: string, options?: DeleteOptions): Promise<void>

• path — The file path to delete.
• options — Delete options (directory, recursive).

Returns: A promise that resolves when the file is deleted.

exists(path, options)

Check if a file or directory exists.

function exists(path: string, options?: StatOptions): Promise<boolean>

• path — The path to check.
• options — Stat options (directory).

Returns: Whether the path exists.

formatFileSize(bytes)

Format a byte count as a human-readable file size string (e.g., '1.5 MB').

function formatFileSize(bytes: number): string

• bytes — The size in bytes.

Returns: A formatted string with the appropriate unit (B, KB, MB, GB, TB).

getAvailableSpace(directory)

Get available storage space in bytes for a directory.

function getAvailableSpace(directory?: Directory): Promise<number>

• directory — The directory type to check (defaults to app data).

Returns: The available space in bytes.

getBasename(path)

Get the filename without its extension from a path.

function getBasename(path: string): string

• path — The file path.

Returns: The base filename without extension (e.g., 'readme' from '/docs/readme.md').

getCapabilities()

Get the platform's filesystem capabilities.

function getCapabilities(): Promise<FilesystemCapabilities>

Returns: The capabilities indicating available directories, picker support, and size limits.

getDirname(path)

Get the directory portion of a file path.

function getDirname(path: string): string

• path — The file path.

Returns: The parent directory path (e.g., '/docs' from '/docs/readme.md').

getExtension(path)

Extract the file extension from a path, without the leading dot.

function getExtension(path: string): string

• path — The file path or filename.

Returns: The lowercase extension (e.g., 'txt'), or empty string if none.

getMimeType(path)

Infer a MIME type from a file extension. Supports common image, document, text, media, and archive formats. Falls back to 'application/octet-stream'.

function getMimeType(path: string): string

• path — The file path or extension to look up.

Returns: The inferred MIME type string.

getProvider()

Get the current filesystem provider.

function getProvider(): FilesystemProvider

Returns: The active FilesystemProvider instance.

getUri(path, options)

Get the platform-specific URI for a file path.

function getUri(path: string, options?: StatOptions): Promise<string>

• path — The file path to resolve.
• options — Stat options (directory).

Returns: The file's platform URI string.

hasProvider()

Check if a filesystem provider has been registered.

function hasProvider(): boolean

Returns: Whether a FilesystemProvider has been bonded.

joinPath(segments)

Join multiple path segments into a single normalized path. Collapses duplicate slashes and removes trailing slashes.

function joinPath(segments?: string[]): string

• segments — The path segments to join.

Returns: The joined and normalized path.

mkdir(path, options)

Create a directory.

function mkdir(path: string, options?: WriteOptions): Promise<void>

• path — The directory path to create.
• options — Write options (directory, recursive for parent directories).

Returns: A promise that resolves when the directory is created.

move(from, to, options)

Move or rename a file.

function move(from: string, to: string, options?: CopyOptions): Promise<void>

• from — The source file path.
• to — The destination file path.
• options — Move options (source/dest directories, overwrite).

Returns: A promise that resolves when the file is moved.

readdir(path, options)

List directory contents.

function readdir(path: string, options?: ListOptions): Promise<FileInfo[]>

• path — The directory path to list.
• options — List options (directory, include hidden files).

Returns: An array of FileInfo objects for each entry.

readFile(path, options)

Read a file as text.

function readFile(path: string, options?: ReadOptions): Promise<string>

• path — The file path to read.
• options — Read options (directory, encoding).

Returns: The file contents as a string.

readFileAsBlob(path, options)

Read a file as binary data.

function readFileAsBlob(path: string, options?: Omit<ReadOptions, 'encoding'>): Promise<Blob>

• path — The file path to read.
• options — Read options (directory).

Returns: The file contents as a Blob.

rmdir(path, options)

Remove a directory.

function rmdir(path: string, options?: DeleteOptions): Promise<void>

• path — The directory path to remove.
• options — Delete options (directory, recursive for contents).

Returns: A promise that resolves when the directory is removed.

setProvider(provider)

Set the filesystem provider.

function setProvider(provider: FilesystemProvider): void

• provider — FilesystemProvider implementation to register.

stat(path, options)

Get file or directory metadata.

function stat(path: string, options?: StatOptions): Promise<FileInfo>

• path — The path to stat.
• options — Stat options (directory).

Returns: The FileInfo with size, dates, and type information.

writeFile(path, data, options)

Write text content to a file.

function writeFile(path: string, data: string, options?: WriteOptions): Promise<void>

• path — The file path to write to.
• data — The text content to write.
• options — Write options (directory, encoding, recursive, append).

Returns: A promise that resolves when the file is written.

writeFileFromBlob(path, data, options)

Write binary data to a file.

function writeFileFromBlob(
  path: string,
  data: Blob,
  options?: Omit<WriteOptions, 'encoding'>,
): Promise<void>

• path — The file path to write to.
• data — The binary data to write as a Blob.
• options — Write options (directory, recursive).

Returns: A promise that resolves when the file is written.

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-bond ^1.0.1
• @molecule/app-i18n ^1.0.1

Runtime Dependencies

• @molecule/app-bond

• @molecule/app-i18n

• Every file operation THROWS until setProvider() is called — there is no web fallback and no prebuilt provider package ships with molecule; supply a FilesystemProvider from your native runtime.

• This is NOT general key-value persistence. For settings/state on any platform use @molecule/app-storage; reach for app-filesystem only when you genuinely need files (large blobs, exports, media handed to other apps via getUri).

• On web there is no path-addressed filesystem; a provider could be built on OPFS (origin-private, invisible to the user's file manager), but 'external'/'library' semantics and getUri for OS viewers do not translate — feature-gate on getCapabilities().

• Paths are RELATIVE to the directory base option (default varies by provider — pass it explicitly). Use joinPath, never string-concat with /.

• Write ops fail on missing parent directories unless { recursive: true }.

Translations

Translation strings are provided by @molecule/app-locales-filesystem.