Skip to content

Latest commit

 

History

History
490 lines (375 loc) · 12.2 KB

README.md

File metadata and controls

490 lines (375 loc) · 12.2 KB

onefs

Cross-platform file system abstraction for web, Tauri, and Capacitor.

Features

  • File System Access API with handle persistence via IndexedDB
  • Fallback mode using file picker + IndexedDB storage
  • Tauri integration via @tauri-apps/plugin-dialog and @tauri-apps/plugin-fs
  • Capacitor integration via @capacitor/filesystem
  • Automatic platform detection with configurable overrides
  • Type-safe error handling with discriminated result types
  • Lazy directory loading - list entries without loading file contents
  • Automatic storage pruning - keeps recent files within configured limit

Installation

npm install onefs
# or
bun add onefs

Quick Start

import { createOneFS } from 'onefs'

const fs = createOneFS({ appName: 'myapp' })

// Open a file
const result = await fs.openFile({ accept: ['.json', '.txt'] })
if (result.ok) {
  const text = fs.readAsText(result.data)
  console.log(text)
} else {
  if (result.error.code === 'cancelled') {
    console.log('User cancelled')
  } else {
    console.error(result.error.message)
  }
}

// Save to the same file
const saveResult = await fs.saveFile(file, 'updated content')

// Save as new file
const newFile = await fs.saveFileAs('content', {
  suggestedName: 'document.txt'
})

Important: Platform Differences

OneFS abstracts platform differences, but some behaviors vary. Always check capabilities before assuming behavior.

Content is Always Uint8Array

File content is always returned as Uint8Array, never as a string. Use helper methods to convert:

const file = (await fs.openFile()).data

// Convert to string
const text = fs.readAsText(file)

// Parse as JSON
const json = fs.readAsJSON<MyType>(file)

// Get as Blob for images
const blob = fs.readAsBlob(file)

Save Behavior Varies by Platform

The saveFile() method behaves differently depending on the platform:

Platform Behavior
web-fs-access Saves in-place to original file location
tauri Saves in-place to original file location
web-fallback Triggers a download (cannot save in-place)
capacitor Saves to app's Data directory (not original location)

Check capabilities.canSaveInPlace to detect this:

if (fs.capabilities.canSaveInPlace) {
  // Will save to original location
  await fs.saveFile(file, newContent)
} else {
  // Will trigger download or save to app directory
  // Consider showing a different UI
  await fs.saveFile(file, newContent)
}

Path Property Varies

The file.path property has different meanings:

Platform file.path value
web-fs-access undefined (no path access in browser)
web-fallback undefined
tauri Real filesystem path (e.g., /home/user/doc.txt)
capacitor Synthetic identifier (e.g., onefs_123_doc.txt)

Directory Support

Directory operations are not available on all platforms:

Platform openDirectory readDirectory
web-fs-access Full support Full support
web-fallback Not supported Not supported
tauri Full support Full support
capacitor Documents only Documents only 
if (fs.supportsDirectories) {
  const dir = await fs.openDirectory()
  // ...
}

Directory Operations

Directories are loaded lazily to avoid memory issues with large folders:

// Open directory picker
const dirResult = await fs.openDirectory()
if (!dirResult.ok) return

// List entries (metadata only - no content loaded)
const entriesResult = await fs.readDirectory(dirResult.data)
if (!entriesResult.ok) return

for (const entry of entriesResult.data) {
  console.log(entry.name, entry.kind, entry.size)

  if (entry.kind === 'file') {
    // Load specific file content on demand
    const fileResult = await fs.readFileFromDirectory(dirResult.data, entry)
    if (fileResult.ok) {
      const content = fs.readAsText(fileResult.data)
    }
  }
}

OneFSEntry

Directory entries include metadata without content:

interface OneFSEntry {
  name: string              // "document.txt" or "subfolder"
  kind: 'file' | 'directory'
  size?: number             // File size in bytes (files only)
  lastModified?: number     // Timestamp (files only)
  path?: string             // Full path (Tauri/Capacitor only)
  handle?: FileSystemHandle // Native handle (web-fs-access only)
}

Error Handling

All async operations return OneFSResult<T>:

type OneFSResult<T> =
  | { ok: true; data: T }
  | { ok: false; error: OneFSError }

interface OneFSError {
  code: OneFSErrorCode
  message: string
  cause?: unknown  // Original error if available
}

type OneFSErrorCode =
  | 'cancelled'           // User cancelled operation
  | 'permission_denied'   // No permission to access file/directory
  | 'not_supported'       // Operation not supported on this platform
  | 'not_found'           // File/handle not found
  | 'io_error'            // Generic I/O error
  | 'unknown'             // Unknown error

Example:

const result = await fs.openFile()

if (!result.ok) {
  switch (result.error.code) {
    case 'cancelled':
      // User clicked cancel - not an error
      break
    case 'permission_denied':
      showPermissionDialog()
      break
    case 'not_supported':
      showFallbackUI()
      break
    default:
      console.error('Failed:', result.error.message)
  }
  return
}

const file = result.data

Configuration

const fs = createOneFS({
  appName: 'myapp',           // Required - used for IndexedDB database name
  maxRecentFiles: 10,         // Max files to remember (default: 10)
  persistByDefault: true,     // Store files/handles in IndexedDB (default: true)
  useNativeFSAccess: true,    // Use File System Access API when available (default: true)
  preferredAdapter: 'tauri',  // Force specific adapter (optional)
})

Per-Operation Options

// Don't persist this file to recent list
const file = await fs.openFile({ persist: false })

// Save without adding to recent
await fs.saveFileAs(content, { persist: false })

Platform Detection

console.log(fs.platform)
// 'web-fs-access' | 'web-fallback' | 'tauri' | 'capacitor'

