deep-guards 1.0.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "author": "eniallator",
+  "description": "Deep guarding package",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "name": "deep-guards",
+  "packageManager": "yarn@3.8.2",
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "version": "1.0.0",
+  "scripts": {
+    "test": "jest",
+    "build": "tsc",
+    "lint": "eslint ./src",
+    "typecheck": "tsc --noEmit",
+    "findissues": "yarn typecheck && yarn lint"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.26.0",
+    "@babel/preset-env": "^7.26.0",
+    "@babel/preset-typescript": "^7.26.0",
+    "@eslint/compat": "^1.2.3",
+    "@eslint/js": "^9.15.0",
+    "@jest/globals": "^29.7.0",
+    "@types/babel__core": "^7.20.5",
+    "@types/babel__preset-env": "^7.9.7",
+    "@types/eslint": "^9.6.1",
+    "@types/eslint__js": "^8.42.3",
+    "@types/jest": "^29.5.14",
+    "@typescript-eslint/eslint-plugin": "^8.15.0",
+    "@typescript-eslint/parser": "^8.15.0",
+    "babel-jest": "^29.7.0",
+    "eslint": "^9.15.0",
+    "eslint-plugin-eslint-comments": "^3.2.0",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jest": "^28.9.0",
+    "jest": "^29.7.0",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.15.0"
+  }
+}

package/src/compound.ts

@@ -0,0 +1,81 @@
+import { Guard, GuardSchemaOf } from "./types.js";
+
+export function isOptional<T>(guard: Guard<T>): Guard<T | undefined> {
+  if (typeof guard !== "function") {
+    throw new TypeError(
+      `isOptional expects a guard parameter. Got instead: ${guard}`
+    );
+  }
+
+  return ((value) => value === undefined || guard(value)) as Guard<
+    T | undefined
+  >;
+}
+
+export function isNullable<T>(guard: Guard<T>): Guard<T | null | undefined> {
+  if (typeof guard !== "function") {
+    throw new TypeError(
+      `isNullable expects a guard parameter. Got instead: ${guard}`
+    );
+  }
+
+  return (value: unknown): value is T | null | undefined =>
+    value == null || guard(value);
+}
+
+export function isNonNullable<T>(value: T | null | undefined): value is T {
+  return value != null;
+}
+
+export function isNot<const N>(guard: Guard<N>) {
+  if (typeof guard !== "function") {
+    throw new TypeError(
+      `isNot expects a guard parameter. Got instead: ${guard}`
+    );
+  }
+
+  return <const T>(value: T | N): value is T => !guard(value);
+}
+
+export function isOneOf<
+  const T extends (string | number | boolean | symbol | null | undefined)[]
+>(...values: T): Guard<(typeof values)[number]> {
+  const valueSet = new Set(values);
+  return (value: unknown): value is T[number] =>
+    valueSet.has(value as T[number]);
+}
+
+export function isUnionOf<T extends readonly unknown[]>(
+  ...guards: GuardSchemaOf<T>
+): Guard<T[number]> {
+  if (guards.every((guard) => typeof guard !== "function")) {
+    throw new TypeError(
+      `isUnionOf expects N guard parameters. Got instead: ${guards}`
+    );
+  }
+
+  return (value): value is T => guards.some((guard) => guard(value));
+}
+
+function isEqual<T>(a: T, b: unknown): b is T {
+  return (
+    a === b ||
+    (a != null &&
+      b != null &&
+      typeof a === "object" &&
+      typeof b === "object" &&
+      (Array.isArray(a)
+        ? Array.isArray(b) &&
+          a.length === b.length &&
+          a.every((v, i) => isEqual(v, b[i]))
+        : Object.keys(a).length === Object.keys(b).length &&
+          Object.entries(a).every(
+            ([k, v]) => k in b && isEqual(v, (b as Record<string, unknown>)[k])
+          )))
+  );
+}
+
+export function isExact<const T>(expected: T, deep: boolean = true): Guard<T> {
+  return (value): value is T =>
+    deep ? isEqual(expected, value) : expected === value;
+}

package/src/errors.ts

