@odata2ts/http-client-api 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 0.2.0 (2023-06-10)
+
+### Features
+
+* **http-client-api:** conventionalize client errors ([65ee7b8](https://github.com/odata2ts/http-client/commit/65ee7b811379881332839236692889b0414bd008))
+
 # 0.1.0 (2023-06-03)
 
 ### Features

package/README.md

@@ -1,46 +1,46 @@
-[![npm (scoped)](https://img.shields.io/npm/v/@odata2ts/http-client-api?style=for-the-badge)](https://www.npmjs.com/package/@odata2ts/http-client-api)
-
-# HTTP Client API
-
-Defines the contract between [odata2ts](https://github.com/odata2ts/odata2ts) and any HTTP client implementation.
-
-The responsibilities of the HTTP Client are:
-- HTTP request execution
-- mapping responses to conventionalized structures
-- custom request configuration (optional)
-- automatic CSRF Token Handling (optional)
-
-Features like **optimistic locking** (via `ETag`) or **batch requests** are currently not in scope
-of the HTTP client and may never be.
-
-## Documentation
-[HTTP Client Documentation](https://odata2ts.github.io/docs/odata-client/http-client)
-
-Main documentation for the odata2ts eco system:
-[https://odata2ts.github.io](https://odata2ts.github.io/)
-
-## Tests
-As this library provides the API as TypeScript types, there are no runtime
-artefacts to test.
-
-## Support, Feedback, Contributing
-This project is open to feature requests, suggestions, bug reports, usage questions etc.
-via [GitHub issues](https://github.com/odata2ts/odata2ts/issues).
-
-Contributions and feedback are encouraged and always welcome.
-
-See the [contribution guidelines](https://github.com/odata2ts/odata2ts/blob/main/CONTRIBUTING.md) for further information.
-
-## Spirit
-This project and this module have been created and are maintained in the following spirit:
-
-* adhere to the **OData specification** as much as possible
-  * support any OData service implementation which conforms to the spec
-  * allow to work around faulty implementations if possible
-* stability matters
-  * exercise Test Driven Development
-  * bomb the place with unit tests (code coverage > 95%)
-  * ensure that assumptions & understanding are correct by creating integration tests
-
-## License
-MIT - see [License](./LICENSE).
+[![npm (scoped)](https://img.shields.io/npm/v/@odata2ts/http-client-api?style=for-the-badge)](https://www.npmjs.com/package/@odata2ts/http-client-api)
+
+# HTTP Client API
+
+Defines the contract between [odata2ts](https://github.com/odata2ts/odata2ts) and any HTTP client implementation.
+
+The responsibilities of the HTTP Client are:
+- HTTP request execution
+- mapping responses to conventionalized structures
+- custom request configuration (optional)
+- automatic CSRF Token Handling (optional)
+
+Features like **optimistic locking** (via `ETag`) or **batch requests** are currently not in scope
+of the HTTP client and may never be.
+
+## Documentation
+[HTTP Client Documentation](https://odata2ts.github.io/docs/odata-client/http-client)
+
+Main documentation for the odata2ts eco system:
+[https://odata2ts.github.io](https://odata2ts.github.io/)
+
+## Tests
+As this library provides the API as TypeScript types, there are no runtime
+artefacts to test.
+
+## Support, Feedback, Contributing
+This project is open to feature requests, suggestions, bug reports, usage questions etc.
+via [GitHub issues](https://github.com/odata2ts/odata2ts/issues).
+
+Contributions and feedback are encouraged and always welcome.
+
+See the [contribution guidelines](https://github.com/odata2ts/odata2ts/blob/main/CONTRIBUTING.md) for further information.
+
+## Spirit
+This project and this module have been created and are maintained in the following spirit:
+
+* adhere to the **OData specification** as much as possible
+  * support any OData service implementation which conforms to the spec
+  * allow to work around faulty implementations if possible
+* stability matters
+  * exercise Test Driven Development
+  * bomb the place with unit tests (code coverage > 95%)
+  * ensure that assumptions & understanding are correct by creating integration tests
+
+## License
+MIT - see [License](./LICENSE).

package/lib/ODataClientError.d.ts

@@ -0,0 +1,6 @@
+export interface ODataClientError {
+    readonly name: string;
+    readonly status?: number;
+    readonly headers?: Record<string, string>;
+    readonly cause?: Error;
+}

package/lib/ODataClientError.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ODataClientError.js.map

package/lib/ODataClientError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ODataClientError.js","sourceRoot":"","sources":["../src/ODataClientError.ts"],"names":[],"mappings":"","sourcesContent":["export interface ODataClientError {\r\n  readonly name: string;\r\n  readonly status?: number;\r\n  readonly headers?: Record<string, string>;\r\n  readonly cause?: Error;\r\n}\r\n"]}

package/lib/ODataHttpClient.d.ts

@@ -1,54 +1,54 @@
-import { ODataResponse } from "./ODataResponseModel";
-/**
- * Retrieves the configuration type for the given HTTP client.
- */
-export type ODataHttpClientConfig<ClientType extends ODataHttpClient> = ClientType extends ODataHttpClient<infer Config> ? Config : never;
-export interface ODataHttpClient<RequestConfig = any> {
-    /**
-     * Create a model or collection entry.
-     *
-     * @param url
-     * @param data
-     * @param requestConfig
-     */
-    post<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;
-    get<ResponseModel>(url: string, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;
-    /**
-     * Replace a model.
-     *
-     * @param url
-     * @param data
-     * @param requestConfig
-     */
-    put<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;
-    /**
-     * Partially update a model.
-     *
-     * @param url
-     * @param data
-     * @param requestConfig
-     */
-    patch<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;
-    /**
-     * OData V2 only feature.
-     * Historically, PATCH method was not part of the official HTTP spec, when V1 & V2 were specified;
-     * but use of PATCH was already envisioned {@link https://www.odata.org/documentation/odata-version-2-0/operations/}.
-     * V3 and all following versions, specify use of PATCH method.
-     *
-     * If implemented, this method wil be used instead of patch to partially update models.
-     * Use case: You want to reuse this client and one server can only handle MERGE,
-     * but not PATCH http requests.
-     *
-     * @param url
-     * @param data
-     * @param requestConfig
-     */
-    merge?<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;
-    /**
-     * Delete a model or collection.
-     *
-     * @param url
-     * @param requestConfig
-     */
-    delete(url: string, requestConfig?: RequestConfig): ODataResponse<void>;
-}
+import { ODataResponse } from "./ODataResponseModel";
+/**
+ * Retrieves the configuration type for the given HTTP client.
+ */
+export type ODataHttpClientConfig<ClientType extends ODataHttpClient> = ClientType extends ODataHttpClient<infer Config> ? Config : never;
+export interface ODataHttpClient<RequestConfig = any> {
+    /**
+     * Create a model or collection entry.
+     *
+     * @param url
+     * @param data
+     * @param requestConfig
+     */
+    post<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;
+    get<ResponseModel>(url: string, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;
+    /**
+     * Replace a model.
+     *
+     * @param url
+     * @param data
+     * @param requestConfig
+     */
+    put<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;
+    /**
+     * Partially update a model.
+     *
+     * @param url
+     * @param data
+     * @param requestConfig
+     */
+    patch<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;
+    /**
+     * OData V2 only feature.
+     * Historically, PATCH method was not part of the official HTTP spec, when V1 & V2 were specified;
+     * but use of PATCH was already envisioned {@link https://www.odata.org/documentation/odata-version-2-0/operations/}.
+     * V3 and all following versions, specify use of PATCH method.
+     *
+     * If implemented, this method wil be used instead of patch to partially update models.
+     * Use case: You want to reuse this client and one server can only handle MERGE,
+     * but not PATCH http requests.
+     *
+     * @param url
+     * @param data
+     * @param requestConfig
+     */
+    merge?<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;
+    /**
+     * Delete a model or collection.
+     *
+     * @param url
+     * @param requestConfig
+     */
+    delete(url: string, requestConfig?: RequestConfig): ODataResponse<void>;
+}

package/lib/ODataHttpClient.js

@@ -1,3 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=ODataHttpClient.js.map

package/lib/ODataHttpClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"ODataHttpClient.js","sourceRoot":"","sources":["../src/ODataHttpClient.ts"],"names":[],"mappings":"","sourcesContent":["import { ODataResponse } from \"./ODataResponseModel\";\n\n/**\n * Retrieves the configuration type for the given HTTP client.\n */\nexport type ODataHttpClientConfig<ClientType extends ODataHttpClient> = ClientType extends ODataHttpClient<infer Config>\n  ? Config\n  : never;\n\nexport interface ODataHttpClient<RequestConfig = any> {\n  /**\n   * Create a model or collection entry.\n   *\n   * @param url\n   * @param data\n   * @param requestConfig\n   */\n  post<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;\n\n  get<ResponseModel>(url: string, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;\n\n  /**\n   * Replace a model.\n   *\n   * @param url\n   * @param data\n   * @param requestConfig\n   */\n  put<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;\n\n  /**\n   * Partially update a model.\n   *\n   * @param url\n   * @param data\n   * @param requestConfig\n   */\n  patch<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;\n\n  /**\n   * OData V2 only feature.\n   * Historically, PATCH method was not part of the official HTTP spec, when V1 & V2 were specified;\n   * but use of PATCH was already envisioned {@link https://www.odata.org/documentation/odata-version-2-0/operations/}.\n   * V3 and all following versions, specify use of PATCH method.\n   *\n   * If implemented, this method wil be used instead of patch to partially update models.\n   * Use case: You want to reuse this client and one server can only handle MERGE,\n   * but not PATCH http requests.\n   *\n   * @param url\n   * @param data\n   * @param requestConfig\n   */\n  merge?<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;\n\n  /**\n   * Delete a model or collection.\n   *\n   * @param url\n   * @param requestConfig\n   */\n  delete(url: string, requestConfig?: RequestConfig): ODataResponse<void>;\n}\n"]}
+{"version":3,"file":"ODataHttpClient.js","sourceRoot":"","sources":["../src/ODataHttpClient.ts"],"names":[],"mappings":"","sourcesContent":["import { ODataResponse } from \"./ODataResponseModel\";\r\n\r\n/**\r\n * Retrieves the configuration type for the given HTTP client.\r\n */\r\nexport type ODataHttpClientConfig<ClientType extends ODataHttpClient> = ClientType extends ODataHttpClient<infer Config>\r\n  ? Config\r\n  : never;\r\n\r\nexport interface ODataHttpClient<RequestConfig = any> {\r\n  /**\r\n   * Create a model or collection entry.\r\n   *\r\n   * @param url\r\n   * @param data\r\n   * @param requestConfig\r\n   */\r\n  post<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;\r\n\r\n  get<ResponseModel>(url: string, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;\r\n\r\n  /**\r\n   * Replace a model.\r\n   *\r\n   * @param url\r\n   * @param data\r\n   * @param requestConfig\r\n   */\r\n  put<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;\r\n\r\n  /**\r\n   * Partially update a model.\r\n   *\r\n   * @param url\r\n   * @param data\r\n   * @param requestConfig\r\n   */\r\n  patch<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;\r\n\r\n  /**\r\n   * OData V2 only feature.\r\n   * Historically, PATCH method was not part of the official HTTP spec, when V1 & V2 were specified;\r\n   * but use of PATCH was already envisioned {@link https://www.odata.org/documentation/odata-version-2-0/operations/}.\r\n   * V3 and all following versions, specify use of PATCH method.\r\n   *\r\n   * If implemented, this method wil be used instead of patch to partially update models.\r\n   * Use case: You want to reuse this client and one server can only handle MERGE,\r\n   * but not PATCH http requests.\r\n   *\r\n   * @param url\r\n   * @param data\r\n   * @param requestConfig\r\n   */\r\n  merge?<ResponseModel>(url: string, data: any, requestConfig?: RequestConfig): ODataResponse<ResponseModel>;\r\n\r\n  /**\r\n   * Delete a model or collection.\r\n   *\r\n   * @param url\r\n   * @param requestConfig\r\n   */\r\n  delete(url: string, requestConfig?: RequestConfig): ODataResponse<void>;\r\n}\r\n"]}

package/lib/ODataResponseModel.d.ts

@@ -1,20 +1,20 @@
-/**
- * This model represents the response for any completed HTTP request.
- */
-export interface HttpResponseModel<T> {
-    /** status code, e.g. 200 or 404 */
-    status: number;
-    /** status text, e.g. 200 = "OK" or 404 = "Not Found" */
-    statusText: string;
-    /** response headers as key value pairs */
-    headers: {
-        [key: string]: string;
-    };
-    /** response data */
-    data: T;
-}
-/**
- * Wrapping response instance, containing status code info, headers
- * and the response body.
- */
-export type ODataResponse<T> = Promise<HttpResponseModel<T>>;
+/**
+ * This model represents the response for any completed HTTP request.
+ */
+export interface HttpResponseModel<T> {
+    /** status code, e.g. 200 or 404 */
+    status: number;
+    /** status text, e.g. 200 = "OK" or 404 = "Not Found" */
+    statusText: string;
+    /** response headers as key value pairs */
+    headers: {
+        [key: string]: string;
+    };
+    /** response data */
+    data: T;
+}
+/**
+ * Wrapping response instance, containing status code info, headers
+ * and the response body.
+ */
+export type ODataResponse<T> = Promise<HttpResponseModel<T>>;

package/lib/ODataResponseModel.js

@@ -1,3 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=ODataResponseModel.js.map

package/lib/ODataResponseModel.js.map

@@ -1 +1 @@
-{"version":3,"file":"ODataResponseModel.js","sourceRoot":"","sources":["../src/ODataResponseModel.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * This model represents the response for any completed HTTP request.\n */\nexport interface HttpResponseModel<T> {\n  /** status code, e.g. 200 or 404 */\n  status: number;\n  /** status text, e.g. 200 = \"OK\" or 404 = \"Not Found\" */\n  statusText: string;\n  /** response headers as key value pairs */\n  headers: { [key: string]: string };\n  // config?: any;\n  /** response data */\n  data: T;\n}\n\n/**\n * Wrapping response instance, containing status code info, headers\n * and the response body.\n */\nexport type ODataResponse<T> = Promise<HttpResponseModel<T>>;\n"]}
+{"version":3,"file":"ODataResponseModel.js","sourceRoot":"","sources":["../src/ODataResponseModel.ts"],"names":[],"mappings":"","sourcesContent":["/**\r\n * This model represents the response for any completed HTTP request.\r\n */\r\nexport interface HttpResponseModel<T> {\r\n  /** status code, e.g. 200 or 404 */\r\n  status: number;\r\n  /** status text, e.g. 200 = \"OK\" or 404 = \"Not Found\" */\r\n  statusText: string;\r\n  /** response headers as key value pairs */\r\n  headers: { [key: string]: string };\r\n  // config?: any;\r\n  /** response data */\r\n  data: T;\r\n}\r\n\r\n/**\r\n * Wrapping response instance, containing status code info, headers\r\n * and the response body.\r\n */\r\nexport type ODataResponse<T> = Promise<HttpResponseModel<T>>;\r\n"]}

package/lib/index.d.ts

@@ -1,2 +1,3 @@
-export * from "./ODataResponseModel";
-export * from "./ODataHttpClient";
+export * from "./ODataResponseModel";
+export * from "./ODataHttpClient";
+export * from "./ODataClientError";

package/lib/index.js

@@ -1,6 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./ODataResponseModel"), exports);
-tslib_1.__exportStar(require("./ODataHttpClient"), exports);
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./ODataResponseModel"), exports);
+tslib_1.__exportStar(require("./ODataHttpClient"), exports);
+tslib_1.__exportStar(require("./ODataClientError"), exports);
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+DAAqC;AACrC,4DAAkC","sourcesContent":["export * from \"./ODataResponseModel\";\nexport * from \"./ODataHttpClient\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+DAAqC;AACrC,4DAAkC;AAClC,6DAAmC","sourcesContent":["export * from \"./ODataResponseModel\";\r\nexport * from \"./ODataHttpClient\";\r\nexport * from \"./ODataClientError\";\r\n"]}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@odata2ts/http-client-api",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },
   "description": "Specifies the contract between HTTP clients and odata2ts",
   "license": "MIT",
-  "repository": "git@github.com:odata2ts/odata2ts.git",
+  "repository": "git@github.com:odata2ts/http-client.git",
   "author": "texttechne",
   "main": "./lib/index.js",
   "scripts": {
@@ -31,13 +31,13 @@
   ],
   "devDependencies": {
     "@types/jest": "^27.4.1",
-    "@types/node": "^17.0.23",
-    "jest": "27.5.1",
-    "rimraf": "^3.0.2",
-    "ts-jest": "^27.1.4",
-    "ts-node": "10.7.0",
-    "typescript": "4.9.4"
+    "@types/node": "^20.2.5",
+    "jest": "29.5.0",
+    "rimraf": "^5.0.1",
+    "ts-jest": "^29.1.0",
+    "ts-node": "10.9.1",
+    "typescript": "5.0.4"
   },
   "types": "./lib/index.d.ts",
-  "gitHead": "a3d6457b87ce8c9ec42772c8a5fd02b4246a2e37"
+  "gitHead": "485559dce9388b480c7d0b3ded2fe2f3f5f98fad"
 }