feat(server-result): Initial check-in of the server-result package

package.json

@@ -192,7 +192,8 @@
       "@storm-stack/server-cache": "workspace:*",
       "@storm-stack/string-fns": "workspace:*",
       "@storm-stack/types": "workspace:*",
-      "@storm-stack/hashing": "workspace:*"
+      "@storm-stack/hashing": "workspace:*",
+      "@storm-stack/server-result": "workspace:*"
     }
   },
   "prettier": "@storm-software/prettier/config.json",

packages/errors/src/storm-error.ts

@@ -130,7 +130,7 @@ export function getCauseFromUnknown(cause: unknown): StormError {
  * @param value - the object to check
  * @returns The function isStormError is returning a boolean value.
  */
-export function isStormError<TCode extends string = any>(
+export function isStormError<TCode extends string = string>(
   value: unknown
 ): value is StormError<TCode> {
   return (
@@ -274,8 +274,8 @@ export class StormError<TCode extends string = string> extends Error {
       ? `${this.name ? (this.code ? `${this.name} ` : this.name) : EMPTY_STRING} ${
         this.code
           ? (this.code && this.name
-            ? `(${this.code})`
-            : this.code)
+              ? `(${this.code})`
+              : this.code)
           : EMPTY_STRING
       }${this.code || this.name ? ": " : EMPTY_STRING}${this.message}${
         this.cause

packages/server-result/README.md

@@ -0,0 +1,63 @@
+<!-- START header -->
+<!-- END header -->
+
+# server-result
+
+A package containing the ServerResult definition
+
+<!-- START doctoc -->
+<!-- END doctoc -->
+
+## Installing
+
+Using [pnpm](http://pnpm.io):
+
+```bash
+pnpm add -D @storm-stack/server-result
+```
+
+<details>
+  <summary>Using npm</summary>
+
+```bash
+npm install -D @storm-stack/server-result
+```
+
+</details>
+
+<details>
+  <summary>Using yarn</summary>
+
+```bash
+yarn add -D @storm-stack/server-result
+```
+
+</details>
+
+## Reduced Package Size
+
+This project uses [tsup](https://tsup.egoist.dev/) to package the source code
+due to its ability to remove unused code and ship smaller javascript files
+thanks to code splitting. This helps to greatly reduce the size of the package
+and to make it easier to use in other projects.
+
+## Development
+
+This project is built using [Nx](https://nx.dev). As a result, many of the usual
+commands are available to assist in development.
+
+### Building
+
+Run `nx build server-result` to build the library.
+
+### Running unit tests
+
+Run `nx test server-result` to execute the unit tests via
+[Jest](https://jestjs.io).
+
+### Linting
+
+Run `nx lint server-result` to run [ESLint](https://eslint.org/) on the package.
+
+<!-- START footer -->
+<!-- END footer -->

packages/server-result/jest.config.ts

@@ -0,0 +1,3 @@
+import { getJestConfig } from '@storm-software/testing-tools';
+
+export default getJestConfig('packages/server-result', true, 'server-result');

packages/server-result/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@storm-stack/server-result",
+  "version": "0.0.1",
+  "description": "⚡ The storm-stack monorepo contains utility applications, tools, and various libraries to create modern and scalable web applications.",
+  "repository": {
+    "type": "github",
+    "url": "https://github.com/storm-software/storm-stack.git",
+    "directory": "packages/server-result"
+  },
+  "private": false,
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/server-result/project.json

@@ -0,0 +1,35 @@
+{
+  "name": "server-result",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "library",
+  "sourceRoot": "packages/server-result/src",
+  "targets": {
+    "build": {
+      "cache": true,
+      "executor": "@storm-software/workspace-tools:unbuild",
+      "inputs": ["typescript", "^production"],
+      "outputs": ["{options.outputPath}"],
+      "defaultConfiguration": "production",
+      "clean": true,
+      "options": {
+        "type": "packages/server-result/src/index.ts",
+        "outputPath": "dist/packages/server-result",
+        "tsConfig": "packages/server-result/tsconfig.json",
+        "project": "packages/server-result/package.json"
+      },
+      "configurations": {
+        "production": {
+          "sourceMap": false,
+          "verbose": false
+        },
+        "development": {
+          "sourceMap": true,
+          "verbose": true
+        }
+      }
+    },
+    "nx-release-publish": {
+      "executor": "@storm-software/workspace-tools:npm-publish"
+    }
+  }
+}

packages/server-result/src/index.ts

@@ -0,0 +1,27 @@
+/*-------------------------------------------------------------------
+
+                  ⚡ Storm Software - Storm Stack
+
+ This code was released as part of the Storm Stack project. Storm Stack
+ is maintained by Storm Software under the Apache-2.0 License, and is
+ free for commercial and private use. For more information, please visit
+ our licensing page.
+
+ Website:         https://stormsoftware.com
+ Repository:      https://github.com/storm-software/storm-stack
+ Documentation:   https://stormsoftware.com/projects/storm-stack/docs
+ Contact:         https://stormsoftware.com/contact
+ License:         https://stormsoftware.com/projects/storm-stack/license
+
+ -------------------------------------------------------------------*/
+
+/**
+ * The server-result library used by Storm Software for building TypeScript applications.
+ *
+ * @remarks
+ * A package containing the ServerResult definition
+ *
+ * @packageDocumentation
+ */
+
+export * from "./server-result";

packages/server-result/src/server-result.ts

@@ -0,0 +1,71 @@
+/*-------------------------------------------------------------------
+
+                  ⚡ Storm Software - Storm Stack
+
+ This code was released as part of the Storm Stack project. Storm Stack
+ is maintained by Storm Software under the Apache-2.0 License, and is
+ free for commercial and private use. For more information, please visit
+ our licensing page.
+
+ Website:         https://stormsoftware.com
+ Repository:      https://github.com/storm-software/storm-stack
+ Documentation:   https://stormsoftware.com/projects/storm-stack/docs
+ Contact:         https://stormsoftware.com/contact
+ License:         https://stormsoftware.com/projects/storm-stack/license
+
+ -------------------------------------------------------------------*/
+
+import { StormDateTime } from "@storm-stack/date-time";
+import { StormError } from "@storm-stack/errors";
+import { MessageDetails } from "@storm-stack/types/utility-types/messages";
+
+export type ServerResultMeta = {
+  /**
+   * The correlation ID returned by the server
+   */
+  correlationId: string;
+
+  /**
+   * The request timestamp returned by the server
+   */
+  timestamp: StormDateTime;
+
+  /**
+   * The user ID who made the server request
+   */
+  userId: string;
+
+  /**
+   * The server endpoint/action name
+   */
+  endpoint: string;
+};
+
+export type ServerResult<T> =
+  | {
+      /**
+       * The meta data returned by the server
+       */
+      meta: ServerResultMeta;
+
+      /**
+       * The data returned by the server
+       */
+      data: T;
+
+      /**
+       * The message returned by the server
+       */
+      message?: MessageDetails;
+    }
+  | {
+      /**
+       * The meta data returned by the server
+       */
+      meta: ServerResultMeta;
+
+      /**
+       * The errors returned by the server
+       */
+      errors: StormError[];
+    };

packages/server-result/src/utilities/create-server-result.ts

@@ -0,0 +1,86 @@
+/*-------------------------------------------------------------------
+
+                  ⚡ Storm Software - Storm Stack
+
+ This code was released as part of the Storm Stack project. Storm Stack
+ is maintained by Storm Software under the Apache-2.0 License, and is
+ free for commercial and private use. For more information, please visit
+ our licensing page.
+
+ Website:         https://stormsoftware.com
+ Repository:      https://github.com/storm-software/storm-stack
+ Documentation:   https://stormsoftware.com/projects/storm-stack/docs
+ Contact:         https://stormsoftware.com/contact
+ License:         https://stormsoftware.com/projects/storm-stack/license
+
+ -------------------------------------------------------------------*/
+
+import { StormDateTime } from "@storm-stack/date-time/storm-date-time";
+import { isStormError, StormError } from "@storm-stack/errors/storm-error";
+import { isSetString } from "@storm-stack/types/type-checks/is-set-string";
+import { isString } from "@storm-stack/types/type-checks/is-string";
+import {
+  MessageDetails,
+  MessageType
+} from "@storm-stack/types/utility-types/messages";
+import { uuid } from "@storm-stack/unique-identifier/uuid";
+import { ServerResult, ServerResultMeta } from "../server-result";
+
+export interface CreateServerResultMetaOptions {
+  correlationId?: string;
+  userId: string;
+  endpoint: string;
+}
+
+export interface CreateServerResultOptions<T> {
+  message?: (Partial<MessageDetails> & Omit<MessageDetails, "type">) | string;
+  data: T;
+}
+
+export const createServerResultMeta = ({
+  correlationId,
+  userId,
+  endpoint
+}: CreateServerResultMetaOptions): ServerResultMeta => {
+  return {
+    correlationId: correlationId || uuid(),
+    timestamp: StormDateTime.current(),
+    userId,
+    endpoint
+  };
+};
+
+export const createServerResult = <T>(
+  meta: CreateServerResultMetaOptions,
+  options: CreateServerResultOptions<T> | StormError | StormError[]
+): ServerResult<T> => {
+  if (Array.isArray(options)) {
+    return {
+      meta: createServerResultMeta(meta),
+      errors: options
+    };
+  }
+
+  if (isStormError<any>(options)) {
+    return {
+      meta: createServerResultMeta(meta),
+      errors: [options]
+    };
+  }
+
+  return {
+    meta: createServerResultMeta(meta),
+    data: options.data,
+    message:
+      isSetString(options.message) ||
+      Boolean(options.message?.message) ||
+      Boolean(options.message?.code)
+        ? ((isString(options.message)
+            ? { message: options.message, type: MessageType.SUCCESS }
+            : {
+                type: MessageType.SUCCESS,
+                ...options.message
+              }) as MessageDetails)
+        : undefined
+  };
+};

packages/server-result/src/utilities/index.ts

@@ -0,0 +1,18 @@
+/*-------------------------------------------------------------------
+
+                  ⚡ Storm Software - Storm Stack
+
+ This code was released as part of the Storm Stack project. Storm Stack
+ is maintained by Storm Software under the Apache-2.0 License, and is
+ free for commercial and private use. For more information, please visit
+ our licensing page.
+
+ Website:         https://stormsoftware.com
+ Repository:      https://github.com/storm-software/storm-stack
+ Documentation:   https://stormsoftware.com/projects/storm-stack/docs
+ Contact:         https://stormsoftware.com/contact
+ License:         https://stormsoftware.com/projects/storm-stack/license
+
+ -------------------------------------------------------------------*/
+
+export * from "./create-server-result";

packages/server-result/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc"
+  },
+  "include": ["src/**/*.ts", "src/**/*.js", "bin/**/*"],
+  "exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
+}

packages/server-result/tsconfig.spec.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "types": ["jest", "node"]
+  },
+  "include": [
+    "jest.config.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.d.ts"
+  ]
+}