ra-spring-data-provider 1.0.1

package/README.md

@@ -0,0 +1,81 @@
+# ra-spring-data-provider
+
+Te [React Admin](https://marmelab.com/react-admin/) data provider of [ra-spring-json-server].
+
+This package provides a data provider that follows JSON Server API conventions, specifically adapted for Spring Boot backends. It supports efficient bulk operations and is designed to work seamlessly with Spring Boot controllers implementing the `IRAController` interface from [ra-spring-json-server] library.
+
+## Installation
+
+```bash
+npm install ra-spring-data-provider
+# or
+yarn add ra-spring-data-provider
+```
+
+## Usage
+
+```jsx
+import * as React from "react";
+import { Admin, Resource } from "react-admin";
+import raSpringDataProvider from "ra-spring-data-provider";
+
+const dataProvider = jsonServerProvider("http://localhost:8080/api");
+
+const App = () => (
+  <Admin dataProvider={dataProvider}>
+    <Resource name="users" list={ListGuesser} />
+  </Admin>
+);
+
+export default App;
+```
+
+## API Mapping
+
+This data provider uses the JSON Server API format to communicate with the backend. Your Spring Boot API should follow these conventions:
+
+| React Admin Method | HTTP Method | URL Example                                                   |
+| ------------------ | ----------- | ------------------------------------------------------------- |
+| `getList`          | `GET`       | `http://api.url/users?_sort=name&_order=ASC&_start=0&_end=24` |
+| `getOne`           | `GET`       | `http://api.url/users/123`                                    |
+| `getMany`          | `GET`       | `http://api.url/users?id=123&id=456`                          |
+| `getManyReference` | `GET`       | `http://api.url/users?authorId=345`                           |
+| `create`           | `POST`      | `http://api.url/users`                                        |
+| `update`           | `PUT`       | `http://api.url/users/123`                                    |
+| `updateMany`       | `PUT`       | `http://api.url/users?id=123&id=456`                          |
+| `delete`           | `DELETE`    | `http://api.url/users/123`                                    |
+| `deleteMany`       | `DELETE`    | `http://api.url/users?id=123&id=456`                          |
+
+## Backend Requirements
+
+For the Spring Boot backend implementation, use the **[ra-spring-json-server]** library which provides all the necessary endpoints and configurations to work with this data provider.
+
+## Development
+
+### Running Integration Tests
+
+You can run the complete integration test suite from the project root:
+
+```bash
+cd .. && ./run-integration-tests.sh
+```
+
+This script will start the Spring Boot backend, run the tests, and clean up automatically.
+
+## Test Cases
+
+The tests cover:
+
+- ✅ Display users list
+- ✅ Create a new user
+- ✅ Edit an existing user
+- ✅ Delete a user
+- ✅ Filter/search users
+- ✅ Sort users
+
+## Requirements
+
+- Node.js 18+
+- Java 17+
+
+[ra-spring-json-server]: https://github.com/femrek/ra-spring-json-server

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "ra-spring-data-provider",
+  "version": "1.0.1",
+  "description": "React Admin data provider for Spring Boot REST APIs",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:headed": "playwright test --headed",
+    "test:debug": "playwright test --debug",
+    "test:users": "playwright test users.spec.js",
+    "test:data-provider": "playwright test data-provider.spec.js",
+    "test:error-handling": "playwright test error-handling.spec.js",
+    "test:performance": "playwright test performance.spec.js",
+    "test:ui-ux": "playwright test ui-ux.spec.js",
+    "test:report": "playwright show-report",
+    "install-browsers": "playwright install",
+    "release": "release-it"
+  },
+  "keywords": [
+    "react-admin",
+    "data-provider",
+    "spring-boot",
+    "rest-api"
+  ],
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/femrek/ra-spring-json-server.git",
+    "directory": "ra-spring-data-provider"
+  },
+  "author": "femrek",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "query-string": "^9.1.0",
+    "ra-core": "^5.4.0",
+    "ra-data-json-server": "^5.13.6"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-admin": "^5.4.0",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@emotion/react": "^11.13.3",
+    "@emotion/styled": "^11.13.0",
+    "@mui/icons-material": "^6.3.0",
+    "@mui/material": "^6.3.0",
+    "@playwright/experimental-ct-react": "^1.49.0",
+    "@playwright/test": "^1.49.0",
+    "@types/node": "^25.0.10",
+    "@vitejs/plugin-react": "^4.3.4",
+    "react": "^18.3.1",
+    "react-admin": "^5.4.0",
+    "react-dom": "^18.3.1",
+    "release-it": "^19.2.4",
+    "vite": "^6.0.5"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,29 @@
+import { DataProvider } from "ra-core";
+
+/**
+ * Creates a React Admin data provider for Spring Boot REST APIs
+ *
+ * @param apiUrl - The base URL of your Spring Boot API (e.g., 'http://localhost:8081/api')
+ * @param httpClient - Optional custom HTTP client function (defaults to fetchUtils.fetchJson)
+ * @returns A React Admin DataProvider configured for Spring Boot
+ *
+ * @example
+ * import raSpringDataProvider from 'ra-spring-data-provider';
+ *
+ * const dataProvider = raSpringDataProvider('http://localhost:8081/api');
+ *
+ * const App = () => (
+ *   <Admin dataProvider={dataProvider}>
+ *     <Resource name="users" list={UserList} />
+ *   </Admin>
+ * );
+ */
+declare const raSpringDataProvider: (
+  apiUrl: string,
+  httpClient?: (
+    url: string,
+    options?: any,
+  ) => Promise<{ headers: Headers; json: any }>,
+) => DataProvider;
+
+export default raSpringDataProvider;

