@aigne/afs 1.11.0-beta → 1.11.0-beta.10

package/dist/provider/decorators.cjs

@@ -0,0 +1,268 @@
+
+//#region src/provider/decorators.ts
+/**
+* WeakMap-based route registry
+* Using WeakMap to avoid memory leaks - when class is garbage collected,
+* its routes are automatically cleaned up
+*/
+const routeRegistry = /* @__PURE__ */ new WeakMap();
+/**
+* Get all registered routes for a class (including inherited routes)
+*/
+function getRoutes(ctor) {
+	const routes = [];
+	let current = ctor;
+	while (current && current !== Function.prototype && current !== Object) {
+		const classRoutes = routeRegistry.get(current);
+		if (classRoutes) routes.unshift(...classRoutes);
+		current = Object.getPrototypeOf(current);
+	}
+	return routes;
+}
+/**
+* Clear routes for a class (mainly for testing)
+*/
+function clearRoutes(ctor) {
+	routeRegistry.delete(ctor);
+}
+/**
+* Register a route on a class
+*/
+function registerRoute(ctor, pattern, operation, methodName, description, listOptions) {
+	const routes = routeRegistry.get(ctor) || [];
+	routes.push({
+		pattern,
+		operation,
+		methodName,
+		description,
+		listOptions
+	});
+	routeRegistry.set(ctor, routes);
+}
+/**
+* Create a route decorator for a specific operation
+*/
+function createRouteDecorator(operation) {
+	return (pattern, description) => (target, propertyKey) => {
+		const ctor = target.constructor;
+		registerRoute(ctor, pattern, operation, String(propertyKey), description);
+	};
+}
+/**
+* @List decorator - handles list operations
+* Handler should return: { data: AFSEntry[], total?: number }
+*
+* @param pattern - Route pattern to match
+* @param optionsOrDescription - Either a description string or ListDecoratorOptions
+*
+* @example
+* ```typescript
+* // Simple usage
+* @List("/:table")
+* async listRows(ctx: RouteContext<{ table: string }>) {
+*   return { data: rows, total: 100 };
+* }
+*
+* // Default behavior - base provider handles depth via BFS
+* @List("/**")
+* async listDir(ctx: RouteContext) {
+*   // Only need to return single-level results
+*   return { data: entries };
+* }
+*
+* // Handler manages depth itself (opt-in for special cases like S3)
+* @List("/**", { handleDepth: true })
+* async listDirWithDepth(ctx: RouteContext) {
+*   // Handler implements maxDepth logic
+*   return { data: entries };
+* }
+* ```
+*/
+function List(pattern, optionsOrDescription) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const description = typeof optionsOrDescription === "string" ? optionsOrDescription : void 0;
+		const listOptions = typeof optionsOrDescription === "object" ? optionsOrDescription : void 0;
+		registerRoute(ctor, pattern, "list", String(propertyKey), description, listOptions);
+	};
+}
+/**
+* @Read decorator - handles read operations
+* Handler should return: AFSEntry
+*
+* @example
+* ```typescript
+* @Read("/:table/:pk")
+* async getRow(ctx: RouteContext<{ table: string; pk: string }>) {
+*   return { id: pk, path: ctx.path, content: row };
+* }
+* ```
+*/
+const Read = createRouteDecorator("read");
+/**
+* @Write decorator - handles write operations
+* Handler should return: AFSWriteResult
+*
+* @example
+* ```typescript
+* @Write("/:table/:pk")
+* async updateRow(ctx: RouteContext, content: AFSWriteEntryPayload) {
+*   return { data: updatedEntry };
+* }
+* ```
+*/
+const Write = createRouteDecorator("write");
+/**
+* @Delete decorator - handles delete operations
+* Handler should return: AFSDeleteResult
+*
+* @example
+* ```typescript
+* @Delete("/:table/:pk")
+* async deleteRow(ctx: RouteContext<{ table: string; pk: string }>) {
+*   return { message: "Deleted" };
+* }
+* ```
+*/
+const Delete = createRouteDecorator("delete");
+/**
+* @Exec decorator - handles exec operations
+* Handler should return: AFSExecResult
+*
+* @example
+* ```typescript
+* @Exec("/:table/:pk/.actions/:action")
+* async executeAction(ctx: RouteContext, args: Record<string, unknown>) {
+*   return { data: { success: true } };
+* }
+* ```
+*/
+const Exec = createRouteDecorator("exec");
+/**
+* @Search decorator - handles search operations
+* Handler should return: AFSSearchResult
+*
+* @example
+* ```typescript
+* @Search("/:table")
+* async searchTable(ctx: RouteContext, query: string, options?: AFSSearchOptions) {
+*   return { data: matchingEntries };
+* }
+* ```
+*/
+const Search = createRouteDecorator("search");
+/**
+* @Meta decorator - handles .meta path reads (introspection only, read-only)
+* Automatically appends /.meta to the pattern
+* Handler should return: AFSEntry
+*
+* Note: Meta is read-only. To write metadata, use @Write handler with payload.meta.
+*
+* @example
+* ```typescript
+* @Meta("/:table/:pk")  // Registers as /:table/:pk/.meta
+* async getRowMeta(ctx: RouteContext<{ table: string; pk: string }>) {
+*   return { id: "meta", path: `${ctx.path}/.meta`, content: schema };
+* }
+*
+* @Meta("/")  // Registers as /.meta (root metadata)
+* async getRootMeta(ctx: RouteContext) {
+*   return { id: "meta", path: "/.meta", content: rootSchema };
+* }
+* ```
+*/
+function Meta(pattern, description) {
+	const metaPattern = pattern === "/" ? "/.meta" : `${pattern}/.meta`;
+	return createRouteDecorator("read")(metaPattern, description);
+}
+/**
+* Creates a list decorator for .actions path
+*/
+function createActionsListDecorator(pattern, description) {
+	const actionsPattern = pattern === "/" ? "/.actions" : `${pattern}/.actions`;
+	return createRouteDecorator("list")(actionsPattern, description);
+}
+/**
+* Creates an exec decorator for action execution
+*/
+function createActionsExecuteDecorator(pattern, actionName, description) {
+	const basePath = pattern === "/" ? "" : pattern;
+	const fullPattern = actionName ? `${basePath}/.actions/${actionName}` : `${basePath}/.actions/:action`;
+	return createRouteDecorator("exec")(fullPattern, description);
+}
+/**
+* @Actions decorator - handles action-related routes
+*
+* Use directly for listing actions:
+* @example
+* ```typescript
+* @Actions("/:table/:pk")  // Registers as /:table/:pk/.actions
+* async listRowActions(ctx: RouteContext<{ table: string; pk: string }>) {
+*   return { data: availableActions };
+* }
+* ```
+*
+* Use Actions.Exec for action execution:
+* @example
+* ```typescript
+* @Actions.Exec("/:table/:pk", "close")
+* async closeAction(ctx: RouteContext, args: Record<string, unknown>) { ... }
+* ```
+*/
+const Actions = Object.assign((pattern, description) => {
+	return createActionsListDecorator(pattern, description);
+}, { Exec: createActionsExecuteDecorator });
+/**
+* @Stat decorator - handles stat operations
+* Handler should return: AFSStatResult
+*
+* @example
+* ```typescript
+* @Stat("/:path*")
+* async statPath(ctx: RouteContext<{ path?: string }>) {
+*   return { data: { path: ctx.path, size: 100, modified: new Date() } };
+* }
+* ```
+*/
+const Stat = createRouteDecorator("stat");
+/**
+* @Explain decorator - handles explain operations
+* Handler should return: AFSExplainResult
+*
+* @example
+* ```typescript
+* @Explain("/:path*")
+* async explainPath(ctx: RouteContext<{ path?: string }>) {
+*   return { data: { content: "...", format: "markdown" } };
+* }
+* ```
+*/
+const Explain = createRouteDecorator("explain");
+/**
+* @Rename decorator - handles rename operations
+* Handler should return: AFSRenameResult
+*
+* @example
+* ```typescript
+* @Rename("/:path*")
+* async renamePath(ctx: RouteContext<{ path?: string }>, newPath: string) {
+*   return { message: "Renamed successfully" };
+* }
+* ```
+*/
+const Rename = createRouteDecorator("rename");
+
+//#endregion
+exports.Actions = Actions;
+exports.Delete = Delete;
+exports.Exec = Exec;
+exports.Explain = Explain;
+exports.List = List;
+exports.Meta = Meta;
+exports.Read = Read;
+exports.Rename = Rename;
+exports.Search = Search;
+exports.Stat = Stat;
+exports.Write = Write;
+exports.clearRoutes = clearRoutes;
+exports.getRoutes = getRoutes;

