Skip to content

utilery@0.3.0

Choose a tag to compare

@github-actions github-actions released this 26 Oct 13:43
· 60 commits to main since this release
Immutable release. Only release title and notes can be modified.
f857c84

Minor Changes

  • 2ffeb62 - Added new pathExists, readJsonFileSafe and readFilesInDirectorySafe server utilities: check whether a path exists, and read a JSON file or all files of a directory, getting null when it does not exist

  • 07e9ad8 - Added new string utilities:

  • 02db2b7 - Added new findExecutable and findExecutableSync utilities (which from which, giving undefined instead of throwing), a new quoteShellArgument utility (quoteForShell from puka) and a new isProcessAlive utility

  • 1d699b1 - colors returns plain text when colors are not supported (output that is not a terminal, NO_COLOR, FORCE_COLOR=0), and a new isColorSupported utility tells whether they are

  • 5c043e8 - Added a new semver group for semantic versions: compareSemver, isSemverInRange, isValidSemver and parseSemver (compare, satisfies, isValid and tryParse from verkit), and the ParsedSemver type

  • 14f9bbc - Added a new bitwise group for bit flags and other bit manipulation of 32-bit integers. Bit indexes are typed as BitIndex (an integer from 0 to 31), so out-of-range literals and enum members fail at compile time, and isBitIndex checks dynamic numbers:

  • 54f7fff - Added a new createSeededRandom utility: a seeded Math.random replacement from a number or a string seed, for reproducible results

  • 9db3b5c - Added a new glob group: globToRegex, isGlobMatch and isGlobPattern (makeRe, isMatch and scan from picomatch), and createPathFilter, a filter from include and exclude patterns

  • 161bee0 - Added a new getBuiltinModule utility: a typed process.getBuiltinModule that gives undefined outside Node.js

  • 80150d3 - Renamed the package from @andreww2012/unutils to utilery, so install it and import from utilery instead

  • a6d367d - arrayShuffle, arraySample, random, randomIntInclusive and randomIntExclusive get a random option for another generator, like one from createSeededRandom

  • d8b0c25 - Added a new parseNpmPackageSpecifier utility (parse from parse-package-name) that splits a specifier like @scope/package@1.2.3/sub/path into the name, the version and the path

  • 2eb3659 - createSingletonPromise no longer keeps a rejection by default, so the next call tries again (pass {cacheRejections: true} for the old behavior), and gets a ttlMs option

  • 8de06c0 - Added new utilities:

    • downloadFile in a new browser group: saves a string, bytes, a Blob, a fetch response or a stream as a file, like a download link, or through a "Save as" dialog in browsers that support it
    • formatDateForFileName: formats a date and time for file names, like 2026-10-25_14-30-05, with a choice of precision, UTC and separators
  • 42e7cec - Added new findUp and findUpSync utilities (findUp and findUpSync from find-up-simple) that find a file or directory in parent directories, and a new isPathInside utility

  • 60b94fa - Added a new sleepAbortable utility: like sleep, but rejects with the reason of the aborted signal and has an unref option to not keep the Node.js process alive

  • 83b38c1 - Added new getErrorMessage and interopDefault utilities: get a message from a caught value of any type, and resolve a module (or a dynamic import()) to its default export when it has one

  • 32e6ccc - Updated remeda from v2.51.0 to v2.53.0, which affected:

    • arrayMapWithAccumulator:
      • BREAKING: the callback now gets the source array as its fourth argument instead of the elements processed so far
  • 5951301 - Added new stripAnsi, getStringWidth and wrapText utilities (stripAnsi, stringWidth and wrapAnsi from strip-ansi, string-width and wrap-ansi): remove ANSI escape codes, measure the terminal width of a string and wrap styled text

  • 22b4cae - Added a new MaybeReadonlyArray type: a value or a readonly array of it. generateMailtoLink now uses it, so its recipient options also accept readonly arrays

  • 22b4cae - Added a new isArray utility from remeda: unlike Array.isArray, it also narrows readonly arrays

  • 23be320 - omit: a * deep path segment now matches every element of an array or property of an object, e.g. users.*.password removes password from every user. Deep paths also no longer mutate the input when they go through an array, e.g. omit(object, ['users.0.password'])

  • 4d59645 - Added a new path group for file paths on any platform, with isSafeRelativePath and parseNodeModulesPath. toForwardSlashes moved there from string, so import it from utilery/path instead of utilery/string

  • 03565c6 - Added new isPromiseLike, isValidDate and isUnsafeObjectKey utilities

  • 5d9e54f - Added a new topologicalSort utility (toposort.array from toposort) and the CyclicDependencyError it throws for a dependency cycle

  • c818297 - Added a new withAbortSignal utility that makes a promise reject with the reason of an AbortSignal as soon as it is aborted

  • bce739b - Utilities with a newer native counterpart now call it where it is available, with the same results everywhere:

    • mapGetOrInsert and mapGetOrInsertComputed call Map#getOrInsert and Map#getOrInsertComputed:
      • BREAKING: so the has, get and set methods of a Map subclass are not called there
    • promiseTry calls Promise.try
    • regexEscape calls RegExp.escape:
      • BREAKING: now escapes the same characters as RegExp.escape: also /, the other ASCII punctuation except _, whitespace, line terminators, lone surrogates and a leading ASCII letter or digit. This fixes a SyntaxError or a wrong match inside [...] with the v flag (like [${regexEscape('a/b')}] or [${regexEscape('a&&b')}]) and right after an escape like \1 or \0
    • uint8ArrayToBase64 and stringToBase64 call Uint8Array#toBase64
    • uint8ArrayToHex calls Uint8Array#toHex
    • base64ToUint8Array and base64ToString call Uint8Array.fromBase64:
      • BREAKING: now throw a SyntaxError instead of a DOMException
      • BREAKING: now reject incomplete padding (SGVsbA=), and always ignore ASCII whitespace (some valid strings with it were rejected)
    • hexToUint8Array calls Uint8Array.fromHex:
      • BREAKING: now throws a SyntaxError instead of an Error
  • edc0141 - Added new writeJsonFile and writeJsonFileSync utilities (writeJsonFile and writeJsonFileSync from write-json-file) that write JSON atomically and keep the indentation of an existing file, and a new getAppPaths utility (envPaths from env-paths) for the data, config and cache directories of an app

  • 3f4c756 - truncate gets a position option to cut the start or the middle

  • 6833f78 - Added a new isNodeError utility that tells whether a caught value is a Node.js system error, optionally with one of the given codes, and narrows its type

  • 8768aab - Fixed the types of objectEntriesUnsafe, objectKeysUnsafe and objectValuesUnsafe:

    • BREAKING: the values of optional properties given by objectEntriesUnsafe and objectValuesUnsafe include undefined, as such a property may be set to it, unless the exactOptionalPropertyTypes compiler option is on
    • a union of objects gives the keys, entries and values of each member instead of never
    • in generic code, the keys can index the object when its type parameter has known keys or an index signature, like T extends {a: number}
    • the keys of string enums keep their enum type
    • arrays give their index strings and other own keys, like index of a regex match, without length and method names
  • 10964e7 - Added new formatTerminalLink, formatTerminalFileLink and isTerminalLinkSupported utilities (hyperlink, link and supportsHyperlinks from clickable-path) for clickable links in terminals

  • e3a9fc0 - Added new isFile, isDirectory and isSymlink utilities and their *Sync versions (isFile, isDirectory, isSymlink, etc. from path-type), which give false for a missing path, and a new pathExistsSync utility

  • 0d9e353 - Added new slugify and createUniqueSlugify utilities, based on slugify from @sindresorhus/slugify and on any-ascii: URL slugs that are always ASCII, for text in any script, including Chinese, Japanese and Korean, and slugs that never repeat

  • 5f36e56 - Added new utilities:

  • 34e077d - Added new isAbortError and isTimeoutError utilities: check whether a caught value is an error named AbortError or TimeoutError

  • 6d0acc3 - Updated es-toolkit from v1.52.0 to v1.53.0, which affected:

    • assignDefaults:
      • with {copy: true}, copies the target like it does with {copy: true, deep: true}, so a target with a null prototype keeps it
    • ceil
    • deburr:
      • BREAKING: keeps letters of scripts other than Latin, like Cyrillic, Greek and Hangul, as they are, even with diacritical marks: deburr('й') gives 'й' instead of 'и'
    • findObjectKey:
      • types keys as Object.keys gives them: numeric keys as strings, without symbol keys
    • floor
    • freezeDeep
    • interpolate:
      • returns exactly max when t is 1, which rounding errors could break before
    • isObjectMatching
    • mapKeys
    • mapRange:
      • maps the end of the input range to exactly the end of the output range
    • mergeDeep
    • omit:
      • shares the other values with the input when it removes a key whose name looks like a path (like 'a.b'), as it does for other keys, instead of copying them
    • once
    • orderBy
    • pick
    • sortBy
    • truncate

    Added utilities from the new release:

  • 52f68c9 - withTimeout passes an AbortSignal to the function and aborts it on timeout; it rejects with a DOMException named TimeoutError, and with the abort reason when its signal is aborted (instead of only stopping the timer)

  • bade937 - Added a new findClosestNumber utility

  • 63cbf31 - Updated safe-stable-stringify from v2.5.0 to v3.0.0, which affected:

    • jsonStringifyStable:
      • BREAKING: now replaces circular references with "[Circular: N]" instead of "[Circular]", where N is the depth of the referenced ancestor (0 for the root)
  • 17ed0f2 - Added a new bytes group of Uint8Array conversions, Base64 and hex encoding, from uint8array-extras:

  • e11e7f6 - Added a new http group for parsing and formatting HTTP headers:

  • 18ef481 - Added a new net group for IP addresses, based on ipaddr.js:

    • isIpv4 and isIpv6 (IPv4.isValidFourPartDecimal and IPv6.isValid, strict about embedded IPv4 addresses too) and isIp
    • getIpRange (based on process), which tells whether an address is private, loopback, link-local, etc.
    • isLocalhost
  • 01f111d - Added a new formatDuration utility from pretty-ms (prettyMilliseconds) that formats milliseconds like '1h 2m 3s' or, in colon notation, '1:02:03', and a new parseColonDuration utility that parses the colon notation back into milliseconds

  • 1b1f8d3 - Added a new promiseTry utility: like Promise.try, it calls a function and always gives a promise, turning a synchronous throw into a rejection

  • bee52e6 - Added a new jsonStringifyForHtml utility (htmlEscape from htmlescape) that turns a value into JSON safe to embed in an HTML <script>

  • 758f540 - Added new memoizeAsync (pMemoize from p-memoize) and callAll utilities: memoize an async function without caching rejections, and combine functions into one that calls all of them

  • 6dabc8e - arrayChunks now also accepts an array of sizes, making one chunk per size. Infinity as a size collects the rest of the elements, and a literal tuple of sizes gives a tuple of chunks

  • 4f6604a - Added new arrayIsUnique, arrayFindDuplicates and arrayToggle utilities: check whether an array has repeated elements, find them, and add or remove a value like classList.toggle does

  • 49c57d1 - Updated ms-ts from v1.1.0 to v1.2.0, which affected:

    • ms:
      • BREAKING: calling it without the duration string as the generic parameter is now an error
    • Ms

