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

package/dist/provider/router.cjs

@@ -0,0 +1,185 @@
+
+//#region src/provider/router.ts
+/**
+* Calculate specificity score for a pattern.
+* Higher score = higher priority.
+*
+* Scoring rules:
+* - Static segment: +100
+* - Named parameter (single segment): +10
+* - Wildcard ((.*)  or (.+) or * or +): +1
+* - Bonus for more segments: +5 per segment
+*
+* Examples:
+* - /:path(.*) = 1 + 5 = 6 (low)
+* - /:path(.*)/.meta = 1 + 100 + 10 = 111 (higher - has static .meta)
+* - /:path(.*)/.meta/.kinds = 1 + 100 + 100 + 15 = 216 (highest)
+*/
+function calculateSpecificity(pattern) {
+	let score = 0;
+	const segments = pattern.split("/").filter(Boolean);
+	for (const segment of segments) if (segment.endsWith("*") || segment.endsWith("+") || segment.endsWith("(.*)") || segment.endsWith("(.+)")) score += 1;
+	else if (segment.startsWith(":")) score += 10;
+	else score += 100;
+	score += segments.length * 5;
+	return score;
+}
+function convertToURLPattern(pattern) {
+	let result = pattern.replace(/\/\*\*$/g, "/:_(.*)");
+	result = result.replace(/\/\*\*\//g, "/:_(.*)/");
+	if (result.includes("/**")) result = result.replace(/\/\*\*/g, "/:_(.*)");
+	result = result.replace(/\/:(\w+)\*(\/.+)/g, "{/:$1(.*)}?$2");
+	const segments = result.split("/").filter(Boolean);
+	if (segments.length >= 2) {
+		const lastSegment = segments[segments.length - 1];
+		if (lastSegment && /^:\w+\*$/.test(lastSegment)) {
+			const wildcardName = lastSegment.slice(1, -1);
+			result = `${`/${segments.slice(0, -1).join("/")}`}{/:${wildcardName}(.*)}?`;
+		}
+	}
+	result = result.replace(/:(\w+)\*/g, ":$1(.*)");
+	result = result.replace(/:(\w+)\+/g, ":$1(.+)");
+	return result;
+}
+/**
+* Provider router using native URLPattern for type-safe route handling.
+* Supports suffix patterns like /:path*\/.meta for flexible routing.
+*/
+var ProviderRouter = class {
+	routers = /* @__PURE__ */ new Map();
+	allPatterns = /* @__PURE__ */ new Set();
+	constructor() {
+		for (const op of [
+			"list",
+			"read",
+			"write",
+			"delete",
+			"exec",
+			"search",
+			"stat",
+			"explain",
+			"rename"
+		]) this.routers.set(op, { routes: [] });
+	}
+	/**
+	* Register a route with the router
+	*/
+	registerRoute(pattern, operation, handler, description, listOptions) {
+		const storage = this.routers.get(operation);
+		if (!storage) throw new Error(`Unknown operation: ${operation}`);
+		if (storage.routes.find((r) => r.originalPattern === pattern)) {
+			console.warn(`[AFSBaseProvider] Route conflict: ${operation} ${pattern} is being overwritten`);
+			storage.routes = storage.routes.filter((r) => r.originalPattern !== pattern);
+		}
+		const definition = {
+			pattern,
+			operation,
+			handler,
+			description,
+			listOptions
+		};
+		const urlPatternPath = convertToURLPattern(pattern);
+		const urlPattern = new URLPattern({ pathname: urlPatternPath });
+		const specificity = calculateSpecificity(urlPatternPath);
+		const compiledRoute = {
+			pattern: urlPattern,
+			originalPattern: pattern,
+			definition,
+			specificity
+		};
+		let inserted = false;
+		for (let i = 0; i < storage.routes.length; i++) {
+			const existingRoute = storage.routes[i];
+			if (existingRoute && specificity > existingRoute.specificity) {
+				storage.routes.splice(i, 0, compiledRoute);
+				inserted = true;
+				break;
+			}
+		}
+		if (!inserted) storage.routes.push(compiledRoute);
+		this.allPatterns.add(pattern);
+	}
+	/**
+	* Match a path against registered routes for an operation.
+	* Routes are checked in specificity order (most specific first).
+	*/
+	match(path, operation) {
+		const storage = this.routers.get(operation);
+		if (!storage) return null;
+		const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+		for (const route of storage.routes) {
+			const result = route.pattern.exec({ pathname: normalizedPath });
+			if (result) {
+				const params = {};
+				const groups = result.pathname.groups;
+				for (const [key, value] of Object.entries(groups)) params[key] = value !== void 0 ? decodeURIComponent(value) : value;
+				return {
+					route: route.definition,
+					params
+				};
+			}
+		}
+		return null;
+	}
+	/**
+	* Get static children paths for a given path.
+	* Used for list auto-expansion.
+	*
+	* This analyzes all registered patterns to find which ones
+	* would be direct children of the given path.
+	*
+	* Excludes .meta and .actions as they are implicit paths.
+	*/
+	getStaticChildren(basePath) {
+		const children = [];
+		const normalizedBase = basePath === "/" ? "" : basePath;
+		for (const pattern of this.allPatterns) {
+			if (pattern.endsWith("/.meta") || pattern.endsWith("/.actions")) continue;
+			const childPath = this.findStaticChild(normalizedBase, pattern);
+			if (childPath && !children.includes(childPath)) children.push(childPath);
+		}
+		return children;
+	}
+	/**
+	* Find a static child path from a pattern relative to basePath
+	*
+	* For patterns like "/:table/new" and basePath "/users",
+	* we need to check if the pattern could match and what static
+	* segment comes after.
+	*/
+	findStaticChild(basePath, pattern) {
+		const baseSegments = basePath ? basePath.split("/").filter(Boolean) : [];
+		const patternSegments = pattern.split("/").filter(Boolean);
+		if (patternSegments.length <= baseSegments.length) return null;
+		for (let i = 0; i < baseSegments.length; i++) {
+			const patternSeg = patternSegments[i];
+			const baseSeg = baseSegments[i];
+			const isParam$1 = patternSeg?.startsWith(":");
+			const isWildcard$1 = patternSeg === "**" || patternSeg?.endsWith("*") || patternSeg?.endsWith("+") || patternSeg?.endsWith("(.*)") || patternSeg?.endsWith("(.+)");
+			if (patternSeg !== baseSeg && !isParam$1 && !isWildcard$1) return null;
+		}
+		const nextSegment = patternSegments[baseSegments.length];
+		if (!nextSegment) return null;
+		const isParam = nextSegment.startsWith(":");
+		const isWildcard = nextSegment === "**" || nextSegment.endsWith("*") || nextSegment.endsWith("+") || nextSegment.endsWith("(.*)") || nextSegment.endsWith("(.+)");
+		if (isParam || isWildcard) return null;
+		return `${basePath}/${nextSegment}`;
+	}
+	/**
+	* Get all registered patterns
+	*/
+	getAllPatterns() {
+		return Array.from(this.allPatterns);
+	}
+	/**
+	* Get all routes for an operation
+	*/
+	getRoutesForOperation(operation) {
+		const storage = this.routers.get(operation);
+		if (!storage) return [];
+		return storage.routes.map((r) => r.definition);
+	}
+};
+
+//#endregion
+exports.ProviderRouter = ProviderRouter;

package/dist/provider/router.d.cts

@@ -0,0 +1,50 @@
+import { ListDecoratorOptions, RouteDefinition, RouteHandler, RouteMatch, RouteOperation } from "./types.cjs";
+
+//#region src/provider/router.d.ts
+/**
+ * Provider router using native URLPattern for type-safe route handling.
+ * Supports suffix patterns like /:path*\/.meta for flexible routing.
+ */
+declare class ProviderRouter {
+  private routers;
+  private allPatterns;
+  constructor();
+  /**
+   * Register a route with the router
+   */
+  registerRoute(pattern: string, operation: RouteOperation, handler: RouteHandler, description?: string, listOptions?: ListDecoratorOptions): void;
+  /**
+   * Match a path against registered routes for an operation.
+   * Routes are checked in specificity order (most specific first).
+   */
+  match(path: string, operation: RouteOperation): RouteMatch | null;
+  /**
+   * Get static children paths for a given path.
+   * Used for list auto-expansion.
+   *
+   * This analyzes all registered patterns to find which ones
+   * would be direct children of the given path.
+   *
+   * Excludes .meta and .actions as they are implicit paths.
+   */
+  getStaticChildren(basePath: string): string[];
+  /**
+   * Find a static child path from a pattern relative to basePath
+   *
+   * For patterns like "/:table/new" and basePath "/users",
+   * we need to check if the pattern could match and what static
+   * segment comes after.
+   */
+  private findStaticChild;
+  /**
+   * Get all registered patterns
+   */
+  getAllPatterns(): string[];
+  /**
+   * Get all routes for an operation
+   */
+  getRoutesForOperation(operation: RouteOperation): RouteDefinition[];
+}
+//#endregion
+export { ProviderRouter };
+//# sourceMappingURL=router.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.cts","names":[],"sources":["../../src/provider/router.ts"],"mappings":";;;;;AA0HA;;cAAa,cAAA;EAAA,QACH,OAAA;EAAA,QACA,WAAA;;EA2FuB;;;EAlE/B,aAAA,CACE,OAAA,UACA,SAAA,EAAW,cAAA,EACX,OAAA,EAAS,YAAA,EACT,WAAA,WACA,WAAA,GAAc,oBAAA;EA8LiD;;;;EAjIjE,KAAA,CAAM,IAAA,UAAc,SAAA,EAAW,cAAA,GAAiB,UAAA;EAlEhD;;;;;;;;;EA6GA,iBAAA,CAAkB,QAAA;EA3CZ;;;;;;;EAAA,QAsEE,eAAA;EA2DR;;;EAPA,cAAA,CAAA;EAOiE;;;EAAjE,qBAAA,CAAsB,SAAA,EAAW,cAAA,GAAiB,eAAA;AAAA"}

package/dist/provider/router.d.mts

@@ -0,0 +1,50 @@
+import { ListDecoratorOptions, RouteDefinition, RouteHandler, RouteMatch, RouteOperation } from "./types.mjs";
+
+//#region src/provider/router.d.ts
+/**
+ * Provider router using native URLPattern for type-safe route handling.
+ * Supports suffix patterns like /:path*\/.meta for flexible routing.
+ */
+declare class ProviderRouter {
+  private routers;
+  private allPatterns;
+  constructor();
+  /**
+   * Register a route with the router
+   */
+  registerRoute(pattern: string, operation: RouteOperation, handler: RouteHandler, description?: string, listOptions?: ListDecoratorOptions): void;
+  /**
+   * Match a path against registered routes for an operation.
+   * Routes are checked in specificity order (most specific first).
+   */
+  match(path: string, operation: RouteOperation): RouteMatch | null;
+  /**
+   * Get static children paths for a given path.
+   * Used for list auto-expansion.
+   *
+   * This analyzes all registered patterns to find which ones
+   * would be direct children of the given path.
+   *
+   * Excludes .meta and .actions as they are implicit paths.
+   */
+  getStaticChildren(basePath: string): string[];
+  /**
+   * Find a static child path from a pattern relative to basePath
+   *
+   * For patterns like "/:table/new" and basePath "/users",
+   * we need to check if the pattern could match and what static
+   * segment comes after.
+   */
+  private findStaticChild;
+  /**
+   * Get all registered patterns
+   */
+  getAllPatterns(): string[];
+  /**
+   * Get all routes for an operation
+   */
+  getRoutesForOperation(operation: RouteOperation): RouteDefinition[];
+}
+//#endregion
+export { ProviderRouter };
+//# sourceMappingURL=router.d.mts.map

package/dist/provider/router.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.mts","names":[],"sources":["../../src/provider/router.ts"],"mappings":";;;;;AA0HA;;cAAa,cAAA;EAAA,QACH,OAAA;EAAA,QACA,WAAA;;EA2FuB;;;EAlE/B,aAAA,CACE,OAAA,UACA,SAAA,EAAW,cAAA,EACX,OAAA,EAAS,YAAA,EACT,WAAA,WACA,WAAA,GAAc,oBAAA;EA8LiD;;;;EAjIjE,KAAA,CAAM,IAAA,UAAc,SAAA,EAAW,cAAA,GAAiB,UAAA;EAlEhD;;;;;;;;;EA6GA,iBAAA,CAAkB,QAAA;EA3CZ;;;;;;;EAAA,QAsEE,eAAA;EA2DR;;;EAPA,cAAA,CAAA;EAOiE;;;EAAjE,qBAAA,CAAsB,SAAA,EAAW,cAAA,GAAiB,eAAA;AAAA"}

package/dist/provider/router.mjs

@@ -0,0 +1,185 @@
+//#region src/provider/router.ts
+/**
+* Calculate specificity score for a pattern.
+* Higher score = higher priority.
+*
+* Scoring rules:
+* - Static segment: +100
+* - Named parameter (single segment): +10
+* - Wildcard ((.*)  or (.+) or * or +): +1
+* - Bonus for more segments: +5 per segment
+*
+* Examples:
+* - /:path(.*) = 1 + 5 = 6 (low)
+* - /:path(.*)/.meta = 1 + 100 + 10 = 111 (higher - has static .meta)
+* - /:path(.*)/.meta/.kinds = 1 + 100 + 100 + 15 = 216 (highest)
+*/
+function calculateSpecificity(pattern) {
+	let score = 0;
+	const segments = pattern.split("/").filter(Boolean);
+	for (const segment of segments) if (segment.endsWith("*") || segment.endsWith("+") || segment.endsWith("(.*)") || segment.endsWith("(.+)")) score += 1;
+	else if (segment.startsWith(":")) score += 10;
+	else score += 100;
+	score += segments.length * 5;
+	return score;
+}
+function convertToURLPattern(pattern) {
+	let result = pattern.replace(/\/\*\*$/g, "/:_(.*)");
+	result = result.replace(/\/\*\*\//g, "/:_(.*)/");
+	if (result.includes("/**")) result = result.replace(/\/\*\*/g, "/:_(.*)");
+	result = result.replace(/\/:(\w+)\*(\/.+)/g, "{/:$1(.*)}?$2");
+	const segments = result.split("/").filter(Boolean);
+	if (segments.length >= 2) {
+		const lastSegment = segments[segments.length - 1];
+		if (lastSegment && /^:\w+\*$/.test(lastSegment)) {
+			const wildcardName = lastSegment.slice(1, -1);
+			result = `${`/${segments.slice(0, -1).join("/")}`}{/:${wildcardName}(.*)}?`;
+		}
+	}
+	result = result.replace(/:(\w+)\*/g, ":$1(.*)");
+	result = result.replace(/:(\w+)\+/g, ":$1(.+)");
+	return result;
+}
+/**
+* Provider router using native URLPattern for type-safe route handling.
+* Supports suffix patterns like /:path*\/.meta for flexible routing.
+*/
+var ProviderRouter = class {
+	routers = /* @__PURE__ */ new Map();
+	allPatterns = /* @__PURE__ */ new Set();
+	constructor() {
+		for (const op of [
+			"list",
+			"read",
+			"write",
+			"delete",
+			"exec",
+			"search",
+			"stat",
+			"explain",
+			"rename"
+		]) this.routers.set(op, { routes: [] });
+	}
+	/**
+	* Register a route with the router
+	*/
+	registerRoute(pattern, operation, handler, description, listOptions) {
+		const storage = this.routers.get(operation);
+		if (!storage) throw new Error(`Unknown operation: ${operation}`);
+		if (storage.routes.find((r) => r.originalPattern === pattern)) {
+			console.warn(`[AFSBaseProvider] Route conflict: ${operation} ${pattern} is being overwritten`);
+			storage.routes = storage.routes.filter((r) => r.originalPattern !== pattern);
+		}
+		const definition = {
+			pattern,
+			operation,
+			handler,
+			description,
+			listOptions
+		};
+		const urlPatternPath = convertToURLPattern(pattern);
+		const urlPattern = new URLPattern({ pathname: urlPatternPath });
+		const specificity = calculateSpecificity(urlPatternPath);
+		const compiledRoute = {
+			pattern: urlPattern,
+			originalPattern: pattern,
+			definition,
+			specificity
+		};
+		let inserted = false;
+		for (let i = 0; i < storage.routes.length; i++) {
+			const existingRoute = storage.routes[i];
+			if (existingRoute && specificity > existingRoute.specificity) {
+				storage.routes.splice(i, 0, compiledRoute);
+				inserted = true;
+				break;
+			}
+		}
+		if (!inserted) storage.routes.push(compiledRoute);
+		this.allPatterns.add(pattern);
+	}
+	/**
+	* Match a path against registered routes for an operation.
+	* Routes are checked in specificity order (most specific first).
+	*/
+	match(path, operation) {
+		const storage = this.routers.get(operation);
+		if (!storage) return null;
+		const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+		for (const route of storage.routes) {
+			const result = route.pattern.exec({ pathname: normalizedPath });
+			if (result) {
+				const params = {};
+				const groups = result.pathname.groups;
+				for (const [key, value] of Object.entries(groups)) params[key] = value !== void 0 ? decodeURIComponent(value) : value;
+				return {
+					route: route.definition,
+					params
+				};
+			}
+		}
+		return null;
+	}
+	/**
+	* Get static children paths for a given path.
+	* Used for list auto-expansion.
+	*
+	* This analyzes all registered patterns to find which ones
+	* would be direct children of the given path.
+	*
+	* Excludes .meta and .actions as they are implicit paths.
+	*/
+	getStaticChildren(basePath) {
+		const children = [];
+		const normalizedBase = basePath === "/" ? "" : basePath;
+		for (const pattern of this.allPatterns) {
+			if (pattern.endsWith("/.meta") || pattern.endsWith("/.actions")) continue;
+			const childPath = this.findStaticChild(normalizedBase, pattern);
+			if (childPath && !children.includes(childPath)) children.push(childPath);
+		}
+		return children;
+	}
+	/**
+	* Find a static child path from a pattern relative to basePath
+	*
+	* For patterns like "/:table/new" and basePath "/users",
+	* we need to check if the pattern could match and what static
+	* segment comes after.
+	*/
+	findStaticChild(basePath, pattern) {
+		const baseSegments = basePath ? basePath.split("/").filter(Boolean) : [];
+		const patternSegments = pattern.split("/").filter(Boolean);
+		if (patternSegments.length <= baseSegments.length) return null;
+		for (let i = 0; i < baseSegments.length; i++) {
+			const patternSeg = patternSegments[i];
+			const baseSeg = baseSegments[i];
+			const isParam$1 = patternSeg?.startsWith(":");
+			const isWildcard$1 = patternSeg === "**" || patternSeg?.endsWith("*") || patternSeg?.endsWith("+") || patternSeg?.endsWith("(.*)") || patternSeg?.endsWith("(.+)");
+			if (patternSeg !== baseSeg && !isParam$1 && !isWildcard$1) return null;
+		}
+		const nextSegment = patternSegments[baseSegments.length];
+		if (!nextSegment) return null;
+		const isParam = nextSegment.startsWith(":");
+		const isWildcard = nextSegment === "**" || nextSegment.endsWith("*") || nextSegment.endsWith("+") || nextSegment.endsWith("(.*)") || nextSegment.endsWith("(.+)");
+		if (isParam || isWildcard) return null;
+		return `${basePath}/${nextSegment}`;
+	}
+	/**
+	* Get all registered patterns
+	*/
+	getAllPatterns() {
+		return Array.from(this.allPatterns);
+	}
+	/**
+	* Get all routes for an operation
+	*/
+	getRoutesForOperation(operation) {
+		const storage = this.routers.get(operation);
+		if (!storage) return [];
+		return storage.routes.map((r) => r.definition);
+	}
+};
+
+//#endregion
+export { ProviderRouter };
+//# sourceMappingURL=router.mjs.map

package/dist/provider/router.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.mjs","names":["isParam","isWildcard"],"sources":["../../src/provider/router.ts"],"sourcesContent":["import type {\n  ListDecoratorOptions,\n  RouteDefinition,\n  RouteHandler,\n  RouteMatch,\n  RouteOperation,\n} from \"./types.js\";\n\n/**\n * Compiled route with URLPattern and metadata\n */\ninterface CompiledRoute {\n  /** URLPattern instance for matching */\n  pattern: URLPattern;\n  /** Original pattern string (e.g., /:path*\\/.meta) */\n  originalPattern: string;\n  /** Route definition */\n  definition: RouteDefinition;\n  /** Specificity score for priority sorting */\n  specificity: number;\n}\n\n/**\n * Internal storage for routes by operation\n */\ninterface RouterStorage {\n  routes: CompiledRoute[];\n}\n\n/**\n * Calculate specificity score for a pattern.\n * Higher score = higher priority.\n *\n * Scoring rules:\n * - Static segment: +100\n * - Named parameter (single segment): +10\n * - Wildcard ((.*)  or (.+) or * or +): +1\n * - Bonus for more segments: +5 per segment\n *\n * Examples:\n * - /:path(.*) = 1 + 5 = 6 (low)\n * - /:path(.*)/.meta = 1 + 100 + 10 = 111 (higher - has static .meta)\n * - /:path(.*)/.meta/.kinds = 1 + 100 + 100 + 15 = 216 (highest)\n */\nfunction calculateSpecificity(pattern: string): number {\n  let score = 0;\n  const segments = pattern.split(\"/\").filter(Boolean);\n\n  for (const segment of segments) {\n    // Check for wildcard patterns: ends with *, +, (.*), or (.+)\n    const isWildcard =\n      segment.endsWith(\"*\") ||\n      segment.endsWith(\"+\") ||\n      segment.endsWith(\"(.*)\") ||\n      segment.endsWith(\"(.+)\");\n\n    if (isWildcard) {\n      // Wildcard: lowest priority\n      score += 1;\n    } else if (segment.startsWith(\":\")) {\n      // Named parameter\n      score += 10;\n    } else {\n      // Static segment: highest priority\n      score += 100;\n    }\n  }\n\n  // Bonus for more segments (longer patterns are more specific)\n  score += segments.length * 5;\n\n  return score;\n}\n\n// Convert AFS route pattern syntax to URLPattern syntax.\n// Conversions:\n// - Standalone wildcard (e.g. at end) → /:_(.*) or /:name(.*)\n// - Suffix patterns (wildcard followed by more path) → optional group {/:name(.*)}?/suffix\n// - Trailing wildcard preceded by segments → optional group {/:name(.*)}?\n// - :name+ → :name(.+) (one or more segments)\nfunction convertToURLPattern(pattern: string): string {\n  // Replace standalone /** with /:_(.*)\n  let result = pattern.replace(/\\/\\*\\*$/g, \"/:_(.*)\");\n  result = result.replace(/\\/\\*\\*\\//g, \"/:_(.*)/\");\n\n  // Handle /** at start or middle\n  if (result.includes(\"/**\")) {\n    result = result.replace(/\\/\\*\\*/g, \"/:_(.*)\");\n  }\n\n  // Convert :name* followed by more path (suffix pattern) to optional group\n  // e.g., /:path*/.meta → {/:path(.*)}?/.meta\n  result = result.replace(/\\/:(\\w+)\\*(\\/.+)/g, \"{/:$1(.*)}?$2\");\n\n  // Convert trailing :name* (preceded by other segments) to optional group\n  // e.g., /:branch/:path* → /:branch{/:path(.*)}?\n  // This allows /main to match with path=undefined, and /main/foo to match with path=\"foo\"\n  // Only apply when there are at least 2 segments (prefix + wildcard)\n  const segments = result.split(\"/\").filter(Boolean);\n  if (segments.length >= 2) {\n    const lastSegment = segments[segments.length - 1];\n    if (lastSegment && /^:\\w+\\*$/.test(lastSegment)) {\n      // Last segment is a wildcard like :path*\n      const wildcardName = lastSegment.slice(1, -1); // Remove : and *\n      const prefix = `/${segments.slice(0, -1).join(\"/\")}`;\n      result = `${prefix}{/:${wildcardName}(.*)}?`;\n    }\n  }\n\n  // Convert standalone :name* to :name(.*) for zero-or-more matching (including empty)\n  result = result.replace(/:(\\w+)\\*/g, \":$1(.*)\");\n\n  // Convert :name+ to :name(.+) for one-or-more matching\n  result = result.replace(/:(\\w+)\\+/g, \":$1(.+)\");\n\n  return result;\n}\n\n/**\n * Provider router using native URLPattern for type-safe route handling.\n * Supports suffix patterns like /:path*\\/.meta for flexible routing.\n */\nexport class ProviderRouter {\n  private routers: Map<RouteOperation, RouterStorage> = new Map();\n  private allPatterns: Set<string> = new Set();\n\n  constructor() {\n    // Initialize routers for each operation type\n    const operations: RouteOperation[] = [\n      \"list\",\n      \"read\",\n      \"write\",\n      \"delete\",\n      \"exec\",\n      \"search\",\n      \"stat\",\n      \"explain\",\n      \"rename\",\n    ];\n    for (const op of operations) {\n      this.routers.set(op, {\n        routes: [],\n      });\n    }\n  }\n\n  /**\n   * Register a route with the router\n   */\n  registerRoute(\n    pattern: string,\n    operation: RouteOperation,\n    handler: RouteHandler,\n    description?: string,\n    listOptions?: ListDecoratorOptions,\n  ): void {\n    const storage = this.routers.get(operation);\n    if (!storage) {\n      throw new Error(`Unknown operation: ${operation}`);\n    }\n\n    // Check for conflict\n    const existing = storage.routes.find((r) => r.originalPattern === pattern);\n    if (existing) {\n      console.warn(\n        `[AFSBaseProvider] Route conflict: ${operation} ${pattern} is being overwritten`,\n      );\n      // Remove the existing route\n      storage.routes = storage.routes.filter((r) => r.originalPattern !== pattern);\n    }\n\n    const definition: RouteDefinition = {\n      pattern,\n      operation,\n      handler,\n      description,\n      listOptions,\n    };\n\n    // Convert pattern to URLPattern syntax\n    const urlPatternPath = convertToURLPattern(pattern);\n\n    // Create URLPattern (using pathname only)\n    const urlPattern = new URLPattern({ pathname: urlPatternPath });\n\n    const specificity = calculateSpecificity(urlPatternPath);\n\n    const compiledRoute: CompiledRoute = {\n      pattern: urlPattern,\n      originalPattern: pattern,\n      definition,\n      specificity,\n    };\n\n    // Insert in sorted order (highest specificity first)\n    let inserted = false;\n    for (let i = 0; i < storage.routes.length; i++) {\n      const existingRoute = storage.routes[i];\n      if (existingRoute && specificity > existingRoute.specificity) {\n        storage.routes.splice(i, 0, compiledRoute);\n        inserted = true;\n        break;\n      }\n    }\n    if (!inserted) {\n      storage.routes.push(compiledRoute);\n    }\n\n    this.allPatterns.add(pattern);\n  }\n\n  /**\n   * Match a path against registered routes for an operation.\n   * Routes are checked in specificity order (most specific first).\n   */\n  match(path: string, operation: RouteOperation): RouteMatch | null {\n    const storage = this.routers.get(operation);\n    if (!storage) {\n      return null;\n    }\n\n    // Ensure path starts with /\n    const normalizedPath = path.startsWith(\"/\") ? path : `/${path}`;\n\n    // Try routes in order (already sorted by specificity)\n    for (const route of storage.routes) {\n      const result = route.pattern.exec({ pathname: normalizedPath });\n      if (result) {\n        // Extract params from URLPattern groups\n        const params: Record<string, string | undefined> = {};\n        const groups = result.pathname.groups;\n\n        for (const [key, value] of Object.entries(groups)) {\n          // URLPattern may return empty string for optional wildcards\n          // We preserve the original value (could be undefined or empty string)\n          // Decode URL-encoded characters (e.g., %20 for spaces)\n          params[key] = value !== undefined ? decodeURIComponent(value) : value;\n        }\n\n        return {\n          route: route.definition,\n          params: params as Record<string, string>,\n        };\n      }\n    }\n\n    return null;\n  }\n\n  /**\n   * Get static children paths for a given path.\n   * Used for list auto-expansion.\n   *\n   * This analyzes all registered patterns to find which ones\n   * would be direct children of the given path.\n   *\n   * Excludes .meta and .actions as they are implicit paths.\n   */\n  getStaticChildren(basePath: string): string[] {\n    const children: string[] = [];\n    const normalizedBase = basePath === \"/\" ? \"\" : basePath;\n\n    for (const pattern of this.allPatterns) {\n      // Skip .meta and .actions - they are implicit\n      if (pattern.endsWith(\"/.meta\") || pattern.endsWith(\"/.actions\")) {\n        continue;\n      }\n\n      // Try to find a static child segment in this pattern\n      const childPath = this.findStaticChild(normalizedBase, pattern);\n      if (childPath && !children.includes(childPath)) {\n        children.push(childPath);\n      }\n    }\n\n    return children;\n  }\n\n  /**\n   * Find a static child path from a pattern relative to basePath\n   *\n   * For patterns like \"/:table/new\" and basePath \"/users\",\n   * we need to check if the pattern could match and what static\n   * segment comes after.\n   */\n  private findStaticChild(basePath: string, pattern: string): string | null {\n    const baseSegments = basePath ? basePath.split(\"/\").filter(Boolean) : [];\n    const patternSegments = pattern.split(\"/\").filter(Boolean);\n\n    // Pattern must be longer than base to have a child\n    if (patternSegments.length <= baseSegments.length) {\n      return null;\n    }\n\n    // Check if pattern could match basePath\n    for (let i = 0; i < baseSegments.length; i++) {\n      const patternSeg = patternSegments[i];\n      const baseSeg = baseSegments[i];\n\n      // Pattern segment must either match exactly or be a parameter/wildcard\n      const isParam = patternSeg?.startsWith(\":\");\n      const isWildcard =\n        patternSeg === \"**\" ||\n        patternSeg?.endsWith(\"*\") ||\n        patternSeg?.endsWith(\"+\") ||\n        patternSeg?.endsWith(\"(.*)\") ||\n        patternSeg?.endsWith(\"(.+)\");\n      if (patternSeg !== baseSeg && !isParam && !isWildcard) {\n        return null;\n      }\n    }\n\n    // Get the next segment after basePath\n    const nextSegment = patternSegments[baseSegments.length];\n\n    // Must be a static segment (not a parameter or wildcard)\n    if (!nextSegment) {\n      return null;\n    }\n    const isParam = nextSegment.startsWith(\":\");\n    const isWildcard =\n      nextSegment === \"**\" ||\n      nextSegment.endsWith(\"*\") ||\n      nextSegment.endsWith(\"+\") ||\n      nextSegment.endsWith(\"(.*)\") ||\n      nextSegment.endsWith(\"(.+)\");\n    if (isParam || isWildcard) {\n      return null;\n    }\n\n    // Build the child path\n    return `${basePath}/${nextSegment}`;\n  }\n\n  /**\n   * Get all registered patterns\n   */\n  getAllPatterns(): string[] {\n    return Array.from(this.allPatterns);\n  }\n\n  /**\n   * Get all routes for an operation\n   */\n  getRoutesForOperation(operation: RouteOperation): RouteDefinition[] {\n    const storage = this.routers.get(operation);\n    if (!storage) {\n      return [];\n    }\n    return storage.routes.map((r) => r.definition);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA4CA,SAAS,qBAAqB,SAAyB;CACrD,IAAI,QAAQ;CACZ,MAAM,WAAW,QAAQ,MAAM,IAAI,CAAC,OAAO,QAAQ;AAEnD,MAAK,MAAM,WAAW,SAQpB,KALE,QAAQ,SAAS,IAAI,IACrB,QAAQ,SAAS,IAAI,IACrB,QAAQ,SAAS,OAAO,IACxB,QAAQ,SAAS,OAAO,CAIxB,UAAS;UACA,QAAQ,WAAW,IAAI,CAEhC,UAAS;KAGT,UAAS;AAKb,UAAS,SAAS,SAAS;AAE3B,QAAO;;AAST,SAAS,oBAAoB,SAAyB;CAEpD,IAAI,SAAS,QAAQ,QAAQ,YAAY,UAAU;AACnD,UAAS,OAAO,QAAQ,aAAa,WAAW;AAGhD,KAAI,OAAO,SAAS,MAAM,CACxB,UAAS,OAAO,QAAQ,WAAW,UAAU;AAK/C,UAAS,OAAO,QAAQ,qBAAqB,gBAAgB;CAM7D,MAAM,WAAW,OAAO,MAAM,IAAI,CAAC,OAAO,QAAQ;AAClD,KAAI,SAAS,UAAU,GAAG;EACxB,MAAM,cAAc,SAAS,SAAS,SAAS;AAC/C,MAAI,eAAe,WAAW,KAAK,YAAY,EAAE;GAE/C,MAAM,eAAe,YAAY,MAAM,GAAG,GAAG;AAE7C,YAAS,GADM,IAAI,SAAS,MAAM,GAAG,GAAG,CAAC,KAAK,IAAI,GAC/B,KAAK,aAAa;;;AAKzC,UAAS,OAAO,QAAQ,aAAa,UAAU;AAG/C,UAAS,OAAO,QAAQ,aAAa,UAAU;AAE/C,QAAO;;;;;;AAOT,IAAa,iBAAb,MAA4B;CAC1B,AAAQ,0BAA8C,IAAI,KAAK;CAC/D,AAAQ,8BAA2B,IAAI,KAAK;CAE5C,cAAc;AAaZ,OAAK,MAAM,MAX0B;GACnC;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACD,CAEC,MAAK,QAAQ,IAAI,IAAI,EACnB,QAAQ,EAAE,EACX,CAAC;;;;;CAON,cACE,SACA,WACA,SACA,aACA,aACM;EACN,MAAM,UAAU,KAAK,QAAQ,IAAI,UAAU;AAC3C,MAAI,CAAC,QACH,OAAM,IAAI,MAAM,sBAAsB,YAAY;AAKpD,MADiB,QAAQ,OAAO,MAAM,MAAM,EAAE,oBAAoB,QAAQ,EAC5D;AACZ,WAAQ,KACN,qCAAqC,UAAU,GAAG,QAAQ,uBAC3D;AAED,WAAQ,SAAS,QAAQ,OAAO,QAAQ,MAAM,EAAE,oBAAoB,QAAQ;;EAG9E,MAAM,aAA8B;GAClC;GACA;GACA;GACA;GACA;GACD;EAGD,MAAM,iBAAiB,oBAAoB,QAAQ;EAGnD,MAAM,aAAa,IAAI,WAAW,EAAE,UAAU,gBAAgB,CAAC;EAE/D,MAAM,cAAc,qBAAqB,eAAe;EAExD,MAAM,gBAA+B;GACnC,SAAS;GACT,iBAAiB;GACjB;GACA;GACD;EAGD,IAAI,WAAW;AACf,OAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,OAAO,QAAQ,KAAK;GAC9C,MAAM,gBAAgB,QAAQ,OAAO;AACrC,OAAI,iBAAiB,cAAc,cAAc,aAAa;AAC5D,YAAQ,OAAO,OAAO,GAAG,GAAG,cAAc;AAC1C,eAAW;AACX;;;AAGJ,MAAI,CAAC,SACH,SAAQ,OAAO,KAAK,cAAc;AAGpC,OAAK,YAAY,IAAI,QAAQ;;;;;;CAO/B,MAAM,MAAc,WAA8C;EAChE,MAAM,UAAU,KAAK,QAAQ,IAAI,UAAU;AAC3C,MAAI,CAAC,QACH,QAAO;EAIT,MAAM,iBAAiB,KAAK,WAAW,IAAI,GAAG,OAAO,IAAI;AAGzD,OAAK,MAAM,SAAS,QAAQ,QAAQ;GAClC,MAAM,SAAS,MAAM,QAAQ,KAAK,EAAE,UAAU,gBAAgB,CAAC;AAC/D,OAAI,QAAQ;IAEV,MAAM,SAA6C,EAAE;IACrD,MAAM,SAAS,OAAO,SAAS;AAE/B,SAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,CAI/C,QAAO,OAAO,UAAU,SAAY,mBAAmB,MAAM,GAAG;AAGlE,WAAO;KACL,OAAO,MAAM;KACL;KACT;;;AAIL,SAAO;;;;;;;;;;;CAYT,kBAAkB,UAA4B;EAC5C,MAAM,WAAqB,EAAE;EAC7B,MAAM,iBAAiB,aAAa,MAAM,KAAK;AAE/C,OAAK,MAAM,WAAW,KAAK,aAAa;AAEtC,OAAI,QAAQ,SAAS,SAAS,IAAI,QAAQ,SAAS,YAAY,CAC7D;GAIF,MAAM,YAAY,KAAK,gBAAgB,gBAAgB,QAAQ;AAC/D,OAAI,aAAa,CAAC,SAAS,SAAS,UAAU,CAC5C,UAAS,KAAK,UAAU;;AAI5B,SAAO;;;;;;;;;CAUT,AAAQ,gBAAgB,UAAkB,SAAgC;EACxE,MAAM,eAAe,WAAW,SAAS,MAAM,IAAI,CAAC,OAAO,QAAQ,GAAG,EAAE;EACxE,MAAM,kBAAkB,QAAQ,MAAM,IAAI,CAAC,OAAO,QAAQ;AAG1D,MAAI,gBAAgB,UAAU,aAAa,OACzC,QAAO;AAIT,OAAK,IAAI,IAAI,GAAG,IAAI,aAAa,QAAQ,KAAK;GAC5C,MAAM,aAAa,gBAAgB;GACnC,MAAM,UAAU,aAAa;GAG7B,MAAMA,YAAU,YAAY,WAAW,IAAI;GAC3C,MAAMC,eACJ,eAAe,QACf,YAAY,SAAS,IAAI,IACzB,YAAY,SAAS,IAAI,IACzB,YAAY,SAAS,OAAO,IAC5B,YAAY,SAAS,OAAO;AAC9B,OAAI,eAAe,WAAW,CAACD,aAAW,CAACC,aACzC,QAAO;;EAKX,MAAM,cAAc,gBAAgB,aAAa;AAGjD,MAAI,CAAC,YACH,QAAO;EAET,MAAM,UAAU,YAAY,WAAW,IAAI;EAC3C,MAAM,aACJ,gBAAgB,QAChB,YAAY,SAAS,IAAI,IACzB,YAAY,SAAS,IAAI,IACzB,YAAY,SAAS,OAAO,IAC5B,YAAY,SAAS,OAAO;AAC9B,MAAI,WAAW,WACb,QAAO;AAIT,SAAO,GAAG,SAAS,GAAG;;;;;CAMxB,iBAA2B;AACzB,SAAO,MAAM,KAAK,KAAK,YAAY;;;;;CAMrC,sBAAsB,WAA8C;EAClE,MAAM,UAAU,KAAK,QAAQ,IAAI,UAAU;AAC3C,MAAI,CAAC,QACH,QAAO,EAAE;AAEX,SAAO,QAAQ,OAAO,KAAK,MAAM,EAAE,WAAW"}

package/dist/provider/types.d.cts

@@ -0,0 +1,113 @@
+import { AFSExplainResult } from "../meta/type.cjs";
+import { AFSDeleteOptions, AFSDeleteResult, AFSEntry, AFSExecOptions, AFSExecResult, AFSListOptions, AFSReadOptions, AFSRenameResult, AFSSearchOptions, AFSSearchResult, AFSStatResult, AFSWriteEntryPayload, AFSWriteOptions, AFSWriteResult } from "../type.cjs";
+
+//#region src/provider/types.d.ts
+/**
+ * Route operation types matching AFSModule methods
+ */
+type RouteOperation = "list" | "read" | "write" | "delete" | "exec" | "search" | "stat" | "explain" | "rename";
+/**
+ * Union type for all possible operation options
+ */
+type RouteOptions = AFSListOptions | AFSReadOptions | AFSWriteOptions | AFSDeleteOptions | AFSExecOptions | AFSSearchOptions;
+/**
+ * Context passed to route handlers
+ *
+ * Note: Wildcard params (e.g., :path*) may be undefined for paths that
+ * don't include that segment (e.g., root paths). Always check for undefined
+ * when using optional wildcard params.
+ */
+interface RouteContext<TParams = Record<string, string | undefined>> {
+  /** The full request path */
+  path: string;
+  /** Parameters extracted from the route pattern */
+  params: TParams;
+  /** Operation options (type depends on operation) */
+  options?: RouteOptions;
+}
+/**
+ * Result type for @List handlers
+ * - data: array of entries
+ * - total: optional, if present indicates complete dataset size
+ *          if absent, data.length IS the total (all data returned)
+ * - noExpand: optional, paths that should not be expanded during BFS depth traversal
+ *             (internal use only, not exposed in public API)
+ */
+interface ListHandlerResult {
+  data: AFSEntry[];
+  total?: number;
+  /** Paths that should not be expanded during BFS (internal, not exposed in public API) */
+  noExpand?: string[];
+}
+/**
+ * Handler function types for each operation
+ */
+type ListRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>) => Promise<ListHandlerResult>;
+type ReadRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>) => Promise<AFSEntry | undefined>;
+type WriteRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>, content: AFSWriteEntryPayload) => Promise<AFSWriteResult>;
+type DeleteRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>) => Promise<AFSDeleteResult>;
+type ExecRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>, args: Record<string, unknown>) => Promise<AFSExecResult>;
+type SearchRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>, query: string, options?: AFSSearchOptions) => Promise<AFSSearchResult>;
+type StatRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>) => Promise<AFSStatResult>;
+type ExplainRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>) => Promise<AFSExplainResult>;
+type RenameRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>, newPath: string) => Promise<AFSRenameResult>;
+/**
+ * Union type for all route handlers
+ */
+type RouteHandler = ListRouteHandler | ReadRouteHandler | WriteRouteHandler | DeleteRouteHandler | ExecRouteHandler | SearchRouteHandler | StatRouteHandler | ExplainRouteHandler | RenameRouteHandler;
+/**
+ * Route definition stored in the router
+ */
+interface RouteDefinition {
+  /** Route pattern (e.g., "/:table/:pk") */
+  pattern: string;
+  /** Operation type */
+  operation: RouteOperation;
+  /** Handler function */
+  handler: RouteHandler;
+  /** Optional description for documentation */
+  description?: string;
+  /** Options specific to list operations */
+  listOptions?: ListDecoratorOptions;
+}
+/**
+ * Options for @List decorator
+ */
+interface ListDecoratorOptions {
+  /**
+   * Whether the handler handles maxDepth recursion itself.
+   * - false (default): Base provider will auto-expand depth via BFS
+   * - true: Handler is responsible for depth traversal
+   *
+   * Most providers can use the default (false) and just return single-level results.
+   * Set to true for providers that need custom depth handling (like S3 with delimiter optimization).
+   */
+  handleDepth?: boolean;
+}
+/**
+ * Metadata stored by decorators for later collection
+ */
+interface RouteMetadata {
+  /** Route pattern */
+  pattern: string;
+  /** Operation type */
+  operation: RouteOperation;
+  /** Method name on the class */
+  methodName: string;
+  /** Optional description */
+  description?: string;
+  /** Options specific to list operations */
+  listOptions?: ListDecoratorOptions;
+}
+/**
+ * Match result from router
+ */
+interface RouteMatch {
+  /** The matched route definition */
+  route: RouteDefinition;
+  /** Extracted parameters (wildcards may be undefined or empty string) */
+  params: Record<string, string | undefined>;
+}
+//#endregion
+export { DeleteRouteHandler, ExecRouteHandler, ExplainRouteHandler, ListDecoratorOptions, ListHandlerResult, ListRouteHandler, ReadRouteHandler, RenameRouteHandler, RouteContext, RouteDefinition, RouteHandler, RouteMatch, RouteMetadata, RouteOperation, SearchRouteHandler, StatRouteHandler, WriteRouteHandler };
+//# sourceMappingURL=types.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/provider/types.ts"],"mappings":";;;;;;;KAqBY,cAAA;;;;KAcA,YAAA,GACR,cAAA,GACA,cAAA,GACA,eAAA,GACA,gBAAA,GACA,cAAA,GACA,gBAAA;AANJ;;;;;;;AAAA,UAeiB,YAAA,WAAuB,MAAA;EATpC;EAWF,IAAA;EAXkB;EAclB,MAAA,EAAQ,OAAA;EAlBN;EAqBF,OAAA,GAAU,YAAA;AAAA;;;;;AARZ;;;;UAmBiB,iBAAA;EACf,IAAA,EAAM,QAAA;EACN,KAAA;EAbsB;EAetB,QAAA;AAAA;;;;KAMU,gBAAA,WAA2B,MAAA,iCACrC,GAAA,EAAK,YAAA,CAAa,OAAA,MACf,OAAA,CAAQ,iBAAA;AAAA,KAED,gBAAA,WAA2B,MAAA,iCACrC,GAAA,EAAK,YAAA,CAAa,OAAA,MACf,OAAA,CAAQ,QAAA;AAAA,KAED,iBAAA,WAA4B,MAAA,iCACtC,GAAA,EAAK,YAAA,CAAa,OAAA,GAClB,OAAA,EAAS,oBAAA,KACN,OAAA,CAAQ,cAAA;AAAA,KAED,kBAAA,WAA6B,MAAA,iCACvC,GAAA,EAAK,YAAA,CAAa,OAAA,MACf,OAAA,CAAQ,eAAA;AAAA,KAED,gBAAA,WAA2B,MAAA,iCACrC,GAAA,EAAK,YAAA,CAAa,OAAA,GAClB,IAAA,EAAM,MAAA,sBACH,OAAA,CAAQ,aAAA;AAAA,KAED,kBAAA,WAA6B,MAAA,iCACvC,GAAA,EAAK,YAAA,CAAa,OAAA,GAClB,KAAA,UACA,OAAA,GAAU,gBAAA,KACP,OAAA,CAAQ,eAAA;AAAA,KAED,gBAAA,WAA2B,MAAA,iCACrC,GAAA,EAAK,YAAA,CAAa,OAAA,MACf,OAAA,CAAQ,aAAA;AAAA,KAED,mBAAA,WAA8B,MAAA,iCACxC,GAAA,EAAK,YAAA,CAAa,OAAA,MACf,OAAA,CAAQ,gBAAA;AAAA,KAED,kBAAA,WAA6B,MAAA,iCACvC,GAAA,EAAK,YAAA,CAAa,OAAA,GAClB,OAAA,aACG,OAAA,CAAQ,eAAA;;;;KAKD,YAAA,GACR,gBAAA,GACA,gBAAA,GACA,iBAAA,GACA,kBAAA,GACA,gBAAA,GACA,kBAAA,GACA,gBAAA,GACA,mBAAA,GACA,kBAAA;;AArDJ;;UA0DiB,eAAA;EA1DsB;EA4DrC,OAAA;EA3DK;EA8DL,SAAA,EAAW,cAAA;EA7DR;EAgEH,OAAA,EAAS,YAAA;EAhEC;EAmEV,WAAA;EArEqC;EAwErC,WAAA,GAAc,oBAAA;AAAA;;;;UAMC,oBAAA;EA5Ea;AAE9B;;;;;;;EAmFE,WAAA;AAAA;;;;UAMe,aAAA;EAxFG;EA0FlB,OAAA;EAzFG;EA4FH,SAAA,EAAW,cAAA;EA5FQ;EA+FnB,UAAA;EA7FU;EAgGV,WAAA;EAhG2B;EAmG3B,WAAA,GAAc,oBAAA;AAAA;;;;UAMC,UAAA;EAtGL;EAwGV,KAAA,EAAO,eAAA;EA3GqB;EA8G5B,MAAA,EAAQ,MAAA;AAAA"}