npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@teamteanpm2024/provident-expedita-recusandae

v1.0.5

Published

Walk objects like this guy.

Downloads

11

Maintainers

shivamkalsi2024shivamkalsi2024

Keywords

monorepotoArrayUint32ArrayconcatMapclideterministicminimalArrayBuffer#sliceargstrimStartiebyteLengthregexharmonytypeofnativeWeakSetflatMaptypedboundbindwhatwgjasminezodargvfullwidthpackage.jsonwhichxtermqueueMicrotasktypescriptdom-testing-libraryvalidatetesteventDispatcherfiletrimRightprotocol-buffersFunction.prototype.namerm -frpnpm9mkdirscssStyleSheetdirectorybufferformcolorgesturesiterateES8jsESnextslotdiffInt16ArrayURLSearchParamskinesisinspectlastequalityqslintspecproxyreact-hook-formdeepcopymapreduceerroroffsetES2023ECMAScript 7css variablemetadatatapeFloat64ArraywordwraplinkauthenticationredactpyyamlfunctionaliamRegExp#flagscss nestingfind-uphigher-orderReactiveExtensionstypedarraysnodejssignalmulti-packageratelimitswfwatchdependenciesparsegettertoSorted@@toStringTagutil.inspectmapCSSaccessoransiAsyncIteratorsequenceString.prototype.trimsearchfromlogbundlerimportexporttelephoneES2018stringifierprotobufcurlargumentECMAScript 2023WebSocketsregular expressionsmochaestreemixinsdatastructurewebnegative zeromime-dbECMAScript 2015checkObject.fromEntriescensorbddwindowsRxJSeventsupl10nspringsharedweaksetponyfillnameerror-handlingsignals-0ECMAScript 2019Float32Arraycall-boundrequirepackagesmodulesimmerinferenceagentmkdirpecmascriptparentObject.entrieswordbreakObject.keysavawafjapanesebrowserlistarktypegetPrototypeOfwrapttypoint-freees-abstractdragES3lrureact posevisualio-tsfunctionbyteOffsettranspilefindLastisConcatSpreadablecommanderbuffersES2015shebangweakmaputilses2016cloudtraillistenersenvcreateeslintconfigdatereal-timewalkingreducesymlinksECMAScript 5regular expressionTypedArraycallbindhttpasynccss lessassertswalktakeautoscalingtypesafejoichannellanguagedebugES2022indicatorasciistringifyescapeistoolsrdspositivedependency managerformsgetoptsanitizehasOwnes-shimshelpersjson-schema-validationcontainsawaithardlinkssetImmediatejsontypeerrorairbnbmakereadablestreamlockfileauthObservablecorscodesprettycloudfronttdddefinePropertyvalidationwatcherpackagefastcopy__proto__nodeflagsjQueryparserconsumedescriptorsiteratorArrayBuffer.prototype.slicebytetouchclassnamereact-hooksarraysorteduser-streamsreusedescriptiona11yquerystringomitlooksnsfull-widthcolorsasserteslint-pluginsymlinkebsflatemitObservablesstyleguidereact-testing-librarymobilebundlingarraysoperating-systemECMAScript 2016guidpromisesroute53SymbolrangeerrorstructuredClones3folderqueueString.prototype.matchAllInt8ArrayenderrapidUint16ArraymimechromeenumerableArray.prototype.flattenformattingloggerfile systemdatajsdifftraversemoveperformantcollection.es6mkdirmatchAllthroathasOwnPropertyrgbreact animationexitPromisepassworddefinewarningdayjsfseventsefficientless mixinswaapiformatenvironmentprototypepipeintrinsices2018ESRxcollectionECMAScript 3tacitlazyvalidatorcopygetintrinsicpruneutilunicodelook-upUint8ArrayjavascriptmatchescloneObject.definePropertydeep-clonebcryptstreamtrimEndbreakstablereadablepureshellastidlesafeelasticachejson-schemaquoteimportcomparehandlerssigtermcryptdynamodbprivate dataloggingtypanionnopestatelessmerge_.extendObject.isrobustlibphonenumberconstES7utilityrmdirgetOwnPropertyDescriptorArray.prototype.findLastIndexyamlspinnerwritetssyntaxerrorviewxhrdotenvvestpropvaluepicomatches7fetchfull6to5cloudsearchworkflowfigletinputtoobjecttermdeepcloneincludesHyBicolumnES2016xsssomeless compileres8variablesendpointdescriptorworkerexecurlobjfastcloneelectronfindLastIndexinstallerSymbol.toStringTagES5shimsharedarraybufferInt32ArrayuuidhttpssameValueZerosuperagentbrowserterminalphoneparsingECMAScript 6ES2019bluebirdzerosidedirreactmodulethrottlefast-copyes-shim APIbannerReflect.getPrototypeOfsuperstructelbrequestfixed-widthquerysqsECMAScript 2022typedarraycjkprocesspathvaluesownscheme-validationECMAScript 2017configurablekeyYAMLvalidsortplugininvariantworkspace:*getgroupJSON-Schemababeles5optimizerchromiumschemejson-schema-validatorinstallMicrosoftprefixwidthnumberpostcss-pluginpolyfilles2017irqremovecode pointsbabel-coretimeajaxargparsecore-jsArray.prototype.filterjsdomnpmArray.prototype.flatMapwaitchinesestatusbootstrap css3dcolourstringMapcolumnstoolkitshamopenframerObjectpropertiesmrupreprocessoramazonfinduplengthUnderscoredeep-copyextralesscsstypesReactiveXframeworkserializationkoreanRegExp.prototype.flagstesterbeanstalkES2021threeRFC-6455eslintclassesArray.prototype.findLastrfc4122fast-deep-cloneTypeScriptBigInt64ArraywatchingduplexajvimmutableTypeBoxruntimeloadbalancingbusychaiclass-validator

