anodynos/upath anodynos/upath

  • Stars
    star
    144
  • Rank 246,995 (Top 6 %)
  • Language
    CoffeeScript
  • License
    MIT License
  • Created over 9 years ago
  • Updated 11 months ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
anodynos/upath
github

anodynos

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A proxy to `path`, replacing `\` with `/` for all results & methods to add, change, default, trim file extensions.

upath v2.0.1

Build Status Up to date Status

A drop-in replacement / proxy to nodejs's path that:

  • Replaces the windows \ with the unix / in all string params & results. This has significant positives - see below.

  • Adds filename extensions functions addExt, trimExt, removeExt, changeExt, and defaultExt.

  • Add a normalizeSafe function to preserve any meaningful leading ./ & a normalizeTrim which additionally trims any useless ending /.

  • Plus a helper toUnix that simply converts \ to / and consolidates duplicates.

Useful note: these docs are actually auto generated from specs, running on Linux.

Notes:

  • upath.sep is set to '/' for seamless replacement (as of 1.0.3).

  • upath has no runtime dependencies, except built-in path (as of 1.0.4)

  • travis-ci tested in node versions 8 to 14 (on linux)

  • Also tested on Windows / [email protected] (without CI)

History brief:

  • 1.x : Initial release and various features / fixes

  • 2.0.0 : Adding UNC paths support - see #38

Why ?

Normal path doesn't convert paths to a unified format (ie /) before calculating paths (normalize, join), which can lead to numerous problems. Also path joining, normalization etc on the two formats is not consistent, depending on where it runs. Running path on Windows yields different results than when it runs on Linux / Mac.

In general, if you code your paths logic while developing on Unix/Mac and it runs on Windows, you may run into problems when using path.

Note that using Unix / on Windows works perfectly inside nodejs (and other languages), so there's no reason to stick to the Windows legacy at all.

Examples / specs

Check out the different (improved) behavior to vanilla path:

`upath.normalize(path)`        --returns-->

      โœ“ `'c:/windows/nodejs/path'`         --->      `'c:/windows/nodejs/path'`  // equal to `path.normalize()`
      โœ“ `'c:/windows/../nodejs/path'`      --->              `'c:/nodejs/path'`  // equal to `path.normalize()`
      โœ“ `'c:\\windows\\nodejs\\path'`      --->      `'c:/windows/nodejs/path'`  // `path.normalize()` gives `'c:\windows\nodejs\path'`
      โœ“ `'c:\\windows\\..\\nodejs\\path'`  --->              `'c:/nodejs/path'`  // `path.normalize()` gives `'c:\windows\..\nodejs\path'`
      โœ“ `'/windows\\unix/mixed'`           --->         `'/windows/unix/mixed'`  // `path.normalize()` gives `'/windows\unix/mixed'`
      โœ“ `'\\windows//unix/mixed'`          --->         `'/windows/unix/mixed'`  // `path.normalize()` gives `'\windows/unix/mixed'`
      โœ“ `'\\windows\\..\\unix/mixed/'`     --->                `'/unix/mixed/'`  // `path.normalize()` gives `'\windows\..\unix/mixed/'`

Joining paths can also be a problem:

`upath.join(paths...)`        --returns-->

      โœ“ `'some/nodejs/deep', '../path'`       --->       `'some/nodejs/path'`  // equal to `path.join()`
      โœ“ `'some/nodejs\\windows', '../path'`   --->       `'some/nodejs/path'`  // `path.join()` gives `'some/path'`
      โœ“ `'some\\windows\\only', '..\\path'`   --->      `'some/windows/path'`  // `path.join()` gives `'some\windows\only/..\path'`

Parsing with path.parse() should also be consistent across OSes:

upath.parse(path) --returns-->

      โœ“ `'c:\Windows\Directory\somefile.ext'`      ---> `{ root: '', dir: 'c:/Windows/Directory', base: 'somefile.ext', ext: '.ext', name: 'somefile'

}//path.parse()gives'{ root: '', dir: '', base: 'c:\Windows\Directory\somefile.ext', ext: '.ext', name: 'c:\Windows\Directory\somefile' }'โœ“'/root/of/unix/somefile.ext' --->{ root: '/', dir: '/root/of/unix', base: 'somefile.ext', ext: '.ext', name: 'somefile' } // equal topath.parse()`

