chore: basic types and helpers

Author: cesarenaldi

package.json

@@ -19,7 +19,7 @@
     "lint:fix": "biome check --write",
     "new:package": "NODE_OPTIONS='--import tsx' plop --plopfile=plopfile.ts",
     "prepublish": "pnpm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "vitest"
   },
   "license": "MIT",
   "devDependencies": {

packages/types/package.json

@@ -19,15 +19,25 @@
   },
   "typesVersions": {
     "*": {
-      "import": ["./dist/index.d.ts"],
-      "require": ["./dist/index.d.cts"]
+      "import": [
+        "./dist/index.d.ts"
+      ],
+      "require": [
+        "./dist/index.d.cts"
+      ]
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
   "scripts": {
     "build": "tsup"
   },
-  "dependencies": {},
+  "dependencies": {
+    "neverthrow": "^8.2.0",
+    "type-fest": "^4.41.0"
+  },
   "devDependencies": {
     "tsup": "^8.5.0",
     "typescript": "^5.6.3"

packages/types/src/errors.ts

@@ -0,0 +1,70 @@
+import { err, errAsync, type Result, type ResultAsync } from 'neverthrow';
+
+export class ResultAwareError extends Error {
+  /**
+   * @internal
+   */
+  asResultAsync(): ResultAsync<never, typeof this> {
+    return errAsync(this);
+  }
+
+  /**
+   * @internal
+   */
+  asResult(): Result<never, typeof this> {
+    return err(this);
+  }
+
+  /**
+   * @internal
+   */
+  static from<T extends typeof ResultAwareError>(
+    this: T,
+    message: string,
+  ): InstanceType<T>;
+  static from<T extends typeof ResultAwareError>(
+    this: T,
+    cause: unknown,
+  ): InstanceType<T>;
+  static from<T extends typeof ResultAwareError>(
+    this: T,
+    args: unknown,
+  ): InstanceType<T> {
+    if (args instanceof Error) {
+      // biome-ignore lint/complexity/noThisInStatic: intentional
+      const message = this.formatMessage(args);
+      // biome-ignore lint/complexity/noThisInStatic: intentional
+      return new this(message, { cause: args }) as InstanceType<T>;
+    }
+    // biome-ignore lint/complexity/noThisInStatic: intentional
+    return new this(String(args)) as InstanceType<T>;
+  }
+
+  static is<T extends typeof ResultAwareError>(
+    this: T,
+    error: unknown,
+  ): error is InstanceType<T> {
+    // biome-ignore lint/complexity/noThisInStatic: intentional
+    return error instanceof this;
+  }
+
+  private static formatMessage(cause: Error): string {
+    const messages: string[] = [];
+    let currentError: unknown = cause;
+
+    while (currentError instanceof Error) {
+      if ('errors' in currentError && Array.isArray(currentError.errors)) {
+        // Handle AggregateError
+        const inner = currentError.errors.map((e: unknown) =>
+          e instanceof Error ? e.message : String(e),
+        );
+        messages.push(inner.join(', '));
+      } else {
+        messages.push(currentError.message);
+      }
+      currentError = currentError.cause;
+    }
+
+    return messages.join(' due to ');
+  }
+}

packages/types/src/helpers/Deferred.ts

@@ -0,0 +1,15 @@
+/**
+ * Unwraps the promise to allow resolving/rejecting outside the Promise constructor
+ */
+export class Deferred<T = void> {
+  readonly promise: Promise<T>;
+  resolve!: (value: T) => void;
+  reject!: (reason?: unknown) => void;
+
+  constructor() {
+    this.promise = new Promise<T>((resolve, reject) => {
+      this.resolve = resolve;
+      this.reject = reject;
+    });
+  }
+}

packages/types/src/helpers/assertions.ts

@@ -0,0 +1,60 @@
+import type { Err, Ok, Result } from 'neverthrow';
+import type { UnknownRecord } from 'type-fest';
+import { InvariantError } from './invariant';
+
+function isObject(value: unknown): value is UnknownRecord {
+  const type = typeof value;
+  return value != null && (type === 'object' || type === 'function');
+}
+
+export function assertError(error: unknown): asserts error is Error {
+  // why not `error instanceof Error`? see https://github.com/microsoft/TypeScript-DOM-lib-generator/issues/1099
+  // biome-ignore lint/suspicious/noPrototypeBuiltins: safe
+  if (!isObject(error) || !Error.prototype.isPrototypeOf(error)) {
+    throw error;
+  }
+}
+
+/**
+ * Exhaustiveness checking for union and enum types
+ * see https://www.typescriptlang.org/docs/handbook/2/narrowing.html#exhaustiveness-checking
+ */
+export function assertNever(
+  x: never,
+  message = `Unexpected object: ${String(x)}`,
+): never {
+  throw new InvariantError(message);
+}
+
+/**
+ * Asserts that the given `Result<T, E>` is an `Ok<T, never>` variant.
+ */
+export function assertOk<T, E extends Error>(
+  result: Result<T, E>,
+): asserts result is Ok<T, E> {
+  if (result.isErr()) {
+    throw new InvariantError(
+      `Expected result to be Ok: ${result.error.message}`,
+    );
+  }
+}
+
+/**
+ * Asserts that the given `Result<T, E>` is an `Err<never, E>` variant.
+ */
+export function assertErr<T, E extends Error>(
+  result: Result<T, E>,
+): asserts result is Err<T, E> {
+  if (result.isOk()) {
+    throw new InvariantError(`Expected result to be Err: ${result.value}`);
+  }
+}
+
+/**
+ * Asserts that the given value is not `null`.
+ */
+export function assertNotNull<T>(value: T): asserts value is Exclude<T, null> {
+  if (value === null) {
+    throw new InvariantError('Expected value to be not null');
+  }
+}

packages/types/src/helpers/identity.ts

@@ -0,0 +1,15 @@
+/**
+ * The identity function returns the input value unchanged.
+ *
+ * @typeParam T - The type of the input and output.
+ * @param value - The value to return.
+ * @returns The same value that was passed in.
+ */
+export function identity<T>(value: T): T {
+  return value;
+}
+
+/**
+ * Alias for the {@link identity} function.
+ */
+export const passthrough = identity;

packages/types/src/helpers/index.ts

@@ -0,0 +1,7 @@
+export * from './assertions';
+export * from './Deferred';
+export * from './identity';
+export * from './invariant';
+export * from './never';
+export * from './refinements';
+export * from './typeguards';

packages/types/src/helpers/invariant.ts

@@ -0,0 +1,22 @@
+/**
+ * An error that occurs when a task violates a logical condition that is assumed to be true at all times.
+ */
+export class InvariantError extends Error {
+  name = 'InvariantError' as const;
+}
+
+/**
+ * Asserts that the given condition is truthy
+ * @internal
+ *
+ * @param condition - Either truthy or falsy value
+ * @param message - An error message
+ */
+export function invariant(
+  condition: unknown,
+  message: string,
+): asserts condition {
+  if (!condition) {
+    throw new InvariantError(message);
+  }
+}

packages/types/src/helpers/never.ts

@@ -0,0 +1,5 @@
+import { InvariantError } from './invariant';
+
+export function never(message = 'Unexpected call to never()'): never {
+  throw new InvariantError(message);
+}

packages/types/src/helpers/refinements.ts

@@ -0,0 +1,28 @@
+import { InvariantError } from './invariant';
+
+/**
+ * Refinement function to check if a value is not null or undefined.
+ */
+export function nonNullable<T>(value: T): Exclude<T, null | undefined> {
+  if (value === null || value === undefined) {
+    throw new InvariantError('Value should not be null or undefined');
+  }
+  return value as Exclude<T, null | undefined>;
+}
+
+/**
+ * Creates a refinement function to check if a value has a specific `__typename` in a union of types with `__typename`.
+ */
+export function expectTypename<
+  T extends { __typename: string },
+  Name extends T['__typename'],
+>(typename: Name) {
+  return (value: T): Extract<T, { __typename: Name }> => {
+    if (value.__typename !== typename) {
+      throw new InvariantError(
+        `Expected __typename to be "${typename}", but got "${value.__typename}"`,
+      );
+    }
+    return value as Extract<T, { __typename: Name }>;
+  };
+}