@jisan901/fs-browser 1.0.0

package/src/index.d.ts

@@ -0,0 +1,288 @@
+/**
+ * fs:browser - Browser-compatible filesystem API
+ * TypeScript Declaration File
+ */
+
+declare module 'fs:browser' {
+  /**
+   * Configuration options for fs-browser
+   */
+  export interface FsConfig {
+    apiBase?: string;
+  }
+
+  /**
+   * File encoding options
+   */
+  export type BufferEncoding =
+    | 'ascii'
+    | 'utf8'
+    | 'utf-8'
+    | 'utf16le'
+    | 'ucs2'
+    | 'ucs-2'
+    | 'base64'
+    | 'base64url'
+    | 'latin1'
+    | 'binary'
+    | 'hex';
+
+  /**
+   * Options for file operations
+   */
+  export interface FileOptions {
+    encoding?: BufferEncoding | null;
+    flag?: string;
+    mode?: number;
+  }
+
+  /**
+   * Options for directory operations
+   */
+  export interface MkdirOptions {
+    recursive?: boolean;
+    mode?: number;
+  }
+
+  /**
+   * Options for readdir
+   */
+  export interface ReaddirOptions {
+    encoding?: BufferEncoding | null;
+    withFileTypes?: boolean;
+  }
+
+  /**
+   * Options for rm/rmdir operations
+   */
+  export interface RmOptions {
+    recursive?: boolean;
+    force?: boolean;
+    maxRetries?: number;
+    retryDelay?: number;
+  }
+
+  /**
+   * Directory entry with type information
+   */
+  export interface Dirent {
+    name: string;
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+  }
+
+  /**
+   * File statistics
+   */
+  export interface Stats {
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    mode: number;
+    size: number;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    birthtimeMs: number;
+    atime: Date;
+    mtime: Date;
+    ctime: Date;
+    birthtime: Date;
+  }
+
+  /**
+   * Read file contents
+   * @param path - File path
+   * @param options - Encoding string or options object
+   * @returns File contents as string or Buffer
+   */
+  export function readFile(
+    path: string,
+    options?: BufferEncoding | FileOptions
+  ): Promise<string>;
+
+  /**
+   * Write data to file
+   * @param path - File path
+   * @param data - Data to write (string, Buffer, Blob, ArrayBuffer, TypedArray, or object)
+   * @param options - Encoding string or options object
+   */
+  export function writeFile(
+    path: string,
+    data: string | Buffer | Blob | ArrayBuffer | ArrayBufferView | object,
+    options?: BufferEncoding | FileOptions
+  ): Promise<void>;
+
+  /**
+   * Append data to file
+   * @param path - File path
+   * @param data - Data to append (string, Buffer, Blob, ArrayBuffer, TypedArray, or object)
+   * @param options - Encoding string or options object
+   */
+  export function appendFile(
+    path: string,
+    data: string | Buffer | Blob | ArrayBuffer | ArrayBufferView | object,
+    options?: BufferEncoding | FileOptions
+  ): Promise<void>;
+
+  /**
+   * Copy file
+   * @param src - Source path
+   * @param dest - Destination path
+   * @param flags - Copy flags (default: 0)
+   */
+  export function copyFile(
+    src: string,
+    dest: string,
+    flags?: number
+  ): Promise<void>;
+
+  /**
+   * Read directory contents
+   * @param path - Directory path
+   * @param options - Options object
+   * @returns Array of filenames or Dirent objects
+   */
+  export function readdir(
+    path: string,
+    options?: { withFileTypes?: false } & ReaddirOptions
+  ): Promise<string[]>;
+  export function readdir(
+    path: string,
+    options: { withFileTypes: true } & ReaddirOptions
+  ): Promise<Dirent[]>;
+  export function readdir(
+    path: string,
+    options?: ReaddirOptions
+  ): Promise<string[] | Dirent[]>;
+
+  /**
+   * Create directory
+   * @param path - Directory path
+   * @param options - Options object
+   */
+  export function mkdir(
+    path: string,
+    options?: MkdirOptions
+  ): Promise<void>;
+
+  /**
+   * Remove directory
+   * @param path - Directory path
+   * @param options - Options object
+   */
+  export function rmdir(
+    path: string,
+    options?: RmOptions
+  ): Promise<void>;
+
+  /**
+   * Remove file or directory
+   * @param path - Path to remove
+   * @param options - Options object
+   */
+  export function rm(
+    path: string,
+    options?: RmOptions
+  ): Promise<void>;
+
+  /**
+   * Rename or move file/directory
+   * @param oldPath - Old path
+   * @param newPath - New path
+   */
+  export function rename(
+    oldPath: string,
+    newPath: string
+  ): Promise<void>;
+
+  /**
+   * Delete file
+   * @param path - File path
+   */
+  export function unlink(path: string): Promise<void>;
+
+  /**
+   * Get file/directory stats
+   * @param path - Path
+   * @returns File statistics
+   */
+  export function stat(path: string): Promise<Stats>;
+
+  /**
+   * Get file/directory stats (doesn't follow symlinks)
+   * @param path - Path
+   * @returns File statistics
+   */
+  export function lstat(path: string): Promise<Stats>;
+
+  /**
+   * Get canonical path
+   * @param path - Path
+   * @returns Resolved path
+   */
+  export function realpath(path: string): Promise<string>;
+
+  /**
+   * Read symbolic link
+   * @param path - Link path
+   * @returns Link target path
+   */
+  export function readlink(path: string): Promise<string>;
+
+  /**
+   * Check if file exists (convenience method)
+   * @param path - Path
+   * @returns true if exists, false otherwise
+   */
+  export function exists(path: string): Promise<boolean>;
+
+  /**
+   * Configure the fs-browser module
+   * @param options - Configuration options
+   * @returns Configured fs module with all methods
+   */
+  export function configure(options: FsConfig): {
+    readFile: typeof readFile;
+    writeFile: typeof writeFile;
+    appendFile: typeof appendFile;
+    copyFile: typeof copyFile;
+    readdir: typeof readdir;
+    mkdir: typeof mkdir;
+    rmdir: typeof rmdir;
+    rm: typeof rm;
+    rename: typeof rename;
+    unlink: typeof unlink;
+    stat: typeof stat;
+    lstat: typeof lstat;
+    realpath: typeof realpath;
+    readlink: typeof readlink;
+    exists: typeof exists;
+    configure: typeof configure;
+  };
+
+  /**
+   * Default export with all methods
+   */
+  const fs: {
+    readFile: typeof readFile;
+    writeFile: typeof writeFile;
+    appendFile: typeof appendFile;
+    copyFile: typeof copyFile;
+    readdir: typeof readdir;
+    mkdir: typeof mkdir;
+    rmdir: typeof rmdir;
+    rm: typeof rm;
+    rename: typeof rename;
+    unlink: typeof unlink;
+    stat: typeof stat;
+    lstat: typeof lstat;
+    realpath: typeof realpath;
+    readlink: typeof readlink;
+    exists: typeof exists;
+    configure: typeof configure;
+  };
+
+  export default fs;
+}

