@carlonicora/nextjs-jsonapi 1.15.0 → 1.17.0

package/src/hooks/__tests__/useDebounce.test.ts

@@ -0,0 +1,170 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useDebounce } from "../useDebounce";
+
+describe("useDebounce", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should delay callback execution", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useDebounce(callback, 500));
+
+    act(() => {
+      result.current("test");
+    });
+
+    // Callback should not be called immediately
+    expect(callback).not.toHaveBeenCalled();
+
+    // Advance timers by 500ms
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+
+    // Now callback should be called
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(callback).toHaveBeenCalledWith("test");
+  });
+
+  it("should reset timer on subsequent calls", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useDebounce(callback, 500));
+
+    act(() => {
+      result.current("first");
+    });
+
+    // Advance 300ms (less than delay)
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    // Call again - should reset timer
+    act(() => {
+      result.current("second");
+    });
+
+    // Advance another 300ms (total 600ms from first call, but only 300ms from second)
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    // Still not called
+    expect(callback).not.toHaveBeenCalled();
+
+    // Advance remaining 200ms
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
+    // Now should be called with the second argument
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(callback).toHaveBeenCalledWith("second");
+  });
+
+  it("should cancel pending call", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useDebounce(callback, 500));
+
+    act(() => {
+      result.current("test");
+    });
+
+    // Cancel before timer fires
+    act(() => {
+      result.current.cancel();
+    });
+
+    // Advance past delay
+    act(() => {
+      vi.advanceTimersByTime(600);
+    });
+
+    // Callback should not be called
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it("should pass multiple arguments to callback", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() =>
+      useDebounce((a: string, b: number, c: boolean) => callback(a, b, c), 500)
+    );
+
+    act(() => {
+      result.current("hello", 42, true);
+    });
+
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+
+    expect(callback).toHaveBeenCalledWith("hello", 42, true);
+  });
+
+  it("should update callback reference when callback changes", () => {
+    const callback1 = vi.fn();
+    const callback2 = vi.fn();
+
+    const { result, rerender } = renderHook(
+      ({ cb }) => useDebounce(cb, 500),
+      { initialProps: { cb: callback1 } }
+    );
+
+    act(() => {
+      result.current("test");
+    });
+
+    // Change callback before timer fires
+    rerender({ cb: callback2 });
+
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+
+    // Should call the new callback
+    expect(callback1).not.toHaveBeenCalled();
+    expect(callback2).toHaveBeenCalledWith("test");
+  });
+
+  it("should handle different delay values", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useDebounce(callback, 1000));
+
+    act(() => {
+      result.current("test");
+    });
+
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+
+    expect(callback).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("should handle zero delay", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useDebounce(callback, 0));
+
+    act(() => {
+      result.current("test");
+    });
+
+    act(() => {
+      vi.advanceTimersByTime(0);
+    });
+
+    expect(callback).toHaveBeenCalledWith("test");
+  });
+});

package/src/index.ts

@@ -9,14 +9,17 @@ export * from "./core";
 export * from "./permissions";
 
 // JSON:API configuration (client-safe)
-export { configureJsonApi, getApiUrl, getAppUrl, getTrackablePages } from "./client/config";
+export { configureJsonApi, getApiUrl, getAppUrl, getTrackablePages, getStripePublishableKey } from "./client/config";
 
 // I18n configuration (NOT hooks - those are in /hooks with "use client")
 export { configureI18n } from "./i18n";
 export type { I18nConfig } from "./i18n";
 
+// Login configuration (multi-provider auth)
+export { configureLogin } from "./login";
+export type { LoginConfig } from "./login";
+
 // Roles configuration
-export { configureDiscord } from "./discord";
 export { configureRoles, getRoleId, isRolesConfigured } from "./roles";
 export type { RoleIdConfig } from "./roles";
 

package/src/login/config.ts

@@ -0,0 +1,27 @@
+let _useDiscordAuth: boolean = false;
+let _useInternalAuth: boolean = true;
+let _allowRegistration: boolean = true;
+
+export interface LoginConfig {
+  useDiscordAuth: boolean;
+  useInternalAuth: boolean;
+  allowRegistration?: boolean;
+}
+
+export function configureLogin(params: LoginConfig): void {
+  _useDiscordAuth = params.useDiscordAuth;
+  _useInternalAuth = params.useInternalAuth;
+  _allowRegistration = params.allowRegistration ?? true;
+}
+
+export function isDiscordAuthEnabled(): boolean {
+  return _useDiscordAuth;
+}
+
+export function isInternalAuthEnabled(): boolean {
+  return _useInternalAuth;
+}
+
+export function isRegistrationAllowed(): boolean {
+  return _allowRegistration;
+}

package/src/login/index.ts

@@ -0,0 +1,2 @@
+export { configureLogin, isDiscordAuthEnabled, isInternalAuthEnabled, isRegistrationAllowed } from "./config";
+export type { LoginConfig } from "./config";