Patch Changes

  • 3c88f4a - Updated arkregex from v0.0.12 to v0.0.14, which affected:

    • regexTyped
  • 4be25e6 - Updated remeda from v2.53.0 to v2.54.1

  • 057879f - Updated lossless-json from v4.3.1 to v4.3.3, which affected:

    • jsonParseLossless
    • jsonStringifyLossless
    • NumberLossless
  • 75bf10b - Updated p-memoize from v8.0.0 to v9.0.0, which affected:

    • memoizeAsync
    • MemoizeAsyncOptions
  • 676ca73 - jsonStringifyAsync now matches JSON.stringify in more cases:

    • circular structures are rejected at any depth, instead of resolving with [object Object] in the output or crashing the process (circular arrays)
    • functions and symbols are skipped, and undefined, functions and symbols in arrays become null
  • e8ba0c7 - Exported TruncateOptions, the options type of truncate

  • 3423c17 - Updated pretty-ms from v9.3.1 to v10.0.0, which affected:

    • formatDuration
  • 3bdc0f0 - regexEscape now uses escape-string-regexp and also escapes -, so its result is safe inside a character class

  • 6c8c77b - Updated devalue from v6.0.2 to v6.0.3

  • 51d85f2 - Rewrote the docs of re-exported utilities, types and their options: they now name our utilities and types instead of the upstream ones, don't mention bundled packages, and show up at call sites, also in parameter hints. Documented the overloads and errors of more utilities

  • 57ce269 - arrayify: a union mixing arrays with other values is now typed member by member, so its tuples keep their own types instead of becoming array elements

  • 2f0a434 - Added the missing license text of typed-query-selector, whose types the published package includes, to THIRD_PARTY_NOTICES.md

  • e42cff7 - Updated ms-ts from v1.0.0 to v1.1.0

  • ec23c95 - Importing the main entry point or regex no longer adds a global ArkEnv type to your project. With skipLibCheck: false, it broke type checking in projects that also use ArkType

  • c9c3f1c - Editor hovers now show the results of these utilities and types as single object types, instead of intersections like {a: number} & {b: number} or helper types like Pick<...>:

    • assignDefaults, mergeDeep (with mergeValues), omit, pick and swapObjectProperties
    • DiscriminatedUnion, NonEmptyObject, OmitDistributed, OmitIndexSignature, PickConditional, PickDistributed, PickIndexSignature, RequireAtLeastOne, RequireExactlyOne, SetNonNullable, StringifiedValues and TruncateOptions
  • a3d2793 - Fixed keys from data or callbacks changing prototypes:

    • deleteByPath:
      • refuses with false a path that steps through an inherited constructor or __proto__, or into the prototype of a function, also with a key that only converts to these names, like ["constructor"]: deleteByPath({}, 'constructor.keys') deleted Object.keys, and deleteByPath({}, 'constructor.prototype.toString') deleted Object.prototype.toString, for the whole program
      • goes through and deletes own constructor and __proto__ keys like other keys, while it refused an own __proto__ key before
    • these utilities no longer replace the prototype of the object they build or update with the value of a __proto__ key (or a key that converts to it, like ["__proto__"]), which JSON.parse can create and a callback can return, but keep the key as an own property:
      • allKeyed
      • assignDefaults with {deep: true}, or with {copy: true} and such a key in the target
      • cloneDeep and cloneShallow
      • flattenObject
      • jsonParseAsync
      • mapKeys, mapKeysAsync, mapValues and mapValuesAsync
      • mergeDeep with {copy: true} and such a key in the target
      • objectAssign and objectUpdate
      • objectFromKeys
      • omit, which also removes the key when asked, and pick
      • parseLinkHeader, which also no longer gives a parameter named like an inherited property, such as constructor, that property as an earlier value
      • replaceKeys and transformKeysDeep
      • setByPathImmutable, for a __proto__ segment of an array
      • sortKeys
      • swapObjectKeysValues
  • c31b63c - Updated decode-uri-component from v0.5.0 to v0.5.1, which affected:

    • decodeUriComponentSafe:
      • a cut-off %C2 and the byte order marks %FE%FF and %FF%FE now become replacement characters (U+FFFD) in any case of hex digits, not only in upper case
  • d31458b - Listed the exact versions of all bundled packages in the new inlinedDependencies field of package.json

  • 8feeb0b - Fixed utilities for options set to undefined, which the types allow without the exactOptionalPropertyTypes compiler option, and types for users with that option:

    • options set to undefined work like missing ones in:
      • jsonStringifyStable.configure, which threw a TypeError for them
      • formatBytes: space
      • slugify and createUniqueSlugify: separator, lowercase, decamelize and preserveCharacters
      • truncate: omission
      • writeJsonFile and writeJsonFileSync: detectIndent
    • with the compiler option:
      • undefined can be passed as circularValue to jsonStringifyStable.configure and as indent to writeJsonFile and writeJsonFileSync, as documented
      • objectUpdate accepts an optional property of the update for a required property of the target, and rejects undefined for an optional property of the target that doesn't include it