I couldn't find an npm package to sort filenames into buckets, so I built one

Last week I was building a file-management feature. Users could upload
documents, and I needed to sort them into sections. One bucket for
NOCs, one for agreements, one for invoices, one for anything else.

Simple enough. I opened npm expecting to find a package for it.

What I found instead

Every search under "sort files" or "classify filename" returned one of
three things:

• sort-package-json variants (sorting keys inside package.json)
• Natural-sort utilities (alphabetical ordering of file lists)
• File-type detectors (identifying MIME types from extensions)

Nothing that took a list of filenames and a list of rules and gave
back named buckets.

I asked around. A few devs suggested "just use .filter()". Fair, for
one bucket. But once you need:

• Multiple buckets with priority order
• A fallback bucket for unmatched files
• Natural sort inside each bucket
• Rules from a config file or user input

...you're rewriting the same 40 lines in every project. That's
package-shaped.

So I built classify-filename

import { classify } from 'classify-filename';

const files = [
  'NOC_2024.pdf',
  'noc_letter.pdf',
  'agreement_v1.docx',
  'invoice_2.pdf',
  'invoice_10.pdf',
  'random.txt',
];

const result = classify(files, [
  { name: 'noc',        match: /^noc/i },
  { name: 'agreements', match: 'agreement' },
  { name: 'invoices',   match: /^invoice/i },
]);

The result:

{
  sections: {
    noc:           ['noc_letter.pdf', 'NOC_2024.pdf'],
    agreements:    ['agreement_v1.docx'],
    invoices:      ['invoice_2.pdf', 'invoice_10.pdf'],
    uncategorized: ['random.txt'],
  }
}

Notice invoice_2.pdf comes before invoice_10.pdf. That's natural
sort, the default behavior, because alphabetical sort would put 10
before 2 and that's usually not what you want with filenames.

Design decisions I actually thought about

A few choices that felt small but mattered.

Section order is priority order.
If a file matches two sections, the earlier one wins. No priority
numbers, no most-specific-match algorithm. Array order is the mental
model users already have when they write a list of rules.

Case-insensitive by default.
Files are messy. NOC_2024.pdf and noc_letter.pdf should land in
the same bucket without the user thinking about it. Regex matchers
still respect their own flags. If you write /^NOC/ you probably
meant it.

A fallback bucket, not a silent drop.
Unmatched files go to uncategorized by default. Silent drops cause
the "where did my files go?" bug I've written before. You can opt into
the drop by passing fallback: false.

An explain mode for debugging.
Set explain: true and the result includes a filename to section map,
so when someone asks "why did noc_agreement.pdf end up in NOC and
not agreements?", you can see the answer in one glance.

What's not in v1 (on purpose)

• No glob support. Regex covers it. Adding globs invites ambiguity with substring matches unless done as an explicit wrapper. Planned for v1.1.
• No file-metadata rules. Filename only for now. Size, date, and extension helpers coming in v1.2.
• No CLI. This is a library. If people want to organize a folder from the command line, that's v1.3.

Each of these could have gone into v1. I left them out because the
scope creep would have delayed shipping, and the API stays cleaner if
each feature earns its way in with real user demand.

The stack

• TypeScript, dual CJS + ESM output via tsup
• Zero runtime dependencies
• Tested with Vitest, around 15 tests covering the matcher and classifier
• ~2 KB minified

Try it

npm install classify-filename

• npm: https://www.npmjs.com/package/classify-filename
• repo: https://github.com/ElizabethSobiya/classify-filename

One thing I'd genuinely like feedback on: section-array-order as
priority. Does that feel natural to you, or would you rather see an
explicit priority: number field?

Would love to hear how you'd approach this. If you find it useful, a
star on the repo helps me know it's worth pushing v1.1 out.