Interface IFilterOnlyOptions

If true, it respects the position of Array items, assigning the mapped/filtered array items to the same indexes (i.e sparse Arrays, will stay sparse). If false, it will always return a dense/compact Array.

@default: false

If filterSingles: false (default), it throws an error on any z.isSingleOrWeak input (eg z.filter(123) throws), as well as for WeakMap & WeakSet which are treated as singles (they can't be iterated over).

Otherwise, if filterSingles: true see singlesReject option for explanation.

true
Copy

If filterSingles: false (default), it throws an error on any single input (eg z.filter(123) throws).

BUT:

If filterSingles: true, it returns a "clone" of the single value itself, if it passes the filterCb!

So, if filterCb passes:

• Primitives are returned as is
• BoxedPrimitive instances & Boxed single values (eg Date, RegExp) are returned a new instance of the same type, with same underlying value. This is so it's consistent with the other collection functions (map, clone etc), which return new instances of the same type.

Now, if filterCb doesn't pass, the return value depends on singlesReject option:

If singlesReject is truthy, it returns that value. Note that the default is the special value z.NOTHING (which equals to Symbol('z.NOTHING'))

If singlesReject is falsey, it returns what ever this value is (eg undefined) in most cases, except:

• number becomes NaN
• BigInt also becomes NaN
• Symbol becomes z.NOTHING (i.e Symbol('z.NOTHING'))
• Date becomes new Date(null), which is 1970-01-01T00:00:00.000Z
• Function becomes a () => EMPTY (i.e () => Symbol('z.NOTHING'))

Boxed Primitives (please, please DONT use them!) are returned as new instances of the same type, with an "invalid" value:

• Number becomes new Number(NaN)
• Boolean becomes new Boolean(false) (which is bad!), but who uses Boolean instances anyway?
• String becomes new String('') - also bad to use!

Note: All other _.isObject single input values (eg Date, RegExp, BoxedPrimitive instances) are returned as a new instance of same type, even if filterCb rejects them.

@default: z.NOTHING (i.e Symbol('z.NOTHING'))