@carlonicora/nextjs-jsonapi 1.15.0 → 1.17.0

package/dist/testing/index.d.mts

@@ -0,0 +1,338 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React__default, { ReactElement } from 'react';
+import { J as JsonApiConfig } from '../JsonApiContext-Bsm_Q2oe.mjs';
+import { a as ApiRequestDataTypeInterface, A as ApiDataInterface } from '../ApiRequestDataTypeInterface-DIEOFn9s.mjs';
+import { A as ApiResponseInterface } from '../ApiResponseInterface-Dqvu09tz.mjs';
+import { Mock } from 'vitest';
+import { RenderOptions, RenderResult } from '@testing-library/react';
+export { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+export { userEvent } from '@testing-library/user-event';
+
+interface MockJsonApiProviderProps {
+    children: React__default.ReactNode;
+    config?: Partial<JsonApiConfig>;
+}
+declare const defaultMockConfig: JsonApiConfig;
+/**
+ * A test-friendly provider that wraps components with mock JSON:API context.
+ *
+ * @example
+ * ```tsx
+ * import { MockJsonApiProvider } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * render(
+ *   <MockJsonApiProvider>
+ *     <MyComponent />
+ *   </MockJsonApiProvider>
+ * );
+ * ```
+ *
+ * @example With custom config
+ * ```tsx
+ * render(
+ *   <MockJsonApiProvider config={{ apiUrl: 'https://custom.api.com' }}>
+ *     <MyComponent />
+ *   </MockJsonApiProvider>
+ * );
+ * ```
+ */
+declare function MockJsonApiProvider({ children, config }: MockJsonApiProviderProps): react_jsx_runtime.JSX.Element;
+
+interface CreateMockModuleOptions {
+    name: string;
+    cache?: string;
+    inclusions?: ApiRequestDataTypeInterface["inclusions"];
+}
+/**
+ * Creates a mock module definition for testing.
+ *
+ * @example
+ * ```ts
+ * import { createMockModule } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const mockArticleModule = createMockModule({ name: 'articles' });
+ * ```
+ */
+declare function createMockModule(options: CreateMockModuleOptions): ApiRequestDataTypeInterface;
+
+interface CreateMockResponseOptions {
+    data?: ApiDataInterface | ApiDataInterface[] | null;
+    ok?: boolean;
+    response?: number;
+    error?: string;
+    meta?: Record<string, any>;
+    self?: string;
+    next?: string;
+    prev?: string;
+}
+/**
+ * Creates a mock API response for testing.
+ *
+ * @example
+ * ```ts
+ * import { createMockResponse, createMockApiData } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const mockData = createMockApiData({ type: 'articles', id: '1' });
+ * const response = createMockResponse({ data: mockData, ok: true });
+ * ```
+ *
+ * @example With pagination
+ * ```ts
+ * const response = createMockResponse({
+ *   data: [mockData],
+ *   ok: true,
+ *   next: '/articles?page=2',
+ *   prev: '/articles?page=0',
+ * });
+ * ```
+ */
+declare function createMockResponse(options?: CreateMockResponseOptions): ApiResponseInterface;
+/**
+ * Creates a mock error response for testing error scenarios.
+ *
+ * @example
+ * ```ts
+ * import { createMockErrorResponse } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const errorResponse = createMockErrorResponse(404, 'Not Found');
+ * ```
+ */
+declare function createMockErrorResponse(statusCode: number, errorMessage: string): ApiResponseInterface;
+
+type MockApiMethod = Mock<(...args: any[]) => Promise<ApiResponseInterface>>;
+interface MockService {
+    get: MockApiMethod;
+    post: MockApiMethod;
+    put: MockApiMethod;
+    patch: MockApiMethod;
+    delete: MockApiMethod;
+}
+interface CreateMockServiceOptions {
+    defaultResponse?: ApiResponseInterface;
+}
+/**
+ * Creates a mock service with Vitest mock functions for all HTTP methods.
+ *
+ * @example
+ * ```ts
+ * import { createMockService, createMockResponse } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const mockService = createMockService();
+ * mockService.get.mockResolvedValue(createMockResponse({ data: mockData }));
+ *
+ * // Use in test
+ * expect(mockService.get).toHaveBeenCalled();
+ * ```
+ *
+ * @example With default response
+ * ```ts
+ * const mockService = createMockService({
+ *   defaultResponse: createMockResponse({ ok: true, data: [] }),
+ * });
+ * ```
+ */
+declare function createMockService(options?: CreateMockServiceOptions): MockService;
+/**
+ * Creates a mock service that returns errors for all methods.
+ *
+ * @example
+ * ```ts
+ * import { createMockErrorService } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const errorService = createMockErrorService(500, 'Internal Server Error');
+ * ```
+ */
+declare function createMockErrorService(statusCode?: number, errorMessage?: string): MockService;
+
+interface CreateMockApiDataOptions {
+    type: string;
+    id?: string;
+    attributes?: Record<string, any>;
+    relationships?: Record<string, any>;
+    included?: any[];
+    createdAt?: Date;
+    updatedAt?: Date;
+    self?: string;
+}
+/**
+ * Creates a mock ApiDataInterface object for testing.
+ *
+ * @example
+ * ```ts
+ * import { createMockApiData } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const mockArticle = createMockApiData({
+ *   type: 'articles',
+ *   id: '1',
+ *   attributes: { title: 'Test Article', body: 'Content here' },
+ * });
+ * ```
+ *
+ * @example With relationships
+ * ```ts
+ * const mockArticle = createMockApiData({
+ *   type: 'articles',
+ *   id: '1',
+ *   attributes: { title: 'Test' },
+ *   relationships: {
+ *     author: { data: { type: 'users', id: '42' } },
+ *   },
+ * });
+ * ```
+ */
+declare function createMockApiData(options: CreateMockApiDataOptions): ApiDataInterface;
+/**
+ * Creates an array of mock ApiDataInterface objects.
+ *
+ * @example
+ * ```ts
+ * import { createMockApiDataList } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const mockArticles = createMockApiDataList('articles', 5, (index) => ({
+ *   title: `Article ${index + 1}`,
+ * }));
+ * ```
+ */
+declare function createMockApiDataList(type: string, count: number, attributesFactory?: (index: number) => Record<string, any>): ApiDataInterface[];
+
+interface JsonApiResponse {
+    data?: {
+        type?: string;
+        id?: string;
+        attributes?: Record<string, any>;
+        relationships?: Record<string, any>;
+    } | Array<{
+        type?: string;
+        id?: string;
+        attributes?: Record<string, any>;
+        relationships?: Record<string, any>;
+    }>;
+}
+/**
+ * Custom Vitest matchers for JSON:API assertions.
+ *
+ * @example
+ * ```ts
+ * import { jsonApiMatchers } from '@carlonicora/nextjs-jsonapi/testing';
+ * import { expect } from 'vitest';
+ *
+ * expect.extend(jsonApiMatchers);
+ *
+ * // Then use in tests:
+ * expect(response).toBeValidJsonApi();
+ * expect(response).toHaveJsonApiType('articles');
+ * expect(response).toHaveJsonApiAttribute('title', 'My Article');
+ * expect(response).toHaveJsonApiRelationship('author');
+ * ```
+ */
+declare const jsonApiMatchers: {
+    /**
+     * Asserts that the response has a valid JSON:API structure with type and id.
+     */
+    toBeValidJsonApi(received: JsonApiResponse): {
+        pass: boolean;
+        message: () => string;
+    };
+    /**
+     * Asserts that the response data has the expected JSON:API type.
+     */
+    toHaveJsonApiType(received: JsonApiResponse, expectedType: string): {
+        pass: boolean;
+        message: () => string;
+    };
+    /**
+     * Asserts that the response data has an attribute with the expected value.
+     */
+    toHaveJsonApiAttribute(received: JsonApiResponse, attributeName: string, expectedValue?: any): {
+        pass: boolean;
+        message: () => string;
+    };
+    /**
+     * Asserts that the response data has the specified relationship.
+     */
+    toHaveJsonApiRelationship(received: JsonApiResponse, relationshipName: string): {
+        pass: boolean;
+        message: () => string;
+    };
+    /**
+     * Asserts that the response data array has the expected length.
+     */
+    toHaveJsonApiLength(received: JsonApiResponse, expectedLength: number): {
+        pass: boolean;
+        message: () => string;
+    };
+};
+declare module "vitest" {
+    interface Assertion<T = any> {
+        toBeValidJsonApi(): T;
+        toHaveJsonApiType(expectedType: string): T;
+        toHaveJsonApiAttribute(attributeName: string, expectedValue?: any): T;
+        toHaveJsonApiRelationship(relationshipName: string): T;
+        toHaveJsonApiLength(expectedLength: number): T;
+    }
+    interface AsymmetricMatchersContaining {
+        toBeValidJsonApi(): any;
+        toHaveJsonApiType(expectedType: string): any;
+        toHaveJsonApiAttribute(attributeName: string, expectedValue?: any): any;
+        toHaveJsonApiRelationship(relationshipName: string): any;
+        toHaveJsonApiLength(expectedLength: number): any;
+    }
+}
+/**
+ * Extends Vitest's expect with JSON:API matchers.
+ * Call this in your test setup file.
+ *
+ * @example
+ * ```ts
+ * // vitest.setup.ts
+ * import { extendExpectWithJsonApiMatchers } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * extendExpectWithJsonApiMatchers();
+ * ```
+ */
+declare function extendExpectWithJsonApiMatchers(): void;
+
+interface RenderWithProvidersOptions extends Omit<RenderOptions, "wrapper"> {
+    /**
+     * Custom JSON:API configuration to pass to the mock provider.
+     */
+    jsonApiConfig?: Partial<JsonApiConfig>;
+    /**
+     * Additional wrapper component to wrap around the providers.
+     */
+    wrapper?: React__default.ComponentType<{
+        children: React__default.ReactNode;
+    }>;
+}
+/**
+ * Renders a component wrapped with all necessary providers for testing.
+ *
+ * @example
+ * ```tsx
+ * import { renderWithProviders } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const { getByText } = renderWithProviders(<MyComponent />);
+ * expect(getByText('Hello')).toBeInTheDocument();
+ * ```
+ *
+ * @example With custom config
+ * ```tsx
+ * const { getByText } = renderWithProviders(<MyComponent />, {
+ *   jsonApiConfig: { apiUrl: 'https://custom.api.com' },
+ * });
+ * ```
+ *
+ * @example With additional wrapper
+ * ```tsx
+ * const CustomWrapper = ({ children }) => (
+ *   <ThemeProvider>{children}</ThemeProvider>
+ * );
+ *
+ * const { getByText } = renderWithProviders(<MyComponent />, {
+ *   wrapper: CustomWrapper,
+ * });
+ * ```
+ */
+declare function renderWithProviders(ui: ReactElement, options?: RenderWithProvidersOptions): RenderResult;
+
+export { type CreateMockApiDataOptions, type CreateMockModuleOptions, type CreateMockResponseOptions, type CreateMockServiceOptions, type MockApiMethod, MockJsonApiProvider, type MockJsonApiProviderProps, type MockService, type RenderWithProvidersOptions, createMockApiData, createMockApiDataList, createMockErrorResponse, createMockErrorService, createMockModule, createMockResponse, createMockService, defaultMockConfig, extendExpectWithJsonApiMatchers, jsonApiMatchers, renderWithProviders };

package/dist/testing/index.d.ts

@@ -0,0 +1,338 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React__default, { ReactElement } from 'react';
+import { J as JsonApiConfig } from '../JsonApiContext-Bsm_Q2oe.js';
+import { a as ApiRequestDataTypeInterface, A as ApiDataInterface } from '../ApiRequestDataTypeInterface-DIEOFn9s.js';
+import { A as ApiResponseInterface } from '../ApiResponseInterface-BKyod24U.js';
+import { Mock } from 'vitest';
+import { RenderOptions, RenderResult } from '@testing-library/react';
+export { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+export { userEvent } from '@testing-library/user-event';
+
+interface MockJsonApiProviderProps {
+    children: React__default.ReactNode;
+    config?: Partial<JsonApiConfig>;
+}
+declare const defaultMockConfig: JsonApiConfig;
+/**
+ * A test-friendly provider that wraps components with mock JSON:API context.
+ *
+ * @example
+ * ```tsx
+ * import { MockJsonApiProvider } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * render(
+ *   <MockJsonApiProvider>
+ *     <MyComponent />
+ *   </MockJsonApiProvider>
+ * );
+ * ```
+ *
+ * @example With custom config
+ * ```tsx
+ * render(
+ *   <MockJsonApiProvider config={{ apiUrl: 'https://custom.api.com' }}>
+ *     <MyComponent />
+ *   </MockJsonApiProvider>
+ * );
+ * ```
+ */
+declare function MockJsonApiProvider({ children, config }: MockJsonApiProviderProps): react_jsx_runtime.JSX.Element;
+
+interface CreateMockModuleOptions {
+    name: string;
+    cache?: string;
+    inclusions?: ApiRequestDataTypeInterface["inclusions"];
+}
+/**
+ * Creates a mock module definition for testing.
+ *
+ * @example
+ * ```ts
+ * import { createMockModule } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const mockArticleModule = createMockModule({ name: 'articles' });
+ * ```
+ */
+declare function createMockModule(options: CreateMockModuleOptions): ApiRequestDataTypeInterface;
+
+interface CreateMockResponseOptions {
+    data?: ApiDataInterface | ApiDataInterface[] | null;
+    ok?: boolean;
+    response?: number;
+    error?: string;
+    meta?: Record<string, any>;
+    self?: string;
+    next?: string;
+    prev?: string;
+}
+/**
+ * Creates a mock API response for testing.
+ *
+ * @example
+ * ```ts
+ * import { createMockResponse, createMockApiData } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const mockData = createMockApiData({ type: 'articles', id: '1' });
+ * const response = createMockResponse({ data: mockData, ok: true });
+ * ```
+ *
+ * @example With pagination
+ * ```ts
+ * const response = createMockResponse({
+ *   data: [mockData],
+ *   ok: true,
+ *   next: '/articles?page=2',
+ *   prev: '/articles?page=0',
+ * });
+ * ```
+ */
+declare function createMockResponse(options?: CreateMockResponseOptions): ApiResponseInterface;
+/**
+ * Creates a mock error response for testing error scenarios.
+ *
+ * @example
+ * ```ts
+ * import { createMockErrorResponse } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const errorResponse = createMockErrorResponse(404, 'Not Found');
+ * ```
+ */
+declare function createMockErrorResponse(statusCode: number, errorMessage: string): ApiResponseInterface;
+
+type MockApiMethod = Mock<(...args: any[]) => Promise<ApiResponseInterface>>;
+interface MockService {
+    get: MockApiMethod;
+    post: MockApiMethod;
+    put: MockApiMethod;
+    patch: MockApiMethod;
+    delete: MockApiMethod;
+}
+interface CreateMockServiceOptions {
+    defaultResponse?: ApiResponseInterface;
+}
+/**
+ * Creates a mock service with Vitest mock functions for all HTTP methods.
+ *
+ * @example
+ * ```ts
+ * import { createMockService, createMockResponse } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const mockService = createMockService();
+ * mockService.get.mockResolvedValue(createMockResponse({ data: mockData }));
+ *
+ * // Use in test
+ * expect(mockService.get).toHaveBeenCalled();
+ * ```
+ *
+ * @example With default response
+ * ```ts
+ * const mockService = createMockService({
+ *   defaultResponse: createMockResponse({ ok: true, data: [] }),
+ * });
+ * ```
+ */
+declare function createMockService(options?: CreateMockServiceOptions): MockService;
+/**
+ * Creates a mock service that returns errors for all methods.
+ *
+ * @example
+ * ```ts
+ * import { createMockErrorService } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const errorService = createMockErrorService(500, 'Internal Server Error');
+ * ```
+ */
+declare function createMockErrorService(statusCode?: number, errorMessage?: string): MockService;
+
+interface CreateMockApiDataOptions {
+    type: string;
+    id?: string;
+    attributes?: Record<string, any>;
+    relationships?: Record<string, any>;
+    included?: any[];
+    createdAt?: Date;
+    updatedAt?: Date;
+    self?: string;
+}
+/**
+ * Creates a mock ApiDataInterface object for testing.
+ *
+ * @example
+ * ```ts
+ * import { createMockApiData } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const mockArticle = createMockApiData({
+ *   type: 'articles',
+ *   id: '1',
+ *   attributes: { title: 'Test Article', body: 'Content here' },
+ * });
+ * ```
+ *
+ * @example With relationships
+ * ```ts
+ * const mockArticle = createMockApiData({
+ *   type: 'articles',
+ *   id: '1',
+ *   attributes: { title: 'Test' },
+ *   relationships: {
+ *     author: { data: { type: 'users', id: '42' } },
+ *   },
+ * });
+ * ```
+ */
+declare function createMockApiData(options: CreateMockApiDataOptions): ApiDataInterface;
+/**
+ * Creates an array of mock ApiDataInterface objects.
+ *
+ * @example
+ * ```ts
+ * import { createMockApiDataList } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const mockArticles = createMockApiDataList('articles', 5, (index) => ({
+ *   title: `Article ${index + 1}`,
+ * }));
+ * ```
+ */
+declare function createMockApiDataList(type: string, count: number, attributesFactory?: (index: number) => Record<string, any>): ApiDataInterface[];
+
+interface JsonApiResponse {
+    data?: {
+        type?: string;
+        id?: string;
+        attributes?: Record<string, any>;
+        relationships?: Record<string, any>;
+    } | Array<{
+        type?: string;
+        id?: string;
+        attributes?: Record<string, any>;
+        relationships?: Record<string, any>;
+    }>;
+}
+/**
+ * Custom Vitest matchers for JSON:API assertions.
+ *
+ * @example
+ * ```ts
+ * import { jsonApiMatchers } from '@carlonicora/nextjs-jsonapi/testing';
+ * import { expect } from 'vitest';
+ *
+ * expect.extend(jsonApiMatchers);
+ *
+ * // Then use in tests:
+ * expect(response).toBeValidJsonApi();
+ * expect(response).toHaveJsonApiType('articles');
+ * expect(response).toHaveJsonApiAttribute('title', 'My Article');
+ * expect(response).toHaveJsonApiRelationship('author');
+ * ```
+ */
+declare const jsonApiMatchers: {
+    /**
+     * Asserts that the response has a valid JSON:API structure with type and id.
+     */
+    toBeValidJsonApi(received: JsonApiResponse): {
+        pass: boolean;
+        message: () => string;
+    };
+    /**
+     * Asserts that the response data has the expected JSON:API type.
+     */
+    toHaveJsonApiType(received: JsonApiResponse, expectedType: string): {
+        pass: boolean;
+        message: () => string;
+    };
+    /**
+     * Asserts that the response data has an attribute with the expected value.
+     */
+    toHaveJsonApiAttribute(received: JsonApiResponse, attributeName: string, expectedValue?: any): {
+        pass: boolean;
+        message: () => string;
+    };
+    /**
+     * Asserts that the response data has the specified relationship.
+     */
+    toHaveJsonApiRelationship(received: JsonApiResponse, relationshipName: string): {
+        pass: boolean;
+        message: () => string;
+    };
+    /**
+     * Asserts that the response data array has the expected length.
+     */
+    toHaveJsonApiLength(received: JsonApiResponse, expectedLength: number): {
+        pass: boolean;
+        message: () => string;
+    };
+};
+declare module "vitest" {
+    interface Assertion<T = any> {
+        toBeValidJsonApi(): T;
+        toHaveJsonApiType(expectedType: string): T;
+        toHaveJsonApiAttribute(attributeName: string, expectedValue?: any): T;
+        toHaveJsonApiRelationship(relationshipName: string): T;
+        toHaveJsonApiLength(expectedLength: number): T;
+    }
+    interface AsymmetricMatchersContaining {
+        toBeValidJsonApi(): any;
+        toHaveJsonApiType(expectedType: string): any;
+        toHaveJsonApiAttribute(attributeName: string, expectedValue?: any): any;
+        toHaveJsonApiRelationship(relationshipName: string): any;
+        toHaveJsonApiLength(expectedLength: number): any;
+    }
+}
+/**
+ * Extends Vitest's expect with JSON:API matchers.
+ * Call this in your test setup file.
+ *
+ * @example
+ * ```ts
+ * // vitest.setup.ts
+ * import { extendExpectWithJsonApiMatchers } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * extendExpectWithJsonApiMatchers();
+ * ```
+ */
+declare function extendExpectWithJsonApiMatchers(): void;
+
+interface RenderWithProvidersOptions extends Omit<RenderOptions, "wrapper"> {
+    /**
+     * Custom JSON:API configuration to pass to the mock provider.
+     */
+    jsonApiConfig?: Partial<JsonApiConfig>;
+    /**
+     * Additional wrapper component to wrap around the providers.
+     */
+    wrapper?: React__default.ComponentType<{
+        children: React__default.ReactNode;
+    }>;
+}
+/**
+ * Renders a component wrapped with all necessary providers for testing.
+ *
+ * @example
+ * ```tsx
+ * import { renderWithProviders } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const { getByText } = renderWithProviders(<MyComponent />);
+ * expect(getByText('Hello')).toBeInTheDocument();
+ * ```
+ *
+ * @example With custom config
+ * ```tsx
+ * const { getByText } = renderWithProviders(<MyComponent />, {
+ *   jsonApiConfig: { apiUrl: 'https://custom.api.com' },
+ * });
+ * ```
+ *
+ * @example With additional wrapper
+ * ```tsx
+ * const CustomWrapper = ({ children }) => (
+ *   <ThemeProvider>{children}</ThemeProvider>
+ * );
+ *
+ * const { getByText } = renderWithProviders(<MyComponent />, {
+ *   wrapper: CustomWrapper,
+ * });
+ * ```
+ */
+declare function renderWithProviders(ui: ReactElement, options?: RenderWithProvidersOptions): RenderResult;
+
+export { type CreateMockApiDataOptions, type CreateMockModuleOptions, type CreateMockResponseOptions, type CreateMockServiceOptions, type MockApiMethod, MockJsonApiProvider, type MockJsonApiProviderProps, type MockService, type RenderWithProvidersOptions, createMockApiData, createMockApiDataList, createMockErrorResponse, createMockErrorService, createMockModule, createMockResponse, createMockService, defaultMockConfig, extendExpectWithJsonApiMatchers, jsonApiMatchers, renderWithProviders };