@clipboard-health/testing-core 0.1.1 → 0.3.0

package/README.md

@@ -1,11 +1,12 @@
 # @clipboard-health/testing-core <!-- omit from toc -->
 
-Core utilities for testing Clipboard Health's software.
+TypeScript-friendly testing utilities.
 
 ## Table of contents <!-- omit from toc -->
 
 - [Install](#install)
 - [Usage](#usage)
+  - [Type narrowing `expect` helpers](#type-narrowing-expect-helpers)
 - [Local development commands](#local-development-commands)
 
 ## Install
@@ -16,6 +17,136 @@ npm install @clipboard-health/testing-core
 
 ## Usage
 
+### Type narrowing `expect` helpers
+
+Jest's [`expect(...).toBeDefined()`](https://jestjs.io/docs/expect#tobedefined) does not narrow types.
+
+This gives a type error:
+
+```ts
+const value = getValue(); // returns 'string | undefined'
+
+expect(value).toBeDefined();
+
+const { length } = value;
+// ^? Property 'length' does not exist on type 'string | undefined'.
+```
+
+This library's helpers narrow types:
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/expectToBeDefined.ts
+
+import { ok } from "node:assert/strict";
+
+import { expectToBeDefined } from "@clipboard-health/testing-core";
+
+function getValue(): string | undefined {
+  return "hi";
+}
+
+const value = getValue();
+expectToBeDefined(value);
+
+// Narrowed to `string`
+const { length } = value;
+ok(length === 2);
+
+```
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/expectToBeLeft.ts
+
+import { ok } from "node:assert/strict";
+
+import { expectToBeLeft } from "@clipboard-health/testing-core";
+import { type Either, left, right } from "@clipboard-health/util-typescript";
+
+function divide(numerator: number, denominator: number): Either<string, number> {
+  if (denominator === 0) {
+    return left("Cannot divide by zero");
+  }
+
+  return right(numerator / denominator);
+}
+
+const value = divide(10, 0);
+expectToBeLeft(value);
+
+// Narrowed to Left
+ok(value.left === "Cannot divide by zero");
+
+```
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/expectToBeRight.ts
+
+import { ok } from "node:assert/strict";
+
+import { expectToBeRight } from "@clipboard-health/testing-core";
+import { type Either, left, right } from "@clipboard-health/util-typescript";
+
+function divide(numerator: number, denominator: number): Either<string, number> {
+  if (denominator === 0) {
+    return left("Cannot divide by zero");
+  }
+
+  return right(numerator / denominator);
+}
+
+const value = divide(10, 2);
+expectToBeRight(value);
+
+// Narrowed to Right
+ok(value.right === 5);
+
+```
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/expectToBeSafeParseError.ts
+
+import { ok } from "node:assert/strict";
+
+import { expectToBeDefined, expectToBeSafeParseError } from "@clipboard-health/testing-core";
+import { z } from "zod";
+
+const schema = z.object({ name: z.string() });
+
+const value = schema.safeParse({ name: 1 });
+expectToBeSafeParseError(value);
+
+// Narrowed to `SafeParseError`
+const firstIssue = value.error.issues[0];
+expectToBeDefined(firstIssue);
+
+// Narrowed to `ZodIssue`
+ok(firstIssue.message === "Expected string, received number");
+
+```
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/expectToBeSafeParseSuccess.ts
+
+import { ok } from "node:assert/strict";
+
+import { expectToBeSafeParseSuccess } from "@clipboard-health/testing-core";
+import { z } from "zod";
+
+const schema = z.object({ name: z.string() });
+
+const value = schema.safeParse({ name: "hi" });
+expectToBeSafeParseSuccess(value);
+
+// Narrowed to `SafeParseSuccess`
+ok(value.data.name === "hi");
+
+```
+
 ## Local development commands
 
 See [`package.json`](./package.json) `scripts` for a list of commands.

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@clipboard-health/testing-core",
-  "description": "Core utilities for testing Clipboard Health's software.",
-  "version": "0.1.1",
+  "description": "TypeScript-friendly testing utilities.",
+  "version": "0.3.0",
   "dependencies": {
+    "@clipboard-health/util-typescript": "0.1.0",
     "tslib": "2.8.0",
     "zod": "3.23.8"
   },
@@ -12,6 +13,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "embed": "embedme README.md"
+  },
   "type": "commonjs",
   "typings": "./src/index.d.ts",
   "types": "./src/index.d.ts"

package/src/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./lib/expectToBeDefined";
+export * from "./lib/expectToBeLeft";
+export * from "./lib/expectToBeRight";
 export * from "./lib/expectToBeSafeParseError";
 export * from "./lib/expectToBeSafeParseSuccess";

package/src/index.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./lib/expectToBeDefined"), exports);
+tslib_1.__exportStar(require("./lib/expectToBeLeft"), exports);
+tslib_1.__exportStar(require("./lib/expectToBeRight"), exports);
 tslib_1.__exportStar(require("./lib/expectToBeSafeParseError"), exports);
 tslib_1.__exportStar(require("./lib/expectToBeSafeParseSuccess"), exports);
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/testing-core/src/index.ts"],"names":[],"mappings":";;;AAAA,kEAAwC;AACxC,yEAA+C;AAC/C,2EAAiD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/testing-core/src/index.ts"],"names":[],"mappings":";;;AAAA,kEAAwC;AACxC,+DAAqC;AACrC,gEAAsC;AACtC,yEAA+C;AAC/C,2EAAiD"}

package/src/lib/expectToBeLeft.d.ts

@@ -0,0 +1,2 @@
+import { type Either, type Left } from "@clipboard-health/util-typescript";
+export declare function expectToBeLeft<E, A>(value: Either<E, A> | undefined): asserts value is Left<E>;

package/src/lib/expectToBeLeft.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expectToBeLeft = expectToBeLeft;
+const node_assert_1 = require("node:assert");
+const util_typescript_1 = require("@clipboard-health/util-typescript");
+const expectToBeDefined_1 = require("./expectToBeDefined");
+function expectToBeLeft(value) {
+    (0, expectToBeDefined_1.expectToBeDefined)(value);
+    (0, node_assert_1.ok)((0, util_typescript_1.isLeft)(value));
+}
+//# sourceMappingURL=expectToBeLeft.js.map

package/src/lib/expectToBeLeft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expectToBeLeft.js","sourceRoot":"","sources":["../../../../../packages/testing-core/src/lib/expectToBeLeft.ts"],"names":[],"mappings":";;AAMA,wCAGC;AATD,6CAAiC;AAEjC,uEAAmF;AAEnF,2DAAwD;AAExD,SAAgB,cAAc,CAAO,KAA+B;IAClE,IAAA,qCAAiB,EAAC,KAAK,CAAC,CAAC;IACzB,IAAA,gBAAE,EAAC,IAAA,wBAAM,EAAC,KAAK,CAAC,CAAC,CAAC;AACpB,CAAC"}

package/src/lib/expectToBeNone.d.ts

@@ -0,0 +1,2 @@
+import { type None, type Option } from "@clipboard-health/util-typescript";
+export declare function expectToBeNone<A>(value: Option<A> | undefined): asserts value is None;

package/src/lib/expectToBeNone.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expectToBeNone = expectToBeNone;
+const node_assert_1 = require("node:assert");
+const util_typescript_1 = require("@clipboard-health/util-typescript");
+const expectToBeDefined_1 = require("./expectToBeDefined");
+function expectToBeNone(value) {
+    (0, expectToBeDefined_1.expectToBeDefined)(value);
+    (0, node_assert_1.ok)((0, util_typescript_1.isNone)(value));
+}
+//# sourceMappingURL=expectToBeNone.js.map

package/src/lib/expectToBeNone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expectToBeNone.js","sourceRoot":"","sources":["../../../../../packages/testing-core/src/lib/expectToBeNone.ts"],"names":[],"mappings":";;AAMA,wCAGC;AATD,6CAAiC;AAEjC,uEAAmF;AAEnF,2DAAwD;AAExD,SAAgB,cAAc,CAAI,KAA4B;IAC5D,IAAA,qCAAiB,EAAC,KAAK,CAAC,CAAC;IACzB,IAAA,gBAAE,EAAC,IAAA,wBAAM,EAAC,KAAK,CAAC,CAAC,CAAC;AACpB,CAAC"}

package/src/lib/expectToBeRight.d.ts

@@ -0,0 +1,2 @@
+import { type Either, type Right } from "@clipboard-health/util-typescript";
+export declare function expectToBeRight<A, E>(value: Either<E, A> | undefined): asserts value is Right<A>;

package/src/lib/expectToBeRight.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expectToBeRight = expectToBeRight;
+const node_assert_1 = require("node:assert");
+const util_typescript_1 = require("@clipboard-health/util-typescript");
+const expectToBeDefined_1 = require("./expectToBeDefined");
+function expectToBeRight(value) {
+    (0, expectToBeDefined_1.expectToBeDefined)(value);
+    (0, node_assert_1.ok)((0, util_typescript_1.isRight)(value));
+}
+//# sourceMappingURL=expectToBeRight.js.map

package/src/lib/expectToBeRight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expectToBeRight.js","sourceRoot":"","sources":["../../../../../packages/testing-core/src/lib/expectToBeRight.ts"],"names":[],"mappings":";;AAMA,0CAGC;AATD,6CAAiC;AAEjC,uEAAqF;AAErF,2DAAwD;AAExD,SAAgB,eAAe,CAAO,KAA+B;IACnE,IAAA,qCAAiB,EAAC,KAAK,CAAC,CAAC;IACzB,IAAA,gBAAE,EAAC,IAAA,yBAAO,EAAC,KAAK,CAAC,CAAC,CAAC;AACrB,CAAC"}

package/src/lib/expectToBeSome.d.ts

@@ -0,0 +1,2 @@
+import { type Option, type Some } from "@clipboard-health/util-typescript";
+export declare function expectToBeSome<A>(value: Option<A> | undefined): asserts value is Some<A>;

package/src/lib/expectToBeSome.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expectToBeSome = expectToBeSome;
+const node_assert_1 = require("node:assert");
+const util_typescript_1 = require("@clipboard-health/util-typescript");
+const expectToBeDefined_1 = require("./expectToBeDefined");
+function expectToBeSome(value) {
+    (0, expectToBeDefined_1.expectToBeDefined)(value);
+    (0, node_assert_1.ok)((0, util_typescript_1.isSome)(value));
+}
+//# sourceMappingURL=expectToBeSome.js.map

package/src/lib/expectToBeSome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expectToBeSome.js","sourceRoot":"","sources":["../../../../../packages/testing-core/src/lib/expectToBeSome.ts"],"names":[],"mappings":";;AAMA,wCAGC;AATD,6CAAiC;AAEjC,uEAAmF;AAEnF,2DAAwD;AAExD,SAAgB,cAAc,CAAI,KAA4B;IAC5D,IAAA,qCAAiB,EAAC,KAAK,CAAC,CAAC;IACzB,IAAA,gBAAE,EAAC,IAAA,wBAAM,EAAC,KAAK,CAAC,CAAC,CAAC;AACpB,CAAC"}