{"id":13760991,"url":"https://github.com/jamesmcnamara/shades","last_synced_at":"2026-01-22T11:25:43.277Z","repository":{"id":11010654,"uuid":"67984466","full_name":"jamesmcnamara/shades","owner":"jamesmcnamara","description":"A lodash-inspired lens-like library for Javascript","archived":false,"fork":false,"pushed_at":"2024-06-13T18:40:53.000Z","size":3602,"stargazers_count":419,"open_issues_count":3,"forks_count":14,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-10-20T11:10:31.812Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jamesmcnamara.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-12T07:06:05.000Z","updated_at":"2025-05-31T16:41:33.000Z","dependencies_parsed_at":"2024-01-02T23:42:41.386Z","dependency_job_id":"0e3e9dd0-b687-4db1-93bc-20e94f3aa148","html_url":"https://github.com/jamesmcnamara/shades","commit_stats":{"total_commits":163,"total_committers":7,"mean_commits":"23.285714285714285","dds":0.08588957055214719,"last_synced_commit":"40eb0f1054e506a9f1e09e8c5574dae7942c5195"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jamesmcnamara/shades","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmcnamara%2Fshades","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmcnamara%2Fshades/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmcnamara%2Fshades/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmcnamara%2Fshades/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamesmcnamara","download_url":"https://codeload.github.com/jamesmcnamara/shades/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesmcnamara%2Fshades/sbom","scorecard":{"id":504025,"data":{"date":"2025-08-11","repo":{"name":"github.com/jamesmcnamara/shades","commit":"40eb0f1054e506a9f1e09e8c5574dae7942c5195"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":1.9,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":1,"reason":"Found 1/10 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 22 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"34 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg","Warn: Project is vulnerable to: GHSA-x9w5-v3q2-3rhw","Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275","Warn: Project is vulnerable to: GHSA-w573-4hg7-7wgq","Warn: Project is vulnerable to: GHSA-434g-2637-qmqr","Warn: Project is vulnerable to: GHSA-49q7-c7j4-3p7m","Warn: Project is vulnerable to: GHSA-977x-g7h5-7qgw","Warn: Project is vulnerable to: GHSA-f7q4-pwc6-w24p","Warn: Project is vulnerable to: GHSA-fc9h-whq2-v747","Warn: Project is vulnerable to: GHSA-vjh7-7g9h-fjfh","Warn: Project is vulnerable to: GHSA-fjxv-7rqg-78g4","Warn: Project is vulnerable to: GHSA-4q6p-r6v2-jvc5","Warn: Project is vulnerable to: GHSA-43f8-2h32-f4cj","Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h","Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv","Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3","Warn: Project is vulnerable to: GHSA-vh95-rmgr-6w4m","Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h","Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55","Warn: Project is vulnerable to: GHSA-5g97-whc9-8g7j","Warn: Project is vulnerable to: GHSA-8r4g-cg4m-x23c","Warn: Project is vulnerable to: GHSA-hj48-42vr-x3v9","Warn: Project is vulnerable to: GHSA-h7cp-r72f-jxh6","Warn: Project is vulnerable to: GHSA-v62p-rq8g-8h59","Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6","Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm","Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw","Warn: Project is vulnerable to: GHSA-76p7-773f-r4q5","Warn: Project is vulnerable to: GHSA-g4rg-993r-mgx7","Warn: Project is vulnerable to: GHSA-f5x3-32g6-xq36","Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-19T22:49:45.045Z","repository_id":11010654,"created_at":"2025-08-19T22:49:45.045Z","updated_at":"2025-08-19T22:49:45.045Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28662022,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T01:17:37.254Z","status":"online","status_checked_at":"2026-01-22T02:00:07.137Z","response_time":144,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T13:01:30.791Z","updated_at":"2026-01-22T11:25:43.222Z","avatar_url":"https://github.com/jamesmcnamara.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Libraries"],"sub_categories":["Lenses"],"readme":"![shades](imgs/shades.svg)\n\n## shades\n\n1. [intro](#intro)\n2. [playground](#try)\n3. [guide](#guide)\n 1. [Traversals](#traversals)\n 2. [Folds](#folds)\n 3. [Virtual Lenses](#virtual)\n4. [api](#api)\n\n## _New in v2!_\n\n- Rich and fully type-safe Typescript support!\n- 0 dependencies!\n- \u003c 5kb (gzipped) build!\n\n## Watch an Introduction\n\n[![Video Introduction](https://img.youtube.com/vi/_D3IPecC0S8/0.jpg)](https://www.youtube.com/watch?v=_D3IPecC0S8)\n\n\u003ca name=\"intro\"\u003e\u003c/a\u003e\nShades is a [lodash](https://github.com/lodash/lodash) inspired [lens](https://www.schoolofhaskell.com/school/to-infinity-and-beyond/pick-of-the-week/basic-lensing)-like library.\n_(Psst! Don't want to learn about lenses? Start with the [collection functions](#collection-transformations) to see how you can clean up your Iterable code, or check out the magic of [`into`](#into))._\n\nA lens is a path into an object, which can be used to extract its values, or even \"modify\" them in place (by creating a new object with the value changed).\n\nWhen writing immutable code, we very commonly end up with nested data stores, e.g.:\n\n```js\nconst store = {\n users: [\n {\n name: 'Jack Sparrow',\n posts: [\n {\n title: 'Why is the rum always gone? An analysis of Carribean trade surplus'\n }\n ],\n ...\n },\n ...\n ]\n}\n```\n\nAnd updating a nested structure will require heavy usage of the spread operator (or `Object.assign`). E.g. To capitalize the title of the first post of the first user, you would write:\n\n```js\nconst userIdx = 0;\nconst postIdx = 0;\nconst capitalize = (string) =\u003e {...}\n\n{...store,\n users: store.users.map((user, idx) =\u003e (\n idx === userIdx\n ? {...user,\n posts: user.posts.map((post, idx) =\u003e\n idx === postIdx\n ? {\n ...post,\n title: capitalize(post.title)\n }\n : post)\n }\n : user\n ))\n}\n```\n\nThis is an enormous amount of obfuscating boiler plate code for a very simple update.\n\nWith lenses, we could write this update much more declaratively:\n\n```js\nmod('users', userIdx, 'posts', postIdx, 'title')\n (capitalize)\n (store);\n```\n\n![Deal with it](imgs/deal-with-it.gif)\n\n### Typings\n\nIf you're using TypeScript, you'll benefit from very robust type-checking. For example if we had typed the above as:\n\n```js\nmod('users', userIdx, 'pots', postIdx, 'title')(capitalize)(store)\n```\n\nTS will error on `store` because it doesn't have an attribute `pots`. Similarly,\n\n```typescript\nmod('users', userIdx, 'posts', postIdx, 'title')((x: number) =\u003e x + 1)(store);\n```\n\nwill error because the type of `title` is `string` and not `number`\n\n## \u003ca name=\"try\"\u003e\u003c/a\u003eTry It Out\n\nshades contains a little node playground that you can use to follow along with the guide or generally mess around with it.\n\nYou can run it with [`npx`](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b)(which you already have if you're running `npm@^5.2.x`):\n\n```sh\nnpx shades\n```\n\nOr the old fashioned way\n\n```sh\nnpm install --global shades\nshades\n```\n\n## \u003ca name=\"guide\"\u003e\u003c/a\u003e Let's Talk About Lens, Baby\n\nFor reference, we will use the following objects:\n\u003ca name=\"store\"\u003e\u003c/a\u003e\n\n```js\nconst jack = {\n name: 'Jack Sparrow',\n goldMember: false,\n posts: [\n {\n title:\n 'Why is the rum always gone? An analysis of Carribean trade surplus',\n likes: 5\n },\n {\n title: 'Sea Turtles - The Tortoise and the Hair',\n likes: 70\n }\n ]\n};\n\nconst liz = {\n name: 'Elizabeth Swan',\n goldMember: true,\n posts: [\n {\n title: 'Bloody Pirates - My Life Aboard the Black Pearl',\n likes: 10000\n },\n {\n title:\n 'Guidelines - When YOU need to be disinclined to acquiesce to their request',\n likes: 5000\n }\n ]\n};\n\nconst bill = {\n name: 'Bill Turner',\n goldMember: false,\n posts: [\n {\n title: 'Bootstraps Bootstraps - UEFI, GRUB and the Linux Kernel',\n likes: 3000\n }\n ]\n};\n\nconst store = {\n users: [jack, liz, bill],\n byName: {\n jack,\n liz,\n bill\n }\n};\n```\n\n#### Baby's first lens\n\nConceptually, a lens is something that represents a path through an object.\n\nThe simplest lens is a string or number path like `'name'` or `0`. Strings represent object properties and numbers represent Array or Object indexes.\n\n`get` is the simplest lens consumer. It takes a lens into an object and produces a function that will take an object and produce the _focus_ of that lens (focus = final value referenced by the lens, i.e. `name` or `posts`). Using the examples from above:\n\n```js\n\u003e const getName = get('name')\n\u003e getName(jack)\n'Jack Sparrow'\n```\n\nor more succinctly:\n\n```js\n\u003e get('name')(jack)\n'Jack Sparrow'\n```\n\nMultiple lenses can be passed in to `get` and they will be composed left-to-right:\n\n```js\n\u003e get('users', 0, 'name')(store)\n'Jack Sparrow'\n```\n\nThis is all well and good, but that `0` is unrealistic. We rarely know _which_ index of an array we need to edit, instead we want to update all elements that match some criterion. Thus we need a way to focus on multiple points in an array (or object).\n\n#### \u003ca name=\"traversals\"\u003e\u003c/a\u003eBaby's first traversal\n\nThis is where stuff starts to get interesting.\n\n[Traversals](#traversals) split the focus of lenses into _multiple_ focus points. These can be particularly helpful when working with arrays.\n\nThe simplest traversal is [`all`](#all). `all` focuses on every element of an array (or every value in an object).\n\n```js\n\u003e get('users', all, 'posts')(store)\n[\n [ { title: 'Why is the rum always gone? An analysis of Carribean trade surplus', likes: 5} ],\n [ { title: 'Bloody Pirates - My Life Aboard the Black Pearl', likes: 10000 } ]\n]\n```\n\n_Note: if you are using the TypeScript bindings, you MUST call `all` as a function, e.g. `get('users', all(), 'posts')`. It behaves exactly the same way._\n\nTraversals can be used anywhere a lens is used. However, as you can see above, when `all` appears in a composition, everything after is applied to every element of a collection, instead of on a single object. In this way, traversals act like prisms:\n\n![Dark Side](imgs/dark-side.jpg)\n\nMultiple traversals can be composed into a single lens. Each traversal in the lens will result to a further level of nesting in the output\n\n```js\n\u003e get('users', all, 'posts', all, 'likes')(store)\n[[5], [100000]]\n```\n\nAbove, we focused on the `users` key of the store, then for every user in the `users` array we focused on the posts array, and then for every post in THAT array we focused on the `likes` key.\n\n`all` will always produce an array in the output, and so we got an array for when we traversed over `users`, and another nested array when we traversed over `posts`. Pretty neat, huh?\n\n#### Modifications\n\n`get`ting data is all well and good, but where shades really shines is performing immutable updates. The good news is everything we have learned up until now translates seamlessly.\n\nMeet `mod`. `mod` is a lot like `get`: it accepts lenses and produces a function. The difference is, before we pass `mod` an object to act on, we pass it a function that transforms the focus of the lens. Then we pass it an object, and instead of producing the focus of the object (like `get`) it will produce a copy of the entire object, with the focus of the lens transformed by your function.\n\n```js\n\u003e const transformer = mod('users', 0, 'posts', 0, 'likes')(likes =\u003e likes + 1)\n\u003e transformer(store)\n{\n users: [\n {\n name: 'Jack Sparrow',\n goldMember: false,\n posts: [\n {\n title: 'Why is the rum always gone? An analysis of Carribean trade surplus',\n likes: 6, // \u003c---- Incremented!!\n }\n ]\n },\n { ... },\n { ... }\n ]\n}\n```\n\nThis transform was done immutably, so our original `store` is unmodified.\n\n`mod` also works with traversals:\n\n```js\n\u003e mod('users', all, 'posts', all, 'likes')(likes =\u003e likes + 1)(store)\n{\n users: [\n {\n name: 'Jack Sparrow',\n goldMember: false,\n posts: [\n {\n title: 'Why is the rum always gone? An analysis of Carribean trade surplus',\n likes: 6, // \u003c---- Incremented!!\n }\n ]\n },\n {\n name: 'Elizabeth Swan',\n goldMember: true,\n posts: [\n {\n title: 'Bloody Pirates - My Life Aboard the Black Pearl',\n likes: 10001, // \u003c---- Also Incremented!! Wow!\n }\n ]\n },\n { ... }\n ]\n}\n```\n\nNow you're ready to start cooking with gas! If you wanna see an even cooler traversal, check out [`matching`](#matching). Or just check out some of the API below, there's a\nlot of really great stuff we didn't even get a chance to touch on.\n\n### Epilogue: Folds and Virtual Lenses\n\nYou'll be able to get pretty dang far with just the built in lenses and traversals described above. But if you really want to dive down the rabbit hole, there's even more\nyou can do with lenses.\n\n#### \u003ca name=\"folds\"\u003e\u003c/a\u003eFolds\n\nTraversals allowed us to focus on multiple elements from a collection at once, but what if we just want to focus on a single element in a collection; one that fits some\ncriterion. This is a fold. Think of `Array::reduce`; folds operate very similarly. There are some built-in folds that should help you get the hang of it. For instance, [`findBy`](#findBy):\n\n```js\n\u003e get('users', findBy(user =\u003e user.name === 'Jack Sparrow'), 'name')\n'Jack Sparrow'\n```\n\nThere are other folding lenses such as `maxBy`, and `minBy` (guess what they do). They all support the [`into` shorthand](#into):\n\n```js\n\u003e get('users', findBy({name: includesi('jack')}), 'name')(store)\n'Jack Sparrow'\n\n\u003e get('users', findBy('Elizabeth Swan'), 'posts', maxBy('likes'), 'title')\n'Bloody Pirates - My Life Aboard the Black Pearl'\n```\n\n#### \u003ca name=\"virtual\"\u003e\u003c/a\u003eVirtual Lenses\n\nLenses are not magic. They are just objects with a `get` and a `mod` field. You can create easily create your own; in fact, this is how [folds](#folds) are implemented.\n\nFor example, let's say that your data represents temperature in Celsius, but being an American, you only understand Fahrenheit. We just need to create a `get`\nfunction that takes a temperature in Celsius transforms it to Fahrenheit, and then a function `mod` that takes a _function_ from Fahrenheit to Fahrenheit, and produces\na Celsius to Celsius function.\n\nlet's start with some conversion functions:\n\n```javascript\nconst ftoc = f =\u003e (f - 32) / 1.8;\nconst ctof = c =\u003e c * 1.8 + 32;\n```\n\nour `get` function is just `ctof` (by definition it is a Celsius to Fahrenheit function), but our `mod` function is more complicated. We will get an updater that works on Fahrenheit, but we need to produce a Celsius updater. So we will create a function that takes the temperature in Celsius, converts it to Fahrenheit, runs it through the updater, and converts the result back to Celsius:\n\n```js\nconst inF = {\n get: ctof,\n mod: ftof =\u003e c =\u003e ftoc(ftof(ctof(c)))\n};\n```\n\nNow we have a lens that will let us view and update temperatures in Celsius as if they are in Fahrenheit\n\n```js\nconst weather = { temp: 35 }\n\n\u003e get('temp')(weather)\n35\n\n\u003e get('temp', inF)(weather)\n95\n\n\u003e mod('temp', inF)(x =\u003e x + 1)(weather)\n{ temp: 35.56 }\n\n\u003e set('temp', inF)(23)(weather)\n{ temp: -5 }\n```\n\nFor more details on virtual lenses, watch my talk at Reactathon:\n\n[![Video Introduction](https://img.youtube.com/vi/_D3IPecC0S8/0.jpg)](https://www.youtube.com/watch?v=_D3IPecC0S8)\n\n## \u003ca name=\"api\"\u003eAPI\u003c/a\u003e\n\n#### _A Note on Type Signatures_\n\nIt's not necessary to fully grok the type signatures when you read them, but if you do want to understand some of the custom types,\nthey can be found in [types/utils.ts](types/utils.ts)\n## \u003ca href=collection-transformations\u003eCollection Transformations\u003c/a\u003e\nWe all love `Array::map`, `Array::filter`, etc. but what do you do when you have an object, or a Map? \nEven if you're just using arrays, defining an arrow function to just extract a property, or test if a\nkey has a certain value is clunky.\n\nEnter shades. Shades provides collection functions that work polymorphically over many different object\ntypes, and are powered by [`into`](#into). _(And they're pretty fast, too)_.\n\n```js\n\u003e map('name')(store.users)\n['jack', 'liz', 'bill']\n\n\u003e map('goldMember')(store.byName)\n{\n jack: false, \n liz: true, \n bill: false\n }\n\n\u003e filter({name: 'jack'})(store.users)\n[jack]\n```\n\n### \u003ca href='filter'\u003efilter\u003c/a\u003e\n```typescript\nexport function filter\u003cK extends string\u003e(k: K): \u003cF extends Collection\u003cHasKey\u003cK\u003e\u003e\u003e(f: F) =\u003e F;\nexport function filter\u003cA\u003e(f: (a: A) =\u003e any): \u003cF\u003e(f: F) =\u003e F;\nexport function filter\u003cPattern\u003e(p: Pattern): \u003cF extends Collection\u003cHasPattern\u003cPattern\u003e\u003e\u003e(f: F) =\u003e F;\n```\n\nTakes an [into pattern](#into) from `A =\u003e boolean` and produces a function that takes a [Collection](types/utils.ts)\nand produces a collection of the same type, with all items that failed the test removed.\n\n```js\n\u003e filter(isEven)([1, 2, 3, 4])\n[2, 4]\n\n\u003e filter((value, key) =\u003e isEven(key) \u0026\u0026 isOdd(value))({2: 1, 3: 1})\n{2: 1}\n\n\u003e filter(isEven)(new Set([1, 2, 3, 4]))\nSet({2, 4})\n\n\u003e filter('goldMember')(store.users)\n[liz]\n\n\u003e filter({posts: includes({likes: lessThan(10)})})(store.users)\n[jack]\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cUser[]\u003e(filter((user: User) =\u003e user.friends.length \u003e 0)(users));\nexpectType\u003c{ [name: string]: User; }\u003e(filter((user: User) =\u003e user.name)(byName));\nexpectType\u003cUser[]\u003e(filter('name')(users));\nexpectType\u003c{ [name: string]: User; }\u003e(filter('name')(byName));\nexpectError(filter('butts')(users));\nexpectType\u003cUser[]\u003e(filter({ name: 'john' })(users));\nexpectType\u003c{ [name: string]: User; }\u003e(filter({ name: 'john' })(byName));\nexpectError(filter({\n settings: (settings: string) =\u003e settings\n})(users));\nexpectType\u003cUser[]\u003e(filter({\n settings: (settings: Settings) =\u003e settings\n})(users));\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should work on lists', () =\u003e {\n filter(greaterThan(2))([1, 2, 3]).should.deep.equal([3]);\n});\n\nit('should work on objects', () =\u003e {\n filter(greaterThan(2))({ a: 1, b: 2, c: 3 }).should.deep.equal({ c: 3 })\n});\n\nit('should work on Maps', () =\u003e {\n filter('goldMember')(\n new Map(Object.entries(store.byName))\n ).should.deep.equal(new Map([['liz', liz]]));\n});\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='map'\u003emap\u003c/a\u003e\n```typescript\nexport function map\u003cK extends string\u003e(k: K): \u003cF extends Container\u003cHasKey\u003cK\u003e\u003e\u003e(f: F) =\u003e Functor\u003cF, Unpack\u003cF\u003e, KeyAt\u003cUnpack\u003cF\u003e, K\u003e\u003e;\nexport function map(i: number): \u003cF extends Container\u003cIndexable\u003e\u003e(f: F) =\u003e Functor\u003cF, Unpack\u003cF\u003e, Index\u003cUnpack\u003cF\u003e\u003e\u003e;\nexport function map\u003cA, B\u003e(f: (a: A) =\u003e B): \u003cF extends Container\u003cA\u003e\u003e(f: F) =\u003e Functor\u003cF, A, B\u003e;\nexport function map\u003cPattern\u003e(p: Pattern): \u003cA extends HasPattern\u003cPattern\u003e, F extends Container\u003cA\u003e\u003e(f: F) =\u003e Functor\u003cF, A, boolean\u003e;\n```\n\nTakes an [into pattern](#into) from `A =\u003e B` and produces a function that takes a [Container](types/utils.ts)\nof `A`s and produces the same type of container with `B`s\n\n```js\n\u003e map(inc)([1, 2, 3, 4])\n[2, 3, 4, 5]\n\n\u003e map((value, key) =\u003e `${value} was at {key}`)({a: 1, b: 2})\n{a: '1 was at a', b: '2 was at b'}\n\n\u003e map((value, key) =\u003e `${value} was at {key}`)(new Map([['a', 1], ['b', 2]])\nMap {a =\u003e '1 was at a', b =\u003e '2 was at b'}\n\n\u003e map('goldMember')(store.byName)\n {jack: false, liz: true, bill: false}\n\n\u003e map({name: includes('Bill')})(store.users)\n[false, false, true]\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cstring[]\u003e(map('name')(users));\nexpectType\u003c{ [key: string]: string; }\u003e(map('name')(byName));\nexpectError(map('not-a-key')(users));\nexpectError(map('not-a-key')(byName));\nexpectType\u003c(User | undefined)[]\u003e(map('bestFriend')(users))\nconst usersFriends = map('friends')(users)\nexpectType\u003cUser[][]\u003e(usersFriends);\nexpectType\u003cUser[]\u003e(map(1)(usersFriends));\nexpectError(map(1)(users));\nconst usersFriendsByName = map('friends')(byName)\nexpectType\u003c{ [key: string]: User[]; }\u003e(usersFriendsByName);\nexpectType\u003c{ [key: string]: User; }\u003e(map(2)(usersFriendsByName));\nexpectType\u003cstring[]\u003e(map((x: User) =\u003e x.name)(users));\nexpectType\u003cboolean[]\u003e(map({ name: 'john', settings: (settings: Settings) =\u003e !!settings })(users));\nexpectType\u003c{ [key: string]: boolean; }\u003e(map({ name: 'john', settings: (settings: Settings) =\u003e !!settings })(byName));\n\ndeclare const fetchUsers: Promise\u003cUser[]\u003e\n// Nested maps require type annotations, but still provide safety\nexpectType\u003cPromise\u003cstring[]\u003e\u003e(map\u003cUser[], string[]\u003e(map('name'))(fetchUsers))\nexpectError(map\u003cUser[], boolean[]\u003e(map('name'))(fetchUsers))\n\ndeclare const userMap: Map\u003cstring, User\u003e\ndeclare const userSet: Set\u003cUser\u003e\nexpectType\u003cMap\u003cstring, string\u003e\u003e(map('name')(userMap))\nexpectType\u003cSet\u003cstring\u003e\u003e(map('name')(userSet))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should work on lists', () =\u003e {\n map(inc)([1, 2, 3]).should.deep.equal([2, 3, 4])\n});\n\nit('should work on objects', () =\u003e {\n map(inc)({ a: 1, b: 2, c: 3 }).should.deep.equal({ a: 2, b: 3, c: 4 })\n})\n\nit('should receive key as second param', () =\u003e {\n map((value, key) =\u003e value + key)({a: 1}).should.deep.equal({a: '1a'})\n})\n\nit('should work on maps', () =\u003e {\n const input = new Map([['a', 1], ['b', 2], ['c', 3]])\n const output = new Map([['a', 2], ['b', 3], ['c', 4]])\n map(inc)(input).should.deep.equal(output)\n})\n\nit('should work on sets', () =\u003e {\n const input = new Set([1, 2, 3])\n const output = new Set([2, 3, 4])\n map(inc)(input).should.deep.equal(output)\n})\n\nit('should work on promises', () =\u003e {\n const p = Promise.resolve({a: 1})\n return map('a')(p).should.eventually.equal(1)\n})\n\nit('should work with shorthand', () =\u003e {\n map('a')([{ a: 1 }, { a: 2 }, { a: 3 }]).should.deep.equal([1, 2, 3]);\n\n map('a')({ d: { a: 1 }, c: { a: 2 }, e: { a: 3 } }).should.deep.equal({\n d: 1,\n c: 2,\n e: 3\n });\n \n map({ a: 1 })([{ a: 1 }, { a: 2 }, { a: 3 }]).should.deep.equal([\n true,\n false,\n false\n ]);\n});\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='find'\u003efind\u003c/a\u003e\n```typescript\nexport function find\u003cKey extends string\u003e(f: Key): \u003cA extends HasKey\u003cKey\u003e\u003e(f: Collection\u003cA\u003e) =\u003e (A | undefined);\nexport function find\u003cA\u003e(f: (a: A) =\u003e any): (f: Collection\u003cA\u003e) =\u003e (A | undefined);\nexport function find\u003cPattern\u003e(p: Pattern): \u003cA extends HasPattern\u003cPattern\u003e\u003e(f: Collection\u003cA\u003e) =\u003e (A | undefined);\n```\n\nTakes an [into pattern](#into) from `A =\u003e any` and produces a function that takes a \n[`Collection`](#collection-type) returns the first item in the collection that returns \na truthy value for the test (or `undefined` if none match)\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cUser | undefined\u003e(find('name')(users));\nexpectError(find('fart')(users));\nexpectType\u003cUser | undefined\u003e(find((user: User) =\u003e user.friends)(users));\nexpectType\u003cUser | undefined\u003e(find((user: User) =\u003e user.friends.length \u003e 0)(users));\nexpectType\u003cUser | undefined\u003e(find({ name: 'barg' })(users));\nexpectError(find({ name: false })(users));\nexpectType\u003cUser | undefined\u003e(find({ name: (s: string) =\u003e !!'barg' })(users));\nexpectError(find({ name: (s: Settings) =\u003e !!'barg' })(users));\nconst a = find({\n friends: find({ name: 'silent bob' })\n})(users);\nexpectType\u003cUser | undefined\u003e(a);\nexpectError(find({ settings: { permissions: false } })(users));\nexpectError(find({\n settings: { permissions: false }\n})(users));\nexpectType\u003cUser | undefined\u003e(find({\n settings: { permissions: (perm: string) =\u003e !!perm }\n})(users));\nexpectError(find({\n settings: { permissions: (perm: boolean) =\u003e !!perm }\n})(users));\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should work on lists', () =\u003e {\n find(user =\u003e user.isLive)([\n { isLive: true, name: 'jack' }\n ]).name.should.equal('jack');\n find('isLive')([{ isLive: true, name: 'jack' }]).name.should.equal(\n 'jack'\n );\n find({ name: 'jack' })([{ isLive: true, name: 'jack' }]).isLive.should\n .be.true;\n});\n\nit('should work on objects', () =\u003e {\n find(user =\u003e user.isLive)({\n jack: { isLive: true, name: 'jack' }\n }).name.should.equal('jack');\n find('isLive')({\n jack: { isLive: true, name: 'jack' }\n }).name.should.equal('jack');\n find({ name: 'jack' })({ jack: { isLive: true, name: 'jack' } }).isLive\n .should.be.true;\n});\n\nit('should work on Maps', () =\u003e {\n find('goldMember')(\n new Map(Object.entries(store.byName))\n ).should.deep.equal(liz);\n});\n\nit('should work on Sets', () =\u003e {\n find('goldMember')(\n new Set(Object.values(store.byName))\n ).should.deep.equal(liz);\n});\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='some'\u003esome\u003c/a\u003e\n```typescript\nexport function some\u003cKey extends string\u003e(f: Key): (f: Collection\u003cHasKey\u003cKey\u003e\u003e) =\u003e boolean;\nexport function some\u003cA\u003e(f: (a: A) =\u003e any): (f: Collection\u003cA\u003e) =\u003e boolean;\nexport function some\u003cPattern\u003e(p: Pattern): (f: Collection\u003cHasPattern\u003cPattern\u003e\u003e) =\u003e boolean;\n```\n\nTakes an [into pattern](#into) and returns a function that takes a [`Collection`](#collection-type)\nand returns true if there is any member in the collection that returns `true` for the test\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cboolean\u003e(some('name')(users));\nexpectType\u003cboolean\u003e(some((user: User) =\u003e user.friends)(users));\nexpectType\u003cboolean\u003e(some((user: User) =\u003e user.friends.length \u003e 0)(users));\nexpectType\u003cboolean\u003e(some({ name: 'barg' })(users));\nexpectError(some({ name: false })(users));\nexpectType\u003cboolean\u003e(some({ name: (s: string) =\u003e !!'barg' })(users));\nexpectError(some({ name: (s: boolean) =\u003e !!'barg' })(users));\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should work on lists', () =\u003e {\n some(user =\u003e user.isLive)([\n { isLive: true, name: 'jack' }\n ]).should.be.true\n some('isLive')([{ isLive: true, name: 'jack' }]).should.be.true\n some({ name: 'jack' })([{ isLive: true, name: 'jack' }]).should.be.true\n some({ name: 'john' })([{ isLive: true, name: 'jack' }]).should.be.false\n some(user =\u003e user.isLive)([{ isLive: true, name: 'jack' }]).should.be.true\n some(user =\u003e !user.isLive)([{ isLive: true, name: 'jack' }]).should.be.false\n});\n\nit('should work on objects', () =\u003e {\n some(user =\u003e user.isLive)({\n jack: { isLive: true, name: 'jack' }\n }).should.be.true\n some('isLive')({\n jack: { isLive: true, name: 'jack' }\n }).should.be.true\n some({ name: 'jack' })({ jack: { isLive: true, name: 'jack' } }).should.be.true;\n});\n\nit('should work on Maps', () =\u003e {\n some('goldMember')(\n new Map(Object.entries(store.byName))\n ).should.be.true\n});\n\nit('should work on Sets', () =\u003e {\n some('goldMember')(\n new Set(store.users)\n ).should.be.true\n\n some({name: s =\u003e s.includes('z')})(\n new Set(store.users)\n ).should.be.true\n\n some({name: s =\u003e s.includes('x')})(\n new Set(store.users)\n ).should.be.false\n});\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='cons'\u003econs\u003c/a\u003e\n```typescript\nexport function cons\u003cA\u003e(a: A): (as: A[]) =\u003e A[]\n```\n\nConsumes an element `x` and an array `xs` and returns a new array with `x` \nAPPENDED to `xs` (not prepended, which is more typical with `cons` and lists. This \nis to make it easier to use in pipelined scenarios)\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber[]\u003e(cons(1)([1, 2, 3]));\nexpectType\u003cstring[]\u003e(cons('a')(['a', 'b', 'c']));\nexpectError(cons(1)(2));\nexpectError(cons(1)(['a', 'b', 'c']));\nexpectError(cons('1')([1, 2, 3]));\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should concat lists', () =\u003e {\n cons(1)([1, 2, 3]).should.deep.equal([1, 2, 3, 1]);\n expect(() =\u003e cons(1)(2)).to.throw(\n 'Invalid attempt to spread non-iterable instance'\n );\n});\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='unshift'\u003eunshift\u003c/a\u003e\n```typescript\nexport function unshift\u003cA\u003e(a: A): (as: A[]) =\u003e A[]\n```\n\nConsumes an element `x` and an array `xs` and returns a new array with `x` \nprepended to `xs`.\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber[]\u003e(unshift(1)([1, 2, 3]));\nexpectType\u003cstring[]\u003e(unshift('a')(['a', 'b', 'c']));\nexpectError(unshift(1)(2));\nexpectError(unshift(1)(['a', 'b', 'c']));\nexpectError(unshift('1')([1, 2, 3]));\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should prepend items to a list', () =\u003e {\n unshift(1)([1, 2, 3]).should.deep.equal([1, 1, 2, 3]);\n expect(() =\u003e unshift(1)(2)).to.throw(\n 'Invalid attempt to spread non-iterable instance'\n );\n});\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='first'\u003efirst\u003c/a\u003e\n```typescript\nexport function first(s: string): string\nexport function first\u003cA\u003e(xs: A[]): A\n```\n\nExtracts the first element of a collection\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber\u003e(first([1, 3, 4]));\nexpectType\u003cUser\u003e(first(users));\nexpectType\u003cstring\u003e(first('hi'));\nexpectError(first(true));\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should extract the first element', () =\u003e {\n first([1, 2, 3]).should.equal(1);\n first('hello').should.equal('h');\n should.not.exist(first([]));\n});\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='rest'\u003erest\u003c/a\u003e\n```typescript\nexport function rest\u003cA\u003e(xs: A[]): A[]\n```\n\nExtracts everything from the list except for the head\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber[]\u003e(rest([1, 3, 4]));\nexpectType\u003cUser[]\u003e(rest(users));\nexpectError(rest('hi'));\nexpectError(rest(true));\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should extract the tail', () =\u003e {\n rest([1, 2, 3]).should.deep.equal([2, 3]);\n rest([]).should.deep.equal([]);\n});\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='push'\u003epush\u003c/a\u003e\n```typescript\nexport function push\u003cA\u003e(a: A): (as: A[]) =\u003e A[]\n```\n\nAlias for [`cons`](#cons)\n\n\n\n\n### \u003ca href='concat'\u003econcat\u003c/a\u003e\n```typescript\nexport function concat\u003cA\u003e(as: A[]): (bs: A[]) =\u003e A[]\n```\n\nTakes two arrays and concatenates the first on to the second.\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber[]\u003e(concat([1, 2, 3])([2, 3]));\n// [2, 3, 1, 2, 3]\nexpectType\u003cstring[]\u003e(concat(['hi'])(['wo']));\n// ['wo', 'hi']\nexpectError(concat(['hi'])([1, 2, 3]));\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should concatenate lists in reverse order', () =\u003e {\n concat([1, 2, 3])([2, 3]).should.deep.equal([2, 3, 1, 2, 3]);\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='append'\u003eappend\u003c/a\u003e\n```typescript\nexport function append\u003cA\u003e(as: A[]): (bs: A[]) =\u003e A[]\n```\n\nAlias for [`concat`](#concat)\n\n\n\n\n### \u003ca href='prepend'\u003eprepend\u003c/a\u003e\n```typescript\nexport function prepend\u003cA\u003e(as: A[]): (bs: A[]) =\u003e A[]\n```\n\nTakes two arrays and concatenates the second on to the first.\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber[]\u003e(prepend([1, 2, 3])([2, 3]));\n// [1, 2, 3, 2, 3]\nexpectType\u003cstring[]\u003e(prepend(['hi'])(['wo']));\n// ['hi', 'wo']\nexpectError(prepend(['hi'])([1, 2, 3]));\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should concatenate lists in lexical order', () =\u003e {\n prepend([1, 2, 3])([2, 3]).should.deep.equal([1, 2, 3, 2, 3]);\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n\n### \u003ca href='into'\u003einto\u003c/a\u003e\n```typescript\nexport function into\u003cFn extends (...a: any[]) =\u003e any\u003e(f: Fn): Fn;\nexport function into\u003cKey extends string\u003e(f: Key): \u003cObj extends HasKey\u003cKey\u003e\u003e(s: Obj) =\u003e Obj[Key];\nexport function into\u003cPattern extends object\u003e(p: Pattern): (o: HasPattern\u003cPattern\u003e) =\u003e boolean;\n```\n\n`into` is the engine of much of shades' magical goodness. It takes either a string or object \n(or function) and turns it into a useful function. All of shades [collection functions](#collection-transformations)\nwill automatically pass their inputs into `into`, creating a useful shorthand.\n\nThe transformation follows one of the following 3 rules:\n* a **function** is returned as is (easy enough)\n* a **string** or **number** is converted into a lens accessor with [`get`](#get)\n* an **object** is converted into a predicate function using the function [`has`](#has). This one is the most interesting, and\nrequires some explanation.\n\nIn the simplest form, a pattern of keys and values will produce a function that takes a test \nvalue and returns `true` if the given test value has at least the equivalent keys and values \nof the pattern. Using the [store](#store) example from above:\n\n```js\n// Tests if an object passed to it has the key goldMember mapped to true\n\u003e const isGoldMember = into({goldMember: true})\n\u003e isGoldMember(jack)\nfalse\n\n// test multiple values\n\u003e into({goldMember: true, name: \"Elizabeth Swan\"})(liz)\ntrue\n```\n\nNested values work just as you'd expect:\n```js\n\u003e into({jack: {goldMember: false}})(store.byName)\ntrue\n```\n\nWhere it REALLY gets interesting is when the _values_ in your pattern are predicate functions. \nIn this case, the value at that key in the test object is passed to the function, and validation \nonly continues if that function returns `true`\n\n```js\n// Tests if the object passed to it has a title attribute that is less than 50 letters long\n\u003e const hasShortTitle = into({title: title =\u003e title.length \u003c 50})\n\u003e hasShortTitle(jack.posts[0])\nfalse\n```\nThis pattern is especially useful with [lenses and traversals](#guide)\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber\u003e(into('a')({a: 10}))\nexpectError(into('b')({a: 10}))\nexpectType\u003cboolean\u003e(into({a: 10})({a: 10}))\nexpectError(into({a: 10})({b: 10}))\nexpectType\u003cnumber\u003e(into((x: number) =\u003e x + 1)(10))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should use into to create functions', () =\u003e {\n into('a')({ a: 10 }).should.equal(10);\n into({ a: 10 })({ a: 10 }).should.be.true;\n into(x =\u003e x + 1)(10).should.equal(11);\n});\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n## \u003ca href=reducer-generators\u003eReducer generators\u003c/a\u003e\nReducer generators are functions that take [`into patterns`](#into) and produce specialized\nreducer functions (`(A, S) =\u003e A`):\n\n```js\n\u003e jack.posts.reduce(maxOf('likes'))\n{\n title: 'Sea Turtles - The Tortoise and the Hair',\n likes: 70\n}\n```\n\n### \u003ca href='maxOf'\u003emaxOf\u003c/a\u003e\n```typescript\nexport function maxOf\u003cKey extends string\u003e(k: Key): \u003cItem extends HasKey\u003cKey, number\u003e\u003e(acc: Item, current: Item) =\u003e Item\nexport function maxOf\u003cA\u003e(f: (a: A) =\u003e number): (acc: A, current: A) =\u003e A\n```\n\nA reducer generator that takes either a path or a getter function and producers \na reducer that will find the element in the collection that has the max of that\nproperty\n\n```js\n\u003e [{a: 1}, {a: 3}, {a: 2}].reduce(maxOf('a'))\n{ a: 3 }\n\n\u003e store.users.reduce(maxOf(user =\u003e user.name.length))\n{ name: 'Elizabeth Swan', ...}\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cPost\u003e(users[0].posts.reduce(maxOf('likes')))\nexpectError(users[0].posts.reduce(maxOf('title')))\nexpectError(users[0].posts.reduce(maxOf('farts')))\nexpectType\u003cUser\u003e(users.reduce(maxOf(user =\u003e user.name.length)))\nexpectError(users.reduce(maxOf(user =\u003e user.name)))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should find largest elements', () =\u003e {\n store.users.reduce(maxOf(user =\u003e user.name.length)).should.be.equal(liz)\n jack.posts.reduce(maxOf('likes')).likes.should.be.equal(70)\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='minOf'\u003eminOf\u003c/a\u003e\n```typescript\nexport function minOf\u003cKey extends string\u003e(k: Key): \u003cItem extends HasKey\u003cKey, number\u003e\u003e(acc: Item, current: Item) =\u003e Item\nexport function minOf\u003cItem\u003e(f: (a: Item) =\u003e number): (acc: Item, current: Item) =\u003e Item\n```\n\nThe opposite of [`maxOf`](#maxOf).\n\n\n\n\n### \u003ca href='findOf'\u003efindOf\u003c/a\u003e\n```typescript\nexport function findOf\u003cKey extends string\u003e(k: Key): \u003cItem extends HasKey\u003cKey\u003e\u003e(acc: Item, item: Item) =\u003e Item\nexport function findOf\u003cItem\u003e(f: (a: Item) =\u003e any): (acc: Item, current: Item) =\u003e Item\nexport function findOf\u003cPattern\u003e(p: Pattern): \u003cItem extends HasPattern\u003cPattern\u003e\u003e(acc: Item, item: Item) =\u003e Item\n```\n\nTakes an [into pattern](#into) and produces a reducer that returns either the accumulated item\nor the current item if it passes the given test.\n\n```js\n\u003e store.users.reduce(findOf('goldMember'))\nliz\n\n\u003e store.users.reduce(findOf({goldMember: false}))\njack\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cUser\u003e(users.reduce(findOf('name')))\nexpectType\u003cUser\u003e(users.reduce(findOf({name: 'butt'})))\nexpectError(users.reduce(findOf({butt: 'name'})))\nexpectType\u003cUser\u003e(users.reduce(findOf(user =\u003e user.name)))\nexpectError(users.reduce(findOf(user =\u003e user.butt)))\nexpectError(users.map(findOf(user =\u003e user.butt)))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('finds elements given a pattern', () =\u003e {\n store.users.reduce(findOf('name')).should.be.equal(store.users[0])\n store.users.reduce(findOf({name: liz.name})).should.be.equal(liz)\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='sumOf'\u003esumOf\u003c/a\u003e\n```typescript\nexport function sumOf\u003cKey extends string\u003e(k: Key): (acc: number, current: HasKey\u003cKey, number\u003e) =\u003e number\nexport function sumOf\u003cA\u003e(f: (a: A) =\u003e number): (acc: number, current: A) =\u003e number\n```\n\nA reducer generator that takes either a path or a getter function and producers \na reducer that will sum all of the values produced by the getter\n\n```js\n\u003e [{a: 1}, {a: 3}, {a: 2}].reduce(sumOf('a'), 0)\n6\n\n\u003e liz.posts.reduce(sumOf('likes'))\n15000\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber\u003e(users[0].posts.reduce(sumOf('likes'), 0))\nexpectError(users[0].posts.reduce(sumOf('title'), 0))\nexpectError(users[0].posts.reduce(sumOf('farts'), 0))\nexpectType\u003cnumber\u003e(users.reduce(sumOf(user =\u003e user.name.length), 0))\nexpectError(users.reduce(sumOf(user =\u003e user.name), 0))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should sum all elements specified by pattern', () =\u003e {\n store.users.reduce(sumOf(user =\u003e user.name.length)).should.be.equal(37)\n liz.posts.reduce(sumOf('likes')).should.be.equal(15000)\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='productOf'\u003eproductOf\u003c/a\u003e\n```typescript\nexport function productOf\u003cKey extends string\u003e(k: Key): (acc: number, current: HasKey\u003cKey, number\u003e) =\u003e number\nexport function productOf\u003cA\u003e(f: (a: A) =\u003e number): (acc: number, current: A) =\u003e number\n```\n\nA reducer generator that takes either a path or a getter function and producers \na reducer that will multiply all of the values produced by the getter\n\n```js\n\u003e [{a: 1}, {a: 30}, {a: 2}].reduce(productOf('a'), 1)\n60\n\n\u003e liz.posts.reduce(productOf('likes'))\n50000000\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber\u003e(users[0].posts.reduce(productOf('likes'), 1))\nexpectError(users[0].posts.reduce(productOf('title'), 1))\nexpectError(users[0].posts.reduce(productOf('farts'), 1))\nexpectType\u003cnumber\u003e(users.reduce(productOf(user =\u003e user.name.length), 1))\nexpectError(users.reduce(productOf(user =\u003e user.name), 1))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should multiply all elements specified by pattern', () =\u003e {\n store.users.reduce(productOf(user =\u003e user.name.length)).should.be.equal(1848)\n liz.posts.reduce(productOf('likes')).should.be.equal(50000000)\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n\n### \u003ca href='identity'\u003eidentity\u003c/a\u003e\n```typescript\nexport function identity\u003cA\u003e(a: A): A\n```\n\nIdentity function. Not much to say about this one. You give it something,\nit gives it back. Nice easy no-op for higher order functions.\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003c10\u003e(identity(10))\nexpectType\u003c\"butts\"\u003e(identity(\"butts\"))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('just gives stuff back', () =\u003e {\n identity(10).should.be.equal(10)\n identity('hi').should.be.equal('hi')\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='flip'\u003eflip\u003c/a\u003e\n```typescript\nexport function flip\u003cA, B, Out\u003e(f: (a: A) =\u003e (b: B) =\u003e Out): (b: B) =\u003e (a: A) =\u003e Out\n```\n\nTakes a 2-curried function and flips the order of the arguments\n\n```js\n\u003e const lessThanEq = flip(greaterThanEq)\n\n\u003e const first = a =\u003e b =\u003e a\n\u003e const second = flip(first)\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\ntype Flipped = \u003cA\u003e(b: any) =\u003e (a: A) =\u003e A\nexpectAssignable\u003cFlipped\u003e(flip(always))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('flips argument order', () =\u003e {\n flip(lessThan)(3)(9).should.be.true\n flip(sub)(1)(9).should.equal(-8)\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='always'\u003ealways\u003c/a\u003e\n```typescript\nexport function always\u003cA\u003e(a: A): (b: any) =\u003e A\n```\n\nA constant function. This is particularly useful when you want\nto just produce a value, but are working with higher order functions\nthat expect to call a function for a result.\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber\u003e(always(10)(map))\nexpectType\u003cstring\u003e(always('10')(map))\nexpectType\u003c(b: any) =\u003e number\u003e(always(10))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should be constant', () =\u003e {\n const fifteen = always(15)\n fifteen(20).should.be.equal(15)\n fifteen('asdfasdf').should.be.equal(15)\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='not'\u003enot\u003c/a\u003e\n```typescript\nexport function not\u003cKey extends string\u003e(k: Key): (obj: HasKey\u003cKey\u003e) =\u003e boolean\nexport function not\u003cA\u003e(a: Fn1\u003cA, any\u003e): Fn1\u003cA, boolean\u003e;\nexport function not\u003cA, B\u003e(a: Fn2\u003cA, B, any\u003e): Fn2\u003cA, B, boolean\u003e;\nexport function not\u003cA, B, C\u003e(a: Fn3\u003cA, B, C, any\u003e): Fn3\u003cA, B, C, boolean\u003e;\nexport function not\u003cA, B, C, D\u003e(a: Fn4\u003cA, B, C, D, any\u003e): Fn4\u003cA, B, C, D, boolean\u003e;\nexport function not\u003cA, B, C, D, E\u003e(a: Fn5\u003cA, B, C, D, E, any\u003e): Fn5\u003cA, B, C, D, E, boolean\u003e;\nexport function not\u003cPattern\u003e(p: Pattern): (obj: HasPattern\u003cPattern\u003e) =\u003e boolean\n```\n\nA function level equivalent of the `!` operator. It consumes a function or [into pattern](#into), and returns a \nfunction that takes the same arguments, and returns the negation of the output\n\n```js\n\u003e const isOdd = not(isEven);\n\u003e isOdd(3)\ntrue\n\n\u003e not('goldMember')(jack)\ntrue\n\n\u003e not({name: \"Jack Sparrow\"})(liz)\ntrue\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\ndeclare function notFn1(a: number): string \ndeclare function notFn4(a: number, b: string, c: boolean, d: number): string \nexpectType\u003cFn1\u003cnumber, boolean\u003e\u003e(not(notFn1))\nexpectType\u003cFn4\u003cnumber, string, boolean, number, boolean\u003e\u003e(not(notFn4))\nexpectType\u003cboolean\u003e(not(\"name\")(users[0]))\nexpectError(not(\"butt\")(users[0]))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should negate functions of various arities', () =\u003e {\n const isEven = n =\u003e n % 2 == 0\n const plus = (a, b) =\u003e a + b\n not(isEven)(3).should.be.true\n not(plus)(2, 3).should.be.false\n not(plus)(2, -2).should.be.true\n})\n\nit('should handle shorthand', () =\u003e {\n not('goldMember')(jack).should.be.true\n not({name: 'Jack Sparrow'})(jack).should.be.false\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='and'\u003eand\u003c/a\u003e\n```typescript\nexport function and\u003cA, Out\u003e(a?: Fn1\u003cA, Out\u003e, b?: Fn1\u003cA, Out\u003e, c?: Fn1\u003cA, Out\u003e, d?: Fn1\u003cA, Out\u003e, e?: Fn1\u003cA, Out\u003e, f?: Fn1\u003cA, Out\u003e): Fn1\u003cA, Out\u003e\nexport function and\u003cA, B, Out\u003e(a?: Fn2\u003cA, B, Out\u003e, b?: Fn2\u003cA, B, Out\u003e, c?: Fn2\u003cA, B, Out\u003e, d?: Fn2\u003cA, B, Out\u003e, e?: Fn2\u003cA, B, Out\u003e, f?: Fn2\u003cA, B, Out\u003e): Fn2\u003cA, B, Out\u003e\nexport function and\u003cA, B, C, Out\u003e(a?: Fn3\u003cA, B, C, Out\u003e, b?: Fn3\u003cA, B, C, Out\u003e, c?: Fn3\u003cA, B, C, Out\u003e, d?: Fn3\u003cA, B, C, Out\u003e, e?: Fn3\u003cA, B, C, Out\u003e, f?: Fn3\u003cA, B, C, Out\u003e): Fn3\u003cA, B, C, Out\u003e\nexport function and\u003cA, B, C, D, Out\u003e(a?: Fn4\u003cA, B, C, D, Out\u003e, b?: Fn4\u003cA, B, C, D, Out\u003e, c?: Fn4\u003cA, B, C, D, Out\u003e, d?: Fn4\u003cA, B, C, D, Out\u003e, e?: Fn4\u003cA, B, C, D, Out\u003e, f?: Fn4\u003cA, B, C, D, Out\u003e): Fn4\u003cA, B, C, D, Out\u003e\nexport function and\u003cA, B, C, D, E, Out\u003e(a?: Fn5\u003cA, B, C, D, E, Out\u003e, b?: Fn5\u003cA, B, C, D, E, Out\u003e, c?: Fn5\u003cA, B, C, D, E, Out\u003e, d?: Fn5\u003cA, B, C, D, E, Out\u003e, e?: Fn5\u003cA, B, C, D, E, Out\u003e, f?: Fn5\u003cA, B, C, D, E, Out\u003e): Fn5\u003cA, B, C, D, E, Out\u003e\n```\n\nA function level equivalent of the `\u0026\u0026` operator. It consumes an arbitrary number of \nfunctions that take the same argument types and produce booleans, and returns a \nsingle function that takes the same arguments, and returns a truthy value if all of \nthe functions are truthy (Return value mimics the behavior of `\u0026\u0026`)\n\n```js\n\u003e and(isEven, greaterThan(3))(6)\ntrue\n\u003e [42, 2, 63].filter(and(isEven, greaterThan(3)))\n[42]\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\ndeclare function andFn1(a: number): number\ndeclare function andFn2(a: number, b: string): number\ndeclare function andFn3(a: number, b: string, c: boolean): number\ndeclare function andFn3Bad(a: number, b: string, c: boolean): boolean\nexpectType\u003cFn3\u003cnumber, string, boolean, number\u003e\u003e(and(andFn3, andFn3, andFn3))\nexpectType\u003cFn3\u003cnumber, string, boolean, number\u003e\u003e(and(andFn1, andFn2, andFn3))\nexpectType\u003cFn2\u003cnumber, string, number\u003e\u003e(and(andFn1, andFn2, identity))\nexpectType\u003cFn1\u003cnumber, number\u003e\u003e(and(andFn1))\nexpectError(and(andFn1, andFn2, andFn3Bad))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nconst isEven = n =\u003e n % 2 == 0;\nconst isPositive = n =\u003e n \u003e 0;\nconst plus = (a, b) =\u003e a + b\nconst lt = (a, b) =\u003e a \u003c b\nconst gt = (a, b) =\u003e a \u003e b\n\nit('handles multiple functions', () =\u003e {\n and(isEven, isPositive)(4).should.be.true;\n and(isEven, isPositive)(3).should.be.false;\n and(isEven, isPositive)(-1).should.be.false \n})\n\nit('handles functions with different arities', () =\u003e {\n and(lt, isEven)(4, 9).should.be.true;\n and(lt, isEven)(4, 9).should.be.true;\n and(lt, isEven)(3, 9).should.be.false;\n})\n\nit('returns the final value or short circuits', () =\u003e {\n and(isEven, plus)(4, 9).should.equal(13);\n and(gt, isEven, plus)(3, 9).should.be.false;\n and(lt, sub(3), isEven)(3, 9).should.equal(0);\n})\n\nit('execution stops after a false', () =\u003e {\n const boomMsg = 'boom'\n const boom = () =\u003e {throw new Error(boomMsg)}\n and(always(false), boom)(false).should.be.false\n expect(() =\u003e and(always(true), boom)(false)).throws(boomMsg)\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='or'\u003eor\u003c/a\u003e\n```typescript\nexport function or\u003cA, Out\u003e(a?: Fn1\u003cA, Out\u003e, b?: Fn1\u003cA, Out\u003e, c?: Fn1\u003cA, Out\u003e, d?: Fn1\u003cA, Out\u003e, e?: Fn1\u003cA, Out\u003e, f?: Fn1\u003cA, Out\u003e): Fn1\u003cA, Out\u003e\nexport function or\u003cA, B, Out\u003e(a?: Fn2\u003cA, B, Out\u003e, b?: Fn2\u003cA, B, Out\u003e, c?: Fn2\u003cA, B, Out\u003e, d?: Fn2\u003cA, B, Out\u003e, e?: Fn2\u003cA, B, Out\u003e, f?: Fn2\u003cA, B, Out\u003e): Fn2\u003cA, B, Out\u003e\nexport function or\u003cA, B, C, Out\u003e(a?: Fn3\u003cA, B, C, Out\u003e, b?: Fn3\u003cA, B, C, Out\u003e, c?: Fn3\u003cA, B, C, Out\u003e, d?: Fn3\u003cA, B, C, Out\u003e, e?: Fn3\u003cA, B, C, Out\u003e, f?: Fn3\u003cA, B, C, Out\u003e): Fn3\u003cA, B, C, Out\u003e\nexport function or\u003cA, B, C, D, Out\u003e(a?: Fn4\u003cA, B, C, D, Out\u003e, b?: Fn4\u003cA, B, C, D, Out\u003e, c?: Fn4\u003cA, B, C, D, Out\u003e, d?: Fn4\u003cA, B, C, D, Out\u003e, e?: Fn4\u003cA, B, C, D, Out\u003e, f?: Fn4\u003cA, B, C, D, Out\u003e): Fn4\u003cA, B, C, D, Out\u003e\nexport function or\u003cA, B, C, D, E, Out\u003e(a?: Fn5\u003cA, B, C, D, E, Out\u003e, b?: Fn5\u003cA, B, C, D, E, Out\u003e, c?: Fn5\u003cA, B, C, D, E, Out\u003e, d?: Fn5\u003cA, B, C, D, E, Out\u003e, e?: Fn5\u003cA, B, C, D, E, Out\u003e, f?: Fn5\u003cA, B, C, D, E, Out\u003e): Fn5\u003cA, B, C, D, E, Out\u003e\n```\n\nA function level equivalent of the `||` operator. It consumes an arbitrary number \nof functions that take the same argument types and produce truthy values, and returns \na single function that takes the same arguments, and returns a truthy value if any of \nthe functions produce truthy values (Return value mimics the behavior of `||`)\n```js\n\u003e or(isEven, greaterThan(3))(5)\ntrue\n\u003e or(isEven, greaterThan(3))(1)\nfalse\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\ndeclare function orFn1(a: number): number\ndeclare function orFn2(a: number, b: string): number\ndeclare function orFn3(a: number, b: string, c: boolean): number\ndeclare function orFn3Bad(a: number, b: string, c: boolean): boolean\nexpectType\u003cFn3\u003cnumber, string, boolean, number\u003e\u003e(or(orFn3, orFn3, orFn3))\nexpectType\u003cFn3\u003cnumber, string, boolean, number\u003e\u003e(or(orFn1, orFn2, orFn3))\nexpectType\u003cFn2\u003cnumber, string, number\u003e\u003e(or(orFn1, orFn2, identity))\nexpectType\u003cFn1\u003cnumber, number\u003e\u003e(or(orFn1))\nexpectError(or(orFn1, orFn2, orFn3Bad))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nconst isEven = n =\u003e n % 2 == 0;\nconst isPositive = n =\u003e n \u003e 0;\nconst plus = (a, b) =\u003e a + b\nconst lt = (a, b) =\u003e a \u003c b\nconst gt = (a, b) =\u003e a \u003e b\n\nit('handles multiple functions', () =\u003e {\n or(isEven, isPositive)(4).should.be.true;\n or(isEven, isPositive)(3).should.be.true;\n or(isEven, isPositive)(-1).should.be.false \n})\n\nit('handles functions with different arities', () =\u003e {\n or(lt, isEven)(4, 9).should.be.true;\n or(lt, isEven)(4, 9).should.be.true;\n or(lt, isEven)(3, 9).should.be.true;\n or(lt, isEven)(3, 1).should.be.false;\n})\n\nit('returns the final value or short circuits', () =\u003e {\n or(isEven, plus)(3, 9).should.equal(12);\n or(gt, isEven, plus)(3, 9).should.equal(12)\n or(lt, sub(3), isEven)(3, 9).should.be.true\n})\n\nit('execution stops after a true', () =\u003e {\n const boomMsg = 'boom'\n const boom = () =\u003e {throw new Error(boomMsg)}\n or(always(true), boom)(false).should.be.true\n expect(() =\u003e or(always(false), boom)(false)).throws(boomMsg)\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n\n### \u003ca href='has'\u003ehas\u003c/a\u003e\n```typescript\nexport function has\u003cPattern\u003e(p: Pattern): (obj: HasPattern\u003cPattern\u003e) =\u003e boolean\n```\n\n`has` takes a pattern and transforms it into a predicate function. In the simplest form, it takes a pattern of keys \nand values and produces a function that takes a test value and returns `true` if the given test value has at least \nthe equivalent keys and values of the pattern. Using the [store](#store) example from above:\n\n```js\n// Tests if an object passed to it has the key goldMember mapped to true\n\u003e const isGoldMember = has({goldMember: true})\n\u003e isGoldMember(jack)\nfalse\n\n// test multiple values\n\u003e has({goldMember: true, name: \"Elizabeth Swan\"})(liz)\ntrue\n```\n\nNested values work just as you'd expect:\n```js\n\u003e has({jack: {goldMember: false}})(store.byName)\ntrue\n```\n\nWhere it REALLY gets interesting is when the _values_ in your pattern are predicate functions. \nIn this case, the value at that key in the test object is passed to the function, and validation \nonly continues if that function returns `true`\n\n```js\n// Tests if the object passed to it has a title attribute that is less than 50 letters long\n\u003e const hasShortTitle = has({title: title =\u003e title.length \u003c 50})\n\u003e hasShortTitle(jack.posts[0])\nfalse\n```\nThis pattern is especially useful with [lenses and traversals](#guide)\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003c(obj: HasPattern\u003c{ a: number; }\u003e) =\u003e boolean\u003e(has({a: 1}))\nexpectType\u003c(obj: HasPattern\u003c{ a: false; }\u003e) =\u003e boolean\u003e(has({a: false}))\nexpectType\u003cboolean\u003e(has({a: 1})({a: 10}))\nexpectError(has({a: 1})({a: false}))\nexpectType\u003cboolean\u003e(has({a: (n: number) =\u003e n \u003e 10})({a: 5}))\nexpectError(has({a: (n: number) =\u003e n \u003e 10})({a: false}))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should handle multiple patterns and nested keys', () =\u003e {\n has({ a: { b: 2 }, c: 3 })({ a: { b: 2, f: 5 }, c: 3, d: 4 }).should.be.true\n});\n\nit('should return false if not true', () =\u003e {\n has({ a: { b: 2 }, c: 3 })({ a: { b: 6, f: 5 }, d: 4 }).should.be.false\n});\n\nit('should handle null values', () =\u003e {\n has({ a: null })({ a: null }).should.be.true\n});\n\nit('should handle scalars', () =\u003e {\n has('three')('three').should.be.true;\n has('three')('four').should.be.false;\n has(true)(true).should.be.true;\n has(false)(false).should.be.true;\n has(true)(false).should.be.false;\n has(undefined)(undefined).should.be.true;\n has(null)(null).should.be.true;\n has(undefined)(null).should.be.false;\n has(3)(3).should.be.true;\n has(3)(4).should.be.false;\n});\n\nit('should handle lists', () =\u003e {\n has([1, 2])([1, 2]).should.be.true;\n has({ a: [1, 2] })({ a: [1, 2], b: 3 }).should.be.true;\n});\n\nit('should handle predicate functions', () =\u003e {\n has(_.isString)('hello').should.be.true;\n has(_.isString)(5).should.be.false;\n has({ a: _.isString })({ a: 'hello' }).should.be.true;\n has({ a: _.isString })({ a: 5 }).should.be.false;\n has({ a: n =\u003e n % 2 == 1, b: { c: _.isString } })({\n a: 5,\n b: { c: 'hello' }\n }).should.be.true;\n has({ a: n =\u003e n % 2 == 0, b: { c: _.isString } })({\n a: 5,\n b: { c: 'hello' }\n }).should.be.false\n});\n\nit('should handle unbalanced patterns and objects', () =\u003e {\n has({ a: { b: { c: 12 } } })(null).should.be.false;\n has({ a: { b: { c: 12 } } })({ a: { b: null } }).should.be.false;\n});\n\nit('should handle binding', () =\u003e {\n const base = {\n IDTag() {\n return this.tag;\n }\n };\n\n const extended = {\n ...base,\n tag: 'hi'\n };\n\n has({ IDTag: returns('hi') })(extended).should.be.true;\n});\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='greaterThan'\u003egreaterThan\u003c/a\u003e\n```typescript\nexport function greaterThan(a: number): (b: number) =\u003e boolean\nexport function greaterThan(a: string): (b: string) =\u003e boolean\n```\n\nCurried function to compare greater than for two values. NOTE: All logical functions \nin shades are reversed; i.e. `greaterThan(a)(b) === b \u003e a`. This might seem confusing,\nbut think of it as predicate factories, that take a value `n` and produce a function \nthat tests 'Is this value greater than `n`?'\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003c(b: number) =\u003e boolean\u003e(greaterThan(2))\nexpectType\u003c(b: string) =\u003e boolean\u003e(greaterThan('a'))\nexpectType\u003cboolean\u003e(greaterThan('a')('b'))\nexpectError(greaterThan('a')(1))\nexpectError(greaterThan({a: 1}))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should compare greaterThan', () =\u003e {\n greaterThan(2)(3).should.be.true;\n greaterThan(3)(2).should.be.false;\n})\n\nit('should compare strings value', () =\u003e {\n greaterThan('a')('b').should.be.true;\n greaterThan('b')('a').should.be.false;\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='lessThan'\u003elessThan\u003c/a\u003e\n```typescript\nexport function lessThan(a: number): (b: number) =\u003e boolean\nexport function lessThan(a: string): (b: string) =\u003e boolean\n```\n\nCurried function to compare less than for two values. NOTE: All logical functions \nin shades are reversed; i.e. `lessThan(a)(b) === b \u003e a`. This might seem confusing,\nbut think of it as predicate factories, that take a value `n` and produce a function \nthat tests 'Is this value less than `n`?'\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003c(b: number) =\u003e boolean\u003e(lessThan(2))\nexpectType\u003c(b: string) =\u003e boolean\u003e(lessThan('a'))\nexpectType\u003cboolean\u003e(lessThan('a')('b'))\nexpectError(lessThan('a')(1))\nexpectError(lessThan({a: 1}))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should compare lessThan', () =\u003e {\n lessThan(2)(3).should.be.false;\n lessThan(3)(2).should.be.true;\n})\n\nit('should compare strings value', () =\u003e {\n lessThan('a')('b').should.be.false;\n lessThan('b')('a').should.be.true;\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='greaterThanEq'\u003egreaterThanEq\u003c/a\u003e\n```typescript\n```\n\nSame as [`greaterThan`](#greaterThan) but `\u003e=` instead of `\u003e`\n\n\n\n\n### \u003ca href='lessThanEq'\u003elessThanEq\u003c/a\u003e\n```typescript\n```\n\nSame as [`greaterThan`](#greaterThan) but `\u003e=` instead of `\u003e`\n\n\n\n\n### \u003ca href='toggle'\u003etoggle\u003c/a\u003e\n```typescript\nexport function toggle(b: boolean): boolean\n```\n\nThe `!` operator as a function. Takes a boolean and flips the value. Very useful as an updater function:\n```js\n\u003e mod('byName', jack, 'goldMember')(toggle)(store)\n{\n byName: {\n jack: {\n goldMember: true,\n ...\n }\n ...\n }\n ...\n}\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cboolean\u003e(toggle(false))\nexpectError(toggle('a'))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should toggle values', () =\u003e {\n toggle(true).should.be.false;\n toggle(false).should.be.true;\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='returns'\u003ereturns\u003c/a\u003e\n```typescript\nexport function returns\u003cA\u003e(a: A): (f: () =\u003e A) =\u003e boolean\n```\n\nA curried function that takes a value `a` of type `A` and a function of no arguments that\nreturns a value of type `A`. These two values are then compared for equality.\n\nThis is very useful with [`has`](#has) or [`into`](#into) when your test value has \ngetter functions, and you want to see if those getters produce a certain value:\n\n```js\n\u003e const a = {\n ID() {\n return '10'\n }\n}\n\n\u003e has({a: returns(10)})(a)\ntrue\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cboolean\u003e(returns(10)(() =\u003e 10))\nexpectError(returns(10)(() =\u003e 'hi'))\ndeclare const getID: {\n ID(): string\n}\nexpectType\u003cboolean\u003e(has({ID: returns('blah')})(getID))\nexpectError(has({ID: returns(10)})(getID))\n\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('works', () =\u003e {\n returns(10)(() =\u003e 10).should.be.true;\n returns(7)(() =\u003e 10).should.be.false;\n})\n\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n\n### \u003ca href='fill'\u003efill\u003c/a\u003e\n```typescript\nexport function fill\u003cP extends object\u003e(pat: P): \u003cT extends FillingPattern\u003cP\u003e\u003e(value: T) =\u003e Fill\u003cT, P\u003e\n```\n\nMerging function that can be used to fill potentially undefined holes in an object. Deep merges objects with a preference for the original, so:\n```ts\nfill({a: {b: 10, c: 20}})({a: {c: 30}})\n```\nproduces:\n```ts\n{a: {b: 10, c: 30}}\n```\nMost importantly, this will also update the output type to erase any `T | undefined | null` that were filled by the given\npattern. Useful before applying a lens function to ensure that the result will be defined.\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber\u003e(fill({a: 10})({a: undefined, b: 5}).a)\nexpectType\u003cnumber\u003e(fill({a: 10})({}).a)\n// 'bestFriend' is an optional `User` property on the `User` object\nexpectType\u003cErrorCannotLensIntoOptionalKey\u003cUser | undefined, \"name\"\u003e\u003e(get('bestFriend', 'name')(user))\nconst friendsWithMyself = fill({bestFriend: user})(user)\nexpectType\u003cstring\u003e(get('bestFriend', 'name')(friendsWithMyself))\nexpectType\u003cErrorCannotLensIntoOptionalKey\u003cErrorCannotLensIntoOptionalKey\u003cUser | undefined, \"bestFriend\"\u003e, \"name\"\u003e\u003e(get('bestFriend', 'bestFriend', 'name')(user))\nconst deepFriendsWithMyself = fill({bestFriend: friendsWithMyself})(user)\nexpectType\u003cstring\u003e(get('bestFriend', 'bestFriend', 'name')(deepFriendsWithMyself))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('fills in keys on an object', () =\u003e {\n fill({a: 10})({b: 5}).a.should.equal(10)\n fill({a: 10})({b: 5}).b.should.equal(5)\n fill({a: 10})({a: null}).a.should.equal(10)\n should.not.exist(fill({b: 10})({a: null}).a)\n})\n\nit('should not overwrite existing keys', () =\u003e {\n fill({a: 10})({a: 5}).a.should.equal(5)\n fill({a: {b: 10}})({a: 5}).a.should.equal(5)\n})\n\nit('should merge nested keys', () =\u003e {\n const out = fill({a: {b: 10, c: 15}})({a: {c: 20}})\n out.a.b.should.be.equal(10)\n out.a.c.should.be.equal(20)\n})\n\nit('should not overwrite falsey values', () =\u003e {\n fill({a: 10})({a: false}).a.should.equal(false)\n fill({a: 10})({a: 0}).a.should.equal(0)\n fill({a: 10})({a: ''}).a.should.equal('')\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n\n### \u003ca href='add'\u003eadd\u003c/a\u003e\n```typescript\nexport function add(a: number): (b: number) =\u003e number\n```\n\nCurried `+` operator\n\n```js\n\u003e add(5)(2)\n7\n\n\u003e [1, 2, 3].map(add(5))\n[6, 7, 8]\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber\u003e(add(1)(3))\nexpectError(add(1)('s'))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('works', () =\u003e {\n add(5)(2).should.be.equal(7);\n [1, 2, 3].map(add(5)).should.deep.equal([6, 7, 8]);\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='sub'\u003esub\u003c/a\u003e\n```typescript\nexport function sub(a: number): (b: number) =\u003e number\n```\n\nCurried `-` operator. _NOTE_: Like the [logical](#logical) functions, `sub` is \nreversed; i.e. `sub(a)(b) === b - a`, so `sub(3)` means \"Take a number and subtract\n3 from it\"\n\n```js\n\u003e sub(5)(2)\n3\n\n\u003e [1, 2, 3].map(sub(5))\n[-4, -3, -2]\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cnumber\u003e(sub(1)(3))\nexpectError(sub(1)('s'))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('works', () =\u003e {\n sub(5)(2).should.be.equal(-3);\n [1, 2, 3].map(sub(5)).should.deep.equal([-4, -3, -2]);\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n\n### \u003ca href='includes'\u003eincludes\u003c/a\u003e\n```typescript\nexport function includes(snippet: string): (text: string) =\u003e boolean\n```\n\nReversed version of `String::includes`. Takes a snippet, and produces a function that will take a string,\nand produce a boolean if that string contains the snippet. Very useful when working with [`into`](#into)\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cboolean\u003e(includes('hello')('hello'))\nexpectError(includes('hello')(false))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('checks for inclusion', () =\u003e {\n includes('he')('hello').should.be.true\n includes('hello')('he').should.be.false\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='includesi'\u003eincludesi\u003c/a\u003e\n```typescript\nexport function includesi(snippet: string): (text: string) =\u003e boolean\n```\n\nReversed, case-insensitive version of `String::includes`. Takes a snippet, and produces a function that will take a string,\nand produce a boolean if that string contains the snippet, ignoring case. Very useful when working with [`into`](#into)\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cboolean\u003e(includesi('hello')('hello'))\nexpectError(includesi('hello')(false))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('checks for inclusion', () =\u003e {\n includesi('he')('hello').should.be.true\n includesi('hello')('he').should.be.false\n})\n\nit('ignores case', () =\u003e {\n includesi('HE')('hello').should.be.true\n includesi('He')('hEllo').should.be.true\n includesi('hello')('he').should.be.false\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n## \u003ca href=lens-consumers\u003eLens Consumers\u003c/a\u003e\n\n### \u003ca href='get'\u003eget\u003c/a\u003e\n```typescript\n```\n\n`get` takes any number of lenses, and returns a function that takes an object and applies\neach of those lenses in order to extract the focus from the lens. (If you are using TypeScript,\nyou'll be pleased to know it's typesafe, and can track the type of lenses and catch many errors).\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cstring\u003e(get('name')(user))\nexpectType\u003cstring\u003e(get(0, 'name')(users))\nexpectError(get(0, 'fart')(users))\nexpectType\u003cUser | undefined\u003e(get('bestFriend')(user))\nexpectType\u003cErrorCannotLensIntoOptionalKey\u003cUser | undefined, \"name\"\u003e\u003e(get('bestFriend', 'name')(user))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit(\"is an accessor\", () =\u003e {\n get('name')(jack).should.equal('Jack Sparrow')\n})\n\nit(\"is composable\", () =\u003e {\n get('users', 0, 'name')(store).should.equal('Jack Sparrow')\n});\n\nit(\"extracts matching elements\", () =\u003e {\n get(matching(\"goldMember\"))(store.users).should.deep.equal([liz])\n})\n\nit(\"composes with traversals\", () =\u003e {\n get(\"users\", all, \"posts\")(store).should.deep.equal([jack.posts, liz.posts, bill.posts])\n})\n\nit(\"preserves structure with traversals\", () =\u003e {\n get(\"byName\", all, \"goldMember\")(store).should.deep.equal({jack: false, liz: true, bill: false})\n})\n\nit(\"nests traverals in output\", () =\u003e {\n get(\"users\", all, \"posts\", all, \"likes\")(store).should.deep.equal([[5, 70], [10000, 5000], [3000]])\n})\n\nit(\"handles folds as lenses\", () =\u003e {\n get(\"users\", 0, \"posts\", maxBy('likes'), 'likes')(store).should.equal(70)\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n\n\n\n### \u003ca href='all'\u003eall\u003c/a\u003e\n```typescript\nexport function all\u003cA\u003e(): Traversal\u003cA\u003e; // tslint:disable-line\n```\n\n`all` is the simplest traversal; it simply signifies that this traversal wi\nin a collection. It is the lens equivalent of the `map` function. \n```js\n\u003e get('users', all(), 'name')(store)\n['Jack Sparrow', 'Elizabeth Swan', 'Bootstrap Bill']\n```\nAs you can see above, the `'name'` lens didn't apply directly to the array of users, and try to extract\na `name` property from the array, but instead mapped it over the array.\n\nIf you're _not_ using typescript, you'll find that you can just use the `all` function itself as\nthe traversal, and there's no need to call it:\n```js\n\u003e set('users', all, 'name')('butt')(store)\n{ users: [...] } // All users will have the name butt\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cstring[]\u003e(get('friends', all\u003cUser\u003e(), 'name')(user))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should act as identity with get', () =\u003e {\n get(all)([1, 2, 3, 4]).should.deep.equal([1, 2, 3, 4]);\n get(all)({ a: 1, b: 2, c: 3, d: 4 }).should.deep.equal({ a: 1, b: 2, c: 3, d: 4 });\n});\n\nit('should allow multifoci gets', () =\u003e {\n get('a', all, 'b')({ a: [{ b: 1 }, { b: 2 }] }).should.deep.equal([ 1, 2 ]);\n});\n\nit('should allow deep multifoci gets', () =\u003e {\n const store = {\n users: [\n {\n blog: {\n posts: [\n {\n title: 'Hi'\n }\n ]\n }\n }\n ]\n };\n get('users', all, 'blog', 'posts', all, 'title')(store).should.deep.equal(\n [['Hi']]\n );\n});\n\nit('should allow deep multifoci mods', () =\u003e {\n const store = {\n users: [\n {\n blog: {\n posts: [\n {\n title: 'Hi'\n }\n ]\n }\n }\n ]\n };\n mod('users', all, 'blog', 'posts', all, 'title')(s =\u003e s.toLowerCase())(\n store\n ).users[0].blog.posts[0].title.should.equal('hi');\n});\n\nit('should act as map with mod', () =\u003e {\n assert.deepStrictEqual([2, 3, 4, 5], mod(all)(inc)([1, 2, 3, 4]));\n assert.deepStrictEqual(\n { a: 2, b: 3, c: 4, d: 5 },\n mod(all)(inc)({ a: 1, b: 2, c: 3, d: 4 })\n );\n});\n\n\nit('should compose in the middle of a lens and act as map', () =\u003e {\n assert.deepStrictEqual(\n [{ n: 1, c: 5 }, { n: 2, c: 7 }],\n mod(all, 'c')(inc)([{ n: 1, c: 4 }, { n: 2, c: 6 }])\n );\n});\n\nit('should compose in the middle of multiple lenses', () =\u003e {\n mod(all, 'c', all)(inc)([\n { n: 1, c: { d: 1, e: 7 } },\n { n: 2, c: { d: 1, e: 7 } }\n ]).should.deep.equal(\n [{ n: 1, c: { d: 2, e: 8 } }, { n: 2, c: { d: 2, e: 8 } }]\n );\n});\n\nit('should work in function form as well', () =\u003e {\n Object.entries(all).should.deep.equal(Object.entries(all()))\n});\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n\n### \u003ca href='matching'\u003ematching\u003c/a\u003e\n```typescript\nexport function matching\u003cKey extends string\u003e(k: Key): Traversal\u003cHasKey\u003cKey\u003e\u003e\nexport function matching\u003cA\u003e(f: (a: A) =\u003e any): Traversal\u003cA\u003e\nexport function matching\u003cPattern\u003e(p: Pattern): Traversal\u003cHasPattern\u003cPattern\u003e\u003e\n```\n\n`matching` is the `filter` of traversals. It takes an predicate function (or [`into` pattern](#into)) and produces\na lens that will apply to every item in the collection that passes the criterion.\n\nFor instance, to `get` every user name that is a gold member in our [`store`](#store) example, we could write\n```js\n\u003e get('users', matching('goldMember'), 'name')(store)\n['Elizabeth Swan']\n```\n\nThey can be stacked together and used to modify, e.g. to find all the gold members and like only \ntheir posts with more than 10 likes (sounds complicated), all we have to write is:\n```js\n\u003e mod('users', matching('goldMember'), 'posts', matching({likes: greaterThan(10)}))(inc)(store)\n{ users: [...] } // Trust me, it's updated\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cUser[]\u003e(get(matching('goldMember'))(users))\nexpectType\u003cstring[]\u003e(get(matching('goldMember'), 'name')(users))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nconst isEven = n =\u003e n % 2 == 0;\n\nit('should be able to get matching elements', () =\u003e {\n get(matching(isEven))([1, 2, 3, 4]).should.deep.equal([2, 4]);\n get(matching(isEven))({ a: 1, b: 2, c: 3, d: 4 }).should.deep.equal({ b: 2, d: 4 });\n});\n\nit('should be able to set matching elements', () =\u003e {\n mod(matching(isEven))(inc)([1, 2, 3, 4]).should.deep.equal([1, 3, 3, 5])\n mod(matching(isEven))(inc)({ a: 1, b: 2, c: 3, d: 4 }).should.deep.equal({ a: 1, b: 3, c: 3, d: 5 })\n});\n\nit('should compose in the middle of a lens', () =\u003e {\n mod(matching(({ n }) =\u003e n % 2 === 0), 'c')(inc)([\n { n: 1, c: 4 },\n { n: 2, c: 6 }\n ]).should.deep.equal(\n [{ n: 1, c: 4 }, { n: 2, c: 7 }]\n )\n});\n\nit('should compose in the middle of a lens', () =\u003e {\n mod(\n matching(({ n }) =\u003e isEven(n)),\n 'c',\n matching(({ d }) =\u003e d === 1),\n 'e'\n )(inc)([\n { n: 1, c: 4 },\n { n: 2, c: { a: { d: 1, e: 2 }, b: { d: 5, e: 12 } } }\n ]).should.deep.equal(\n [\n { n: 1, c: 4 },\n { n: 2, c: { a: { d: 1, e: 3 }, b: { d: 5, e: 12 } } }\n ])\n});\n\nit('should handle shorthands', () =\u003e {\n get(matching({ n: isEven }), 'c', matching('d'), 'e')([\n { n: 1, c: 4 },\n { n: 2, c: { a: { d: true, e: 2 }, b: { d: false, e: 12 } } }\n ]).should.deep.equal([{ a: 2 }]);\n\n get(matching({ n: isEven }), 'c', matching('d'), 'e')([\n { n: 1, c: 4 },\n { n: 2, c: { a: { d: true, e: 2 }, b: { d: true, e: 12 } } }\n ]).should.deep.equal([{ a: 2, b: 12 }]);\n});\n\nit('should set with shorthands', () =\u003e {\n set(matching({ n: isEven }), 'c', matching('d'), 'e')(10)([\n { n: 1, c: 4 },\n { n: 2, c: { a: { d: true, e: 2 }, b: { d: false, e: 12 } } }\n ]).should.deep.equal([\n { n: 1, c: 4 },\n { n: 2, c: { a: { d: true, e: 10 }, b: { d: false, e: 12 } } }\n ]);\n});\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n\n### \u003ca href='findBy'\u003efindBy\u003c/a\u003e\n```typescript\nexport interface FindBy {\n \u003cKey extends string\u003e(k: Key): Lens\u003cCollection\u003cHasKey\u003cKey\u003e\u003e, HasKey\u003cKey\u003e\u003e\n \u003cA\u003e(f: (a: A) =\u003e any): Lens\u003cCollection\u003cA\u003e, A\u003e\n \u003cPattern\u003e(p: Pattern): Lens\u003cCollection\u003cHasPattern\u003cPattern\u003e\u003e, HasPattern\u003cPattern\u003e\u003e\n\n of: \u003cA\u003e(pattern: any) =\u003e Lens\u003cCollection\u003cA\u003e, A\u003e\n}\n\n```\n\n`findBy` is a folding lens that focuses on the element of a collection that matches the\ngiven [`into` pattern](#into). For example, in our store example, we could find Jack Sparrows\n`goldMember` status with:\n```js\n\u003e get('users', findBy({name: contains('Jack')}), 'goldMember')(store)\nfalse\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cstring\u003e(get('friends', findBy.of\u003cUser\u003e({name: 'john'}), 'name')(user))\nexpectType\u003cPost[]\u003e(get('friends', findBy.of\u003cUser\u003e('goldMember'), 'posts')(user))\nexpectType\u003cPost[]\u003e(get('friends', findBy((user: User) =\u003e user.settings), 'posts')(user))\nexpectError(get('friends', findBy((user: User) =\u003e user.settings), 'pots')(user))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('acts as a reducer', () =\u003e {\n get('users', findBy({name: 'Jack Sparrow'}), 'name')(store).should.equal('Jack Sparrow')\n get('users', findBy('goldMember'), 'name')(store).should.equal('Elizabeth Swan')\n})\n\nit('uses of as an alias', () =\u003e {\n get('users', findBy.of({name: 'Jack Sparrow'}), 'name')(store).should.equal('Jack Sparrow')\n get('users', findBy.of('goldMember'), 'name')(store).should.equal('Elizabeth Swan')\n})\n\nit('produces undefined when it cant find something', () =\u003e {\n should.not.exist(get('users', findBy({name: 'frank'}))(store))\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='maxBy'\u003emaxBy\u003c/a\u003e\n```typescript\nexport interface MinBy {\n \u003cKey extends string\u003e(k: Key): Lens\u003cCollection\u003cHasKey\u003cKey\u003e\u003e, HasKey\u003cKey\u003e\u003e\n \u003cA\u003e(f: (a: A) =\u003e any): Lens\u003cCollection\u003cA\u003e, A\u003e\n\n of: \u003cA\u003e(pattern: any) =\u003e Lens\u003cCollection\u003cA\u003e, A\u003e\n}\n\n```\n\n`maxBy` is a folding lens that focuses on the element of a collection that has the\nmaximum value for the given [`into` pattern](#into). For example, in our store example, \nwe could find Jack Sparrows most liked post title with:\n```js\n\u003e get('users', findBy({name: icontains('jack')}), 'posts', maxBy('likes'), 'title')(store)\n'Sea Turtles - The Tortoise and the Hair'\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cstring\u003e(get('friends', maxBy.of\u003cUser\u003e({name: 'john'}), 'name')(user))\nexpectType\u003cPost[]\u003e(get('friends', maxBy.of\u003cUser\u003e('goldMember'), 'posts')(user))\nexpectType\u003cPost[]\u003e(get('friends', maxBy((user: User) =\u003e user.settings), 'posts')(user))\nexpectError(get('friends', maxBy((user: User) =\u003e user.settings), 'pots')(user))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('acts as a reducer', () =\u003e {\n get('posts', maxBy('likes'), 'title')(jack).should.equal('Sea Turtles - The Tortoise and the Hair')\n get('posts', maxBy(post =\u003e -post.title.length), 'title')(liz).should.equal('Bloody Pirates - My Life Aboard the Black Pearl')\n})\n\nit('uses of as an alias', () =\u003e {\n get('posts', maxBy.of('likes'), 'title')(jack).should.equal('Sea Turtles - The Tortoise and the Hair')\n get('posts', maxBy.of(post =\u003e -post.title.length), 'title')(liz).should.equal('Bloody Pirates - My Life Aboard the Black Pearl')\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n### \u003ca href='minBy'\u003eminBy\u003c/a\u003e\n```typescript\nexport interface MaxBy {\n \u003cKey extends string\u003e(k: Key): Lens\u003cCollection\u003cHasKey\u003cKey\u003e\u003e, HasKey\u003cKey\u003e\u003e\n \u003cA\u003e(f: (a: A) =\u003e any): Lens\u003cCollection\u003cA\u003e, A\u003e\n\n of: \u003cA\u003e(pattern: any) =\u003e Lens\u003cCollection\u003cA\u003e, A\u003e\n}\n\n```\n\n`minBy` is a folding lens that focuses on the element of a collection that has the\nminimum value for the given [`into` pattern](#into). For example, in our store example, \nwe could find Jack Sparrows most liked post title with:\n```js\n\u003e get('users', findBy({name: icontains('jack')}), 'posts', minBy('likes'), 'title')(store)\n'Sea Turtles - The Tortoise and the Hair'\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cstring\u003e(get('friends', minBy.of\u003cUser\u003e({name: 'john'}), 'name')(user))\nexpectType\u003cPost[]\u003e(get('friends', minBy.of\u003cUser\u003e('goldMember'), 'posts')(user))\nexpectType\u003cPost[]\u003e(get('friends', minBy((user: User) =\u003e user.settings), 'posts')(user))\nexpectError(get('friends', minBy((user: User) =\u003e user.settings), 'pots')(user))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('acts as a reducer', () =\u003e {\n get('posts', minBy('likes'), 'title')(jack).should.equal('Why is the rum always gone? An analysis of Carribean trade surplus')\n get('posts', minBy(post =\u003e -post.title.length), 'title')(liz).should.equal('Guidelines - When YOU need to be disinclined to acquiesce to their request')\n})\n\nit('uses of as an alias', () =\u003e {\n get('posts', minBy.of('likes'), 'title')(jack).should.equal('Why is the rum always gone? An analysis of Carribean trade surplus')\n get('posts', minBy.of(post =\u003e -post.title.length), 'title')(liz).should.equal('Guidelines - When YOU need to be disinclined to acquiesce to their request')\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n\n### \u003ca href='updateAll'\u003eupdateAll\u003c/a\u003e\n```typescript\nexport function updateAll\u003cS\u003e(...fns: Array\u003c(state: S) =\u003e S\u003e): (state: S) =\u003e S\n```\n\nSequences many updates together:\n```ts\n\u003e updateAll(\n set('a')(10),\n mod('b')(add(5))\n)({b: 20})\n{ a: 10, b: 25 }\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cUser\u003e(updateAll\u003cUser\u003e(\n set('name')('jack'),\n mod('posts', all\u003cPost\u003e(), 'title')((s: string) =\u003e s.toUpperCase())\n)(user))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should sequence updates', () =\u003e {\n const out = updateAll(\n set('a')(10),\n mod('b')(add(5))\n )({b: 20})\n out.a.should.equal(10)\n out.b.should.equal(25)\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n\n### \u003ca href='valueOr'\u003evalueOr\u003c/a\u003e\n```typescript\nexport function valueOr\u003cT\u003e(dflt: T): Lens\u003cT | undefined | null, T\u003e\n```\n\nVirtual Lens that takes a default value and transforms the focus of the lens from \nan optional value into a guaranteed value.\n```ts\ninterface A {\n first: {\n second: {\n third?: string;\n }\n }\n}\nget('first', 'second', 'third')(aValue) // string | undefined\nget('first', 'second', 'third', valueOr('default'))(aValue) // string\n```\n\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTypeScript Usage\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```typescript\nexpectType\u003cUser | undefined\u003e(get('bestFriend')(user))\nexpectType\u003cUser\u003e(get('bestFriend', valueOr(user))(user))\nexpectType\u003c(User | undefined)[]\u003e(get(all(), 'bestFriend')(users))\nexpectType\u003cUser[]\u003e(get(all(), 'bestFriend', valueOr(user))(users))\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cem\u003eTests\u003c/em\u003e\u003c/summary\u003e\n\u003cp\u003e\n\n```javascript\nit('should fill in default values', () =\u003e {\n should.not.exist(get('bestFriend')(jack))\n get('bestFriend', valueOr(jack), 'name')(liz).should.equal('Jack Sparrow')\n mod('bestFriend', valueOr(jack), 'name')(s =\u003e s.toUpperCase())(liz).bestFriend.name.should.equal('JACK SPARROW')\n})\n\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesmcnamara%2Fshades","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamesmcnamara%2Fshades","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesmcnamara%2Fshades/lists"}