@@ -0,0 +1,17 @@
+import { Guard } from "./types.js";
+
+export class GuardError extends Error {
+  name = "GuardError";
+}
+
+export function guardOrThrow<T>(
+  value: unknown,
+  guard: Guard<T>,
+  hint?: string
+): T {
+  if (guard(value)) {
+    return value;
+  } else {
+    throw new GuardError(hint ?? "Guard error");
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./compound.js";
+export * from "./errors.js";
+export * from "./primitives.js";
+export * from "./structures.js";
+export * from "./types.js";

package/src/primitives.ts

@@ -0,0 +1,23 @@
+import { Guard } from "./types.js";
+
+export const isUnknown: Guard<unknown> = (_value): _value is unknown => true;
+
+export const isNull: Guard<null> = (value) => value === null;
+
+export const isUndefined: Guard<undefined> = (value) => value === undefined;
+
+export const isNumber: Guard<number> = (value) => typeof value === "number";
+
+export const isInteger: Guard<number> = (value): value is number =>
+  Number.isInteger(value);
+
+export const isString: Guard<string> = (value) => typeof value === "string";
+
+export const isSymbol: Guard<symbol> = (value) => typeof value === "symbol";
+
+export const isBoolean: Guard<boolean> = (value) =>
+  value === true || value === false;
+
+export const isFunction: Guard<(...args: unknown[]) => unknown> = (
+  value
+): value is (...args: unknown[]) => unknown => typeof value === "function";

package/src/structures.ts

@@ -0,0 +1,83 @@
+import { Guard, GuardSchemaOf } from "./types.js";
+
+type ObjectKey = string | number | symbol;
+
+function objectKeys<K extends ObjectKey>(obj: Record<K, unknown>): K[] {
+  return (Object.getOwnPropertyNames(obj) as K[]).concat(
+    Object.getOwnPropertySymbols(obj) as K[]
+  );
+}
+
+export const isAnyArray: Guard<unknown[]> = (value) => Array.isArray(value);
+
+export const isAnyRecord: Guard<Record<ObjectKey, unknown>> = (
+  value
+): value is Record<ObjectKey, unknown> =>
+  value != null && typeof value === "object" && !Array.isArray(value);
+
+export function isArrayOf<T>(guard: Guard<T>): Guard<T[]> {
+  if (typeof guard !== "function") {
+    throw new TypeError(
+      `isArrayOf expects a guard parameter. Got instead: ${guard}`
+    );
+  }
+
+  return (value): value is T[] => Array.isArray(value) && value.every(guard);
+}
+
+export function isRecordOf<K extends ObjectKey>(
+  keyGuard: Guard<K>
+): Guard<Record<K, unknown>>;
+export function isRecordOf<K extends ObjectKey, V>(
+  keyGuard: Guard<K>,
+  valueGuard: Guard<V>
+): Guard<Record<K, V>>;
+export function isRecordOf<K extends ObjectKey, V>(
+  keyGuard: Guard<K>,
+  valueGuard?: Guard<V>
+): Guard<Record<K, V>> {
+  if (typeof keyGuard !== "function") {
+    throw new TypeError(
+      `isRecordOf keyGuard expects a guard parameter. Got instead: ${keyGuard}`
+    );
+  } else if (valueGuard != null && typeof valueGuard !== "function") {
+    throw new TypeError(
+      `isRecordOf valueGuard expects an optional guard parameter. Got instead: ${valueGuard}`
+    );
+  }
+
+  return (value): value is Record<K, V> =>
+    value != null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    objectKeys(value).every(
+      (key) => keyGuard(key) && (valueGuard?.(value[key]) ?? true)
+    );
+}
+
+export function isObjectOf<O extends object>(
+  schema: GuardSchemaOf<O>
+): O extends unknown[] ? never : Guard<O> {
+  const schemaKeys = objectKeys(schema);
+  const schemaUnknown = schema as unknown;
+  if (schemaKeys.length === 0) {
+    throw new Error("isObjectOf received an empty schema");
+  } else if (
+    schemaUnknown == null ||
+    typeof schemaUnknown !== "object" ||
+    Array.isArray(schemaUnknown) ||
+    schemaKeys.some((key) => typeof (schemaUnknown as O)[key] !== "function")
+  ) {
+    throw new TypeError(
+      `isObjectOf expects a guard schema. Got instead: ${schemaUnknown}`
+    );
+  }
+
+  return ((value): value is O =>
+    value != null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    schemaKeys.every(
+      (key) => key in value && schema[key]((value as O)[key])
+    )) as O extends unknown[] ? never : Guard<O>;
+}

package/src/types.ts

@@ -0,0 +1,5 @@
+export type Guard<T> = (value: unknown) => value is T;
+
+export type GuardSchemaOf<O extends object> = {
+  [K in keyof O]: Guard<O[K]>;
+};

package/tests/compound.test.ts

@@ -0,0 +1,136 @@
+import {
+  isExact,
+  isNot,
+  isNullable,
+  isNonNullable,
+  isOneOf,
+  isOptional,
+  isUnionOf,
+} from "../src/compound";
+import { isNumber, isString } from "../src/primitives";
+
+describe("isOptional", () => {
+  const guard = isOptional(isString);
+
+  it("succeeds for the expected type or undefined", () => {
+    expect(guard("foo")).toBe(true);
+    expect(guard(undefined)).toBe(true);
+  });
+
+  it("fails for any other value", () => {
+    expect(guard(null)).toBe(false);
+  });
+});
+
+describe("isNullable", () => {
+  const guard = isNullable(isString);
+
+  it("succeeds for the expected type, null, or undefined", () => {
+    expect(guard("foo")).toBe(true);
+    expect(guard(null)).toBe(true);
+    expect(guard(undefined)).toBe(true);
+  });
+
+  it("fails any other value", () => {
+    expect(guard(1)).toBe(false);
+  });
+});
+
+describe("isNonNullable", () => {
+  const guard = isNonNullable;
+
+  it("succeeds for the expected type, null, or undefined", () => {
+    expect(guard("foo")).toBe(true);
+    expect(guard(1)).toBe(true);
+  });
+
+  it("fails any other value", () => {
+    expect(guard(null)).toBe(false);
+    expect(guard(undefined)).toBe(false);
+  });
+});
+
+describe("isNot", () => {
+  const guard = isNot(isString);
+
+  it("succeeds for any other value", () => {
+    expect(guard(1)).toBe(true);
+  });
+
+  it("fails for the isNot type", () => {
+    expect(guard("foo")).toBe(false);
+  });
+});
+
+describe("isOneOf", () => {
+  const guard = isOneOf(1, "foo", true);
+
+  it("succeeds for all of the values", () => {
+    expect(guard(1)).toBe(true);
+    expect(guard("foo")).toBe(true);
+    expect(guard(true)).toBe(true);
+  });
+
+  expect(guard(2)).toBe(false);
+  it("fails any other value", () => {
+    expect(guard(null)).toBe(false);
+    expect(guard("bar")).toBe(false);
+    expect(guard(false)).toBe(false);
+  });
+});
+
+describe("isUnionOf", () => {
+  const guard = isUnionOf(isString, isNumber);
+  it("succeeds for the union types", () => {
+    expect(guard(1)).toBe(true);
+    expect(guard("foo")).toBe(true);
+  });
+
+  it("fails for any other type", () => {
+    expect(guard(true)).toBe(false);
+    expect(guard(null)).toBe(false);
+  });
+});
+
+describe("isExact", () => {
+  describe("deep", () => {
+    const guard = isExact(
+      { foo: "bar", hello: ["world", { key: "test" }] },
+      true
+    );
+
+    it("succeeds for the exact value", () => {
+      expect(guard({ foo: "bar", hello: ["world", { key: "test" }] })).toBe(
+        true
+      );
+    });
+
+    it("fails for any other value", () => {
+      expect(guard({ foo: "baz", hello: ["world", { key: "test" }] })).toBe(
+        false
+      );
+      expect(guard({ foo: "bar", hello: ["world", { key: "tester" }] })).toBe(
+        false
+      );
+      expect(guard(1)).toBe(false);
+    });
+  });
+
+  describe("shallow", () => {
+    const guard = isExact("foo", false);
+
+    it("succeeds for the exact value", () => {
+      expect(guard("foo")).toBe(true);
+    });
+
+    it("fails for deep equality", () => {
+      const guard = isExact(["foo", "bar", "baz", 1, 2, 3], false);
+      expect(guard(["foo", "bar", "baz", 1, 2, 3])).toBe(false);
+    });
+
+    it("fails for any other value", () => {
+      expect(guard("bar")).toBe(false);
+      expect(guard(1)).toBe(false);
+    });
+  });
+});

package/tests/primitives.test.ts

@@ -0,0 +1,91 @@
+import {
+  isBoolean,
+  isFunction,
+  isInteger,
+  isNull,
+  isNumber,
+  isString,
+  isUndefined,
+  isUnknown,
+} from "../src/primitives";
+
+describe("isUnknown", () => {
+  it("succeeds for any value", () => {
+    expect(isUnknown("unknown")).toBe(true);
+  });
+});
+
+describe("isAnyFunction", () => {
+  it("succeeds for a function", () => {
+    expect(isFunction(() => {})).toBe(true);
+  });
+
+  it("fails for any other value", () => {
+    expect(isFunction(1)).toBe(false);
+  });
+});
+
+describe("isNull", () => {
+  it("succeeds for null", () => {
+    expect(isNull(null)).toBe(true);
+  });
+
+  it("fails for any other value", () => {
+    expect(isNull(undefined)).toBe(false);
+  });
+});
+
+describe("isUndefined", () => {
+  it("succeeds for undefined", () => {
+    expect(isUndefined(undefined)).toBe(true);
+  });
+
+  it("fails for any other value", () => {
+    expect(isUndefined(null)).toBe(false);
+  });
+});
+
+describe("isNumber", () => {
+  it("succeeds for a number", () => {
+    expect(isNumber(1.23)).toBe(true);
+  });
+
+  it("fails for any other type", () => {
+    expect(isNumber("foo")).toBe(false);
+  });
+});
+
+describe("isInteger", () => {
+  it("succeeds for an integer", () => {
+    expect(isInteger(1)).toBe(true);
+  });
+
+  it("fails for a non-integer", () => {
+    expect(isInteger(1.23)).toBe(false);
+  });
+
+  it("fails for any other type", () => {
+    expect(isInteger("foo")).toBe(false);
+  });
+});
+
+describe("isString", () => {
+  it("succeeds for a string", () => {
+    expect(isString("Foo bar")).toBe(true);
+  });
+
+  it("fails for other types", () => {
+    expect(isString(true)).toBe(false);
+  });
+});
+
+describe("isBoolean", () => {
+  it("succeeds for a boolean", () => {
+    expect(isBoolean(true)).toBe(true);
+    expect(isBoolean(false)).toBe(true);
+  });
+
+  it("fails for other types", () => {
+    expect(isBoolean("foo")).toBe(false);
+  });
+});

package/tests/structures.test.ts

@@ -0,0 +1,110 @@
+import { isNumber, isString, isSymbol } from "../src/primitives";
+import {
+  isAnyArray,
+  isAnyRecord,
+  isArrayOf,
+  isObjectOf,
+  isRecordOf,
+} from "../src/structures";
+
+describe("isAnyArray", () => {
+  it("succeeds for an array", () => {
+    expect(isAnyArray([])).toBe(true);
+    expect(isAnyArray(["foo", 1, true, null])).toBe(true);
+  });
+
+  it("fails for any other value", () => {
+    expect(isAnyArray({})).toBe(false);
+    expect(isAnyArray(1)).toBe(false);
+  });
+});
+
+describe("isAnyRecord", () => {
+  it("succeeds for a record", () => {
+    expect(isAnyRecord({})).toBe(true);
+    expect(isAnyRecord({ foo: "bar", baz: 1 })).toBe(true);
+  });
+
+  it("fails for any other value", () => {
+    expect(isAnyRecord([])).toBe(false);
+    expect(isAnyRecord(1)).toBe(false);
+  });
+});
+
+describe("isArrayOf", () => {
+  const guard = isArrayOf(isString);
+
+  it("succeeds for an array of the value", () => {
+    expect(guard([])).toBe(true);
+    expect(guard(["foo", "bar", "baz"])).toBe(true);
+  });
+
+  it("fails for any other value", () => {
+    expect(guard([1, 2, 3])).toBe(false);
+    expect(guard(["foo", "bar", null])).toBe(false);
+    expect(guard(1)).toBe(false);
+  });
+});
+
+describe("isObjectOf", () => {
+  const barSymbol = Symbol("bar");
+  const guard = isObjectOf({
+    foo: isString,
+    [barSymbol]: isNumber,
+    baz: isObjectOf({
+      qux: isSymbol,
+    }),
+  });
+
+  it("succeeds for an object of the value", () => {
+    expect(
+      guard({
+        foo: "hello",
+        [barSymbol]: 1,
+        baz: { qux: Symbol("world!") },
+        quux: "this should not be checked",
+      })
+    ).toBe(true);
+  });
+
+  it("fails for any other value", () => {
+    expect(
+      guard({
+        foo: "hello",
+        [barSymbol]: "FAIL",
+        baz: { qux: Symbol("world!") },
+      })
+    ).toBe(false);
+    expect(guard(1)).toBe(false);
+  });
+});
+
+describe("isRecordOf", () => {
+  describe("with valueGuard", () => {
+    const guard = isRecordOf(isString, isNumber);
+
+    it("succeeds for a record of the key/value types", () => {
+      expect(guard({})).toBe(true);
+      expect(guard({ foo: 1, bar: 2 })).toBe(true);
+    });
+
+    it("fails for any other value", () => {
+      expect(guard({ foo: "bar", baz: 1 })).toBe(false);
+      expect(guard(1)).toBe(false);
+    });
+  });
+
+  describe("without valueGuard", () => {
+    const guard = isRecordOf(isString);
+
+    it("succeeds for a record with the key type", () => {
+      expect(guard({})).toBe(true);
+      expect(guard({ foo: 1, bar: "baz" })).toBe(true);
+    });
+
+    it("fails for any other value", () => {
+      expect(guard({ 1: "foo", [Symbol("bar")]: 1 })).toBe(false);
+      expect(guard(1)).toBe(false);
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "include": ["src"],
+  "compilerOptions": {
+    "allowJs": false,
+    "allowSyntheticDefaultImports": true,
+    "declaration": true,
+    "downlevelIteration": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "lib": ["esnext"],
+    "module": "esnext",
+    "sourceRoot": "src",
+    "moduleResolution": "Bundler",
+    "noErrorTruncation": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "outDir": "dist",
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "esnext"
+  }
+}