123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245
/** * 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 "@core/unknownutil"; * * const a: unknown = "Hello"; * if (is.String(a)) { *   // 'a' is 'string' in this block * } * ``` * * For more complex types, you can use `is*Of` (or `is.*Of`) functions like: * * ```typescript * import { *   is, *   PredicateType, * } from "@core/unknownutil"; * * const isArticle = is.ObjectOf({ *   title: is.String, *   body: is.String, *   refs: is.ArrayOf( *     is.UnionOf([ *       is.String, *       is.ObjectOf({ *         name: is.String, *         url: is.String, *       }), *     ]), *   ), *   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 = { *   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); *     } *   } * } * ``` * * Additionally, you can manipulate the predicate function returned from * `isObjectOf` with `isPickOf`, `isOmitOf`, `isPartialOf`, and `isRequiredOf` * similar to TypeScript's `Pick`, `Omit`, `Partial`, `Required` utility types. * * ```typescript * import { is } from "@core/unknownutil"; * * const isArticle = is.ObjectOf({ *   title: is.String, *   body: is.String, *   refs: is.ArrayOf( *     is.UnionOf([ *       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.UnionOf([ * //      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.UnionOf([ * //      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.UnionOf([ * //      is.String, * //      is.ObjectOf({ * //        name: is.String, * //        url: is.String, * //      }), * //    ]), * //  )), * //}); * * const isArticleAvailableParams = is.RequiredOf(isArticle); * // is equivalent to * //const isArticlePutParams = is.ObjectOf({ * //  body: is.String, * //  refs: is.ArrayOf( * //    is.UnionOf([ * //      is.String, * //      is.ObjectOf({ * //        name: is.String, * //        url: is.String, * //      }), * //    ]), * //  ), * //  createTime: is.InstanceOf(Date), * //  updateTime: is.InstanceOf(Date), * //}); * ``` * * If you need an union type or an intersection type, use `isUnionOf` and `isIntersectionOf` * like: * * ```typescript * import { is } from "@core/unknownutil"; * * const isFoo = is.ObjectOf({ *   foo: is.String, * }); * * const isBar = is.ObjectOf({ *   bar: is.String, * }); * * const isFooOrBar = is.UnionOf([isFoo, isBar]); * // { foo: string } | { bar: string } * * const isFooAndBar = is.IntersectionOf([isFoo, isBar]); * // { foo: string } & { bar: string } * ``` * * ### 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 "@core/unknownutil"; * * 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 "@core/unknownutil"; * * 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 "@core/unknownutil"; * * 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 "./metadata.ts";export * from "./util.ts";