ok-fp 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/dist/task.d.mts +144 -14
- package/dist/task.mjs +71 -13
- package/package.json +5 -1
package/README.md
CHANGED
|
@@ -12,8 +12,8 @@ It provides a minimal set of **typed effects**: composable, type-safe wrappers f
|
|
|
12
12
|
|
|
13
13
|
OK-FP is pre-1.0.
|
|
14
14
|
|
|
15
|
-
- ✅ Implemented: `Option`, `Either`, `Validation`
|
|
16
|
-
- 🚧 Planned before `v1.0.0`: `
|
|
15
|
+
- ✅ Implemented: `Option`, `Either`, `Validation`, `Task`
|
|
16
|
+
- 🚧 Planned before `v1.0.0`: `TaskEither`
|
|
17
17
|
|
|
18
18
|
See: [ROADMAP.md](./ROADMAP.md)
|
|
19
19
|
|
package/dist/task.d.mts
CHANGED
|
@@ -1,16 +1,146 @@
|
|
|
1
|
-
//#region src/task.d.ts
|
|
2
|
-
type
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
1
|
+
//#region src/task/model.d.ts
|
|
2
|
+
type TaskValue<T> = () => Promise<T>;
|
|
3
|
+
//#endregion
|
|
4
|
+
//#region src/task/task.d.ts
|
|
5
|
+
type Task<T> = {
|
|
6
|
+
/**
|
|
7
|
+
* Transforms the value produced by the Task using a mapping function.
|
|
8
|
+
*
|
|
9
|
+
* @typeParam U - The type of the transformed value
|
|
10
|
+
* @param mapper - Function to transform the resolved value
|
|
11
|
+
* @returns A new Task that resolves with the transformed value
|
|
12
|
+
*
|
|
13
|
+
* @example
|
|
14
|
+
* ```typescript
|
|
15
|
+
* task(5).map(x => x * 2).run() // Promise<10>
|
|
16
|
+
* ```
|
|
17
|
+
*/
|
|
18
|
+
map: <U>(mapper: (value: T) => U) => Task<U>;
|
|
19
|
+
/**
|
|
20
|
+
* Applies a function wrapped in a Task to a value wrapped in a Task.
|
|
21
|
+
* Both Tasks are run concurrently.
|
|
22
|
+
*
|
|
23
|
+
* @typeParam A - The type of the argument value
|
|
24
|
+
* @typeParam U - The type of the function's return value
|
|
25
|
+
* @param arg - Task containing the argument to apply the function to
|
|
26
|
+
* @returns Task containing the function result
|
|
27
|
+
*
|
|
28
|
+
* @example
|
|
29
|
+
* ```typescript
|
|
30
|
+
* const add = (x: number) => (y: number) => x + y;
|
|
31
|
+
* task(add(5)).ap(task(3)).run() // Promise<8>
|
|
32
|
+
* ```
|
|
33
|
+
*/
|
|
34
|
+
ap: <A, U>(this: Task<(a: A) => U>, arg: Task<A>) => Task<U>;
|
|
35
|
+
/**
|
|
36
|
+
* Combines this Task with another Task into a tuple.
|
|
37
|
+
* Both Tasks are run concurrently.
|
|
38
|
+
*
|
|
39
|
+
* @typeParam A - The type of the value in the other Task
|
|
40
|
+
* @param taskA - The Task to combine with this one
|
|
41
|
+
* @returns Task containing a tuple of both values
|
|
42
|
+
*
|
|
43
|
+
* @example
|
|
44
|
+
* ```typescript
|
|
45
|
+
* task("Alice").zip(task(30)).run() // Promise<["Alice", 30]>
|
|
46
|
+
* ```
|
|
47
|
+
*/
|
|
48
|
+
zip: <A>(taskA: Task<A>) => Task<readonly [T, A]>;
|
|
49
|
+
/**
|
|
50
|
+
* Flattens a nested Task structure by removing one level of nesting.
|
|
51
|
+
*
|
|
52
|
+
* @returns The inner Task result
|
|
53
|
+
*
|
|
54
|
+
* @example
|
|
55
|
+
* ```typescript
|
|
56
|
+
* task(task(42)).flatten().run() // Promise<42>
|
|
57
|
+
* ```
|
|
58
|
+
*/
|
|
59
|
+
flatten: <U>(this: Task<Task<U>>) => Task<U>;
|
|
60
|
+
/**
|
|
61
|
+
* Chains Task-returning operations together (monadic bind).
|
|
62
|
+
*
|
|
63
|
+
* @typeParam U - The type of the value in the returned Task
|
|
64
|
+
* @param mapper - Function that takes a resolved value and returns a Task
|
|
65
|
+
* @returns The Task returned by mapper
|
|
66
|
+
*
|
|
67
|
+
* @example
|
|
68
|
+
* ```typescript
|
|
69
|
+
* task(10).flatMap(x => task(x * 2)).run() // Promise<20>
|
|
70
|
+
* ```
|
|
71
|
+
*/
|
|
72
|
+
flatMap: <U>(mapper: (value: T) => Task<U>) => Task<U>;
|
|
73
|
+
/**
|
|
74
|
+
* Performs a side effect with the resolved value, returning the original Task unchanged.
|
|
75
|
+
*
|
|
76
|
+
* @param sideEffect - Function to execute with the resolved value (return value is ignored)
|
|
77
|
+
* @returns The same Task instance unchanged
|
|
78
|
+
*
|
|
79
|
+
* @example
|
|
80
|
+
* ```typescript
|
|
81
|
+
* task(42)
|
|
82
|
+
* .tap(value => console.log(`Got value: ${value}`))
|
|
83
|
+
* .run() // Logs: "Got value: 42", resolves to 42
|
|
84
|
+
* ```
|
|
85
|
+
*/
|
|
86
|
+
tap: (sideEffect: (value: T) => unknown) => Task<T>;
|
|
87
|
+
/**
|
|
88
|
+
* Executes the Task and returns the resulting Promise.
|
|
89
|
+
*
|
|
90
|
+
* @returns A Promise that resolves with the Task's value
|
|
91
|
+
*
|
|
92
|
+
* @example
|
|
93
|
+
* ```typescript
|
|
94
|
+
* const result = await task(42).run(); // 42
|
|
95
|
+
* ```
|
|
96
|
+
*/
|
|
97
|
+
run: () => Promise<T>;
|
|
9
98
|
};
|
|
10
|
-
declare function task<T>(): Task<T>;
|
|
11
|
-
declare function fromPromise<T>(_thunk: () => Promise<T>): void;
|
|
12
|
-
declare function all(): void;
|
|
13
|
-
declare function traverse(): void;
|
|
14
|
-
declare function sequence(): void;
|
|
15
99
|
//#endregion
|
|
16
|
-
|
|
100
|
+
//#region src/task/constructors.d.ts
|
|
101
|
+
/**
|
|
102
|
+
* Creates a Task that immediately resolves with the provided value.
|
|
103
|
+
*
|
|
104
|
+
* @typeParam T - The type of the value
|
|
105
|
+
* @param value - The value to wrap in a Task
|
|
106
|
+
* @returns Task that resolves with the given value
|
|
107
|
+
*
|
|
108
|
+
* @example
|
|
109
|
+
* ```typescript
|
|
110
|
+
* const t = task(42); // Task<number>
|
|
111
|
+
* await t.run(); // 42
|
|
112
|
+
* ```
|
|
113
|
+
*/
|
|
114
|
+
declare function task<T>(value: T): Task<T>;
|
|
115
|
+
/**
|
|
116
|
+
* Creates a Task from a lazy Promise-returning thunk.
|
|
117
|
+
* The thunk is not called until `run()` is invoked.
|
|
118
|
+
*
|
|
119
|
+
* @typeParam T - The type of the resolved value
|
|
120
|
+
* @param thunk - A function that returns a Promise
|
|
121
|
+
* @returns Task wrapping the lazy Promise
|
|
122
|
+
*
|
|
123
|
+
* @example
|
|
124
|
+
* ```typescript
|
|
125
|
+
* const fetchUser = fromPromise(() => fetch("/api/user").then(r => r.json()));
|
|
126
|
+
* await fetchUser.run(); // fetches the user
|
|
127
|
+
* ```
|
|
128
|
+
*/
|
|
129
|
+
declare function fromPromise<T>(thunk: () => Promise<T>): Task<T>;
|
|
130
|
+
//#endregion
|
|
131
|
+
//#region src/task/helpers.d.ts
|
|
132
|
+
/**
|
|
133
|
+
* Runs all Tasks concurrently and collects their results into an array.
|
|
134
|
+
* Equivalent to `Promise.all` for Tasks.
|
|
135
|
+
*
|
|
136
|
+
* @param tasks - Array of Tasks to run concurrently
|
|
137
|
+
* @returns Task that resolves with an array of all results
|
|
138
|
+
*
|
|
139
|
+
* @example
|
|
140
|
+
* ```typescript
|
|
141
|
+
* await all([task(1), task(2), task(3)]).run() // [1, 2, 3]
|
|
142
|
+
* ```
|
|
143
|
+
*/
|
|
144
|
+
declare function all<T>(tasks: Task<T>[]): Task<T[]>;
|
|
145
|
+
//#endregion
|
|
146
|
+
export { type Task, type TaskValue, all, fromPromise, task };
|
package/dist/task.mjs
CHANGED
|
@@ -1,19 +1,77 @@
|
|
|
1
|
-
//#region src/task.ts
|
|
2
|
-
function
|
|
3
|
-
|
|
1
|
+
//#region src/task/task.ts
|
|
2
|
+
function createTask(thunk) {
|
|
3
|
+
const t = {
|
|
4
|
+
map: (mapper) => createTask(() => thunk().then(mapper)),
|
|
5
|
+
ap: function(arg) {
|
|
6
|
+
return createTask(() => Promise.all([this.run(), arg.run()]).then(([fn, a]) => fn(a)));
|
|
7
|
+
},
|
|
8
|
+
zip: (taskA) => t.map((value) => (a) => [value, a]).ap(taskA),
|
|
9
|
+
flatten: function() {
|
|
10
|
+
return this.flatMap((value) => value);
|
|
11
|
+
},
|
|
12
|
+
flatMap: (mapper) => createTask(() => thunk().then((value) => mapper(value).run())),
|
|
13
|
+
tap: (sideEffect) => createTask(() => thunk().then((value) => {
|
|
14
|
+
sideEffect(value);
|
|
15
|
+
return value;
|
|
16
|
+
})),
|
|
17
|
+
run: () => thunk()
|
|
18
|
+
};
|
|
19
|
+
return t;
|
|
4
20
|
}
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
21
|
+
|
|
22
|
+
//#endregion
|
|
23
|
+
//#region src/task/constructors.ts
|
|
24
|
+
/**
|
|
25
|
+
* Creates a Task that immediately resolves with the provided value.
|
|
26
|
+
*
|
|
27
|
+
* @typeParam T - The type of the value
|
|
28
|
+
* @param value - The value to wrap in a Task
|
|
29
|
+
* @returns Task that resolves with the given value
|
|
30
|
+
*
|
|
31
|
+
* @example
|
|
32
|
+
* ```typescript
|
|
33
|
+
* const t = task(42); // Task<number>
|
|
34
|
+
* await t.run(); // 42
|
|
35
|
+
* ```
|
|
36
|
+
*/
|
|
37
|
+
function task(value) {
|
|
38
|
+
return createTask(() => Promise.resolve(value));
|
|
10
39
|
}
|
|
11
|
-
|
|
12
|
-
|
|
40
|
+
/**
|
|
41
|
+
* Creates a Task from a lazy Promise-returning thunk.
|
|
42
|
+
* The thunk is not called until `run()` is invoked.
|
|
43
|
+
*
|
|
44
|
+
* @typeParam T - The type of the resolved value
|
|
45
|
+
* @param thunk - A function that returns a Promise
|
|
46
|
+
* @returns Task wrapping the lazy Promise
|
|
47
|
+
*
|
|
48
|
+
* @example
|
|
49
|
+
* ```typescript
|
|
50
|
+
* const fetchUser = fromPromise(() => fetch("/api/user").then(r => r.json()));
|
|
51
|
+
* await fetchUser.run(); // fetches the user
|
|
52
|
+
* ```
|
|
53
|
+
*/
|
|
54
|
+
function fromPromise(thunk) {
|
|
55
|
+
return createTask(thunk);
|
|
13
56
|
}
|
|
14
|
-
|
|
15
|
-
|
|
57
|
+
|
|
58
|
+
//#endregion
|
|
59
|
+
//#region src/task/helpers.ts
|
|
60
|
+
/**
|
|
61
|
+
* Runs all Tasks concurrently and collects their results into an array.
|
|
62
|
+
* Equivalent to `Promise.all` for Tasks.
|
|
63
|
+
*
|
|
64
|
+
* @param tasks - Array of Tasks to run concurrently
|
|
65
|
+
* @returns Task that resolves with an array of all results
|
|
66
|
+
*
|
|
67
|
+
* @example
|
|
68
|
+
* ```typescript
|
|
69
|
+
* await all([task(1), task(2), task(3)]).run() // [1, 2, 3]
|
|
70
|
+
* ```
|
|
71
|
+
*/
|
|
72
|
+
function all(tasks) {
|
|
73
|
+
return createTask(() => Promise.all(tasks.map((t) => t.run())));
|
|
16
74
|
}
|
|
17
75
|
|
|
18
76
|
//#endregion
|
|
19
|
-
export { all, fromPromise,
|
|
77
|
+
export { all, fromPromise, task };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ok-fp",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Essential Effect Data Types for TypeScript",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"typescript",
|
|
@@ -39,6 +39,10 @@
|
|
|
39
39
|
"./validation": {
|
|
40
40
|
"types": "./dist/validation.d.mts",
|
|
41
41
|
"default": "./dist/validation.mjs"
|
|
42
|
+
},
|
|
43
|
+
"./task": {
|
|
44
|
+
"types": "./dist/task.d.mts",
|
|
45
|
+
"default": "./dist/task.mjs"
|
|
42
46
|
}
|
|
43
47
|
},
|
|
44
48
|
"files": [
|