package/src/shadcnui/custom/link.tsx

@@ -1,16 +1,26 @@
 "use client";
 
-import NextLink from "next/link";
-import { cn } from "../../utils/cn";
 import * as React from "react";
+import { getI18nLink } from "../../i18n";
+import { cn } from "../../utils/cn";
 
-// Create our custom Link props interface that extends Next.js Link
-export interface LinkProps extends React.ComponentPropsWithoutRef<typeof NextLink> {
+// Create our custom Link props interface
+// Note: We use 'any' for now since the actual Link is retrieved at runtime
+export interface LinkProps {
+  href: string;
+  children: React.ReactNode;
   className?: string;
+  [key: string]: any;
 }
 
-const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(({ className, ...props }, ref) => {
-  return <NextLink ref={ref} className={cn(`font-medium`, className)} {...props} />;
+const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(({ className, href, children, ...props }, ref) => {
+  // Get the configured next-intl Link component at runtime (after i18n is configured)
+  const NextIntlLink = getI18nLink();
+  return (
+    <NextIntlLink prefetch={false} ref={ref} href={href} className={cn(`font-medium`, className)} {...props}>
+      {children}
+    </NextIntlLink>
+  );
 });
 
 Link.displayName = "Link";

package/src/testing/factories/createMockApiData.ts

@@ -0,0 +1,143 @@
+import { ApiDataInterface } from "../../core/interfaces/ApiDataInterface";
+
+export 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' } },
+ *   },
+ * });
+ * ```
+ */
+export function createMockApiData(options: CreateMockApiDataOptions): ApiDataInterface {
+  const {
+    type,
+    id = `mock-${type}-${Math.random().toString(36).substring(7)}`,
+    attributes = {},
+    relationships = {},
+    included = [],
+    createdAt = new Date(),
+    updatedAt = new Date(),
+    self,
+  } = options;
+
+  const jsonApiData = {
+    type,
+    id,
+    attributes: {
+      ...attributes,
+      createdAt: createdAt.toISOString(),
+      updatedAt: updatedAt.toISOString(),
+    },
+    relationships,
+  };
+
+  const mockData: ApiDataInterface = {
+    get included() {
+      return included;
+    },
+    get type() {
+      return type;
+    },
+    get id() {
+      return id;
+    },
+    get createdAt() {
+      return createdAt;
+    },
+    get updatedAt() {
+      return updatedAt;
+    },
+    get self() {
+      return self;
+    },
+    get jsonApi() {
+      return jsonApiData;
+    },
+    generateApiUrl: (params?: any) => {
+      const baseUrl = `/${type}/${id}`;
+      if (params) {
+        const searchParams = new URLSearchParams(params);
+        return `${baseUrl}?${searchParams.toString()}`;
+      }
+      return baseUrl;
+    },
+    dehydrate: () => ({
+      jsonApi: jsonApiData,
+      included,
+      allData: [jsonApiData],
+    }),
+    rehydrate: function (data: any) {
+      return this;
+    },
+    createJsonApi: (data: any) => ({
+      type,
+      id,
+      attributes: data,
+    }),
+  };
+
+  // Add attribute accessors to the mock object
+  Object.keys(attributes).forEach((key) => {
+    Object.defineProperty(mockData, key, {
+      get: () => attributes[key],
+      enumerable: true,
+    });
+  });
+
+  return mockData;
+}
+
+/**
+ * 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}`,
+ * }));
+ * ```
+ */
+export function createMockApiDataList(
+  type: string,
+  count: number,
+  attributesFactory?: (index: number) => Record<string, any>
+): ApiDataInterface[] {
+  return Array.from({ length: count }, (_, index) =>
+    createMockApiData({
+      type,
+      id: `${index + 1}`,
+      attributes: attributesFactory?.(index) ?? {},
+    })
+  );
+}

package/src/testing/factories/createMockModule.ts

@@ -0,0 +1,32 @@
+import { ApiRequestDataTypeInterface } from "../../core/interfaces/ApiRequestDataTypeInterface";
+
+export 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' });
+ * ```
+ */
+export function createMockModule(options: CreateMockModuleOptions): ApiRequestDataTypeInterface {
+  // Create a mock model class
+  class MockModel {
+    id = "mock-id";
+    type = options.name;
+  }
+
+  return {
+    name: options.name,
+    cache: options.cache,
+    inclusions: options.inclusions,
+    model: MockModel,
+  };
+}

package/src/testing/factories/createMockResponse.ts

