@odata2ts/http-client-api 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# 0.1.0 (2023-06-03)
+
+### Features
+
+* force new minor for new http-client-api ([5628666](https://github.com/odata2ts/odata2ts/commit/56286668abf6fe5f3c0639f07a4a9f99cc549068))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 odata2ts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +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).

package/lib/ODataHttpClient.d.ts

@@ -0,0 +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>;
+}

package/lib/ODataHttpClient.js

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

package/lib/ODataHttpClient.js.map

@@ -0,0 +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"]}

package/lib/ODataResponseModel.d.ts

@@ -0,0 +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>>;

package/lib/ODataResponseModel.js

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

package/lib/ODataResponseModel.js.map

@@ -0,0 +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"]}

package/lib/index.d.ts

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

package/lib/index.js

@@ -0,0 +1,6 @@
+"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);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +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"]}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@odata2ts/http-client-api",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Specifies the contract between HTTP clients and odata2ts",
+  "license": "MIT",
+  "repository": "git@github.com:odata2ts/odata2ts.git",
+  "author": "texttechne",
+  "main": "./lib/index.js",
+  "scripts": {
+    "build": "yarn clean && yarn compile",
+    "check-circular-deps": "madge ./src --extensions ts --circular",
+    "clean": "rimraf lib coverage",
+    "compile": "tsc",
+    "prepublish": "yarn build",
+    "test": "jest --passWithNoTests"
+  },
+  "files": [
+    "*.md",
+    "lib",
+    "LICENSE"
+  ],
+  "keywords": [
+    "http client",
+    "api",
+    "odata2ts",
+    "ts",
+    "typescript"
+  ],
+  "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": "./lib/index.d.ts",
+  "gitHead": "a3d6457b87ce8c9ec42772c8a5fd02b4246a2e37"
+}