chore: update changelog, remove unnecessary comments

Author: kyleamazza-fq

CHANGELOG.md

@@ -9,37 +9,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- New query options exports for better React Query v5 compatibility
-  - `{methodName}QueryOptions` functions for regular queries
-  - `{methodName}MutationOptions` functions for mutations
-  - `{methodName}InfiniteQueryOptions` functions for infinite queries
-- Service getter functions (`get{ServiceName}Service`) for use in non-React contexts
-- Query key builder utility for type-safe cache invalidation and queries
+- **New query/mutation/infinite options exports** for React Query v5 compatibility
+  - `{methodName}QueryOptions` functions that return `queryOptions` for use with `useQuery`/`useSuspenseQuery`
+  - `{methodName}MutationOptions` functions that return `mutationOptions` for use with `useMutation`
+  - `{methodName}InfiniteQueryOptions` functions that return `infiniteQueryOptions` for use with `useInfiniteQuery`/`useSuspenseInfiniteQuery`
+  - These exports enable better tree-shaking and composability
+  - Full TypeScript support with proper generic types
+- **Service getter functions** for non-React contexts
+  - `get{ServiceName}Service()` functions that return service instances without React hooks
+  - Enables use of API clients outside React components (e.g., in server-side code, scripts, tests)
+- **Query key builder utility** (`query-key-builder.ts`) for type-safe cache operations
+  - `matchQueryKey()` function for building type-safe query keys
+  - `QueryKeyMap`, `ServiceKeys`, `OperationKeys`, and `OperationParams` types for full type safety
+  - Enables precise cache invalidation and query matching
 
 ### Changed
 
-- Generated hooks now use simplified `@deprecated` JSDoc tags instead of custom deprecation blocks
-- Query keys now use a simpler static structure based on interface and method names
-  - Changed from URL-based resource keys to pattern: `['interface', 'method', params || {}]`
-  - Interface names in query keys now use camelCase for consistency with JavaScript conventions
-  - Removed complex URL path parsing logic for cleaner, more predictable keys
-- Refactored internal code generation to use helper functions instead of NameFactory class
+- **Query key structure completely redesigned** for simplicity and consistency
+  - Changed from complex URL-based patterns (e.g., `` `/widgets/${id}` ``) to simple arrays: `['serviceName', 'methodName', params || {}, metadata?]`
+  - Infinite queries now differentiated by metadata (`{infinite: true}`) instead of key structure
+  - All queries for an interface can now be invalidated with just `['interfaceName']`
+  - Removed `buildResourceKey()`, `isCacheParam()`, and complex path parsing logic
+- **Mutations now invalidate at the interface level** instead of specific resource paths
+  - Simplified from invalidating multiple specific query keys to just `queryClient.invalidateQueries({ queryKey: ['interfaceName'] })`
+  - More predictable cache invalidation behavior
+- **Refactored naming system** from class-based to function-based
+  - Replaced `NameFactory` class with standalone functions in `name-helpers.ts`
+  - Functions: `buildHookName()`, `buildQueryOptionsName()`, `buildMutationOptionsName()`, `buildInfiniteQueryOptionsName()`, `buildServiceName()`, `buildServiceHookName()`, `buildServiceGetterName()`, `buildContextName()`, `buildProviderName()`
+  - `buildHookName()` now requires `service` parameter for proper context
+- **Context file enhanced** with new capabilities
+  - Added `currentContext` variable for non-hook access to context
+  - Service getter functions exported alongside hooks for flexibility
+  - Interfaces sorted alphabetically for consistent output
+  - Props interface now extends options type with optional fetch
+- **Error handling improved** with `QueryError` type
+  - Changed from `CompositeError` throws to structured `QueryError<Error[]>` type
+  - Enables better error discrimination in error handlers
 
 ### Fixed
 
-- Parameter names with special characters (e.g., hyphens) are now properly handled in query keys
-  - All parameter access now uses bracket notation for consistency
-  - Object keys in query key generation are properly quoted
-- Fixed duplicate function declarations for methods not starting with "get"
-  - Suspense hooks now correctly generate with `useSuspense` prefix for all method types
-  - Prevents TypeScript errors from duplicate function names
-- Fixed invalid TypeScript syntax in query keys where optional parameter syntax (`params?`) was incorrectly used in runtime expressions
-- Fixed infinite query key typo (`inifinite` → `infinite`)
-- Build configuration now properly excludes snapshot directory from TypeScript compilation
-- Added README.md to .prettierignore to prevent formatter hanging
+- **TypeScript compilation errors** in generated code
+  - Fixed `isRequired()` parameter access in `query-key-builder.ts` (accessing `p.value` instead of `p`)
+  - Removed unused `includeRelayParams` parameter that was being passed but ignored
+  - Fixed duplicate imports and missing function exports
+- **Test and snapshot generation issues**
+  - Updated test utilities to use `@basketry/ir` parser instead of inline JSON parsing
+  - Fixed snapshot file generation that was silently failing
+  - Cleaned up debug `console.log` statements from test utilities
 
 ### Deprecated
 
