Skip to main content

findKey()

findKey<T>(object, predicate): string | undefined

Returns the key of the first element predicate returns truthy for.

Type Parameters​

T: T extends Record<string, unknown>​

The type of the object.

Parameters​

object: T​

The object to inspect.

predicate: (value, key, object) => boolean​

The function invoked per iteration.

Returns: string | undefined​

The key of the matched element, or undefined if not found.

Since​

2.0.0

Performance​

O(n) where n is the number of own enumerable properties.

Also known as​

findFirst (Effect) · findKey (Lodash, es-toolkit) · ❌ (Remeda, Radashi, Ramda, Modern Dash, Antfu)

Example​

const users = {
  barney: { age: 36, active: true },
  fred: { age: 40, active: false },
  pebbles: { age: 1, active: true }
};

findKey(users, u => u.age < 40);
// => 'barney' (iteration order is not guaranteed)

findKey(users, u => u.active === false);
// => 'fred'

findKey(users, u => u.age > 100);
// => undefined

How it works?​

Returns the key of the first element that satisfies a predicate.

Search Process​

Not Found​

Use Cases​

Find User by Property 📌​

Find object key based on a value condition. Essential for reverse lookups in object maps.

import { findKey } from "@pithos/core/arkhe/object/find-key";

const users = {
  user_1: { name: "Alice", active: true },
  user_2: { name: "Bob", active: false },
  user_3: { name: "Charlie", active: true },
};

// Find first active user's key
const activeUserKey = findKey(users, (user) => user.active);
console.log(activeUserKey); // "user_1"

// Find user by name
const bobKey = findKey(users, (user) => user.name === "Bob");
console.log(bobKey); // "user_2"

Reverse Enum Lookup 📌​

Find enum key from its value. Critical for translating values back to identifiers.

import { findKey } from "@pithos/core/arkhe/object/find-key";

const HttpStatus = {
  OK: 200,
  CREATED: 201,
  BAD_REQUEST: 400,
  NOT_FOUND: 404,
  INTERNAL_ERROR: 500,
} as const;

function getStatusName(code: number): string {
  const name = findKey(HttpStatus, (value) => value === code);
  return name ?? "UNKNOWN";
}

console.log(getStatusName(200)); // "OK"
console.log(getStatusName(404)); // "NOT_FOUND"
console.log(getStatusName(999)); // "UNKNOWN"

Configuration Validation finding invalid entries​

Find the first invalid configuration entry. Important for debugging configuration issues.

import { findKey } from "@pithos/core/arkhe/object/find-key";

interface ConfigValue {
  value: unknown;
  required: boolean;
}

const config: Record<string, ConfigValue> = {
  apiKey: { value: "abc123", required: true },
  timeout: { value: null, required: true },
  debug: { value: false, required: false },
  endpoint: { value: "", required: true },
};

// Find first missing required config
const missingKey = findKey(
  config,
  (entry) => entry.required && (entry.value === null || entry.value === "")
);

if (missingKey) {
  throw new Error(`Missing required configuration: ${missingKey}`);
}
// Throws: "Missing required configuration: timeout"

Detect current platform from user agent patterns​

Find the matching platform key from a set of user agent patterns. Essential for platform detection utilities in CDK-style libraries.

const platformPatterns = {
  ios: (ua: string) => /iPhone|iPad|iPod/.test(ua),
  android: (ua: string) => /Android/.test(ua),
  windows: (ua: string) => /Windows/.test(ua),
  mac: (ua: string) => /Macintosh/.test(ua),
  linux: (ua: string) => /Linux/.test(ua) && !/Android/.test(ua),
};

const currentPlatform = findKey(platformPatterns, (test) => test(navigator.userAgent));
// => "mac" on macOS, "ios" on iPhone, etc.

applyPlatformStyles(currentPlatform ?? "unknown");

Find the active theme in a theme registry​

Locate the currently active theme key from a theme configuration map. Essential for design systems with multiple theme presets.

const themes = {
  light: { active: false, colors: { bg: "#fff", text: "#111" } },
  dark: { active: true, colors: { bg: "#1a1a1a", text: "#f0f0f0" } },
  highContrast: { active: false, colors: { bg: "#000", text: "#fff" } },
};

const activeThemeKey = findKey(themes, (theme) => theme.active);
// => "dark"

applyTheme(themes[activeThemeKey]);