📝 Update README and mod.ts

jsr-core · Feb 12, 2024 · 77d9bc7 · 77d9bc7
1 parent c223369
commit 77d9bc7
Show file tree

Hide file tree

Showing 2 changed files with 190 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -31,8 +31,7 @@ if (is.String(a)) {
 }
 ```
 
-Additionally, `is*Of` (or `is.*Of`) functions return type predicate functions to
-predicate types of `x` more precisely like:
+For more complex types, you can use `is*Of` (or `is.*Of`) functions like:
 
 ```typescript
 import {
@@ -52,8 +51,11 @@ const isArticle = is.ObjectOf({
       }),
     ]),
   ),
+  createTime: is.OptionalOf(is.InstanceOf(Date)),
+  updateTime: is.OptionalOf(is.InstanceOf(Date)),
 });
 
+// Infer the type of `Article` from the definition of `isArticle`
 type Article = PredicateType<typeof isArticle>;
 
 const a: unknown = {
@@ -76,6 +78,97 @@ if (isArticle(a)) {
 }
 ```
 
+Additionally, you can manipulate the predicate function returned from
+`isObjectOf` with `isPickOf`, `isOmitOf`, and `isPartialOf` similar to
+TypeScript's `Pick`, `Omit`, and `Partial` utility types.
+
+```typescript
+import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
+
+const isArticle = is.ObjectOf({
+  title: is.String,
+  body: is.String,
+  refs: is.ArrayOf(
+    is.OneOf([
+      is.String,
+      is.ObjectOf({
+        name: is.String,
+        url: is.String,
+      }),
+    ]),
+  ),
+  createTime: is.OptionalOf(is.InstanceOf(Date)),
+  updateTime: is.OptionalOf(is.InstanceOf(Date)),
+});
+
+const isArticleCreateParams = is.PickOf(isArticle, ["title", "body", "refs"]);
+// is equivalent to
+//const isArticleCreateParams = is.ObjectOf({
+//  title: is.String,
+//  body: is.String,
+//  refs: is.ArrayOf(
+//    is.OneOf([
+//      is.String,
+//      is.ObjectOf({
+//        name: is.String,
+//        url: is.String,
+//      }),
+//    ]),
+//  ),
+//});
+
+const isArticleUpdateParams = is.OmitOf(isArticleCreateParams, ["title"]);
+// is equivalent to
+//const isArticleUpdateParams = is.ObjectOf({
+//  body: is.String,
+//  refs: is.ArrayOf(
+//    is.OneOf([
+//      is.String,
+//      is.ObjectOf({
+//        name: is.String,
+//        url: is.String,
+//      }),
+//    ]),
+//  ),
+//});
+
+const isArticlePatchParams = is.PartialOf(isArticleUpdateParams);
+// is equivalent to
+//const isArticlePatchParams = is.ObjectOf({
+//  body: is.OptionalOf(is.String),
+//  refs: is.OptionalOf(is.ArrayOf(
+//    is.OneOf([
+//      is.String,
+//      is.ObjectOf({
+//        name: is.String,
+//        url: is.String,
+//      }),
+//    ]),
+//  )),
+//});
+```
+
+If you need an union type or an intersection type, use `isUnionOf` and
+`isIntersectionOf` like:
+
+```typescript
+import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
+
+const isFoo = is.ObjectOf({
+  foo: is.String,
+});
+
+const isBar = is.ObjectOf({
+  bar: is.String,
+});
+
+const isFooOrBar = is.OneOf([isFoo, isBar]);
+// { foo: string } | { bar: string }
+
+const isFooAndBar = is.AllOf([isFoo, isBar]);
+// { foo: string } & { bar: string }
+```
+
 ### assert
 
 The `assert` function does nothing if a given value is expected type. Otherwise,

diff --git a/mod.ts b/mod.ts
@@ -21,8 +21,7 @@
  * }
  * ```
  *
- * Additionally, `is*Of` (or `is.*Of`) functions return type predicate functions to
- * predicate types of `x` more precisely like:
+ * For more complex types, you can use `is*Of` (or `is.*Of`) functions like:
  *
  * ```typescript
  * import {
@@ -42,8 +41,11 @@
  *       }),
  *     ]),
  *   ),
+ *   createTime: is.OptionalOf(is.InstanceOf(Date)),
+ *   updateTime: is.OptionalOf(is.InstanceOf(Date)),
  * });
  *
+ * // Infer the type of `Article` from the definition of `isArticle`
  * type Article = PredicateType<typeof isArticle>;
  *
  * const a: unknown = {
@@ -66,6 +68,97 @@
  * }
  * ```
  *
+ * Additionally, you can manipulate the predicate function returned from
+ * `isObjectOf` with `isPickOf`, `isOmitOf`, and `isPartialOf` similar to
+ * TypeScript's `Pick`, `Omit`, and `Partial` utility types.
+ *
+ * ```typescript
+ * import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
+ *
+ * const isArticle = is.ObjectOf({
+ *   title: is.String,
+ *   body: is.String,
+ *   refs: is.ArrayOf(
+ *     is.OneOf([
+ *       is.String,
+ *       is.ObjectOf({
+ *         name: is.String,
+ *         url: is.String,
+ *       }),
+ *     ]),
+ *   ),
+ *   createTime: is.OptionalOf(is.InstanceOf(Date)),
+ *   updateTime: is.OptionalOf(is.InstanceOf(Date)),
+ * });
+ *
+ * const isArticleCreateParams = is.PickOf(isArticle, ["title", "body", "refs"]);
+ * // is equivalent to
+ * //const isArticleCreateParams = is.ObjectOf({
+ * //  title: is.String,
+ * //  body: is.String,
+ * //  refs: is.ArrayOf(
+ * //    is.OneOf([
+ * //      is.String,
+ * //      is.ObjectOf({
+ * //        name: is.String,
+ * //        url: is.String,
+ * //      }),
+ * //    ]),
+ * //  ),
+ * //});
+ *
+ * const isArticleUpdateParams = is.OmitOf(isArticleCreateParams, ["title"]);
+ * // is equivalent to
+ * //const isArticleUpdateParams = is.ObjectOf({
+ * //  body: is.String,
+ * //  refs: is.ArrayOf(
+ * //    is.OneOf([
+ * //      is.String,
+ * //      is.ObjectOf({
+ * //        name: is.String,
+ * //        url: is.String,
+ * //      }),
+ * //    ]),
+ * //  ),
+ * //});
+ *
+ * const isArticlePatchParams = is.PartialOf(isArticleUpdateParams);
+ * // is equivalent to
+ * //const isArticlePatchParams = is.ObjectOf({
+ * //  body: is.OptionalOf(is.String),
+ * //  refs: is.OptionalOf(is.ArrayOf(
+ * //    is.OneOf([
+ * //      is.String,
+ * //      is.ObjectOf({
+ * //        name: is.String,
+ * //        url: is.String,
+ * //      }),
+ * //    ]),
+ * //  )),
+ * //});
+ * ```
+ *
+ * If you need an union type or an intersection type, use `isUnionOf` and `isIntersectionOf`
+ * like:
+ *
+ * ```typescript
+ * import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
+ *
+ * const isFoo = is.ObjectOf({
+ *   foo: is.String,
+ * });
+ *
+ * const isBar = is.ObjectOf({
+ *   bar: is.String,
+ * });
+ *
+ * const isFooOrBar = is.OneOf([isFoo, isBar]);
+ * // { foo: string } | { bar: string }
+ *
+ * const isFooAndBar = is.AllOf([isFoo, isBar]);
+ * // { foo: string } & { bar: string }
+ * ```
+ *
  * ### assert
  *
  * The `assert` function does nothing if a given value is expected type. Otherwise,