console.log(fs.capabilities)
// {
//   openFile: true,
//   saveFile: true,
//   saveFileAs: true,
//   openDirectory: true,
//   readDirectory: true,
//   handlePersistence: true,
//   canSaveInPlace: true,
// }

console.log(fs.supportsDirectories)      // boolean
console.log(fs.supportsHandlePersistence) // boolean

Platform Capabilities Matrix

Capability web-fs-access web-fallback tauri capacitor
openFile Yes Yes Yes Yes
saveFile Yes Yes (download) Yes Yes (app dir)
saveFileAs Yes Yes (download) Yes Yes (app dir)
openDirectory Yes No Yes Limited
readDirectory Yes No Yes Limited
handlePersistence Yes No No No
canSaveInPlace Yes No Yes No

OneFSFile

interface OneFSFile {
  id: string              // Unique identifier
  name: string            // File name (e.g., "document.txt")
  path?: string           // Full path (Tauri/Capacitor only)
  content: Uint8Array     // File content as bytes
  mimeType: string        // MIME type (e.g., "text/plain")
  size: number            // File size in bytes
  lastModified: number    // Timestamp (ms since epoch)
  handle?: FileSystemFileHandle  // Native handle (web-fs-access only)
}

Helper Methods

fs.readAsText(file)       // string (UTF-8)
fs.readAsJSON(file)       // parsed JSON
fs.readAsDataURL(file)    // data:mime;base64,...
fs.readAsBlob(file)       // Blob
fs.readAsObjectURL(file)  // blob:... (remember to revoke!)

Recent Files

// Get recent files
const recent = await fs.getRecentFiles()
// Returns StoredHandle[] with { id, name, path?, type, storedAt }

// Restore a file
const file = await fs.restoreFile(recent[0])

// On web-fs-access: Re-reads from disk (may prompt for permission)
// On other platforms: Returns cached content from IndexedDB

// Restore a directory with specific permission mode
const dir = await fs.restoreDirectory(recent[0], 'readwrite')

// Remove from recent
await fs.removeFromRecent(id)

// Clear all
await fs.clearRecent()

Permission Management (web-fs-access only)

Check and request permissions on files and directories:

// Check current permission status
const status = await fs.queryPermission(directory, 'readwrite')
// Returns: 'granted' | 'denied' | 'prompt'

// Request permission (must be called during user gesture)
const result = await fs.requestPermission(directory, 'readwrite')
if (result.ok) {
  // Permission granted
}

// On non-web-fs-access platforms, these return 'granted' and ok(true)

Named Directory Storage (web-fs-access only)

Store directories by key, separate from the recent files list. Useful for app preferences like output directories:

// Open and store a directory by key
const dir = await fs.openDirectory({ mode: 'readwrite' })
if (dir.ok) {
  await fs.setNamedDirectory('outputDir', dir.data)
}

// Retrieve later (automatically requests permission)
const stored = await fs.getNamedDirectory('outputDir', 'readwrite')
if (stored.ok) {
  // Use stored.data.handle for file operations
}

// Remove
await fs.removeNamedDirectory('outputDir')

Exports

// Main factory
import { createOneFS, OneFS } from 'onefs'

// Types
import type {
  OneFSFile,
  OneFSDirectory,
  OneFSEntry,
  OneFSResult,
  OneFSError,
  OneFSErrorCode,
  OneFSCapabilities,
  Platform,
  StoredHandle,
} from 'onefs'

// Helpers
import { ok, err, PLATFORM_CAPABILITIES } from 'onefs'

// Individual adapters (for advanced use)
import {
  FSAccessAdapter,
  PickerIDBAdapter,
  TauriAdapter,
  CapacitorAdapter,
} from 'onefs'

Platform-Specific Setup

Tauri

Add the required plugins to your Cargo.toml:

[dependencies]
tauri-plugin-dialog = "2"
tauri-plugin-fs = "2"

And initialize them in your Tauri app:

fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_dialog::init())
        .plugin(tauri_plugin_fs::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Capacitor

Install the filesystem plugin:

npm install @capacitor/filesystem
npx cap sync

For iOS Files app integration (users can drop files into your app's folder):

Add to your ios/App/App/Info.plist:

<key>UIFileSharingEnabled</key>
<true/>
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>

This exposes your app's Documents folder in the iOS Files app. Users can drag files there, and your app can scan them with openDirectory() and scanDirectory().

Optional: Install @capawesome/capacitor-file-picker for native file picker (otherwise falls back to HTML input).

Scanning Directories

Recursively scan directories for files with optional filtering:

const dir = await fs.openDirectory()
if (!dir.ok) return

// Scan for specific file types
const result = await fs.scanDirectory(dir.data, {
  extensions: ['.mp3', '.flac', '.wav'],
  skipStats: true,  // Faster - don't fetch size/mtime
  onProgress: (scanned, found) => {
    console.log(`Scanned ${scanned} entries, found ${found} matches`)
  },
  signal: abortController.signal,  // Optional cancellation
})

if (result.ok) {
  for (const entry of result.data) {
    console.log(entry.name, entry.path)
  }
}

Streaming URLs (Tauri/Capacitor)

Get efficient URLs for media playback without loading files into memory:

// From a directory entry (recommended for media apps)
const url = await fs.getEntryUrl(entry)
if (url) {
  audioElement.src = url
}

// From a file object
const url = await fs.getFileUrl(file)

On Tauri/Capacitor, this uses convertFileSrc() for efficient native streaming. On web platforms, falls back to blob URLs.

Future Improvements

The following features are planned but not yet implemented:

  • Streaming support for large files (ReadableStream)
  • File watching for external changes (FileSystemObserver)

License

MIT