@kiwiproject/kiwi-js 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Kiwi Project
+
+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,2 @@
+# kiwi-js
+KiwiJS is a utility library. It contains a variety of utilities that we have built over time and find useful. Most of these utilities are ports from the Java Kiwi library (https://github.com/kiwiproject/kiwi).

package/dist/express/kiwi-standard-responses-express.d.ts

@@ -0,0 +1,13 @@
+export declare const KiwiStandardResponsesExpress: {
+    standardGetResponseWithIdentifier: (identifierField: String, identifier: Object, entity: any, res: Express.Response) => void;
+    standardGetResponseWithMessage: (entity: any, notFoundMessage: String, res: Express.Response) => void;
+    standardPostResponse: (location: String, entity: any, res: Express.Response) => void;
+    standardPutResponse: (entity: any, res: Express.Response) => void;
+    standardDeleteResponse: (res: Express.Response) => void;
+    standardDeleteResponseWithEntity: (deletedEntity: any, res: Express.Response) => void;
+    standardAcceptedResponse: (entity: any, res: Express.Response) => void;
+    standardErrorResponse: (status: Number, errorDetails: String, res: Express.Response) => void;
+    standardUnauthorizedResponse: (errorDetails: String, res: Express.Response) => void;
+    standardNotFoundResponse: (errorDetails: String, res: Express.Response) => void;
+    standardBadRequestResponse: (errorDetails: String, res: Express.Response) => void;
+};

package/dist/express/kiwi-standard-responses-express.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KiwiStandardResponsesExpress = void 0;
+const error_message_1 = require("../model/error-message");
+/**
+ * Returns a 200 OK response if the entity contains a value. Otherwise, returns a 404 Not Found response with
+ * a message stating that the entity was not found using the given identifier field and value.
+ *
+ * @param identifierField the field which identifies the entity being looked up, e.g. "id"
+ * @param identifier      the value of the identifier field, e.g. 42
+ * @param entity          the entity or undefined
+ * @param res             the Express Response
+ */
+const standardGetResponseWithIdentifier = (identifierField, identifier, entity, res) => {
+    if (entity !== undefined) {
+        res.status(200).json(entity);
+        return;
+    }
+    standardNotFoundResponse(`Object with ${identifierField} ${identifier} not found`, res);
+};
+/**
+ * Returns a 200 OK response if the entity is non-null. Otherwise, returns a 404 Not Found response with
+ * the given detail message.
+ *
+ * @param entity          the entity or undefined
+ * @param notFoundMessage the specific message to use in the 404 response (if entity is undefined)
+ * @param res             the Express Response
+ */
+const standardGetResponseWithMessage = (entity, notFoundMessage, res) => {
+    if (entity !== undefined) {
+        res.status(200).json(entity);
+        return;
+    }
+    standardNotFoundResponse(notFoundMessage, res);
+};
+/**
+ * Returns a 404 Not Found response containing an {@link ErrorMessage} entity which uses {@code errorDetails}
+ * as the detailed error message.
+ *
+ * @param errorDetails the error message to use
+ * @param res          the Express Response
+ */
+const standardNotFoundResponse = (errorDetails, res) => {
+    res.status(404).json(new error_message_1.ErrorMessage(404, errorDetails).toMap());
+};
+/**
+ * Returns a 201 Created response having the specified Location header and response entity.
+ *
+ * @param location the value for the location header
+ * @param entity   the new entity
+ * @param res      the Express Response
+ */
+const standardPostResponse = (location, entity, res) => {
+    res.status(201).set('Location', location).json(entity);
+};
+/**
+ * Returns a 200 OK response having the specified response entity.
+ *
+ * @param entity the updated entity
+ * @param res    the Express Response
+ */
+const standardPutResponse = (entity, res) => {
+    res.status(200).json(entity);
+};
+/**
+ * Returns a 204 No Content response for DELETE requests that do not return an entity.
+ *
+ * @param res the Express Response
+ */
+const standardDeleteResponse = (res) => {
+    res.status(204);
+};
+/**
+ * Returns a 204 No Content response for DELETE requests and return an entity.
+ *
+ * @param deletedEntity the entity that was deleted
+ * @param res           the Express Response
+ */
+const standardDeleteResponseWithEntity = (deletedEntity, res) => {
+    res.status(204).json(deletedEntity);
+};
+/**
+ * Returns a 400 Bad Request response containing an {@link ErrorMessage} entity which uses {@code errorDetails}
+ * as the detailed error message.
+ *
+ * @param errorDetails the error message to use
+ * @param res          the Express Response
+ */
+const standardBadRequestResponse = (errorDetails, res) => {
+    res.status(400).json(new error_message_1.ErrorMessage(400, errorDetails).toMap());
+};
+/**
+ * Returns a 401 Unauthorized response containing an {@link ErrorMessage} entity which uses {@code errorDetails}
+ * as the detailed error message.
+ *
+ * @param errorDetails the error message to use
+ * @param res          the Express Response
+ */
+const standardUnauthorizedResponse = (errorDetails, res) => {
+    res.status(401).json(new error_message_1.ErrorMessage(401, errorDetails).toMap());
+};
+/**
+ * Returns a response having the given status and an {@link ErrorMessage} entity which uses {@code errorDetails}
+ * as the detailed error message.
+ * <p>
+ * Does not verify that the given status is actually an error status.
+ *
+ * @param status       the status code
+ * @param errorDetails the error message to use
+ * @param res          the Express Response
+ */
+const standardErrorResponse = (status, errorDetails, res) => {
+    res.status(status).json(new error_message_1.ErrorMessage(status, errorDetails).toMap());
+};
+/**
+ * Returns a 202 Accepted response having the specified response entity.
+ * <p>
+ * This generally applies to POST, PUT, and PATCH requests that might take a while and are processed asynchronously.
+ *
+ * @param entity the accepted entity
+ * @param res    the Express Response
+ */
+const standardAcceptedResponse = (entity, res) => {
+    res.status(202).json(entity);
+};
+exports.KiwiStandardResponsesExpress = {
+    standardGetResponseWithIdentifier,
+    standardGetResponseWithMessage,
+    standardPostResponse,
+    standardPutResponse,
+    standardDeleteResponse,
+    standardDeleteResponseWithEntity,
+    standardAcceptedResponse,
+    standardErrorResponse,
+    standardUnauthorizedResponse,
+    standardNotFoundResponse,
+    standardBadRequestResponse,
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { ErrorMessage } from './model/error-message';
+export { KiwiStandardResponsesExpress } from './express/kiwi-standard-responses-express';

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KiwiStandardResponsesExpress = exports.ErrorMessage = void 0;
+var error_message_1 = require("./model/error-message");
+Object.defineProperty(exports, "ErrorMessage", { enumerable: true, get: function () { return error_message_1.ErrorMessage; } });
+var kiwi_standard_responses_express_1 = require("./express/kiwi-standard-responses-express");
+Object.defineProperty(exports, "KiwiStandardResponsesExpress", { enumerable: true, get: function () { return kiwi_standard_responses_express_1.KiwiStandardResponsesExpress; } });

package/dist/model/error-message.d.ts

@@ -0,0 +1,20 @@
+/**
+ * An error message that Kiwi uses to standardize HTTP error responses.
+ * <p>
+ * Each instance contains the HTTP status (error) code; the error message; an optional identifier to identify the
+ * specific item causing the error (e.g. a primary key); and an optional field/property name for cases when a specific
+ * field causes the error.
+ */
+export declare class ErrorMessage {
+    private readonly fieldName;
+    private readonly itemId;
+    private readonly code;
+    private readonly message;
+    constructor(code: Number, message: String, fieldName?: String, itemId?: String);
+    toMap(): {
+        message: String;
+        code: Number;
+        fieldName: String;
+        itemId: String;
+    };
+}

package/dist/model/error-message.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorMessage = void 0;
+/**
+ * An error message that Kiwi uses to standardize HTTP error responses.
+ * <p>
+ * Each instance contains the HTTP status (error) code; the error message; an optional identifier to identify the
+ * specific item causing the error (e.g. a primary key); and an optional field/property name for cases when a specific
+ * field causes the error.
+ */
+class ErrorMessage {
+    constructor(code, message, fieldName = '', itemId = '') {
+        this.itemId = itemId;
+        this.code = code;
+        this.message = message;
+        this.fieldName = fieldName;
+    }
+    toMap() {
+        return {
+            message: this.message,
+            code: this.code,
+            fieldName: this.fieldName,
+            itemId: this.itemId
+        };
+    }
+}
+exports.ErrorMessage = ErrorMessage;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@kiwiproject/kiwi-js",
+  "version": "0.5.0",
+  "description": "KiwiJS is a utility library. It contains a variety of utilities that we have built over time and find useful. Most of these utilities are ports from the Java Kiwi library.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --coverage --collectCoverageFrom=src/**/*.ts"
+  },
+  "jest": {
+    "testPathIgnorePatterns": ["<rootDir>/__tests__/__utils__", "<rootDir>/node_modules/"]
+  },
+  "dependencies": {
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.21.8",
+    "@babel/preset-env": "^7.21.5",
+    "@babel/preset-typescript": "^7.21.5",
+    "@jest/globals": "^29.5.0",
+    "babel-jest": "^29.5.0",
+    "jest": "^29.5.0"
+  }
+}