Create sharded path strings from filenames.
This library only builds path strings from a filename prefix. It does not perform I/O, hashing, or persistence.
import { shardian } from '@b4moss/shardian'
const path = shardian('abc1234.jpg')
console.log(path)
// => '/a/b/c/1/abc1234.jpg'| Field | Required | Default | Meaning |
|---|---|---|---|
(fileName as 1st arg) |
yes | — | Filename including extension |
dirLetterCount |
no | 1 |
Characters per directory level |
dirNestDepth |
no | 4 |
Nesting depth |
stripHeadSlash |
no | false |
When true, omit the leading / |
splitPathFilename |
no | false |
When true, return a split path object |
insufficientChars |
no | 'ignore' |
On short names: 'ignore' / 'warn' / 'throw' |
extensionOnlyList |
no | COMMON_EXTENSIONS |
Full replacement list for extension-only checks ([] falls back to default) |
- The string return value always includes the filename at the end
- For the directory part only, use
pathOnlyfromsplitPathFilename: true(e.g.'/a/b/c/1/') stripHeadSlash: trueexample:'a/b/c/1/abc1234.jpg'
- Extension: Kept as part of the filename (never stripped)
- Path input: Not allowed. Filenames containing
/or\throw - Relative refs:
./.././/../throw - Extension-only: Throws when the name case-insensitively equals an entry in
COMMON_EXTENSIONS(orextensionOnlyList) - Short filenames: Build from what fits. Notification is controlled by
insufficientChars(default: silent)
shardian('abc1234.jpg')
// => '/a/b/c/1/abc1234.jpg'
shardian('ab', { dirLetterCount: 1, dirNestDepth: 4 })
// => '/a/b/ab' (no warn)
shardian('ab', {
dirLetterCount: 1,
dirNestDepth: 4,
insufficientChars: 'warn',
})
// => '/a/b/ab' + console.warn
const { pathOnly } = shardian('abc1234.jpg', { splitPathFilename: true })
// pathOnly => '/a/b/c/1/'
shardian('dir/abc1234.jpg')
// Error
shardian('.jpg')
// ErrorFull contract: docs/specs/path-api.md. Hub: docs/README.md.
- Node.js (Bun / Deno compatible): published on npm as
@b4moss/shardian - Go:
github.com/b4moss/shardian/packages/go - PHP:
b4moss/shardianvia Packagist (mirror:b4moss/shardian-php; source:packages/php)
import shardian "github.com/b4moss/shardian/packages/go"
path, err := shardian.Shardian("abc1234.jpg", nil)
// path => "/a/b/c/1/abc1234.jpg"
split, err := shardian.ShardianSplit("abc1234.jpg", nil)
// split.PathOnly => "/a/b/c/1/"go get github.com/b4moss/shardian/packages/go@latest
use function B4moss\Shardian\shardian;
use function B4moss\Shardian\shardianSplit;
$path = shardian('abc1234.jpg');
// => '/a/b/c/1/abc1234.jpg'
$split = shardianSplit('abc1234.jpg');
// $split->pathOnly => '/a/b/c/1/'composer require b4moss/shardian
MIT License