populate Available since v0.9

The populate() allows you to populate a target object's properties with those from a source object. The values are shallow copied.

• Arguments
• Limit keys to populate
• Source Keys Callback
• When keys do not exist

Arguments

populate() accepts the following arguments:

• target: object

• source: object

• keys: PropertyKey | PropertyKey[] | SourceKeysCallback = '*' - The keys to select and copy from source object. If wildcard (*) given, then all properties from the source are selected. If a callback is given, then that callback must return key or keys to select from source.

• safe: boolean = true - When true, properties must exist in target (must be defined in target), before they are shallow copied.

Caution

The target object is mutated by this function.

Note

"Unsafe" properties are disregarded, regardless of what keys are given.

import { populate } from "@aedart/support/objects";

class Person {
    name = null;
    age = null;

    constructor(data) {
        populate(this, data);
    }
}

const instance = new Person({ name: 'Janine', age: 36 });
instance.name // Janine
instance.age // 36

Limit keys to populate

By default, all keys (*) from the source object are attempted populated into the target. You can limit what properties can be populated, by specifying what keys are allowed to be populated.

class Person {
    name = null;
    age = null;
    phone = null;

    constructor(data) {
        populate(this, data, [ 'name', 'age' ]);
    }
}

const instance = new Person({ name: 'Janine', age: 36, phone: '555 555 555' });
instance.name // Janine
instance.age // 36
instance.phone // null

Source Keys Callback

If you need a more advanced way to determine what keys to populate, then you can specify a callback as the keys argument.

populate(target, source, (source, target) => {
    if (Reflect.has(source, 'phone') && Reflect.has(target, 'phone')) {
        return [ 'name', 'age', 'phone' ];
    }

    return [ 'name', 'age' ];
});

When keys do not exist

When the safe argument is set to true (default behavior), and a property key does not exist in the target object, then a TypeError is thrown.

class Person {
    name = null;
    age = null;

    constructor(data) {
        populate(this, data, [ 'name', 'age', 'phone' ]);
    }
}

const instance = new Person({
    name: 'Janine',
    age: 36,
    phone: '555 555 555'
}); // TypeError - phone does not exist in target 

However, if a requested key does not exist in the source object, then a TypeError is thrown regardless of the safe argument value.

class Person {
    name = null;
    age = null;

    constructor(data) {
        populate(this, data, [ 'name', 'age', 'phone' ], false);
    }
}

const instance = new Person({
    name: 'Janine',
    age: 36
}); // TypeError - phone does not exist in source