📝 Use $MODULE_VERSION in docs

Author: lambdalisue

README.md

@@ -23,7 +23,7 @@ expected type. For example, `isString` (or `is.String`) returns `true` if a
 given value is `string`.
 
 ```typescript
-import { is } from "./mod.ts";
+import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
 
 const a: unknown = "Hello";
 if (is.String(a)) {
@@ -35,7 +35,10 @@ Additionally, `is*Of` (or `is.*Of`) functions return type predicate functions to
 predicate types of `x` more precisely like:
 
 ```typescript
-import { is, PredicateType } from "./mod.ts";
+import {
+  is,
+  PredicateType,
+} from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
 
 const isArticle = is.ObjectOf({
   title: is.String,
@@ -47,7 +50,7 @@ const isArticle = is.ObjectOf({
         name: is.String,
         url: is.String,
       }),
-    ])
+    ]),
   ),
 });
 
@@ -79,7 +82,10 @@ The `assert` function does nothing if a given value is expected type. Otherwise,
 it throws an `AssertError` exception like:
 
 ```typescript
-import { assert, is } from "./mod.ts";
+import {
+  assert,
+  is,
+} from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
 
 const a: unknown = "Hello";
 
@@ -97,7 +103,10 @@ The `ensure` function return the value as-is if a given value is expected type.
 Otherwise, it throws an `AssertError` exception like:
 
 ```typescript
-import { ensure, is } from "./mod.ts";
+import {
+  ensure,
+  is,
+} from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
 
 const a: unknown = "Hello";
 
@@ -116,7 +125,10 @@ Otherwise, it returns `undefined` that suites with
 like:
 
 ```typescript
-import { is, maybe } from "./mod.ts";
+import {
+  is,
+  maybe,
+} from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
 
 const a: unknown = "Hello";
 

is.ts

@@ -86,7 +86,7 @@ export type TupleOf<T extends readonly Predicate<unknown>[]> = {
  * Return a type predicate function that returns `true` if the type of `x` is `TupleOf<T>`.
  *
  * ```ts
- * import is from "./is.ts";
+ * import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
  *
  * const predTup = [is.Number, is.String, is.Boolean] as const;
  * const a: unknown = [0, "a", true];
@@ -129,7 +129,7 @@ export type UniformTupleOf<
  * Return a type predicate function that returns `true` if the type of `x` is `UniformTupleOf<T>`.
  *
  * ```ts
- * import is from "./is.ts";
+ * import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
  *
  * const a: unknown = [0, 1, 2, 3, 4];
  * if (is.UniformTupleOf(5)(a)) {
@@ -223,7 +223,7 @@ export type ObjectOf<T extends RecordOf<Predicate<unknown>>> = FlatType<
  * Otherwise, the number of keys of `x` must be greater than or equal to the number of keys of `predObj`.
  *
  * ```ts
