@zemnmez/future 1.0.2 → 1.0.5

package/README.md

@@ -18,7 +18,7 @@ need to remain in a minified bundle.
 when a component should call all of its hooks unconditionally and select its
 loading, error, or resolved UI only after those hooks have run:
 
-```tsx
+```tsx file=examples/react-query.tsx
 import { useQuery } from '@tanstack/react-query';
 import { future, useQueryFuture } from '@zemnmez/future';
 
@@ -27,7 +27,9 @@ interface Todo {
 	title: string;
 }
 
-function TodoList() {
+declare function useTheme(): { error: string; todoList: string };
+
+export function TodoList() {
 	const theme = useTheme();
 	const todos = useQueryFuture(
 		useQuery<Todo[], Error>({
@@ -35,7 +37,7 @@ function TodoList() {
 			queryFn: async () => {
 				const response = await fetch('/api/todos');
 				if (!response.ok) throw new Error('Could not load todos.');
-				return response.json();
+				return response.json() as Promise<Todo[]>;
 			},
 		})
 	);
@@ -60,11 +62,11 @@ function TodoList() {
 Construct a Future with `resolve`, `loading`, or `error`, then handle its three
 possible states with `future`:
 
-```typescript
-import { Future, future, resolve } from '@zemnmez/future';
+```typescript file=examples/basic.ts
+import { type Future, future, resolve } from '@zemnmez/future';
 
-const answer: Future<number, number, Error> = resolve(42);
-const message = future(
+export const answer: Future<number, number, Error> = resolve(42);
+export const message = future(
 	answer,
 	value => `The answer is ${value}.`,
 	progress => `Loading: ${progress}%`,
@@ -73,19 +75,22 @@ const message = future(
 ```
 
 `future_and_then` maps a resolved value while preserving the loading and error
-types. `future_flatten_then` flattens nested Futures, and `future_collect`
-combines several Futures into one.
+types. Combine `future_and_then` with `future_flatten_then` to chain an
+operation that returns another Future, and
+`future_collect` combines several Futures into one.
 
 ## Pipelines
 
 `future_and_then` and `future_flatten_then` compose Future-returning operations
-into a pipeline. Each operation receives the preceding resolved value, while a
-loading or error state stops the pipeline:
+into a pipeline.
+Each operation receives the preceding resolved value, while a loading or error
+state stops the pipeline. The resulting Future includes the loading and error
+types from every operation:
 
-```typescript
+```typescript file=examples/pipeline.ts
 import {
 	error,
-	Future,
+	type Future,
 	future_and_then,
 	future_flatten_then,
 	resolve,
@@ -96,29 +101,20 @@ interface User {
 	name: string;
 }
 
-const findUser = (
+export const findUser = (
 	id: number
 ): Future<User, 'fetching user', 'user not found'> =>
 	id === 42
 		? resolve({ id, name: 'Deep Thought' })
 		: error('user not found');
 
-const displayName = (
+export const displayName = (
 	user: User
 ): Future<string, 'formatting name', 'missing name'> =>
 	user.name ? resolve(user.name) : error('missing name');
 
-const user = future_flatten_then(
-	future_and_then(resolve(42), findUser)
-);
-const name = future_flatten_then(
-	future_and_then(user, displayName)
-);
-// Future<
-//   string,
-//   'fetching user' | 'formatting name',
-//   'user not found' | 'missing name'
-// >
+const user = future_flatten_then(future_and_then(resolve(42), findUser));
+export const name = future_flatten_then(future_and_then(user, displayName));
 ```
 
 [result]: https://www.npmjs.com/package/@zemnmez/result

package/package.json

@@ -18,7 +18,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.0.2",
+  "version": "1.0.5",
   "dependencies": {
     "@tanstack/react-query": "5.101.4",
     "react": "19.2.8"
@@ -33,6 +33,6 @@
     "directory": "ts/future"
   },
   "bugs": {
-    "url": "https://github.com/zemn-me/monorepo/issues/new?title=%2F%2Fts%2Ffuture%401.0.2%3A+something+went+wrong%21"
+    "url": "https://github.com/zemn-me/monorepo/issues/new?title=%2F%2Fts%2Ffuture%401.0.5%3A+something+went+wrong%21"
   }
 }