@leancodepl/react-query-cqrs-client 8.4.0 → 8.5.1

package/README.md

@@ -0,0 +1,155 @@
+# @leancodepl/react-query-cqrs-client
+
+TanStack Query CQRS client with hooks for queries, operations, and commands.
+
+## Features
+
+- **TanStack Query integration** - Built-in caching, optimistic updates, and background refetching
+- **CQRS pattern** - Separate queries, commands, and operations with proper typing
+- **Custom hooks** - Hook factories for all operation types with loading states
+- **Error handling** - Validation errors with custom error codes and handlers
+- **Authentication** - Token handling with automatic refresh integration
+- **Cache management** - Smart invalidation and query dependency management
+
+## Installation
+
+```bash
+npm install @leancodepl/react-query-cqrs-client
+# or
+yarn add @leancodepl/react-query-cqrs-client
+```
+
+## API
+
+### `mkCqrsClient(cqrsEndpoint, queryClient, tokenProvider, ajaxOptions, tokenHeader)`
+
+Creates TanStack Query CQRS client with hooks for queries, operations, and commands.
+
+**Parameters:**
+
+- `cqrsEndpoint: string` - Base URL for CQRS API endpoints
+- `queryClient: QueryClient` - TanStack Query client instance
+- `tokenProvider?: Partial<TokenProvider>` - Optional token provider for authentication
+- `ajaxOptions?: Omit<AjaxConfig, ...>` - Optional RxJS Ajax configuration options
+- `tokenHeader?: string` - Header name for authentication token (default: "Authorization")
+
+**Returns:** Object with `createQuery`, `createOperation`, and `createCommand` hook factories
+
+## Usage Examples
+
+### Basic Setup
+
+```typescript
+import { mkCqrsClient } from "@leancodepl/react-query-cqrs-client"
+import { QueryClient } from "@tanstack/react-query"
+
+const queryClient = new QueryClient()
+
+const client = mkCqrsClient({
+    cqrsEndpoint: "https://api.example.com",
+    queryClient,
+    tokenProvider: {
+        getToken: () => Promise.resolve(localStorage.getItem("token")),
+    },
+})
+```
+
+### Query Hook
+
+```typescript
+import React from 'react';
+
+interface GetUserQuery {
+  userId: string;
+}
+
+interface UserResult {
+  id: string;
+  name: string;
+  email: string;
+}
+
+const useGetUser = client.createQuery<GetUserQuery, UserResult>('GetUser');
+
+function UserProfile({ userId }: { userId: string }) {
+  const { data, isLoading, error } = useGetUser({ userId });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error loading user</div>;
+
+  return (
+    <div>
+      <h1>{data?.name}</h1>
+      <p>{data?.email}</p>
+    </div>
+  );
+}
+```
+
+### Command Hook
+
+```typescript
+import React from 'react';
+
+interface CreateUserCommand {
+  name: string;
+  email: string;
+}
+
+const errorCodes = { EmailExists: 1, InvalidEmail: 2 } as const;
+const useCreateUser = client.createCommand<CreateUserCommand, typeof errorCodes>('CreateUser', errorCodes);
+
+function CreateUserForm() {
+  const { mutate: createUser, isPending } = useCreateUser({
+    handler: (handle) =>
+      handle('success', () => 'User created successfully')
+        .handle('EmailExists', () => 'Email already exists')
+        .handle('failure', () => 'Failed to create user')
+        .check(),
+  });
+
+  const handleSubmit = () => {
+    createUser({ name: 'John', email: 'john@example.com' });
+  };
+
+  return (
+    <button onClick={handleSubmit} disabled={isPending}>
+      {isPending ? 'Creating...' : 'Create User'}
+    </button>
+  );
+}
+```
+
+### Operation Hook
+
+```typescript
+interface UploadFileOperation {
+  file: File;
+  folder: string;
+}
+
+interface UploadResult {
+  url: string;
+  filename: string;
+}
+
+const useUploadFile = client.createOperation<UploadFileOperation, UploadResult>('UploadFile');
+
+function FileUploader() {
+  const { mutate: uploadFile, isPending } = useUploadFile({
+    invalidateQueries: [['GetFiles']],
+  });
+
+  const handleUpload = (file: File) => {
+    uploadFile({ file, folder: 'documents' });
+  };
+
+  return (
+    <input
+      type="file"
+      onChange={(e) => e.target.files?.[0] && handleUpload(e.target.files[0])}
+      disabled={isPending}
+    />
+  );
+}
+```

package/index.cjs.js

