deep-guards 1.0.1 → 1.0.2

package/README.md

@@ -52,15 +52,18 @@ if (vehicleGuard(value)) {
    4. [isNot](#isnot)
    5. [isOneOf](#isoneof)
    6. [isUnionOf](#isunionof)
-   7. [isExact](#isexact)
+   7. [isIntersectionOf](#isintersectionof)
+   8. [isExact](#isexact)
 3. [Structures](#structures)
    1. [isAnyArray](#isanyarray)
    2. [isAnyRecord](#isanyrecord)
    3. [isArrayOf](#isarrayof)
    4. [isRecordOf](#isrecordof)
    5. [isObjectOf](#isobjectof)
-4. [guardOrThrow](#guardorthrow)
-5. [TypeFromGuard](#typefromguard)
+4. [Macros](#macros)
+   1. [isDiscriminatedObjectOf](#isdiscriminatedobjectof)
+5. [guardOrThrow](#guardorthrow)
+6. [TypeFromGuard](#typefromguard)
 
 ## Terminology
 
@@ -123,7 +126,11 @@ It's very useful for enumerations, where you only have a few specific values, e.
 
 ### isUnionOf
 
-Higher order guard. This takes in any amount of guards as arguments, and then produces a guard which does a union over all the incoming guards.
+Higher order guard. This takes in any amount of guards as arguments, and then produces a guard which does a union over all the incoming guards. This means that if _any_ one of the guards passes for the incoming value, then this will pass.
+
+### isIntersectionOf
+
+Higher order guard. This takes in any amount of guards as arguments, and then produces a guard which does an intersection over all the incoming guards. This means that if _every_ one of the guards passes for the incoming value, then this will pass.
 
 ### isExact
 
@@ -168,6 +175,56 @@ As seen in the example at the start of this readme, you can do all sorts of comp
 NOTE: This throws an error if you give it an empty object.\
 It will also accept an object which contains keys which are not specified.
 
+## Macros
+
+These are common use cases for guarding setups, where they are made entirely out of the above guard suite.
+
+### isDiscriminatedObjectOf
+
+This takes in a string literal `type`, and an `isObjectOf` guard. This then combines the two, where the returned guard has the signature: `Guard<{ type: T } & O>`.
+This is good for use cases where you don't have a discriminator on an individual type, but then do have it on the union type. For example:
+
+```ts
+interface Car {
+  wheels: 4;
+  owner: string;
+  passengers: {
+    name: string;
+  }[];
+}
+
+interface Bike {
+  wheels: 2;
+  owner: string;
+  storage?: string[];
+}
+
+type Vehicle = ({ type: "car" } & Car) | ({ type: "bike" } & Bike);
+
+// Can then be represented like so in guards:
+
+const carGuard = isObjectOf({
+  wheels: isExact(4),
+  owner: isString,
+  passengers: isArrayOf(
+    isObjectOf({
+      name: isString,
+    })
+  ),
+});
+
+const bikeGuard = isObjectOf({
+  wheels: isExact(2),
+  owner: isString,
+  storage: isOptional(isArrayOf(isString)),
+});
+
+const vehicleGuard = isUnionOf(
+  isDiscriminatedObjectOf("car", carGuard),
+  isDiscriminatedObjectOf("bike", bikeGuard)
+);
+```
+
 ## guardOrThrow
 
 This package also includes a `guardOrThrow` method which when given an incoming value, a guard, and an optional hint message, will return a narrowed version of the value, or throw a `GuardError` containing that hint message.

package/package.json

@@ -8,7 +8,7 @@
   "type": "module",
   "types": "dist/index.d.ts",
   "homepage": "https://github.com/eniallator/Deep-Guards",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "scripts": {
     "test": "jest",
     "build": "tsc",

package/src/compound.ts

@@ -1,81 +1,101 @@
-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;
-}
+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));
+}
+
+type ArrayToIntersection<A extends readonly unknown[]> = A extends [
+  infer T,
+  ...infer R
+]
+  ? T & ArrayToIntersection<R>
+  : unknown;
+
+export function isIntersectionOf<T extends readonly unknown[]>(
+  ...guards: GuardSchemaOf<T>
+): Guard<ArrayToIntersection<T>> {
+  if (guards.every((guard) => typeof guard !== "function")) {
+    throw new TypeError(
+      `isIntersectionOf expects N guard parameters. Got instead: ${guards}`
+    );
+  }
+
+  return (value): value is ArrayToIntersection<T> =>
+    guards.every((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/macros.ts

@@ -0,0 +1,11 @@
+import { isExact, isIntersectionOf } from "./compound";
+import { isObjectOf } from "./structures";
+import { Guard } from "./types";
+
+export const isDiscriminatedObjectOf = <T extends string, O extends object>(
+  type: T,
+  guard: Guard<O>
+): Guard<{ type: T } & O> =>
+  isIntersectionOf(isObjectOf({ type: isExact(type) }), guard) as Guard<
+    { type: T } & O
+  >;

package/src/structures.ts

@@ -1,83 +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>;
-}
+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 (
+    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}`
+    );
+  } else if (schemaKeys.length === 0) {
+    throw new Error("isObjectOf received an empty schema");
+  }
+
+  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/tests/compound.test.ts

@@ -1,136 +1,151 @@
-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);
-    });
-  });
-});
+import {
+  isExact,
+  isNot,
+  isNullable,
+  isNonNullable,
+  isOneOf,
+  isOptional,
+  isUnionOf,
+  isIntersectionOf,
+} 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", () => {
+  it("succeeds for the expected type, null, or undefined", () => {
+    expect(isNonNullable("foo")).toBe(true);
+    expect(isNonNullable(1)).toBe(true);
+  });
+
+  it("fails any other value", () => {
+    expect(isNonNullable(null)).toBe(false);
+    expect(isNonNullable(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("isIntersectionOf", () => {
+  const guard = isIntersectionOf(
+    isOneOf("foo", "bar", "baz"),
+    isExact("foo", false)
+  );
+
+  it("succeeds for the intersection", () => {
+    expect(guard("foo")).toBe(true);
+  });
+
+  it("fails for any other type", () => {
+    expect(guard("bar")).toBe(false);
+    expect(guard(1)).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);
+    });
+  });
+});