package/src/index.ts

@@ -0,0 +1,191 @@
+import queryString from "query-string";
+import { fetchUtils, DataProvider } from "ra-core";
+
+/**
+ * Creates a React Admin data provider for Spring Boot REST APIs following JSON Server conventions.
+ *
+ * This data provider is designed to work with Spring Boot controllers that implement the
+ * IRAController interface, supporting JSON Server-style query parameters and response formats.
+ *
+ * @param apiUrl - The base URL of your Spring Boot API (e.g., 'http://localhost:8081/api')
+ * @param httpClient - Optional custom HTTP client function (defaults to fetchUtils.fetchJson)
+ *
+ * @returns A React Admin DataProvider instance
+ *
+ * @example
+ * ```tsx
+ * import { Admin, Resource } from 'react-admin';
+ * import raSpringDataProvider from 'ra-spring-data-provider';
+ *
+ * const dataProvider = raSpringDataProvider('http://localhost:8081/api');
+ *
+ * const App = () => (
+ *   <Admin dataProvider={dataProvider}>
+ *     <Resource name="users" list={UserList} edit={UserEdit} create={UserCreate} />
+ *   </Admin>
+ * );
+ * ```
+ *
+ * @remarks
+ * **API Requirements:**
+ * - GET endpoints must return X-Total-Count header for pagination
+ * - List queries use _start, _end, _sort, _order query parameters
+ * - Bulk operations (updateMany, deleteMany) use multiple id query parameters
+ * - CORS must expose the X-Total-Count header
+ *
+ * **Supported Operations:**
+ * - `getList`: GET /resource?_start=0&_end=10&_sort=id&_order=ASC
+ * - `getOne`: GET /resource/123
+ * - `getMany`: GET /resource?id=123&id=456&id=789
+ * - `getManyReference`: GET /resource?author_id=12&_start=0&_end=10
+ * - `create`: POST /resource with JSON body
+ * - `update`: PUT /resource/123 with JSON body
+ * - `updateMany`: PUT /resource?id=123&id=456 with JSON body (bulk update)
+ * - `delete`: DELETE /resource/123
+ * - `deleteMany`: DELETE /resource?id=123&id=456 (bulk delete)
+ *
+ * **Spring Boot Adaptations:**
+ * - Bulk operations (updateMany, deleteMany) send single requests with multiple id parameters
+ * - updateMany sends data fields in request body to update all specified records
+ * - This differs from standard ra-data-json-server which sends individual requests for bulk operations
+ *
+ * **Embedded Resources:**
+ * Use the `meta.embed` parameter to request related records:
+ * ```tsx
+ * useGetOne('posts', { id: 1, meta: { embed: 'author' } })
+ * ```
+ */
+export default (
+  apiUrl: string,
+  httpClient = fetchUtils.fetchJson,
+): DataProvider => ({
+  getList: async (resource, params) => {
+    const { page, perPage } = params.pagination || {};
+    const { field, order } = params.sort || {};
+    const query = {
+      ...fetchUtils.flattenObject(params.filter),
+      _sort: field,
+      _order: order,
+      _start:
+        page != null && perPage != null ? (page - 1) * perPage : undefined,
+      _end: page != null && perPage != null ? page * perPage : undefined,
+      _embed: params?.meta?.embed,
+    };
+    const url = `${apiUrl}/${resource}?${queryString.stringify(query)}`;
+
+    const { headers, json } = await httpClient(url, {
+      signal: params?.signal,
+    });
+    if (!headers.has("x-total-count")) {
+      throw new Error(
+        "The X-Total-Count header is missing in the HTTP Response. The jsonServer Data Provider expects responses for lists of resources to contain this header with the total number of results to build the pagination. If you are using CORS, did you declare X-Total-Count in the Access-Control-Expose-Headers header?",
+      );
+    }
+    const totalString = headers.get("x-total-count")!.split("/").pop();
+    if (totalString == null) {
+      throw new Error(
+        "The X-Total-Count header is invalid in the HTTP Response.",
+      );
+    }
+    return { data: json, total: parseInt(totalString, 10) };
+  },
+
+  getOne: async (resource, params) => {
+    let url = `${apiUrl}/${resource}/${params.id}`;
+    if (params?.meta?.embed) {
+      url += `?_embed=${params.meta.embed}`;
+    }
+    const { json } = await httpClient(url, { signal: params?.signal });
+    return { data: json };
+  },
+
+  getMany: async (resource, params) => {
+    const query = {
+      id: params.ids,
+      _embed: params?.meta?.embed,
+    };
+    const url = `${apiUrl}/${resource}?${queryString.stringify(query)}`;
+    const { json } = await httpClient(url, { signal: params?.signal });
+    return { data: json };
+  },
+
+  getManyReference: async (resource, params) => {
+    const { page, perPage } = params.pagination;
+    const { field, order } = params.sort;
+    const query = {
+      ...fetchUtils.flattenObject(params.filter),
+      [params.target]: params.id,
+      _sort: field,
+      _order: order,
+      _start: (page - 1) * perPage,
+      _end: page * perPage,
+      _embed: params?.meta?.embed,
+    };
+    const url = `${apiUrl}/${resource}?${queryString.stringify(query)}`;
+
+    const { headers, json } = await httpClient(url, {
+      signal: params?.signal,
+    });
+
+    if (!headers.has("x-total-count")) {
+      throw new Error(
+        "The X-Total-Count header is missing in the HTTP Response. The jsonServer Data Provider expects responses for lists of resources to contain this header with the total number of results to build the pagination. If you are using CORS, did you declare X-Total-Count in the Access-Control-Expose-Headers header?",
+      );
+    }
+    const totalString = headers.get("x-total-count")!.split("/").pop();
+    if (totalString == null) {
+      throw new Error(
+        "The X-Total-Count header is invalid in the HTTP Response.",
+      );
+    }
+    return { data: json, total: parseInt(totalString, 10) };
+  },
+
+  update: async (resource, params) => {
+    const { json } = await httpClient(`${apiUrl}/${resource}/${params.id}`, {
+      method: "PUT",
+      body: JSON.stringify(params.data),
+    });
+    return { data: json };
+  },
+
+  // Spring Boot bulk update: PUT /resource?id=1&id=2&id=3 with data in body
+  updateMany: async (resource, params) => {
+    const query = {
+      id: params.ids,
+    };
+    const url = `${apiUrl}/${resource}?${queryString.stringify(query)}`;
+    const { json } = await httpClient(url, {
+      method: "PUT",
+      body: JSON.stringify(params.data),
+    });
+    return { data: json };
+  },
+
+  create: async (resource, params) => {
+    const { json } = await httpClient(`${apiUrl}/${resource}`, {
+      method: "POST",
+      body: JSON.stringify(params.data),
+    });
+    return { data: { ...params.data, ...json } as any };
+  },
+
+  delete: async (resource, params) => {
+    const { json } = await httpClient(`${apiUrl}/${resource}/${params.id}`, {
+      method: "DELETE",
+    });
+    return { data: json };
+  },
+
+  // Spring Boot bulk delete: DELETE /resource?id=1&id=2&id=3
+  deleteMany: async (resource, params) => {
+    const query = {
+      id: params.ids,
+    };
+    const url = `${apiUrl}/${resource}?${queryString.stringify(query)}`;
+    const { json } = await httpClient(url, {
+      method: "DELETE",
+    });
+    return { data: json };
+  },
+});