@leancodepl/rx-cqrs-client 8.4.0 → 8.5.1

package/README.md

@@ -0,0 +1,138 @@
+# @leancodepl/rx-cqrs-client
+
+RxJS-based CQRS client for reactive command and query operations.
+
+## Features
+
+- **RxJS integration** - Reactive streams with operators for real-time data handling
+- **CQRS pattern** - Separate queries, commands, and operations with proper typing
+- **Observable operations** - Stream-based data handling with composable operators
+- **Error handling** - Validation errors with custom error codes and stream operators
+- **Authentication** - Token handling with automatic refresh and retry logic
+- **Custom operators** - Command response handling and stream transformation utilities
+
+## Installation
+
+```bash
+npm install @leancodepl/rx-cqrs-client
+# or
+yarn add @leancodepl/rx-cqrs-client
+```
+
+## API
+
+### `mkCqrsClient(cqrsEndpoint, tokenProvider, ajaxOptions, tokenHeader)`
+
+Creates CQRS client for command and query operations.
+
+**Parameters:**
+
+- `cqrsEndpoint: string` - Base URL for CQRS API endpoints
+- `tokenProvider?: 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` observable factories
+
+### `handleCommandResponse(handlerFunc)`
+
+Handles command responses with RxJS operators for validation error processing.
+
+**Parameters:**
+
+- `handlerFunc: Function` - Function that processes validation error handlers
+
+**Returns:** RxJS operator function for handling command responses
+
+### `reduceBoolean()`
+
+Reduces boolean values in RxJS streams using logical AND operation.
+
+**Returns:** RxJS operator function that reduces boolean values
+
+### `reduceObject()`
+
+Reduces object values in RxJS streams by merging properties.
+
+**Returns:** RxJS operator function that reduces object values
+
+## Usage Examples
+
+### Basic Setup
+
+```typescript
+import { mkCqrsClient } from "@leancodepl/rx-cqrs-client"
+
+const client = mkCqrsClient({
+    cqrsEndpoint: "https://api.example.com",
+    tokenProvider: {
+        getToken: () => Promise.resolve(localStorage.getItem("token")),
+        invalidateToken: () => Promise.resolve(true),
+    },
+})
+```
+
+### Query Operations
+
+```typescript
+import { switchMap } from "rxjs/operators"
+
+interface GetUserQuery {
+    userId: string
+}
+
+interface UserResult {
+    id: string
+    name: string
+    email: string
+}
+
+const getUser = client.createQuery<GetUserQuery, UserResult>("GetUser")
+
+getUser({ userId: "123" }).subscribe({
+    next: user => console.log("User:", user),
+    error: error => console.error("Error:", error),
+})
+```
+
+### Command Operations
+
+```typescript
+import { catchError } from "rxjs/operators"
+import { of } from "rxjs"
+
+interface CreateUserCommand {
+    name: string
+    email: string
+}
+
+const errorCodes = { EmailExists: 1, InvalidEmail: 2 } as const
+const createUser = client.createCommand<CreateUserCommand, typeof errorCodes>("CreateUser", errorCodes)
+
+createUser
+    .handle({ name: "John", email: "john@example.com" })
+    .handle("success", () => console.log("User created"))
+    .handle("EmailExists", () => console.log("Email already exists"))
+    .handle("failure", () => console.log("Creation failed"))
+    .check()
+```
+
+### Reactive Patterns
+
+```typescript
+import { fromEvent, switchMap, debounceTime } from "rxjs"
+
+const searchInput = document.getElementById("search") as HTMLInputElement
+
+fromEvent(searchInput, "input")
+    .pipe(
+        debounceTime(300),
+        switchMap(event => {
+            const query = (event.target as HTMLInputElement).value
+            return client.createQuery("SearchUsers")({ query })
+        }),
+    )
+    .subscribe(results => {
+        console.log("Search results:", results)
+    })
+```

package/index.cjs.js

@@ -5,7 +5,25 @@ var operators = require('rxjs/operators');
 var ajax = require('rxjs/ajax');
 var validation = require('@leancodepl/validation');
 
