Skip to content
b4mossPublic

About

Create sharded path library

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

146 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

shardian

CI Coverage npm Release License OpenSSF Scorecard

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.

Usage

import { shardian } from '@b4moss/shardian'

const path = shardian('abc1234.jpg')

console.log(path)
// => '/a/b/c/1/abc1234.jpg'

Options

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 pathOnly from splitPathFilename: true (e.g. '/a/b/c/1/')
  • stripHeadSlash: true example: 'a/b/c/1/abc1234.jpg'

Rules

  • 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 (or extensionOnlyList)
  • 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')
// Error

Full contract: docs/specs/path-api.md. Hub: docs/README.md.

Supported runtimes

  • Node.js (Bun / Deno compatible): published on npm as @b4moss/shardian
  • Go: github.com/b4moss/shardian/packages/go
  • PHP: b4moss/shardian via Packagist (mirror: b4moss/shardian-php; source: packages/php)

Go

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

PHP

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

License

MIT License

About

Create sharded path library

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages