👍 Add isOptionalOf

Author: Milly

is.ts

@@ -273,6 +273,27 @@ export function isOneOf<T extends readonly Predicate<unknown>[]>(
   return (x: unknown): x is OneOf<T> => preds.some((pred) => pred(x));
 }
 
+export type OptionalPredicate<T> = Predicate<T | undefined>;
+
+/**
+ * Return a type predicate function that returns `true` if the type of `x` is `T` or `undefined`.
+ *
+ * ```ts
+ * import is from "./is.ts";
+ *
+ * const a: unknown = "a";
+ * if (is.OptionalOf(is.String)(a)) {
+ *  // a is narrowed to string | undefined;
+ *  const _: string | undefined = a;
+ * }
+ * ```
+ */
+export function isOptionalOf<T>(
+  pred: Predicate<T>,
+): OptionalPredicate<T> {
+  return isOneOf([isUndefined, pred]);
+}
+
 export default {
   String: isString,
   Number: isNumber,
@@ -292,4 +313,5 @@ export default {
   Nullish: isNullish,
   Symbol: isSymbol,
   OneOf: isOneOf,
+  OptionalOf: isOptionalOf,
 };

is_test.ts

@@ -18,6 +18,7 @@ import is, {
   isNumber,
   isObjectOf,
   isOneOf,
+  isOptionalOf,
   isRecord,
   isRecordOf,
   isString,
@@ -346,6 +347,65 @@ Deno.test("isOneOf<T>", async (t) => {
   });
 });
 
+Deno.test("isOptionalOf<T>", async (t) => {
+  await t.step("returns proper type predicate", () => {
+    const a: unknown = undefined;
+    if (isOptionalOf(isNumber)(a)) {
+      type _ = AssertTrue<IsExact<typeof a, number | undefined>>;
+    }
+  });
+  await t.step("with isString", async (t) => {
+    await testWithExamples(t, isOptionalOf(isString), {
+      validExamples: ["string", "undefined"],
+    });
+  });
+  await t.step("with isNumber", async (t) => {
+    await testWithExamples(t, isOptionalOf(isNumber), {
+      validExamples: ["number", "undefined"],
+    });
+  });
+  await t.step("with isBigInt", async (t) => {
+    await testWithExamples(t, isOptionalOf(isBigInt), {
+      validExamples: ["bigint", "undefined"],
+    });
+  });
+  await t.step("with isBoolean", async (t) => {
+    await testWithExamples(t, isOptionalOf(isBoolean), {
+      validExamples: ["boolean", "undefined"],
+    });
+  });
+  await t.step("with isArray", async (t) => {
+    await testWithExamples(t, isOptionalOf(isArray), {
+      validExamples: ["array", "undefined"],
+    });
+  });
+  await t.step("with isRecord", async (t) => {
+    await testWithExamples(t, isOptionalOf(isRecord), {
+      validExamples: ["record", "date", "promise", "undefined"],
+    });
+  });
+  await t.step("with isFunction", async (t) => {
+    await testWithExamples(t, isOptionalOf(isFunction), {
+      validExamples: ["function", "undefined"],
+    });
+  });
+  await t.step("with isNull", async (t) => {
+    await testWithExamples(t, isOptionalOf(isNull), {
+      validExamples: ["null", "undefined"],
+    });
+  });
+  await t.step("with isUndefined", async (t) => {
+    await testWithExamples(t, isOptionalOf(isUndefined), {
+      validExamples: ["undefined"],
+    });
+  });
+  await t.step("with isSymbol", async (t) => {
+    await testWithExamples(t, isOptionalOf(isSymbol), {
+      validExamples: ["symbol", "undefined"],
+    });
+  });
+});
+
 Deno.test("is", async (t) => {
   const mod = await import("./is.ts");
   const casesOfAliasAndIsFunction = Object.entries(mod)