basic

AFS Basic Example

Demonstrates the core AFS operations — mount providers, list directories, read files, search content, write files, and inspect metadata.

What It Does

1. Mount a local directory and a JSON config file as AFS providers
2. List directory contents (files and subdirectories)
3. Read a file's content
4. Navigate JSON as a virtual directory tree (objects become folders, values become files)
5. Search for text patterns across all mounted files
6. Write a new file through AFS
7. Stat a file for metadata without reading its content

Run

bun index.ts

Expected Output

AFS Basic Example

Mounted providers:
  /project → afs-example-...
  /config → config

--- List /project ---
  📄 /README.md
  📄 /config.json
  📄 /src

--- List /project/src ---
  📄 /src/index.ts  (56 bytes)
  📄 /src/utils.ts  (63 bytes)

--- Read /project/README.md ---
# My Project

A sample project.

--- Navigate /config (JSON as directories) ---
  📄 /name
  📄 /version
  📄 /features
  config.name = "my-app"
  config.features → /features/auth, /features/api

--- Search for 'TODO' in /project ---
  /project/src/utils.ts: match found

--- Write /project/output.txt ---
  Written: Generated by AFS example

--- Stat /project/src/index.ts ---
  size: 56 bytes

Done!

Key Concepts

Mounting Providers

Every data source is a provider that you mount at a path. Once mounted, all AFS operations work uniformly regardless of the underlying storage.

const afs = new AFS();
await afs.mount(new AFSFS({ localPath: "./my-dir" }), "/project");
await afs.mount(new AFSJSON({ localPath: "./config.json" }), "/config");

JSON as a Filesystem

The JSON provider (@aigne/afs-json) maps JSON structure to directories and files:

• Objects and arrays become directories you can list
• Primitive values become files you can read
• Changes via write persist back to the original JSON file

Uniform Operations

Every provider supports the same operations: list, read, write, search, stat, explain, exec. Your code doesn't need to know what's behind the path.

Packages Used

• @aigne/afs — Core AFS library
• @aigne/afs-fs — Local filesystem provider
• @aigne/afs-json — JSON virtual filesystem provider