@clipboard-health/util-ts 2.2.5 → 2.2.7

package/.eslintrc.json

@@ -0,0 +1,12 @@
+{
+  "extends": ["../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "parserOptions": {
+    "project": "tsconfig.lint.json",
+    "tsconfigRootDir": "packages/util-ts"
+  },
+  "rules": {
+    // Block node dependencies so this library is usable in the browser.
+    "no-restricted-imports": ["error", { "patterns": ["node:*"] }]
+  }
+}

package/jest.config.ts

@@ -0,0 +1,18 @@
+export default {
+  coveragePathIgnorePatterns: [],
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100,
+    },
+  },
+  displayName: "util-ts",
+  moduleFileExtensions: ["ts", "js"],
+  preset: "../../jest.preset.js",
+  setupFiles: ["../../jest.setup.js"],
+  transform: {
+    "^.+\\.[tj]s$": ["ts-jest", { tsconfig: "<rootDir>/tsconfig.spec.json" }],
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/util-ts",
-  "version": "2.2.5",
+  "version": "2.2.7",
   "main": "./src/index.js",
   "publishConfig": {
     "access": "restricted"
@@ -9,7 +9,5 @@
     "build": "nx build util-ts",
     "lint": "nx lint util-ts",
     "test": "nx test util-ts"
-  },
-  "type": "commonjs",
-  "types": "./src/index.d.ts"
+  }
 }

package/project.json

@@ -0,0 +1,33 @@
+{
+  "name": "util-ts",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "library",
+  "sourceRoot": "packages/util-ts/src",
+  "tags": ["scope:no-external-imports"],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "options": {
+        "assets": ["packages/util-ts/*.md"],
+        "main": "packages/util-ts/src/index.js",
+        "outputPath": "dist/packages/util-ts",
+        "tsConfig": "packages/util-ts/tsconfig.lib.json"
+      },
+      "outputs": ["{options.outputPath}"]
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "options": {
+        "maxWarnings": 0
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "options": {
+        "jestConfig": "packages/util-ts/jest.config.ts",
+        "passWithNoTests": false
+      },
+      "outputs": ["{projectRoot}/coverage"]
+    }
+  }
+}

package/src/{index.d.ts → index.ts}

@@ -13,4 +13,3 @@ export * from "./lib/null-to-undefined";
 export * from "./lib/option";
 export * from "./lib/stringify";
 export * from "./lib/to-error";
-//# sourceMappingURL=index.d.ts.map

package/src/lib/{attributes.d.ts → attributes.ts}

@@ -1,3 +1,3 @@
 export type AttributeValue = boolean | Date | number | string | Uint8Array | undefined;
+
 export type Attributes = Record<string, AttributeValue>;
-//# sourceMappingURL=attributes.d.ts.map

package/src/lib/cbh-error.spec.ts

@@ -0,0 +1,30 @@
+import { CbhError } from "./cbh-error";
+
+describe("CbhError", () => {
+  it("returns proper defaults", () => {
+    const message = "boom";
+    const statusCode = 500;
+
+    const error = new CbhError({ message, statusCode });
+
+    expect(error.name).toBe("CbhError");
+    expect(error.message).toBe(message);
+    expect(error.issues[0]?.statusCode).toBe(statusCode);
+  });
+
+  it("sets the cause", () => {
+    const cause = new Error("cause");
+
+    const error = new CbhError({ message: "boom", cause });
+
+    expect(error.cause).toBe(cause);
+  });
+
+  it("accpets an array", () => {
+    const message = "boom";
+
+    const error = new CbhError([{ message }]);
+
+    expect(error.message).toBe(message);
+  });
+});

package/src/lib/cbh-error.ts

@@ -0,0 +1,26 @@
+import { type OneOrNonEmptyArray, toNonEmptyArray } from "./non-empty-array";
+
+const ERROR_STATUS_CODES = [400, 401, 403, 404, 409, 422, 429, 500] as const;
+export type ErrorStatusCode = (typeof ERROR_STATUS_CODES)[number];
+
+export interface CbhIssue {
+  cause?: Error;
+  id?: string;
+  message: string;
+  statusCode?: ErrorStatusCode;
+}
+
+export class CbhError extends Error {
+  public readonly issues: CbhIssue[];
+
+  constructor(issues: OneOrNonEmptyArray<CbhIssue>) {
+    const is = toNonEmptyArray(issues);
+    const first = is[0];
+    super(first?.message, { cause: first?.cause });
+    // See https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html#example
+    Object.setPrototypeOf(this, new.target.prototype);
+
+    this.issues = is;
+    this.name = "CbhError";
+  }
+}

