JavaScript Natural Sort

Common errors

• TypeError: naturalSort is not a function

  cause Incorrectly importing the `naturalSort` function, typically by trying to use named imports (`{ naturalSort }`) when it is a default export.
  fix For CommonJS, use `const naturalSort = require('javascript-natural-sort');`. For ESM, use `import naturalSort from 'javascript-natural-sort';`.

• Array.prototype.sort() results in 'A', 'b', 'C' instead of 'A', 'C', 'b'

  cause The `naturalSort` function is case-sensitive by default, leading to uppercase letters sorting before lowercase letters.
  fix Enable case-insensitive sorting by setting the global flag: `naturalSort.insensitive = true;` (remember to reset it if needed).

• TypeError: naturalSort.insensitive is not callable

  cause Attempting to call `naturalSort.insensitive()` as a function instead of assigning a boolean value to it.
  fix Set the property directly: `naturalSort.insensitive = true;` (or `false`).

Warnings

• gotcha The `naturalSort.insensitive` property sets a global flag for case-insensitive sorting. This means if you set it to `true`, all subsequent calls to `naturalSort` will be case-insensitive until you explicitly set it back to `false`. This global state can lead to unexpected behavior in applications with multiple concurrent sorts or long-running processes if not managed carefully.
  Fix: Always explicitly set `naturalSort.insensitive = false;` after performing case-insensitive sorts if subsequent sorts require case-sensitive behavior, or wrap your usage in a function that manages the state.
• breaking This package is considered abandoned, with the last commit over six years ago. It means it will not receive updates for new JavaScript features, bug fixes, or security patches. Using it in modern applications might lead to compatibility issues with newer Node.js versions or browser environments, and it will not address new edge cases in natural sorting.
  Fix: Consider migrating to a more actively maintained natural sort library that supports modern JavaScript features and best practices, or be prepared to fork and maintain the code yourself.
• gotcha The package does not have an explicit `module` field in its `package.json`, indicating a lack of native ESM support. While bundlers often handle CommonJS interoperability, direct ESM imports in Node.js environments without a bundler might behave differently or require specific configurations on older Node.js versions.
  Fix: Use CommonJS `require` for Node.js environments, or rely on a bundler (like Webpack, Rollup, or esbuild) to correctly handle the CJS-to-ESM transformation for browser environments.

Install

• npm install javascript-natural-sort npm
• yarn add javascript-natural-sort yarn
• pnpm add javascript-natural-sort pnpm

Imports

• naturalSort
  wrong:

  import { naturalSort } from 'javascript-natural-sort';

  correct:

  import naturalSort from 'javascript-natural-sort';

  The package exports a default function. While technically a CJS default export, modern bundlers and Node.js often allow this ESM syntax.
• naturalSort
  wrong:

  const { naturalSort } = require('javascript-natural-sort');

  correct:

  const naturalSort = require('javascript-natural-sort');

  The package uses CommonJS `module.exports = naturalSort;` for its main entry point.
• naturalSort.insensitive
  wrong:

  naturalSort({ insensitive: true });

  correct:

  naturalSort.insensitive = true;

  Case-insensitivity is enabled by setting a global property directly on the `naturalSort` function, not via a function parameter.

Quickstart

Demonstrates basic natural sorting for mixed numeric data and IP addresses, plus how to enable and disable global case-insensitive sorting.

import naturalSort from 'javascript-natural-sort';

// Basic numeric string and number sorting
const mixedNumerics = ['10', 9, '2', 1, '4'];
const sortedNumerics = mixedNumerics.sort(naturalSort);
console.log('Sorted Numerics:', sortedNumerics); // Expected: [1, '2', '4', 9, '10']

// Sorting IP addresses
const ipAddresses = ['192.168.0.100', '192.168.0.1', '192.168.1.1'];
const sortedIPs = ipAddresses.sort(naturalSort);
console.log('Sorted IPs:', sortedIPs); // Expected: ['192.168.0.1', '192.168.0.100', '192.168.1.1']

// Case-insensitive sorting (modifies global state)
naturalSort.insensitive = true;
const mixedCase = ['a', 'B', 'C', 'd'];
const sortedMixedCase = mixedCase.sort(naturalSort);
console.log('Sorted Mixed Case (insensitive):', sortedMixedCase); // Expected: ['a', 'B', 'C', 'd']

// Remember to reset if needed to avoid affecting other sorts
naturalSort.insensitive = false;