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 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`: `Task`, `TaskEither`
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 TaskV<T> = () => Promise<T>;
3
- type Task<_T> = {
4
- map: never;
5
- ap: never;
6
- flatMap: never;
7
- tap: never;
8
- run: never;
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
- export { Task, TaskV, all, fromPromise, sequence, task, traverse };
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 task() {
3
- throw new Error("Not implemented");
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
- function fromPromise(_thunk) {
6
- throw new Error("Not implemented");
7
- }
8
- function all() {
9
- throw new Error("Not implemented");
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
- function traverse() {
12
- throw new Error("Not implemented");
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
- function sequence() {
15
- throw new Error("Not implemented");
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, sequence, task, traverse };
77
+ export { all, fromPromise, task };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ok-fp",
3
- "version": "0.2.0",
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": [