@aginix/vulcan-data-provider 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# @aginix/vulcan-data-provider
+
+[React Admin](https://marmelab.com/react-admin/) data provider for APIs built
+with [`@aginix/adonis-vulcan`](../adonis-vulcan)'s `BaseResourceController`.
+
+It speaks the same PostgREST-style filter grammar that `BaseResourceController`
+parses on the server side (`?status=eq.active&age=gte.18`), so any controller
+that `extends BaseResourceController` is wired up automatically.
+
+## Install
+
+```sh
+pnpm add @aginix/vulcan-data-provider react-admin
+```
+
+`react-admin` (or `ra-core`) is a peer dependency.
+
+## Usage
+
+```tsx
+import { Admin, Resource, fetchUtils } from 'react-admin'
+import { vulcanDataProvider } from '@aginix/vulcan-data-provider'
+
+import { PostList, PostEdit, PostCreate } from './posts'
+
+const dataProvider = vulcanDataProvider({
+  apiUrl: '/api',
+  httpClient: fetchUtils.fetchJson,
+})
+
+export const App = () => (
+  <Admin dataProvider={dataProvider}>
+    <Resource name="posts" list={PostList} edit={PostEdit} create={PostCreate} />
+  </Admin>
+)
+```
+
+## How it maps to the API
+
+| react-admin call    | HTTP method + URL                                   |
+| ------------------- | --------------------------------------------------- |
+| `getList`           | `GET /<resource>?page=&perPage=&order=&<filters>`   |
+| `getOne`            | `GET /<resource>/<id>`                              |
+| `getMany`           | `GET /<resource>?id=in.(...)&page=1&perPage=<n>`    |
+| `getManyReference`  | `GET /<resource>?<target>=eq.<id>&...`              |
+| `create`            | `POST /<resource>`                                  |
+| `update`            | `PUT /<resource>/<id>` (only changed fields)        |
+| `updateMany`        | `PUT /<resource>/<id>` looped (no batch endpoint)   |
+| `delete`            | `DELETE /<resource>/<id>`                           |
+| `deleteMany`        | `DELETE /<resource>/<id>` looped                    |
+
+Response envelope (matches `ResourceSerializer` / Lucid pagination):
+
+```jsonc
+// list
+{ "data": [...], "metadata": { "total": 99, "perPage": 25, "currentPage": 1, ... } }
+
+// single
+{ "data": { ... } }
+
+// destroy → 204 No Content
+```
+
+## Filter grammar
+
+The data provider reads react-admin's `filter` object and emits
+PostgREST-flavored query strings that `@aginix/adonis-vulcan`'s `FilterParser`
+understands.
+
+| Filter shape                                      | URL fragment                              |
+| ------------------------------------------------- | ----------------------------------------- |
+| `{ status: 'active' }`                            | `status=eq.active`                        |
+| `{ 'age@gt': 18 }`                                | `age=gt.18`                               |
+| `{ 'name@like': 'foo bar' }`                      | `name=like.*foo*&name=like.*bar*`         |
+| `{ tags: ['admin', 'user'] }`                     | `tags=in.(admin,user)`                    |
+| `{ q: 'search' }`                                 | `q=search` (no operator)                  |
+| `{ faculty: { name: 'CS' } }`                     | `faculty.name=eq.CS` (embedded filter)    |
+| `{ 'curriculums.exists': 'true' }`                | `curriculums.exists=true` (special key)   |
+
+Set `defaultListOp` on the config to change the implicit operator from `eq` to
+something else (e.g. `'ilike'` for free-text fields).
+
+## Compound primary keys
+
+For resources whose primary key is more than one column, register the column
+list when constructing the provider:
+
+```ts
+import { vulcanDataProvider, defaultPrimaryKeys } from '@aginix/vulcan-data-provider'
+
+defaultPrimaryKeys.set('enrollments', ['student_id', 'course_id'])
+
+const dataProvider = vulcanDataProvider({
+  apiUrl: '/api',
+  httpClient: fetchUtils.fetchJson,
+  primaryKeys: defaultPrimaryKeys,
+})
+```
+
+The provider then synthesizes a virtual `id` (a JSON-encoded array of the key
+parts) so react-admin's record-by-id flow keeps working transparently.
+
+## Configuration
+
+```ts
+type VulcanDataProviderConfig = {
+  apiUrl: string
+  httpClient: (url: string, options?: any) => Promise<{ status, headers, body, json }>
+  defaultListOp?: VulcanOperator           // default: 'eq'
+  sortOrder?: VulcanSortOrder              // default: ASC nullsLast / DESC nullsFirst
+  primaryKeys?: Map<string, readonly string[]>  // default: ['id'] for every resource
+  pageParam?: string                       // default: 'page'
+  perPageParam?: string                    // default: 'perPage'
+}
+```

package/build/index.d.ts

@@ -0,0 +1,4 @@
+export * from './src/types.js';
+export { parseFilters, getPrimaryKey, decodeId, encodeId, removePrimaryKey, dataWithVirtualId, dataWithoutVirtualId, getQuery, getOrderBy, type ParsedFilters, } from './src/url_builder.js';
+export { vulcanDataProvider, defaultPrimaryKeys } from './src/data_provider.js';
+export { default } from './src/data_provider.js';

package/build/index.js

@@ -0,0 +1,4 @@
+import { EMBEDDED_SPECIAL_KEYS, VULCAN_OPERATORS, VulcanSortOrder } from "./src/types.js";
+import { dataWithVirtualId, dataWithoutVirtualId, decodeId, encodeId, getOrderBy, getPrimaryKey, getQuery, parseFilters, removePrimaryKey } from "./src/url_builder.js";
+import vulcanDataProvider, { defaultPrimaryKeys } from "./src/data_provider.js";
+export { EMBEDDED_SPECIAL_KEYS, VULCAN_OPERATORS, VulcanSortOrder, dataWithVirtualId, dataWithoutVirtualId, decodeId, vulcanDataProvider as default, vulcanDataProvider, defaultPrimaryKeys, encodeId, getOrderBy, getPrimaryKey, getQuery, parseFilters, removePrimaryKey };

package/build/src/data_provider.d.ts

@@ -0,0 +1,32 @@
+import type { DataProvider } from 'ra-core';
+import { type PrimaryKey, type VulcanDataProviderConfig } from './types.js';
+/**
+ * Convenience: a per-resource `Map<resource, PrimaryKey>` you can pass to
+ * `vulcanDataProvider({ primaryKeys: defaultPrimaryKeys })` and then `.set()`
+ * compound-key resources on. Empty by default — `['id']` is the implicit
+ * fallback.
+ */
+export declare const defaultPrimaryKeys: Map<string, PrimaryKey>;
+/**
+ * React-admin data provider for APIs built with `@aginix/adonis-vulcan`.
+ *
+ * Endpoints expected (matches `Route.resource()` + `BaseResourceController`):
+ *
+ *     getList          GET    /<resource>?page=&perPage=&order=&<filters>
+ *     getOne           GET    /<resource>/<id>
+ *     getMany          GET    /<resource>?id=in.(...)&page=1&perPage=<count>
+ *     getManyReference GET    /<resource>?<target>=eq.<id>&...
+ *     create           POST   /<resource>
+ *     update           PUT    /<resource>/<id>
+ *     updateMany       PUT    /<resource>/<id>   (looped)
+ *     delete           DELETE /<resource>/<id>
+ *     deleteMany       DELETE /<resource>/<id>   (looped)
+ *
+ * Response envelopes:
+ *
+ *     list   { data: T[], metadata: { total, perPage, currentPage, lastPage, ... } }
+ *     single { data: T }
+ *     destroy 204 No Content
+ */
+export declare const vulcanDataProvider: (config: VulcanDataProviderConfig) => DataProvider;
+export default vulcanDataProvider;

package/build/src/data_provider.js

@@ -0,0 +1,212 @@
+import { dataWithVirtualId, dataWithoutVirtualId, encodeId, getOrderBy, getPrimaryKey, getQuery, parseFilters, removePrimaryKey } from "./url_builder.js";
+import { HttpError } from "ra-core";
+import qs from "qs";
+import { dequal } from "dequal";
+//#region src/data_provider.ts
+/**
+* Convenience: a per-resource `Map<resource, PrimaryKey>` you can pass to
+* `vulcanDataProvider({ primaryKeys: defaultPrimaryKeys })` and then `.set()`
+* compound-key resources on. Empty by default — `['id']` is the implicit
+* fallback.
+*/
+const defaultPrimaryKeys = /* @__PURE__ */ new Map();
+const computeChanges = (data, previousData) => {
+	return Object.keys(data).reduce((acc, key) => {
+		if (!dequal(data[key], previousData[key])) acc[key] = data[key];
+		return acc;
+	}, {});
+};
+/**
+* Map a VineJS-style 422 error body into the
+* `{ errors: { fieldName: VineError } }` shape that
+* react-admin's `<Form>` reads from `HttpError.body`.
+*
+* AdonisJS + VineJS typically produces `{ errors: [{ field, message, rule, ...}] }`.
+* Some setups return the bare array. Both are handled.
+*/
+const checkIfFormValidation = (ex) => {
+	if (ex.status === 400 || ex.status === 422) {
+		const body = ex.body;
+		const list = Array.isArray(body) ? body : Array.isArray(body?.errors) ? body.errors : [];
+		if (list.length > 0) {
+			const errors = list.reduce((acc, curr) => {
+				if (curr && typeof curr.field === "string") acc[curr.field] = curr;
+				return acc;
+			}, {});
+			throw new HttpError(ex.message, ex.status, { errors });
+		}
+	}
+	throw ex;
+};
+const buildHeaders = (extra) => {
+	const headers = new Headers({ Accept: "application/json" });
+	if (extra) for (const [key, value] of Object.entries(extra)) headers.set(key, value);
+	return headers;
+};
+const unwrapList = (json) => {
+	const rows = Array.isArray(json?.data) ? json.data : [];
+	return {
+		rows,
+		total: typeof json?.metadata?.total === "number" ? json.metadata.total : typeof json?.meta?.total === "number" ? json.meta.total : rows.length
+	};
+};
+const unwrapItem = (json) => {
+	if (json === null || json === void 0) return json;
+	if (Object.prototype.hasOwnProperty.call(json, "data")) return json.data;
+	return json;
+};
+/**
+* React-admin data provider for APIs built with `@aginix/adonis-vulcan`.
+*
+* Endpoints expected (matches `Route.resource()` + `BaseResourceController`):
+*
+*     getList          GET    /<resource>?page=&perPage=&order=&<filters>
+*     getOne           GET    /<resource>/<id>
+*     getMany          GET    /<resource>?id=in.(...)&page=1&perPage=<count>
+*     getManyReference GET    /<resource>?<target>=eq.<id>&...
+*     create           POST   /<resource>
+*     update           PUT    /<resource>/<id>
+*     updateMany       PUT    /<resource>/<id>   (looped)
+*     delete           DELETE /<resource>/<id>
+*     deleteMany       DELETE /<resource>/<id>   (looped)
+*
+* Response envelopes:
+*
+*     list   { data: T[], metadata: { total, perPage, currentPage, lastPage, ... } }
+*     single { data: T }
+*     destroy 204 No Content
+*/
+const vulcanDataProvider = (config) => {
+	const { apiUrl, httpClient, defaultListOp = "eq", sortOrder, primaryKeys, pageParam = "page", perPageParam = "perPage" } = config;
+	const stringify = (q) => qs.stringify(q);
+	const sendList = async (url, options, primaryKey) => {
+		const { json } = await runRequest(httpClient, url, options);
+		const { rows, total } = unwrapList(json);
+		return {
+			data: rows.map((row) => dataWithVirtualId(row, primaryKey)),
+			total
+		};
+	};
+	return {
+		getList: async (resource, params) => {
+			const primaryKey = getPrimaryKey(resource, primaryKeys);
+			const { page = 1, perPage = 25 } = params.pagination ?? {};
+			const { field, order } = params.sort ?? {};
+			const { filter } = parseFilters(params, defaultListOp);
+			const query = {
+				[pageParam]: page,
+				[perPageParam]: perPage,
+				...filter
+			};
+			if (field) query.order = getOrderBy(field, order, primaryKey, sortOrder);
+			return sendList(`${apiUrl}/${resource}?${stringify(query)}`, { headers: buildHeaders(params.meta?.headers) }, primaryKey);
+		},
+		getOne: async (resource, params) => {
+			const primaryKey = getPrimaryKey(resource, primaryKeys);
+			const { json } = await runRequest(httpClient, `${apiUrl}/${resource}/${encodeURIComponent(String(params.id))}`, { headers: buildHeaders(params.meta?.headers) });
+			return { data: dataWithVirtualId(unwrapItem(json), primaryKey) };
+		},
+		getMany: async (resource, params) => {
+			if (!params.ids || params.ids.length === 0) return { data: [] };
+			const primaryKey = getPrimaryKey(resource, primaryKeys);
+			const { data } = await sendList(`${apiUrl}/${resource}?${stringify({
+				...getQuery(primaryKey, params.ids),
+				[pageParam]: 1,
+				[perPageParam]: params.ids.length
+			})}`, { headers: buildHeaders(params.meta?.headers) }, primaryKey);
+			return { data };
+		},
+		getManyReference: async (resource, params) => {
+			const primaryKey = getPrimaryKey(resource, primaryKeys);
+			const { page = 1, perPage = 25 } = params.pagination ?? {};
+			const { field, order } = params.sort ?? {};
+			const { filter } = parseFilters(params, defaultListOp);
+			const query = {
+				...params.target ? { [params.target]: `eq.${params.id}` } : {},
+				[pageParam]: page,
+				[perPageParam]: perPage,
+				...filter
+			};
+			if (field) query.order = getOrderBy(field, order, primaryKey, sortOrder);
+			return sendList(`${apiUrl}/${resource}?${stringify(query)}`, { headers: buildHeaders(params.meta?.headers) }, primaryKey);
+		},
+		create: async (resource, params) => {
+			const primaryKey = getPrimaryKey(resource, primaryKeys);
+			const url = `${apiUrl}/${resource}`;
+			const body = JSON.stringify(dataWithoutVirtualId(params.data, primaryKey));
+			try {
+				const { json } = await runRequest(httpClient, url, {
+					method: "POST",
+					headers: buildHeaders({
+						"Content-Type": "application/json",
+						...params.meta?.headers ?? {}
+					}),
+					body
+				});
+				return { data: dataWithVirtualId(unwrapItem(json), primaryKey) };
+			} catch (ex) {
+				return checkIfFormValidation(ex);
+			}
+		},
+		update: async (resource, params) => {
+			const primaryKey = getPrimaryKey(resource, primaryKeys);
+			const url = `${apiUrl}/${resource}/${encodeURIComponent(String(params.id))}`;
+			const data = params.data;
+			const previousData = params.previousData ?? {};
+			const changed = computeChanges(data, previousData);
+			if (Object.keys(changed).length === 0) return { data: { ...previousData } };
+			const body = JSON.stringify(dataWithoutVirtualId(removePrimaryKey(changed, primaryKey), primaryKey));
+			try {
+				const { json } = await runRequest(httpClient, url, {
+					method: "PUT",
+					headers: buildHeaders({
+						"Content-Type": "application/json",
+						...params.meta?.headers ?? {}
+					}),
+					body
+				});
+				return { data: dataWithVirtualId(unwrapItem(json), primaryKey) };
+			} catch (ex) {
+				return checkIfFormValidation(ex);
+			}
+		},
+		updateMany: async (resource, params) => {
+			const primaryKey = getPrimaryKey(resource, primaryKeys);
+			const data = params.data;
+			const body = JSON.stringify(dataWithoutVirtualId(removePrimaryKey(data, primaryKey), primaryKey));
+			const headers = buildHeaders({
+				"Content-Type": "application/json",
+				...params.meta?.headers ?? {}
+			});
+			const ids = params.ids ?? [];
+			return { data: await Promise.all(ids.map((id) => runRequest(httpClient, `${apiUrl}/${resource}/${encodeURIComponent(String(id))}`, {
+				method: "PUT",
+				headers,
+				body
+			}).then(({ json }) => encodeId(unwrapItem(json), primaryKey)))) };
+		},
+		delete: async (resource, params) => {
+			const primaryKey = getPrimaryKey(resource, primaryKeys);
+			const { json } = await runRequest(httpClient, `${apiUrl}/${resource}/${encodeURIComponent(String(params.id))}`, {
+				method: "DELETE",
+				headers: buildHeaders(params.meta?.headers)
+			});
+			const fallback = params.previousData ?? { id: params.id };
+			return { data: json ? dataWithVirtualId(unwrapItem(json), primaryKey) : fallback };
+		},
+		deleteMany: async (resource, params) => {
+			const headers = buildHeaders(params.meta?.headers);
+			const ids = params.ids ?? [];
+			await Promise.all(ids.map((id) => runRequest(httpClient, `${apiUrl}/${resource}/${encodeURIComponent(String(id))}`, {
+				method: "DELETE",
+				headers
+			})));
+			return { data: ids };
+		}
+	};
+};
+const runRequest = async (httpClient, url, options) => {
+	return { json: (await httpClient(url, options))?.json };
+};
+//#endregion
+export { vulcanDataProvider as default, vulcanDataProvider, defaultPrimaryKeys };

package/build/src/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The full set of PostgREST-style operators that the
+ * `@aginix/adonis-vulcan` filter pipeline understands.
+ *
+ * Mirrors the operator list in
+ * `@aginix/adonis-vulcan`'s `FilterParser` (`OPERATOR_PATTERN` / `OPERATOR_SQL_MAP`)
+ * plus the `not` / `or` / `and` modifiers that wrap conditions.
+ */
+export declare const VULCAN_OPERATORS: readonly ["eq", "gt", "gte", "lt", "lte", "neq", "like", "ilike", "match", "imatch", "in", "is", "fts", "plfts", "phfts", "wfts", "cs", "cd", "ov", "sl", "sr", "nxr", "nxl", "adj", "not", "or", "and"];
+export type VulcanOperator = (typeof VULCAN_OPERATORS)[number];
+/**
+ * Special path segments that may appear after a relation name when filtering
+ * embedded resources (e.g. `curriculums.exists=true`,
+ * `curriculums.order=name.asc`, `curriculums.limit=5`).
+ *
+ * These are passed through the URL as-is — no `eq.` / `in.` / etc. is
+ * prepended, because they are control parameters, not column filters.
+ */
+export declare const EMBEDDED_SPECIAL_KEYS: readonly ["exists", "order", "limit"];
+export type EmbeddedSpecialKey = (typeof EMBEDDED_SPECIAL_KEYS)[number];
+/**
+ * Order-by null handling. Format: `<asc-spec>,<desc-spec>` so that a single
+ * value covers both directions; the appropriate half is chosen depending on
+ * whether the user clicked an ASC or DESC sort header.
+ */
+export declare enum VulcanSortOrder {
+    AscendingNullsLastDescendingNullsFirst = "asc,desc",
+    AscendingNullsLastDescendingNullsLast = "asc,desc.nullslast",
+    AscendingNullsFirstDescendingNullsFirst = "asc.nullsfirst,desc",
+    AscendingNullsFirstDescendingNullsLast = "asc.nullsfirst,desc.nullslast"
+}
+/**
+ * A primary key descriptor. A single string (`['id']`) for the common case,
+ * or several strings for compound keys (`['org_id', 'sku']`). When the
+ * primary key is compound, the data provider synthesizes a virtual `id` field
+ * encoded as a JSON-stringified array of the key parts so react-admin can
+ * keep using its expected `id` lookup.
+ */
+export type PrimaryKey = readonly string[];
+/**
+ * Fetch-like signature compatible with `fetchUtils.fetchJson` from
+ * react-admin. Implementations resolve with `{ status, headers, body, json }`
+ * for 2xx responses and reject with an `HttpError` otherwise.
+ */
+export type HttpClient = (url: string, options?: HttpClientOptions) => Promise<HttpClientResponse>;
+export interface HttpClientOptions {
+    method?: string;
+    headers?: Headers;
+    body?: string | null;
+    user?: {
+        authenticated?: boolean;
+        token?: string;
+    };
+    [key: string]: unknown;
+}
+export interface HttpClientResponse {
+    status: number;
+    headers: Headers;
+    body: string;
+    json?: any;
+}
+export interface VulcanDataProviderConfig {
+    /**
+     * Base URL of the API. e.g. `https://api.example.com` or `/api`. The
+     * resource name is appended directly: `<apiUrl>/<resource>`.
+     */
+    apiUrl: string;
+    /**
+     * Fetch-compatible function used for every request. Most consumers pass
+     * `fetchUtils.fetchJson` from `react-admin`, optionally wrapped with auth
+     * headers.
+     */
+    httpClient: HttpClient;
+    /**
+     * Operator applied to filter values that don't specify one explicitly via
+     * the `field@op` syntax. Defaults to `eq`.
+     */
+    defaultListOp?: VulcanOperator;
+    /**
+     * Null handling for ASC / DESC sorts. Defaults to
+     * `AscendingNullsLastDescendingNullsFirst` (`asc` / `desc`), which mirrors
+     * PostgreSQL's default ordering.
+     */
+    sortOrder?: VulcanSortOrder;
+    /**
+     * Per-resource primary key overrides. Resources missing from the map fall
+     * back to `['id']`.
+     */
+    primaryKeys?: Map<string, PrimaryKey>;
+    /**
+     * Pagination input names used by the `BaseResourceController`. Override
+     * here when a controller customizes `pagination.pageInput` /
+     * `perPageInput`. Defaults to `page` / `perPage`.
+     */
+    pageParam?: string;
+    perPageParam?: string;
+}

package/build/src/types.js

@@ -0,0 +1,65 @@
+//#region src/types.ts
+/**
+* The full set of PostgREST-style operators that the
+* `@aginix/adonis-vulcan` filter pipeline understands.
+*
+* Mirrors the operator list in
+* `@aginix/adonis-vulcan`'s `FilterParser` (`OPERATOR_PATTERN` / `OPERATOR_SQL_MAP`)
+* plus the `not` / `or` / `and` modifiers that wrap conditions.
+*/
+const VULCAN_OPERATORS = [
+	"eq",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"neq",
+	"like",
+	"ilike",
+	"match",
+	"imatch",
+	"in",
+	"is",
+	"fts",
+	"plfts",
+	"phfts",
+	"wfts",
+	"cs",
+	"cd",
+	"ov",
+	"sl",
+	"sr",
+	"nxr",
+	"nxl",
+	"adj",
+	"not",
+	"or",
+	"and"
+];
+/**
+* Special path segments that may appear after a relation name when filtering
+* embedded resources (e.g. `curriculums.exists=true`,
+* `curriculums.order=name.asc`, `curriculums.limit=5`).
+*
+* These are passed through the URL as-is — no `eq.` / `in.` / etc. is
+* prepended, because they are control parameters, not column filters.
+*/
+const EMBEDDED_SPECIAL_KEYS = [
+	"exists",
+	"order",
+	"limit"
+];
+/**
+* Order-by null handling. Format: `<asc-spec>,<desc-spec>` so that a single
+* value covers both directions; the appropriate half is chosen depending on
+* whether the user clicked an ASC or DESC sort header.
+*/
+let VulcanSortOrder = /* @__PURE__ */ function(VulcanSortOrder) {
+	VulcanSortOrder["AscendingNullsLastDescendingNullsFirst"] = "asc,desc";
+	VulcanSortOrder["AscendingNullsLastDescendingNullsLast"] = "asc,desc.nullslast";
+	VulcanSortOrder["AscendingNullsFirstDescendingNullsFirst"] = "asc.nullsfirst,desc";
+	VulcanSortOrder["AscendingNullsFirstDescendingNullsLast"] = "asc.nullsfirst,desc.nullslast";
+	return VulcanSortOrder;
+}({});
+//#endregion
+export { EMBEDDED_SPECIAL_KEYS, VULCAN_OPERATORS, VulcanSortOrder };

package/build/src/url_builder.d.ts

@@ -0,0 +1,60 @@
+import type { Identifier, SortPayload } from 'ra-core';
+import { type PrimaryKey, type VulcanOperator, VulcanSortOrder } from './types.js';
+export type ParsedFilters = {
+    /**
+     * A flat record of query-string keys to either a single
+     * `<op>.<value>` string (or `(child1,child2)` for `and`/`or`) or an array of
+     * those strings when the same key needs to repeat — `qs.stringify` will
+     * expand the array into `field=foo&field=bar`, which the server-side
+     * `FilterParser` joins back into an AND.
+     */
+    filter: Record<string, string | string[]>;
+};
+/**
+ * Translate a react-admin `filter` object into the PostgREST-style
+ * query-string fragment understood by `@aginix/adonis-vulcan`'s
+ * `FilterParser`.
+ *
+ * Conventions:
+ *
+ * - `field: value` becomes `field=<defaultListOp>.<value>` (default `eq`).
+ * - `field@op: value` overrides the operator (e.g. `age@gt: 18`).
+ * - Array values map to `field=in.(v1,v2,v3)`.
+ * - `like` / `ilike` split the value on whitespace and emit one
+ *   `field=like.*token*` per token, which `qs.stringify` turns into repeated
+ *   keys (joined with AND server-side).
+ * - `or` / `and` keys recurse and emit `or=(c1.<op>.v1,c2.<op>.v2)`.
+ * - The `q` key is a free-form search term — it is forwarded verbatim
+ *   (`q=value`), so a filter subclass on the server side can take it via the
+ *   "custom method takes precedence" hook of `PostgRESTModelFilter`.
+ * - Embedded special keys (e.g. `curriculums.exists`) are forwarded verbatim
+ *   as well — no operator is prepended.
+ */
+export declare const parseFilters: (params: {
+    filter?: Record<string, any>;
+}, defaultListOp?: VulcanOperator) => ParsedFilters;
+export declare const getPrimaryKey: (resource: string, primaryKeys?: Map<string, PrimaryKey>) => PrimaryKey;
+export declare const decodeId: (id: Identifier, primaryKey: PrimaryKey) => string[] | number[];
+export declare const encodeId: (data: Record<string, unknown>, primaryKey: PrimaryKey) => Identifier;
+export declare const removePrimaryKey: (data: Record<string, unknown>, primaryKey: PrimaryKey) => Record<string, unknown>;
+/**
+ * For compound primary keys, attach a synthetic `id` so react-admin can rely
+ * on its standard record-by-id flow. No-op for the regular `['id']` case.
+ */
+export declare const dataWithVirtualId: <T extends Record<string, unknown>>(data: T, primaryKey: PrimaryKey) => T;
+/**
+ * Strip the synthetic `id` field before sending a payload back to the server.
+ */
+export declare const dataWithoutVirtualId: (data: Record<string, unknown>, primaryKey: PrimaryKey) => Record<string, unknown>;
+/**
+ * Build the filter fragment that selects records by primary key. Works for
+ * single ids, multiple ids, and compound primary keys. Used by
+ * `getMany`, `updateMany`, and `deleteMany` to address rows in bulk.
+ */
+export declare const getQuery: (primaryKey: PrimaryKey, ids: Identifier | readonly Identifier[] | undefined) => Record<string, string | string[]>;
+/**
+ * Format `field` + `order` (`'ASC' | 'DESC'`) into the `order=...` value
+ * understood by `FilterParser`. When the sort field is the synthetic `id` and
+ * the resource has a compound primary key, expand it across each key part.
+ */
+export declare const getOrderBy: (field: string, order: SortPayload["order"] | undefined, primaryKey: PrimaryKey, sortOrder?: VulcanSortOrder) => string;

package/build/src/url_builder.js

@@ -0,0 +1,168 @@
+import { EMBEDDED_SPECIAL_KEYS } from "./types.js";
+//#region src/url_builder.ts
+const isObject = (obj) => typeof obj === "object" && !Array.isArray(obj) && obj !== null;
+const resolveKeys = (filter, keys) => {
+	let result = filter[keys[0]];
+	for (let i = 1; i < keys.length; ++i) result = result[keys[i]];
+	return result;
+};
+/**
+* `curriculums.exists` / `faculty.order` / etc. The last dotted segment must
+* match one of the `EMBEDDED_SPECIAL_KEYS`.
+*/
+const isEmbeddedSpecialKey = (key) => {
+	const parts = key.split(".");
+	if (parts.length < 2) return false;
+	const last = parts[parts.length - 1].toLowerCase();
+	return EMBEDDED_SPECIAL_KEYS.includes(last);
+};
+const isCompoundKey = (primaryKey) => primaryKey.length > 1;
+/**
+* Translate a react-admin `filter` object into the PostgREST-style
+* query-string fragment understood by `@aginix/adonis-vulcan`'s
+* `FilterParser`.
+*
+* Conventions:
+*
+* - `field: value` becomes `field=<defaultListOp>.<value>` (default `eq`).
+* - `field@op: value` overrides the operator (e.g. `age@gt: 18`).
+* - Array values map to `field=in.(v1,v2,v3)`.
+* - `like` / `ilike` split the value on whitespace and emit one
+*   `field=like.*token*` per token, which `qs.stringify` turns into repeated
+*   keys (joined with AND server-side).
+* - `or` / `and` keys recurse and emit `or=(c1.<op>.v1,c2.<op>.v2)`.
+* - The `q` key is a free-form search term — it is forwarded verbatim
+*   (`q=value`), so a filter subclass on the server side can take it via the
+*   "custom method takes precedence" hook of `PostgRESTModelFilter`.
+* - Embedded special keys (e.g. `curriculums.exists`) are forwarded verbatim
+*   as well — no operator is prepended.
+*/
+const parseFilters = (params, defaultListOp = "eq") => {
+	const filter = params.filter ?? {};
+	const result = { filter: {} };
+	Object.keys(filter).forEach((rawKey) => {
+		let key = rawKey;
+		let keyArray = [key];
+		let values;
+		if (key.split("@")[0] !== "" && isObject(filter[key])) {
+			let innerVal = filter[key];
+			while (isObject(innerVal)) {
+				const [innerKey] = Object.keys(innerVal);
+				keyArray.push(innerKey);
+				innerVal = innerVal[innerKey];
+			}
+			key = keyArray.join(".");
+			values = [innerVal];
+		} else values = [filter[rawKey]];
+		const splitKey = key.split("@");
+		const filterKey = splitKey[0];
+		const filterValue = filter[rawKey];
+		const isArrayValue = Array.isArray(filterValue);
+		const operation = (() => {
+			if (splitKey.length === 2) return splitKey[1];
+			if (key[0] === "$") return "";
+			if (filterKey === "q") return "";
+			if (isEmbeddedSpecialKey(filterKey)) return "";
+			if (isArrayValue) return "in";
+			return defaultListOp;
+		})();
+		if (operation === "like" || operation === "ilike") {
+			const raw = resolveKeys(filter, keyArray);
+			values = String(raw).trim().split(/\s+/);
+		} else if (operation === "or" || operation === "and") {
+			const subResult = parseFilters({ filter: resolveKeys(filter, keyArray) }, defaultListOp);
+			const expressions = [];
+			Object.entries(subResult.filter).forEach(([subKey, val]) => {
+				if (Array.isArray(val)) expressions.push(...val.map((v) => [subKey, v].join(".")));
+				else expressions.push([subKey, val].join("."));
+			});
+			values = [`(${expressions.join(",")})`];
+		}
+		if (isArrayValue && operation === "in") {
+			result.filter[filterKey] = `in.(${filterValue.join(",")})`;
+			return;
+		}
+		values.forEach((value) => {
+			const op = (() => {
+				if (operation.length === 0) return `${value}`;
+				if (operation.includes("like")) return `${operation}.*${value}*`;
+				if (operation === "and" || operation === "or") return `${value}`;
+				return `${operation}.${value}`;
+			})();
+			const writeKey = operation === "and" || operation === "or" ? operation : filterKey;
+			const existing = result.filter[writeKey];
+			if (existing === void 0) result.filter[writeKey] = op;
+			else if (Array.isArray(existing)) existing.push(op);
+			else result.filter[writeKey] = [existing, op];
+		});
+	});
+	return result;
+};
+const getPrimaryKey = (resource, primaryKeys) => {
+	return primaryKeys?.get(resource) ?? ["id"];
+};
+const decodeId = (id, primaryKey) => {
+	if (isCompoundKey(primaryKey)) return JSON.parse(id.toString());
+	return [id.toString()];
+};
+const encodeId = (data, primaryKey) => {
+	if (isCompoundKey(primaryKey)) return JSON.stringify(primaryKey.map((key) => data[key]));
+	return data[primaryKey[0]];
+};
+const removePrimaryKey = (data, primaryKey) => {
+	const next = { ...data };
+	primaryKey.forEach((key) => {
+		delete next[key];
+	});
+	return next;
+};
+/**
+* For compound primary keys, attach a synthetic `id` so react-admin can rely
+* on its standard record-by-id flow. No-op for the regular `['id']` case.
+*/
+const dataWithVirtualId = (data, primaryKey) => {
+	if (primaryKey.length === 1 && primaryKey[0] === "id") return data;
+	return Object.assign(data, { id: encodeId(data, primaryKey) });
+};
+/**
+* Strip the synthetic `id` field before sending a payload back to the server.
+*/
+const dataWithoutVirtualId = (data, primaryKey) => {
+	if (primaryKey.length === 1 && primaryKey[0] === "id") return data;
+	const next = { ...data };
+	delete next.id;
+	return next;
+};
+/**
+* Build the filter fragment that selects records by primary key. Works for
+* single ids, multiple ids, and compound primary keys. Used by
+* `getMany`, `updateMany`, and `deleteMany` to address rows in bulk.
+*/
+const getQuery = (primaryKey, ids) => {
+	if (Array.isArray(ids) && ids.length > 1) {
+		if (isCompoundKey(primaryKey)) return { or: `(${ids.map((id) => {
+			const parts = decodeId(id, primaryKey);
+			return `and(${primaryKey.map((key, i) => `${key}.eq.${parts[i]}`).join(",")})`;
+		}).join(",")})` };
+		return { [primaryKey[0]]: `in.(${ids.join(",")})` };
+	}
+	if (ids !== void 0 && ids !== null) {
+		const id = (Array.isArray(ids) ? ids[0] : ids).toString();
+		const parts = decodeId(id, primaryKey);
+		if (isCompoundKey(primaryKey)) return { and: `(${primaryKey.map((key, i) => `${key}.eq.${parts[i]}`).join(",")})` };
+		return { [primaryKey[0]]: `eq.${id}` };
+	}
+	return {};
+};
+/**
+* Format `field` + `order` (`'ASC' | 'DESC'`) into the `order=...` value
+* understood by `FilterParser`. When the sort field is the synthetic `id` and
+* the resource has a compound primary key, expand it across each key part.
+*/
+const getOrderBy = (field, order, primaryKey, sortOrder = "asc,desc") => {
+	const direction = sortOrder.split(",")[order === "ASC" ? 0 : 1];
+	if (field === "id") return primaryKey.map((key) => `${key}.${direction}`).join(",");
+	return `${field}.${direction}`;
+};
+//#endregion
+export { dataWithVirtualId, dataWithoutVirtualId, decodeId, encodeId, getOrderBy, getPrimaryKey, getQuery, parseFilters, removePrimaryKey };

package/package.json

@@ -0,0 +1,149 @@
+{
+  "name": "@aginix/vulcan-data-provider",
+  "description": "React Admin data provider for APIs built with @aginix/adonis-vulcan",
+  "version": "0.1.0",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "type": "module",
+  "files": [
+    "build",
+    "!build/bin",
+    "!build/tests"
+  ],
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    },
+    "./url_builder": {
+      "types": "./build/src/url_builder.d.ts",
+      "default": "./build/src/url_builder.js"
+    },
+    "./types": {
+      "types": "./build/src/types.d.ts",
+      "default": "./build/src/types.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "quick:test": "node --import=@poppinss/ts-exec --enable-source-maps bin/test.ts",
+    "pretest": "npm run lint",
+    "test": "c8 npm run quick:test",
+    "precompile": "npm run lint",
+    "compile": "tsdown && tsc --emitDeclarationOnly --declaration",
+    "build": "npm run compile",
+    "release": "release-it",
+    "version": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "react-admin",
+    "data-provider",
+    "adonisjs",
+    "adonis",
+    "vulcan",
+    "postgrest",
+    "rest",
+    "api"
+  ],
+  "author": "n3n",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "dequal": "^2.0.3",
+    "qs": "^6.14.0"
+  },
+  "devDependencies": {
+    "@adonisjs/eslint-config": "^3.0.0",
+    "@adonisjs/prettier-config": "^1.4.5",
+    "@adonisjs/tsconfig": "^2.0.0",
+    "@japa/assert": "^4.2.0",
+    "@japa/runner": "^5.3.0",
+    "@poppinss/ts-exec": "^1.4.4",
+    "@release-it/conventional-changelog": "^10.0.5",
+    "@types/node": "^25.3.5",
+    "@types/qs": "^6.9.18",
+    "c8": "^11.0.0",
+    "eslint": "^10.0.3",
+    "prettier": "^3.8.1",
+    "ra-core": "^5.0.0",
+    "react-admin": "^5.0.0",
+    "release-it": "^19.2.4",
+    "tsdown": "^0.21.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "ra-core": "^5.0.0",
+    "react-admin": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-admin": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "tsdown": {
+    "entry": [
+      "./index.ts",
+      "./src/types.ts",
+      "./src/url_builder.ts",
+      "./src/data_provider.ts"
+    ],
+    "outDir": "./build",
+    "clean": true,
+    "format": "esm",
+    "minify": "dce-only",
+    "fixedExtension": false,
+    "dts": false,
+    "treeshake": false,
+    "sourcemaps": false,
+    "target": "esnext",
+    "external": [
+      "ra-core",
+      "react-admin",
+      "qs",
+      "dequal"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "requireCleanWorkingDir": true,
+      "requireUpstream": true,
+      "commitMessage": "chore(vulcan-data-provider): release ${version}",
+      "tagAnnotation": "vulcan-data-provider-v${version}",
+      "push": true,
+      "tagName": "vulcan-data-provider-v${version}"
+    },
+    "github": {
+      "release": true,
+      "releaseName": "@aginix/vulcan-data-provider ${version}"
+    },
+    "npm": {
+      "publish": true,
+      "skipChecks": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "c8": {
+    "reporter": [
+      "text",
+      "html"
+    ],
+    "exclude": [
+      "tests/**"
+    ]
+  },
+  "prettier": "@adonisjs/prettier-config"
+}