@planet-matrix/mobius-model 0.3.0 → 0.4.0

package/src/basic/bigint.ts

@@ -0,0 +1,114 @@
+import { isBigInt } from "./is.ts"
+
+/**
+ * Check whether a value is zero as a bigint.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = bigintIsZero(0n)
+ * // Expect: false
+ * const example2 = bigintIsZero(2n)
+ * ```
+ */
+export const bigintIsZero = (value: unknown): value is 0n => {
+  return isBigInt(value) && value === 0n
+}
+
+/**
+ * Check whether a value is a positive bigint.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = bigintIsPositive(3n)
+ * // Expect: false
+ * const example2 = bigintIsPositive(-1n)
+ * ```
+ */
+export const bigintIsPositive = (value: unknown): value is bigint => {
+  return isBigInt(value) && value > 0n
+}
+
+/**
+ * Check whether a value is a negative bigint.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = bigintIsNegative(-3n)
+ * // Expect: false
+ * const example2 = bigintIsNegative(1n)
+ * ```
+ */
+export const bigintIsNegative = (value: unknown): value is bigint => {
+  return isBigInt(value) && value < 0n
+}
+
+/**
+ * Get the absolute value of a bigint.
+ *
+ * @example
+ * ```
+ * // Expect: 5n
+ * const example1 = bigintAbs(-5n)
+ * // Expect: 2n
+ * const example2 = bigintAbs(2n)
+ * ```
+ */
+export const bigintAbs = (value: bigint): bigint => {
+  return value < 0n ? -value : value
+}
+
+/**
+ * Get the smaller of two bigint values.
+ *
+ * @example
+ * ```
+ * // Expect: 2n
+ * const example1 = bigintMinOf(2n, 9n)
+ * // Expect: -1n
+ * const example2 = bigintMinOf(5n, -1n)
+ * ```
+ */
+export const bigintMinOf = (a: bigint, b: bigint): bigint => {
+  return a < b ? a : b
+}
+
+/**
+ * Get the larger of two bigint values.
+ *
+ * @example
+ * ```
+ * // Expect: 9n
+ * const example1 = bigintMaxOf(2n, 9n)
+ * // Expect: 5n
+ * const example2 = bigintMaxOf(5n, -1n)
+ * ```
+ */
+export const bigintMaxOf = (a: bigint, b: bigint): bigint => {
+  return a > b ? a : b
+}
+
+/**
+ * Clamp a bigint between two bounds.
+ *
+ * @example
+ * ```
+ * // Expect: 5n
+ * const example1 = bigintClamp(0n, 10n, 5n)
+ * // Expect: 0n
+ * const example2 = bigintClamp(0n, 10n, -3n)
+ * ```
+ */
+export const bigintClamp = (min: bigint, max: bigint, value: bigint): bigint => {
+  const minValue = bigintMinOf(min, max)
+  const maxValue = bigintMaxOf(min, max)
+  if (value < minValue) {
+    return minValue
+  }
+  if (value > maxValue) {
+    return maxValue
+  }
+  return value
+}

package/src/basic/boolean.ts