package/src/lib/cbh-response.spec.ts

@@ -0,0 +1,25 @@
+import { CbhError } from "./cbh-error";
+import { toErrorCbhResponse, toSuccessCbhResponse } from "./cbh-response";
+
+describe("toErrorCbhResponse", () => {
+  it("returns error", () => {
+    const message = "boom";
+
+    const response = toErrorCbhResponse({ message });
+
+    expect(response).toEqual({
+      success: false,
+      error: new CbhError({ message }),
+    });
+  });
+});
+
+describe("toSuccessCbhResponse", () => {
+  it("returns success", () => {
+    const message = "success";
+
+    const response = toSuccessCbhResponse({ message });
+
+    expect(response).toEqual({ success: true, data: { message } });
+  });
+});

package/src/lib/cbh-response.ts

@@ -0,0 +1,15 @@
+import { CbhError, type CbhIssue } from "./cbh-error";
+import type { OneOrNonEmptyArray } from "./non-empty-array";
+
+export type CbhResponse<T> = { success: true; data: T } | { success: false; error: CbhError };
+
+export function toErrorCbhResponse(issues: OneOrNonEmptyArray<CbhIssue>): {
+  success: false;
+  error: CbhError;
+} {
+  return { success: false, error: new CbhError(issues) };
+}
+
+export function toSuccessCbhResponse<T>(data: T): { success: true; data: T } {
+  return { success: true, data };
+}

package/src/lib/defined-utils.spec.ts

@@ -0,0 +1,35 @@
+import { isDefined, isNullOrUndefined } from "./defined-utils";
+
+const DEFINED_TEST_CASES = ["gandalf", " ", "", 42, 0, -0];
+
+describe("isNullOrUndefined", () => {
+  it.each(DEFINED_TEST_CASES)("returns false for (%s)", (value) => {
+    expect(isNullOrUndefined(value)).toBe(false);
+  });
+
+  it("returns true if null", () => {
+    // eslint-disable-next-line unicorn/no-null
+    expect(isNullOrUndefined(null)).toBe(true);
+  });
+
+  it("returns true if undefined", () => {
+    // eslint-disable-next-line unicorn/no-useless-undefined
+    expect(isNullOrUndefined(undefined)).toBe(true);
+  });
+});
+
+describe("isDefined", () => {
+  it.each(DEFINED_TEST_CASES)("returns true for (%s)", (value) => {
+    expect(isDefined(value)).toBe(true);
+  });
+
+  it("returns false if undefined", () => {
+    // eslint-disable-next-line unicorn/no-null
+    expect(isDefined(null)).toBe(false);
+  });
+
+  it("returns false if null", () => {
+    // eslint-disable-next-line unicorn/no-useless-undefined
+    expect(isDefined(undefined)).toBe(false);
+  });
+});

package/src/lib/{defined-utils.d.ts → defined-utils.ts}

@@ -2,18 +2,23 @@
  * We specifically want to guard against both `null` and `undefined`
  * In this one case, we need to define `null` as an expected argument type.
  */
+// eslint-disable-next-line @typescript-eslint/ban-types
 type NullOrUndefined = null | undefined;
+
 /**
  * Checks whether a value is null or undefined. If it is not defined, the return type ensures type safety.
  * @param value any value or null or undefined
  * @returns true if `value` is null or undefined, false otherwise.
  */
-export declare function isNullOrUndefined<T>(value: T | NullOrUndefined): value is NullOrUndefined;
+export function isNullOrUndefined<T>(value: T | NullOrUndefined): value is NullOrUndefined {
+  return value === null || value === undefined;
+}
+
 /**
  * Checks whether a value is defined. If it is defined, the return type ensures type safety.
  * @param value any value or null or undefined
  * @returns true if `value` is defined (not null and not undefined), false otherwise.
  */