package/dist/provider/decorators.d.cts

@@ -0,0 +1,244 @@
+import { ListDecoratorOptions, RouteMetadata } from "./types.cjs";
+
+//#region src/provider/decorators.d.ts
+type Constructor = Function;
+/**
+ * Get all registered routes for a class (including inherited routes)
+ */
+declare function getRoutes(ctor: Constructor): RouteMetadata[];
+/**
+ * Clear routes for a class (mainly for testing)
+ */
+declare function clearRoutes(ctor: Constructor): void;
+/**
+ * @List decorator - handles list operations
+ * Handler should return: { data: AFSEntry[], total?: number }
+ *
+ * @param pattern - Route pattern to match
+ * @param optionsOrDescription - Either a description string or ListDecoratorOptions
+ *
+ * @example
+ * ```typescript
+ * // Simple usage
+ * @List("/:table")
+ * async listRows(ctx: RouteContext<{ table: string }>) {
+ *   return { data: rows, total: 100 };
+ * }
+ *
+ * // Default behavior - base provider handles depth via BFS
+ * @List("/**")
+ * async listDir(ctx: RouteContext) {
+ *   // Only need to return single-level results
+ *   return { data: entries };
+ * }
+ *
+ * // Handler manages depth itself (opt-in for special cases like S3)
+ * @List("/**", { handleDepth: true })
+ * async listDirWithDepth(ctx: RouteContext) {
+ *   // Handler implements maxDepth logic
+ *   return { data: entries };
+ * }
+ * ```
+ */
+declare function List(pattern: string, optionsOrDescription?: string | ListDecoratorOptions): MethodDecorator;
+/**
+ * @Read decorator - handles read operations
+ * Handler should return: AFSEntry
+ *
+ * @example
+ * ```typescript
+ * @Read("/:table/:pk")
+ * async getRow(ctx: RouteContext<{ table: string; pk: string }>) {
+ *   return { id: pk, path: ctx.path, content: row };
+ * }
+ * ```
+ */
+declare const Read: (pattern: string, description?: string) => MethodDecorator;
+/**
+ * @Write decorator - handles write operations
+ * Handler should return: AFSWriteResult
+ *
+ * @example
+ * ```typescript
+ * @Write("/:table/:pk")
+ * async updateRow(ctx: RouteContext, content: AFSWriteEntryPayload) {
+ *   return { data: updatedEntry };
+ * }
+ * ```
+ */
+declare const Write: (pattern: string, description?: string) => MethodDecorator;
+/**
+ * @Delete decorator - handles delete operations
+ * Handler should return: AFSDeleteResult
+ *
+ * @example
+ * ```typescript
+ * @Delete("/:table/:pk")
+ * async deleteRow(ctx: RouteContext<{ table: string; pk: string }>) {
+ *   return { message: "Deleted" };
+ * }
+ * ```
+ */
+declare const Delete: (pattern: string, description?: string) => MethodDecorator;
+/**
+ * @Exec decorator - handles exec operations
+ * Handler should return: AFSExecResult
+ *
+ * @example
+ * ```typescript
+ * @Exec("/:table/:pk/.actions/:action")
+ * async executeAction(ctx: RouteContext, args: Record<string, unknown>) {
+ *   return { data: { success: true } };
+ * }
+ * ```
+ */
+declare const Exec: (pattern: string, description?: string) => MethodDecorator;
+/**
+ * @Search decorator - handles search operations
+ * Handler should return: AFSSearchResult
+ *
+ * @example
+ * ```typescript
+ * @Search("/:table")
+ * async searchTable(ctx: RouteContext, query: string, options?: AFSSearchOptions) {
+ *   return { data: matchingEntries };
+ * }
+ * ```
+ */
+declare const Search: (pattern: string, description?: string) => MethodDecorator;
+/**
+ * @Meta decorator - handles .meta path reads (introspection only, read-only)
+ * Automatically appends /.meta to the pattern
+ * Handler should return: AFSEntry
+ *
+ * Note: Meta is read-only. To write metadata, use @Write handler with payload.meta.
+ *
+ * @example
+ * ```typescript
+ * @Meta("/:table/:pk")  // Registers as /:table/:pk/.meta
+ * async getRowMeta(ctx: RouteContext<{ table: string; pk: string }>) {
+ *   return { id: "meta", path: `${ctx.path}/.meta`, content: schema };
+ * }
+ *
+ * @Meta("/")  // Registers as /.meta (root metadata)
+ * async getRootMeta(ctx: RouteContext) {
+ *   return { id: "meta", path: "/.meta", content: rootSchema };
+ * }
+ * ```
+ */
+declare function Meta(pattern: string, description?: string): MethodDecorator;
+/**
+ * Actions decorator interface - callable function with Execute method
+ */
+interface ActionsDecorator {
+  /**
+   * @Actions decorator - handles .actions path listing
+   * Automatically appends /.actions to the pattern
+   * Handler should return: { data: AFSEntry[] }
+   *
+   * @param pattern - Base path pattern for the node
+   * @param description - Optional description for the route
+   *
+   * @example
+   * ```typescript
+   * @Actions("/:table/:pk")  // Registers as /:table/:pk/.actions
+   * async listRowActions(ctx: RouteContext<{ table: string; pk: string }>) {
+   *   return { data: availableActions };
+   * }
+   * ```
+   */
+  (pattern: string, description?: string): MethodDecorator;
+  /**
+   * @Actions.Exec decorator - handles action execution on nodes
+   * Automatically constructs the full .actions path for action execution.
+   * Handler should return: AFSExecResult
+   *
+   * @param pattern - Base path pattern for the node (e.g., "/issues/:number")
+   * @param actionName - Optional specific action name. If omitted, registers catch-all pattern.
+   * @param description - Optional description for the route
+   *
+   * @example
+   * ```typescript
+   * // Specific action - registers as /issues/:number/.actions/close
+   * @Actions.Exec("/issues/:number", "close")
+   * async closeIssue(ctx: RouteContext<{ number: string }>, args: Record<string, unknown>) {
+   *   return { data: { success: true } };
+   * }
+   *
+   * // Catch-all action - registers as /issues/:number/.actions/:action
+   * @Actions.Exec("/issues/:number")
+   * async handleIssueAction(ctx: RouteContext<{ number: string; action: string }>, args: Record<string, unknown>) {
+   *   return { data: { action: ctx.params.action } };
+   * }
+   *
+   * // Root-level action - registers as /.actions/refresh
+   * @Actions.Exec("/", "refresh")
+   * async refreshAll(ctx: RouteContext, args: Record<string, unknown>) {
+   *   return { data: { refreshed: true } };
+   * }
+   * ```
+   */
+  Exec: (pattern: string, actionName?: string, description?: string) => MethodDecorator;
+}
+/**
+ * @Actions decorator - handles action-related routes
+ *
+ * Use directly for listing actions:
+ * @example
+ * ```typescript
+ * @Actions("/:table/:pk")  // Registers as /:table/:pk/.actions
+ * async listRowActions(ctx: RouteContext<{ table: string; pk: string }>) {
+ *   return { data: availableActions };
+ * }
+ * ```
+ *
+ * Use Actions.Exec for action execution:
+ * @example
+ * ```typescript
+ * @Actions.Exec("/:table/:pk", "close")
+ * async closeAction(ctx: RouteContext, args: Record<string, unknown>) { ... }
+ * ```
+ */
+declare const Actions: ActionsDecorator;
+/**
+ * @Stat decorator - handles stat operations
+ * Handler should return: AFSStatResult
+ *
+ * @example
+ * ```typescript
+ * @Stat("/:path*")
+ * async statPath(ctx: RouteContext<{ path?: string }>) {
+ *   return { data: { path: ctx.path, size: 100, modified: new Date() } };
+ * }
+ * ```
+ */
+declare const Stat: (pattern: string, description?: string) => MethodDecorator;
+/**
+ * @Explain decorator - handles explain operations
+ * Handler should return: AFSExplainResult
+ *
+ * @example
+ * ```typescript
+ * @Explain("/:path*")
+ * async explainPath(ctx: RouteContext<{ path?: string }>) {
+ *   return { data: { content: "...", format: "markdown" } };
+ * }
+ * ```
+ */
+declare const Explain: (pattern: string, description?: string) => MethodDecorator;
+/**
+ * @Rename decorator - handles rename operations
+ * Handler should return: AFSRenameResult
+ *
+ * @example
+ * ```typescript
+ * @Rename("/:path*")
+ * async renamePath(ctx: RouteContext<{ path?: string }>, newPath: string) {
+ *   return { message: "Renamed successfully" };
+ * }
+ * ```
+ */
+declare const Rename: (pattern: string, description?: string) => MethodDecorator;
+//#endregion
+export { Actions, Delete, Exec, Explain, List, Meta, Read, Rename, Search, Stat, Write, clearRoutes, getRoutes };
+//# sourceMappingURL=decorators.d.cts.map

