@aigne/afs 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.1.0](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.1.0-beta...afs-v1.1.0) (2025-10-19)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/sqlite bumped to 0.4.3
+
+## [1.1.0-beta](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.0.0...afs-v1.1.0-beta) (2025-10-11)
+
+
+### Features
+
+* **afs:** add module system fs for afs ([#594](https://github.com/AIGNE-io/aigne-framework/issues/594)) ([83c7b65](https://github.com/AIGNE-io/aigne-framework/commit/83c7b6555d21c606a5005eb05f6686882fb8ffa3))
+
 ## 1.0.0 (2025-10-07)
 
 

package/lib/cjs/afs.d.ts

@@ -4,6 +4,7 @@ import type { AFSStorage } from "./storage/type.js";
 import type { AFSEntry, AFSListOptions, AFSModule, AFSRoot, AFSRootEvents, AFSSearchOptions, AFSWriteEntryPayload } from "./type.js";
 export interface AFSOptions {
     storage?: SharedAFSStorage | SharedAFSStorageOptions;
+    modules?: AFSModule[];
 }
 export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     moduleId: string;
@@ -13,14 +14,27 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     storage(module: AFSModule): AFSStorage;
     private modules;
     use(module: AFSModule): this;
+    listModules(): Promise<{
+        moduleId: string;
+        path: string;
+        description?: string;
+    }[]>;
     list(path: string, options?: AFSListOptions): Promise<{
         list: AFSEntry[];
+        message?: string;
     }>;
     private findModules;
     private isSubpath;
-    read(path: string): Promise<AFSEntry | undefined>;
-    write(path: string, content: AFSWriteEntryPayload): Promise<AFSEntry>;
+    read(path: string): Promise<{
+        result?: AFSEntry;
+        message?: string;
+    }>;
+    write(path: string, content: AFSWriteEntryPayload): Promise<{
+        result: AFSEntry;
+        message?: string;
+    }>;
     search(path: string, query: string, options?: AFSSearchOptions): Promise<{
         list: AFSEntry[];
+        message?: string;
     }>;
 }

package/lib/cjs/afs.js

@@ -16,6 +16,9 @@ class AFS extends strict_event_emitter_1.Emitter {
                 ? options.storage
                 : new index_js_2.SharedAFSStorage(options?.storage);
         this.use(new index_js_1.AFSHistory());
+        for (const module of options?.modules ?? []) {
+            this.use(module);
+        }
     }
     _storage;
     storage(module) {
@@ -27,11 +30,19 @@ class AFS extends strict_event_emitter_1.Emitter {
         module.onMount?.(this);
         return this;
     }
+    async listModules() {
+        return Array.from(this.modules.entries()).map(([path, module]) => ({
+            moduleId: module.moduleId,
+            path,
+            description: module.description,
+        }));
+    }
     async list(path, options) {
         const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
         if (!(maxDepth >= 0))
             throw new Error(`Invalid maxDepth: ${maxDepth}`);
         const results = [];
+        const messages = [];
         const modules = this.findModules(path);
         for (const { module, subpath, mountPath } of modules) {
             if (!module.list)
@@ -40,17 +51,19 @@ class AFS extends strict_event_emitter_1.Emitter {
                 const newMaxDepth = maxDepth - mountPath.split("/").filter(Boolean).length;
                 if (newMaxDepth < 0)
                     continue;
-                const { list } = await module.list(subpath, { ...options, maxDepth: newMaxDepth });
+                const { list, message } = await module.list(subpath, { ...options, maxDepth: newMaxDepth });
                 results.push(...list.map((entry) => ({
                     ...entry,
                     path: (0, ufo_1.joinURL)(mountPath, entry.path),
                 })));
+                if (message)
+                    messages.push(message);
             }
             catch (error) {
                 console.error(`Error listing from module at ${mountPath}`, error);
             }
         }
-        return { list: results };
+        return { list: results, message: messages.join("; ") };
     }
     findModules(fullPath) {
         const modules = [];
@@ -76,51 +89,61 @@ class AFS extends strict_event_emitter_1.Emitter {
         else if (mp.startsWith(fp)) {
             return {
                 matchedDepth: fullPathSegments.length,
-                subpath: (0, ufo_1.joinURL)("/", ...mountPathSegments.slice(fullPathSegments.length)),
+                subpath: "/",
             };
         }
     }
     async read(path) {
         const modules = this.findModules(path);
         for (const { module, mountPath, subpath } of modules) {
-            const entry = await module.read?.(subpath);
-            if (entry) {
+            const res = await module.read?.(subpath);
+            if (res?.result) {
                 return {
-                    ...entry,
-                    path: (0, ufo_1.joinURL)(mountPath, entry.path),
+                    ...res,
+                    result: {
+                        ...res.result,
+                        path: (0, ufo_1.joinURL)(mountPath, res.result.path),
+                    },
                 };
             }
         }
+        return { result: undefined, message: "File not found" };
     }
     async write(path, content) {
         const module = this.findModules(path)[0];
         if (!module?.module.write)
             throw new Error(`No module found for path: ${path}`);
-        const entry = await module.module.write(module.subpath, content);
+        const res = await module.module.write(module.subpath, content);
         return {
-            ...entry,
-            path: (0, ufo_1.joinURL)(module.mountPath, entry.path),
+            ...res,
+            result: {
+                ...res.result,
+                path: (0, ufo_1.joinURL)(module.mountPath, res.result.path),
+            },
         };
     }
     async search(path, query, options) {
         const results = [];
+        const messages = [];
         for (const { module, mountPath, subpath } of this.findModules(path)) {
             if (mountPath.startsWith(path)) {
                 if (!module.search)
                     continue;
                 try {
-                    const { list } = await module.search(subpath, query, options);
+                    const { list, message } = await module.search(subpath, query, options);
                     results.push(...list.map((entry) => ({
                         ...entry,
                         path: (0, ufo_1.joinURL)(mountPath, entry.path),
                     })));
+                    if (message)
+                        messages.push(message);
                 }
                 catch (error) {
                     console.error(`Error searching in module at ${mountPath}`, error);
                 }
             }
         }
-        return { list: results };
+        return { list: results, message: messages.join("; ") };
     }
 }
 exports.AFS = AFS;

package/lib/cjs/history/index.d.ts

@@ -9,6 +9,12 @@ export declare class AFSHistory implements AFSModule {
     list(path: string, options?: AFSListOptions): Promise<{
         list: AFSEntry[];
     }>;
-    read(path: string): Promise<AFSEntry | undefined>;
-    write(path: string, content: AFSWriteEntryPayload): Promise<AFSEntry>;
+    read(path: string): Promise<{
+        result: AFSEntry | undefined;
+        message?: string;
+    }>;
+    write(path: string, content: AFSWriteEntryPayload): Promise<{
+        result: AFSEntry;
+        message?: string;
+    }>;
 }

package/lib/cjs/history/index.js

@@ -33,13 +33,15 @@ class AFSHistory {
     async list(path, options) {
         if (path !== "/")
             return { list: [] };
-        return this.afs.storage(this).list(options);
+        return await this.afs.storage(this).list(options);
     }
     async read(path) {
-        return this.afs.storage(this).read(path);
+        const result = await this.afs.storage(this).read(path);
+        return { result };
     }
     async write(path, content) {
-        return this.afs.storage(this).create({ ...content, path });
+        const result = await this.afs.storage(this).create({ ...content, path });
+        return { result };
     }
 }
 exports.AFSHistory = AFSHistory;

package/lib/cjs/type.d.ts

@@ -18,14 +18,23 @@ export interface AFSWriteEntryPayload extends Omit<AFSEntry, "id" | "path"> {
 export interface AFSModule {
     readonly moduleId: string;
     readonly path: string;
+    readonly description?: string;
     onMount?(root: AFSRoot): void;
     list?(path: string, options?: AFSListOptions): Promise<{
         list: AFSEntry[];
+        message?: string;
+    }>;
+    read?(path: string): Promise<{
+        result?: AFSEntry;
+        message?: string;
+    }>;
+    write?(path: string, content: AFSWriteEntryPayload): Promise<{
+        result: AFSEntry;
+        message?: string;
     }>;
-    read?(path: string): Promise<AFSEntry | undefined>;
-    write?(path: string, content: AFSWriteEntryPayload): Promise<AFSEntry>;
     search?(path: string, query: string, options?: AFSSearchOptions): Promise<{
         list: AFSEntry[];
+        message?: string;
     }>;
 }
 export type AFSRootEvents = {

package/lib/dts/afs.d.ts

@@ -4,6 +4,7 @@ import type { AFSStorage } from "./storage/type.js";
 import type { AFSEntry, AFSListOptions, AFSModule, AFSRoot, AFSRootEvents, AFSSearchOptions, AFSWriteEntryPayload } from "./type.js";
 export interface AFSOptions {
     storage?: SharedAFSStorage | SharedAFSStorageOptions;
+    modules?: AFSModule[];
 }
 export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     moduleId: string;
@@ -13,14 +14,27 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     storage(module: AFSModule): AFSStorage;
     private modules;
     use(module: AFSModule): this;
+    listModules(): Promise<{
+        moduleId: string;
+        path: string;
+        description?: string;
+    }[]>;
     list(path: string, options?: AFSListOptions): Promise<{
         list: AFSEntry[];
+        message?: string;
     }>;
     private findModules;
     private isSubpath;
-    read(path: string): Promise<AFSEntry | undefined>;
-    write(path: string, content: AFSWriteEntryPayload): Promise<AFSEntry>;
+    read(path: string): Promise<{
+        result?: AFSEntry;
+        message?: string;
+    }>;
+    write(path: string, content: AFSWriteEntryPayload): Promise<{
+        result: AFSEntry;
+        message?: string;
+    }>;
     search(path: string, query: string, options?: AFSSearchOptions): Promise<{
         list: AFSEntry[];
+        message?: string;
     }>;
 }

package/lib/dts/history/index.d.ts

@@ -9,6 +9,12 @@ export declare class AFSHistory implements AFSModule {
     list(path: string, options?: AFSListOptions): Promise<{
         list: AFSEntry[];
     }>;
-    read(path: string): Promise<AFSEntry | undefined>;
-    write(path: string, content: AFSWriteEntryPayload): Promise<AFSEntry>;
+    read(path: string): Promise<{
+        result: AFSEntry | undefined;
+        message?: string;
+    }>;
+    write(path: string, content: AFSWriteEntryPayload): Promise<{
+        result: AFSEntry;
+        message?: string;
+    }>;
 }

package/lib/dts/type.d.ts

@@ -18,14 +18,23 @@ export interface AFSWriteEntryPayload extends Omit<AFSEntry, "id" | "path"> {
 export interface AFSModule {
     readonly moduleId: string;
     readonly path: string;
+    readonly description?: string;
     onMount?(root: AFSRoot): void;
     list?(path: string, options?: AFSListOptions): Promise<{
         list: AFSEntry[];
+        message?: string;
+    }>;
+    read?(path: string): Promise<{
+        result?: AFSEntry;
+        message?: string;
+    }>;
+    write?(path: string, content: AFSWriteEntryPayload): Promise<{
+        result: AFSEntry;
+        message?: string;
     }>;
-    read?(path: string): Promise<AFSEntry | undefined>;
-    write?(path: string, content: AFSWriteEntryPayload): Promise<AFSEntry>;
     search?(path: string, query: string, options?: AFSSearchOptions): Promise<{
         list: AFSEntry[];
+        message?: string;
     }>;
 }
 export type AFSRootEvents = {

package/lib/esm/afs.d.ts

@@ -4,6 +4,7 @@ import type { AFSStorage } from "./storage/type.js";
 import type { AFSEntry, AFSListOptions, AFSModule, AFSRoot, AFSRootEvents, AFSSearchOptions, AFSWriteEntryPayload } from "./type.js";
 export interface AFSOptions {
     storage?: SharedAFSStorage | SharedAFSStorageOptions;
+    modules?: AFSModule[];
 }
 export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     moduleId: string;
@@ -13,14 +14,27 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     storage(module: AFSModule): AFSStorage;
     private modules;
     use(module: AFSModule): this;
+    listModules(): Promise<{
+        moduleId: string;
+        path: string;
+        description?: string;
+    }[]>;
     list(path: string, options?: AFSListOptions): Promise<{
         list: AFSEntry[];
+        message?: string;
     }>;
     private findModules;
     private isSubpath;
-    read(path: string): Promise<AFSEntry | undefined>;
-    write(path: string, content: AFSWriteEntryPayload): Promise<AFSEntry>;
+    read(path: string): Promise<{
+        result?: AFSEntry;
+        message?: string;
+    }>;
+    write(path: string, content: AFSWriteEntryPayload): Promise<{
+        result: AFSEntry;
+        message?: string;
+    }>;
     search(path: string, query: string, options?: AFSSearchOptions): Promise<{
         list: AFSEntry[];
+        message?: string;
     }>;
 }

package/lib/esm/afs.js

@@ -13,6 +13,9 @@ export class AFS extends Emitter {
                 ? options.storage
                 : new SharedAFSStorage(options?.storage);
         this.use(new AFSHistory());
+        for (const module of options?.modules ?? []) {
+            this.use(module);
+        }
     }
     _storage;
     storage(module) {
@@ -24,11 +27,19 @@ export class AFS extends Emitter {
         module.onMount?.(this);
         return this;
     }
+    async listModules() {
+        return Array.from(this.modules.entries()).map(([path, module]) => ({
+            moduleId: module.moduleId,
+            path,
+            description: module.description,
+        }));
+    }
     async list(path, options) {
         const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
         if (!(maxDepth >= 0))
             throw new Error(`Invalid maxDepth: ${maxDepth}`);
         const results = [];
+        const messages = [];
         const modules = this.findModules(path);
         for (const { module, subpath, mountPath } of modules) {
             if (!module.list)
@@ -37,17 +48,19 @@ export class AFS extends Emitter {
                 const newMaxDepth = maxDepth - mountPath.split("/").filter(Boolean).length;
                 if (newMaxDepth < 0)
                     continue;
-                const { list } = await module.list(subpath, { ...options, maxDepth: newMaxDepth });
+                const { list, message } = await module.list(subpath, { ...options, maxDepth: newMaxDepth });
                 results.push(...list.map((entry) => ({
                     ...entry,
                     path: joinURL(mountPath, entry.path),
                 })));
+                if (message)
+                    messages.push(message);
             }
             catch (error) {
                 console.error(`Error listing from module at ${mountPath}`, error);
             }
         }
-        return { list: results };
+        return { list: results, message: messages.join("; ") };
     }
     findModules(fullPath) {
         const modules = [];
@@ -73,50 +86,60 @@ export class AFS extends Emitter {
         else if (mp.startsWith(fp)) {
             return {
                 matchedDepth: fullPathSegments.length,
-                subpath: joinURL("/", ...mountPathSegments.slice(fullPathSegments.length)),
+                subpath: "/",
             };
         }
     }
     async read(path) {
         const modules = this.findModules(path);
         for (const { module, mountPath, subpath } of modules) {
-            const entry = await module.read?.(subpath);
-            if (entry) {
+            const res = await module.read?.(subpath);
+            if (res?.result) {
                 return {
-                    ...entry,
-                    path: joinURL(mountPath, entry.path),
+                    ...res,
+                    result: {
+                        ...res.result,
+                        path: joinURL(mountPath, res.result.path),
+                    },
                 };
             }
         }
+        return { result: undefined, message: "File not found" };
     }
     async write(path, content) {
         const module = this.findModules(path)[0];
         if (!module?.module.write)
             throw new Error(`No module found for path: ${path}`);
-        const entry = await module.module.write(module.subpath, content);
+        const res = await module.module.write(module.subpath, content);
         return {
-            ...entry,
-            path: joinURL(module.mountPath, entry.path),
+            ...res,
+            result: {
+                ...res.result,
+                path: joinURL(module.mountPath, res.result.path),
+            },
         };
     }
     async search(path, query, options) {
         const results = [];
+        const messages = [];
         for (const { module, mountPath, subpath } of this.findModules(path)) {
             if (mountPath.startsWith(path)) {
                 if (!module.search)
                     continue;
                 try {
-                    const { list } = await module.search(subpath, query, options);
+                    const { list, message } = await module.search(subpath, query, options);
                     results.push(...list.map((entry) => ({
                         ...entry,
                         path: joinURL(mountPath, entry.path),
                     })));
+                    if (message)
+                        messages.push(message);
                 }
                 catch (error) {
                     console.error(`Error searching in module at ${mountPath}`, error);
                 }
             }
         }
-        return { list: results };
+        return { list: results, message: messages.join("; ") };
     }
 }

package/lib/esm/history/index.d.ts

@@ -9,6 +9,12 @@ export declare class AFSHistory implements AFSModule {
     list(path: string, options?: AFSListOptions): Promise<{
         list: AFSEntry[];
     }>;
-    read(path: string): Promise<AFSEntry | undefined>;
-    write(path: string, content: AFSWriteEntryPayload): Promise<AFSEntry>;
+    read(path: string): Promise<{
+        result: AFSEntry | undefined;
+        message?: string;
+    }>;
+    write(path: string, content: AFSWriteEntryPayload): Promise<{
+        result: AFSEntry;
+        message?: string;
+    }>;
 }

package/lib/esm/history/index.js

@@ -30,12 +30,14 @@ export class AFSHistory {
     async list(path, options) {
         if (path !== "/")
             return { list: [] };
-        return this.afs.storage(this).list(options);
+        return await this.afs.storage(this).list(options);
     }
     async read(path) {
-        return this.afs.storage(this).read(path);
+        const result = await this.afs.storage(this).read(path);
+        return { result };
     }
     async write(path, content) {
-        return this.afs.storage(this).create({ ...content, path });
+        const result = await this.afs.storage(this).create({ ...content, path });
+        return { result };
     }
 }

package/lib/esm/type.d.ts

@@ -18,14 +18,23 @@ export interface AFSWriteEntryPayload extends Omit<AFSEntry, "id" | "path"> {
 export interface AFSModule {
     readonly moduleId: string;
     readonly path: string;
+    readonly description?: string;
     onMount?(root: AFSRoot): void;
     list?(path: string, options?: AFSListOptions): Promise<{
         list: AFSEntry[];
+        message?: string;
+    }>;
+    read?(path: string): Promise<{
+        result?: AFSEntry;
+        message?: string;
+    }>;
+    write?(path: string, content: AFSWriteEntryPayload): Promise<{
+        result: AFSEntry;
+        message?: string;
     }>;
-    read?(path: string): Promise<AFSEntry | undefined>;
-    write?(path: string, content: AFSWriteEntryPayload): Promise<AFSEntry>;
     search?(path: string, query: string, options?: AFSSearchOptions): Promise<{
         list: AFSEntry[];
+        message?: string;
     }>;
 }
 export type AFSRootEvents = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/afs",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "AIGNE File System (AFS) is a virtual file system that supports various storage backends and provides a unified API for file operations.",
   "publishConfig": {
     "access": "public"
@@ -50,7 +50,7 @@
     "@aigne/uuid": "^13.0.1",
     "strict-event-emitter": "^0.5.1",
     "ufo": "^1.6.1",
-    "@aigne/sqlite": "^0.4.3-beta"
+    "@aigne/sqlite": "^0.4.3"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",