IonIon
Packages
  • next
  • current
Changelog
GitHub
Packages
  • next
  • current
Changelog
GitHub
  • Version 0.x

    • Release Notes
    • Upgrade Guide
    • Contribution Guide
    • Security Policy
    • Code of Conduct
    • Origin
  • Packages

    • Introduction
    • Container

      • Introduction
      • Prerequisites
      • How to install
      • Container Instance
      • Bindings
      • Dependencies
      • Resolving
      • Contextual Bindings
    • Contracts

      • Introduction
      • How to install
    • Support

      • Introduction
      • How to install
      • Arrays

        • About Arrays
        • Includes All
        • Includes Any
        • Is Array Like
        • Is Concat Spreadable
        • Is Safe Array Like
        • Is Typed Array
        • Merge
      • Concerns

        • About Concerns
        • Prerequisites
        • Concern Class
        • Using Concerns
        • Aliases
        • Conflict Resolution
        • Booting
        • Hooks
        • Edge Cases
        • JSDoc
      • Exceptions

        • About Exceptions
        • Configure Custom Error
        • Configure Stack Trace
        • Get Error Message
        • Custom Errors
      • Facades

        • About Facades
      • Meta

        • About Meta
        • Prerequisites
        • Supported Elements
        • Set & Get
        • Inheritance
        • Outside Changes
        • TC39 Proposal
        • Target Meta
      • Mixins

        • About Mixins
        • New Mixin
        • Apply Mixins
        • Instanceof
        • Inheritance
        • Onward
      • Object

        • About Objects
        • Forget
        • Forget All
        • Get
        • Has
        • Has All
        • Has Any
        • Has Unique ID
        • Is Cloneable
        • Is Populatable
        • Isset
        • Merge
        • Populate
        • Set
        • Unique ID
      • Reflections

        • About reflections
        • Assert Has Prototype Prop.
        • Class Looks Like
        • Class Own Keys
        • Get All Parents Of Class
        • Get Class Prop. Descriptor
        • Get Class Prop. Descriptors
        • Get Constructor Name
        • Get Name Or Desc. Tag
        • Get Parent Of Class
        • Has All Methods
        • Has Method
        • Has Prototype Property
        • Is Callable
        • Is Class Constructor
        • Is Class Method Reference
        • Is Constructor
        • Is Key Safe
        • Is Key Unsafe
        • Is Method
        • Is Subclass
        • Is Subclass Or Looks Like
        • Is WeakKind
      • Misc

        • About Misc.
        • Desc. Tag
        • Empty
        • Is Key
        • Is Primitive
        • Is Property Key
        • Isset
        • Merge Keys
        • To Weak Ref.
      • Callback Wrapper
    • Vuepress Utils

      • Introduction
      • How to install
      • Navigation

        • Archive
      • Plugins

        • Last Updated
      • Components

        • Version Disclaimer
    • XYZ (test package)

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 
Edit page
Last Updated:
Contributors: alin
Prev
Merge
Next
Set