or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-object-assign

ES6 spec-compliant Object.assign shim with ES3 compatibility and Symbol support.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/object.assign@4.1.x

To install, run

npx @tessl/cli install tessl/npm-object-assign@4.1.0

index.mddocs/

object.assign

object.assign is an ES6 spec-compliant Object.assign shim that works in ES3-supported environments and properly handles Symbol properties in ES6 environments. It implements the es-shim API interface and provides multiple usage patterns including polyfill mode, shimming mode, and direct implementation access.

Package Information

  • Package Name: object.assign
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install object.assign

Core Imports

var assign = require('object.assign');

For direct access to specific components:

var assign = require('object.assign');
var getPolyfill = require('object.assign/polyfill');
var shim = require('object.assign/shim');
var implementation = require('object.assign/implementation');

Auto-shimming (installs Object.assign globally if needed):

require('object.assign/auto');

Basic Usage

var assign = require('object.assign');

// Basic usage
var target = { a: true };
var source1 = { b: true };
var source2 = { c: true };

var result = assign(target, source1, source2);
// target is now { a: true, b: true, c: true }
// result === target (returns the target object)

// Using the polyfill (recommended)
var assign = require('object.assign').getPolyfill();
var result = assign({ a: 1 }, { b: 2 }, { c: 3 });
// result: { a: 1, b: 2, c: 3 }

Capabilities

Main Assignment Function

The primary bound function that implements Object.assign functionality with automatic polyfill selection.

/**
 * Copies all enumerable own properties from one or more source objects to a target object
 * @param {any} target - The target object to copy properties to
 * @param {...any} sources - One or more source objects to copy properties from
 * @returns {Object} The target object with copied properties
 * @throws {TypeError} If target is null or undefined
 */
function assign(target, ...sources);

Usage Examples:

var assign = require('object.assign');

// Multiple sources
var target = { a: true };
var source1 = { b: true };
var source2 = { c: true };
assign(target, source1, source2);
// target is now { a: true, b: true, c: true }

// Property overwriting
var target = { a: 1, b: 2 };
var source = { b: 3, c: 4 };
assign(target, source);
// target is now { a: 1, b: 3, c: 4 }

// Non-enumerable properties are ignored
var source = {};
Object.defineProperty(source, 'hidden', { value: 'secret', enumerable: false });
var result = assign({}, source);
// result: {} (hidden property not copied)

Polyfill Detection

Returns the best available Object.assign implementation (native or shim).

/**
 * Returns native Object.assign if compliant, otherwise returns the shim implementation
 * @returns {Function} The best available assign function
 */
assign.getPolyfill();

Usage Examples:

var assign = require('object.assign').getPolyfill();
// Use the best available implementation
var result = assign({ a: 1 }, { b: 2 });

// Or access directly
var getPolyfill = require('object.assign/polyfill');
var assign = getPolyfill();

Direct Implementation Access

Direct access to the ES6-compliant Object.assign implementation.

/**
 * Direct access to the ES6-compliant Object.assign implementation
 * @param {any} target - The target object
 * @param {...any} sources - Source objects
 * @returns {Object} The target object with copied properties
 * @throws {TypeError} If target is null or undefined
 */
assign.implementation;

Usage Examples:

var implementation = require('object.assign').implementation;
// or
var implementation = require('object.assign/implementation');

var result = implementation({ a: 1 }, { b: 2 });

Shimming Functionality

Installs the polyfill as Object.assign if not present or if the native version is faulty.

/**
 * Conditionally installs Object.assign polyfill
 * @returns {Function} The installed polyfill function
 */
assign.shim();

Usage Examples:

// Install the shim
var shimmedAssign = require('object.assign').shim();
// Object.assign is now available globally (if it wasn't compliant before)

// Or use directly
var shim = require('object.assign/shim');
var assign = shim();

// Example showing shimming behavior
delete Object.assign; // Remove native implementation
var shimmedAssign = require('object.assign').shim();
console.log(Object.assign === shimmedAssign); // true

// With compliant native implementation
var shimmedAssign = require('object.assign').shim();
console.log(Object.assign === shimmedAssign); // true (uses native)

Advanced Usage Patterns

ES6 Environments with Symbols

var assign = require('object.assign').getPolyfill();

// Symbol properties are properly handled
var sym1 = Symbol('prop1');
var sym2 = Symbol('prop2');

var source = {
  normalProp: 'value',
  [sym1]: 'symbol value 1',
  [sym2]: 'symbol value 2'
};

var target = assign({}, source);
// target has all properties, including Symbol properties

Polyfill vs Shim vs Implementation

// Polyfill: Returns best available (native or shim)
var polyfill = require('object.assign').getPolyfill();

// Shim: Installs globally if needed, returns function
var shim = require('object.assign').shim();

// Implementation: Always uses the shim implementation
var implementation = require('object.assign').implementation;

// Auto: Automatically shims globally on require
require('object.assign/auto'); // Object.assign is now available

Browser Compatibility

The package works in all browser environments. For maximum compatibility, use the polyfill pattern:

var assign = require('object.assign').getPolyfill();
// This automatically uses native Object.assign if available and compliant

Error Handling

The assign function throws TypeError in specific cases:

var assign = require('object.assign');

try {
  assign(null, { a: 1 }); // Throws TypeError
} catch (e) {
  console.log(e.message); // "target must be an object"
}

try {
  assign(undefined, { a: 1 }); // Throws TypeError  
} catch (e) {
  console.log(e.message); // "target must be an object"
}

// Non-object targets are coerced to objects (no error)
var result = assign(true, { a: 1 });
console.log(typeof result); // "object"
console.log(Boolean.prototype.valueOf.call(result)); // true
console.log(result.a); // 1

Type Definitions

/**
 * Main assign function signature
 */
interface AssignFunction {
  (target: any, ...sources: any[]): any;
  getPolyfill(): AssignFunction;
  implementation: AssignFunction;
  shim(): AssignFunction;
}

/**
 * Polyfill getter function
 */
interface GetPolyfillFunction {
  (): AssignFunction;
}

/**
 * Shim installer function  
 */
interface ShimFunction {
  (): AssignFunction;
}