package/src/index.js

@@ -0,0 +1,402 @@
+/**
+ * fs:browser - Browser-compatible filesystem API
+ * Uses fetch to communicate with backend fs API
+ */
+
+let API_BASE = '/api/fs';
+
+/**
+ * Configure the fs-browser module
+ * @param {Object} options - Configuration options
+ * @param {string} options.apiBase - Base URL for the fs API
+ * @returns {Object} - Configured fs module
+ */
+export function configure(options = {}) {
+  if (options.apiBase !== undefined) {
+    API_BASE = options.apiBase;
+    // Ensure no trailing slash
+    if (API_BASE.endsWith('/')) {
+      API_BASE = API_BASE.slice(0, -1);
+    }
+  }
+  
+  return {
+    readFile,
+    writeFile,
+    appendFile,
+    copyFile,
+    readdir,
+    mkdir,
+    rmdir,
+    rm,
+    rename,
+    unlink,
+    stat,
+    lstat,
+    realpath,
+    readlink,
+    exists,
+    configure
+  };
+}
+
+/**
+ * Read file contents
+ * @param {string} path - File path
+ * @param {string|Object} options - Encoding string or options object
+ * @returns {Promise<string|Buffer>}
+ */
+export async function readFile(path, options = 'utf8') {
+  const encoding = typeof options === 'string' ? options : options?.encoding || 'utf8';
+  const response = await fetch(`${API_BASE}/readFile?path=${encodeURIComponent(path)}&encoding=${encoding}`);
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to read file');
+  }
+  
+  const { data } = await response.json();
+  return data;
+}
+
+/**
+ * Write data to file
+ * @param {string} path - File path
+ * @param {string|Buffer|Blob} data - Data to write
+ * @param {string|Object} options - Encoding string or options object
+ * @returns {Promise<void>}
+ */
+export async function writeFile(path, data, options = 'utf8') {
+  const encoding = typeof options === 'string' ? options : options?.encoding || 'utf8';
+  
+  let body;
+  let contentType;
+  
+  // Handle Blob
+  if (data instanceof Blob) {
+    body = data;
+    contentType = data.type || 'application/octet-stream';
+  }
+  // Handle ArrayBuffer
+  else if (data instanceof ArrayBuffer) {
+    body = new Blob([data], { type: 'application/octet-stream' });
+    contentType = 'application/octet-stream';
+  }
+  // Handle Uint8Array or other TypedArray
+  else if (ArrayBuffer.isView(data)) {
+    body = new Blob([data], { type: 'application/octet-stream' });
+    contentType = 'application/octet-stream';
+  }
+  // Handle string
+  else if (typeof data === 'string') {
+    body = new Blob([data], { type: 'text/plain' });
+    contentType = 'text/plain';
+  }
+  // Handle object (convert to JSON)
+  else if (typeof data === 'object') {
+    body = JSON.stringify(data);
+    contentType = 'application/json';
+  }
+  else {
+    throw new Error('Unsupported data type');
+  }
+  
+  const response = await fetch(`${API_BASE}/writeFile?path=${encodeURIComponent(path)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': contentType },
+    body
+  });
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to write file');
+  }
+}
+
+/**
+ * Append data to file
+ * @param {string} path - File path
+ * @param {string|Buffer|Blob} data - Data to append
+ * @param {string|Object} options - Encoding string or options object
+ * @returns {Promise<void>}
+ */
+export async function appendFile(path, data, options = 'utf8') {
+  const encoding = typeof options === 'string' ? options : options?.encoding || 'utf8';
+  
+  let body;
+  let contentType;
+  
+  if (data instanceof Blob) {
+    body = data;
+    contentType = data.type || 'application/octet-stream';
+  }
+  else if (data instanceof ArrayBuffer) {
+    body = new Blob([data], { type: 'application/octet-stream' });
+    contentType = 'application/octet-stream';
+  }
+  else if (ArrayBuffer.isView(data)) {
+    body = new Blob([data], { type: 'application/octet-stream' });
+    contentType = 'application/octet-stream';
+  }
+  else if (typeof data === 'string') {
+    body = new Blob([data], { type: 'text/plain' });
+    contentType = 'text/plain';
+  }
+  else if (typeof data === 'object') {
+    body = JSON.stringify(data);
+    contentType = 'application/json';
+  }
+  else {
+    throw new Error('Unsupported data type');
+  }
+  
+  const response = await fetch(`${API_BASE}/appendFile?path=${encodeURIComponent(path)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': contentType },
+    body
+  });
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to append file');
+  }
+}
+
+/**
+ * Copy file
+ * @param {string} src - Source path
+ * @param {string} dest - Destination path
+ * @param {number} flags - Copy flags
+ * @returns {Promise<void>}
+ */
+export async function copyFile(src, dest, flags = 0) {
+  const response = await fetch(`${API_BASE}/copyFile`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ src, dest, flags })
+  });
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to copy file');
+  }
+}
+
+/**
+ * Read directory contents
+ * @param {string} path - Directory path
+ * @param {Object} options - Options
+ * @returns {Promise<string[]|Dirent[]>}
+ */
+export async function readdir(path, options = {}) {
+  const withFileTypes = options.withFileTypes || false;
+  const response = await fetch(`${API_BASE}/readdir?path=${encodeURIComponent(path)}&withFileTypes=${withFileTypes}`);
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to read directory');
+  }
+  
+  const { files } = await response.json();
+  return files;
+}
+
+/**
+ * Create directory
+ * @param {string} path - Directory path
+ * @param {Object} options - Options
+ * @returns {Promise<void>}
+ */
+export async function mkdir(path, options = {}) {
+  const recursive = options.recursive !== undefined ? options.recursive : true;
+  const response = await fetch(`${API_BASE}/mkdir`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path, recursive })
+  });
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to create directory');
+  }
+}
+
+/**
+ * Remove directory
+ * @param {string} path - Directory path
+ * @param {Object} options - Options
+ * @returns {Promise<void>}
+ */
+export async function rmdir(path, options = {}) {
+  const recursive = options.recursive || false;
+  const response = await fetch(`${API_BASE}/rmdir`, {
+    method: 'DELETE',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path, recursive })
+  });
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to remove directory');
+  }
+}
+
+/**
+ * Remove file or directory
+ * @param {string} path - Path to remove
+ * @param {Object} options - Options
+ * @returns {Promise<void>}
+ */
+export async function rm(path, options = {}) {
+  const recursive = options.recursive || false;
+  const force = options.force || false;
+  const response = await fetch(`${API_BASE}/rm`, {
+    method: 'DELETE',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path, recursive, force })
+  });
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to remove');
+  }
+}
+
+/**
+ * Rename or move file/directory
+ * @param {string} oldPath - Old path
+ * @param {string} newPath - New path
+ * @returns {Promise<void>}
+ */
+export async function rename(oldPath, newPath) {
+  const response = await fetch(`${API_BASE}/rename`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ oldPath, newPath })
+  });
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to rename');
+  }
+}
+
+/**
+ * Delete file
+ * @param {string} path - File path
+ * @returns {Promise<void>}
+ */
+export async function unlink(path) {
+  const response = await fetch(`${API_BASE}/unlink`, {
+    method: 'DELETE',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path })
+  });
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to delete file');
+  }
+}
+
+/**
+ * Get file/directory stats
+ * @param {string} path - Path
+ * @returns {Promise<Stats>}
+ */
+export async function stat(path) {
+  const response = await fetch(`${API_BASE}/stat?path=${encodeURIComponent(path)}`);
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to get stats');
+  }
+  
+  const { stats } = await response.json();
+  return stats;
+}
+
+/**
+ * Get file/directory stats (doesn't follow symlinks)
+ * @param {string} path - Path
+ * @returns {Promise<Stats>}
+ */
+export async function lstat(path) {
+  const response = await fetch(`${API_BASE}/lstat?path=${encodeURIComponent(path)}`);
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to get stats');
+  }
+  
+  const { stats } = await response.json();
+  return stats;
+}
+
+/**
+ * Get canonical path
+ * @param {string} path - Path
+ * @returns {Promise<string>}
+ */
+export async function realpath(path) {
+  const response = await fetch(`${API_BASE}/realpath?path=${encodeURIComponent(path)}`);
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to get real path');
+  }
+  
+  const { realPath } = await response.json();
+  return realPath;
+}
+
+/**
+ * Read symbolic link
+ * @param {string} path - Link path
+ * @returns {Promise<string>}
+ */
+export async function readlink(path) {
+  const response = await fetch(`${API_BASE}/readlink?path=${encodeURIComponent(path)}`);
+  
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.error?.message || 'Failed to read link');
+  }
+  
+  const { target } = await response.json();
+  return target;
+}
+
+/**
+ * Check if file exists (convenience method)
+ * @param {string} path - Path
+ * @returns {Promise<boolean>}
+ */
+export async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Default export with all methods
+export default {
+  readFile,
+  writeFile,
+  appendFile,
+  copyFile,
+  readdir,
+  mkdir,
+  rmdir,
+  rm,
+  rename,
+  unlink,
+  stat,
+  lstat,
+  realpath,
+  readlink,
+  exists,
+  configure
+};