package/dist/provider/decorators.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.cts","names":[],"sources":["../../src/provider/decorators.ts"],"mappings":";;;KAGK,WAAA,GAAc,QAAA;;AAHmE;;iBAetE,SAAA,CAAU,IAAA,EAAM,WAAA,GAAc,aAAA;;;AAA9C;iBAoBgB,WAAA,CAAY,IAAA,EAAM,WAAA;;;;;;;;AAAlC;;;;;AA6DA;;;;;;;;;;AAwBA;;;;;;;;iBAxBgB,IAAA,CACd,OAAA,UACA,oBAAA,YAAgC,oBAAA,GAC/B,eAAA;AAmCH;;;;;;;;;AAcA;;;AAdA,cAda,IAAA,GAAI,OAAA,UA7DQ,WAAA,cAAyB,eAAA;;;;;;AAuGlD;;;;;;;cA5Ba,KAAA,GAAK,OAAA,UA3EO,WAAA,cAAyB,eAAA;;AAqHlD;;;;;;;;;AAsBA;;cAlDa,MAAA,GAAM,OAAA,UAzFM,WAAA,cAAyB,eAAA;;;;;;;AA+IjD;;;;;;cAxCY,IAAA,GAAI,OAAA,UAvGQ,WAAA,cAAyB,eAAA;;;;;;;;AAkPlD;;;;;cA7Ha,MAAA,GAAM,OAAA,UArHM,WAAA,cAAyB,eAAA;;;;;;;;;AAuRlD;;;;;;;;;AAcA;;;iBA1JgB,IAAA,CAAK,OAAA,UAAiB,WAAA,YAAuB,eAAA;;;;UAgCnD,gBAAA;EA0H0C;;;;;;;;;;;;;;;;EAAA,CAzGjD,OAAA,UAAiB,WAAA,YAAuB,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgCzC,IAAA,GAAO,OAAA,UAAiB,UAAA,WAAqB,WAAA,cAAyB,eAAA;AAAA;;;;;;;;;;;;;;;;;;;;cAsB3D,OAAA,EAAS,gBAAA;;;;;;;;;;;;;cAuBT,IAAA,GAAI,OAAA,UAzQQ,WAAA,cAAyB,eAAA;;;;;;;;;;;;;cAuRrC,OAAA,GAAO,OAAA,UAvRK,WAAA,cAAyB,eAAA;;;;;;;;;;;;;cAqSrC,MAAA,GAAM,OAAA,UArSM,WAAA,cAAyB,eAAA"}