-function handleCommandResponse(handlerFunc) {
+/**
+ * Handles command responses with RxJS operators for validation error processing.
+ * 
+ * Creates an operator that processes validation error handlers and transforms them
+ * into the desired result type using a reducer pattern.
+ * 
+ * @param handlerFunc - Function that processes validation error handlers
+ * @returns RxJS operator function for handling command responses
+ * @example
+ * ```typescript
+ * import { handleCommandResponse } from '@leancodepl/rx-cqrs-client';
+ * 
+ * const handler = handleCommandResponse((handle) => 
+ *   handle('success', () => 'Success!')
+ *     .handle('failure', () => 'Failed!')
+ *     .check()
+ * );
+ * ```
+ */ function handleCommandResponse(handlerFunc) {
     return (source)=>source.pipe(operators.concatMap((handler)=>{
             const subj = new rxjs.ReplaySubject();
             handlerFunc(handler)({
@@ -26,7 +44,25 @@ function authGuard(tokenProvider) {
             }))));
 }
 
-function mkCqrsClient({ cqrsEndpoint, tokenProvider, ajaxOptions, tokenHeader = "Authorization" }) {
+/**
+ * Creates RxJS-based CQRS client for reactive command and query operations.
+ * 
+ * Provides observable-based methods for CQRS operations with automatic authentication,
+ * retry logic, and error handling.
+ * 
+ * @param cqrsEndpoint - Base URL for CQRS API endpoints
+ * @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` observable factories
+ * @example
+ * ```typescript
+ * const client = mkCqrsClient({
+ *   cqrsEndpoint: 'https://api.example.com',
+ *   tokenProvider: { getToken: () => Promise.resolve('token') }
+ * });
+ * ```
+ */ function mkCqrsClient({ cqrsEndpoint, tokenProvider, ajaxOptions, tokenHeader = "Authorization" }) {
     return {
         createQuery (type) {
             const queryCall = (dto, token)=>ajax.ajax({
@@ -100,11 +136,43 @@ function mkCqrsClient({ cqrsEndpoint, tokenProvider, ajaxOptions, tokenHeader =
     };
 }
 
-function reduceBoolean() {
+/**
+ * Reduces boolean values in RxJS streams using logical AND operation.
+ * 
+ * Creates an operator that combines multiple boolean values into a single result
+ * by applying logical AND. Returns true only if all values are true.
+ * 
+ * @returns RxJS operator function that reduces boolean values
+ * @example
+ * ```typescript
+ * import { of } from 'rxjs';
+ * import { reduceBoolean } from '@leancodepl/rx-cqrs-client';
+ * 
+ * of(true, true, false).pipe(reduceBoolean()).subscribe(result => {
+ *   console.log(result); // false
+ * });
+ * ```
+ */ function reduceBoolean() {
     return (source)=>source.pipe(rxjs.reduce((prev, cur)=>prev && cur, true));
 }
 
-function reduceObject() {
+/**
+ * Reduces object values in RxJS streams by merging properties.
+ * 
+ * Creates an operator that combines multiple objects into a single result
+ * by spreading properties. Later objects override earlier ones.
+ * 
+ * @returns RxJS operator function that reduces object values
+ * @example
+ * ```typescript
+ * import { of } from 'rxjs';
+ * import { reduceObject } from '@leancodepl/rx-cqrs-client';
+ * 
+ * of({ a: 1 }, { b: 2 }, { a: 3 }).pipe(reduceObject()).subscribe(result => {
+ *   console.log(result); // { a: 3, b: 2 }
+ * });
+ * ```
+ */ function reduceObject() {
     return (source)=>source.pipe(rxjs.reduce((prev, cur)=>({
                 ...prev,
                 ...cur

package/index.esm.js

@@ -3,7 +3,25 @@ import { concatMap, retryWhen, mergeMap, map } from 'rxjs/operators';
 import { AjaxError, ajax } from 'rxjs/ajax';
 import { handleResponse } from '@leancodepl/validation';
 
-function handleCommandResponse(handlerFunc) {
+/**
+ * Handles command responses with RxJS operators for validation error processing.
+ * 
+ * Creates an operator that processes validation error handlers and transforms them
+ * into the desired result type using a reducer pattern.
+ * 
+ * @param handlerFunc - Function that processes validation error handlers
+ * @returns RxJS operator function for handling command responses
+ * @example
+ * ```typescript
+ * import { handleCommandResponse } from '@leancodepl/rx-cqrs-client';
+ * 
+ * const handler = handleCommandResponse((handle) => 
+ *   handle('success', () => 'Success!')
+ *     .handle('failure', () => 'Failed!')
+ *     .check()
+ * );
+ * ```
+ */ function handleCommandResponse(handlerFunc) {
     return (source)=>source.pipe(concatMap((handler)=>{
             const subj = new ReplaySubject();
             handlerFunc(handler)({
@@ -24,7 +42,25 @@ function authGuard(tokenProvider) {
             }))));
 }
 
-function mkCqrsClient({ cqrsEndpoint, tokenProvider, ajaxOptions, tokenHeader = "Authorization" }) {
+/**
+ * Creates RxJS-based CQRS client for reactive command and query operations.
+ * 
+ * Provides observable-based methods for CQRS operations with automatic authentication,
+ * retry logic, and error handling.
+ * 
+ * @param cqrsEndpoint - Base URL for CQRS API endpoints
+ * @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` observable factories
+ * @example
+ * ```typescript
+ * const client = mkCqrsClient({
+ *   cqrsEndpoint: 'https://api.example.com',
+ *   tokenProvider: { getToken: () => Promise.resolve('token') }
+ * });
+ * ```
+ */ function mkCqrsClient({ cqrsEndpoint, tokenProvider, ajaxOptions, tokenHeader = "Authorization" }) {
     return {
         createQuery (type) {
             const queryCall = (dto, token)=>ajax({
@@ -98,11 +134,43 @@ function mkCqrsClient({ cqrsEndpoint, tokenProvider, ajaxOptions, tokenHeader =
     };
 }
 
-function reduceBoolean() {
+/**
+ * Reduces boolean values in RxJS streams using logical AND operation.
+ * 
+ * Creates an operator that combines multiple boolean values into a single result
+ * by applying logical AND. Returns true only if all values are true.
+ * 
+ * @returns RxJS operator function that reduces boolean values
+ * @example
+ * ```typescript
+ * import { of } from 'rxjs';
+ * import { reduceBoolean } from '@leancodepl/rx-cqrs-client';
+ * 
+ * of(true, true, false).pipe(reduceBoolean()).subscribe(result => {
+ *   console.log(result); // false
+ * });
+ * ```
+ */ function reduceBoolean() {
     return (source)=>source.pipe(reduce((prev, cur)=>prev && cur, true));
 }
 
-function reduceObject() {
+/**
+ * Reduces object values in RxJS streams by merging properties.
+ * 
+ * Creates an operator that combines multiple objects into a single result
+ * by spreading properties. Later objects override earlier ones.
+ * 
+ * @returns RxJS operator function that reduces object values
+ * @example
+ * ```typescript
+ * import { of } from 'rxjs';
+ * import { reduceObject } from '@leancodepl/rx-cqrs-client';
+ * 
+ * of({ a: 1 }, { b: 2 }, { a: 3 }).pipe(reduceObject()).subscribe(result => {
+ *   console.log(result); // { a: 3, b: 2 }
+ * });
+ * ```
+ */ function reduceObject() {
     return (source)=>source.pipe(reduce((prev, cur)=>({
                 ...prev,
                 ...cur

package/package.json

@@ -1,25 +1,54 @@
 {
   "name": "@leancodepl/rx-cqrs-client",
-  "version": "8.4.0",
+  "version": "8.5.1",
   "license": "Apache-2.0",
   "dependencies": {
-    "@leancodepl/cqrs-client-base": "8.4.0",
-    "@leancodepl/validation": "8.4.0",
+    "@leancodepl/cqrs-client-base": "8.5.1",
+    "@leancodepl/validation": "8.5.1",
     "rxjs": ">=7.0.0"
   },
   "devDependencies": {
     "xhr-mock": "2.5.1"
   },
+  "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/rx-cqrs-client"
+  },
+  "homepage": "https://github.com/leancodepl/js_corelibrary",
+  "bugs": {
+    "url": "https://github.com/leancodepl/js_corelibrary/issues"
+  },
+  "description": "RxJS-based reactive CQRS client for real-time applications",
+  "keywords": [
+    "cqrs",
+    "rxjs",
+    "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/handleCommandResponse.d.ts

@@ -1,3 +1,22 @@
 import { OperatorFunction } from "rxjs";
 import type { ReducerDescription, ValidationErrorsHandler } from "@leancodepl/validation";
+/**
+ * Handles command responses with RxJS operators for validation error processing.
+ *
+ * Creates an operator that processes validation error handlers and transforms them
+ * into the desired result type using a reducer pattern.
+ *
+ * @param handlerFunc - Function that processes validation error handlers
+ * @returns RxJS operator function for handling command responses
+ * @example
+ * ```typescript
+ * import { handleCommandResponse } from '@leancodepl/rx-cqrs-client';
+ *
+ * const handler = handleCommandResponse((handle) =>
+ *   handle('success', () => 'Success!')
+ *     .handle('failure', () => 'Failed!')
+ *     .check()
+ * );
+ * ```
+ */
 export declare function handleCommandResponse<TErrorCodes extends Record<string, number>, THandlerResult>(handlerFunc: (handler: ValidationErrorsHandler<TErrorCodes, never>) => (reducer: ReducerDescription<THandlerResult, any>) => any): OperatorFunction<ValidationErrorsHandler<TErrorCodes, never>, THandlerResult>;

package/src/lib/mkCqrsClient.d.ts

@@ -1,5 +1,24 @@
 import { AjaxConfig } from "rxjs/ajax";
 import { CommandResult, TokenProvider } from "@leancodepl/cqrs-client-base";
+/**
+ * Creates RxJS-based CQRS client for reactive command and query operations.
+ *
+ * Provides observable-based methods for CQRS operations with automatic authentication,
+ * retry logic, and error handling.
+ *
+ * @param cqrsEndpoint - Base URL for CQRS API endpoints
+ * @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` observable factories
+ * @example
+ * ```typescript
+ * const client = mkCqrsClient({
+ *   cqrsEndpoint: 'https://api.example.com',
+ *   tokenProvider: { getToken: () => Promise.resolve('token') }
+ * });
+ * ```
+ */
 export declare function mkCqrsClient({ cqrsEndpoint, tokenProvider, ajaxOptions, tokenHeader, }: {
     cqrsEndpoint: string;
     tokenProvider?: TokenProvider;

package/src/lib/reduceBoolean.d.ts

@@ -1,2 +1,19 @@
 import { OperatorFunction } from "rxjs";
+/**
+ * Reduces boolean values in RxJS streams using logical AND operation.
+ *
+ * Creates an operator that combines multiple boolean values into a single result
+ * by applying logical AND. Returns true only if all values are true.
+ *
+ * @returns RxJS operator function that reduces boolean values
+ * @example
+ * ```typescript
+ * import { of } from 'rxjs';
+ * import { reduceBoolean } from '@leancodepl/rx-cqrs-client';
+ *
+ * of(true, true, false).pipe(reduceBoolean()).subscribe(result => {
+ *   console.log(result); // false
+ * });
+ * ```
+ */
 export declare function reduceBoolean(): OperatorFunction<boolean, boolean>;

package/src/lib/reduceObject.d.ts

@@ -1,4 +1,21 @@
 import { OperatorFunction } from "rxjs";
 type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) extends (x: infer R) => any ? R : never;
+/**
+ * Reduces object values in RxJS streams by merging properties.
+ *
+ * Creates an operator that combines multiple objects into a single result
+ * by spreading properties. Later objects override earlier ones.
+ *
+ * @returns RxJS operator function that reduces object values
+ * @example
+ * ```typescript
+ * import { of } from 'rxjs';
+ * import { reduceObject } from '@leancodepl/rx-cqrs-client';
+ *
+ * of({ a: 1 }, { b: 2 }, { a: 3 }).pipe(reduceObject()).subscribe(result => {
+ *   console.log(result); // { a: 3, b: 2 }
+ * });
+ * ```
+ */
 export declare function reduceObject<T>(): OperatorFunction<T, Partial<UnionToIntersection<T>>>;
 export {};

package/index.esm.d.ts

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