CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-natural-compare-lite

Compare strings containing a mix of letters and numbers in the way a human being would in sort order.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Natural Compare Lite

Natural Compare Lite provides natural string comparison that handles mixed letters and numbers in human-readable sort order. It sorts strings the way humans expect, treating numbers within strings numerically rather than lexicographically (e.g., "img10.png" comes after "img2.png", not before).

Package Information

  • Package Name: natural-compare-lite
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install natural-compare-lite

Core Imports

CommonJS (default):

const naturalCompare = require("natural-compare-lite");

ES modules (with bundler/transpiler):

import naturalCompare from "natural-compare-lite";

Browser (global):

<script src="path/to/natural-compare-lite"></script>
<script>
  // Access via String.naturalCompare when CommonJS is unavailable
  const naturalCompare = String.naturalCompare;
</script>

Basic Usage

const naturalCompare = require("natural-compare-lite");

// Simple array sorting
const files = ["z1.doc", "z10.doc", "z17.doc", "z2.doc", "z23.doc", "z3.doc"];
files.sort(naturalCompare);
// Result: ["z1.doc", "z2.doc", "z3.doc", "z10.doc", "z17.doc", "z23.doc"]

// Case insensitive sorting
const names = ["Alice", "bob", "Charlie"];
names.sort((a, b) => naturalCompare(a.toLowerCase(), b.toLowerCase()));

// Object sorting by property
const items = [
  { street: "350 5th Ave", room: "A-1021" },
  { street: "350 5th Ave", room: "A-21046-b" }
];
items.sort((a, b) => 
  naturalCompare(a.street, b.street) || naturalCompare(a.room, b.room)
);

Capabilities

Natural String Comparison

Compares two strings containing mixed letters and numbers in natural (human-readable) order.

/**
 * Compare two strings in natural order
 * @param {string|any} a - First string to compare (non-strings are converted to strings)
 * @param {string|any} b - Second string to compare (non-strings are converted to strings)
 * @returns {number} -1 if a < b, 0 if a === b, 1 if a > b
 */
function naturalCompare(a, b);

The function handles:

  • Numeric sequences within strings (treats "10" as larger than "2")
  • Mixed alphanumeric content ("file2.txt" vs "file10.txt")
  • Negative numbers ("-1" comes before "1")
  • Decimal numbers with proper precision handling
  • Unicode characters and custom alphabets

Usage Examples:

// Basic comparison
naturalCompare("a1", "a2");     // -1 (a1 comes before a2)
naturalCompare("a10", "a2");    // 1  (a10 comes after a2)
naturalCompare("same", "same"); // 0  (strings are equal)

// Numeric sequences
naturalCompare("file1.txt", "file10.txt");  // -1
naturalCompare("version1.2", "version1.10"); // -1

// With JavaScript's sort method
["img1.png", "img10.png", "img2.png"].sort(naturalCompare);
// Result: ["img1.png", "img2.png", "img10.png"]

// Decimal numbers
naturalCompare("1.01", "1.001"); // 1 (maintains decimal precision)
naturalCompare("1.001", "1.01"); // -1

Custom Alphabet Configuration

Configure custom character ordering for internationalization by setting the global String.alphabet property.

/**
 * Global alphabet configuration for custom character ordering
 * @type {string|undefined}
 */
String.alphabet;

Usage Examples:

// Estonian alphabet
String.alphabet = "ABDEFGHIJKLMNOPRSŠZŽTUVÕÄÖÜXYabdefghijklmnoprsšzžtuvõäöüxy";
["t", "z", "x", "õ"].sort(naturalCompare);
// Result: ["z", "t", "õ", "x"] (follows Estonian ordering)

// Russian alphabet  
String.alphabet = "АБВГДЕЁЖЗИЙКЛМНОПРСТУФХЦЧШЩЪЫЬЭЮЯабвгдеёжзийклмнопрстуфхцчшщъыьэюя";
["Ё", "А", "Б"].sort(naturalCompare);
// Result: ["А", "Б", "Ё"] (follows Russian ordering)

// Reset to default behavior
String.alphabet = undefined;

Browser Compatibility

In browser environments where CommonJS modules aren't available, the function is attached to String.naturalCompare.

/**
 * Browser-compatible reference to naturalCompare function  
 * Available when CommonJS modules are not supported
 * @type {function}
 */
String.naturalCompare;

Usage Example:

<script src="natural-compare-lite.js"></script>
<script>
  // Use String.naturalCompare in browser environments
  const files = ["file1.txt", "file10.txt", "file2.txt"];
  files.sort(String.naturalCompare);
  // Result: ["file1.txt", "file2.txt", "file10.txt"]
</script>

Types

/**
 * Natural comparison function type
 * @param {string} a - First string to compare
 * @param {string} b - Second string to compare  
 * @returns {number} Comparison result: -1, 0, or 1
 */
type naturalCompare = (a: string, b: string) => number;

docs

index.md

tile.json