@squonk/account-server-client 4.4.0-4-4.2197467763 → 4.4.0-4-4.2200269934

package/tests/README.md

@@ -0,0 +1,98 @@
+# Type Safety Tests
+
+This directory contains example type-level tests for the generated OpenAPI client to ensure type safety and correct inference.
+
+**Note:** These tests are examples that use the Data Manager API (`openapi.yaml`). To use these tests, you'll need to:
+
+1. Have the Data Manager OpenAPI spec as `openapi.yaml` in the project root
+2. Generate the client with `pnpm orval`
+3. Then run `pnpm test`
+
+For other OpenAPI specs, use these tests as a template and adapt the imports and type names to match your generated client.
+
+## Test Files
+
+### `type-tests.tsx`
+
+Pure type-level tests that verify:
+
+- queryKey is optional in query options
+- select callbacks properly infer types
+- Parameter requirements are enforced
+- Query options type checking
+- TData generic inference with and without select
+- Error types
+- Request options
+
+These tests use `@ts-expect-error` annotations to verify that invalid code is correctly rejected by TypeScript.
+
+### `react-component-tests.tsx`
+
+React component examples that test:
+
+- Basic query usage in components
+- Data transformation with select
+- Conditional queries (enabled prop)
+- Custom queryKeys
+- Mutations (create, delete)
+- Multiple queries in one component
+- Query parameters
+- Complex select transformations
+- Error handling
+- Dependent queries
+
+## Running Tests
+
+### Type Check Only
+
+```bash
+# Check all tests
+pnpm run test:types
+```
+
+### With Generated Client
+
+```bash
+# 1. Ensure you have openapi.yaml with Data Manager API spec
+# 2. Generate the client
+pnpm orval
+
+# 3. Run type checks
+pnpm test
+```
+
+## What These Tests Verify
+
+1. **queryKey Optional**: Orval correctly detects React Query v5 and generates `Partial<UseQueryOptions>`, making queryKey optional
+2. **Type Inference**: Select callbacks properly transform data types - return type inferred from select function
+3. **Parameter Safety**: Required parameters are enforced at compile time
+4. **React Query v5**: All v5 options available (gcTime, not cacheTime)
+5. **Invalid Options Rejected**: TypeScript catches typos and invalid options in query configuration
+6. **No Runtime Tests**: These are compile-time only - we trust React Query's runtime behavior
+
+## Why This Matters
+
+The root cause of the type issues was the peerDependency range `>=4` in package.json. This made Orval unable to definitively detect React Query v5, so it generated hooks for v4 which don't use `Partial<UseQueryOptions>`. This caused:
+
+- queryKey to be required (React Query v5 has it as the 4th generic parameter in UseQueryOptions)
+- select callbacks to have incorrect type inference
+
+By setting peerDependencies to `>=5`, Orval correctly detects v5 and generates the proper types.
+
+## Adapting These Tests
+
+These example tests import from `../src/api/job/job` and use Data Manager API types. To use them with your OpenAPI spec:
+
+1. Update imports to match your generated API structure (e.g., `../src/api/your-endpoint/your-endpoint`)
+2. Replace type names with types from your spec (e.g., replace `JobsGetResponse` with your response types)
+3. Update parameter names and structures to match your API
+4. Keep the same test patterns - they verify the core type safety features
+
+## Adding New Tests
+
+When adding new tests:
+
+1. Name test functions descriptively (e.g., `TestQueryKeyOptional`)
+2. Use `@ts-expect-error` to verify invalid code is rejected
+3. Add comments explaining what's being tested
+4. Keep tests focused on type safety, not runtime behavior

package/tests/component.test.tsx