Added functions

upath.toUnix(path)

Just converts all `` to / and consolidates duplicates, without performing any normalization.

Examples / specs
`upath.toUnix(path)`        --returns-->

    โœ“ `'.//windows\//unix//mixed////'`      --->         `'./windows/unix/mixed/'`
    โœ“ `'..///windows\..\\unix/mixed'`       --->      `'../windows/../unix/mixed'`

upath.normalizeSafe(path)

Exactly like path.normalize(path), but it keeps the first meaningful ./ or //.

Note that the unix / is returned everywhere, so windows \ is always converted to unix /.

Examples / specs & how it differs from vanilla path
`upath.normalizeSafe(path)`        --returns-->

    โœ“ `''`                               --->                              `'.'`  // equal to `path.normalize()`
    โœ“ `'.'`                              --->                              `'.'`  // equal to `path.normalize()`
    โœ“ `'./'`                             --->                             `'./'`  // equal to `path.normalize()`
    โœ“ `'.//'`                            --->                             `'./'`  // equal to `path.normalize()`
    โœ“ `'.\\'`                            --->                             `'./'`  // `path.normalize()` gives `'.\'`
    โœ“ `'.\\//'`                          --->                             `'./'`  // `path.normalize()` gives `'.\/'`
    โœ“ `'./..'`                           --->                             `'..'`  // equal to `path.normalize()`
    โœ“ `'.//..'`                          --->                             `'..'`  // equal to `path.normalize()`
    โœ“ `'./../'`                          --->                            `'../'`  // equal to `path.normalize()`
    โœ“ `'.\\..\\'`                        --->                            `'../'`  // `path.normalize()` gives `'.\..\'`
    โœ“ `'./../dep'`                       --->                         `'../dep'`  // equal to `path.normalize()`
    โœ“ `'../dep'`                         --->                         `'../dep'`  // equal to `path.normalize()`
    โœ“ `'../path/dep'`                    --->                    `'../path/dep'`  // equal to `path.normalize()`
    โœ“ `'../path/../dep'`                 --->                         `'../dep'`  // equal to `path.normalize()`
    โœ“ `'dep'`                            --->                            `'dep'`  // equal to `path.normalize()`
    โœ“ `'path//dep'`                      --->                       `'path/dep'`  // equal to `path.normalize()`
    โœ“ `'./dep'`                          --->                          `'./dep'`  // `path.normalize()` gives `'dep'`
    โœ“ `'./path/dep'`                     --->                     `'./path/dep'`  // `path.normalize()` gives `'path/dep'`
    โœ“ `'./path/../dep'`                  --->                          `'./dep'`  // `path.normalize()` gives `'dep'`
    โœ“ `'.//windows\\unix/mixed/'`        --->          `'./windows/unix/mixed/'`  // `path.normalize()` gives `'windows\unix/mixed/'`
    โœ“ `'..//windows\\unix/mixed'`        --->          `'../windows/unix/mixed'`  // `path.normalize()` gives `'../windows\unix/mixed'`
    โœ“ `'windows\\unix/mixed/'`           --->            `'windows/unix/mixed/'`  // `path.normalize()` gives `'windows\unix/mixed/'`
    โœ“ `'..//windows\\..\\unix/mixed'`    --->                  `'../unix/mixed'`  // `path.normalize()` gives `'../windows\..\unix/mixed'`
    โœ“ `'\\\\server\\share\\file'`        --->            `'//server/share/file'`  // `path.normalize()` gives `'\\server\share\file'`
    โœ“ `'//server/share/file'`            --->            `'//server/share/file'`  // `path.normalize()` gives `'/server/share/file'`
    โœ“ `'\\\\?\\UNC\\server\\share\\file'` --->      `'//?/UNC/server/share/file'`  // `path.normalize()` gives `'\\?\UNC\server\share\file'`
    โœ“ `'\\\\LOCALHOST\\c$\\temp\\file'`  --->       `'//LOCALHOST/c$/temp/file'`  // `path.normalize()` gives `'\\LOCALHOST\c$\temp\file'`
    โœ“ `'\\\\?\\c:\\temp\\file'`          --->               `'//?/c:/temp/file'`  // `path.normalize()` gives `'\\?\c:\temp\file'`
    โœ“ `'\\\\.\\c:\\temp\\file'`          --->               `'//./c:/temp/file'`  // `path.normalize()` gives `'\\.\c:\temp\file'`
    โœ“ `'//./c:/temp/file'`               --->               `'//./c:/temp/file'`  // `path.normalize()` gives `'/c:/temp/file'`
    โœ“ `'////\\.\\c:/temp\\//file'`       --->               `'//./c:/temp/file'`  // `path.normalize()` gives `'/\.\c:/temp\/file'`

