getObjectKeys

Extracts object keys with optional filtering and sorting capabilities. Retrieves all enumerable own property keys from an object, with support for excluding specific keys and applying custom sorting logic. Provides efficient key filtering and transformation for object manipulation operations.

Signature

const getObjectKeys: <Type extends Dictionary>(object: Type | undefined, omit?: Set<keyof Type> | Array<keyof Type>, sort?: Fn<[a: keyof Type, b: keyof Type], number>) => Array<keyof Type>

Parameters

Name	Type	Description
object	-	Object to extract keys from (undefined returns empty array)
omit	-	Set or array of keys to exclude from the result (optional)
sort	-	Comparison function for sorting keys (optional)

Returns

Array of filtered and optionally sorted object keys

Examples

Basic key extraction

import { getObjectKeys } from '@winglet/common-utils';

// Simple object keys
const user = { id: 1, name: 'John', email: 'john@example.com' };
console.log(getObjectKeys(user)); // ['id', 'name', 'email']

// Empty object
console.log(getObjectKeys({})); // []

// Undefined input handling
console.log(getObjectKeys(undefined)); // []

Key filtering with exclusion

const config = {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
  retries: 3,
  debug: true,
  secretKey: 'hidden'
};

// Exclude sensitive or internal keys
const publicKeys = getObjectKeys(config, ['secretKey', 'debug']);
console.log(publicKeys); // ['apiUrl', 'timeout', 'retries']

// Using Set for better performance with many exclusions
const excludeSet = new Set(['secretKey', 'debug', 'internal']);
const filteredKeys = getObjectKeys(config, excludeSet);
console.log(filteredKeys); // ['apiUrl', 'timeout', 'retries']

// Exclude all keys (edge case)
const allKeys = Object.keys(config);
console.log(getObjectKeys(config, allKeys)); // []

Key sorting and ordering

const unorderedData = {
  zebra: 'last',
  apple: 'first',
  banana: 'middle',
  cherry: 'second'
};

// Alphabetical sorting
const alphabetical = getObjectKeys(unorderedData, undefined, (a, b) => a.localeCompare(b));
console.log(alphabetical); // ['apple', 'banana', 'cherry', 'zebra']

// Reverse alphabetical
const reverseAlpha = getObjectKeys(unorderedData, undefined, (a, b) => b.localeCompare(a));
console.log(reverseAlpha); // ['zebra', 'cherry', 'banana', 'apple']

// Custom sorting by length
const byLength = getObjectKeys(unorderedData, undefined, (a, b) => a.length - b.length);
console.log(byLength); // ['zebra', 'apple', 'banana', 'cherry']

Combined filtering and sorting

const database = {
  users_table: 'user data',
  orders_table: 'order data',
  products_table: 'product data',
  temp_cache: 'temporary',
  debug_log: 'debug info',
  config_settings: 'configuration'
};

// Get table names only, sorted alphabetically
const tableKeys = getObjectKeys(
  database,
  ['temp_cache', 'debug_log'], // exclude non-table keys
  (a, b) => a.localeCompare(b)   // sort alphabetically
);
console.log(tableKeys); // ['config_settings', 'orders_table', 'products_table', 'users_table']

Working with complex objects

interface UserProfile {
  id: number;
  personalInfo: { name: string; age: number };
  preferences: { theme: string; notifications: boolean };
  _internal: string;
  __debug: boolean;
}

const profile: UserProfile = {
  id: 123,
  personalInfo: { name: 'Alice', age: 30 },
  preferences: { theme: 'dark', notifications: true },
  _internal: 'system',
  __debug: false
};

// Get public API keys (exclude internal/debug)
const publicKeys = getObjectKeys(
  profile,
  ['_internal', '__debug'],
  (a, b) => a.localeCompare(b)
);
console.log(publicKeys); // ['id', 'personalInfo', 'preferences']

Playground

import { getObjectKeys } from '@winglet/common-utils';

// Simple object keys
const user = { id: 1, name: 'John', email: 'john@example.com' };
console.log(getObjectKeys(user)); // ['id', 'name', 'email']

// Empty object
console.log(getObjectKeys({})); // []

// Undefined input handling
console.log(getObjectKeys(undefined)); // []

Notes

Performance Characteristics:

• Time Complexity: O(n) for extraction, O(n log n) if sorting is applied
• Space Complexity: O(n) for result array, O(k) for omit Set conversion
• Optimizations: Early array allocation, efficient filtering loop

Performance Benchmarks (Node.js v18, typical hardware):

• Small objects (< 100 keys): ~0.01ms
• Medium objects (< 1000 keys): ~0.1ms
• Large objects (< 10000 keys): ~2ms
• With sorting (1000 keys): ~0.3ms
• vs Object.keys(): ~10% overhead for filtering, ~50% for sorting
• vs Lodash.keys(): ~2x faster with better type safety

Error Cases and Edge Conditions:

• Null/Undefined Input: Returns empty array (safe default)
• Non-Object Input: Attempts Object.keys() - may throw TypeError
• Empty Omit Array: No performance penalty, all keys returned
• All Keys Omitted: Returns empty array efficiently
• Duplicate Keys in Omit: Set conversion handles automatically
• Non-String Keys: Object.keys() converts to strings automatically

Key Extraction Strategy:

• Uses Object.keys() to get enumerable own properties only
• Converts omit array to Set automatically for O(1) lookup performance
• Maintains original key order when no sorting is applied
• Preserves type information through generic constraints

Filtering Behavior:

• Array Omit: Converted to Set internally for better lookup performance
• Set Omit: Used directly for O(1) membership testing
• Empty Omit: No filtering applied, all keys returned
• Complete Omit: Returns empty array if all keys excluded

Sorting Behavior:

• Applied after filtering to reduce sort operations
• Uses native Array.sort() with provided comparator
• Maintains stable sort for equal elements
• No sorting applied if comparator is undefined

Use Cases:

• Object transformation and mapping operations
• API response filtering and sanitization
• Configuration management and validation
• Dynamic form field generation
• Object serialization with selective fields
• Database query field selection