Readme

@teamteanpm2024/provident-expedita-recusandae

Walk objects like this guy.

Map over an object in a preorder or postoder depth-first manner. Also, provides functions for serializing and deserializng self-referential objects using JSON pointer.

This library is designed to work well with functions that traverse an object in the same way JSON.stringify and JSON.parse do. Namely, preorder and postorder. To mimic that behavior entirely set the jsonCompat option to true.

Custom traversal functions are supported for some functions. This allows you to walk tree-like structures, such as a JSON schema, in a more efficient and logical way. Prefer walkEach in these scenarios.

map, walkEach, walkEachAsync, mapLeaves, compact, and truncate support the option modifyInPlace for in-place modification. Otherwise, the object is deep cloned.

export interface MutationOption {
    /** Set to true to modify the object instead of returning a new object. */
    modifyInPlace?: boolean
}

walker

walker(obj: object, walkFn: WalkFn, options: Options = {}) => void

Generic walking fn that traverses an object in preorder (default) or postorder, calling walkFn for each node. Can be used directly, but probably shouldn't.

export interface Node {
    key: string | undefined
    val: any
    parents: any[]
    path: string[]
    isLeaf: boolean
    isRoot: boolean
}

export interface Options {
    postOrder?: boolean
    jsonCompat?: boolean
    traverse?(x: any): any
}
import { walker } from '@teamteanpm2024/provident-expedita-recusandae'

const obj = {
    a: {
        b: 23,
        c: 24,
    },
    d: {
        e: 'Bob',
        f: [10, 20, 30],
    },
}

const nodes: Node[] = []
const walkFn = (node: Node) => {
    nodes.push(node)
}
walker(obj, walkFn, options)
nodes

Returns an array of nodes. Note this is how walk works, so prefer that fn.

[
  {
    key: undefined,
    parents: [],
    val: { a: { b: 23, c: 24 }, d: { e: 'Bob', f: [10, 20, 30] } },
    path: [],
    isRoot: true,
    isLeaf: false,
  },
  {
    key: 'a',
    val: { b: 23, c: 24 },
    parents: [{ a: { b: 23, c: 24 }, d: { e: 'Bob', f: [10, 20, 30] } }],
    path: ['a'],
    isLeaf: false,
    isRoot: false,
  },
  {
    key: 'b',
    val: 23,
    parents: [
      { b: 23, c: 24 },
      { a: { b: 23, c: 24 }, d: { e: 'Bob', f: [10, 20, 30] } },
    ],
    path: ['a', 'b'],
    isLeaf: true,
    isRoot: false,
  },
  ...
]

walk

walk(obj: object, options: WalkOptions = {}) => Node[]

Walk an object. Returns an array of all nodes in the object in either preorder or postorder.

export interface WalkOptions extends Options {
    leavesOnly?: boolean
}
import { walk } from '@teamteanpm2024/provident-expedita-recusandae'

const obj = {
    a: {
        b: 23,
        c: 24,
    },
    d: {
        e: 'Bob',
        f: [10, 20, 30],
    },
}
walk(obj).map((x) => x.path)

