Object Utilities

/**
 * High performance object assignment
 * @param target - Target object to assign properties to
 * @param objects - Source object(s) to assign from
 * @returns Modified target object
 */
function assign(target: any, objects: any | any[]): any;

import { assign } from "utility";

// Single source object
const target1 = { a: 1 };
const result1 = assign(target1, { b: 2, c: 3 });
// Result: { a: 1, b: 2, c: 3 }

// Multiple source objects
const target2 = { x: 'original' };
const result2 = assign(target2, [
  { y: 'first' },
  { z: 'second' },
  { x: 'overwritten' }
]);
// Result: { x: 'overwritten', y: 'first', z: 'second' }

// With null/undefined sources (safely ignored)
const target3 = { safe: true };
const result3 = assign(target3, [null, { added: 'value' }, undefined]);
// Result: { safe: true, added: 'value' }

// Modifies target object
const original = { keep: 'me' };
assign(original, { new: 'property' });
console.log(original); // { keep: 'me', new: 'property' }

/**
 * Check if object has own property
 * @param obj - Object to check
 * @param prop - Property name to check
 * @returns True if object has own property
 */
function has(obj: object, prop: string): boolean;

import { has } from "utility";

// Basic property check
const obj = { name: 'test', value: 42 };
const hasName = has(obj, 'name');
// Result: true

const hasAge = has(obj, 'age');
// Result: false

// Inherited properties
class Parent {
  parentProp = 'inherited';
}
class Child extends Parent {
  childProp = 'own';
}

const child = new Child();
const hasOwn = has(child, 'childProp');
// Result: true

const hasInherited = has(child, 'parentProp');
// Result: false (inherited, not own)

// Safe checking
const hasToString = has(obj, 'toString');
// Result: false (inherited from Object.prototype)

/**
 * Get all enumerable own property names
 * @param obj - Object to inspect
 * @param ignoreNull - Ignore null, undefined, or NaN properties
 * @returns Array of enumerable property names
 */
function getOwnEnumerables(obj: any, ignoreNull?: boolean): Array<string>;

import { getOwnEnumerables } from "utility";

// Basic enumerable properties
const obj1 = { a: 1, b: 2, c: 3 };
const props1 = getOwnEnumerables(obj1);
// Result: ['a', 'b', 'c']

// With null/undefined values
const obj2 = { 
  valid: 'value',
  nullProp: null,
  undefinedProp: undefined,
  nanProp: NaN,
  zeroProp: 0
};

const allProps = getOwnEnumerables(obj2);
// Result: ['valid', 'nullProp', 'undefinedProp', 'nanProp', 'zeroProp']

const filteredProps = getOwnEnumerables(obj2, true);
// Result: ['valid', 'zeroProp']

// Non-enumerable properties ignored
const obj3 = { visible: 'yes' };
Object.defineProperty(obj3, 'hidden', {
  value: 'no',
  enumerable: false
});

const enumerables = getOwnEnumerables(obj3);
// Result: ['visible'] (hidden not included)

// Array and non-object handling
const arrProps = getOwnEnumerables([1, 2, 3]);
// Result: [] (arrays return empty)

const nullProps = getOwnEnumerables(null);
// Result: [] (null returns empty)

/**
 * Generate a clean object with no constructor or __proto__
 * @param obj - Optional initial object to copy properties from
 * @returns Clean object without prototype
 */
function map(obj?: any): Record<string, any>;

import { map } from "utility";

// Empty clean object
const clean = map();
console.log(clean.constructor); // undefined
console.log(clean.__proto__);   // null
console.log(clean.toString);    // undefined

// Clean object with initial data
const cleanWithData = map({ name: 'test', id: 123 });
// Result: clean object with name and id properties, no prototype

// Safe property storage
const safeMap = map();
safeMap['__proto__'] = 'safe';
safeMap['constructor'] = 'safe';
safeMap['toString'] = 'safe';
// These are just regular properties, not special prototype properties

// Use case: configuration objects
function createConfig(userConfig: any) {
  const config = map({
    // Default configuration
    timeout: 5000,
    retries: 3,
    debug: false
  });
  
  // Safely add user config
  if (userConfig) {
    for (const key in userConfig) {
      config[key] = userConfig[key];
    }
  }
  
  return config;
}

const userConfig = createConfig({ timeout: 10000, debug: true });
// Result: clean object with merged configuration