1 | # K2
|
2 |
|
3 | > Functional javascript utilities
|
4 |
|
5 | [![NPM][k2-icon] ][k2-url]
|
6 |
|
7 | [![Circle CI](https://circleci.com/gh/kensho/k2.svg?style=svg)](https://circleci.com/gh/kensho/k2)
|
8 | [![Code Climate](https://codeclimate.com/github/kensho/k2/badges/gpa.svg)](https://codeclimate.com/github/kensho/k2)
|
9 |
|
10 | [k2-icon]: https://nodei.co/npm/k2.png?downloads=true
|
11 | [k2-url]: https://npmjs.org/package/k2
|
12 |
|
13 | ## Install
|
14 |
|
15 | npm install --save k2
|
16 |
|
17 | In the browser, if you already have global [lodash](https://lodash.com/docs) library, you can
|
18 | include `dist/k2-browser.js`. Under Node, or to use lodash included in the k2 bundle, use `dist/k2.js`.
|
19 |
|
20 | ```js
|
21 | // node
|
22 | var k2 = require('k2');
|
23 | ```
|
24 |
|
25 | ## Api
|
26 |
|
27 | ### presentProperties
|
28 |
|
29 | Determines if each property in the list is present in each object given in the second list
|
30 |
|
31 | ```js
|
32 | var bad = [{
|
33 | name: 'foo',
|
34 | age: 1
|
35 | }, {
|
36 | name: 'bar'
|
37 | }, {
|
38 | name: 'baz'
|
39 | }];
|
40 | presentProperties(['name', 'age'], bad);
|
41 | // ['name']
|
42 | ```
|
43 |
|
44 | `presentProperties` is curried, works with deep properties, requires `lodash` version
|
45 | with deep property support, see [_.has](https://lodash.com/docs#has)
|
46 |
|
47 | ### cleanEnteredText
|
48 |
|
49 | Removes HTML entities from user-entered text. Common entities introduced by a textarea element
|
50 | are ` ` at the end.
|
51 |
|
52 | ```js
|
53 | var cleanText = k2.cleanEnteredText(text);
|
54 | // text - string entered into a textarea
|
55 | ```
|
56 |
|
57 | ```js
|
58 | k2.cleanEnteredText('FOO b') // 'foo b'
|
59 | k2.cleanEnteredText('foo ') // 'foo'
|
60 | ```
|
61 |
|
62 | ### findPartialMatches
|
63 |
|
64 | Finds all items where given properties are matching the given query text.
|
65 |
|
66 | ```js
|
67 | var matches = k2.findPartialMatches(properties, items, queryText);
|
68 | // properties - single string or an array of strings
|
69 | // items - objects to search over
|
70 | // queryText - single string
|
71 | ```
|
72 |
|
73 | ```js
|
74 | // find all items where property 'foo' contains 'ooo'
|
75 | var items = [{
|
76 | foo: 'foo'
|
77 | }, {
|
78 | foo: 'foo2'
|
79 | }, {
|
80 | foo: 'bar'
|
81 | }];
|
82 | var result = k2.findPartialMatches('foo', items, 'oo');
|
83 | // result is [ items[0], items[1] ]
|
84 | ```
|
85 |
|
86 | ### rankPartialMatches
|
87 |
|
88 | Useful to order items by text entered by the user, but only considering matches of query text to
|
89 | certain properties. Items without any matches will be pushed to the back of the returned list.
|
90 |
|
91 | ```js
|
92 | var matches = k2.rankPartialMatches(properties, matches, queryText);
|
93 | // properties - single string or array of strings
|
94 | // matches - objects to search
|
95 | // queryText - single string
|
96 | ```
|
97 |
|
98 | ```js
|
99 | var items = [{
|
100 | foo: 'foo'
|
101 | }, {
|
102 | foo: 'foo2',
|
103 | bar: 'abar'
|
104 | }, {
|
105 | foo: 'bar'
|
106 | }];
|
107 | var result = k2.rankPartialMatches(['foo', 'bar'], items, 'bar');
|
108 | // result is a new array with 3 items
|
109 | // result[0] is items[2] (exact match)
|
110 | // result[1] is items[1] (partial match)
|
111 | // result[2] is items[0] (nothing matches)
|
112 | ```
|
113 |
|
114 | ### objectLens
|
115 |
|
116 | A function for building immutable object lenses. Construct the lens with a key
|
117 | and then use its getter, setter, or mapper.
|
118 |
|
119 | ```js
|
120 | objectLens('name')({ name: 'joe' });
|
121 | // => 'joe'
|
122 | objectLens('age').set(20, { age: 19 });
|
123 | // => { age: 20 }
|
124 | objectLens('age').map(R.add(1), { age: 19 });
|
125 | // => { age: 20 }
|
126 | ```
|
127 |
|
128 | To compose setters, use function composition!
|
129 |
|
130 | ```js
|
131 | var setter = R.compose(objectLens('name').set('matt'),
|
132 | objectLens('age').map(R.add(1)));
|
133 | setter({ name: 'joe', age: 19 })
|
134 | // => { name: 'matt', age: 20 }
|
135 | ```
|
136 |
|
137 | ### onlyTrue
|
138 |
|
139 | XOR for predicates - returns true if and only if a single value is truthy.
|
140 |
|
141 | ```js
|
142 | onlyTrue(true, false, false); // true
|
143 | onlyTrue(false, false, false); // false
|
144 | onlyTrue(false, true, true); // false
|
145 | onlyTrue(false, false, true); // true
|
146 | ```
|
147 |
|
148 | ### guessDateFormat
|
149 |
|
150 | Tries to determine date format from single or list of strings. If there is ambiguity returns undefined.
|
151 |
|
152 | ```js
|
153 | guessDateFormat('2010-15-10'); // 'YYYY-DD-MM'
|
154 | guessDateFormat(['05/19/2000', '22/01/2002']); // undefined
|
155 | ```
|
156 |
|
157 | ### Small print
|
158 |
|
159 | Author: Kensho © 2015
|
160 |
|
161 | * [@kensho](https://twitter.com/kensho)
|
162 | * [kensho.com](http://kensho.com)
|
163 |
|
164 | Support: if you find any problems with this library,
|
165 | [open issue](https://github.com/kensho/k2/issues) on Github
|
166 |
|
167 | ## MIT License
|
168 |
|
169 | The MIT License (MIT)
|
170 |
|
171 | Copyright (c) 2015 Kensho
|
172 |
|
173 | Permission is hereby granted, free of charge, to any person obtaining a copy of
|
174 | this software and associated documentation files (the "Software"), to deal in
|
175 | the Software without restriction, including without limitation the rights to
|
176 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
177 | the Software, and to permit persons to whom the Software is furnished to do so,
|
178 | subject to the following conditions:
|
179 |
|
180 | The above copyright notice and this permission notice shall be included in all
|
181 | copies or substantial portions of the Software.
|
182 |
|
183 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
184 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
185 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
186 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
187 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
188 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
189 |
|