Produces:

[
    [],
    ["a"],
    ["a", "b"],
    ["a", "c"],
    ["d"],
    ["d", "e"],
    ["d", "f"],
    ["d", "f", "0"],
    ["d", "f", "1"],
    ["d", "f", "2"]
]

walkEach

walkEach(obj: object, walkFn: WalkFn, options: options?: WalkOptions & MutationOption) => object
export type WalkFn = (node: Node) => void

Walk over an object calling walkFn for each node. The original object is deep-cloned by default making it possible to simply mutate each node as needed in order to transform the object. The cloned object is returned if options.modifyInPlace is not set to true.

Below I want to walk a MongoDB JSON schema and set additionalProperties to true wherever it exists. I traverse this tree using a custom traverse fn. The original object is not modified.

import { walkEach } from '@teamteanpm2024/provident-expedita-recusandae'

const obj = {
    bsonType: 'object',
    additionalProperties: false,
    required: ['name'],
    properties: {
        _id: {
            bsonType: 'objectId',
        },
        name: { bsonType: 'string' },
        addresses: {
            bsonType: 'array',
            items: {
                bsonType: 'object',
                additionalProperties: false,
                properties: {
                    address: {
                        bsonType: 'object',
                        additionalProperties: false,
                        properties: {
                            zip: { bsonType: 'string' },
                            country: { bsonType: 'string' },
                        },
                    },
                },
            },
        },
    },
}

const traverse = (x: any) => x.properties || (x.items && { items: x.items })
const walkFn = ({ val }: Node) => {
    if ('additionalProperties' in val) {
        val.additionalProperties = true
    }
}
walkEach(obj, walkFn, { traverse })

Produces:

{
  bsonType: 'object',
  additionalProperties: true,
  required: ['name'],
  properties: {
    _id: { bsonType: 'objectId' },
    name: { bsonType: 'string' },
    addresses: {
      bsonType: 'array',
      items: {
        bsonType: 'object',
        additionalProperties: true,
        properties: {
          address: {
            bsonType: 'object',
            additionalProperties: true,
            properties: {
              zip: { bsonType: 'string' },
              country: { bsonType: 'string' },
            },
          },
        },
      },
    },
  },
}

walkEachAsync

Like walkEach but awaits the promise returned by walkFn before proceeding to the next node.

map

Map over an object modifying values with a fn depth-first in a preorder or postorder manner. The output of the mapper fn will be traversed if possible when traversing preorder.

By default, nodes will be excluded by returning undefined. Undefined array values will not be excluded. To customize pass a fn for options.shouldSkip.

map(obj: object, mapper: Mapper, options?: MapOptions & MutationOption) => object
export type Mapper = (node: Node) => any

export type MapOptions = Omit<Options, 'traverse'> & {
    shouldSkip?(val: any, node: Node): boolean
}
import { map } from '@teamteanpm2024/provident-expedita-recusandae'

const obj = {
    a: {
        b: 23,
        c: 24,
    },
    d: {
        e: 'Bob',
        f: [10, null, 30, [31, undefined, 32], 40],
    },
    g: [25, '', { h: [null, 26, 27] }],
    i: 'Frank',
}
map(obj, ({ val }) => (Array.isArray(val) ? _.compact(val) : val))

Produces:

{
  a: { b: 23, c: 24 },
  d: { e: 'Bob', f: [10, 30, [31, 32], 40] },
  g: [25, { h: [26, 27] }],
  i: 'Frank',
}

Postorder

const obj = {
    bob: {
        scores: ['87', 'x97', 95, false],
    },
    joe: {
        scores: [92, 92.5, '73.2', ''],
    },
    frank: {
        scores: ['abc', ''],
    },
}
const result = map(
    obj,
    ({ val, isLeaf }) => {
        if (isLeaf) {
            return parseFloat(val)
        }
        return Array.isArray(val) ? _.compact(val) : val
    },
    { postOrder: true }
)

Produces:

{
  bob: { scores: [87, 95] },
  joe: { scores: [92, 92.5, 73.2] },
  frank: { scores: [] },
}

Custom shouldSkip fn

const obj = {
    bob: {
        scores: ['87', 'x97', 95, false],
    },
    joe: {
        scores: [92, 92.5, '73.2', ''],
    },
    frank: {
        scores: ['abc', ''],
    },
}

