diff --git a/README.md b/README.md index d6e7d7b..3930600 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,8 @@ [![Test](https://github.com/lambdalisue/deno-unnullish/workflows/Test/badge.svg)](https://github.com/lambdalisue/deno-unnullish/actions?query=workflow%3ATest) [![npm version](https://badge.fury.io/js/unnullish.svg)](https://badge.fury.io/js/unnullish) -`unnullish` provided by this package returns the value as is if `value` is -nullish, otherwise it executes `callback` and returns the result. It is an -opposite function of the +`unnullish` returns `undefined` if `value` is nullish, otherwise it executes +`callback` and returns the result. It is an opposite function of the [nullish coalescing operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing_operator) (`??`). @@ -18,24 +17,28 @@ opposite function of the ### unnullish -- `unnullish(value: T | null | undefined, callback(v: T) => R): R | null | undefined` +- `unnullish(value: T | null | undefined, callback(v: T) => R): R | undefined` The function is useful when you want to apply some transformation functions to optional values. For example, ```typescript -import { unnullish } from "https://deno.land/x/unnullish/mod.ts"; +import { unnullish } from "./mod.ts"; type Options = { foo?: string; - bar?: boolean; + bar?: number; }; +function sayHello(v: string): string { + return `Hello ${v}`; +} + const options: Options = { - foo: unnullish(Deno.env.get("foo"), (v) => v.toUpperCase()), + foo: unnullish(Deno.env.get("foo"), (v) => sayHello(v)), // instead of //foo: Deno.env.get("foo") != null - // ? Deno.env.get("foo").toUpperCase() + // ? sayHello(Deno.env.get("foo")) // : undefined, bar: unnullish(Deno.env.get("bar"), (v) => parseInt(v, 10)), @@ -46,24 +49,32 @@ const options: Options = { }; ``` -Note that the function returns `null` or `undefined` **as is**, mean that you -may need to use nullish coalescing operator to normalize the result. For +Note that the function returns `undefined` even the input is `null`, mean that +you may need to use nullish coalescing operator to normalize the result. For example, ```typescript -import { unnullish } from "https://deno.land/x/unnullish/mod.ts"; +import { unnullish } from "./mod.ts"; console.log(unnullish(null, () => 0)); -// -> null +// -> undefined console.log(unnullish(undefined, () => 0)); // -> undefined -console.log(unnullish(null, () => 0) ?? undefined); -// -> undefined -console.log(unnullish(undefined, () => 0) ?? undefined); -// -> undefined +console.log(unnullish(null, () => 0) ?? null); +// -> null +console.log(unnullish(undefined, () => 0) ?? null); +// -> null ``` +##### Deno + +Use `import { unnullish } from "https://deno.land/x/unnullish/mod.ts"`; + +##### Node + +Use `import { unnullish } from "unnullish"`; + ## License The code follows MIT license written in [LICENSE](./LICENSE). Contributors need diff --git a/unnullish.ts b/unnullish.ts index 4d96998..a086e90 100644 --- a/unnullish.ts +++ b/unnullish.ts @@ -1,17 +1,17 @@ -type Nullish = undefined | null; +export type Nullish = undefined | null; /** - * Returns the value as is if `value` is nullish, otherwise + * Returns `undefined` if `value` is nullish, otherwise * it executes `callback` and returns the result. * * This function is the opposite of the Nullish coalescing operator (??). */ export function unnullish( value: T | Nullish, - callback: (value: T) => R, -): R | Nullish { + callback: (v: T) => R, +): R | undefined { if (value == null) { - return value as Nullish; + return undefined; } return callback(value); } diff --git a/unnullish_test.ts b/unnullish_test.ts index 6e5f466..40a1221 100644 --- a/unnullish_test.ts +++ b/unnullish_test.ts @@ -4,10 +4,14 @@ import { unnullish } from "./unnullish.ts"; Deno.test("unnullish() returns undefined when the value is undefined", () => { assertEquals(unnullish(undefined, unreachable), undefined); + // Type-check + const _: string | undefined = unnullish("" as string | undefined, () => ""); }); -Deno.test("unnullish() returns null when the value is null", () => { - assertEquals(unnullish(null, unreachable), null); +Deno.test("unnullish() returns undefined when the value is null", () => { + assertEquals(unnullish(null, unreachable), undefined); + // Type-check + const _: string | undefined = unnullish("" as string | null, () => ""); }); Deno.test("unnullish() returns the result of the callback when the value is string", () => {