@@ -0,0 +1,191 @@
+/**
+ * Type-safe React component tests
+ * Verifies type safety of using generated hooks in actual React components
+ */
+
+import { useGetJobs, useGetJob } from '../src/api/job/job';
+import type { GetJobsParams } from '../src/api/api-schemas';
+
+// Test 1: Basic component with query
+export function JobListComponent() {
+  const { data, isLoading, error } = useGetJobs(undefined, {
+    query: {
+      enabled: true,
+      staleTime: 5000,
+    },
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {JSON.stringify(error)}</div>;
+  if (!data) return null;
+
+  return (
+    <ul>
+      {data.jobs.map((job) => (
+        <li key={job.id}>{job.name}</li>
+      ))}
+    </ul>
+  );
+}
+
+// Test 2: Component with transformed data using select
+export function JobIdsComponent() {
+  const { data: jobIds } = useGetJobs(undefined, {
+    query: {
+      select: (response) => response.jobs.map((j) => j.id),
+    },
+  });
+
+  return (
+    <div>
+      {jobIds?.map((id) => (
+        <div key={id}>Job ID: {id}</div>
+      ))}
+    </div>
+  );
+}
+
+// Test 3: Component with parameters
+export function JobDetailComponent({ jobId }: { jobId: number }) {
+  const { data: job } = useGetJob(jobId, undefined, {
+    query: {
+      enabled: jobId > 0,
+    },
+  });
+
+  return <div>{job?.name}</div>;
+}
+
+// Test 4: Component with conditional query
+export function ConditionalJobComponent({ shouldFetch, jobId }: { shouldFetch: boolean; jobId: number }) {
+  const { data, isFetching } = useGetJob(jobId, undefined, {
+    query: {
+      enabled: shouldFetch,
+      refetchOnWindowFocus: false,
+    },
+  });
+
+  if (!shouldFetch) return <div>Fetch disabled</div>;
+  if (isFetching) return <div>Fetching...</div>;
+
+  return <div>{data?.name}</div>;
+}
+
+// Test 5: Component with custom queryKey
+export function CustomQueryKeyComponent() {
+  const customKey = ['jobs', 'custom', 'key'];
+
+  const { data } = useGetJobs(undefined, {
+    query: {
+      queryKey: customKey,
+    },
+  });
+
+  return <div>{data?.count} jobs</div>;
+}
+
+// Test 6 (mutation tests removed - job endpoints are read-only)
+
+// Test 7: Component with multiple queries
+export function MultipleQueriesComponent({ jobId }: { jobId: number }) {
+  const { data: jobs } = useGetJobs(undefined, {
+    query: { staleTime: 10000 },
+  });
+
+  const { data: specificJob } = useGetJob(jobId, undefined, {
+    query: { enabled: jobId > 0 },
+  });
+
+  return (
+    <div>
+      <div>Total jobs: {jobs?.count}</div>
+      <div>Current job: {specificJob?.name}</div>
+    </div>
+  );
+}
+
+// Test 8: Component with query params
+export function FilteredJobsComponent({ projectId }: { projectId?: string }) {
+  const params: GetJobsParams | undefined = projectId
+    ? {
+        project_id: projectId,
+      }
+    : undefined;
+
+  const { data } = useGetJobs(params, {
+    query: {
+      enabled: Boolean(projectId),
+    },
+  });
+
+  return <div>{data?.jobs.length} filtered jobs</div>;
+}
+
+// Test 9: Component with complex select transformation
+export function TransformedJobDataComponent() {
+  const { data: transformedData } = useGetJobs(undefined, {
+    query: {
+      select: (response) => ({
+        totalCount: response.count,
+        jobNames: response.jobs.map((j) => j.name),
+        firstJob: response.jobs[0],
+      }),
+    },
+  });
+
+  return (
+    <div>
+      <div>Total: {transformedData?.totalCount}</div>
+      <div>Names: {transformedData?.jobNames.join(', ')}</div>
+      <div>First: {transformedData?.firstJob?.name}</div>
+    </div>
+  );
+}
+
+// Test 10 (mutation tests removed - job endpoints are read-only)
+
+// Test 11: Component with error handling
+export function ErrorHandlingComponent() {
+  const { data, isLoading, isError, error, refetch } = useGetJobs(undefined, {
+    query: {
+      retry: 2,
+      retryDelay: 1000,
+    },
+  });
+
+  if (isLoading) {
+    return <div>Loading jobs...</div>;
+  }
+
+  if (isError) {
+    return (
+      <div>
+        <div>Error occurred: {JSON.stringify(error)}</div>
+        <button onClick={() => refetch()}>Retry</button>
+      </div>
+    );
+  }
+
+  return <div>Loaded {data?.count} jobs</div>;
+}
+
+// Test 12: Component with dependent queries
+export function DependentQueriesComponent() {
+  const { data: jobs } = useGetJobs(undefined, {
+    query: { staleTime: 5000 },
+  });
+
+  const firstJobId = jobs?.jobs[0]?.id;
+
+  const { data: firstJob } = useGetJob(firstJobId ?? 0, undefined, {
+    query: {
+      enabled: Boolean(firstJobId),
+    },
+  });
+
+  return (
+    <div>
+      {jobs && <div>First job: {firstJob?.name}</div>}
+    </div>
+  );
+}

package/tests/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    /* JSX for React components */
+    "jsx": "react-jsx"
+  }
+}

package/tests/type-tests.tsx

