Skip to main content

Helpers Package

The @kousta-ui/helpers package provides a small set of framework-agnostic utility functions.

🚀 Features​

  • Framework Agnostic: Works with any JavaScript environment
  • TypeScript First: Full TypeScript support with comprehensive type definitions
  • Zero Dependencies: Lightweight utilities with no external dependencies
  • Tree Shaking: Import only what you need
  • Battle Tested: Thoroughly tested for reliability
  • Performance Optimized: Efficient implementations for common operations

📦 Installation​

npm install @kousta-ui/helpers
# or
yarn add @kousta-ui/helpers
# or
pnpm add @kousta-ui/helpers

🎯 Available Helpers​

HelperPurposeCommon Use Cases
getNestedPropertyAccess nested object properties with string pathsForm data access, API response parsing
updateNestedPropertiesUpdate nested object properties immutablyState management, configuration updates

🎨 Quick Start​

// Import individual helpers (recommended for tree shaking)
import { getNestedProperty, updateNestedProperties } from "@kousta-ui/helpers";

// Object manipulation
const user = {
  personal: {
    first_name: "John",
    last_name: "Doe"
  },
  contact: {
    email: "john@example.com"
  }
};

// Get nested property with string concatenation
const fullName = getNestedProperty(user, "personal.first_name personal.last_name");
console.log(fullName); // "John Doe"

// Update nested property immutably
const updatedUser = updateNestedProperties(user, "contact.email", "newemail@example.com");

📊 Helper Categories​

Object Manipulation​

Helpers for working with complex nested objects:

DOM Utilities​

Helpers for browser DOM operations:

This package does not currently export DOM utilities.

🎯 When to Use These Helpers​

Use getNestedProperty when:​

  • Accessing deeply nested API response data
  • Working with complex configuration objects
  • Parsing form data with nested structures
  • Need string concatenation of multiple properties

Use updateNestedProperties when:​

  • Managing immutable state updates
  • Updating configuration objects
  • Modifying nested data without mutation
  • Working with React/Vue state management

🔧 TypeScript Support​

All helpers provide full TypeScript support:

import { getNestedProperty, updateNestedProperties } from "@kousta-ui/helpers";

// Typed object access
interface User {
  personal: {
    first_name: string;
    last_name: string;
  };
  contact: {
    email: string;
  };
}

const user: User = { /* ... */ };

// Get with type inference
const fullName: string = getNestedProperty(user, "personal.first_name personal.last_name");

// Update with type safety
const updatedUser: User = updateNestedProperties(user, "contact.email", "new@example.com");

🚀 Performance Considerations​

  • Optimized Algorithms: Efficient implementations for common operations
  • Minimal Memory Footprint: Zero dependencies and small bundle size
  • Immutable Operations: Safe for functional programming patterns
  • Tree Shaking Ready: Import only what you need

Performance Tip These helpers are designed to be performant out of the box, even with large nested objects.

🔄 Framework Integration Examples​

React Integration​

import React, { useState } from "react";
import { getNestedProperty, updateNestedProperties } from "@kousta-ui/helpers";

function UserProfile({ userData }) {
  const [user, setUser] = useState(userData);

  const handleEmailChange = (newEmail) => {
    const updatedUser = updateNestedProperties(user, "contact.email", newEmail);
    setUser(updatedUser);
  };

  const fullName = getNestedProperty(user, "personal.first_name personal.last_name");

  return (
    <div>
      <h1>{fullName}</h1>
      <input
        value={getNestedProperty(user, "contact.email")}
        onChange={(e) => handleEmailChange(e.target.value)}
      />
    </div>
  );
}

Vue Integration​

<template>
  <div>
    <h1>{{ fullName }}</h1>
    <input v-model="email" @input="updateEmail" />
  </div>
</template>

<script>
import { getNestedProperty, updateNestedProperties } from "@kousta-ui/helpers";

export default {
  data() {
    return {
      user: {
        personal: { first_name: "John", last_name: "Doe" },
        contact: { email: "john@example.com" }
      }
    };
  },
  computed: {
    fullName() {
      return getNestedProperty(this.user, "personal.first_name personal.last_name");
    },
    email: {
      get() {
        return getNestedProperty(this.user, "contact.email");
      },
      set(value) {
        this.user = updateNestedProperties(this.user, "contact.email", value);
      }
    }
  }
};
</script>

Node.js Integration​

const { getNestedProperty, updateNestedProperties } = require("@kousta-ui/helpers");

// Process configuration files
const config = {
  database: {
    host: "localhost",
    port: 5432,
    credentials: {
      username: "admin",
      password: "secret"
    }
  },
  server: {
    port: 3000
  }
};

// Access nested configuration
const dbHost = getNestedProperty(config, "database.host");
const dbCredentials = getNestedProperty(config, "database.credentials.username database.credentials.password");

// Update configuration immutably
const updatedConfig = updateNestedProperties(config, "server.port", 8080);

console.log("Database host:", dbHost);
console.log("Database credentials:", dbCredentials);

📚 Best Practices​

Do's​

  • ✅ Use helpers for their intended purpose
  • ✅ Leverage TypeScript for type safety
  • ✅ Use immutable operations for state management
  • ✅ Test edge cases with your specific data structures

Don'ts​

  • ❌ Don't mutate objects returned by helpers
  • ❌ Don't use with circular references in objects
  • ❌ Don't ignore TypeScript warnings
  • ❌ Don't use isNodeAChild in non-browser environments

📖 Next Steps​

🤝 Contributing​

We welcome contributions! Please see our contributing guidelines for details.

📄 License​

MIT © Ousta