@fivexlabs/use-file-system/dist/index.d.ts

A comprehensive React hook for the File System Access API with TypeScript support

// File System Access API Type Definitions
interface FilePickerAcceptType {
  description?: string;
  accept: Record<string, string | string[]>;
}

interface OpenFilePickerOptions {
  multiple?: boolean;
  excludeAcceptAllOption?: boolean;
  types?: FilePickerAcceptType[];
}

interface SaveFilePickerOptions {
  suggestedName?: string;
  excludeAcceptAllOption?: boolean;
  types?: FilePickerAcceptType[];
}

interface DirectoryPickerOptions {
  mode?: 'read' | 'readwrite';
}

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

type FileSystemWriteChunkType = BufferSource | Blob | string | WriteParams;

interface WriteParams {
  type: 'write' | 'seek' | 'truncate';
  data?: BufferSource | Blob | string;
  position?: number;
  size?: number;
}

interface FileSystemFileHandle {
  readonly kind: 'file';
  readonly name: string;
  getFile(): Promise<File>;
  createWritable(options?: FileSystemCreateWritableOptions): Promise<FileSystemWritableFileStream>;
  isSameEntry(other: FileSystemHandle): Promise<boolean>;
}

interface FileSystemDirectoryHandle {
  readonly kind: 'directory';
  readonly name: string;
  getFileHandle(name: string, options?: FileSystemGetFileOptions): Promise<FileSystemFileHandle>;
  getDirectoryHandle(name: string, options?: FileSystemGetDirectoryOptions): Promise<FileSystemDirectoryHandle>;
  removeEntry(name: string, options?: FileSystemRemoveOptions): Promise<void>;
  resolve(possibleDescendant: FileSystemHandle): Promise<string[] | null>;
  entries(): AsyncIterableIterator<[string, FileSystemHandle]>;
  keys(): AsyncIterableIterator<string>;
  values(): AsyncIterableIterator<FileSystemHandle>;
  isSameEntry(other: FileSystemHandle): Promise<boolean>;
}

type FileSystemHandle = FileSystemFileHandle | FileSystemDirectoryHandle;

interface FileSystemCreateWritableOptions {
  keepExistingData?: boolean;
}

interface FileSystemGetFileOptions {
  create?: boolean;
}

interface FileSystemGetDirectoryOptions {
  create?: boolean;
}

interface FileSystemRemoveOptions {
  recursive?: boolean;
}

// useFileSystem Hook Types
export type FileContent = string | ArrayBuffer | null;

export interface FileDetails {
  name: string;
  content: FileContent;
  handle: FileSystemFileHandle | null;
  size: number;
  type: string;
  lastModified: number;
}

export interface DirectoryDetails {
  name: string;
  handle: FileSystemDirectoryHandle | null;
}

export interface FileSystemState {
  isSupported: boolean;
  file: FileDetails | null;
  files: FileDetails[];
  directory: DirectoryDetails | null;
  loading: boolean;
  error: Error | null;
}

export interface UseFileSystemReturn extends FileSystemState {
  openFile: (options?: OpenFilePickerOptions) => Promise<void>;
  openMultipleFiles: (options?: OpenFilePickerOptions) => Promise<void>;
  saveFile: (
    suggestedName: string,
    data: BlobPart[],
    options?: SaveFilePickerOptions
  ) => Promise<void>;
  saveAs: (
    content: string | ArrayBuffer,
    suggestedName?: string,
    options?: SaveFilePickerOptions
  ) => Promise<void>;
  openDirectory: (options?: DirectoryPickerOptions) => Promise<void>;
  readFileContent: (file: File, readAs?: 'text' | 'buffer') => Promise<string | ArrayBuffer>;
  clearFile: () => void;
  clearFiles: () => void;
  clearDirectory: () => void;
  clearError: () => void;
}

// Hook Declaration and Export
declare const useFileSystem: () => UseFileSystemReturn;
export { useFileSystem };
export default useFileSystem;