-export declare function isDefined<T>(value: T | NullOrUndefined): value is T;
-export {};
-//# sourceMappingURL=defined-utils.d.ts.map
+export function isDefined<T>(value: T | NullOrUndefined): value is T {
+  return !isNullOrUndefined(value);
+}

package/src/lib/delay.spec.ts

@@ -0,0 +1,11 @@
+import { delay } from "./delay";
+
+describe("delay", () => {
+  it("should wait for the specified time", async () => {
+    const start = Date.now();
+
+    await delay(10);
+
+    expect(Date.now() - start).toBeGreaterThanOrEqual(10);
+  });
+});

package/src/lib/delay.ts

@@ -0,0 +1,5 @@
+export async function delay(milliseconds: number): Promise<void> {
+  await new Promise((resolve) => {
+    setTimeout(resolve, milliseconds);
+  });
+}

package/src/lib/either.spec.ts

@@ -0,0 +1,23 @@
+import * as E from "./either";
+
+describe("Either", () => {
+  it("left works", () => {
+    const error = new Error("boom");
+    const either = E.left(error) as E.Left<Error>;
+
+    expect(E.isLeft(either)).toBe(true);
+    expect(E.isRight(either)).toBe(false);
+    expect(either.isRight).toBe(false);
+    expect(either.left).toBe(error);
+  });
+
+  it("right works", () => {
+    const value = "my-value";
+    const either = E.right(value) as E.Right<string>;
+
+    expect(E.isRight(either)).toBe(true);
+    expect(E.isLeft(either)).toBe(false);
+    expect(either.isRight).toBe(true);
+    expect(either.right).toBe(value);
+  });
+});

package/src/lib/{either.d.ts → either.ts}

@@ -1,11 +1,13 @@
 export interface Left<E> {
-    isRight: false;
-    left: E;
+  isRight: false;
+  left: E;
 }
+
 export interface Right<A> {
-    isRight: true;
-    right: A;
+  isRight: true;
+  right: A;
 }
+
 /**
  * A value of either type `Left<E>` or type `Right<A>`; a disjoint union.
  *
@@ -13,20 +15,31 @@ export interface Right<A> {
  * information. Convention dictates that `Left<E>` is used for failure and `Right<A>` for success.
  */
 export type Either<E, A> = Left<E> | Right<A>;
+
 /**
  * Constructs an `Either` holding a `Left<E>` value, usually representing a failure.
  */
-export declare function left<E, A = never>(left: E): Either<E, A>;
+export function left<E, A = never>(left: E): Either<E, A> {
+  return { isRight: false, left };
+}
+
 /**
  * Constructs an `Either` holding a `Right<A>` value, usually representing a success.
  */
-export declare function right<A, E = never>(right: A): Either<E, A>;
+export function right<A, E = never>(right: A): Either<E, A> {
+  return { isRight: true, right };
+}
+
 /**
  * Returns `true` if the either is `Left<E>`, `false` otherwise.
  */
-export declare function isLeft<E, A>(either: Either<E, A>): either is Left<E>;
+export function isLeft<E, A>(either: Either<E, A>): either is Left<E> {
+  return !either.isRight;
+}
+
 /**
  * Returns `true` if the either is `Right<A>`, `false` otherwise.
  */
-export declare function isRight<E, A>(either: Either<E, A>): either is Right<A>;
-//# sourceMappingURL=either.d.ts.map
+export function isRight<E, A>(either: Either<E, A>): either is Right<A> {
+  return either.isRight;
+}

package/src/lib/force-cast.spec.ts

@@ -0,0 +1,8 @@
+import { forceCast } from "./force-cast";
+
+describe("forceCast", () => {
+  it("doesn't actually change type", () => {
+    const a: number = forceCast<number>("a");
+    expect(typeof a).toBe("string");
+  });
+});

package/src/lib/force-cast.ts

@@ -0,0 +1,4 @@
+/** Force cast to the provided type. */
+export function forceCast<T>(value: unknown): T {
+  return value as T;
+}

package/src/lib/head.spec.ts

