Merge pull request #35 from lambdalisue/support-literal

Add `isPrimitive`, `isLiteralOf<T>`, and `isLiteralOneOf<T>` predicate/predicator functions

Author: lambdalisue

is.ts

@@ -255,6 +255,49 @@ export function isSymbol(x: unknown): x is symbol {
   return typeof x === "symbol";
 }
 
+export type Primitive =
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined
+  | symbol;
+
+/**
+ * Return `true` if the type of `x` is Primitive.
+ */
+export function isPrimitive(x: unknown): x is Primitive {
+  return x == null ||
+    ["string", "number", "bigint", "boolean", "symbol"].includes(typeof x);
+}
+
+/**
+ * Return a type predicate function that returns `true` if the type of `x` is a literal type of `pred`.
+ */
+export function isLiteralOf<T extends Primitive>(pred: T): Predicate<T> {
+  return (x: unknown): x is T => x === pred;
+}
+
+/**
+ * Return a type predicate function that returns `true` if the type of `x` is one of literal type in `preds`.
+ *
+ * ```ts
+ * import is from "./is.ts";
+ * const a: unknown = "hello";
+ * if (is.LiteralOneOf(["hello", "world"] as const)(a)) {
+ *  // a is narrowed to "hello" | "world"
+ *  const _: "hello" | "world" = a;
+ * }
+ * ```
+ */
+export function isLiteralOneOf<T extends readonly Primitive[]>(
+  preds: T,
+): Predicate<T[number]> {
+  return (x: unknown): x is T[number] =>
+    preds.includes(x as unknown as T[number]);
+}
+
 export type OneOf<T> = T extends Predicate<infer U>[] ? U : never;
 
 /**
@@ -346,6 +389,9 @@ export default {
   Undefined: isUndefined,
   Nullish: isNullish,
   Symbol: isSymbol,
+  Primitive: isPrimitive,
+  LiteralOf: isLiteralOf,
+  LiteralOneOf: isLiteralOneOf,
   OneOf: isOneOf,
   AllOf: isAllOf,
   OptionalOf: isOptionalOf,

is_bench.ts

@@ -246,6 +246,57 @@ Deno.bench({
   },
 });
 
+Deno.bench({
+  name: "is.Primitive",
+  fn: () => {
+    for (const c of cs) {
+      is.Primitive(c);
+    }
+  },
+});
+
+const predLiteral = "hello";
+Deno.bench({
+  name: "is.LiteralOf",
+  fn: () => {
+    const pred = is.LiteralOf(predLiteral);
+    for (const c of cs) {
+      pred(c);
+    }
+  },
+});
+
+const isLiteralOfPred = is.LiteralOf(predLiteral);
+Deno.bench({
+  name: "is.LiteralOf (pre)",
+  fn: () => {
+    for (const c of cs) {
+      isLiteralOfPred(c);
+    }
+  },
+});
+
+const predLiteralOne = ["hello", "world"] as const;
+Deno.bench({
+  name: "is.LiteralOneOf",
+  fn: () => {
+    const pred = is.LiteralOneOf(predLiteralOne);
+    for (const c of cs) {
+      pred(c);
+    }
+  },
+});
+
+const isLiteralOneOfPred = is.LiteralOneOf(predLiteralOne);
+Deno.bench({
+  name: "is.LiteralOneOf (pre)",
+  fn: () => {
+    for (const c of cs) {
+      isLiteralOneOfPred(c);
+    }
+  },
+});
+
 const predsOne = [is.String, is.Number, is.Boolean] as const;
 Deno.bench({
   name: "is.OneOf",

is_test.ts

@@ -14,12 +14,15 @@ import is, {
   isBoolean,
   isFunction,
   isInstanceOf,
+  isLiteralOf,
+  isLiteralOneOf,
   isNull,
   isNullish,
   isNumber,
   isObjectOf,
   isOneOf,
   isOptionalOf,
+  isPrimitive,
   isRecord,
   isRecordOf,
   isString,
@@ -421,6 +424,57 @@ Deno.test("isSymbol", async (t) => {
   await testWithExamples(t, isSymbol, { validExamples: ["symbol"] });
 });
 
+Deno.test("isPrimitive", async (t) => {
+  await testWithExamples(t, isPrimitive, {
+    validExamples: [
+      "string",
+      "number",
+      "bigint",
+      "boolean",
+      "null",
+      "undefined",
+      "symbol",
+    ],
+  });
+});
+
+Deno.test("isLiteralOf<T>", async (t) => {
+  await t.step("returns proper type predicate", () => {
+    const pred = "hello";
+    const a: unknown = "hello";
+    if (isLiteralOf(pred)(a)) {
+      type _ = AssertTrue<IsExact<typeof a, "hello">>;
+    }
+  });
+  await t.step("returns true on literal T", () => {
+    const pred = "hello";
+    assertEquals(isLiteralOf(pred)("hello"), true);
+  });
+  await t.step("returns false on non literal T", async (t) => {
+    const pred = "hello";
+    await testWithExamples(t, isLiteralOf(pred));
+  });
+});
+
+Deno.test("isLiteralOneOf<T>", async (t) => {
+  await t.step("returns proper type predicate", () => {
+    const preds = ["hello", "world"] as const;
+    const a: unknown = "hello";
+    if (isLiteralOneOf(preds)(a)) {
+      type _ = AssertTrue<IsExact<typeof a, "hello" | "world">>;
+    }
+  });
+  await t.step("returns true on literal T", () => {
+    const preds = ["hello", "world"] as const;
+    assertEquals(isLiteralOneOf(preds)("hello"), true);
+    assertEquals(isLiteralOneOf(preds)("world"), true);
+  });
+  await t.step("returns false on non literal T", async (t) => {
+    const preds = ["hello", "world"] as const;
+    await testWithExamples(t, isLiteralOneOf(preds));
+  });
+});
+
 Deno.test("isOneOf<T>", async (t) => {
   await t.step("returns proper type predicate", () => {
     const preds = [isNumber, isString, isBoolean];