-- Legacy hook exports (`use{MethodName}`, `useSuspense{MethodName}`, etc.) are now deprecated
-  - These hooks will be removed in a future major version
-  - Users should migrate to the new query options pattern with React Query's built-in hooks
+- **All wrapped hook exports** are now marked as `@deprecated`
+  - `use{MethodName}()` - query hooks
+  - `useSuspense{MethodName}()` - suspense query hooks  
+  - `useInfinite{MethodName}()` - infinite query hooks
+  - `useSuspenseInfinite{MethodName}()` - suspense infinite query hooks
+  - Hooks remain functional for backward compatibility but display deprecation warnings
+  - Each deprecation notice includes migration guidance to the new pattern
+  - Will be removed in the next major version (v1.0.0)
+
+### Internal
+
+- Added `xxxx()` method in `hook-file.ts` that needs renaming (analyzes return types for select function generation)
+- Removed complex relay parameter handling from query key generation
+- Simplified infinite query differentiation using metadata instead of key manipulation

src/hook-file.ts

@@ -128,7 +128,7 @@ export class HookFile extends ModuleBuilder {
 
         const optionsExpression = `options?: Omit<${UndefinedInitialDataOptions()}<${genericTypes}>,'queryKey' | 'queryFn' | 'select'>`;
 
-        yield* buildDescription(method.description, true); // Mark as deprecated
+        yield* buildDescription(method.description, true);
         yield `/** @deprecated Use ${queryOptionsName} with useQuery instead */`;
         yield `export function ${name}(${[
           paramsExpression,
@@ -138,7 +138,7 @@ export class HookFile extends ModuleBuilder {
         yield `  return ${useQuery()}({...defaultOptions, ...options});`;
         yield `}`;
         yield '';
-        yield* buildDescription(method.description, true); // Mark as deprecated
+        yield* buildDescription(method.description, true);
         yield `/** @deprecated Use ${queryOptionsName} with useSuspenseQuery instead */`;
         yield `export function ${suspenseName}(${[
           paramsExpression,
@@ -159,7 +159,7 @@ export class HookFile extends ModuleBuilder {
 
         const optionsExpression = `options?: Omit<${mutationOptions()}, 'mutationFn'>`;
 
-        yield* buildDescription(method.description, true); // Mark as deprecated
+        yield* buildDescription(method.description, true);
         yield `/** @deprecated Use ${buildMutationOptionsName(
           method,
         )} with useMutation instead */`;
@@ -178,7 +178,7 @@ export class HookFile extends ModuleBuilder {
         yield `        throw handled`;
         yield `      }`;
 
-        // Invalidate all queries for this interface using the simpler pattern
+        // Invalidate all queries for this interface
         const interfaceName = camel(this.int.name.value);
         yield `      queryClient.invalidateQueries({ queryKey: ['${interfaceName}'] });`;
         if (dataProp && !isRequired(dataProp.value)) {
@@ -222,15 +222,14 @@ export class HookFile extends ModuleBuilder {
         yield `      return res;`;
         yield `    },`;
         yield* this.buildInfiniteSelectFn(method);
-        yield `    initialPageParam: ${getInitialPageParam()}(params${
-          q ? '?? {}' : ''
-        }),`;
+        yield `    initialPageParam: ${getInitialPageParam()}(params${q ? '?? {}' : ''
+          }),`;
         yield `    ${getNextPageParam()},`;
         yield `    ${getPreviousPageParam()},`;
         yield `  };`;
         yield `}`;
 
-        yield* buildDescription(method.description, true); // Mark as deprecated
+        yield* buildDescription(method.description, true);
         yield `/** @deprecated Use ${buildInfiniteQueryOptionsName(
           method,
         )} with useInfiniteQuery instead */`;
@@ -242,7 +241,7 @@ export class HookFile extends ModuleBuilder {
         yield `  return ${useInfiniteQuery()}(options);`;
         yield `}`;
 
-        yield* buildDescription(method.description, true); // Mark as deprecated
+        yield* buildDescription(method.description, true);
         yield `/** @deprecated Use ${buildInfiniteQueryOptionsName(
           method,
         )} with useSuspenseInfiniteQuery instead */`;
@@ -346,9 +345,8 @@ export class HookFile extends ModuleBuilder {
 
     yield `    select: (data: ${InfiniteData()}<${type(
       returnTypeName,
-    )}, string | undefined>) => data.pages.flatMap((page) => page.data${
-      optional ? ' ?? []' : ''
-    }),`;
+    )}, string | undefined>) => data.pages.flatMap((page) => page.data${optional ? ' ?? []' : ''
+      }),`;
   }
 
   private buildQueryOptions(method: Method): () => string {
@@ -367,13 +365,10 @@ export class HookFile extends ModuleBuilder {
     const { returnTypeName, dataTypeName, array, skipSelect } =
       this.xxxx(method);
 
-    // This is the type returned by the queryFn
     genericTypes.push(type(returnTypeName));
 
-    // This is the type of the error returned by the hook if the query fails
     genericTypes.push(`${QueryError()}<${type('Error')}[]>`);
 
-    // This is the type returned by the select function (if it exists)
     if (!skipSelect) {
       genericTypes.push(`${type(dataTypeName)}${array}`);
     }
@@ -467,21 +462,21 @@ export class HookFile extends ModuleBuilder {
     const dataProp =
       returnType.kind === 'Type'
         ? returnType.properties.find(
-            (p) =>
-              p.name.value.toLocaleLowerCase() === 'data' ||
-              p.name.value.toLocaleLowerCase() === 'value' ||
-              p.name.value.toLocaleLowerCase() === 'values',
-          )
+          (p) =>
+            p.name.value.toLocaleLowerCase() === 'data' ||
+            p.name.value.toLocaleLowerCase() === 'value' ||
+            p.name.value.toLocaleLowerCase() === 'values',
+        )
         : undefined;
     if (!dataProp) return { envelope: undefined, returnType };
 
     const errorProp =
       returnType.kind === 'Type'
         ? returnType.properties.find(
-            (p) =>
-              p.name.value.toLocaleLowerCase() === 'error' ||
-              p.name.value.toLocaleLowerCase() === 'errors',
-          )
+          (p) =>
+            p.name.value.toLocaleLowerCase() === 'error' ||
+            p.name.value.toLocaleLowerCase() === 'errors',
+        )
         : undefined;
     if (!errorProp) return { envelope: undefined, returnType };
 
@@ -671,9 +666,8 @@ export class HookFile extends ModuleBuilder {
     yield `      return res;`;
     yield `    },`;
     yield* this.buildInfiniteSelectFn(method);
-    yield `    initialPageParam: ${getInitialPageParam()}(params${
-      q ? '?? {}' : ''
-    }),`;
+    yield `    initialPageParam: ${getInitialPageParam()}(params${q ? '?? {}' : ''
+      }),`;
     yield `    ${getNextPageParam()},`;
     yield `    ${getPreviousPageParam()},`;
     yield `  });`;

src/name-helpers.ts

@@ -51,8 +51,7 @@ export function buildHookName(
   ) {
     // Query Hook
     return camel(
-      `use_${options?.suspense ? 'suspense_' : ''}${
-        options?.infinite ? 'infinite_' : ''
+      `use_${options?.suspense ? 'suspense_' : ''}${options?.infinite ? 'infinite_' : ''
       }${name.slice(3)}`,
     );
   }

src/query-key-builder.ts

@@ -23,15 +23,12 @@ export class QueryKeyBuilder extends ModuleBuilder {
   protected readonly importBuilders = [this.types];
 
   *body(): Iterable<string> {
-    // Generate QueryKeyMap interface
     yield* this.generateQueryKeyMap();
     yield '';
 
-    // Generate type extraction helpers
     yield* this.generateTypeHelpers();
     yield '';
 
-    // Generate matchQueryKey function
     yield* this.generateMatchQueryKeyFunction();
   }
 
@@ -59,21 +56,18 @@ export class QueryKeyBuilder extends ModuleBuilder {
   }
 
   private *generateTypeHelpers(): Iterable<string> {
-    // ServiceKeys type
     yield '/**';
     yield ' * Extract all service names from QueryKeyMap';
     yield ' */';
     yield 'export type ServiceKeys = keyof QueryKeyMap;';
     yield '';
 
-    // OperationKeys type
     yield '/**';
     yield ' * Extract operation names for a given service';
     yield ' */';
     yield 'export type OperationKeys<S extends ServiceKeys> = keyof QueryKeyMap[S];';
     yield '';
 
-    // OperationParams type
     yield '/**';
     yield ' * Extract parameter type for a given service and operation';
     yield ' */';