const shouldSkip = (val: any, node: Node) =>
    _.isEmpty(val) && !parentIsArray(node)
const result = map(
    obj,
    ({ val, isLeaf }) => {
        if (isLeaf) {
            return parseFloat(val)
        }
        return Array.isArray(val) ? _.compact(val) : val
    },
    { postOrder: true, shouldSkip }
)

Produces:

{
  bob: { scores: [87, 95] },
  joe: { scores: [92, 92.5, 73.2] },
}

mapLeaves

mapLeaves(obj: object, mapper: Mapper, options?: MapOptions) => object

Map over the leaves of an object with a fn. By default, nodes will be excluded by returning undefined. Undefined array values will not be excluded. To customize pass a fn for options.shouldSkip.

import { mapLeaves } from '@teamteanpm2024/provident-expedita-recusandae'

const obj = {
    a: {
        b: 23,
        c: 24,
    },
    d: {
        e: 100,
        f: [10, 20, 30],
    },
}
mapLeaves(obj, ({ val }) => val + 1)

Produces:

{
  a: { b: 24, c: 25 },
  d: { e: 101, f: [11, 21, 31] },
}

findNode

findNode(obj: object, findFn: FindFn, options?: Options) => Node | undefined

Search for a node and short-circuit the tree traversal if it's found.

import { findNode } from '@teamteanpm2024/provident-expedita-recusandae'

const obj = {
    name: 'Joe',
    address: {
        city: 'New York',
        state: 'NY',
        zipCode: '10001',
    },
    likes: ['Stock Market', 'Running'],
}

findNode(obj, (node) => {
    return _.isEqual(node.path, ['address', 'zipCode'])
})

Produces:

{
  key: 'zipCode',
  val: '10001',
  parents: [
    { city: 'New York', state: 'NY', zipCode: '10001' },
    {
      name: 'Joe',
      address: { city: 'New York', state: 'NY', zipCode: '10001' },
      likes: ['Stock Market', 'Running'],
    },
  ],
  path: ['address', 'zipCode'],
  isLeaf: true,
  isRoot: false,
}

flatten

flatten(obj: object, options?: WalkOptions & FlattenOptions) => object
interface FlattenOptions {
    /** Defaults to '.' */
    separator?: string
    /** Flatten objects and not arrays */
    objectsOnly?: boolean
}

Flatten an object's keys. Optionally pass separator to determine what character to join keys with. Defaults to '.'. If an array is passed, an object of path to values is returned unless the objectsOnly option is set.

import { flatten } from '@teamteanpm2024/provident-expedita-recusandae'

const obj = {
    a: {
        b: 23,
        c: 24,
    },
    d: {
        e: 100,
        f: [10, 20, 30],
    },
}
flatten(obj)

Produces:

{
  'a.b': 23,
  'a.c': 24,
  'd.e': 100,
  'd.f.0': 10,
  'd.f.1': 20,
  'd.f.2': 30,
}

unflatten

unflatten(obj: object, options?: UnflattenOptions) => object
interface UnflattenOptions {
    /** Defaults to '.' */
    separator?: string | RegExp
}

Unflatten an object previously flattened. Optionally pass separator to determine what character or RegExp to split keys with. Defaults to '.'.

import { unflatten } from '@teamteanpm2024/provident-expedita-recusandae'

const obj = {
    'a.b': 23,
    'a.c': 24,
    'd.e': 100,
    'd.f.0': 10,
    'd.f.1': 20,
    'd.f.2.g': 30,
    'd.f.2.h.i': 40,
}
unflatten(obj)

Produces:

{
  a: {
    b: 23,
    c: 24,
  },
  d: {
    e: 100,
    f: [10, 20, { g: 30, h: { i: 40 } }],
  },
}

compact

compact(obj: object, options: CompactOptions & MutationOption) => object
interface CompactOptions {
    removeUndefined?: boolean
    removeNull?: boolean
    removeEmptyString?: boolean
    removeFalse?: boolean
    removeNaN?: boolean
    removeEmptyObject?: boolean
    removeEmptyArray?: boolean
    compactArrays?: boolean
    removeFn?: (val: any, node: Node) => boolean
}

Compact an object, removing fields recursively according to the supplied options. All option flags are false by default. If compactArrays is set to true arrays will be compacted based on the enabled remove option flags.