upath.normalizeTrim(path)

Exactly like path.normalizeSafe(path), but it trims any useless ending /.

Examples / specs
`upath.normalizeTrim(path)`        --returns-->

    โœ“ `'./'`                          --->                         `'.'`  // `upath.normalizeSafe()` gives `'./'`
    โœ“ `'./../'`                       --->                        `'..'`  // `upath.normalizeSafe()` gives `'../'`
    โœ“ `'./../dep/'`                   --->                    `'../dep'`  // `upath.normalizeSafe()` gives `'../dep/'`
    โœ“ `'path//dep\\'`                 --->                  `'path/dep'`  // `upath.normalizeSafe()` gives `'path/dep/'`
    โœ“ `'.//windows\\unix/mixed/'`     --->      `'./windows/unix/mixed'`  // `upath.normalizeSafe()` gives `'./windows/unix/mixed/'`

upath.joinSafe([path1][, path2][, ...])

Exactly like path.join(), but it keeps the first meaningful ./ or //.

Note that the unix / is returned everywhere, so windows \ is always converted to unix /.

Examples / specs & how it differs from vanilla path
`upath.joinSafe(path)`        --returns-->

    โœ“ `'some/nodejs/deep', '../path'`                --->           `'some/nodejs/path'`  // equal to `path.join()`
    โœ“ `'./some/local/unix/', '../path'`              --->          `'./some/local/path'`  // `path.join()` gives `'some/local/path'`
    โœ“ `'./some\\current\\mixed', '..\\path'`         --->        `'./some/current/path'`  // `path.join()` gives `'some\current\mixed/..\path'`
    โœ“ `'../some/relative/destination', '..\\path'`   --->      `'../some/relative/path'`  // `path.join()` gives `'../some/relative/destination/..\path'`
    โœ“ `'\\\\server\\share\\file', '..\\path'`        --->        `'//server/share/path'`  // `path.join()` gives `'\\server\share\file/..\path'`
    โœ“ `'\\\\.\\c:\\temp\\file', '..\\path'`          --->           `'//./c:/temp/path'`  // `path.join()` gives `'\\.\c:\temp\file/..\path'`
    โœ“ `'//server/share/file', '../path'`             --->        `'//server/share/path'`  // `path.join()` gives `'/server/share/path'`
    โœ“ `'//./c:/temp/file', '../path'`                --->           `'//./c:/temp/path'`  // `path.join()` gives `'/c:/temp/path'`

Added functions for filename extension manipulation.

Happy notes:

In all functions you can:

  • use both .ext & ext - the dot . on the extension is always adjusted correctly.

  • omit the ext param (pass null/undefined/empty string) and the common sense thing will happen.

  • ignore specific extensions from being considered as valid ones (eg .min, .dev .aLongExtIsNotAnExt etc), hence no trimming or replacement takes place on them.

upath.addExt(filename, [ext])

Adds .ext to filename, but only if it doesn't already have the exact extension.

