@plone/client - npm Package Compare versions

Comparing version 1.0.0-alpha.3 to 1.0.0-alpha.4

package.json

@@ -12,3 +12,3 @@ {
   "license": "MIT",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "repository": {
@@ -50,3 +50,3 @@ "type": "git",
     "build": "vite build",
-    "test": "vitest --no-threads",
+    "test": "node testRunner.js",
     "check-ts": "tsc --project tsconfig.json",
@@ -71,2 +71,3 @@ "coverage": "vitest run --coverage --no-threads",
     "@types/react-dom": "18.0.11",
+    "@types/uuid": "^9.0.2",
     "@typescript-eslint/eslint-plugin": "5.57.1",
@@ -86,2 +87,3 @@ "@typescript-eslint/parser": "5.57.1",
     "typescript": "5.0.4",
+    "uuid": "^9.0.0",
     "vite": "^4.3.8",
@@ -88,0 +90,0 @@ "vite-plugin-dts": "^2.3.0",

README.md

@@ -6,9 +6,105 @@ # @plone/client
 [![Build Status](https://github.com/plone/plone.restapi-client/actions/workflows/unit.yml/badge.svg)](https://github.com/plone/plone.restapi-client/actions)
+[![Documentation Status](https://readthedocs.org/projects/plone-client/badge/?version=latest)](https://plone-client.readthedocs.io/en/latest/?badge=latest)
 
-This package is an agnostic client written in TypeScript and built on the top of [@tanstack/query](https://tanstack.com/query) to query Plone 6 backend.
+## Introduction
 
+The Javascript Plone client is an agnostic library that provides easy access to the Plone REST API from a client written in TypeScript.
+This client can be used as an alternative to directly interacting with the Plone REST API.
+It is based on the foundations that [@tanstack/query](https://tanstack.com/query) lays off.
 It should be possible to use it in React/Vue/Solid/Svelte projects.
+It provides the artifacts that TanStack Query requires to work:
 
-## File Structure
+- Query (or mutation) options factories
+- Query (or mutation) functions
+- API request layer
 
+The API request layer allows to build and send arbitrary requests to Plone REST API endpoints.
+It has the potential to also be able to send requests to other APIs (provided the custom Query options factories/functions).
+
+The Javascript Plone client is conceived to work with TanStack Query, the query or mutation functions can be used to call any Plone REST API endpoint without using it.
+These functions can be used in other use cases like command line helpers, scripts or programatic tests.
+
+## Installation​
+
+To install the Javascript Plone client run the following command:
+
+```shell
+yarn add @plone/client
+```
+
+## `ploneClient` entry point
+
+The main artifact that the client provides is the `ploneClient` entry point.
+
+Once imported, you should call `initialize` to setup its basic parameters, like `apiPath`, headers or authentication options.
+
+After initialization, you can import all the prorvided query options factories.
+
+```ts
+import ploneClient from '@plone/client';
+
+const client = ploneClient.initialize({
+  apiPath: 'http://localhost:8080/Plone',
+});
+```
+
+## Query (or mutation) options factories
+
+A query (or mutation) options factory is a TanStack Query basic artifact, a function that returns an object, ready to be passed to a React Query hook (in case that we are in a React environment) or to the TanStack Query adapter that we are using in our framework.
+
+```ts
+import { useQuery } from '@tanstack/react-query';
+
+const { getContentQuery } = client;
+
+const { data, isLoading } = useQuery(getContentQuery({ path: pathname }));
+```
+
+The query (or mutation) factories ara functions that take an object as arguments.
+These arguments can have some common properties (like the path) and other specific depending on the nature of the endpoint that they are correspond with.
+
+This is a complete example of the usage of the client in a React client component:
+
+```jsx
+import { useQuery } from '@tanstack/react-query';
+import ploneClient from '@plone/client';
+import { usePathname } from 'next/navigation';
+
+const client = ploneClient.initialize({
+  apiPath: 'http://localhost:8080/Plone',
+});
+
+export default function Title() {
+  const { getContentQuery } = client;
+  const pathname = usePathname();
+  const { data, isLoading } = useQuery(getContentQuery({ path: pathname }));
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (data) {
+    return (
+      <div>
+        <h1>{data.title}</h1>
+      </div>
+    );
+  }
+
+  return '';
+}
+```
+
+## Plone Client React Hooks
+
+This package also provides custom hooks for actions that can be used directly in functional React components.
+
+```ts
+const { useGetContent } = client;
+
+const { data, isLoading } = useGetContent({ path: pathname });
+```
+
+## File Structure used
+
 The file structure should match the one in `plone.restapi` package, so it should be organized in folders one for each endpoint family, and following the convention naming depending on the action (add, get, update, delete).
@@ -23,3 +119,5 @@
 [plone.restapi](https://github.com/plone/plone.restapi)
+
 [plone.restapi documentation](https://plonerestapi.readthedocs.io/en/latest/)
+
 [Volto](https://github.com/plone/volto)

New alerts

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

454875

96.34%

Lines of code

11528

105.53%

Number of lines in readme file

122

408.33%

Worsened metrics

Dev dependency count

24

9.09%

Number of low supply chain risk alerts

10

Infinity%

No dependency changes