useFileSystemAccess

Hook for reading and writing local files via the File System Access API

browser

low

test coverage

Last changed: 1 hour ago

TIP

This hook uses File browser api to provide enhanced functionality. Make sure to check for compatibility with different browsers when using this api

Installation

Library

CLI

Manual

import { useFileSystemAccess } from '@siberiacancode/reactuse';

Usage

const fileSystemAccess = useFileSystemAccess({ dataType: 'Text' });

Demo

source

Api

Returns

UseFileSystemAccessReturn<string | ArrayBuffer | Blob>

Parameters

Name	Type	Default	Note
options?	UseFileSystemAccessOptions	-

Returns

UseFileSystemAccessReturn

Type declaration

export interface FileSystemAccessShowOpenFileOptions {
  excludeAcceptAllOption?: boolean;
  multiple?: boolean;
  types?: Array<{
    description?: string;
    accept: Record<string, string[]>;
  }>;
}

export interface FileSystemAccessShowSaveFileOptions {
  excludeAcceptAllOption?: boolean;
  suggestedName?: string;
  types?: Array<{
    description?: string;
    accept: Record<string, string[]>;
  }>;
}

export interface FileSystemFileHandle {
  createWritable: () => Promise<FileSystemWritableFileStream>;
  getFile: () => Promise<File>;
}

export interface FileSystemWritableFileStream extends WritableStream {
  write: FileSystemWritableFileStreamWrite;
  seek: (position: number) => Promise<void>;
  truncate: (size: number) => Promise<void>;
}

export interface FileSystemWritableFileStreamWrite {
  (data: string | Blob | BufferSource): Promise<void>;
  (options: { type: 'write'; position: number; data: string | Blob | BufferSource }): Promise<void>;
  (options: { type: 'seek'; position: number }): Promise<void>;
  (options: { type: 'truncate'; size: number }): Promise<void>;
}

interface Window {
    readonly showOpenFilePicker: (
      options?: FileSystemAccessShowOpenFileOptions
    ) => Promise<FileSystemFileHandle[]>;
    readonly showSaveFilePicker: (
      options?: FileSystemAccessShowSaveFileOptions
    ) => Promise<FileSystemFileHandle>;
  }

export type UseFileSystemAccessCommonOptions = Pick<
  FileSystemAccessShowOpenFileOptions,
  'excludeAcceptAllOption' | 'types'
>;

export type UseFileSystemAccessShowSaveOptions = Pick<
  FileSystemAccessShowSaveFileOptions,
  'suggestedName'
>;

export type UseFileSystemAccessOptions = UseFileSystemAccessCommonOptions & {
  dataType?: 'ArrayBuffer' | 'Blob' | 'Text';
};

export interface UseFileSystemAccessReturn<Data = string | ArrayBuffer | Blob> {
  /** Last read data */
  data?: Data;
  /** Current file */
  file?: File;
  /** Last modified timestamp */
  lastModified: number;
  /** File base name */
  name: string;
  /** Size in bytes */
  size: number;
  /** Whether the File System Access API is available */
  supported: boolean;
  /** MIME type */
  type: string;
  /** Create a new file via save picker */
  create: (createOptions?: UseFileSystemAccessShowSaveOptions) => Promise<void>;
  /** Open an existing file */
  open: (openOptions?: UseFileSystemAccessCommonOptions) => Promise<void>;
  /** Save to the current handle, or prompt with {@link saveAs} if none */
  save: (saveOptions?: UseFileSystemAccessShowSaveOptions) => Promise<void>;
  /** Always prompt for a file path then save */
  saveAs: (saveOptions?: UseFileSystemAccessShowSaveOptions) => Promise<void>;
  /** Set the data */
  set: (data: Data) => void;
  /** Re-read data from the current handle using `dataType` */
  update: () => Promise<void>;
}

export interface UseFileSystemAccess {
  (): UseFileSystemAccessReturn<string | ArrayBuffer | Blob>;
  (
    options: UseFileSystemAccessOptions & { dataType: 'ArrayBuffer' }
  ): UseFileSystemAccessReturn<ArrayBuffer>;
  (options: UseFileSystemAccessOptions & { dataType: 'Blob' }): UseFileSystemAccessReturn<Blob>;
  (options: UseFileSystemAccessOptions & { dataType: 'Text' }): UseFileSystemAccessReturn<string>;
  (options?: UseFileSystemAccessOptions): UseFileSystemAccessReturn<string | ArrayBuffer | Blob>;
}

Source

Source • Demo

Contributors

D

debabin