File System

Manage files, folders, and file collections

File

Creates and manages files in the filesystem with automatic directory creation and proper cleanup on deletion.

Properties

path · string · required

Path to the file (relative or absolute).

content · string · required

Content to write to the file.

Returns

path · string

Path to the created file.

content · string

Content of the file.

Examples

Create a simple text file

const config = await File("config.txt", {
  path: "config.txt",
  content: "some configuration data"
});

console.log(config.path); // "config.txt"

Create a file in a nested directory

const log = await File("logs/app.log", {
  path: "logs/app.log",
  content: "application log entry"
});

// Directory "logs" is created automatically

Update file content and path

let file = await File("config.json", {
  path: "config.json",
  content: JSON.stringify({ version: "1.0.0" })
});

// Later, update the path and content (old file will be removed)
file = await File("config.json", {
  path: "config/config.json",
  content: JSON.stringify({ version: "1.0.1" })
});

---

Folder

Creates and manages directories in the filesystem with automatic parent directory creation and cleanup on deletion.

Properties

path · string

Path to the folder. If not provided, uses the resource ID.

delete · boolean

Whether to delete the folder during the delete phase.

Default: true

clean · boolean

Whether to clean the folder during deletion (even if it contains existing files).

Default: false

recursive · boolean

Whether to create the folder recursively (including parent directories).

Default: true

Returns

path · string

Path to the created folder.

Examples

Create a directory using id as path

const dir = await Folder("uploads");

console.log(dir.path); // "uploads"

Create a directory with explicit path

const dir = await Folder("uploads", {
  path: "uploads"
});

Create a nested directory structure

const logs = await Folder("var/log/app", {
  path: "var/log/app",
  recursive: true  // Creates var/, var/log/, and var/log/app/
});

Persist folder on deletion

const cache = await Folder("cache", {
  path: ".cache",
  delete: false  // Folder won't be deleted when resource is destroyed
});

---

CopyFile

Copies a file from a source location to a destination location.

Properties

src · string · required

Source path of the file to copy.

dest · string · required

Destination path where the file should be copied to.

overwrite · boolean

Whether to overwrite the destination file if it already exists.

Default: true

Returns

src · string

Source path of the file.

dest · string

Destination path of the file.

copied · boolean

Whether the file was successfully copied.

createdAt · number

Timestamp when the copy operation completed.

Examples

Copy a file to a new location

const copiedFile = await CopyFile("config-copy", {
  src: "config.json",
  dest: "backup/config.json"
});

console.log(copiedFile.copied); // true

Copy without overwriting

const safeCopy = await CopyFile("safe-copy", {
  src: "data.json",
  dest: "backup/data.json",
  overwrite: false  // Won't overwrite if destination exists
});

---

File References

Alchemy provides utilities for working with file references and collections, useful for documentation generation and template processing.

alchemy.file()

Creates a reference to a file in the filesystem. Used in template string interpolation to include file contents.

const fileRef = await alchemy.file("./README.md");

console.log(fileRef);
// {
//   kind: "fs::FileRef",
//   path: "./README.md"
// }

Example: Include in documentation generation

import { Document } from "alchemy/ai";

await Document("api-docs", {
  prompt: await alchemy`
    Generate docs using the contents of:
    ${alchemy.file("./README.md")}
  `
});

alchemy.files()

Creates a collection of files with their contents. Used in template string interpolation to include multiple file contents.

const fileCollection = await alchemy.files([
  "src/types.ts",
  "src/resource.ts",
  "src/provider.ts"
]);

console.log(fileCollection);
// {
//   type: "fs::FileCollection",
//   files: {
//     "src/types.ts": "...content...",
//     "src/resource.ts": "...content...",
//     "src/provider.ts": "...content..."
//   }
// }

Variadic syntax

const files = await alchemy.files(
  "src/types.ts",
  "src/resource.ts",
  "src/provider.ts"
);

Example: Bulk documentation generation

import { Document } from "alchemy/ai";

await Document("provider-docs", {
  prompt: await alchemy`
    Generate comprehensive docs for these files:
    ${alchemy.files([
      "src/types.ts",
      "src/resource.ts",
      "src/provider.ts"
    ])}
  `
});

alchemy.folder()

Gets all files in a directory and returns them as a FileCollection.

const files = await alchemy.folder("./docs", {
  recursive: true  // Include all subdirectories
});

console.log(files.files);
// {
//   "docs/guide.md": "...content...",
//   "docs/api/index.md": "...content...",
//   ...
// }

Example: Process all documentation files

const docsFiles = await alchemy.folder("./docs", {
  recursive: true
});

// All file contents are available in docsFiles.files
for (const [path, content] of Object.entries(docsFiles.files)) {
  console.log(`${path}: ${content.length} bytes`);
}

---

Type Guards

isFileRef()

Type guard to check if a value is a FileRef.

import { isFileRef } from "alchemy/fs";

const value = await alchemy.file("./README.md");

if (isFileRef(value)) {
  console.log(value.path); // TypeScript knows this is a FileRef
}

isFileCollection()

Type guard to check if a value is a FileCollection.

import { isFileCollection } from "alchemy/fs";

const value = await alchemy.files(["file1.ts", "file2.ts"]);

if (isFileCollection(value)) {
  console.log(Object.keys(value.files)); // TypeScript knows this is a FileCollection
}