object-no-new-keys^5.0.3

Installation

Quick Take

Purpose

Check, does a given plain object have any keys, not present in a reference object. Returns array of zero or more paths in object-path notation.

For example, it can be used to look for any rogue keys in email template content JSON files.

API — noNewKeys()

The main function noNewKeys() is imported like this:

It’s a function which takes three input arguments:

The Optional Options Object has the following shape:

Here are all defaults in one place for copying:

The function will return an array of zero or more strings — paths to each key/element in the input which does not exist in reference.

Two modes

This library has two modes:

1. Strict comparing, having no assumptions about the reference.
2. Comparing, assuming that the reference will be NORMALISED.

By ”normalised“ we mean if any arrays have object children, those objects have the same keys.

These two modes mainly concern the case when both input and reference have an array, but reference has fewer elements and there’s nothing to compare the input element to:

const input = {
  a: [
    {
      // object number 1
      b: "b1",
      c: "c1",
    },
    {
      // object number 2
      b: "b2",
      c: "c2",
      x: "y",
    },
  ],
};

const reference = {
  a: [
    {
      // << just one object!
      b: "b3",
      c: "c3",
    },
  ],
};

First mode will report that a[1].b and a[1].c and a[1].x are all rogue keys, not present in reference.

The second mode will anticipate that reference will be normalised, that is, we can compare input array elements to the first element of an array in reference. We’ll get the same thing — all objects within an array should have the same keys. This means, input has only one rogue key — a[1].x. And algorithm will identify it by comparing input object a[1] to reference object a[0] — second/third/whatever element in the input to ALWAYS THE FIRST ELEMENT IN REFERENCE, a[0].

We need the second mode, but we give people chance to use the first mode as well. Maybe somebody will find it useful.

For example

import { noNewKeys } from "object-no-new-keys";
const res = noNewKeys(
  {
    a: "a",
    b: "b",
    c: "c",
  },
  {
    c: "z",
  }
);
console.log(JSON.stringify(noNewKeys, null, 4));
// => ['a', 'b']
// meaning, path "a" and path "b" were missing
// path notation uses [] to mark array's contents

works with arrays too:

import { noNewKeys } from "object-no-new-keys";
const res = noNewKeys(
  {
    //<<< input
    a: [
      {
        b: "aaa",
        d: "aaa", // rogue key, record it
        f: "fff", // another rogue key, record it
      },
      {
        c: "aaa",
        k: "kkk", // yet another rogue key, record it
      },
    ],
    x: "x", // rogue too
  },
  {
    // <<< reference
    a: [
      {
        b: "bbb",
        c: "ccc",
      },
      {
        b: "yyy",
        c: "zzz",
      },
    ],
  }
);
console.log(JSON.stringify(res, null, 4));
// => ['a[0].d', 'a[0].f', 'a[1].k', 'x']

Competition

You could try to use a missing-deep-keys, but it won’t work if your inputs have arrays. For posterity, the algorithm of it is quite wise: run lodash.difference against deep-keys-flattened stringified key schemas of both object and reference. However, deep-keys does not support arrays, so it’s not that easy.

In short, missing-deep-keys is for cases when you have only objects-within-objects. object-no-new-keys is for work with parsed HTML (AST’s) or JSON.

Changelog