extra-utils 5.1.0 → 5.2.0

package/README.md

@@ -98,6 +98,8 @@ function isntChar(val: unknown): boolean
 
 function isURLString(text: string): boolean
 function isntURLString(text: string): boolean
+
+function toString(val: unknown): string
 ```
 
 #### removeExtraIndents

package/lib/string/index.d.ts

@@ -5,3 +5,4 @@ export * from './remove-blank-lines.js';
 export * from './remove-extra-indents.js';
 export * from './remove-leading-blank-lines.js';
 export * from './remove-trailing-blank-lines.js';
+export * from './to-string.js';

package/lib/string/index.js

@@ -5,4 +5,5 @@ export * from './remove-blank-lines.js';
 export * from './remove-extra-indents.js';
 export * from './remove-leading-blank-lines.js';
 export * from './remove-trailing-blank-lines.js';
+export * from './to-string.js';
 //# sourceMappingURL=index.js.map

package/lib/string/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/string/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,iCAAiC,CAAA;AAC/C,cAAc,kCAAkC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/string/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,iCAAiC,CAAA;AAC/C,cAAc,kCAAkC,CAAA;AAChD,cAAc,gBAAgB,CAAA"}

package/lib/string/to-string.d.ts

@@ -0,0 +1 @@
+export declare function toString(val: unknown): string;

package/lib/string/to-string.js

@@ -0,0 +1,4 @@
+export function toString(val) {
+    return `${val}`;
+}
+//# sourceMappingURL=to-string.js.map

package/lib/string/to-string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-string.js","sourceRoot":"","sources":["../../src/string/to-string.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,QAAQ,CAAC,GAAY;IACnC,OAAO,GAAG,GAAG,EAAE,CAAA;AACjB,CAAC"}

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "extra-utils",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "Utilities for JavaScript and Typescript",
   "files": [
+    "src",
     "lib"
   ],
   "type": "module",
@@ -35,30 +36,30 @@
   "devDependencies": {
     "@blackglory/jest-resolver": "^0.3.0",
     "@blackglory/pass": "^1.1.0",
-    "@commitlint/cli": "^17.4.4",
-    "@commitlint/config-conventional": "^17.4.4",
-    "@types/jest": "^29.4.0",
-    "@types/jsdom": "^21.1.0",
-    "@types/lodash-es": "^4.17.6",
-    "@typescript-eslint/eslint-plugin": "^5.52.0",
-    "@typescript-eslint/parser": "^5.52.0",
+    "@commitlint/cli": "^17.6.1",
+    "@commitlint/config-conventional": "^17.6.1",
+    "@types/jest": "^29.5.0",
+    "@types/jsdom": "^21.1.1",
+    "@types/lodash-es": "^4.17.7",
+    "@typescript-eslint/eslint-plugin": "^5.58.0",
+    "@typescript-eslint/parser": "^5.58.0",
     "cross-env": "^7.0.3",
-    "eslint": "^8.34.0",
+    "eslint": "^8.38.0",
     "husky": "^4.3.8",
-    "jest": "^29.4.3",
-    "jest-resolve": "^29.4.3",
+    "jest": "^29.5.0",
+    "jest-resolve": "^29.5.0",
     "npm-run-all": "^4.1.5",
     "rimraf": "^3.0.2",
     "standard-version": "^9.5.0",
-    "ts-jest": "^29.0.5",
+    "ts-jest": "^29.1.0",
     "ts-patch": "^2.1.0",
-    "tsd": "^0.25.0",
+    "tsd": "^0.28.1",
     "tslib": "^2.5.0",
     "typescript": "4.8",
     "typescript-transform-paths": "^3.4.6"
   },
   "dependencies": {
-    "justypes": "^4.1.0",
+    "justypes": "^4.2.0",
     "lodash-es": "^4.17.21"
   }
 }

package/src/array/index.ts

@@ -0,0 +1,2 @@
+export * from './is-array.js'
+export * from './is-empty-array.js'

package/src/array/is-array.ts

@@ -0,0 +1,7 @@
+export function isArray<T>(val: unknown): val is Array<T> {
+  return Array.isArray(val)
+}
+
+export function isntArray<T>(val: T): val is Exclude<T, Array<unknown>> {
+  return !isArray(val)
+}

package/src/array/is-empty-array.ts

@@ -0,0 +1,9 @@
+import { NonEmptyArray } from 'justypes'
+
+export function isEmptyArray(val: unknown[]): boolean {
+  return val.length === 0
+}
+
+export function isntEmptyArray<T>(val: T[]): val is NonEmptyArray<T> {
+  return val.length !== 0
+}

package/src/boolean/index.ts

@@ -0,0 +1,2 @@
+export * from './is-boolean.js'
+export * from './is-falsy.js'

package/src/boolean/is-boolean.ts

@@ -0,0 +1,7 @@
+export function isBoolean(val: unknown): val is boolean {
+  return typeof val === 'boolean'
+}
+
+export function isntBoolean<T>(val: unknown): val is Exclude<T, boolean> {
+  return !isBoolean(val)
+}

package/src/boolean/is-falsy.ts

@@ -0,0 +1,9 @@
+import { Falsy } from 'justypes'
+
+export function isFalsy(val: unknown): val is Falsy {
+  return !val
+}
+
+export function isntFalsy<T>(val: T): val is Exclude<T, Falsy> {
+  return !isFalsy(val)
+}

package/src/in-enum.ts

@@ -0,0 +1,10 @@
+// 由于以下原因, 该函数不应该被改写为其他形式:
+// - enum在TypeScript里被作为单独的类型看待, 不满足extends object
+// - 作为泛型时, enum参数会被提取为typeof enum类型而不是enum
+export function inEnum<T>(val: unknown, _enum: object): val is T {
+  return Object.values(_enum).includes(val)
+}
+
+export function notInEnum<T, U>(val: T, _enum: object): val is Exclude<T, U> {
+  return !inEnum(val, _enum)
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from './array/index.js'
+export * from './boolean/index.js'
+export * from './number/index.js'
+export * from './object/index.js'
+export * from './json/index.js'
+export * from './string/index.js'
+export * from './nullish/index.js'
+export * from './in-enum.js'
+export * from './is-regexp.js'
+export * from './is-symbol.js'
+export * from './is-date.js'
+export * from './is-function.js'
+export * from './pipe.js'
+export * from './pipe-async.js'

package/src/is-date.ts

@@ -0,0 +1,7 @@
+export function isDate(val: unknown): val is Date {
+  return val instanceof Date
+}
+
+export function isntDate<T>(val: T): val is Exclude<T, Date> {
+  return !isDate(val)
+}

package/src/is-function.ts

@@ -0,0 +1,9 @@
+export function isFunction<T extends Function = (...args: any[]) => any>(
+  val: unknown
+): val is T {
+  return typeof val === 'function'
+}
+
+export function isntFunction<T>(val: T): val is Exclude<T, Function> {
+  return !isFunction(val)
+}

package/src/is-regexp.ts

@@ -0,0 +1,7 @@
+export function isRegExp(val: unknown): val is RegExp {
+  return val instanceof RegExp
+}
+
+export function isntRegExp<T>(val: T): val is Exclude<T, RegExp> {
+  return !isRegExp(val)
+}

package/src/is-symbol.ts

@@ -0,0 +1,7 @@
+export function isSymbol(val: unknown): val is symbol {
+  return typeof val === 'symbol'
+}
+
+export function isntSymbol<T>(val: T): val is Exclude<T, symbol> {
+  return !isSymbol(val)
+}

package/src/json/index.ts

@@ -0,0 +1,2 @@
+export * from './is-json-value.js'
+export * from './is-json-serializable.js'

package/src/json/is-json-serializable.ts

@@ -0,0 +1,17 @@
+import { JSONValue, JSONSerializable } from 'justypes'
+import { isObject } from '@src/object/index.js'
+import { isFunction } from '@src/is-function.js'
+
+export function isJSONSerializable<T extends
+| JSONValue
+| Record<string, JSONValue | JSONSerializable<any>>
+| Array<JSONValue | JSONSerializable<any>>
+>(val: unknown): val is JSONSerializable<T> {
+  return isObject(val)
+      && 'toJSON' in val
+      && isFunction(val.toJSON)
+}
+
+export function isntJSONSerializable<T>(val: T): val is Exclude<T, JSONSerializable<any>> {
+  return !isJSONSerializable(val)
+}

package/src/json/is-json-value.ts

@@ -0,0 +1,20 @@
+import { JSONValue } from 'justypes'
+import { isNull } from '@src/nullish/index.js'
+import { isBoolean } from '@src/boolean/index.js'
+import { isString } from '@src/string/index.js'
+import { isNumber } from '@src/number/index.js'
+import { isArray } from '@src/array/index.js'
+import { isPlainObject } from '@src/object/index.js'
+
+export function isJSONValue(val: unknown): val is JSONValue {
+  return isNull(val)
+      || isBoolean(val)
+      || isString(val)
+      || isNumber(val)
+      || (isArray(val) && val.every(isJSONValue))
+      || (isPlainObject(val) && Object.values(val).every(isJSONValue))
+}
+
+export function isntJSONValue<T>(val: T): val is Exclude<T, JSONValue> {
+  return !isJSONValue(val)
+}

package/src/nullish/index.ts

@@ -0,0 +1,3 @@
+export * from './is-null.js'
+export * from './is-undefined.js'
+export * from './is-nullish.js'

package/src/nullish/is-null.ts

@@ -0,0 +1,7 @@
+export function isNull(val: unknown): val is null {
+  return val === null
+}
+
+export function isntNull<T>(val: T): val is Exclude<T, null> {
+  return !isNull(val)
+}

package/src/nullish/is-nullish.ts

@@ -0,0 +1,12 @@
+import { Nullish } from 'justypes'
+import { isNull } from './is-null.js'
+import { isUndefined } from './is-undefined.js'
+
+export function isNullish(val: unknown): val is Nullish {
+  return isNull(val)
+      || isUndefined(val)
+}
+
+export function isntNullish<T>(val: T): val is Exclude<T, Nullish> {
+  return !isNullish(val)
+}

package/src/nullish/is-undefined.ts

@@ -0,0 +1,7 @@
+export function isUndefined(val: unknown): val is undefined {
+  return val === undefined
+}
+
+export function isntUndefined<T>(val: T): val is Exclude<T, undefined> {
+  return !isUndefined(val)
+}

package/src/number/index.ts

@@ -0,0 +1,5 @@
+export * from './is-bigint.js'
+export * from './is-finite.js'
+export * from './is-infinity.js'
+export * from './is-nan.js'
+export * from './is-number.js'

package/src/number/is-bigint.ts

@@ -0,0 +1,7 @@
+export function isBigInt(val: unknown): val is bigint {
+  return typeof val === 'bigint'
+}
+
+export function isntBigInt<T>(val: T): val is Exclude<T, bigint> {
+  return !isBigInt(val)
+}

package/src/number/is-finite.ts

@@ -0,0 +1,3 @@
+export function isFinite(val: number): boolean {
+  return Number.isFinite(val)
+}

package/src/number/is-infinity.ts

@@ -0,0 +1,7 @@
+export function isPositiveInfinity(val: number): boolean {
+  return val === Infinity
+}
+
+export function isNegativeInfinity(val: number): boolean {
+  return val === -Infinity
+}

package/src/number/is-nan.ts

@@ -0,0 +1,7 @@
+export function isNaN(val: number): boolean {
+  return Number.isNaN(val)
+}
+
+export function isntNaN(val: number): boolean {
+  return !isNaN(val)
+}

package/src/number/is-number.ts

@@ -0,0 +1,7 @@
+export function isNumber(val: unknown): val is number {
+  return typeof val === 'number'
+}
+
+export function isntNumber<T>(val: T): val is Exclude<T, number> {
+  return !isNumber(val)
+}

package/src/object/index.ts

@@ -0,0 +1,3 @@
+export * from './is-empty-object.js'
+export * from './is-object.js'
+export * from './is-plain-object.js'

package/src/object/is-empty-object.ts

@@ -0,0 +1,7 @@
+export function isEmptyObject(val: object): boolean {
+  return Object.keys(val).length === 0
+}
+
+export function isntEmptyObject(val: object): boolean {
+  return Object.keys(val).length !== 0
+}

package/src/object/is-object.ts

@@ -0,0 +1,12 @@
+export function isObject(
+  val: unknown
+): val is object & Record<string | symbol | number, unknown> {
+  return val !== null
+      && typeof val === 'object'
+}
+
+export function isntObject<T>(
+  val: T
+): val is Exclude<T, object & Record<string | symbol | number, unknown>> {
+  return !isObject(val)
+}

package/src/object/is-plain-object.ts

@@ -0,0 +1,15 @@
+import { isPlainObject as isPlainObjectByLodash } from 'lodash-es'
+
+export function isPlainObject(
+  val: unknown
+): val is object & Record<string | symbol | number, unknown> {
+  // 仅通过`Object.getPrototypeOf(val) === Object.prototype`无法判断Node.js的一些纯对象,
+  // 因此在此引入lodash的方法.
+  return isPlainObjectByLodash(val)
+}
+
+export function isntPlainObject<T>(
+  val: T
+): val is Exclude<T, object & Record<string | symbol | number, unknown>> {
+  return !isPlainObject(val)
+}

package/src/pipe-async.ts

@@ -0,0 +1,79 @@
+import { Awaitable } from 'justypes'
+
+export function pipeAsync<A, B, C, D, E, F, G, H>(
+  value: Awaitable<A>
+, ...operators: [
+    (value: A) => Awaitable<B>
+  , (value: B) => Awaitable<C>
+  , (value: C) => Awaitable<D>
+  , (value: D) => Awaitable<E>
+  , (value: E) => Awaitable<F>
+  , (value: F) => Awaitable<G>
+  , (value: G) => Awaitable<H>
+  ]
+): Promise<H>
+export function pipeAsync<A, B, C, D, E, F, G>(
+  value: Awaitable<A>
+, ...operators: [
+    (value: A) => Awaitable<B>
+  , (value: B) => Awaitable<C>
+  , (value: C) => Awaitable<D>
+  , (value: D) => Awaitable<E>
+  , (value: E) => Awaitable<F>
+  , (value: F) => Awaitable<G>
+  ]
+): Promise<G>
+export function pipeAsync<A, B, C, D, E, F>(
+  value: Awaitable<A>
+, ...operators: [
+    (value: A) => Awaitable<B>
+  , (value: B) => Awaitable<C>
+  , (value: C) => Awaitable<D>
+  , (value: D) => Awaitable<E>
+  , (value: E) => Awaitable<F>
+  ]
+): Promise<F>
+export function pipeAsync<A, B, C, D, E>(
+  value: Awaitable<A>
+, ...operators: [
+    (value: A) => Awaitable<B>
+  , (value: B) => Awaitable<C>
+  , (value: C) => Awaitable<D>
+  , (value: D) => Awaitable<E>
+  ]
+): Promise<E>
+export function pipeAsync<A, B, C, D>(
+  value: Awaitable<A>
+, ...operators: [
+    (value: A) => Awaitable<B>
+  , (value: B) => Awaitable<C>
+  , (value: C) => Awaitable<D>
+  ]
+): Promise<D>
+export function pipeAsync<A, B, C>(
+  value: Awaitable<A>
+, ...operators: [
+    (value: A) => Awaitable<B>
+  , (value: B) => Awaitable<C>
+  ]
+): Promise<C>
+export function pipeAsync<A, B>(
+  value: Awaitable<A>
+, ...operators: [
+    (value: A) => Awaitable<B>
+  ]
+): Promise<B>
+export function pipeAsync<T, U>(
+  value: Awaitable<T>
+, ...operators: Array<(value: any) => Awaitable<unknown>>
+): Promise<U>
+export async function pipeAsync<T, U>(
+  value: Awaitable<T>
+, ...operators: Array<(value: T | U) => T | U>
+): Promise<U> {
+  let result: T | U = await value
+  for (const operator of operators) {
+    result = await operator(result)
+  }
+  return result as U
+}

package/src/pipe.ts

@@ -0,0 +1,77 @@
+export function pipe<A, B, C, D, E, F, G, H>(
+  value: A
+, ...operators: [
+    (value: A) => B
+  , (value: B) => C
+  , (value: C) => D
+  , (value: D) => E
+  , (value: E) => F
+  , (value: F) => G
+  , (value: G) => H
+  ]
+): H
+export function pipe<A, B, C, D, E, F, G>(
+  value: A
+, ...operators: [
+    (value: A) => B
+  , (value: B) => C
+  , (value: C) => D
+  , (value: D) => E
+  , (value: E) => F
+  , (value: F) => G
+  ]
+): G
+export function pipe<A, B, C, D, E, F>(
+  value: A
+, ...operators: [
+    (value: A) => B
+  , (value: B) => C
+  , (value: C) => D
+  , (value: D) => E
+  , (value: E) => F
+  ]
+): F
+export function pipe<A, B, C, D, E>(
+  value: A
+, ...operators: [
+    (value: A) => B
+  , (value: B) => C
+  , (value: C) => D
+  , (value: D) => E
+  ]
+): E
+export function pipe<A, B, C, D>(
+  value: A
+, ...operators: [
+    (value: A) => B
+  , (value: B) => C
+  , (value: C) => D
+  ]
+): D
+export function pipe<A, B, C>(
+  value: A
+, ...operators: [
+    (value: A) => B
+  , (value: B) => C
+  ]
+): C
+export function pipe<A, B>(
+  value: A
+, ...operators: [
+    (value: A) => B
+  ]
+): B
+export function pipe<T, U>(
+  value: T
+, ...operators: Array<(value: any) => unknown>
+): U
+export function pipe<T, U>(
+  value: T
+, ...operators: Array<(value: T | U) => T | U>
+): U {
+  let result: T | U = value
+  for (const operator of operators) {
+    result = operator(result)
+  }
+  return result as U
+}

package/src/string/index.ts

@@ -0,0 +1,8 @@
+export * from './is-char.js'
+export * from './is-string.js'
+export * from './is-url-string.js'
+export * from './remove-blank-lines.js'
+export * from './remove-extra-indents.js'
+export * from './remove-leading-blank-lines.js'
+export * from './remove-trailing-blank-lines.js'
+export * from './to-string.js'

package/src/string/is-char.ts

@@ -0,0 +1,10 @@
+import { isString } from './is-string.js'
+
+export function isChar(val: unknown): val is string {
+  return isString(val)
+      && val.length === 1
+}
+
+export function isntChar(val: unknown): boolean {
+  return !isChar(val)
+}

package/src/string/is-string.ts

@@ -0,0 +1,7 @@
+export function isString(val: unknown): val is string {
+  return typeof val === 'string'
+}
+
+export function isntString<T>(val: T): val is Exclude<T, string> {
+  return !isString(val)
+}

package/src/string/is-url-string.ts

@@ -0,0 +1,12 @@
+export function isURLString(text: string): boolean {
+  try {
+    new URL(text)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function isntURLString(text: string): boolean {
+  return !isURLString(text)
+}

package/src/string/remove-blank-lines.ts

@@ -0,0 +1,8 @@
+import { isntBlankLine } from './utils.js'
+
+export function removeBlankLines(text: string): string {
+  return text
+    .split('\n')
+    .filter(line => isntBlankLine(line))
+    .join('\n')
+}

package/src/string/remove-extra-indents.ts

@@ -0,0 +1,29 @@
+import { isntBlankLine } from './utils.js'
+
+export function removeExtraIndents(
+  text: string
+, { ignoreBlankLines = false }: {
+    ignoreBlankLines?: boolean
+  } = {}
+): string {
+  const lines = text.split('\n')
+  const commonIndentLength = lines
+    .filter(line => ignoreBlankLines ? isntBlankLine(line) : true)
+    .reduce(
+      (acc, cur) => {
+        const indent = cur.match(/^(\s+)/)
+        if (indent) {
+          return Math.min(acc, indent[1].length)
+        } else {
+          return 0
+        }
+      }
+    , Infinity
+    )
+  if (commonIndentLength === 0 || commonIndentLength === Infinity) {
+    return text
+  }
+
+  const newLines = lines.map(x => x.slice(commonIndentLength))
+  return newLines.join('\n')
+}

package/src/string/remove-leading-blank-lines.ts

@@ -0,0 +1,20 @@
+import { isBlankLine } from './utils.js'
+
+export function removeLeadingBlankLines(
+  text: string
+, maxRemovals: number = Infinity
+): string {
+  const lines = text.split('\n')
+
+  let removals = 0
+  while (
+    removals < maxRemovals &&
+    lines.length > 0 &&
+    isBlankLine(lines[0])
+  ) {
+    lines.shift()
+    removals++
+  }
+
+  return lines.join('\n')
+}

package/src/string/remove-trailing-blank-lines.ts

@@ -0,0 +1,20 @@
+import { isBlankLine } from './utils.js'
+
+export function removeTrailingBlankLines(
+  text: string
+, maxRemovals: number = Infinity
+): string {
+  const lines = text.split('\n')
+
+  let removals = 0
+  while (
+    removals < maxRemovals &&
+    lines.length > 0 &&
+    isBlankLine(lines[lines.length - 1])
+  ) {
+    lines.pop()
+    removals++
+  }
+
+  return lines.join('\n')
+}

package/src/string/to-string.ts

@@ -0,0 +1,3 @@
+export function toString(val: unknown): string {
+  return `${val}`
+}

package/src/string/utils.ts

@@ -0,0 +1,7 @@
+export function isBlankLine(line: string): boolean {
+  return line.trim() === ''
+}
+
+export function isntBlankLine(line: string): boolean {
+  return !isBlankLine(line)
+}