Merge pull request #11 from lambdalisue/require

Add `require` that returns the value as-is

Author: lambdalisue

README.md

@@ -95,14 +95,14 @@ The `unknownutil` provides the following ensure functions which will raise
 `EnsureError` when a given `x` is not expected type.
 
 - `ensureString(x: unknown): assert x is string`
-- `ensureNumber(x: unknown): assert x is string`
+- `ensureNumber(x: unknown): assert x is number`
 - `ensureBoolean(x: unknown): assert x is boolean`
 - `ensureArray<T extends unknown>(x: unknown, pred?: Predicate<T>): assert x is T[]`
-- `ensureObject<T extends unknown>(x: unknown, pred?: Predicate<T>): x ensure Record<string, T>`
-- `ensureFunction(x: unknown): x ensure (...args: unknown[]) => unknown`
-- `ensureNull(x: unknown): x ensure null`
-- `ensureUndefined(x: unknown): x ensure undefined`
-- `ensureNone(x: unknown): x ensure null | undefined`
+- `ensureObject<T extends unknown>(x: unknown, pred?: Predicate<T>): x is Record<string, T>`
+- `ensureFunction(x: unknown): x is (...args: unknown[]) => unknown`
+- `ensureNull(x: unknown): x is null`
+- `ensureUndefined(x: unknown): x is undefined`
+- `ensureNone(x: unknown): x is null | undefined`
 
 For example:
 
@@ -145,6 +145,62 @@ ensureLike({}, b); // Now 'b' is 'Record<string, unknown>'
 ensureLike({ foo: "", bar: 0 }, b); // Now 'b' is '{foo: string, bar: number}'
 ```
 
+### requireXXXXX
+
+The `unknownutil` provides the following require functions which returns a given
+`x` as is or raise `EnsureError` when that is not expected type.
+
+- `requireString(x: unknown): string`
+- `requireNumber(x: unknown): number`
+- `requireBoolean(x: unknown): boolean`
+- `requireArray<T extends unknown>(x: unknown, pred?: Predicate<T>): T[]`
+- `requireObject<T extends unknown>(x: unknown, pred?: Predicate<T>): Record<string, T>`
+- `requireFunction(x: unknown): (...args: unknown[]) => unknown`
+- `requireNull(x: unknown): null`
+- `requireUndefined(x: unknown): undefined`
+- `requireNone(x: unknown): null | undefined`
+
+For example:
+
+```typescript
+import { requireString } from "https://deno.land/x/unknownutil/mod.ts";
+
+const a: unknown = "Hello";
+const a1 = requireString(a); // Now 'a' and 'a1' is 'string'
+
+const b: unknown = 0;
+const b1 = requireString(b); // Raise EnsureError on above while 'b' is not string
+```
+
+Additionally, `requireArray` and `requireObject` supports an inner predicate
+function to predicate `x` more precisely like:
+
+```typescript
+import { isString, requireArray } from "https://deno.land/x/unknownutil/mod.ts";
+
+const a: unknown = ["a", "b", "c"];
+const a1 = requireArray(a); // Now 'a' and 'a1' is 'unknown[]'
+const a2 = requireArray(a, isString); // Now 'a' and 'a2' is 'string[]'
+
+const b: unknown = [0, 1, 2];
+const b1 = requireArray(b); // Now 'b' and 'b1' is 'unknown[]'
+const b2 = requireArray(b, isString); // Raise EnsureError on above while 'b' is not string array
+```
+
+Use `requireLike` if you need some complicated types like tuple or struct like:
+
+```typescript
+import { requireLike } from "https://deno.land/x/unknownutil/mod.ts";
+
+const a: unknown = ["a", "b", "c"];
+const a1 = requireLike([], a); // Now 'a' and 'a1' is 'unknown[]'
+const a2 = requireLike(["", "", ""], a); // Now 'a' and 'a2' is '[string, string, string]'
+
+const b: unknown = { foo: "foo", bar: 0 };
+const b1 = requireLike({}, b); // Now 'b' and 'b1' is 'Record<string, unknown>'
+const b2 = requireLike({ foo: "", bar: 0 }, b); // Now 'b' and 'b2' is '{foo: string, bar: number}'
+```
+
 ## Development
 
 Lint code like:

mod.ts

@@ -1,2 +1,3 @@
-export * from "./is.ts";
 export * from "./ensure.ts";
+export * from "./is.ts";
+export * from "./require.ts";

require.ts

@@ -0,0 +1,118 @@
+import { Predicate } from "./is.ts";
+import {
+  ensure,
+  ensureArray,
+  ensureBoolean,
+  ensureFunction,
+  ensureLike,
+  ensureNone,
+  ensureNull,
+  ensureNumber,
+  ensureObject,
+  ensureString,
+  ensureUndefined,
+} from "./ensure.ts";
+
+/**
+ * Return `x` as-is if `x` is expected type or raise an `EnsureError` when it's not.
+ */
+export function require<T>(
+  x: unknown,
+  pred: Predicate<T>,
+  message = "The value is not expected type",
+): T {
+  ensure(x, pred, message);
+  return x;
+}
+
+/**
+ * Return `x` as-is if `x` is string or raise an `EnsureError` when it's not.
+ */
+export function requireString(x: unknown): string {
+  ensureString(x);
+  return x;
+}
+
+/**
+ * Return `x` as-is if `x` is number or raise an `EnsureError` when it's not.
+ */
+export function requireNumber(x: unknown): number {
+  ensureNumber(x);
+  return x;
+}
+
+/**
+ * Return `x` as-is if `x` is boolean or raise an `EnsureError` when it's not.
+ */
+export function requireBoolean(x: unknown): boolean {
+  ensureBoolean(x);
+  return x;
+}
+
+/**
+ * Return `x` as-is if `x` is array or raise an `EnsureError` when it's not.
+ */
+export function requireArray<T extends unknown>(
+  x: unknown,
+  ipred?: Predicate<T>,
+): T[] {
+  ensureArray(x, ipred);
+  return x;
+}
+
+/**
+ * Return `x` as-is if `x` is object or raise an `EnsureError` when it's not.
+ */
+export function requireObject<T>(
+  x: unknown,
+  ipred?: Predicate<T>,
+): Record<string, T> {
+  ensureObject(x, ipred);
+  return x;
+}
+
+/**
+ * Return `x` as-is if `x` is function or raise an `EnsureError` when it's not.
+ */
+export function requireFunction(
+  x: unknown,
+): (...args: unknown[]) => unknown {
+  ensureFunction(x);
+  return x;
+}
+
+/**
+ * Return `x` as-is if `x` is null or raise an `EnsureError` when it's not.
+ */
+export function requireNull(x: unknown): null {
+  ensureNull(x);
+  return x;
+}
+
+/**
+ * Return `x` as-is if `x` is undefined or raise an `EnsureError` when it's not.
+ */
+export function requireUndefined(x: unknown): undefined {
+  ensureUndefined(x);
+  return x;
+}
+
+/**
+ * Return `x` as-is if `x` is null or undefined or raise an `EnsureError` when it's not.
+ */
+export function requireNone(x: unknown): null | undefined {
+  ensureNone(x);
+  return x;
+}
+
+/**
+ * Return `x` as-is if `x` follows the reference or raise an `EnsureError` when it doesn't.
+ */
+export function requireLike<R, T extends unknown>(
+  ref: R,
+  x: unknown,
+  ipred?: Predicate<T>,
+): R {
+  ensureLike(ref, x, ipred);
+  return x;
+}