File
Creates and manages files in the filesystem with automatic directory creation and proper cleanup on deletion.
Properties
Path to the file (relative or absolute).
Content to write to the file.
Returns
Path to the created 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 to the folder. If not provided, uses the resource ID.
Whether to delete the folder during the delete phase.Default: true
Whether to clean the folder during deletion (even if it contains existing files).Default: false
Whether to create the folder recursively (including parent directories).Default: true
Returns
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
Source path of the file to copy.
Destination path where the file should be copied to.
Whether to overwrite the destination file if it already exists.Default: true
Returns
Destination path of the file.
Whether the file was successfully copied.
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
}