@@ -0,0 +1,180 @@
+import type {
+  AnyFunctionOfReturn, BooleanNot, CastBoolean
+} from "#Source/type/index.ts"
+
+/**
+ * Convert any value to a boolean.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = booleanFrom(1)
+ * // Expect: false
+ * const example2 = booleanFrom(0)
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Glossary/Truthy}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Glossary/Falsy}
+ */
+export const booleanFrom = (value: unknown): boolean => Boolean(value)
+
+/**
+ * Invert a boolean value.
+ *
+ * @example
+ * ```
+ * // Expect: false
+ * const example1 = booleanNot(true)
+ * // Expect: true
+ * const example2 = booleanNot(false)
+ * ```
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Logic_gate}
+ */
+export function booleanNot(b: true): false
+export function booleanNot(b: false): true
+// catch all overload, used in `pipe` or `compose` or likewise situations.
+export function booleanNot(b: boolean): boolean
+export function booleanNot(b: unknown): boolean
+export function booleanNot(b: unknown): boolean { return !booleanFrom(b) }
+
+/**
+ * Perform logical AND.
+ *
+ * @example
+ * ```
+ * // Expect: false
+ * const example1 = booleanAnd(true, false)
+ * // Expect: true
+ * const example2 = booleanAnd(true, true)
+ * ```
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Logic_gate}
+ */
+export const booleanAnd = (x: unknown, y: unknown): boolean => booleanFrom(x) && booleanFrom(y)
+
+/**
+ * Perform logical OR.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = booleanOr(true, false)
+ * // Expect: false
+ * const example2 = booleanOr(false, false)
+ * ```
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Logic_gate}
+ */
+export const booleanOr = (x: unknown, y: unknown): boolean => booleanFrom(x) || booleanFrom(y)
+
+/**
+ * Perform logical NAND.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = booleanNand(true, false)
+ * // Expect: false
+ * const example2 = booleanNand(true, true)
+ * ```
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Logic_gate}
+ */
+export const booleanNand = (x: unknown, y: unknown): boolean => !booleanAnd(x, y)
+
+/**
+ * Perform logical NOR.
+ *
+ * @example
+ * ```
+ * // Expect: false
+ * const example1 = booleanNor(true, false)
+ * // Expect: true
+ * const example2 = booleanNor(false, false)
+ * ```
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Logic_gate}
+ */
+export const booleanNor = (x: unknown, y: unknown): boolean => !booleanOr(x, y)
+
+/**
+ * Perform logical XOR.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = booleanXor(true, false)
+ * // Expect: false
+ * const example2 = booleanXor(true, true)
+ * ```
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Logic_gate}
+ */
+export const booleanXor = (x: unknown, y: unknown): boolean => booleanFrom(x) !== booleanFrom(y)
+
+/**
+ * Perform logical XNOR.
+ *
+ * @example
+ * ```
+ * // Expect: false
+ * const example1 = booleanXnor(true, false)
+ * // Expect: true
+ * const example2 = booleanXnor(true, true)
+ * ```
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Logic_gate}
+ */
+export const booleanXnor = (x: unknown, y: unknown): boolean => !booleanXor(x, y)
+
+export type BooleanInvertFunctionReturn<FN extends AnyFunctionOfReturn<boolean>> =
+  // oxlint-disable-next-line no-explicit-any
+  FN extends (...args: any[]) => infer R ? (...args: Parameters<FN>) => BooleanNot<CastBoolean<R>> : never
+/**
+ * Create a complement function that inverts a boolean-returning function.
+ *
+ * @example
+ * ```
+ * const isEven = (value: number) => value % 2 === 0
+ * const isOdd = booleanComplement(isEven)
+ * // Expect: true
+ * const example1 = isOdd(3)
+ * // Expect: false
+ * const example2 = isOdd(4)
+ * ```
+ */
+export const booleanComplement = <FN extends AnyFunctionOfReturn<boolean>>(fn: FN): BooleanInvertFunctionReturn<FN> =>
+  // oxlint-disable-next-line no-explicit-any no-unsafe-type-assertion no-unsafe-argument
+  ((...args: any[]) => booleanNot(fn(...args))) as any as BooleanInvertFunctionReturn<FN>
+
+/**
+ * Check whether the value is truthy.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = booleanIsTruthy("ok")
+ * // Expect: false
+ * const example2 = booleanIsTruthy("")
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Glossary/Truthy}
+ * @see {@link booleanIsFalsy}
+ */
+export const booleanIsTruthy = (v: unknown): boolean => booleanFrom(v)
+/**
+ * Check whether the value is falsy.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = booleanIsFalsy(0)
+ * // Expect: false
+ * const example2 = booleanIsFalsy("0")
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Glossary/Falsy}
+ * @see {@link booleanIsTruthy}
+ */
+export const booleanIsFalsy = (v: unknown): boolean => !booleanIsTruthy(v)

package/src/basic/error.ts

@@ -0,0 +1,51 @@
+import { isError } from "./is.ts"
+
+const internalErrorMessages = new Set([
+  "network error", // Chrome
+  "Failed to fetch", // Chrome
+  "NetworkError when attempting to fetch resource.", // Firefox
+  "The Internet connection appears to be offline.", // Safari 16
+  "Load failed", // Safari 17+
+  "Network request failed", // `cross-fetch`
+  "fetch failed", // Undici (Node.js)
+  "terminated", // Undici (Node.js)
+])
+
+/**
+ * Checks if an error is a network error.
+ *
+ * @see {@link https://github.com/sindresorhus/is-network-error}
+ */
+export const errorIsNetworkError = (error: unknown): error is Error => {
+  if (error === null || error === undefined) {
+    return false
+  }
+
+  if (isError(error) === false) {
+    return false
+  }
+
+  if (error.name !== "TypeError" || typeof error.message !== "string") {
+    return false
+  }
+
+  // We do an extra check for Safari 17+ as it has a very generic error message.
+  // Network errors in Safari have no stack.
+  if (error.message === "Load failed") {
+    return error.stack === undefined
+  }
+
+  return internalErrorMessages.has(error.message)
+}
+
+/**
+ * Stringifies an exception into a readable format.
+ */
+export const errorStringifyException = (exception: unknown): string => {
+  if (isError(exception)) {
+    return `${exception.name}: ${exception.message}`
+  }
+  else {
+    return `${String(exception)}`
+  }
+}