Examples / specs
`upath.addExt(filename, 'js')`     --returns-->

    โœ“ `'myfile/addExt'`           --->           `'myfile/addExt.js'`
    โœ“ `'myfile/addExt.txt'`       --->       `'myfile/addExt.txt.js'`
    โœ“ `'myfile/addExt.js'`        --->           `'myfile/addExt.js'`
    โœ“ `'myfile/addExt.min.'`      --->      `'myfile/addExt.min..js'`

It adds nothing if no ext param is passed.

`upath.addExt(filename)`           --returns-->

      โœ“ `'myfile/addExt'`           --->              `'myfile/addExt'`
      โœ“ `'myfile/addExt.txt'`       --->          `'myfile/addExt.txt'`
      โœ“ `'myfile/addExt.js'`        --->           `'myfile/addExt.js'`
      โœ“ `'myfile/addExt.min.'`      --->         `'myfile/addExt.min.'`

upath.trimExt(filename, [ignoreExts], [maxSize=7])

Trims a filename's extension.

  • Extensions are considered to be up to maxSize chars long, counting the dot (defaults to 7).

  • An Array of ignoreExts (eg ['.min']) prevents these from being considered as extension, thus are not trimmed.

Examples / specs
`upath.trimExt(filename)`          --returns-->

    โœ“ `'my/trimedExt.txt'`             --->                 `'my/trimedExt'`
    โœ“ `'my/trimedExt'`                 --->                 `'my/trimedExt'`
    โœ“ `'my/trimedExt.min'`             --->                 `'my/trimedExt'`
    โœ“ `'my/trimedExt.min.js'`          --->             `'my/trimedExt.min'`
    โœ“ `'../my/trimedExt.longExt'`      --->      `'../my/trimedExt.longExt'`

It is ignoring .min & .dev as extensions, and considers exts with up to 8 chars.

`upath.trimExt(filename, ['min', '.dev'], 8)`          --returns-->

      โœ“ `'my/trimedExt.txt'`              --->                  `'my/trimedExt'`
      โœ“ `'my/trimedExt.min'`              --->              `'my/trimedExt.min'`
      โœ“ `'my/trimedExt.dev'`              --->              `'my/trimedExt.dev'`
      โœ“ `'../my/trimedExt.longExt'`       --->               `'../my/trimedExt'`
      โœ“ `'../my/trimedExt.longRExt'`      --->      `'../my/trimedExt.longRExt'`

upath.removeExt(filename, ext)

Removes the specific ext extension from filename, if it has it. Otherwise it leaves it as is. As in all upath functions, it be .ext or ext.

Examples / specs
`upath.removeExt(filename, '.js')`          --returns-->

    โœ“ `'removedExt.js'`          --->          `'removedExt'`
    โœ“ `'removedExt.txt.js'`      --->      `'removedExt.txt'`
    โœ“ `'notRemoved.txt'`         --->      `'notRemoved.txt'`

It does not care about the length of exts.

`upath.removeExt(filename, '.longExt')`          --returns-->

    โœ“ `'removedExt.longExt'`          --->          `'removedExt'`
    โœ“ `'removedExt.txt.longExt'`      --->      `'removedExt.txt'`
    โœ“ `'notRemoved.txt'`              --->      `'notRemoved.txt'`

upath.changeExt(filename, [ext], [ignoreExts], [maxSize=7])

Changes a filename's extension to ext. If it has no (valid) extension, it adds it.

  • Valid extensions are considered to be up to maxSize chars long, counting the dot (defaults to 7).

  • An Array of ignoreExts (eg ['.min']) prevents these from being considered as extension, thus are not changed - the new extension is added instead.

Examples / specs
`upath.changeExt(filename, '.js')`  --returns-->

    โœ“ `'my/module.min'`            --->                `'my/module.js'`
    โœ“ `'my/module.coffee'`         --->                `'my/module.js'`
    โœ“ `'my/module'`                --->                `'my/module.js'`
    โœ“ `'file/withDot.'`            --->             `'file/withDot.js'`
    โœ“ `'file/change.longExt'`      --->      `'file/change.longExt.js'`

