File Writing

/**
 * Write string or buffer to file
 * @param filepath - Target file path
 * @param contents - File contents as string or Buffer
 * @param stat - Optional file stat information for permissions
 * @returns Contents as string
 */
function write(filepath: string, contents: string | Buffer, stat?: FileStats): string;

/**
 * Internal write function for writing file objects directly
 * @param file - File object to write to the store
 */
function _write<EditorFile extends MemFsEditorFile>(file: EditorFile): void;

interface FileStats {
  /** File mode/permissions (e.g., 0o755 for executable) */
  mode?: number;
}

import { create as createMemFs } from "mem-fs";
import { create as createEditor } from "mem-fs-editor";

const store = createMemFs();
const fs = createEditor(store);

// Write string content
fs.write("hello.txt", "Hello, World!");

// Write buffer content
const buffer = Buffer.from("Binary data", "utf8");
fs.write("data.bin", buffer);

// Write with file permissions
fs.write("script.sh", "#!/bin/bash\necho 'Hello'", { mode: 0o755 });

// Write complex content
const jsContent = `
const greeting = "Hello, World!";
console.log(greeting);
`;
fs.write("greeting.js", jsContent);

/**
 * Write object as JSON to file
 * @param filepath - Target file path
 * @param contents - Object to serialize as JSON
 * @param replacer - JSON.stringify replacer function or array of keys
 * @param space - Formatting spaces (default: 2)
 * @returns JSON string that was written
 */
function writeJSON(
  filepath: string, 
  contents: any, 
  replacer?: JSONReplacer, 
  space?: string | number
): string;

type JSONReplacer = ((key: string, value: any) => any) | (number | string)[] | null;

// Write simple object
const packageData = {
  name: "my-package",
  version: "1.0.0",
  dependencies: {
    lodash: "^4.17.21"
  }
};
fs.writeJSON("package.json", packageData);

// Write with custom spacing
fs.writeJSON("config.json", { port: 3000, debug: true }, null, 4);

// Write with replacer function
const data = { password: "secret", username: "admin", settings: {} };
fs.writeJSON("public-config.json", data, (key, value) => {
  return key === "password" ? "[REDACTED]" : value;
});

// Write with specific keys only
const user = { id: 1, name: "John", password: "secret", email: "john@example.com" };
fs.writeJSON("user-public.json", user, ["id", "name", "email"]);

/**
 * Extend existing JSON file with new properties
 * @param filepath - Path to JSON file
 * @param contents - Properties to merge with existing content
 * @param replacer - JSON.stringify replacer function or array of keys
 * @param space - Formatting spaces (default: 2)
 */
function extendJSON(
  filepath: string,
  contents?: Record<string, unknown>,
  replacer?: JSONReplacer,
  space?: string | number
): void;

// Extend existing package.json
fs.extendJSON("package.json", {
  scripts: {
    build: "tsc",
    test: "jest"
  },
  devDependencies: {
    typescript: "^4.9.0"
  }
});

// Add new properties to config
fs.extendJSON("config.json", {
  newFeature: true,
  timeout: 5000
});

// Create file if doesn't exist
fs.extendJSON("new-config.json", {
  created: new Date().toISOString(),
  version: "1.0.0"
});

/**
 * Append content to existing file
 * @param filepath - Target file path
 * @param contents - Content to append as string or Buffer
 * @param options - Append configuration options
 */
function append(filepath: string, contents: string | Buffer, options?: AppendOptions): void;

interface AppendOptions {
  /** Create file if it doesn't exist (default: undefined) */
  create?: boolean;
  /** Remove trailing whitespace before appending (default: true) */
  trimEnd?: boolean;
  /** Separator to add between existing and new content (default: OS EOL) */
  separator?: string;
}

// Simple append
fs.write("log.txt", "Initial log entry");
fs.append("log.txt", "\nSecond log entry");

// Append with newline separator
fs.append("log.txt", "Third entry", { separator: "\n" });

// Append to new file
fs.append("new-log.txt", "First entry in new file", { create: true });

// Append with trimming
fs.write("content.txt", "Hello World   ");
fs.append("content.txt", "!", { trimEnd: true });
// Result: "Hello World!"

// Build up a file with multiple appends
fs.write("script.sh", "#!/bin/bash\n");
fs.append("script.sh", "echo 'Starting script'", { separator: "\n" });
fs.append("script.sh", "echo 'Processing...'", { separator: "\n" });
fs.append("script.sh", "echo 'Done!'", { separator: "\n" });

// String content
fs.write("text.txt", "Plain text content");

// Buffer content  
const imageBuffer = Buffer.from([0x89, 0x50, 0x4E, 0x47]);
fs.write("image.png", imageBuffer);

// JSON objects
fs.writeJSON("data.json", { items: [1, 2, 3] });

// Mixed append operations
fs.write("mixed.txt", "Initial content");
fs.append("mixed.txt", Buffer.from("\nBinary data follows"));

// Make file executable
fs.write("script.sh", "#!/bin/bash\necho 'Hello'", { mode: 0o755 });

// Read-only file
fs.write("readonly.txt", "Important data", { mode: 0o444 });

// Standard file permissions
fs.write("regular.txt", "Regular file", { mode: 0o644 });