{"_id":"cross-path-sort","_rev":"1-1ebe689f871e5fc686161f996fa72f1d","name":"cross-path-sort","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"cross-path-sort","version":"1.0.0","description":"Cross-platform file path sorting. Sort an array of path strings or objects containing path strings.","main":"index.js","scripts":{"test":"eslint . -f tap && nyc --reporter=lcov --reporter=text mocha","coveralls":"cat ./coverage/lcov.info | coveralls"},"author":{"name":"Milos Djermanovic","email":"milos.djermanovic@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/mdjermanovic/cross-path-sort.git"},"homepage":"https://github.com/mdjermanovic/cross-path-sort","bugs":{"url":"https://github.com/mdjermanovic/cross-path-sort/issues"},"devDependencies":{"chai":"^4.2.0","coveralls":"^3.0.2","eslint":"^5.7.0","eslint-plugin-prettier":"^3.0.0","js-combinatorics":"^0.5.3","mocha":"^5.2.0","nyc":"^13.1.0","prettier":"^1.14.3","sinon":"^7.0.0","sinon-test":"^2.4.0"},"engines":{"node":">=6"},"keywords":["sort","sorting","path","paths","file","files","filepath","dir","directory","directories","folder","subdirectory","relative","absolute","array","cross-platform","posix","linux","unix","macos","windows","node"],"gitHead":"37079345d79796df2362dcb005e9cdb5a6b26504","_id":"cross-path-sort@1.0.0","_npmVersion":"6.4.1","_nodeVersion":"8.12.0","_npmUser":{"name":"mdjermanovic","email":"milos.djermanovic@gmail.com"},"dist":{"integrity":"sha512-aNS22Ns5IC2YmotLFBaQLmH+RtRpfjQlnZtUuwlHUaaxMKUeLQ0Pve1c69zgU6jmh2Irug1ZiMex9XkYdm5Mwg==","shasum":"9c07df9fe5ebdc49d980d99ffcf845f7717865b8","tarball":"https://registry.npmjs.org/cross-path-sort/-/cross-path-sort-1.0.0.tgz","fileCount":4,"unpackedSize":26436,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJbz4etCRA9TVsSAnZWagAAxNUP/AraNDup8GLs5WPW2Cw8\nMQKZA0j+PKC8LkwR9pFMO+CH6P9KzKQD0ODOdV4BdvnABPGlfASpilq0cb0l\nHASgw6d83fYI1UqmsECpXA8rV8J6fn6u/MOExXJX9B8+E9SLPawS+T95AsRC\nFNdTmgTXwPe60yzv+71uaxeYIVgj/gltk10MiGcfwdiVv3CZyZVFJzBclkrN\nYHkqVxS4yfIpzmm+q4Nc0u0Fd5dn4uwLXFnkJnk5ntZJB+1IaqYOLy24yCpG\nPoMIEhz9Bg0YnIoFdLjKOXVKl/hr7Q9h+A/6JzGijNMyiXjOK5fofvDfji8D\nUYPWktY7rb1Jvt+itiF/6N0MhtUG/iDN9/or5zN40RTes+NQrpxm3499ENqc\nrMzJQx9mkTQM7Vg3OnA1y03IFkDXFcVKrDjbl1WZncu98MWopCrMWLkngtmK\nPs1qVzuZ82ARsI5yTb2WKLyweqlueDvD6UH3+rRx55WtGZB9qPHFBkKdapFY\nfD+jfY+Ml/USpQzpEvH/AoKbrida2ego0ChVkEN8TvhfwV/xStWQFGsSb4R3\nY94LAltQC4nhnnj/q118BYLacNW4GvtA5b05rTv+C8p/boeQxBfHDEmfHgIm\nLMtC3/PHPa8M12Rdes29xVKTg5LeNe9AeUDCCMhzMo5tDTi3rbLHVz8WoTW/\ncHoW\r\n=b2iJ\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIFE4WnJikd+NF6Mw57X9JNsJ50raRGsjMd80l7DHo6f2AiEAlewt38+ZTQEWWo3dvB3GpK90b31tqKi/1lDg+zeUuOE="}]},"maintainers":[{"name":"mdjermanovic","email":"milos.djermanovic@gmail.com"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/cross-path-sort_1.0.0_1540327340438_0.2140923905244163"},"_hasShrinkwrap":false}},"time":{"created":"2018-10-23T20:42:20.437Z","1.0.0":"2018-10-23T20:42:20.668Z","modified":"2022-04-27T22:24:07.613Z"},"maintainers":[{"name":"mdjermanovic","email":"milos.djermanovic@gmail.com"}],"description":"Cross-platform file path sorting. Sort an array of path strings or objects containing path strings.","homepage":"https://github.com/mdjermanovic/cross-path-sort","keywords":["sort","sorting","path","paths","file","files","filepath","dir","directory","directories","folder","subdirectory","relative","absolute","array","cross-platform","posix","linux","unix","macos","windows","node"],"repository":{"type":"git","url":"git+https://github.com/mdjermanovic/cross-path-sort.git"},"author":{"name":"Milos Djermanovic","email":"milos.djermanovic@gmail.com"},"bugs":{"url":"https://github.com/mdjermanovic/cross-path-sort/issues"},"license":"MIT","readme":"# cross-path-sort\n\n[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mdjermanovic/cross-path-sort/blob/master/LICENSE) [![npm version](https://img.shields.io/npm/v/cross-path-sort.svg?style=flat)](https://www.npmjs.com/package/cross-path-sort) [![Build Status](https://travis-ci.org/mdjermanovic/cross-path-sort.svg?branch=master)](https://travis-ci.org/mdjermanovic/cross-path-sort) [![Coverage Status](https://coveralls.io/repos/github/mdjermanovic/cross-path-sort/badge.svg?branch=master)](https://coveralls.io/github/mdjermanovic/cross-path-sort?branch=master)\n\nCross-platform non-destructive file path sorting function.\n\nPass in an array of path strings or objects with a property whose value is path string. Get a new array with\nthe same elements, sorted in a more intuitive way than with a simple sort:\n\n* You can use shallowFirst/deepFirst options to separate the content of a directory from the content of its subdirectories.\n\n```\nsimple sort vs this function with the shallowFirst option\n\none.js                  one.js\ntest/one_spec.js        two.js\ntest/two_spec.js        test/one_spec.js\ntwo.js                  test/two_spec.js\n```\n\n* Different types of paths (relative, absolute, home, UNC, namespaced...) in the same array are always separated.\nYou can change the default order of types.\n\n```\nsimple sort vs this function on Windows\n\napi.js                  api.js\nC:\\util\\hash.js         engine.js\nengine.js               C:\\util\\hash.js\n```\n\nThe sort function:\n\n* Works well with all kinds of paths on all platforms on which Node.js can be installed.\n* Parses and sorts paths based on the platform on which it is running. See the Platforms section below for details.\n* Normalizes path strings, but it always returns same strings/objects from the original array.\n* Does not access the file system, it just works with the strings.\n* By design, does not throw any exceptions related to the content of the paths array.\n\n## Installation and Usage\n\n```\n$ npm install cross-path-sort\n```\n\nThis particular example will produce the same results on all platforms since\nthe forward slash `/` is a valid separator on both Windows and POSIX (Linux, Unix, macOS...) systems:\n\n```js\nconst crossPathSort = require('cross-path-sort');\n\nconst paths = [\n  'one.js',\n  'test/one_spec.js', \n  '/mylibs/hash.js',\n  'two.js',\n  '/mylibs/encode/url.js',\n  '/mylibs/assign.js',\n  'test/shared/init.js',\n  'test/two_spec.js',\n  'config/env.js'\n];\n\nconst sortedPaths1 = crossPathSort.sort(paths, { shallowFirst: true });\n/*\n  [\n    'one.js',\n    'two.js',\n    'config/env.js',\n    'test/one_spec.js',\n    'test/two_spec.js',\n    'test/shared/init.js',\n    '/mylibs/assign.js',\n    '/mylibs/hash.js',\n    '/mylibs/encode/url.js'\n  ]\n*/\n\nconst sortedPaths2 = crossPathSort.sort(paths, { deepFirst: true });\n/*\n  [\n    'config/env.js',\n    'test/shared/init.js',\n    'test/one_spec.js',\n    'test/two_spec.js',\n    'one.js',\n    'two.js',\n    '/mylibs/encode/url.js',\n    '/mylibs/assign.js',\n    '/mylibs/hash.js'\n  ]\n*/\n\n// if you just want to separate path types\nconst sortedPaths3 = crossPathSort.sort(paths);\n/*\n  [\n    'config/env.js',\n    'one.js',\n    'test/one_spec.js',\n    'test/shared/init.js',\n    'test/two_spec.js',\n    'two.js',\n    '/mylibs/assign.js',\n    '/mylibs/encode/url.js',\n    '/mylibs/hash.js'\n  ]\n*/\n```\n\nHad we used the backslash `\\` instead, results would be different on different platforms.\n\n## Platforms\n\nThe cross-platform sorting function assumes that the paths it works on are related to the operating system on which it is running.\nIn other words, it assumes that the paths are either locally generated by your application or specified by its user.\n\nThe paths are normalized, parsed and sorted accordingly.\n\nThis module exposes three functions:\n\n* `sort()` is the cross-platform sorting function, which you should use.\n* `posix.sort()` is POSIX-specific sorting function.\n* `windows.sort()` is Windows-specific sorting function.\n\nDepending on the local platform, `sort()` works like `posix.sort()` or `windows.sort()`.\n\nYou should always use just `sort()` unless you have a specific application that doesn't work with local paths.\n\n```js\nconst crossPathSort = require('cross-path-sort');\n\n// escaped backslash\nconst paths = ['b\\\\a.js', 'c.js', 'a.js'];\n\n// on windows: b\\a.js = file a.js in subdirectory b\nconst sortedOnWindows = crossPathSort.windows.sort(paths, { shallowFirst: true });\n/*\n  [\n    'a.js', \n    'c.js', \n    'b\\\\a.js'\n  ]\n*/\n\n// on posix: b\\a.js = file b\\a.js\nconst sortedOnPosix = crossPathSort.posix.sort(paths, { shallowFirst: true });\n/*\n  [\n    'a.js', \n    'b\\\\a.js',\n    'c.js' \n  ]\n*/\n\nconst sortedLocally = crossPathSort.sort(paths, { shallowFirst: true });\n/*\n  same as sortedOnWindows or sortedOnPosix, depending on your platform\n*/\n```\n\nAll three functions have the same signature.\n\n## sort(paths, options)\n\n#### parameters\n\n`paths` is an array of path strings or objects, see the _paths_ and _pathKey_ sections.\n\n`options` is an options object. All options are optional, and the whole object is optional.\n\n#### returns\n\nThe function returns a new, sorted array with the exact same elements from the `paths` array.\n\n#### exceptions\n\nOnly if you specify invalid options. See the options below for details.\n\n#### example\n\nAll options with their default values:\n\n```js\nconst sortedPaths = crossPathSort.sort(paths, {\n  pathKey: undefined,\n  shallowFirst: false,\n  deepFirst: false,\n  homePathsSupported: false,\n  posixOrder: ['rel', 'home', 'abs'],\n  windowsOrder: ['rel', 'home', 'abs', 'drel', 'dabs', 'unc', 'nms'],\n  segmentCompareFn: (a, b) => a.localeCompare(b)\n});\n```\n\n### paths\n\nArray of strings or objects, or even a mixed array of strings and objects.\n\nBy design, this array can contain anything:\n\n* `string` elements and `object` elements whose `object[pathKey]` is `string` will be treated equally and sorted.\n* All other elements will be treated as 'unreadable' and come after the sorted elements.\n* Holes will be preserved and come at the very end of the resulting array.\n\nIf `paths` is not an array, `sort()` will simply return the same value.\n\n### pathKey\n\nIf you want to sort an array of your custom objects that contain path strings, use the `pathKey` option\nto specify the key of a property whose value represents the path string.\n\nIf specified, `pathKey` should be a `string`.\n\nPath string of an `object` element from the `paths` array will be read from `object[pathKey]`.\n\nNotes:\n\n* If your array has a mixed content, `pathKey` will be used only for `object` elements and ignored for `string` elements\n(`string` element itself represents a path).\n* If `object[pathKey]` is not a `string`, that `object` element will be treated as 'unreadable'.\n* If you don't specify `pathKey`, all `object` elements will be treated as 'unreadable'.\n\nExample: \n\n```js\nconst crossPathSort = require('cross-path-sort');\n\nconst obj1 = { file: 'c.js' };\nconst obj2 = { file: 'b/a.js' };\nconst obj3 = {};\nconst obj4 = { file: 'a.js'};\nconst paths = [obj1, obj2, obj3, obj4];\n\nconst sortedPaths = crossPathSort.sort(paths, { \n  pathKey: 'file',\n  shallowFirst: true \n});\n/*\n  [obj4, obj1, obj2, obj3]\n*/\n```\n\nIf your array contains just `string` elements, you can leave this value `undefined`.\n\n`sort()` will throw an exception if the `pathKey` argument itself is not a `string` or `undefined`.\n\n`sort()` will __NOT__ throw an exception if `object[pathKey]` is not a `string`.\n\n### shallowFirst & deepFirst\n\nDefault values are `false`. Only one can be set to `true`.\n\nSort has three modes:\n\n* If `shallowFirst` is `true`, content of a directory will come _before_ the content of its subdirectories.\n* If `deepFirst` is `true`, content of a directory will come _after_ the content of its subdirectories.\n* If both values are `false`, file names will be compared with subdirectory names.\n\nSee the example in the Installation and Usage section above.\n\n`sort()` will throw an exception if both `shallowFirst` and `deepFirst` have a truthy value.\n\n### homePathsSupported\n\nDefault value is `false` and paths starting with `~` are treated as _relative paths_, as the tilde is\na valid character for file names and directory names on all systems.\n\nThis is in line with how Node's modules such as `fs` or `path` treat these paths.\n\nIf your application explicitly supports shell-specific paths like `~/` or `~user/`, and you want\nthe paths starting with `~` to appear in a different partition of the resulting array as _home paths_, set\nthis value to `true`.\n\nRegarding the next section:\n\n* If `homePathsSupported` is `false`, paths starting with `~` will be `'rel'` paths. \nThere will be no `home` paths.\n* If `homePathsSupported` is `true`, paths starting with `~` will be `'home'` paths.\n\n### posixOrder & windowsOrder\n\nThese options specify the order of different path types in the resulting array.\n\n`sort()` uses `posixOrder` on POSIX platforms, `windowsOrder` on Windows platforms.\n\n#### POSIX path types\n\n* `'rel'` are relative paths, such as `a.js` and `b/a.js`.\n* `'home'` are home paths, see the previous section.\n* `'abs'` are absolute paths, such as `/a.js` and `/b/a.js`.\n\n`posixOrder` default value is: `['rel', 'home', 'abs']`\n\n#### Windows path types\n\n* `'rel'` are relative paths, such as `a.js` and `b\\a.js`\n* `'home'` are home paths, see the previous section.\n* `'abs'` are absolute paths, such as `\\a.js` and `\\b\\a.js`.\n* `'drel'` are relative paths with a specified drive, such as `C:a.js` and `C:b\\a.js`.\n* `'dabs'` are absolute paths with a specified drive, such as `C:\\a.js` and `C:\\b\\a.js`.\n* `'unc'` are UNC paths, such as `\\\\server\\share\\a.js` and `\\\\server\\share\\b\\a.js`.\n* `'nms'` are namespaced paths - paths starting with `\\\\?\\` or `\\\\.\\`.\n\n`windowsOrder` default value is: `['rel', 'home', 'abs', 'drel', 'dabs', 'unc', 'nms']`\n\nSince the forward slash `/` is a valid separator on Windows, paths like `/a.js` on Windows are also `'abs'` type paths,\npaths like `C:/a.js` on Windows are also `'dabs'` type paths etc.\n\nExample:\n\n```js\nconst crossPathSort = require('cross-path-sort');\n\nconst paths = [\n  'one.js',\n  'test/one_spec.js', \n  '/mylibs/hash.js',\n  'two.js',\n  '/mylibs/encode/url.js',\n  '/mylibs/assign.js',\n  'test/shared/init.js',\n  'test/two_spec.js',\n  'config/env.js'\n];\n\n// position of the 'home' type is irrelevant if homePathsSupported is not true\nconst sortedPaths1 = crossPathSort.sort(paths, { \n  shallowFirst: true,\n  posixOrder: ['abs', 'home', 'rel'],\n  windowsOrder: ['abs', 'dabs', 'unc', 'nms', 'drel', 'home', 'rel']\n});\n/*\n  [\n    '/mylibs/assign.js',\n    '/mylibs/hash.js',\n    '/mylibs/encode/url.js',\n    'one.js',\n    'two.js',\n    'config/env.js',\n    'test/one_spec.js',\n    'test/two_spec.js',\n    'test/shared/init.js'\n  ]\n*/\n```\n\n`sort()` will throw an exception if the `posixOrder` argument is not an `array` or `undefined`.\nAn `array` must be a permutation of the default array. The same applies to the `windowsOrder` argument.\n\n### segmentCompareFn\n\nFunction used to compare path segments such as file names, directory names, drive letters etc.\n\nDefault function is: `(a, b) => a.localeCompare(b)`\n\nIf you don't specify this option, the default function will be used.\n\nYour custom function should work like a function you would use with `Array.prototype.sort()`.\n\nThe function will always get two `string` values, and should return a number that is `< 0`, `0` or `> 0`.\n\n`sort()` will throw an exception if `segmentCompareFn` is not a `function` or `undefined`.\nAlso, `sort()` does not catch exceptions thrown by your function.\nIf your function throws an exception, the whole `sort()` will throw that exception.\n\n## About\n\n### Author\n\n[Milos Djermanovic](https://github.com/mdjermanovic)\n\n### License\n\n[MIT License](https://github.com/mdjermanovic/cross-path-sort/blob/master/LICENSE)\n","readmeFilename":"README.md"}