@devlander/utils

Devlander JavaScript Utilities Collection

📊 View Detailed Coverage Report

Enhance your JavaScript projects with the Devlander JavaScript Utils Collection—a meticulously curated set of utility functions to streamline your coding workflow. Join our vibrant community on Discord, engage in discussions on GitHub, and stay updated with our latest streams on Twitch. Boost your project's efficiency today!

📈 Package Statistics

• 📦 61+ Published Versions - Continuously maintained and updated
• 🔧 100+ Utility Functions - Comprehensive utility library
• 📚 15+ Categories - Organized by functionality
• 🌐 4 Platform Support - React, Next.js, React Native, Node.js
• ⚡ Zero Dependencies - Lightweight and fast
• 🛡️ 87.37% Test Coverage - High reliability and quality

---

📚 New to contributing? Start here!

If you're new to open source, npm packages, or TypeScript, please reference the step-by-step Medium articles linked below. These guides will walk you through everything from Git basics to advanced package publishing, testing, and code style:

• What is Git? A Complete Beginner's Guide to Version Control and GitHub
• npm Packages: What They Are, Where They Came From, and When to Use Them
• How to Plan and Structure Your npm Package for Success
• How to Build Your First npm Package: Validators
• How to Add TypeScript to Your npm Package
• Testing and Deploying Your npm Package with Jest and Unit Testing
• Setting Up ESLint and Prettier for Your npm Package

These articles are highly recommended for all contributors!

---

About This Project

The Devlander JavaScript Utils Collection is an evolving library of JavaScript utilities developed by Landon Johnson. These utilities address everyday coding tasks, reducing the need for repetitive code and enhancing productivity. Open to community input for naming and improvements, this project aims to be a go-to resource for developers.

Utilities Overview

JSON Utilities

• isDeepEqual(obj1, obj2): Deeply compares two objects for equality.
• isJson(value): Validates if a value is a legitimate JSON string or object.
• mergeObjects(oldObj, newObj): Merges two nested objects into one.

Filter Utilities

• hasItemByLetterAndFilter(array, key, value): Filters various objects based on a specified letter and additional filter criteria.

Conversion Utilities

• abbreviateNumber(value): Abbreviates numbers with appropriate suffixes (k, m, b, t) for readability.

Timeout Utilities

• waitFor(value, timeUnits?: ms | s, logDuration?: boolean): Delays the execution of a function by a specified time.

Quick Start and Documentation

Dive into our utility functions with ease. Each utility is documented with parameters, return values, and usage examples to get you started quickly. Whether you're merging objects, checking JSON validity, or filtering data, our collection is designed to enhance your development process with minimal effort.

• Installation: npm install @devlander/utils
• Usage: Import utilities as needed in your project. Example usage is provided for each function to illustrate its application.

Changelog

For a full list of changes, check the CHANGELOG.md file.

Engage and Contribute

We welcome contributions, feedback, and suggestions! Join our discussions on GitHub, or connect with us on Discord and Twitter. Your input helps us improve the Devlander JavaScript Utils Collection for the developer community.

Before contributing, please read the Medium articles above for step-by-step guidance on Git, npm, TypeScript, testing, and code style.

Become a Sponsor!

🧪 Cross-Platform Testing

This package includes comprehensive cross-platform testing to ensure compatibility across different environments:

Automated Testing

• Unit Tests: Run with yarn test
• Cross-Platform Tests: Run with yarn test:examples
• Full Pre-Publish Check: Run with yarn prepublishOnly

Example Apps

The /examples directory contains minimal test apps for each platform:

• React (examples/react/) - Vite-based React app
• Next.js (examples/nextjs/) - Next.js app with TypeScript
• React Native (examples/react-native/) - Expo app
• Node.js (examples/node/) - Node.js with TypeScript

How It Works

1. Build & Pack: Creates a tarball (exactly like npm would deliver)
2. Install: Installs the tarball into each example app
3. Test: Runs tests in each environment to verify imports work
4. Validate: Ensures your package works in real-world scenarios

This guarantees that your package can be installed and used successfully in React, Next.js, React Native, and Node.js projects.

🏆 Quality Assurance

Test Statistics

• ✅ 298 Tests Passed - Comprehensive test coverage across all utilities
• ✅ 51 Test Suites - Organized testing for each utility category
• ✅ 87.37% Code Coverage - High coverage ensures reliability
• ✅ 4 Platforms Supported - Cross-platform compatibility verified
• ✅ 0 Failing Tests - All tests pass consistently

Quality Metrics

• TypeScript Strict Mode - Full type safety with strict configuration
• ESLint + Prettier - Consistent code style and quality
• Jest Testing Framework - Industry-standard testing
• Conventional Commits - Automated changelog generation
• GitHub Actions CI/CD - Automated testing and deployment
• Cross-Platform Validation - Works in React, Next.js, React Native, Node.js

Reliability Features

• Zero Dependencies - Lightweight and fast
• Tree Shaking Support - Only import what you use
• Multiple Build Formats - CJS, ESM, and UMD support
• TypeScript Definitions - Full type support included
• Comprehensive Documentation - Auto-generated with TypeDoc

🚀 Release Process

This project uses an automated release process with GitHub Actions. Here's how it works:

Automatic Release Workflow

1. Create a new version: Use one of the release commands:

   # Standard release (with version checking)
   yarn release:patch:check  # 1.0.1 → 1.0.2
   yarn release:minor:check  # 1.0.1 → 1.1.0  
   yarn release:major:check  # 1.0.1 → 2.0.0
   
   # Quick release (no version checking)
   yarn release:patch  # 1.0.1 → 1.0.2
   yarn release:minor  # 1.0.1 → 1.1.0
   yarn release:major  # 1.0.1 → 2.0.0

2. What happens automatically:

   • ✅ Version is incremented in package.json
   • ✅ Version check: Verifies the version doesn't already exist on npm
   • ✅ Git tag is created and pushed
   • ✅ GitHub Action triggers on tag push
   • ✅ Smart publishing: Only publishes if version is new
   • ✅ Changelog is generated from conventional commits
   • ✅ Package is published to npm (if new version)
   • ✅ GitHub release is created with changelog notes

Manual Release (Alternative)

If you prefer manual control:

# Generate changelog and create release
yarn release

Commit Convention

This project uses Conventional Commits for automatic changelog generation:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• style: - Code style changes
• refactor: - Code refactoring
• test: - Test changes
• chore: - Maintenance tasks

How Version Detection Works

The release process uses dual-layer version checking:

1. Local Check (before pushing tag):

   npm view @devlander/utils@1.0.2 version

   • If version exists → Stops and shows warning
   • If version is new → Proceeds with tag push

2. GitHub Action Check (after tag push):

   • Extracts version from git tag (v1.0.2 → 1.0.2)
   • Checks npm registry for existing version
   • Only publishes if version is new
   • Creates GitHub release regardless

Current Status

• Latest npm version: 1.0.0 (published 3 days ago)
• Current package version: 1.0.1 (ready for next release)
• GitHub Actions: ✅ Configured and working
• Auto-release: ✅ Enabled with changelog generation
• Version checking: ✅ Smart publishing (only new versions)