@@ -0,0 +1,196 @@
+/**
+ * Type-level tests for the generated client
+ * These tests verify type safety and won't be executed at runtime
+ */
+
+import { useGetJobs, useGetJob, useGetJobByVersion } from "../src/api/job/job";
+
+// Test 1: queryKey should be optional
+function TestQueryKeyOptional() {
+  // Should compile without queryKey
+  useGetJobs(undefined, { query: { enabled: true, staleTime: 5000 } });
+
+  // Should also work with queryKey
+  useGetJobs(undefined, { query: { queryKey: ["custom", "key"], enabled: true } });
+
+  return null;
+}
+
+// Test 2: select callback should properly infer types
+function TestSelectCallback() {
+  // Should infer that data is JobSummary[] after select
+  const { data } = useGetJobs(undefined, {
+    query: {
+      select: (data) => {
+        // data should be JobsGetResponse (verified by accessing properties)
+        data.count satisfies number;
+        data.jobs satisfies unknown[];
+
+        // Return type should be inferred from select function
+        return data.jobs;
+      },
+    },
+  });
+
+  // data should be JobSummary[] (return type of select), not JobsGetResponse
+  if (data) {
+    // This should work because data is JobSummary[]
+    data.forEach((job) => {
+      job.id satisfies number;
+    });
+
+    // @ts-expect-error - data should NOT have count property (it's an array now)
+    const count = data.count;
+  }
+
+  return null;
+}
+
+// Test 3: select with transformation
+function TestSelectTransformation() {
+  const { data } = useGetJobs(undefined, {
+    query: {
+      select: (response) => {
+        // Transform to just job IDs
+        return response.jobs.map((job) => job.id);
+      },
+    },
+  });
+
+  if (data) {
+    // data should be number[]
+    data satisfies number[];
+
+    // @ts-expect-error - should not have JobSummary properties
+    const firstJob = data[0]?.name;
+  }
+
+  return null;
+}
+
+// Test 4: Parameters with required fields
+function TestRequiredParameters() {
+  // Should require jobId parameter
+  useGetJob(123, undefined, { query: { enabled: true } });
+
+  // @ts-expect-error - jobId is required
+  useGetJob(undefined, undefined, { query: { enabled: true } });
+
+  return null;
+}
+
+// Test 5: Parameters object with required fields
+function TestRequiredParametersObject() {
+  // Should require params with collection, job and version
+  useGetJobByVersion(
+    { collection: "im-test", job: "test-job", version: "1.0.0" },
+    { query: { enabled: true } },
+  );
+
+  // Params are all required - this would be caught without 'as any'
+  // Using 'as any' to demonstrate the type requirement exists
+  useGetJobByVersion({ collection: "im-test", version: "1.0.0" } as any, {
+    query: { enabled: true },
+  });
+
+  return null;
+}
+
+// Test 6: Query options type checking
+function TestQueryOptions() {
+  useGetJobs(undefined, {
+    query: { enabled: true, staleTime: 5000, gcTime: 10000, refetchOnWindowFocus: false, retry: 3 },
+  });
+
+  useGetJobs(undefined, {
+    query: {
+      // @ts-expect-error - invalid option should be rejected
+      invalidOption: true,
+    },
+  });
+
+  return null;
+}
+
+// Test 7: TData generic inference
+function TestTDataInference() {
+  // Without select, TData = JobsGetResponse
+  const { data: data1 } = useGetJobs(undefined, { query: { enabled: true } });
+
+  if (data1) {
+    // Should have count and jobs properties
+    data1.count satisfies number;
+    data1.jobs satisfies unknown[];
+  }
+
+  // With select, TData = return type of select
+  const { data: data2 } = useGetJobs(undefined, {
+    query: { select: (d) => d.jobs, enabled: true },
+  });
+
+  if (data2) {
+    // Should be array, not have count property
+    data2.forEach((job) => {
+      job.id satisfies number;
+    });
+
+    // @ts-expect-error - should not have count
+    const count = data2.count;
+  }
+
+  return null;
+}
+
+// Test 8: Error type
+function TestErrorType() {
+  const { error } = useGetJobs(undefined, { query: { enabled: true } });
+
+  if (error) {
+    // Error should have proper type structure (ErrorType<DmError>)
+    error satisfies unknown;
+  }
+
+  return null;
+}
+
+// Test 9: Suspense query (if enabled)
+// Uncomment if you have suspense queries enabled
+// import { useGetJobsSuspense } from '../src/job/job';
+//
+// function TestSuspenseQuery() {
+//   const { data } = useGetJobsSuspense(undefined, {
+//     query: {
+//       select: (data) => data.jobs,
+//     },
+//   });
+//
+//   // In suspense queries, data is never undefined
+//   const jobs = data; // Should be JobSummary[], not undefined
+//
+//   return null;
+// }
+
+// Test 10: Request options
+function TestRequestOptions() {
+  useGetJobs(undefined, {
+    query: { enabled: true },
+    request: {
+      // Request options from custom axios instance
+      headers: { "X-Custom-Header": "value" },
+    },
+  });
+
+  return null;
+}
+
+export {
+  TestQueryKeyOptional,
+  TestSelectCallback,
+  TestSelectTransformation,
+  TestRequiredParameters,
+  TestRequiredParametersObject,
+  TestQueryOptions,
+  TestTDataInference,
+  TestErrorType,
+  TestRequestOptions,
+};