@veloxts/client 0.6.64 → 0.6.65

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @veloxts/client
 
+## 0.6.65
+
+### Patch Changes
+
+- improve ai integration and simplify api router definition
+
 ## 0.6.64
 
 ### Patch Changes

package/dist/react/proxy-hooks.js

@@ -31,6 +31,51 @@ import { buildQueryKey } from './utils.js';
 // ============================================================================
 // Query/Mutation Detection
 // ============================================================================
+/**
+ * Query procedure naming prefixes
+ * Procedures starting with these prefixes are treated as queries.
+ */
+const QUERY_PREFIXES = ['get', 'list', 'find'];
+/**
+ * Mutation procedure naming prefixes
+ * Procedures starting with these prefixes are treated as mutations.
+ */
+const MUTATION_PREFIXES = ['create', 'add', 'update', 'edit', 'patch', 'delete', 'remove'];
+/**
+ * Map of common alternative prefixes to their standard equivalents
+ * Used to provide helpful suggestions when non-standard names are detected.
+ */
+const SIMILAR_PATTERNS = {
+    fetch: { type: 'query', suggest: 'list or get' },
+    retrieve: { type: 'query', suggest: 'get' },
+    obtain: { type: 'query', suggest: 'get' },
+    load: { type: 'query', suggest: 'list or get' },
+    read: { type: 'query', suggest: 'get' },
+    query: { type: 'query', suggest: 'list, get, or find' },
+    search: { type: 'query', suggest: 'find' },
+    new: { type: 'mutation', suggest: 'create' },
+    insert: { type: 'mutation', suggest: 'create' },
+    make: { type: 'mutation', suggest: 'create' },
+    modify: { type: 'mutation', suggest: 'update or patch' },
+    change: { type: 'mutation', suggest: 'update or patch' },
+    set: { type: 'mutation', suggest: 'update' },
+    destroy: { type: 'mutation', suggest: 'delete' },
+    drop: { type: 'mutation', suggest: 'delete' },
+    erase: { type: 'mutation', suggest: 'delete' },
+    trash: { type: 'mutation', suggest: 'delete' },
+};
+/**
+ * Detects if a procedure name uses a similar (non-standard) pattern
+ * @returns The similar pattern info if found, null otherwise
+ */
+function detectSimilarPattern(procedureName) {
+    for (const [prefix, info] of Object.entries(SIMILAR_PATTERNS)) {
+        if (procedureName.toLowerCase().startsWith(prefix)) {
+            return { prefix, ...info };
+        }
+    }
+    return null;
+}
 /**
  * Determines if a procedure is a query based on naming convention
  *
@@ -46,8 +91,86 @@ import { buildQueryKey } from './utils.js';
  * @returns true if the procedure is a query, false for mutation
  */
 function isQueryProcedure(procedureName) {
-    const queryPrefixes = ['get', 'list', 'find'];
-    return queryPrefixes.some((prefix) => procedureName.startsWith(prefix));
+    return QUERY_PREFIXES.some((prefix) => procedureName.startsWith(prefix));
+}
+/**
+ * Extracts the entity name from a procedure name by stripping common prefixes
+ * @example extractEntityName('fetchUsers') returns 'Users'
+ */
+function extractEntityName(procedureName) {
+    // Check for standard prefixes first
+    for (const prefix of [...QUERY_PREFIXES, ...MUTATION_PREFIXES]) {
+        if (procedureName.startsWith(prefix)) {
+            return procedureName.slice(prefix.length);
+        }
+    }
+    // Check for similar patterns
+    for (const prefix of Object.keys(SIMILAR_PATTERNS)) {
+        if (procedureName.toLowerCase().startsWith(prefix)) {
+            return procedureName.slice(prefix.length);
+        }
+    }
+    // Capitalize first letter for generic case
+    return procedureName.charAt(0).toUpperCase() + procedureName.slice(1);
+}
+/**
+ * Creates a helpful error message for naming convention violations
+ *
+ * Provides context-aware suggestions based on:
+ * - Whether the procedure uses a similar (non-standard) pattern like 'fetch'
+ * - What the developer likely intended based on the method they called
+ *
+ * @param procedureName - The procedure name that was accessed incorrectly
+ * @param attemptedMethod - The method that was called (e.g., 'useQuery', 'useMutation')
+ * @param isQuery - Whether the procedure is detected as a query
+ */
+function createNamingConventionError(procedureName, attemptedMethod, isQuery) {
+    const queryMethods = 'useQuery, useSuspenseQuery, getQueryKey, invalidate, prefetch, setData, getData';
+    const mutationMethods = 'useMutation';
+    const similarPattern = detectSimilarPattern(procedureName);
+    const entityName = extractEntityName(procedureName);
+    if (isQuery) {
+        // Called mutation method on a query procedure
+        const suggestions = MUTATION_PREFIXES.slice(0, 3).map((p) => `${p}${entityName}`);
+        return new Error(`Cannot call ${attemptedMethod}() on query procedure "${procedureName}".\n\n` +
+            `VeloxTS Naming Convention:\n` +
+            `  • Query procedures must start with: ${QUERY_PREFIXES.join(', ')}\n` +
+            `  • Mutation procedures must start with: ${MUTATION_PREFIXES.join(', ')}\n\n` +
+            `"${procedureName}" starts with a query prefix, so only these methods are available:\n` +
+            `  ${queryMethods}\n\n` +
+            `If this should be a mutation, rename it to one of:\n` +
+            `  ${suggestions.join(', ')}`);
+    }
+    // Called query method on a mutation procedure
+    // Check if using a similar pattern (e.g., 'fetchUsers' instead of 'listUsers')
+    if (similarPattern) {
+        const querySuggestions = similarPattern.suggest
+            .split(/,?\s+or\s+|,\s*/)
+            .map((s) => s.trim())
+            .filter(Boolean)
+            .map((prefix) => `${prefix}${entityName}`);
+        return new Error(`Cannot call ${attemptedMethod}() on procedure "${procedureName}".\n\n` +
+            `The prefix "${similarPattern.prefix}" is not a standard VeloxTS naming convention.\n\n` +
+            `Did you mean to use "${similarPattern.suggest}" instead?\n` +
+            `  Suggested name${querySuggestions.length > 1 ? 's' : ''}: ${querySuggestions.join(', ')}\n\n` +
+            `VeloxTS Naming Convention:\n` +
+            `  • Query procedures: ${QUERY_PREFIXES.join(', ')}\n` +
+            `  • Mutation procedures: ${MUTATION_PREFIXES.join(', ')}\n\n` +
+            `This matters because procedure names determine REST routes:\n` +
+            `  • "listUsers" → GET /users (collection)\n` +
+            `  • "getUser" → GET /users/:id (single resource)\n` +
+            `  • "fetchUsers" → POST /users (treated as mutation!)`);
+    }
+    // Generic mutation procedure, no similar pattern detected
+    const querySuggestions = QUERY_PREFIXES.map((p) => `${p}${entityName}`);
+    return new Error(`Cannot call ${attemptedMethod}() on mutation procedure "${procedureName}".\n\n` +
+        `VeloxTS Naming Convention:\n` +
+        `  • Query procedures must start with: ${QUERY_PREFIXES.join(', ')}\n` +
+        `  • Mutation procedures must start with: ${MUTATION_PREFIXES.join(', ')}\n\n` +
+        `"${procedureName}" does not start with a query prefix, so only these methods are available:\n` +
+        `  ${mutationMethods}\n\n` +
+        `If this should be a query, rename it to one of:\n` +
+        `  ${querySuggestions.join(', ')}`);
 }
 /**
  * Determines the mutation type from procedure name
@@ -170,7 +293,8 @@ async function performAutoInvalidation(queryClient, namespace, procedureName, in
  * @param getClient - Factory function to get the client (called inside hooks)
  */
 function createQueryProcedureProxy(namespace, procedureName, getClient) {
-    return {
+    // Add useMutation stub that throws helpful error
+    const proxy = {
         useQuery(...args) {
             const [input, options] = args;
             const client = getClient();
@@ -229,7 +353,12 @@ function createQueryProcedureProxy(namespace, procedureName, getClient) {
             const queryKey = buildQueryKey(namespace, procedureName, input);
             return queryClient.getQueryData(queryKey);
         },
+        // Stub that throws helpful error when called on a query procedure
+        useMutation() {
+            throw createNamingConventionError(procedureName, 'useMutation', true);
+        },
     };
+    return proxy;
 }
 /**
  * Creates a mutation procedure proxy with hook methods and auto-invalidation
@@ -244,13 +373,13 @@ function createQueryProcedureProxy(namespace, procedureName, getClient) {
  * @param getClient - Factory function to get the client (called inside hooks)
  */
 function createMutationProcedureProxy(namespace, procedureName, getClient) {
-    return {
+    // Add query method stubs that throw helpful errors
+    const proxy = {
         useMutation(options) {
             const client = getClient();
             const queryClient = useReactQueryClient();
             // Extract auto-invalidation configuration
-            const typedOptions = options;
-            const autoInvalidateOption = typedOptions?.autoInvalidate;
+            const autoInvalidateOption = options?.autoInvalidate;
             const autoInvalidateEnabled = autoInvalidateOption !== false;
             const autoInvalidateConfig = typeof autoInvalidateOption === 'object' ? autoInvalidateOption : undefined;
             // Store original onSuccess to call after auto-invalidation
@@ -274,11 +403,58 @@ function createMutationProcedureProxy(namespace, procedureName, getClient) {
                 },
             });
         },
+        // Stubs that throw helpful errors when called on a mutation procedure
+        useQuery() {
+            throw createNamingConventionError(procedureName, 'useQuery', false);
+        },
+        useSuspenseQuery() {
+            throw createNamingConventionError(procedureName, 'useSuspenseQuery', false);
+        },
+        getQueryKey() {
+            throw createNamingConventionError(procedureName, 'getQueryKey', false);
+        },
+        invalidate() {
+            throw createNamingConventionError(procedureName, 'invalidate', false);
+        },
+        prefetch() {
+            throw createNamingConventionError(procedureName, 'prefetch', false);
+        },
+        setData() {
+            throw createNamingConventionError(procedureName, 'setData', false);
+        },
+        getData() {
+            throw createNamingConventionError(procedureName, 'getData', false);
+        },
     };
+    return proxy;
 }
 // ============================================================================
 // Namespace Proxy
 // ============================================================================
+/**
+ * Determines procedure type using routes metadata or naming convention
+ *
+ * Priority:
+ * 1. If routes has explicit `kind` for this procedure, use it
+ * 2. Otherwise, fall back to naming convention heuristic
+ *
+ * @param namespace - The procedure namespace
+ * @param procedureName - The procedure name
+ * @param routes - Optional route metadata from backend
+ * @returns true if the procedure is a query, false for mutation
+ */
+function isProcedureQuery(namespace, procedureName, routes) {
+    // Check routes for explicit kind first
+    const routeEntry = routes?.[namespace]?.[procedureName];
+    if (routeEntry) {
+        // RouteEntry can be object with kind, or legacy string (path only)
+        if (typeof routeEntry === 'object' && 'kind' in routeEntry) {
+            return routeEntry.kind === 'query';
+        }
+    }
+    // Fall back to naming convention
+    return isQueryProcedure(procedureName);
+}
 /**
  * Creates a proxy for a namespace that returns procedure proxies
  *
@@ -287,8 +463,9 @@ function createMutationProcedureProxy(namespace, procedureName, getClient) {
  *
  * @param namespace - The namespace name (e.g., 'users')
  * @param getClient - Factory function to get the client
+ * @param routes - Optional route metadata for explicit kind detection
  */
-function createNamespaceProxy(namespace, getClient) {
+function createNamespaceProxy(namespace, getClient, routes) {
     // Cache procedure proxies to avoid recreating on every access
     const procedureCache = new Map();
     return new Proxy({}, {
@@ -298,8 +475,8 @@ function createNamespaceProxy(namespace, getClient) {
             if (cached) {
                 return cached;
             }
-            // Create new procedure proxy based on naming convention
-            const procedureProxy = isQueryProcedure(procedureName)
+            // Create new procedure proxy based on routes metadata or naming convention
+            const procedureProxy = isProcedureQuery(namespace, procedureName, routes)
                 ? createQueryProcedureProxy(namespace, procedureName, getClient)
                 : createMutationProcedureProxy(namespace, procedureName, getClient);
             // Cache for future access
@@ -380,6 +557,8 @@ export function createVeloxHooks(config) {
         const { client: contextClient } = useVeloxContext();
         return config?.client ?? contextClient;
     };
+    // Extract routes for explicit kind detection
+    const routes = config?.routes;
     // Create the root proxy
     return new Proxy({}, {
         get(_target, namespace) {
@@ -388,8 +567,8 @@ export function createVeloxHooks(config) {
             if (cached) {
                 return cached;
             }
-            // Create new namespace proxy
-            const namespaceProxy = createNamespaceProxy(namespace, getClient);
+            // Create new namespace proxy with routes for kind detection
+            const namespaceProxy = createNamespaceProxy(namespace, getClient, routes);
             // Cache for future access
             namespaceCache.set(namespace, namespaceProxy);
             return namespaceProxy;

package/dist/react/proxy-types.d.ts

@@ -7,7 +7,7 @@
  * @module @veloxts/client/react/proxy-types
  */
 import type { QueryClient, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult, UseSuspenseQueryOptions, UseSuspenseQueryResult } from '@tanstack/react-query';
-import type { ClientFromRouter, ClientProcedure, ProcedureCollection, ProcedureRecord } from '../types.js';
+import type { ClientFromRouter, ClientProcedure, ProcedureCollection, ProcedureRecord, RouteMap } from '../types.js';
 import type { VeloxQueryKey } from './types.js';
 /**
  * Hook methods available for query procedures
@@ -385,6 +385,32 @@ export interface VeloxHooksConfig<TRouter = unknown> {
      * ```
      */
     client?: ClientFromRouter<TRouter>;
+    /**
+     * Optional: route metadata from backend
+     *
+     * When provided, the `kind` field in route entries overrides the naming
+     * convention heuristic for determining query vs mutation. This is useful
+     * for procedures that don't follow naming conventions.
+     *
+     * Generate this using `extractRoutes()` from `@veloxts/router`:
+     *
+     * @example
+     * ```typescript
+     * // Backend: api/index.ts
+     * import { extractRoutes } from '@veloxts/router';
+     * export const routes = extractRoutes([userProcedures, authProcedures]);
+     *
+     * // Frontend: api.ts
+     * import { createVeloxHooks } from '@veloxts/client/react';
+     * import { routes } from '../../api/src/index.js';
+     *
+     * export const api = createVeloxHooks<AppRouter>({ routes });
+     *
+     * // Now non-conventional procedures work correctly:
+     * api.health.check.useQuery({});  // Works even though 'check' is not a query prefix
+     * ```
+     */
+    routes?: RouteMap;
 }
 /**
  * Generic client type for internal use

package/dist/types.d.ts

@@ -119,11 +119,25 @@ export type ClientFromRouter<TRouter> = {
     [K in keyof TRouter]: TRouter[K] extends ProcedureCollection ? ClientFromCollection<TRouter[K]> : never;
 };
 /**
- * A single route entry with method and path
+ * A single route entry with method, path, and procedure kind
+ *
+ * The `kind` field enables explicit query/mutation type annotation,
+ * overriding the naming convention heuristic when procedures don't
+ * follow standard prefixes (get*, list*, create*, etc.).
  */
 export interface RouteEntry {
     method: HttpMethod;
     path: string;
+    /**
+     * Explicit procedure type annotation
+     *
+     * When provided, this overrides the naming convention detection:
+     * - `'query'` → enables useQuery, useSuspenseQuery, getQueryKey, etc.
+     * - `'mutation'` → enables useMutation
+     *
+     * Use when procedure names don't follow conventions (e.g., `fetchUsers`, `process`)
+     */
+    kind?: 'query' | 'mutation';
 }
 /**
  * Maps procedure names to their REST endpoint configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/client",
-  "version": "0.6.64",
+  "version": "0.6.65",
   "description": "Type-safe frontend API client for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",