@raphiniert/ra-data-postgrest 2.0.0-alpha.1 → 2.0.0-alpha.3

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 Find all notable changes of this project in this file.
 
+## v2.0.0-alpha.3 - 2023-06-16
+### Improvements
+- updated dependencies
+
+### New feature
+- [#82](https://github.com/raphiniert-com/ra-data-postgrest/pull/82), add logical operator filter parsing - @[jordiyapz](https://github.com/jordiyapz)
+
+### Fixes
+- [#81](https://github.com/raphiniert-com/ra-data-postgrest/pull/81), use {} with cs and cd operators url - @[YannBeauxis](https://github.com/YannBeauxis)
+
+### Breaking changes
+- Changed from from regular parameters to instantiate the dataProvider to a configuration interface/class. Thus, in future initalize the dataProvider by creating a structure which implements the interface:
+
+```jsx
+import { fetchUtils } from 'react-admin';
+import postgrestRestProvider, 
+    { IDataProviderConfig, 
+      defaultPrimaryKeys, 
+      defaultSchema } from '@raphiniert/ra-data-postgrest';
+
+const config: IDataProviderConfig = {
+    apiUrl: 'http://path.to.my.api/',
+    httpClient: fetchUtils.fetchJson,
+    defaultListOp: 'eq',
+    primaryKeys: defaultPrimaryKeys,
+    schema: defaultSchema
+}
+
+dp = postgrestRestProvider(config);
+```
+
+## v2.0.0-alpha.2 - 2023-04-24
+### Improvements
+- updated dependencies
+
+### New feature
+- [#49](https://github.com/raphiniert-com/ra-data-postgrest/issues/49), custom schema name can be used
+
 ## v2.0.0-alpha.1 - 2023-04-09
 ### Improvements
 - updated dependencies

package/IDEAS.md

@@ -0,0 +1,46 @@
+Here's a list of customizations that I have implemented locally in an old local version of ra-data-postgrest. The gaps in the numbers means it has already been imlemented in master. My customizations are relatively low quality and without tests. I thought I'd leave it here with you for inspiration or maybe it has overlap with one of the thins you want to work on.
+- 1: Allowing calls like dataProvider.getOne('rpc/xxx') that actually returns a single object
+- 6: column filtering voor getOne en getMany
+- 8: Be able to use useGetOne with an array of ids for rpc/xxx functions
+- 8b: Be able to use useGetMany with an array of ids for rpc/xxx functions
+- 9: Be able to use useGetList with rpc functions (that return a list)
+- 10: we could do null valued parameters, but undefined valued paramters do not make sense to pass to Postgrest
+- 11: be able to filter on an array of values (and use 'in' operator by default)
+- 12: be able to sort on multiple fields
+- 13: with calls to getOne using rpc functions do not use eq.xxx but simply xxx
+- 17: Allow a null response with getManyReference instead of an empty array (because that's what som of my rpcs return)
+Some might be so niche that you should ignore them and that I instead should actually implement in a decorator (a function that alters the params a bit before the dataprovider function is called)
+
+
+About the decorator. Not sure if know how to use it, but I use it like this:
+```jsx
+import { CreateParams, DataProvider } from 'react-admin';
+
+/**
+ * Gives opportunity to alter method, resource and params before calling the original dataProvider
+ */
+export const decorator = (dataProvider: DataProvider) => ({
+	...dataProvider,
+	create: (originalResource: string, originalParams: CreateParams) => {
+		const method = 'create';
+
+		const newParams = {
+			...originalParams,
+			// alterations
+		}
+
+		return dataProvider[method](originalResource, newParams);
+	},
+});
+```
+
+And then to use it.
+```jsx
+const restClient = postgrestRestProvider(
+    httpClientApi,
+    defaultListOp,
+    resourcePimaryKeys
+);
+
+export const dataProvider = decorator(restClient);
+```

package/README.md

@@ -47,14 +47,25 @@ Access-Control-Expose-Headers: Content-Range
 
 ```jsx
 // in src/App.js
-import React from 'react';
-import { Admin, Resource } from 'react-admin';
-import postgrestRestProvider from '@raphiniert/ra-data-postgrest';
+import * as React from 'react';
+import { Admin, Resource, fetchUtils } from 'react-admin';
+import postgrestRestProvider, 
+     { IDataProviderConfig, 
+       defaultPrimaryKeys, 
+       defaultSchema } from '@raphiniert/ra-data-postgrest';
 
 import { PostList } from './posts';
 
+const config: IDataProviderConfig = {
+    apiUrl: 'http://path.to.my.api/',
+    httpClient: fetchUtils.fetchJson,
+    defaultListOp: 'eq',
+    primaryKeys: defaultPrimaryKeys,
+    schema: defaultSchema
+}
+
 const App = () => (
-    <Admin dataProvider={postgrestRestProvider('http://path.to.my.api/')}>
+    <Admin dataProvider={postgrestRestProvider(config)}>
         <Resource name="posts" list={PostList} />
     </Admin>
 );
@@ -80,7 +91,14 @@ const httpClient = (url, options = {}) => {
     options.headers.set('X-Custom-Header', 'foobar');
     return fetchUtils.fetchJson(url, options);
 };
-const dataProvider = postgrestRestProvider('http://localhost:3000', httpClient);
+
+const config: IDataProviderConfig = {
+    ...
+    httpClient: httpClient,
+    ...
+}
+
+const dataProvider = postgrestRestProvider(config);
 
 render(
     <Admin dataProvider={dataProvider} title="Example Admin">
@@ -137,22 +155,36 @@ Given a RPC call as `GET /rpc/add_them?post_author=Herbert HTTP/1.1`, the dataPr
 If one has data resources without primary keys named `id`, one will have to define this specifically. Also, if there is a primary key, which is defined over multiple columns:
 
 ```jsx
-const dataProvider = postgrestRestProvider(
-    API_URL,
-    fetchUtils.fetchJson,
-    'eq',
-    new Map([
+const config: IDataProviderConfig = {
+    ...
+    primaryKeys: new Map([
         ['some_table', ['custom_id']],
         ['another_table', ['first_column', 'second_column']],
-    ])
-);
+    ]),
+    ...
+}
+
+const dataProvider = postgrestRestProvider(config);
+```
+
+### Custom schema
+PostgREST allows to [select and switch the database schema](https://postgrest.org/en/stable/api.html#switching-schemas) by setting a custom header. Thus, one way to use this function would be adding the custom header as a string while using react-admin hooks within `meta.schema` (compare to next section) or to set it up as function of `() => (string)` while using the data provider just component based. The latter can be done as follows and gives the opportunity to use some central storage (e.g. localStorage) which can be changed at multiple points of the application:
+```jsx
+const config: IDataProviderConfig = {
+    ...
+    schema: localStorage.getItem("schema") || "api",
+    ...
+}
+
+const dataProvider = postgrestRestProvider(config);
 ```
 
 ### Passing extra headers via meta
 Postgrest supports calling functions with a single JSON parameter by sending the header Prefer: params=single-object with your request according to its [docs](https://postgrest.org/en/stable/api.html#calling-functions-with-a-single-json-parameter).
 
 Within the data provider one can add any kind of header to the request while calling react-admin hooks, e.g.:
-```
+
+```jsx
 const [create, { isLoading, error }] = useCreate(
     'rpc/my-function',
     {
@@ -164,7 +196,8 @@ const [create, { isLoading, error }] = useCreate(
 
 ### Vertical filtering
 Postgrest supports a feature of [Vertical Filtering (Columns)](https://postgrest.org/en/stable/api.html#vertical-filtering-columns). Within the react-admin hooks this feature can be used as in the following example:
-```
+
+```jsx
 const { data, total, isLoading, error } = useGetList(
     'posts',
     { 
@@ -176,15 +209,15 @@ const { data, total, isLoading, error } = useGetList(
 ```
 
 Further, one should be able to leverage this feature to rename columns:
-```
+```jsx
 columns: ['id', 'somealias:title']
 ```
 , to cast columns:
-```
+```jsx
 columns: ['id::text', 'title']
 ```
 and even get bits from a json or jsonb column"
-```
+```jsx
 columns: ['id', 'json_data->>blood_type', 'json_data->phones']
 ```
 

package/esm/index.d.ts

@@ -1,9 +1,60 @@
-import { fetchUtils, DataProvider } from 'ra-core';
+import { DataProvider } from 'ra-core';
 import { PrimaryKey, PostgRestOperator } from './urlBuilder';
-declare const _default: (apiUrl: string, httpClient?: (url: any, options?: fetchUtils.Options) => Promise<{
-    status: number;
-    headers: Headers;
-    body: string;
-    json: any;
-}>, defaultListOp?: PostgRestOperator, primaryKeys?: Map<string, PrimaryKey>) => DataProvider;
+/**
+ * Maps react-admin queries to a postgrest REST API
+ *
+ * This REST dialect uses postgrest syntax
+ *
+ * @see https://postgrest.org/en/stable/api.html#embedded-filters
+ *
+ * @example
+ *
+ * getList          => GET    http://my.api.url/posts?order=title.asc&offset=0&limit=24&filterField=eq.value
+ * getOne           => GET    http://my.api.url/posts?id=eq.123
+ * getMany          => GET    http://my.api.url/posts?id=in.(123,456,789)
+ * getManyReference => GET    http://my.api.url/posts?author_id=eq.345
+ * create           => POST   http://my.api.url/posts
+ * update           => PATCH  http://my.api.url/posts?id=eq.123
+ * updateMany       => PATCH  http://my.api.url/posts?id=in.(123,456,789)
+ * delete           => DELETE http://my.api.url/posts?id=eq.123
+ * deleteMany       => DELETE http://my.api.url/posts?id=in.(123,456,789)
+ *
+ * @example
+ *
+ * import * as React from 'react';
+ * import { Admin, Resource, fetchUtils } from 'react-admin';
+ * import postgrestRestProvider,
+ *      { IDataProviderConfig,
+ *        defaultPrimaryKeys,
+ *        defaultSchema } from '@raphiniert/ra-data-postgrest';
+ *
+ * import { PostList } from './posts';
+ *
+ * const config: IDataProviderConfig = {
+ *     apiUrl: 'http://path.to.my.api/',
+ *     httpClient: fetchUtils.fetchJson,
+ *     defaultListOp: 'eq',
+ *     primaryKeys: defaultPrimaryKeys,
+ *     schema: defaultSchema
+ * }
+ *
+ * const App = () => (
+ *     <Admin dataProvider={postgrestRestProvider(config)}>
+ *         <Resource name="posts" list={PostList} />
+ *     </Admin>
+ * );
+ *
+ * export default App;
+ */
+export type MetaOption = string | undefined;
+export declare const defaultPrimaryKeys: Map<string, PrimaryKey>;
+export declare const defaultSchema: () => string;
+export interface IDataProviderConfig {
+    apiUrl: string;
+    httpClient: (string: any, Options: any) => Promise<any>;
+    defaultListOp: PostgRestOperator;
+    primaryKeys: Map<string, PrimaryKey>;
+    schema: () => string;
+}
+declare const _default: (config: IDataProviderConfig) => DataProvider;
 export default _default;