Object/Since 1.38.0

defaults

Fills undefined properties in an object with values from a source object.

defaults(object, source):T & Omit<U, keyof T>

Parameters

objectTrequired

The target object whose undefined properties should receive default values.

sourceUrequired

The source object containing default values.

Returns

T & Omit<U, keyof T>

Returns a new object containing the properties of object, with undefined properties filled from source.

Examples

Basic usage

Missing values are filled from the source object.

TypeScript

const result = defaults(
  {
    name: "Alice",
    age: undefined,
  },
  {
    age: 25,
    active: true,
  },
);

console.log(result);
// {
//   name: "Alice",
//   age: 25,
//   active: true
// }

Existing values are preserved

An existing defined value is not replaced by the source value.

TypeScript

const result = defaults(
  {
    name: "Alice",
    age: 30,
  },
  {
    name: "Bob",
    age: 25,
  },
);

console.log(result);
// {
//   name: "Alice",
//   age: 30
// }

Undefined values

Only properties whose current value is undefined receive the source value.

TypeScript

const result = defaults(
  {
    a: undefined,
    b: 0,
    c: false,
    d: "",
    e: null,
  },
  {
    a: 1,
    b: 2,
    c: true,
    d: "default",
    e: "value",
  },
);

console.log(result);
// {
//   a: 1,
//   b: 0,
//   c: false,
//   d: "",
//   e: null
// }

Additional properties

Properties that exist only in the source object are added to the result.

TypeScript

const result = defaults(
  {
    name: "Alice",
  },
  {
    age: 25,
    active: true,
  },
);

console.log(result);
// {
//   name: "Alice",
//   age: 25,
//   active: true
// }

Source undefined values

If a missing property in source is itself undefined, that undefined value is assigned.

TypeScript

const result = defaults(
  {
    name: undefined,
  },
  {
    name: undefined,
  },
);

console.log(result.name);
// undefined

Nested objects

The function performs a shallow operation and does not merge nested objects.

TypeScript

const result = defaults(
  {
    settings: {
      theme: "dark",
    },
  },
  {
    settings: {
      language: "en",
    },
  },
);

console.log(result);
// {
//   settings: {
//     theme: "dark"
//   }
// }

Returns a new object

The original object is not modified because the function starts with an object spread.

TypeScript

const original = {
  name: "Alice",
  age: undefined,
};

const result = defaults(original, {
  age: 25,
});

console.log(result);
// { name: "Alice", age: 25 }

console.log(original.age);
// undefined

console.log(result === original);
// false

Own enumerable source properties

Only enumerable own string-keyed properties from source are processed.

TypeScript

const source = {
  age: 25,
};

Object.defineProperty(source, "hidden", {
  value: true,
  enumerable: false,
});

const result = defaults(
  {
    age: undefined,
    hidden: undefined,
  },
  source,
);

console.log(result);
// {
//   age: 25,
//   hidden: undefined
// }

Built with@cyref/js·Official documentation