const obj = {
    a: {
        b: [null, null, 21, '', { b1: null }, { b2: 26 }],
    },
    c: [],
    d: [42, null],
    e: {
        f: {
            g: '',
            h: undefined,
            i: 'null',
        },
    },
}
const result = compact(obj, {
    removeUndefined: true,
    removeEmptyString: true,
    removeNull: true,
    compactArrays: true,
    removeEmptyArray: true,
    removeEmptyObject: true,
    removeFn: (val: any) => val === 'null',
})

Produces:

{
  a: { b: [21, { b2: 26 }] },
  d: [42],
}

truncate

truncate(obj: object, options: TruncateOptions & MutationOption) => object
export interface TruncateOptions {
    /** Max allowed depth of objects/arrays. Default to Infinity */
    maxDepth?: number
    /** What to replace an object/array at the maximum depth with. Defaults to '[Truncated]' */
    replacementAtMaxDepth?: any
    /** Max allowed length of a string. Defaults to Infinity */
    maxStringLength?: number
    /** What to replace the last characters of the truncated string with. Defaults to '...' */
    replacementAtMaxStringLength?: string
    /** Max allowed length of an array. Defaults to Infinity */
    maxArrayLength?: number
    /** Transform instances of Error into plain objects so that truncation can be performed. Defautls to false */
    transformErrors?: boolean
}

Truncate allows you to limit the depth of nested objects/arrays, the length of strings, and the length of arrays. Instances of Error can be converted to plain objects so that the enabled truncation options also apply to the error fields. All truncation methods are opt-in.

Note: For the best performance you should consider setting modifyInPlace to true.

const obj = {
    a: {
        b: 'Frank',
        c: {
            d: 'Joe',
        },
        e: null,
    },
    f: 42,
}
truncate(obj, { depth: 2 })

Produces:

{
  a: {
    b: 'Frank',
    c: '[Truncated]',
    e: null,
  },
  f: 42,
}

size

size(val: any) => number

Estimate the size in bytes.

const obj = {
    a: {
        b: 'hello',
    },
    c: Symbol('hello'),
    d: {
        e: [true, false],
    },
    f: [42, 10n],
}
size(obj)
// 44

Helper fns

These helper fns are exported for your convenience.

export const isObjectOrArray = _.overSome([_.isPlainObject, _.isArray])

export const defShouldSkip = (val: any, node: Node) =>
    val === undefined && !parentIsArray(node)

export const parentIsArray = (node: Node) => {
    const parent = node.parents[0]
    return Array.isArray(parent)
}

export const defTraverse = (x: any) => isObjectOrArray(x) && !_.isEmpty(x) && x

addRefs

addRefs(obj: object, options?: RefOptions): object

Replace duplicate objects refs with pointers to the first object seen.

import { addRefs } from '@teamteanpm2024/provident-expedita-recusandae'

const apiOutput = {
    1: 'foo',
    2: 'bar',
    3: 'baz',
}

const detailsOutput = {
    1: 'bla',
    2: 'bla',
    3: 'bla',
}

const obj = {
    api: {
        input: [1, 2, 3],
        output: apiOutput,
    },
    details: {
        input: apiOutput,
        output: detailsOutput,
    },
    writeToDB: {
        input: detailsOutput,
    },
}
addRefs(obj)

Produces:

{
  api: {
    input: [1, 2, 3],
    output: { '1': 'foo', '2': 'bar', '3': 'baz' },
  },
  details: {
    input: { $ref: '#/api/output' },
    output: { '1': 'bla', '2': 'bla', '3': 'bla' },
  },
  writeToDB: { input: { $ref: '#/details/output' } },
}

deref

deref(obj: object, options?: RefOptions): object

Rehydrate objects by replacing refs with actual objects.

import { deref } from '@teamteanpm2024/provident-expedita-recusandae'

const obj = {
    api: {
        input: [1, 2, 3],
        output: { '1': 'foo', '2': 'bar', '3': 'baz' },
    },
    details: {
        input: { $ref: '#/api/output' },
        output: { '1': 'bla', '2': 'bla', '3': 'bla' },
    },
    writeToDB: { input: { $ref: '#/details/output' } },
}
deref(obj)

Produces:

{
  api: {
    input: [1, 2, 3],
    output: { '1': 'foo', '2': 'bar', '3': 'baz' },
  },
  details: {
    input: { '1': 'foo', '2': 'bar', '3': 'baz' },
    output: { '1': 'bla', '2': 'bla', '3': 'bla' },
  },
  writeToDB: { input: { '1': 'bla', '2': 'bla', '3': 'bla' } },
}