- * import is from "./is.ts";
+ * import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
  *
  * const predObj = {
  *  a: is.Number,
@@ -310,7 +310,7 @@ export function isAsyncFunction(
  * Return `true` if the type of `x` is instance of `ctor`.
  *
  * ```ts
- * import is from "./is.ts";
+ * import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
  *
  * const a: unknown = new Date();
  * if (is.InstanceOf(Date)(a)) {
@@ -396,7 +396,8 @@ export function isLiteralOf<T extends Primitive>(literal: T): Predicate<T> {
  * 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";
+ * import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
+ *
  * const a: unknown = "hello";
  * if (is.LiteralOneOf(["hello", "world"] as const)(a)) {
  *  // a is narrowed to "hello" | "world"
@@ -424,7 +425,7 @@ export type OneOf<T> = T extends Predicate<infer U>[] ? U : never;
  * Return a type predicate function that returns `true` if the type of `x` is `OneOf<T>`.
  *
  * ```ts
- * import is from "./is.ts";
+ * import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
  *
  * const preds = [is.Number, is.String, is.Boolean];
  * const a: unknown = 0;
@@ -457,7 +458,7 @@ export type AllOf<T> = UnionToIntersection<OneOf<T>>;
  * Return a type predicate function that returns `true` if the type of `x` is `AllOf<T>`.
  *
  * ```ts
- * import is from "./is.ts";
+ * import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
  *
  * const preds = [is.ObjectOf({ a: is.Number }), is.ObjectOf({ b: is.String })];
  * const a: unknown = { a: 0, b: "a" };
@@ -488,7 +489,7 @@ 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";
+ * import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
  *
  * const a: unknown = "a";
  * if (is.OptionalOf(is.String)(a)) {

mod.ts

@@ -1,3 +1,134 @@
+/**
+ * A utility pack for handling `unknown` type.
+ *
+ * ## Usage
+ *
+ * It provides `is` module for type predicate functions and `assert`, `ensure`, and
+ * `maybe` helper functions.
+ *
+ * ### is\*
+ *
+ * Type predicate function is a function which returns `true` if a given value is
+ * expected type. For example, `isString` (or `is.String`) returns `true` if a
+ * given value is `string`.
+ *
+ * ```typescript
+ * import { is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
+ *
+ * const a: unknown = "Hello";
+ * if (is.String(a)) {
+ *   // 'a' is 'string' in this block
+ * }
+ * ```
+ *
+ * Additionally, `is*Of` (or `is.*Of`) functions return type predicate functions to
+ * predicate types of `x` more precisely like:
+ *
+ * ```typescript
+ * import {
+ *   is,
+ *   PredicateType,
+ * } 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,
+ *       }),
+ *     ]),
+ *   ),
+ * });
+ *
+ * type Article = PredicateType<typeof isArticle>;
+ *
+ * const a: unknown = {
+ *   title: "Awesome article",
+ *   body: "This is an awesome article",
+ *   refs: [{ name: "Deno", url: "https://deno.land/" }, "https://github.com"],
+ * };
+ * if (isArticle(a)) {
+ *   // a is narrowed to the type of `isArticle`
+ *   console.log(a.title);
+ *   console.log(a.body);
+ *   for (const ref of a.refs) {
+ *     if (is.String(ref)) {
+ *       console.log(ref);
+ *     } else {
+ *       console.log(ref.name);
+ *       console.log(ref.url);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### assert
+ *
+ * The `assert` function does nothing if a given value is expected type. Otherwise,
+ * it throws an `AssertError` exception like:
+ *
+ * ```typescript
+ * import {
+ *   assert,
+ *   is,
+ * } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
+ *
+ * const a: unknown = "Hello";
+ *
+ * // `assert` does nothing or throws an `AssertError`
+ * assert(a, is.String);
+ * // a is now narrowed to string
+ *
+ * // With custom message
+ * assert(a, is.String, { message: "a must be a string" });
+ * ```
+ *
+ * ### ensure
+ *
+ * The `ensure` function return the value as-is if a given value is expected type.
+ * Otherwise, it throws an `AssertError` exception like:
+ *
+ * ```typescript
+ * import {
+ *   ensure,
+ *   is,
+ * } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
+ *
+ * const a: unknown = "Hello";
+ *
+ * // `ensure` returns `string` or throws an `AssertError`
+ * const _: string = ensure(a, is.String);
+ *
+ * // With custom message
+ * const __: string = ensure(a, is.String, { message: "a must be a string" });
+ * ```
+ *
+ * ### maybe
+ *
+ * The `maybe` function return the value as-is if a given value is expected type.
+ * Otherwise, it returns `undefined` that suites with
+ * [nullish coalescing operator (`??`)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing)
+ * like:
+ *
+ * ```typescript
+ * import {
+ *   is,
+ *   maybe,
+ * } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
+ *
+ * const a: unknown = "Hello";
+ *
+ * // `maybe` returns `string | undefined` so it suites with `??`
+ * const _: string = maybe(a, is.String) ?? "default value";
+ * ```
+ *
+ * @module
+ */
+
 export * from "./is.ts";
 export * from "./util.ts";
 

util.ts

@@ -45,8 +45,7 @@ export class AssertError extends Error {
  * @param factory The factory function.
  * @example
  * ```ts
- * import { setAssertMessageFactory } from "./util.ts";
- * import is from "./is.ts";
+ * import { is, setAssertMessageFactory } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
  *
  * setAssertMessageFactory((x, pred) => {
  *   if (pred === is.String) {
@@ -69,8 +68,7 @@ export function setAssertMessageFactory(factory: AssertMessageFactory): void {
  * Asserts that the given value satisfies the provided predicate.
  *
  * ```ts
- * import { assert } from "./util.ts";
- * import is from "./is.ts";
+ * import { assert, is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
  *
  * const a: unknown = "hello";
  * assert(a, is.String);
@@ -99,8 +97,7 @@ export function assert<T>(
  * Ensures that the given value satisfies the provided predicate.
  *
  * ```ts
- * import { ensure } from "./util.ts";
- * import is from "./is.ts";
+ * import { ensure, is } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
  *
  * const a: unknown = "hello";
  * const _: string = ensure(a, is.String);
@@ -125,8 +122,7 @@ export function ensure<T>(
  * Returns the input value if it satisfies the provided predicate, or `undefined` otherwise.
  *
  * ```ts
- * import { maybe } from "./util.ts";
- * import is from "./is.ts";
+ * import { is, maybe } from "https://deno.land/x/unknownutil@$MODULE_VERSION/mod.ts";
  *
  * const a: unknown = "hello";
  * const _: string = maybe(a, is.String) ?? "default value";