laravel-request 1.2.26 → 1.2.28

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "laravel-request",
   "productName": "laravel-request",
-  "version": "1.2.26",
+  "version": "1.2.28",
   "description": "laravel-request",
+  "type": "module",
   "main": "src/index.js",
   "module": "src/index.js",
   "types": "@types/laravel-request.d.ts",
-  "scripts": {},
+  "scripts": {
+    "test": "env-cmd mocha \"tests/**/*.js\"",
+    "test:watch": "env-cmd mocha \"tests/**/*.js\" --watch"
+  },
   "keywords": [],
   "author": {
     "name": "Abramov Oleg",
@@ -19,8 +23,13 @@
     "axios-mock-adapter": "^2.1.0",
     "query-string": "^8.1.0"
   },
+  "devDependencies": {
+    "chai": "^4.5.0",
+    "env-cmd": "^10.1.0",
+    "mocha": "^10.0.0"
+  },
   "files": [
     "src",
     "@types"
   ]
-}
+}

package/readme.md

@@ -1,111 +1,266 @@
-Install
-
-npm install laravel-request
-
-Connected package
-
-https://github.com/olegstan/laravel-rest
-
-set domain resolver before any request
-
-```
-Api.domainResolver = () => {
-    try {
-        return Environment.get('REACT_APP_API_URL');
-    } catch (e) {
-        console.log(e)
-        return null;
-    }
-}
-```
-
-set auth token resolver before any request
-
-default token resolver, you can redefine it to any other
-```
-Api.tokenResolver = async () => {
-    try {
-        return await localStorage.getItem('api_token'); 
-    } catch (e) {
-        console.log(e)
-        return null;
-    }
-}
-```
-
-Usage get data
-
-```
-Api.get('active-trade', 'index')
-      .where('active_id', 115)
-      .with('currency')
-      .with('to_account', 'to_account.currency')
-      .with('from_account', 'from_account.currency')
-      .orderBy('trade_at', 'DESC')
-      .all((response) => {
-        //success
-      }, () => {
-        //error
-      })
-}}     
-```
-  
-or
-
-```
-Api.get('active-trade', 'index')
-      .where('id', 115)
-      .with('currency')
-      .with('to_account', 'to_account.currency')
-      .with('from_account', 'from_account.currency')
-      .orderBy('trade_at', 'DESC')
-      .first((response) => {
-        //success
-        
-      }, () => {
-        //error
-      })
-}}
-```
-
-  
-You can use
-
-all or first or paginate
-
-usage POST data
-
-```
-Api.post('active', 'store', {
-      user_id: this.props.client.id,
-      type: 2,
-      type_id: item.type_id
-    })
-      .call((response) => {
-        //success
-      }, (response) => {
-        //error
-      });
-```
-
-response must be like below, for 200 status should contains key "result" with text "success"
-
-{
-    "meta": [],
-    "result": "success",
-    "data": [],
-}
-
-you can cancel request by
-
-```
-
-let cancelTokenSource = Api.get('active', SearchAllTypesHelper.ALL_TYPES, {
-            item_search: searchQuery,
-            user_id: clientId,
-            search_stock: 1
-        }).call(({data}) => {}, () => {}).getSource()
-        
-cancelTokenSource.cancel();
-        
-```
+# laravel-request
+
+Клиентская библиотека для работы с Laravel API. Поддерживает JSON и MessagePack, fluent-интерфейс в стиле Eloquent Query Builder.
+
+## Содержание
+
+- [Установка](#установка)
+- [Переменные окружения](#переменные-окружения)
+- [Api](#api)
+- [ApiRequest](#apirequest)
+  - [Два типа запросов](#два-типа-запросов)
+  - [Выборки: примеры и payload](#выборки-примеры-и-payload)
+  - [Действия: call()](#действия-call)
+  - [Отключение уведомлений](#отключение-уведомлений)
+  - [Прямой вызов по URL](#прямой-вызов-по-url)
+  - [Отмена запроса](#отмена-запроса)
+- [Лицензия](#лицензия)
+
+---
+
+## Установка
+
+```bash
+npm install laravel-request
+```
+
+## Переменные окружения
+
+| Переменная | Описание |
+|------------|----------|
+| `REACT_APP_API_URL` | Базовый URL API |
+| `REACT_APP_DEBUG` | `true`/`false` — логирование запросов и ответов |
+
+---
+
+## Api
+
+```javascript
+import { Api } from 'laravel-request';
+```
+
+| Метод | Описание |
+|-------|----------|
+| `Api.get(controller, action, data)` | GET |
+| `Api.post(controller, action, data)` | POST |
+| `Api.put(controller, action, data)` | PUT |
+| `Api.patch(controller, action, data)` | PATCH |
+| `Api.delete(controller, action, id, data)` | DELETE |
+| `Api.getArg(controller, action, arg, data)` | GET с аргументом в URL (например, index/123) |
+| `Api.getUrl(url, data)` | Прямой GET по URL |
+
+URL формируется как: `{domain}/api/v1/call/{controller}/{action}`
+
+---
+
+## ApiRequest
+
+### Два типа запросов
+
+**Выборка (список)** — `Api.get(controller, 'index')` или `'list'`  
+Цепочка `where()`, `select()`, `orderBy()` и т.д. + метод выполнения:
+
+| Метод | Результат |
+|-------|-----------|
+| `first()` | Первая страница |
+| `all()` | Все записи |
+| `paginate(page, perPage)` | Страница с пагинацией |
+| `pluck(fields)` | Только указанные поля |
+| `call()` | Без указания способа |
+
+**Действие** — POST/PUT/PATCH/DELETE или GET одной записи (index)  
+Всегда завершается `call()`.
+
+### Выборки: примеры и payload
+
+Данные уходят в query-параметрах URL (или в теле POST, если длина >5000 символов).
+
+При `REACT_APP_API_URL=https://api.example.com` URL формируется как `https://api.example.com/api/v1/call/{controller}/{action}`.
+
+**first():**
+
+URL: `https://api.example.com/api/v1/call/product/index` (GET)
+
+```javascript
+Api.get('product', 'index')
+  .select(['id', 'name', 'price'])
+  .where('status', '=', 'active')
+  .orderBy('created_at', 'desc')
+  .first(success, error, final);
+```
+```json
+{
+  "arguments": [],
+  "query": [
+    { "select": [["id", "name", "price"]] },
+    { "where": ["status", "=", "active"] },
+    { "orderBy": ["created_at", "desc"] }
+  ],
+  "data": { "paginateType": "first" },
+  "unique_hash": "xK9...",
+  "timestamp": 1708123456789
+}
+```
+
+**all():**
+
+URL: `https://api.example.com/api/v1/call/product/index` (GET)
+
+```javascript
+Api.get('product', 'index')
+  .where('category_id', '=', 1)
+  .all(success, error, final);
+```
+```json
+{
+  "arguments": [],
+  "query": [{ "where": ["category_id", "=", 1] }],
+  "data": { "paginateType": "all" },
+  "unique_hash": "xK9...",
+  "timestamp": 1708123456789
+}
+```
+
+**paginate():**
+
+URL: `https://api.example.com/api/v1/call/product/index` (GET)
+
+```javascript
+Api.get('product', 'index')
+  .whereIn('category_id', [1, 2, 3])
+  .orderBy('name')
+  .paginate(2, 15, success, error, final);
+```
+```json
+{
+  "arguments": [],
+  "query": [
+    { "whereIn": ["category_id", [1, 2, 3]] },
+    { "orderBy": ["name"] }
+  ],
+  "data": {
+    "paginateType": "paginate",
+    "page": 2,
+    "perPage": 15
+  },
+  "unique_hash": "xK9...",
+  "timestamp": 1708123456789
+}
+```
+
+**pluck():**
+
+URL: `https://api.example.com/api/v1/call/product/index` (GET)
+
+```javascript
+Api.get('product', 'index')
+  .pluck(['id', 'name'], success, error, final);
+```
+```json
+{
+  "arguments": [],
+  "query": [],
+  "data": {
+    "paginateType": "pluck",
+    "fields": ["id", "name"]
+  },
+  "unique_hash": "xK9...",
+  "timestamp": 1708123456789
+}
+```
+
+**first() — сложный (whereHas, with):**
+
+URL: `https://api.example.com/api/v1/call/product/index` (GET)
+
+```javascript
+Api.get('product', 'index')
+  .select(['id', 'name', 'price'])
+  .where('status', '=', 'active')
+  .whereHas('category', (q) => q.where('visible', true))
+  .with(['images', 'category'])
+  .orderBy('created_at', 'desc')
+  .first(success, error, final);
+```
+```json
+{
+  "arguments": [],
+  "query": [
+    { "select": [["id", "name", "price"]] },
+    { "where": ["status", "=", "active"] },
+    { "whereHas": ["category", { "query": [{ "where": ["visible", true] }] }] },
+    { "with": [["images", "category"]] },
+    { "orderBy": ["created_at", "desc"] }
+  ],
+  "data": { "paginateType": "first" },
+  "unique_hash": "xK9...",
+  "timestamp": 1708123456789
+}
+```
+
+**getArg()** (например, index/123):
+
+URL: `https://api.example.com/api/v1/call/user/index` (GET, id=123 в payload)
+
+```javascript
+Api.getArg('user', 'index', 123).call(success, error, final);
+```
+```json
+{
+  "arguments": [123],
+  "query": [],
+  "data": {},
+  "unique_hash": "xK9...",
+  "timestamp": 1708123456789
+}
+```
+
+### Действия: call()
+
+```javascript
+// URL: https://api.example.com/api/v1/call/user/store (POST)
+Api.post('user', 'store', { name: 'John', email: 'john@example.com' })
+  .call(success, error, final);
+
+// URL: https://api.example.com/api/v1/call/user/update (PUT)
+Api.put('user', 'update', { id: 1, name: 'John' })
+  .call(success, error, final);
+
+// URL: https://api.example.com/api/v1/call/user/destroy (DELETE, id=123 в payload)
+Api.delete('user', 'destroy', 123)
+  .call(success, error, final);
+
+// URL: https://api.example.com/api/v1/call/user/index (GET, id=123 в payload)
+Api.getArg('user', 'index', 123)
+  .call(success, error, final);
+```
+
+### Отключение уведомлений
+
+```javascript
+Api.get('product', 'index').withoutNotify().first(success, error, final);
+
+Api.post('user', 'store', data)
+  .withoutNotify((status) => status !== 422)
+  .call(success, error, final);
+```
+
+### Прямой вызов по URL
+
+```javascript
+Api.getUrl('https://api.example.com/custom/endpoint')
+  .callUrl(success, error, final);
+```
+
+### Отмена запроса
+
+```javascript
+const request = Api.get('product', 'index').first(success, error, final);
+request.getSource().cancel();
+```
+
+---
+
+## Лицензия
+
+MIT © Abramov Oleg

package/src/Api.js

@@ -1,4 +1,4 @@
-import ApiRequest from "./ApiRequest";
+import ApiRequest from "./ApiRequest.js";
 import axios from "axios";
 import { decode } from "@msgpack/msgpack";
 

package/src/ApiProxy.js

@@ -1,4 +1,4 @@
-import Api from "./Api";
+import Api from "./Api.js";
 
 export default class ApiProxy extends Api
 {

package/src/ApiRequest.js

@@ -1,6 +1,6 @@
-import Api from "./Api";
-import Builder from "./Builder";
-import Binding from "./Binding";
+import Api from "./Api.js";
+import Builder from "./Builder.js";
+import Binding from "./Binding.js";
 import axios from "axios";
 
 /**
@@ -221,6 +221,19 @@ export default class ApiRequest {
     return this.executeRequest(successCallback, errorCallback, finalCallback, params, byUrl)
   }
 
+  /**
+   * Returns built query array and arguments without executing the request.
+   * Useful for testing and debugging.
+   * @return {{ query: Array, data: object, arguments: Array }}
+   */
+  getBuiltPayload() {
+    return {
+      query: this.builder.toArray(),
+      data: this.data,
+      arguments: this.arguments,
+    };
+  }
+
   /**
    * Constructs request data object based on provided keys
    * @param dataKey

package/src/Builder.js

@@ -60,7 +60,17 @@ export default class Builder {
             if (typeof val == 'function') {
                 var func = val;
                 args[key] = {query: new Builder()};
-                args[key].query = func(args[key].query).toArray();
+
+                var result = func(args[key].query);
+
+                if (!(result instanceof Builder)) {
+                    throw new Error(
+                        'Callback for "' + method + '" must return instance of Builder. ' +
+                        'Did you forget "return query" in the callback?'
+                    );
+                }
+
+                args[key].query = result.toArray();
             }
 
           return;

package/src/index.js

@@ -1,9 +1,9 @@
-import Api from "./Api";
-import ApiProxy from "./ApiProxy";
-import ApiRequest from "./ApiRequest";
-import Binding from "./Binding";
-import Builder from "./Builder";
-import UrlBind from "./UrlBind";
+import Api from "./Api.js";
+import ApiProxy from "./ApiProxy.js";
+import ApiRequest from "./ApiRequest.js";
+import Binding from "./Binding.js";
+import Builder from "./Builder.js";
+import UrlBind from "./UrlBind.js";