@@ -0,0 +1,21 @@
+import { head } from "./head";
+
+describe("head", () => {
+  it("returns head of list", () => {
+    expect(head([1, 2])).toBe(1);
+  });
+
+  it("returns undefined if empty list", () => {
+    // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+    expect(head([])).toBeUndefined();
+  });
+
+  it("returns undefined if passed", () => {
+    expect(head()).toBeUndefined();
+  });
+
+  it("returns value if not an array", () => {
+    const value = { hi: "there" };
+    expect(head(value)).toEqual(value);
+  });
+});

package/src/lib/head.ts

@@ -0,0 +1,5 @@
+export type OneOrArray<T> = T | T[];
+
+export function head<T>(value?: OneOrArray<T>): T | undefined {
+  return Array.isArray(value) ? value[0] : (value ?? undefined);
+}

package/src/lib/identity.spec.ts

@@ -0,0 +1,17 @@
+import { identity } from "./identity";
+
+describe("identity", () => {
+  it("returns the provided input", () => {
+    expect(identity(1)).toBe(1);
+    expect(identity("text")).toBe("text");
+    expect(identity({})).toStrictEqual({});
+  });
+
+  it("should correctly infer the type", () => {
+    const a = 1;
+    expect(typeof a).toBe("number");
+
+    const b = identity(a);
+    expect(typeof b).toBe("number");
+  });
+});

package/src/lib/{identity.d.ts → identity.ts}

@@ -8,5 +8,6 @@
  * @param {T} value - The value to return unchanged.
  * @returns {T} The input value, unchanged.
  */
-export declare function identity<T>(value: T): T;
-//# sourceMappingURL=identity.d.ts.map
+export function identity<T>(value: T): T {
+  return value;
+}

package/src/lib/is-string.spec.ts

@@ -0,0 +1,11 @@
+import { isString } from "./is-string";
+
+describe("isString", () => {
+  it("returns true", () => {
+    expect(isString("hi")).toBe(true);
+  });
+
+  it("returns false", () => {
+    expect(isString({})).toBe(false);
+  });
+});

package/src/lib/is-string.ts

@@ -0,0 +1,3 @@
+export function isString(value: unknown): value is string {
+  return typeof value === "string" || value instanceof String;
+}

package/src/lib/non-empty-array.ts

@@ -0,0 +1,7 @@
+export type NonEmptyArray<T> = [T, ...T[]];
+
+export type OneOrNonEmptyArray<T> = T | NonEmptyArray<T>;
+
+export function toNonEmptyArray<T>(value: OneOrNonEmptyArray<T>): NonEmptyArray<T> {
+  return Array.isArray(value) ? value : [value];
+}

package/src/lib/null-to-undefined.spec.ts

@@ -0,0 +1,33 @@
+import { nullToUndefined } from "./null-to-undefined";
+
+describe("nullToUndefined", () => {
+  it("returns undefined", async () => {
+    // eslint-disable-next-line unicorn/no-null
+    expect(await nullToUndefined(Promise.resolve(null))).toBeUndefined();
+  });
+
+  it("returns value", async () => {
+    const expected = "hi";
+
+    expect(await nullToUndefined(Promise.resolve(expected))).toBe(expected);
+  });
+
+  it("supports PromiseLike objects", async () => {
+    const expected = "hello";
+
+    const promiseLike: PromiseLike<string> = {
+      // eslint-disable-next-line unicorn/no-thenable
+      then: function <TResult1, TResult2>(
+        onfulfilled?: ((value: string) => TResult1 | PromiseLike<TResult1>) | undefined,
+      ): PromiseLike<TResult1 | TResult2> {
+        if (onfulfilled) {
+          return Promise.resolve(onfulfilled(expected));
+        }
+
+        return Promise.reject();
+      },
+    };
+
+    expect(await nullToUndefined(promiseLike)).toBe(expected);
+  });
+});

package/src/lib/{null-to-undefined.d.ts → null-to-undefined.ts}

@@ -7,5 +7,7 @@
  *
  * @param value A promise or a promise-like object.
  */
-export declare function nullToUndefined<T>(value: PromiseLike<T | null>): Promise<T | undefined>;
-//# sourceMappingURL=null-to-undefined.d.ts.map
+// eslint-disable-next-line @typescript-eslint/ban-types
+export async function nullToUndefined<T>(value: PromiseLike<T | null>): Promise<T | undefined> {
+  return (await value) ?? undefined;
+}

package/src/lib/option.spec.ts