If no ext param is given, it trims the current extension (if any).

`upath.changeExt(filename)`        --returns-->

      โœ“ `'my/module.min'`            --->                   `'my/module'`
      โœ“ `'my/module.coffee'`         --->                   `'my/module'`
      โœ“ `'my/module'`                --->                   `'my/module'`
      โœ“ `'file/withDot.'`            --->                `'file/withDot'`
      โœ“ `'file/change.longExt'`      --->         `'file/change.longExt'`

It is ignoring .min & .dev as extensions, and considers exts with up to 8 chars.

`upath.changeExt(filename, 'js', ['min', '.dev'], 8)`        --returns-->

      โœ“ `'my/module.coffee'`          --->                 `'my/module.js'`
      โœ“ `'file/notValidExt.min'`      --->      `'file/notValidExt.min.js'`
      โœ“ `'file/notValidExt.dev'`      --->      `'file/notValidExt.dev.js'`
      โœ“ `'file/change.longExt'`       --->               `'file/change.js'`
      โœ“ `'file/change.longRExt'`      --->      `'file/change.longRExt.js'`

upath.defaultExt(filename, [ext], [ignoreExts], [maxSize=7])

Adds .ext to filename, only if it doesn't already have any old extension.

  • (Old) extensions are considered to be up to maxSize chars long, counting the dot (defaults to 7).

  • An Array of ignoreExts (eg ['.min']) will force adding default .ext even if one of these is present.

Examples / specs
`upath.defaultExt(filename, 'js')`   --returns-->

    โœ“ `'fileWith/defaultExt'`              --->              `'fileWith/defaultExt.js'`
    โœ“ `'fileWith/defaultExt.js'`           --->              `'fileWith/defaultExt.js'`
    โœ“ `'fileWith/defaultExt.min'`          --->             `'fileWith/defaultExt.min'`
    โœ“ `'fileWith/defaultExt.longExt'`      --->      `'fileWith/defaultExt.longExt.js'`

If no ext param is passed, it leaves filename intact.

`upath.defaultExt(filename)`       --returns-->

      โœ“ `'fileWith/defaultExt'`              --->                 `'fileWith/defaultExt'`
      โœ“ `'fileWith/defaultExt.js'`           --->              `'fileWith/defaultExt.js'`
      โœ“ `'fileWith/defaultExt.min'`          --->             `'fileWith/defaultExt.min'`
      โœ“ `'fileWith/defaultExt.longExt'`      --->         `'fileWith/defaultExt.longExt'`

It is ignoring .min & .dev as extensions, and considers exts with up to 8 chars.

`upath.defaultExt(filename, 'js', ['min', '.dev'], 8)` --returns-->

      โœ“ `'fileWith/defaultExt'`               --->               `'fileWith/defaultExt.js'`
      โœ“ `'fileWith/defaultExt.min'`           --->           `'fileWith/defaultExt.min.js'`
      โœ“ `'fileWith/defaultExt.dev'`           --->           `'fileWith/defaultExt.dev.js'`
      โœ“ `'fileWith/defaultExt.longExt'`       --->          `'fileWith/defaultExt.longExt'`
      โœ“ `'fileWith/defaultExt.longRext'`      --->      `'fileWith/defaultExt.longRext.js'`

Copyright(c) 2014-2020 Angelos Pikoulas ([email protected])

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

More Repositories

1

uRequire

The Ultimate JavaScript Module Builder & Automagical Task Runner. Convert AMD & CommonJS/NodeJS modules to UMD, AMD, CommonJS or bundle them as `combined.js` (rjs & almond, AMDclean soon) & automagically run/test/watch them on nodejs, Web/AMD or Web/Script. Declarative & DRY config with inheritance. Manipulate & inject dependencies, module code, banners, version etc while building with a single line. Support two kinds of plugins, ResourceConverter (i.e file level) and AfterBuilder (i.e the whole bundle). Transparent support for Coffeescript, IcedCoffeescript, Coco, LiveScript โ€“ theyโ€™re just JavaScript :-)
CoffeeScript
265
star
2

