0
# prelude-ls
1

2
prelude-ls is a functionally oriented utility library for LiveScript and JavaScript that provides a comprehensive collection of curried functions for data manipulation. It offers 137 functions across five modules covering list operations, object manipulation, string processing, mathematical operations, and function utilities, designed for elegant functional programming patterns and function composition.
3

4
## Package Information
5

6
- **Package Name**: prelude-ls
7
- **Package Type**: npm
8
- **Language**: LiveScript (compiled to JavaScript)
9
- **Installation**: `npm install prelude-ls`
10

11
## Core Imports
12

13
```javascript
14
const prelude = require('prelude-ls');
15
// Access all functions: prelude.map, prelude.filter, prelude.fold, etc.
16
```
17

18
ES6 destructuring:
19

20
```javascript
21
const { map, filter, fold, curry, split, keys } = require('prelude-ls');
22
```
23

24
Module-specific imports:
25

26
```javascript
27
const List = require('prelude-ls/lib/List');
28
const Func = require('prelude-ls/lib/Func');
29
const Str = require('prelude-ls/lib/Str');
30
const Obj = require('prelude-ls/lib/Obj');
31
const Num = require('prelude-ls/lib/Num');
32
```
33

34
## Basic Usage
35

36
```javascript
37
const { map, filter, fold, curry, split, join } = require('prelude-ls');
38

39
// Functional programming with curried functions
40
const numbers = [1, 2, 3, 4, 5];
41
const processNumbers = fold((acc, x) => acc + x, 0);
42
const doubled = map(x => x * 2);
43
const evens = filter(x => x % 2 === 0);
44

45
const result = processNumbers(evens(doubled(numbers)));
46
// Result: 12 (sum of [2, 4, 6, 8, 10])
47

48
// String processing
49
const words = split(' ', 'hello world from prelude');
50
const capitalized = map(word => word.charAt(0).toUpperCase() + word.slice(1));
51
const result2 = join(' ', capitalized(words));
52
// Result: "Hello World From Prelude"
53
```
54

55
## Architecture
56

57
prelude-ls is organized around five specialized modules that work together seamlessly:
58

59
- **Function Module (Func)**: Core functional programming utilities including currying, composition, and higher-order functions
60
- **List Module (List)**: Comprehensive array operations with 69 functions covering iteration, transformation, folding, sorting, and searching
61
- **Object Module (Obj)**: Object manipulation utilities for conversion, iteration, and property operations
62
- **String Module (Str)**: String processing functions including splitting, joining, case conversion, and character manipulation
63
- **Number Module (Num)**: Mathematical operations, trigonometric functions, and number property testing
64

65
**Key Design Principles:**
66
- **Currying**: 85 functions are automatically curried for partial application and function composition
67
- **Immutability**: All operations return new values without modifying original data
68
- **Functional Style**: Designed for point-free programming and function composition
69
- **LiveScript Integration**: Optimized for LiveScript syntax but works perfectly with JavaScript
70

71
## Capabilities
72

73
### List Operations
74

75
Comprehensive array manipulation with functional programming patterns. Includes iteration, transformation, folding, sorting, searching, and mathematical operations on arrays.
76

77
```javascript { .api }
78
// Core iteration and transformation
79
function each(fn, array);
80
function map(fn, array);
81
function filter(predicate, array);
82
function fold(fn, initial, array);
83

84
// Array structure operations
85
function head(array);
86
function tail(array);
87
function reverse(array);
88
function flatten(array);
89
```
90

91
[List Operations](./list-operations.md)
92

93
### Object Operations
94

95
Object manipulation utilities for converting between objects and arrays, iterating over properties, and transforming object structures.
96

97
```javascript { .api }
98
// Object conversion
99
function keys(object);
100
function values(object);
101
function objToPairs(object);
102
function pairsToObj(pairs);
103

104
// Object transformation
105
function map(fn, object);
106
function filter(predicate, object);
107
```
108

109
[Object Operations](./object-operations.md)
110

111
### String Processing
112

113
String manipulation functions including splitting, joining, case conversion, and character-level operations. Many functions inherit list operations for treating strings as character arrays.
114

115
```javascript { .api }
116
// String splitting and joining
117
function split(separator, string);
118
function join(separator, array);
119
function words(string);
120
function lines(string);
121

122
// Case conversion
123
function capitalize(string);
124
function camelize(string);
125
function dasherize(string);
126
```
127

128
[String Processing](./string-processing.md)
129

130
### Function Utilities
131

132
Core functional programming utilities including currying, function composition, argument manipulation, and memoization.
133

134
```javascript { .api }
135
// Function transformation
136
function curry(fn);
137
function flip(fn);
138
function apply(fn, args);
139

140
// Function composition
141
function over(fn, gn, x, y);
142
function fix(fn);
143
```
144

145
[Function Utilities](./function-utilities.md)
146

147
### Mathematical Operations
148

149
Comprehensive mathematical functions including basic arithmetic, trigonometry, logarithmic operations, and number property testing.
150

151
```javascript { .api }
152
// Basic operations
153
function max(a, b);
154
function min(a, b);
155
function abs(n);
156
function signum(n);
157

158
// Division operations
159
function div(a, b);
160
function mod(a, b);
161
function quot(a, b);
162
function rem(a, b);
163

164
// Trigonometric functions
165
function sin(x);
166
function cos(x);
167
function tan(x);
168
```
169

170
[Mathematical Operations](./mathematical-operations.md)
171

172
## Core Types
173

174
```javascript { .api }
175
// Built-in utility functions
176
function id(x);                    // Identity function
177
function isType(type, value);      // Type checking
178
function replicate(n, value);      // Create array with n copies of value
179

180
// Constants
181
const VERSION = "1.2.1";           // Library version
182
```
183

184
## Common Patterns
185

186
### Function Composition
187

188
```javascript
189
const { map, filter, fold, curry } = require('prelude-ls');
190

191
// Create reusable functions through currying
192
const double = map(x => x * 2);
193
const evens = filter(x => x % 2 === 0);
194
const sum = fold((a, b) => a + b, 0);
195

196
// Compose operations
197
const processNumbers = numbers => sum(evens(double(numbers)));
198
```
199

200
### Data Pipeline Processing
201

202
```javascript
203
const { split, map, filter, join } = require('prelude-ls');
204

205
const processText = text => 
206
  join(' ', 
207
    filter(word => word.length > 3,
208
      map(word => word.toLowerCase(),
209
        split(' ', text))));
210
```