@@ -57,7 +57,27 @@ function uncapitalizedJSONParse(json) {
 function uncapitalizedParse() {
     return ($source)=>$source.pipe(operators.map(uncapitalizedJSONParse));
 }
-function mkCqrsClient({ cqrsEndpoint, queryClient, tokenProvider, ajaxOptions, tokenHeader = "Authorization" }) {
+/**
+ * Creates React Query CQRS client with hooks for queries, operations, and commands.
+ * 
+ * Integrates with React Query to provide caching, background updates, and optimistic updates
+ * for CQRS operations. Automatically handles authentication, retries, and response transformation
+ * with uncapitalized keys.
+ * 
+ * @param cqrsEndpoint - Base URL for CQRS API endpoints
+ * @param queryClient - React Query client instance
+ * @param tokenProvider - Optional token provider for authentication
+ * @param ajaxOptions - Optional RxJS Ajax configuration options
+ * @param tokenHeader - Header name for authentication token (default: "Authorization")
+ * @returns Object with `createQuery`, `createOperation`, and `createCommand` hook factories
+ * @example
+ * ```typescript
+ * const client = mkCqrsClient({
+ *   cqrsEndpoint: 'https://api.example.com',
+ *   queryClient: new QueryClient()
+ * });
+ * ```
+ */ function mkCqrsClient({ cqrsEndpoint, queryClient, tokenProvider, ajaxOptions, tokenHeader = "Authorization" }) {
     function mkFetcher(endpoint, config = {}) {
         const apiCall = (data, token)=>{
             var _ajaxOptions_withCredentials;

package/index.esm.js

@@ -55,7 +55,27 @@ function uncapitalizedJSONParse(json) {
 function uncapitalizedParse() {
     return ($source)=>$source.pipe(map(uncapitalizedJSONParse));
 }
-function mkCqrsClient({ cqrsEndpoint, queryClient, tokenProvider, ajaxOptions, tokenHeader = "Authorization" }) {
+/**
+ * Creates React Query CQRS client with hooks for queries, operations, and commands.
+ * 
+ * Integrates with React Query to provide caching, background updates, and optimistic updates
+ * for CQRS operations. Automatically handles authentication, retries, and response transformation
+ * with uncapitalized keys.
+ * 
+ * @param cqrsEndpoint - Base URL for CQRS API endpoints
+ * @param queryClient - React Query client instance
+ * @param tokenProvider - Optional token provider for authentication
+ * @param ajaxOptions - Optional RxJS Ajax configuration options
+ * @param tokenHeader - Header name for authentication token (default: "Authorization")
+ * @returns Object with `createQuery`, `createOperation`, and `createCommand` hook factories
+ * @example
+ * ```typescript
+ * const client = mkCqrsClient({
+ *   cqrsEndpoint: 'https://api.example.com',
+ *   queryClient: new QueryClient()
+ * });
+ * ```
+ */ function mkCqrsClient({ cqrsEndpoint, queryClient, tokenProvider, ajaxOptions, tokenHeader = "Authorization" }) {
     function mkFetcher(endpoint, config = {}) {
         const apiCall = (data, token)=>{
             var _ajaxOptions_withCredentials;

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@leancodepl/react-query-cqrs-client",
-  "version": "8.4.0",
+  "version": "8.5.1",
   "license": "Apache-2.0",
   "dependencies": {
-    "@leancodepl/cqrs-client-base": "8.4.0",
-    "@leancodepl/utils": "8.4.0",
-    "@leancodepl/validation": "8.4.0",
+    "@leancodepl/cqrs-client-base": "8.5.1",
+    "@leancodepl/utils": "8.5.1",
+    "@leancodepl/validation": "8.5.1",
     "@tanstack/react-query": ">=5.0.0",
     "rxjs": ">=7.0.0"
   },
@@ -13,16 +13,48 @@
     "@testing-library/react": "*",
     "react": "*"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leancodepl/js_corelibrary.git",
+    "directory": "packages/cqrs-clients/react-query-cqrs-client"
+  },
+  "homepage": "https://github.com/leancodepl/js_corelibrary",
+  "bugs": {
+    "url": "https://github.com/leancodepl/js_corelibrary/issues"
+  },
+  "description": "TanStack Query integration for CQRS commands and queries",
+  "keywords": [
+    "cqrs",
+    "tanstack-query",
+    "react",
+    "hooks",
+    "cache",
+    "typescript",
+    "javascript",
+    "leancode"
+  ],
+  "author": {
+    "name": "LeanCode",
+    "url": "https://leancode.co"
+  },
+  "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "module": "./index.esm.js",
-      "types": "./index.esm.d.ts",
+      "types": "./index.d.ts",
       "import": "./index.cjs.mjs",
       "default": "./index.cjs.js"
     }
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
-  "types": "./index.esm.d.ts"
+  "types": "./index.d.ts"
 }

package/src/lib/mkCqrsClient.d.ts

@@ -5,6 +5,27 @@ import { ApiResponse, ApiSuccess, CommandResult, FailedCommandResult, Successful
 import { ValidationErrorsHandler } from "@leancodepl/validation";
 import { NullableUncapitalizeDeep } from "./types";
 export declare function uncapitalizedParse<TResult>(): OperatorFunction<string, NullableUncapitalizeDeep<TResult>>;
+/**
+ * Creates React Query CQRS client with hooks for queries, operations, and commands.
+ *
+ * Integrates with React Query to provide caching, background updates, and optimistic updates
+ * for CQRS operations. Automatically handles authentication, retries, and response transformation
+ * with uncapitalized keys.
+ *
+ * @param cqrsEndpoint - Base URL for CQRS API endpoints
+ * @param queryClient - React Query client instance
+ * @param tokenProvider - Optional token provider for authentication
+ * @param ajaxOptions - Optional RxJS Ajax configuration options
+ * @param tokenHeader - Header name for authentication token (default: "Authorization")
+ * @returns Object with `createQuery`, `createOperation`, and `createCommand` hook factories
+ * @example
+ * ```typescript
+ * const client = mkCqrsClient({
+ *   cqrsEndpoint: 'https://api.example.com',
+ *   queryClient: new QueryClient()
+ * });
+ * ```
+ */
 export declare function mkCqrsClient({ cqrsEndpoint, queryClient, tokenProvider, ajaxOptions, tokenHeader, }: {
     cqrsEndpoint: string;
     queryClient: QueryClient;

package/index.esm.d.ts

@@ -1 +0,0 @@
-export * from "./src/index";