accesscontrol-re

A facade enhancing the great javascript lib AccessControl, but with much desired missing features!
TypeScript
11
star
3

node-glob-expand

A sync glob / minimatch call with a gruntjs -like `expand` of patterns, with minimum depepndencies. Derived from gruntjs's v0.4.1 `file.expand`.
CoffeeScript
9
star
4

uBerscore

An anorthodox, extensible, overloaded facade experiment of underscore facilities & leftovers.
CoffeeScript
6
star
5

node2web

Registers browserify-ied nodejs core modules to bower (via their name), to make them easily available to browsers.
CoffeeScript
6
star
6

require-clean

Cleanly require a module from disk, having flushed the module's cache, including all of its submodules. Used like normal require.
CoffeeScript
5
star
7

touchegg

Automatically exported from code.google.com/p/touchegg
C++
4
star
8

urequire-example-helloworld

Example `Hello world` project build with uRequire, demonstrating declarative DRYness packed with automagical power.
CoffeeScript
3
star
9

node2web_querystring

JavaScript
2
star
10

node2web_buffer

JavaScript
2
star
11

urequire-example

Example project build with uRequire, demonstrating declarative DRYness packed with automagical power.
CoffeeScript
2
star
12

ramdash

(Some) missing lodash functions for ramda with minimal size (1k minified)
CoffeeScript
2
star
13

newin

CLI to open new window(s)/tab(s) & execute bash command(s) on WSL Windows Terminal or KDE Konsole
JavaScript
2
star
14

calculated-cached-properties

CoffeeScript
2
star
15

decurry

Decurry is the 'reverse' of curry: given a composed function `fn(arg1)(arg2)(arg3)` it gives a function that can be called as `fn(arg1, arg2, arg3)` or `fn(arg1, arg2)(arg3) etc.
CoffeeScript
2
star
16

urequire-ab-specrunner

Automagically generates and runs Specs using mocha, chai & phantomjs after running a `lib` and a `specs` build in [uRequire](http://urequire.org) running on grunt.
CoffeeScript
2
star
17

SpringDataNeo4jTrials

Some Spring Data Neo4j 2.x testing on OO/Inheritance/Polymorhpism, Repositories, AspectJ, Groovy, Cypher, Gremlin etc
Java
1
star
18

nodejs-browser-cross-development

Using uRequire with cross platform (nodejs/browser) dependencies
JavaScript
1
star
19

permissions-nestjs

NestJS Guard & Decorators for @superawesome/permissions, promoting orthogonal fine-grained access control to resources.
TypeScript
1
star
20

urequire-rc-rxjs5-custom-build

Build *custom build of RxJS 5*, a custom Observable with added (patched) operators on streams (eg 'map', 'filter' etc), and static methods attached to Observable (like 'Observable.fromEvent').
CoffeeScript
1
star
21

permissions

Fine grained permissions / access control with ownerships & attribute picking, done right.
TypeScript
1
star
22

umatch

A `function(filename, specs)` thats checks if `'someFile.ext'` passes through an of Array of `minimatch` / `RegExp` / `callbacks` / `Array` (recursive) specs, with a negation/exclusion '!' flag for all
CoffeeScript
1
star
23

urequire-ab-grunt-contrib-watch

Automagically generates and runs a `grunt-contrib-watch` task from a uRequire config running within grunt.
CoffeeScript
1
star
24

node2web_path

JavaScript
1
star
25

policy-peoplefinder-abac

Open Policy Agent
1
star
26

urequire-rc-inject-version

uRequire ResourceConverter that injects a `var VERSION = 'x.x.x'` where its needed.
CoffeeScript
1
star
27

urequire-grunt

Write a 5-10 line build configuration, get an out-of-the-box, ready-to-work, full-fledged, fool-proof grunt & urequire based build system.
CoffeeScript
1
star