@@ -0,0 +1,93 @@
+import { ApiResponseInterface } from "../../core/interfaces/ApiResponseInterface";
+import { ApiDataInterface } from "../../core/interfaces/ApiDataInterface";
+
+export 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',
+ * });
+ * ```
+ */
+export function createMockResponse(options: CreateMockResponseOptions = {}): ApiResponseInterface {
+  const {
+    data = null,
+    ok = true,
+    response = ok ? 200 : 500,
+    error = ok ? "" : "Error",
+    meta,
+    self,
+    next,
+    prev,
+  } = options;
+
+  const mockResponse: ApiResponseInterface = {
+    ok,
+    response,
+    data: data as ApiDataInterface | ApiDataInterface[],
+    error,
+    meta,
+    self,
+    next,
+    prev,
+  };
+
+  // Add pagination methods if next/prev provided
+  if (next) {
+    mockResponse.nextPage = async () =>
+      createMockResponse({ ...options, next: undefined, prev: self });
+  }
+
+  if (prev) {
+    mockResponse.prevPage = async () =>
+      createMockResponse({ ...options, prev: undefined, next: self });
+  }
+
+  return mockResponse;
+}
+
+/**
+ * Creates a mock error response for testing error scenarios.
+ *
+ * @example
+ * ```ts
+ * import { createMockErrorResponse } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const errorResponse = createMockErrorResponse(404, 'Not Found');
+ * ```
+ */
+export function createMockErrorResponse(
+  statusCode: number,
+  errorMessage: string
+): ApiResponseInterface {
+  return createMockResponse({
+    ok: false,
+    response: statusCode,
+    error: errorMessage,
+    data: null,
+  });
+}

package/src/testing/factories/createMockService.ts

@@ -0,0 +1,79 @@
+import { vi, type Mock } from "vitest";
+import { ApiResponseInterface } from "../../core/interfaces/ApiResponseInterface";
+import { createMockResponse } from "./createMockResponse";
+
+export type MockApiMethod = Mock<(...args: any[]) => Promise<ApiResponseInterface>>;
+
+export interface MockService {
+  get: MockApiMethod;
+  post: MockApiMethod;
+  put: MockApiMethod;
+  patch: MockApiMethod;
+  delete: MockApiMethod;
+}
+
+export 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: [] }),
+ * });
+ * ```
+ */
+export function createMockService(options: CreateMockServiceOptions = {}): MockService {
+  const defaultResponse = options.defaultResponse ?? createMockResponse({ ok: true });
+
+  return {
+    get: vi.fn().mockResolvedValue(defaultResponse),
+    post: vi.fn().mockResolvedValue(defaultResponse),
+    put: vi.fn().mockResolvedValue(defaultResponse),
+    patch: vi.fn().mockResolvedValue(defaultResponse),
+    delete: vi.fn().mockResolvedValue(defaultResponse),
+  };
+}
+
+/**
+ * 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');
+ * ```
+ */
+export function createMockErrorService(
+  statusCode: number = 500,
+  errorMessage: string = "Error"
+): MockService {
+  const errorResponse = createMockResponse({
+    ok: false,
+    response: statusCode,
+    error: errorMessage,
+  });
+
+  return {
+    get: vi.fn().mockResolvedValue(errorResponse),
+    post: vi.fn().mockResolvedValue(errorResponse),
+    put: vi.fn().mockResolvedValue(errorResponse),
+    patch: vi.fn().mockResolvedValue(errorResponse),
+    delete: vi.fn().mockResolvedValue(errorResponse),
+  };
+}

package/src/testing/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Test utilities for @carlonicora/nextjs-jsonapi
+ *
+ * Import from '@carlonicora/nextjs-jsonapi/testing'
+ *
+ * @example
+ * ```ts
+ * import {
+ *   MockJsonApiProvider,
+ *   renderWithProviders,
+ *   createMockApiData,
+ *   createMockResponse,
+ *   createMockModule,
+ *   createMockService,
+ *   jsonApiMatchers,
+ *   extendExpectWithJsonApiMatchers,
+ * } from '@carlonicora/nextjs-jsonapi/testing';
+ * ```
+ */
+
+// Providers
+export {
+  MockJsonApiProvider,
+  defaultMockConfig,
+  type MockJsonApiProviderProps,
+} from "./providers/MockJsonApiProvider";
+
+// Factories
+export {
+  createMockModule,
+  type CreateMockModuleOptions,
+} from "./factories/createMockModule";
+
+export {
+  createMockResponse,
+  createMockErrorResponse,
+  type CreateMockResponseOptions,
+} from "./factories/createMockResponse";
+
+export {
+  createMockService,
+  createMockErrorService,
+  type MockService,
+  type MockApiMethod,
+  type CreateMockServiceOptions,
+} from "./factories/createMockService";
+
+export {
+  createMockApiData,
+  createMockApiDataList,
+  type CreateMockApiDataOptions,
+} from "./factories/createMockApiData";
+
+// Matchers
+export {
+  jsonApiMatchers,
+  extendExpectWithJsonApiMatchers,
+} from "./matchers/jsonApiMatchers";
+
+// Utilities
+export {
+  renderWithProviders,
+  render,
+  screen,
+  waitFor,
+  fireEvent,
+  within,
+  userEvent,
+  type RenderWithProvidersOptions,
+} from "./utils/renderWithProviders";