Sort Objects Array

A lightweight, type-safe TypeScript library for sorting arrays of objects by any property, including deeply nested properties using dot notation.

Features

• Type-safe - Full TypeScript support with autocomplete for nested paths
• Dot notation - Sort by deeply nested properties ("user.profile.name")
• Case-insensitive strings - String comparisons ignore case by default
• Multiple types - Supports strings, numbers, and booleans
• Null-safe - Automatically filters out null/undefined values
• Immutable - Never mutates the original array
• Performant - Optimized with value caching
• Zero dependencies - Lightweight and fast

Installation

npm install sort-objects-list

yarn add sort-objects-list

pnpm add sort-objects-list

Quick Start

import { sort } from "sort-objects-list";

const users = [
  { name: "John", age: 30 },
  { name: "Alice", age: 25 },
  { name: "Bob", age: 35 }
];

// Sort by name (ascending)
const sorted = sort(users, "name");
// [{ name: "Alice", ... }, { name: "Bob", ... }, { name: "John", ... }]

// Sort by age (descending)
const sortedByAge = sort(users, "age", false);
// [{ name: "Bob", age: 35 }, { name: "John", age: 30 }, { name: "Alice", age: 25 }]

Usage Examples

Basic Sorting

import { sort } from "sort-objects-list";

const products = [
  { id: 3, name: "Laptop", price: 999 },
  { id: 1, name: "Mouse", price: 25 },
  { id: 2, name: "Keyboard", price: 75 }
];

// Sort by price (ascending)
const byPrice = sort(products, "price");
// [{ id: 1, price: 25 }, { id: 2, price: 75 }, { id: 3, price: 999 }]

// Sort by name (descending)
const byName = sort(products, "name", false);
// [{ name: "Mouse" }, { name: "Laptop" }, { name: "Keyboard" }]

Nested Properties (Dot Notation)

const employees = [
  { id: 1, user: { profile: { name: "Charlie", age: 28 } } },
  { id: 2, user: { profile: { name: "Alice", age: 32 } } },
  { id: 3, user: { profile: { name: "Bob", age: 25 } } }
];

// Sort by nested name property
const sorted = sort(employees, "user.profile.name");
// [{ id: 2, user: { profile: { name: "Alice" } } }, ...]

// TypeScript autocomplete works for nested paths!
sort(employees, "user.profile."); // Shows: name | age

String Sorting (Case-Insensitive)

const items = [{ name: "banana" }, { name: "Apple" }, { name: "CHERRY" }];

const sorted = sort(items, "name");
// [{ name: "Apple" }, { name: "banana" }, { name: "CHERRY" }]

Boolean Sorting

const tasks = [
  { task: "Buy milk", completed: true },
  { task: "Clean room", completed: false },
  { task: "Study", completed: true }
];

// Sort by completion status (false < true)
const sorted = sort(tasks, "completed");
// [{ completed: false }, { completed: true }, { completed: true }]

Handling Null and Undefined

const data = [
  { id: 1, name: "Alice" },
  { id: 2, name: null },
  { id: 3, name: "Bob" },
  { id: 4 } // name is undefined
];

const sorted = sort(data, "name");
// Only returns items with valid names:
// [{ id: 1, name: "Alice" }, { id: 3, name: "Bob" }]

Edge Cases

// Empty arrays
sort([], "name"); // []

// Single item
sort([{ name: "Solo" }], "name"); // [{ name: "Solo" }]

// All values filtered out
sort([{ name: null }, { name: null }], "name"); // []

API Reference

sort<T>(objectArray, key, ascending?)

Sorts an array of objects by a specified key.

Parameters

| Parameter | Type | Default | Description | | ------------- | ------------------- | ------- | -------------------------------------------------------- | | objectArray | T[] | - | The array of objects to sort | | key | Path<T> \| string | - | The property key to sort by (supports dot notation) | | ascending | boolean | true | Sort order: true for ascending, false for descending |

Returns

T[] - A new sorted array (original array is not modified)

Type Safety

The key parameter is fully type-safe with autocomplete support:

const users = [{ profile: { name: "Alice", age: 25 } }];

sort(users, "profile.name"); // ✓ Valid - autocomplete suggests this
sort(users, "profile.invalid"); // ✗ TypeScript error

Advanced Usage

Error Handling

The library throws a TypeError when trying to sort by non-primitive values:

const data = [{ id: 1, metadata: { nested: "value" } }];

// This throws TypeError - can't sort by object
sort(data, "metadata"); // ✗ Error

// This works - sorting by the nested primitive
sort(data, "metadata.nested"); // ✓ Works

Mixed Types

If the array contains mixed types for the same property, they are sorted by type name for consistency:

const mixed = [{ value: "string" }, { value: 42 }, { value: true }];

sort(mixed, "value"); // Sorted by type, then value

Testing

The library has comprehensive test coverage:

yarn test

Test coverage includes:

• Basic sorting (ascending/descending)
• String, number, and boolean types
• Nested property access
• Null/undefined handling
• Edge cases (empty arrays, single items)
• Error handling
• Mixed type scenarios

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Derek Oware

• Email: [email protected]
• Website: https://oware.me
• GitHub: @Dchole

Support

If you find this library helpful, consider starring the project on GitHub or buying me a coffee!

Acknowledgments

• Built with TypeScript for maximum type safety
• Inspired by the need for simple, type-safe array sorting

Changelog

1.0.0

• Initial release with full TypeScript support
• Dot notation for nested properties
• Case-insensitive string sorting
• Null/undefined filtering
• Boolean and number support
• Comprehensive test coverage