@@ -0,0 +1,24 @@
+import * as O from "./option";
+
+const { none, some } = O;
+
+describe("Option", () => {
+  it("none is not some", () => {
+    const option = none;
+
+    expect(O.isNone(option)).toBe(true);
+    expect(O.isSome(option)).toBe(false);
+    expect(option.isSome).toBe(false);
+  });
+
+  it("some is some", () => {
+    const value = "my-value";
+
+    const option = some(value);
+
+    expect(O.isNone(option)).toBe(false);
+    expect(O.isSome(option)).toBe(true);
+    expect(option.isSome).toBe(true);
+    expect(option.value).toBe(value);
+  });
+});

package/src/lib/{option.d.ts → option.ts}

@@ -1,28 +1,39 @@
 export interface None {
-    isSome: false;
+  isSome: false;
 }
+
 export interface Some<A> {
-    isSome: true;
-    value: A;
+  isSome: true;
+  value: A;
 }
+
 /**
  * An optional value. If the value exists, it's of type `Some<A>`, otherwise it's of type `None`.
  */
 export type Option<A> = None | Some<A>;
+
 /**
  * Constructs an `Option` of `None`, representing a missing value.
  */
-export declare const none: None;
+export const none: None = { isSome: false };
+
 /**
  * Constructs an `Option` holding a `Some<A>`, representing an optional value that exists.
  */
-export declare function some<A>(value: A): Some<A>;
+export function some<A>(value: A): Some<A> {
+  return { isSome: true, value };
+}
+
 /**
  * Returns `true` if the option is `None`, `false` otherwise.
  */
-export declare function isNone<A>(option: Option<A>): option is None;
+export function isNone<A>(option: Option<A>): option is None {
+  return !option.isSome;
+}
+
 /**
  * Returns `true` if the option is `Some<A>`, `false` otherwise.
  */
-export declare function isSome<A>(option: Option<A>): option is Some<A>;
-//# sourceMappingURL=option.d.ts.map
+export function isSome<A>(option: Option<A>): option is Some<A> {
+  return option.isSome;
+}

package/src/lib/stringify.spec.ts

@@ -0,0 +1,11 @@
+import { stringify } from "./stringify";
+
+describe("stringify", () => {
+  test.each([
+    [1n, '"1"'],
+    [{ a: 1 }, '{"a":1}'],
+    [{ a: 1n }, '{"a":"1"}'],
+  ])("stringify(%i, %i)", (value, expected) => {
+    expect(stringify(value)).toBe(expected);
+  });
+});

package/src/lib/stringify.ts

@@ -0,0 +1,5 @@
+export function stringify(value: unknown): string {
+  return JSON.stringify(value, (_, value: unknown) =>
+    typeof value === "bigint" ? String(value) : value,
+  );
+}

package/src/lib/to-error.spec.ts

@@ -0,0 +1,28 @@
+import { stringify } from "./stringify";
+import { toErrorMessage } from "./to-error";
+
+const MESSAGE = "hi";
+
+describe("toErrorMessage", () => {
+  it("returns message", () => {
+    expect(toErrorMessage(new Error(MESSAGE))).toEqual(MESSAGE);
+  });
+
+  it("returns message if non-error object", () => {
+    const error = { hello: MESSAGE };
+
+    expect(toErrorMessage(error)).toEqual(stringify(error));
+  });
+
+  it("returns message if unable to stringify", () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const circularReference = { a: { b: "c" }, d: {} } as any;
+    circularReference.a.d = circularReference.a;
+
+    expect(toErrorMessage(circularReference)).toBe("[object Object]");
+  });
+
+  it("returns message if string", () => {
+    expect(toErrorMessage(MESSAGE)).toEqual(MESSAGE);
+  });
+});

package/src/lib/to-error.ts

@@ -0,0 +1,20 @@
+import { isString } from "./is-string";
+import { stringify } from "./stringify";
+
+export function isError(error: unknown): error is Error {
+  return error instanceof Error;
+}
+
+export function toError(error: unknown): Error {
+  if (isError(error)) return error;
+
+  try {
+    return new Error(isString(error) ? error : stringify(error));
+  } catch {
+    return new Error(String(error));
+  }
+}
+
+export function toErrorMessage(error: unknown): string {
+  return toError(error).message;
+}