rpominov / path-rebuild

Transform a file path by splitting the original path into an array of parts and defining a new path in terms of indices of the parts

path-rebuild

Transform a file path by splitting the original path into an array of parts and defining a new path in terms of indices of the parts:

       "some/path/to/a/file.js"
                  ↓
["some", "path", "to", "a", "file", ".js"]  +  "new_home/{0}_new/{1..-3}/{-2}.json"
                                            ↓
                          "new_home/some_new/path/to/a/file.json"

Examples:

• {0..-1}: no modifications (foo/baz.js -> foo/baz.js)
• {0..-2}.json: change the extension to .json (foo/baz.js -> foo/baz.json)
• dir/{0..-1}: move the entire path to a different directory (foo/baz.js -> dir/foo/baz.js)
• {0..-3}/prefix_{-2..-1}: add a prefix to the file name (foo/baz.js -> foo/prefix_baz.js)
• {0..-3}/{-2}_postfix{-1}: add a postfix to the file name (foo/baz.js -> foo/baz_postfix.js)
• {0..-3}/sub/{-2..-1}: add a sub directory (foo/baz.js -> foo/sub/baz.js)

---

For the API documentation, go to the package corresponding to your programming language:

• JavaScript
• ReScript

Separator

/ is a special character. It will be replaced with a platform dependent separator in the final output.

Examples:

// On Windows

const transform = createTransform("{0..-3}/sub/{-2..-1}");
transform("foo\\bar.js"); // -> foo\sub\bar.js

// On Linux

const transform = createTransform("{0..-3}/sub/{-2..-1}");
transform("foo/bar.js"); // -> foo/sub/bar.js

Numerical ranges

• {n}: insert the n'th part of the source path
• {n..m}: insert n through m (inclusive) parts of the source path

Where n and m can be negative numbers, indicating an offset from the end of the parts sequence. -1 corresponds to the last item.

A range can collapse if there’re no parts corresponding to the parameters. If a range collapses, and it’s followed by the separator symbol /, it will be ignored:

const transform = createTransform("{-5..-4}/{-3..-1}");

// {-5..-4} -> collapsed
// / -> ignored, because the preceding range has collapsed
// {-3..-1} -> foo/bar.js
transform("foo/bar.js"); // -> foo/bar.js

When a range like {n..m} is interpreted, a platform dependent separator is inserted between the parts. But not before the part that corresponds to the file extension:

const transform = createTransform("{-3..-1}");

// -3 -> bar
// -2 -> baz
// -1 -> .js
// `/` is inserted between `bar` and `baz`, but not before `.js`
transform("foo/bar/baz.js"); // -> bar/baz.js

For the consistency, if the source path has no extension, -1 will correspond to an empty string:

const transform = createTransform("{-3..-1}");

// -3 -> bar
// -2 -> baz
// -1 ->
transform("foo/bar/baz"); // -> bar/baz

Predefined ranges

You can also use special ranges derived from path.parse().

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
"  /    home/user/dir / file  .txt "
└──────┴──────────────┴──────┴─────┘

• {root}: inserts parsed.root
• {dir}: insert parsed.dir
• ... and so on

const transform = createTransform("{dir}/sub/{name}.json");
transform("foo/bar.js"); // -> foo/sub/bar.json

Root

The root as defined by path.parse() cannot be inserted using the numerical ranges. If the path to be transformed has a root, it will be stripped before splitting the path into the parts. If you want to have the root in your final path, make it explicit using {root} or {dir}:

const withoutRoot = createTransform("{0..-2}.json");
const withRoot = createTransform("{root}{0..-2}.json");

withoutRoot("/foo/bar.js"); // -> foo/bar.json
withRoot("/foo/bar.js"); // -> /foo/bar.json

Escaping

% is the escape character.

• %{: inserts a {
• %}: inserts a }
• %/: inserts a /
• %%: inserts a %

path-rebuild's Issues

The `sep` option does not work well with predefined ranges

const transform = createTransform("{dir}/new/path");

// Ok
transform("foo/bar/baz.js"); // -> foo/bar/new/path

// Not ok
transform("foo/bar/baz.js", "\\"); // -> foo/bar\new\path

Maybe remove the sep option altogether. Added it because it was easy to add, but now it causes problems...

Absolute paths support

Solution 1

One way we can add support of absolute paths is to automatically strip out root (as defined by path.parse()) before transforming the path, then add it back to the front of the result path.

Issues:

• No way to remove the root
• on Windows it won't be possible to change the root from C:\ to D:\ etc.

Solution 2

Add a {root} keyword, that inserts the root. This way you can either do {root}{0..-1}, or D:/{0..-1} to change the root.

Issues:

• users will have to think about it "do I always add {root}? do I do it only when I expect an absolute path? do I expect an absolute in a particular case?"
• visual noise / mental load when looking at a pattern

Solution 3

The first solution + an option removeRoot.

Issues:

• will make API more complex
• will work only when you use API directly. If a path-rebuild pattern is a part of some kind of a config there will be no way to pass the option (except by making the config schema more complex as well)

Add support of {dir} {root} {ext} etc. special groups

Add special groups support for all fields produced by path.parse(path)

This will make most common cases easier to work with.

Also, this is consistent with the "Solution 2" for #1 (So allows to choose a solution for that issue)