{"_id":"3fn","_rev":"1-5d1565618dce7597618dbcffe1ce4d1d","name":"3fn","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"3fn","version":"1.0.0","description":"Creates a three-way comparison callback.","keywords":["three-way","comparison","callback","Map","object","key","compare"],"author":{"name":"Fr. John Lamansky","url":"lamansky.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/lamansky/3fn.git"},"main":"index.js","files":[],"engines":{"node":">=8.3.0"},"dependencies":{"3":"^2.1.0","kget":"^1.0.0","vfn":"^1.1.0"},"devDependencies":{"eslint-config-lamansky":"^1.0.0","mocha":"^5.2.0"},"scripts":{"test":"mocha"},"eslintConfig":{"extends":"lamansky","env":{"mocha":true}},"gitHead":"b6a35bc7587552cf3c8b88657cc368f906f91460","bugs":{"url":"https://github.com/lamansky/3fn/issues"},"homepage":"https://github.com/lamansky/3fn#readme","_id":"3fn@1.0.0","_npmVersion":"5.5.1","_nodeVersion":"9.2.1","_npmUser":{"name":"lamansky","email":"johnlamansky@gmail.com"},"dist":{"integrity":"sha512-/Ot9A5gBDEIwuFL7/lTsmOCNP9dujz6nQL0JqDjlJU0cqEa0WWagQRqXGgsvP5GOhAP2DN92iCkFqskeDqGHpg==","shasum":"de7d23f701da7c548a0c1ce0a4bed796fed4ed29","tarball":"https://registry.npmjs.org/3fn/-/3fn-1.0.0.tgz","fileCount":4,"unpackedSize":5624,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJbbdXvCRA9TVsSAnZWagAAsUEP/1gRFExiu707D9Pg2TjK\nf4MfifDpivZIaw4xv8a0Fk+u7JeKas9OqcXsWOn8RO+HAKBMyYm46yQT6sYP\nPDBV3Q+q/CMsQlO85JUtO8dVzTZSZ71qukfDcJYxXpKSPRO1gMOtEZigT4Ug\nYSDekd8YqiuLcoQGHC5xZd0VamYMCC56nS2xsPakhgnfQlqJRk8ZxTl6qvGf\nlL4p/wY1gcF7RjbWSx54rrOtyl0OAiiW0FdzbD/xplvIQoVRtKaYSSlzsFkW\n6x8XMAdk9NnbnReohVEJjuD5t9U9EfFKfcyAFw5TQQoqZXAhmY22EoimTSlp\nsTcdRECOEfb6ldFQ3tc0up5GMsNH+oibpX3ypn38iDu/pR9asqGJBePwUBti\nuXWw6iYIHwGLLbd2ecriuKQipVp3sZOOdJLv5VYCzgpPiFhHIaaJ9AqEz+IC\n3ESu9fvlg06EW69lqjz7n5OgPBgrMBM7W/WmkfAsmvpWcWbNIGI9krqsi2WE\nwhYv58G7e2/g/Q1VBhuRa8W+dd55iJS5sZWTUQIPluIrYqn6Zkf2MKDknO7T\np9k82aPilp6SNjkqpaFgIuHdjuQ2Nr5X9a6tHctmS+TbmEGCsoBOJBNA3XuB\nMXrvKadgtir43V8fFE8icE/4JgYaLf1ZWAdZWf38zSr05l0olaMcPUdr2k2X\nGdIj\r\n=Z8Ky\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIDLT1xJhM5ofL4FxmQD76kQKXys9wHMvNfXGQgz3C/OXAiEA4sU/HpJB+RBOG/tAGgq2SKbQDPy0dRskcAnE8l5JFc8="}]},"maintainers":[{"name":"lamansky","email":"johnlamansky@gmail.com"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/3fn_1.0.0_1533924846921_0.36387764981534243"},"_hasShrinkwrap":false}},"time":{"created":"2018-08-10T18:14:06.920Z","1.0.0":"2018-08-10T18:14:07.009Z","modified":"2022-04-04T10:21:29.396Z"},"maintainers":[{"name":"lamansky","email":"johnlamansky@gmail.com"}],"description":"Creates a three-way comparison callback.","homepage":"https://github.com/lamansky/3fn#readme","keywords":["three-way","comparison","callback","Map","object","key","compare"],"repository":{"type":"git","url":"git+https://github.com/lamansky/3fn.git"},"author":{"name":"Fr. John Lamansky","url":"lamansky.com"},"bugs":{"url":"https://github.com/lamansky/3fn/issues"},"license":"MIT","readme":"# Three-Way Comparison Function (3fn)\n\nCreates a callback that compares two objects by one or more keys.\n\n## Installation\n\nRequires [Node.js](https://nodejs.org/) 8.3.0 or above.\n\n```bash\nnpm i 3fn\n```\n\n## API\n\nThe module exports a single function.\n\n### Parameters\n\n1. Variadic/Optional: `sortBy` (function, array, or any): A Map/object key. An array will be interpreted as a chain of nested keys. A function will be interpreted as a three-way comparison callback that accepts two arguments and returns a number. If the key is user-provided, you should wrap it in an array; otherwise you’ll have problems if the key is a function, array, or plain object.\n2. Optional: `options` (plain object): An argument passed to the [3](https://github.com/lamansky/3) and [kget](https://github.com/lamansky/kget) modules, allowing you to set their options. The most commonly-needed option is `inObj`, which must be set to `true` if `sortBy` is a key which points to an _inherited_ object property.\n\n### Return Value\n\nA callback function that accepts a Map, Object, or other collection as its argument and returns `-1`, `0`, or `1`. This callback then can be passed to the `sort` function of an Array, for example.\n\n## Examples\n\n### Compare By Key\n\n```javascript\nconst threeFn = require('3fn')\n\nconst personA = {name: 'John'}\nconst personB = {name: 'Andrew'}\n\nconst compare = threeFn('name')\n\ncompare(personA, personB) // 1\ncompare(personB, personA) // -1\n\n[personA, personB].sort(compare) // [personB, personA]\n```\n\n### Compare By Inherited Key\n\n```javascript\nconst threeFn = require('3fn')\n\nconst _name = Symbol('name')\n\nclass Person {\n  constructor (name) {\n    this[_name] = name\n  }\n\n  get name () {\n    return this[_name]\n  }\n}\n\nconst personA = new Person('John')\nconst personB = new Person('Andrew')\n\nconst compare = threeFn('name', {inObj: true})\n\ncompare(personA, personB) // 1\ncompare(personB, personA) // -1\n\n[personA, personB].sort(compare) // [personB, personA]\n```\n\n### Compare By Multiple Keys\n\n```javascript\nconst threeFn = require('3fn')\n\nconst personA = {name: 'John', age: 46}\nconst personB = {name: 'John', age: 27}\n\nconst compare = threeFn('name', 'age') // Sort by name first, and by age second\n\ncompare(personA, personB) // 1\ncompare(personB, personA) // -1\n\n[personA, personB].sort(compare) // [personB, personA]\n```\n\n### Compare By Nested Keys\n\n```javascript\nconst threeFn = require('3fn')\n\nconst personA = {name: {first: 'John'}}\nconst personB = {name: {first: 'Andrew'}}\n\nconst compare = threeFn(['name', 'first'])\n\ncompare(personA, personB) // 1\ncompare(personB, personA) // -1\n\n[personA, personB].sort(compare) // [personB, personA]\n```\n\n## Related\n\nThis module is based on [3](https://github.com/lamansky/3), the three-way comparison module.\n\nIt is also part of the `fn` family of modules:\n\n* [efn](https://github.com/lamansky/efn): Extracted Function\n* [ffn](https://github.com/lamansky/ffn): Filtering Function\n* [jfn](https://github.com/lamansky/jfn): Joined Function\n* [mfn](https://github.com/lamansky/mfn): Memoized Function\n* [ofn](https://github.com/lamansky/ofn): Overloaded Function\n* [pfn](https://github.com/lamansky/pfn): Possible Function\n* [qfn](https://github.com/lamansky/qfn): Qualified Function\n* [vfn](https://github.com/lamansky/vfn): Variadic Function\n* [wfn](https://github.com/lamansky/wfn): Wrapper Function\n* [xfn](https://github.com/lamansky/xfn): Extended Function\n","readmeFilename":"readme.md"}