Fixed ES modules imports

@perfective/common can now be imported from regular .js/.mjs ESM files.

Added wrappers for most of the Math functions (#20)

Unlike the standard Math functions, the following functions throw an Exception for invalid inputs:

• absolute()
• arccos(), arccosh()
• arcsin(), arcsinh()
• arctan(), arctan2(), arctanh()
• cos(), cosh()
• sin(), sinh()
• tan(), tanh()
• rounded(), roundedUp(), roundedDown(), roundedToFloat32(), truncated()
• power(), powerOf()
• squareRoot(), cubeRoot(), l2norm()
• exp(), expm1()
• log(), log10(), log1p(), log2()
• sign() with the Sign nominal type

Replacing NaN with null is a redundant idea, because it’s trivial to use library functions with Maybe instead:

maybe(x).to(Math.acos).that(isNumber)

Meanwhile, throwing an exception gives library users an option to track invalid inputs.
In this case, the Result monad can be used:

result(x).onto(resultFrom(arccos))

Added more nominal types for numbers

• Added the Infinity, PositiveInfinity, and NegativeInfinity nominal types with the isInfinity() type guard.
• Added the FiniteNumber nominal type with the isFinite() type guard (#18) and assertIsFinite() assertion.
• Added the PositiveNumber, NonPositiveNumber, NegativeNumber, NonNegativeNumber nominal types.
• Added the assertIsNonNegativeNumber() type guard.

Introduced assertion functions

• Added the assertIsNotNaN() (#53) and assertIsNonNegativeNumber() functions.
• Added the typeException() function.

Read the release announcement in the Perfective blog.

@perfective/common/result

• Added the Result.that() filter method.
• Added the Result.which() type-guard method.
• Added the Result.when() filter method.
• Added the Result.or() fold method.
• Added the Result.otherwise() recovery method.
  • Deprecated the recovery() function.
• [Breaking] Changed the resultFrom() to use try-catch instead of the T | Error union type. This makes the function behavior safer and allows wider usage.

New @perfective/common/date package

• Added functions for the Date class:
  • Added date(), now(), and epoch() Date constructors.
  • Added isValid()/isInvalid() Date predicates.
• Added Timestamp type.
  • Added timestamp() constructor.

Restructured Roadmap

ROADMAP.adoc now contains all built-in objects with their properties and methods. Some of the methods and properties already have a matching Perfective function, and some are marked as prohibited (e.g. eval) or not supported.

The Roadmap will document minimum support to tag @perfective/common v1.0.

Breaking changes

• Dropped Node.js v16.x support, as it is no longer supported.
• Removed deprecated functions and types:
  • @perfective/common/array:
    • arrayFromArrayLike(), arrayFromIterable(), flatten().
  • @perfective/common/match:
    • Match.that(), Match.to();
    • Statement, StatementEntry, statements();
    • When.then().
  • @perfective/common/maybe:
    • Maybe.lift()/lift(), Maybe.run()/run();
    • Nullable, Nil, Only/Solum, nullable(), nil(), only()/solum();
    • Optional, None, Some, optional(), none(), some().
  • @perfective/common/promise:
    • Run, result().
  • @perfective/common/string:
    • Output, isNotOutput(), isOutput(), output().

Improvements

• @perfective/common/boolean:
  • Added JsDocs for all types and functions.
  • Added ES Coverage documentation for the Boolean type.
  • Added the isBoolean()/isNotBoolean() predicates.
  • Moved the isTruthy()/isFalsy() functions from @perfective/common/object.
• @perfective/common/error:
  • Added Recovery type.
  • Added JsDocs for all types and functions.
  • Added support for cause (previous) error to the Panic type and panic() function.
• @perfective/common/maybe:
  • Changed the nothing()/nil() functions return type to Nothing<Present<T>> for TypeScript v5.3 compatibility.
• @perfective/common/object:
  • Added JsDocs for all types and functions.
• @perfective/common/string:
  • Fixed lines() function: Use correct separator for Mac OS strings.
  • Deprecated the stringFromCharCode() and stringFromCodePoint() functions.
    Use the String.fromCharCode() and String.fromCodePoint() functions directly.

Deprecations

• @perfective/common/function:
  • Deprecated the emtpy() function. Use naught() as an empty no-op function instead.
• @perfective/common/error:
  • Deprecated the Rethrow type. Use Panic instead.
  • Deprecated the rethrow() function. Use panic() instead.
  • Renamed the unknownError() function into caughtError().
• @perfective/common/maybe:
  • Renamed the naught() function into nil().
• @perfective/common/object:
  • Moved the isTruthy()/isFalsy() functions into @perfective/common/boolean.
• @perfective/common/result:
  • Deprecated the recovery() function. Use Result.otherwise() instead.

• Added JSDocs for all functions and types.
• Updated the roadmap to cover all existing packages.
• @perfective/common/date:
  • Supported string input parsing in the timestamp() function.
• @perfective/common/string:
  • Fixed lines() function: using correct separator (\r) for Mac OS strings.
  • Deprecated the stringFromCharCode() and stringFromCodePoint() functions. Use the String.fromCharCode() and String.fromCodePoint() functions directly.

New @perfective/common/date package

• Added functions for the Date class:
  • Added date(), now(), and epoch() Date constructors.
  • Added isValid()/isInvalid() Date predicates.
• Added Timestamp type.
  • Added timestamp() constructor.

Restructured Roadmap

ROADMAP.adoc now contains all built-in objects with their properties and methods. Some of the methods and properties already have a matching Perfective function, and some are marked as prohibited (e.g. eval) or not supported.

The Roadmap will document minimum support to tag @perfective/common v1.0.

@perfective/common/result

• Added the Result.that() filter method.
• Added the Result.which() type-guard method.
• Added the Result.when() filter method.
• Added the Result.or() fold method.
• Added the Result.otherwise() recovery method.
  • Deprecated the recovery() function.
• [Breaking] Changed the resultFrom() to use try-catch instead of the T | Error union type.
  This makes the function behavior safer and allows wider usage.

Breaking changes

• Removed deprecated functions and types:
  • @perfective/common/array:
    • arrayFromArrayLike(), arrayFromIterable(), flatten().
  • @perfective/common/match:
    • Match.that(), Match.to();
    • Statement, StatementEntry, statements();
    • When.then().
  • @perfective/common/maybe:
    • Maybe.lift()/lift(), Maybe.run()/run();
    • Nullable, Nil, Only/Solum, nullable(), nil(), only()/solum();
    • Optional, None, Some, optional(), none(), some().
  • @perfective/common/promise:
    • Run, result().
  • @perfective/common/string:
    • Output, isNotOutput(), isOutput(), output().

Deprecations

• @perfective/common/function:
  • Deprecated the emtpy() function.
    Use naught() as an empty no-op function instead.
• @perfective/common/error:
  • Deprecated the Rethrow type. Use Panic instead.
  • Deprecated the rethrow() function. Use panic() instead.
  • Renamed the unknownError() function into caughtError().
• @perfective/common/maybe:
  • Renamed the naught() function into nil().
• @perfective/common/object:
  • Moved the isTruthy()/isFalsy() functions into @perfective/common/boolean.
• @perfective/common/result:
  • Deprecated the recovery() function.
    Use Result.otherwise() instead.

Improvements

• @perfective/common/boolean:
  • Added JsDocs for all types and functions.
  • Added ES Coverage documentation for the Boolean type.
  • Added the isBoolean()/isNotBoolean() predicates.
  • Moved the isTruthy()/isFalsy() functions from @perfective/common/object.
• @perfective/common/error:
  • Added Recovery type.
  • Added JsDocs for all types and functions.
  • Added support for cause (previous) error to the Panic type and panic() function.
• @perfective/common/object:
  • Added JsDocs for all types and functions.

Changes since v0.8.3.

New @perfective/common/result package

• Added the Result<T> monad type with Success<T> and Failure<T> implementations.
  • Added the result(), success(), and failure() constructors.
  • Added the resultOf() lazy constructor.
  • Added the resultFrom(), successFrom(), and failureFrom() functions.
  • Added the recovery() function.
  • Added the rejection() constructor for rejected Promise handling.
  • Added the promisedResult() and settledResult() async functions.
  • Added the onto(), to(), into(), and through() lifting functions.
  • Added type guards:
    • isResult()/isNotResult(),
    • isSuccess()/isNotSuccess(),
    • and isFailure()/isNotFailure().
• Added the BiMapResult<T, U> type for the Result.to(maps) method:
  • Added the successWith() and failureWith() BiMapResult constructors.
• Added the BiFoldResult<T, U> type for the Result.into(fold) method.
• Added the BiVoidResult<T> type for the Result.through(procedures) method.

Breaking changes

• @perfective/common/function:
  • Changed the same() function into a unary function.
    To migrate:
    • replace calls passing the same as an argument with constant(same);
    • replace calls of the same() with just same.
• @perfective/common/object:
  • Narrowed argument to the NonNullable type in the:
    • pick()/recordWithPicked(),
    • omit()/recordWithOmitted(),
    • and filter()/recordFiltered() functions.

Deprecations

• @perfective/common/array:
  • Merged the flatten() function into the concatenated() function.
  • Merged the arrayFromIterable() and arrayFromArrayLike() functions into the new elements() function.
• @perfective/common/match:
  • Renamed the Match.that() and Match.to() methods into Match.cases().
  • Renamed the When.then() method into When.to().
  • Renamed the Statement type into Case.
  • Renamed the StatementEntry type into CaseEntry.
  • Renamed the statements() function into fromEntries().
• @perfective/common/maybe:
  • Renamed the Maybe.run() method into the Maybe.through() method.
  • Deprecated the Nullable and Optional types.
    Both types cover specific edge cases for the Maybe type.
    But they have not been used in real-world applications.
    Use cases that these types covered can be handled by Maybe,
    so there is no good reason to maintain them.
    • Deprecated nil(), nullable(), only(), and solum() functions.
    • Deprecated none(), optional(), and some() functions.
    • Deprecated lift() function.
  • Deprecated the Maybe.lift() method.
    Use the Maybe.into() method with the maybeFrom() function instead.
• @perfective/common/promise:
  • Renamed the Run type into Executor.
    ECMA specification uses the term executor.
  • Renamed the result() function into settlement().
• @perfective/common/string:
  • Deprecated the Output interface.
  • Deprecated the output(), isOutput(), and isNotOutput() functions.
    Use the String() function for native string coercion instead.

Improvements

• Removed mock files from the distribution.
  mock.ts files are only imported in tests.

• @perfective/common:

  • Added support of abstract classes to the isInstanceOf()/isNotInstanceOf() type guards.
  • Added the Voidable<T> type.
  • Added the ecmaType() and isEcmaType() functions.
  • Added the tsType() and isTsType() functions.
  • Added the present(), notNull(), and defined() functions.
  • Set Present<T> as the isPresent() function return value.
  • Set Defined<T> as the isDefined() function return value.
  • Set NotNull<T> as the isNotNull() function return value.

• @perfective/common/array:

  • Added the pushInto() function.

• @perfective/common/error:

  • Fixed the Exception class prototype for
    the ES5 compilation.
  • Added the chained() function.
  • Included a non-error value output into an unknownError() message.

• @perfective/common/function:

  • Added the BiMap<T1, U1, T2, V2> arguments pair type.
  • Added the BiFold<T1, T2, U> arguments pair type.
  • Added the Void and UnaryVoid<T> procedure types.

• @perfective/common/match:

  • Added the caseFromEntry() function.

• @perfective/common/maybe:

  • Added Maybe.into(reduce) method and into(reduce) function.
  • Added maybeFrom() and justFrom() functions.
  • Narrowed signatures for the maybe() function.
    When a function is given an always present value, it will return Just<T>,
    and for always absent values, it will return Nothing<T>.
    Otherwise, the Maybe type is compiled as an interface and cannot be checked with the instance of in runtime.
  • Added JSDocs for the Maybe type methods.
  • Changed error messages for absent values in Just.
  • Switch to extends instead of implements in Maybe
  • Added type guards:
    • isMaybe()/isNotMaybe(),
    • isJust()/isNotJust(),
    • and isNothing()/isNotNothing().

• @perfective/common/object:

  • Added the hasMethod() and hasNoMethod() functions.
  • Changed the isRecord() predicate to be a type guard.
  • Marked property definition in the ObjectWithUndefined type as optional.
    Required to work with exactOptionalPropertyTypes: true.
    Otherwise, an object with a never defined property cannot be assigned to an object with a property set to
    undefined.
    The type guard is not yet strict enough, but it is better than just a predicate.

• @perfective/common/promise:

  • Added the Resolvable shortcut type.
  • Added the OnFulfilled and OnRejected types.
  • Added the fulfilled() and rejected() functions.
  • Added the settled() function.

• Updated documentation.

Deprecations

• @perfective/common/array:
  • Merged the flatten() function into the concatenated() function.
  • Merged the arrayFromIterable() and arrayFromArrayLike() functions into the new elements() function.
• @perfective/common/maybe:
  • Renamed the Maybe.run() method into the Maybe.through() method.

Improvements

• @perfective/common:
  • Added support of abstract classes to the isInstanceOf()/isNotInstanceOf() type guards.
• @perfective/common/error:
  • Fixed the Exception class prototype for
    the ES5 compilation.
• @perfective/common/maybe:
  • Added the isMaybe()/isNotMaybe(), isJust()/isNotJust(), and isNothing()/isNotNothing() type guards.
• @perfective/common/result:
  • Added the onto(), to(), into(), and through() lifting functions.
  • Added the isResult()/isNotResult(), isSuccess()/isNotSuccess(),and isFailure()/isNotFailure() type guards.

New @perfective/common/result package

• Added the Result<T> monad type with Success<T> and Failure<T> implementations.
  • Added the result(), success(), and failure() constructors.
  • Added the resultOf() lazy constructor.
  • Added the resultFrom(), successFrom(), and failureFrom() functions.
  • Added the recovery() function.
  • Added the rejection() constructor for rejected Promise handling.
  • Added the promisedResult() and settledResult() async functions.
• Added the BiMapResult<T, U> type for the Result.to(maps) method:
  • Added the successWith() and failureWith() BiMapResult constructors.
• Added the BiFoldResult<T, U> type for the Result.into(fold) method.
• Added the BiVoidResult<T> type for the Result.through(procedures) method.

Breaking changes

• @perfective/common/function:
  • Changed the same() function into a unary function.
    To migrate:
    • replace calls passing the same as an argument with constant(same);
    • replace calls of the same() with just same.
• @perfective/common/object:
  • Narrowed argument to the NonNullable type in the pick()/recordWithPicked(), omit()/recordWithOmitted(), and filter()/recordFiltered() functions.

Deprecations

• @perfective/common/match:
  • Renamed the Match.that() and Match.to() methods into Match.cases().
  • Renamed the When.then() method into When.to().
  • Renamed the Statement type into Case.
  • Renamed the StatementEntry type into CaseEntry.
  • Renamed the statements() function into fromEntries().
• @perfective/common/maybe:
  • Deprecated the Nullable and Optional types.
    Both types cover specific edge cases for the Maybe type.
    But they have not been used in real-world applications.
    Use cases that these types covered can be handled by Maybe,
    so there is no good reason to maintain them.
    • Deprecated nil(), nullable(), only(), and solum() functions.
    • Deprecated none(), optional(), and some() functions.
    • Deprecated lift() function.
  • Deprecated the Maybe.lift() method.
    Use the Maybe.into() method with the maybeFrom() function instead.
• @perfective/common/promise:
  • Renamed the Run type into Executor.
    ECMA specification uses the term executor.
  • Renamed the result() function into settlement().
• @perfective/common/string:
  • Deprecated the Output interface.
  • Deprecated the output(), isOutput(), and isNotOutput() functions.
    Use the String() function for native string coercion instead.

Improvements

• Removed mock files from the distribution.
  mock.ts files are only imported in tests.
• @perfective/common:
  • Added the Voidable<T> type.
  • Added the ecmaType() and isEcmaType() functions.
  • Added the tsType() and isTsType() functions.
  • Added the present(), notNull(), and defined() functions.
  • Set Present<T> as the isPresent() function return value.
  • Set Defined<T> as the isDefined() function return value.
  • Set NotNull<T> as the isNotNull() function return value.
• @perfective/common/array:
  • Added the pushInto() function.
• @perfective/common/error:
  • Added the chained() function.
  • Included a non-error value output into an unknownError() message.
• @perfective/common/function:
  • Added the BiMap<T1, U1, T2, V2> arguments pair type.
  • Added the BiFold<T1, T2, U> arguments pair type.
  • Added the Void and UnaryVoid<T> procedure types.
• @perfective/common/match:
  • Added the caseFromEntry() function.
• @perfective/common/maybe:
  • Added Maybe.into(reduce) method and into(reduce) function.
  • Added maybeFrom() and justFrom() functions.
  • Narrowed signatures for the maybe() function.
    When a function is given an always present value, it will return Just<T>,
    and for always absent values, it will return Nothing<T>.
  • Added JSDocs for the Maybe type methods.
  • Changed error messages for absent values in Just.
  • Switch to extends instead of implements in Maybe
    Otherwise, the Maybe type is compiled as an interface and cannot be checked with the instance of in runtime.
• @perfective/common/object:
  • Added the hasMethod() and hasNoMethod() functions.
  • Changed the isRecord() predicate to be a type guard.
  • Marked property definition in the ObjectWithUndefined type as optional.
    Required to work with exactOptionalPropertyTypes: true.
    Otherwise, an object with a never defined property cannot be assigned to an object with a property set to undefined.
    The type guard is not yet strict enough, but it is better than just a predicate.
• @perfective/common/promise:
  • Added the Resolvable shortcut type.
  • Added the OnFulfilled and OnRejected types.
  • Added the fulfilled() and rejected() functions.
  • Added the settled() function.

• Update @perfective/common/maybe package documentation.