@effectify/react-router 0.2.0 → 0.4.0

package/README.md

@@ -41,15 +41,20 @@ Use the Effect-based loaders and actions in your React Router routes:
 ```typescript
 // routes/home.tsx
 import type * as Route from "./+types.home";
-import { Ok, LoaderArgsContext } from "@effectify/react-router";
+import { httpSuccess, httpFailure, LoaderArgsContext } from "@effectify/react-router";
 import { withLoaderEffect } from "~/lib/server-runtime";
-import * as T from "effect/Effect"
+import * as Effect from "effect/Effect"
 
 export const loader = withLoaderEffect(
-  T.gen(function* () {
+  Effect.gen(function* () {
     const { request } = yield* LoaderArgsContext
-    yield* T.log("request", request)
-    return yield* T.succeed(new Ok({ data: { hello: 'world' }}))
+    yield* Effect.log("request", request)
+    
+    // Improved DX: Simple syntax for success responses
+    return yield* httpSuccess({ hello: 'world' })
+    
+    // For error responses, use:
+    // return yield* httpFailure("Something went wrong")
   })
 )
 
@@ -63,6 +68,40 @@ export default function Home({ loaderData }: Route.ComponentProps) {
 }
 ```
 
+## Improved Developer Experience
+
+The library provides helper functions for better DX when returning HTTP responses:
+
+### Success Responses
+
+Instead of the verbose:
+```typescript
+return yield* Effect.succeed(new HttpResponseSuccess({ data: { hello: 'world' }}))
+```
+
+Use the simplified syntax:
+```typescript
+return yield* httpSuccess({ hello: 'world' })
+```
+
+### Error Responses
+
+For error handling, use the `httpFailure` helper:
+```typescript
+return yield* httpFailure("Something went wrong")
+// or with more complex error objects
+return yield* httpFailure({ code: 'VALIDATION_ERROR', message: 'Invalid input' })
+```
+
+### Redirects
+
+For redirects, use the `httpRedirect` helper:
+```typescript
+return yield* httpRedirect('/login')
+// or with custom status/headers
+return yield* httpRedirect('/dashboard', { status: 301 })
+```
+
 ## API
 
 ### `make(layers)`
@@ -88,9 +127,49 @@ Effect context providing access to React Router loader arguments including:
 
 ### Response Types
 
-- `Ok(data)`: Successful response with data
-- `Redirect(url)`: Redirect response
-- `Error(message)`: Error response
+- `HttpResponseSuccess<T>(data)`: Successful HTTP response with data
+- `HttpResponseFailure<T>(cause)`: Failed HTTP response with cause
+- `HttpResponseRedirect(to, init?)`: HTTP redirect response
+
+### Helper Functions
+
+- `httpSuccess<T>(data: T)`: Creates a successful Effect with HttpResponseSuccess
+- `httpFailure<T>(cause: T)`: Creates a successful Effect with HttpResponseFailure
+- `httpRedirect(to: string, init?: ResponseInit)`: Creates a successful Effect with HttpResponseRedirect
+
+### Error Handling & Logging
+
+The library provides comprehensive error handling with full ErrorBoundary support:
+
+- **Automatic Error Logging**: Errors are automatically logged using `Effect.logError`
+- **ErrorBoundary Compatible**: Loader errors are properly thrown as `Response` objects for React Router ErrorBoundary
+- **Configurable Logging**: Users can configure their own logging system through Effect layers
+- **Non-blocking**: Logging doesn't block the main thread
+- **Structured Logging**: Errors are logged with context and structured data
+- **Error Preservation**: Original error context is preserved for better debugging
+
+```typescript
+// The library automatically logs errors like this:
+Effect.tapError((cause) => Effect.logError('Loader effect failed', cause))
+
+// Loader errors are automatically converted to Response objects for ErrorBoundary:
+// - Effect errors → Response with { ok: false, errors: [...] } and status 500
+// - HttpResponseFailure → Response with { ok: false, errors: [...] } and status 500
+// - Original Response/Error objects are preserved
+
+// Users can configure custom logging through Effect layers
+const customLogger = Logger.make(({ message, cause }) => {
+  // Custom logging implementation
+  console.log(`[${new Date().toISOString()}] ${message}`, cause)
+})
+
+const runtime = make(pipe(
+  // Your app layers
+  MyAppLayer,
+  // Custom logger layer
+  Logger.replace(Logger.defaultLogger, customLogger)
+))
+```
 
 ## Requirements
 

package/dist/src/index.d.ts

@@ -1,3 +1,4 @@
 export * from './lib/context.js';
+export * as HttpApiHandler from './lib/http-api-handler.js';
 export * from './lib/http-response.js';
 export * as Runtime from './lib/runtime.js';

package/dist/src/index.js

@@ -1,3 +1,4 @@
 export * from './lib/context.js';
+export * as HttpApiHandler from './lib/http-api-handler.js';
 export * from './lib/http-response.js';
 export * as Runtime from './lib/runtime.js';

package/dist/src/lib/http-api-handler.d.ts

@@ -0,0 +1,13 @@
+/** biome-ignore-all lint/suspicious/noConsole: <debug> */
+import type * as HttpApi from '@effect/platform/HttpApi';
+import * as HttpApiScalar from '@effect/platform/HttpApiScalar';
+import * as Layer from 'effect/Layer';
+import type { ActionFunctionArgs, LoaderFunctionArgs } from 'react-router';
+export type HttpApiOptions = {
+    apiLive: Layer.Layer<HttpApi.Api, never, never>;
+    scalar?: HttpApiScalar.ScalarConfig;
+};
+export type RoutePath = '/' | `/${string}/`;
+export declare const make: (options: HttpApiOptions & {
+    pathPrefix?: RoutePath;
+}) => ({ request }: ActionFunctionArgs | LoaderFunctionArgs) => Promise<Response>;

package/dist/src/lib/http-api-handler.js

@@ -0,0 +1,17 @@
+import * as HttpApiBuilder from '@effect/platform/HttpApiBuilder';
+import * as HttpApiScalar from '@effect/platform/HttpApiScalar';
+import * as HttpServer from '@effect/platform/HttpServer';
+import { Option } from 'effect';
+import { pipe } from 'effect/Function';
+import * as Layer from 'effect/Layer';
+export const make = (options) => ({ request }) => pipe(Option.fromNullable(options.scalar), Option.map((scalar) => HttpApiScalar.layer({
+    path: `${options.pathPrefix || '/api/'}docs`,
+    scalar: {
+        ...scalar,
+        baseServerURL: new URL(request.url).origin,
+    },
+}).pipe(Layer.provide(options.apiLive))), Option.getOrElse(() => Layer.empty), (ApiDocsLive) => {
+    const EnvLive = Layer.mergeAll(options.apiLive, ApiDocsLive, HttpServer.layerContext);
+    const { handler } = HttpApiBuilder.toWebHandler(EnvLive);
+    return handler(request);
+});

package/dist/src/lib/http-response.d.ts

@@ -1,21 +1,33 @@
-declare const Ok_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => Readonly<A> & {
-    readonly _tag: "Ok";
+import * as Effect from 'effect/Effect';
+declare const HttpResponseSuccess_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => Readonly<A> & {
+    readonly _tag: "HttpResponseSuccess";
 };
-export declare class Ok<T> extends Ok_base<{
+export declare class HttpResponseSuccess<T> extends HttpResponseSuccess_base<{
     readonly data: T;
 }> {
 }
-declare const Redirect_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => Readonly<A> & {
-    readonly _tag: "Redirect";
+declare const HttpResponseFailure_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => Readonly<A> & {
+    readonly _tag: "HttpResponseFailure";
 };
-export declare class Redirect extends Redirect_base<{
+export declare class HttpResponseFailure<T = unknown> extends HttpResponseFailure_base<{
+    readonly cause: T;
+}> {
+}
+declare const HttpResponseRedirect_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => Readonly<A> & {
+    readonly _tag: "HttpResponseRedirect";
+};
+export declare class HttpResponseRedirect extends HttpResponseRedirect_base<{
     readonly to: string;
     readonly init?: number | ResponseInit | undefined;
 }> {
 }
-export type HttpResponse<T> = Redirect | Ok<T>;
+export type HttpResponse<T> = HttpResponseRedirect | HttpResponseSuccess<T> | HttpResponseFailure<unknown>;
 export declare const matchHttpResponse: <T>() => <P extends {
-    readonly Ok: (_: Ok<T>) => any;
-    readonly Redirect: (_: Redirect) => any;
-} & { readonly [Tag in Exclude<keyof P, "Ok" | "Redirect">]: never; }>(fields: P) => (input: HttpResponse<T>) => import("effect/Unify").Unify<ReturnType<P[keyof P]>>;
+    readonly HttpResponseSuccess: (_: HttpResponseSuccess<T>) => any;
+    readonly HttpResponseFailure: (_: HttpResponseFailure<unknown>) => any;
+    readonly HttpResponseRedirect: (_: HttpResponseRedirect) => any;
+} & { readonly [Tag in Exclude<keyof P, "HttpResponseSuccess" | "HttpResponseFailure" | "HttpResponseRedirect">]: never; }>(fields: P) => (input: HttpResponse<T>) => import("effect/Unify").Unify<ReturnType<P[keyof P]>>;
+export declare const httpSuccess: <T>(data: T) => Effect.Effect<HttpResponseSuccess<T>, never, never>;
+export declare const httpFailure: <T = unknown>(cause: T) => Effect.Effect<HttpResponseFailure<T>, never, never>;
+export declare const httpRedirect: (to: string, init?: number | ResponseInit) => Effect.Effect<HttpResponseRedirect, never, never>;
 export {};

package/dist/src/lib/http-response.js

@@ -1,7 +1,14 @@
 import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
 import * as Match from 'effect/Match';
-export class Ok extends Data.TaggedClass('Ok') {
+export class HttpResponseSuccess extends Data.TaggedClass('HttpResponseSuccess') {
 }
-export class Redirect extends Data.TaggedClass('Redirect') {
+export class HttpResponseFailure extends Data.TaggedClass('HttpResponseFailure') {
+}
+export class HttpResponseRedirect extends Data.TaggedClass('HttpResponseRedirect') {
 }
 export const matchHttpResponse = () => Match.typeTags();
+// Helper functions for better DX
+export const httpSuccess = (data) => Effect.succeed(new HttpResponseSuccess({ data }));
+export const httpFailure = (cause) => Effect.succeed(new HttpResponseFailure({ cause }));
+export const httpRedirect = (to, init) => Effect.succeed(new HttpResponseRedirect({ to, init }));

package/dist/src/lib/runtime.d.ts

@@ -1,21 +1,24 @@
-import * as T from 'effect/Effect';
+import * as Effect from 'effect/Effect';
 import type * as Layer from 'effect/Layer';
 import { type ActionFunctionArgs, type LoaderFunctionArgs } from 'react-router';
 import { ActionArgsContext, LoaderArgsContext } from '../lib/context.js';
 import { type HttpResponse } from '../lib/http-response.js';
 export declare const make: <R, E>(layer: Layer.Layer<R, E, never>) => {
-    withLoaderEffect: <A, B>(self: T.Effect<HttpResponse<A>, B, R | LoaderArgsContext>) => (args: LoaderFunctionArgs) => Promise<{
+    withLoaderEffect: <A, B>(self: Effect.Effect<HttpResponse<A> | Response, B, R | LoaderArgsContext>) => (args: LoaderFunctionArgs) => Promise<{
         ok: true;
         data: A;
     } | {
         ok: false;
         errors: string[];
     }>;
-    withActionEffect: <A, B_1>(self: T.Effect<HttpResponse<A>, B_1, R | ActionArgsContext>) => (args: ActionFunctionArgs) => Promise<import("react-router").UNSAFE_DataWithResponseInit<{
+    withActionEffect: <A, B_1>(self: Effect.Effect<HttpResponse<A> | Response, B_1, R | ActionArgsContext>) => (args: ActionFunctionArgs) => Promise<Response | import("react-router").UNSAFE_DataWithResponseInit<{
         ok: false;
-        errors: B_1;
+        errors: string[];
     }> | {
         ok: true;
         response: A;
-    } | Response>;
+    } | import("react-router").UNSAFE_DataWithResponseInit<{
+        ok: false;
+        errors: string[];
+    }>>;
 };

package/dist/src/lib/runtime.js

@@ -1,4 +1,4 @@
-import * as T from 'effect/Effect';
+import * as Effect from 'effect/Effect';
 import * as Exit from 'effect/Exit';
 import { pipe } from 'effect/Function';
 import * as Logger from 'effect/Logger';
@@ -9,41 +9,95 @@ import { matchHttpResponse } from '../lib/http-response.js';
 export const make = (layer) => {
     const runtime = ManagedRuntime.make(layer);
     const withLoaderEffect = (self) => (args) => {
-        const runnable = pipe(self, T.provide(Logger.pretty), T.provideService(LoaderArgsContext, args));
+        const runnable = pipe(self, Effect.provide(Logger.pretty), Effect.provideService(LoaderArgsContext, args), Effect.tapError((cause) => Effect.logError('Loader effect failed', cause)));
         return runtime.runPromiseExit(runnable).then(Exit.match({
             onFailure: (cause) => {
-                console.error(cause);
                 if (cause._tag === 'Fail') {
-                    throw pipe(cause.error);
+                    // Preserve the original error for ErrorBoundary
+                    const error = cause.error;
+                    if (error instanceof Response) {
+                        throw error;
+                    }
+                    if (error instanceof Error) {
+                        throw error;
+                    }
+                    // Convert other errors to Response for ErrorBoundary with ok: false
+                    const errorData = { ok: false, errors: [String(error)] };
+                    throw new Response(JSON.stringify(errorData), {
+                        status: 500,
+                        headers: { 'Content-Type': 'application/json' },
+                    });
                 }
-                // biome-ignore lint/style/useThrowOnlyError: <library uses non-Error throws>
-                throw { ok: false, errors: ['Something went wrong'] };
+                // Handle other types of failures (interrupts, defects, etc.)
+                console.error('Runtime execution failed with defect:', JSON.stringify(cause, null, 2));
+                const errorData = { ok: false, errors: ['Internal server error'] };
+                throw new Response(JSON.stringify(errorData), {
+                    status: 500,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            },
+            onSuccess: (result) => {
+                // If the result is a Response, throw it directly to preserve headers (including Set-Cookie)
+                // This is how React Router expects to handle Responses from loaders/actions
+                if (result instanceof Response) {
+                    throw result;
+                }
+                // Otherwise, match the HttpResponse types
+                return matchHttpResponse()({
+                    HttpResponseSuccess: ({ data: response }) => ({ ok: true, data: response }),
+                    HttpResponseFailure: ({ cause }) => {
+                        // Convert HttpResponseFailure to Response for ErrorBoundary with ok: false
+                        const errorMessage = typeof cause === 'string' ? cause : String(cause);
+                        const errorData = { ok: false, errors: [errorMessage] };
+                        throw new Response(JSON.stringify(errorData), {
+                            status: 500,
+                            headers: { 'Content-Type': 'application/json' },
+                        });
+                    },
+                    HttpResponseRedirect: ({ to, init = {} }) => {
+                        redirect(to, init);
+                        return { ok: false, errors: ['Redirecting...'] };
+                    },
+                })(result);
             },
-            onSuccess: matchHttpResponse()({
-                Ok: ({ data: response }) => {
-                    return { ok: true, data: response };
-                },
-                Redirect: ({ to, init = {} }) => {
-                    redirect(to, init);
-                    return { ok: false, errors: ['Redirecting...'] };
-                },
-            }),
         }));
     };
     // Don't throw the Error requests, handle them in the normal UI. No ErrorBoundary
     const withActionEffect = (self) => (args) => {
-        const runnable = pipe(self, T.provide(Logger.pretty), T.provideService(ActionArgsContext, args), T.match({
-            onFailure: (errors) => data({ ok: false, errors }, { status: 400 }),
-            onSuccess: matchHttpResponse()({
-                Ok: ({ data: response }) => {
-                    return { ok: true, response };
-                },
-                Redirect: ({ to, init = {} }) => {
-                    return redirect(to, init);
-                },
-            }),
+        const runnable = pipe(self, Effect.provide(Logger.pretty), Effect.provideService(ActionArgsContext, args), Effect.tapError((cause) => {
+            // Don't log if it's a Response - that's expected behavior
+            if (!(cause instanceof Response)) {
+                return Effect.logError('Action effect failed', cause);
+            }
+            return Effect.void;
+        }));
+        return runtime.runPromiseExit(runnable).then(Exit.match({
+            onFailure: (cause) => {
+                if (cause._tag === 'Fail') {
+                    const error = cause.error;
+                    // If the error is a Response, throw it directly to preserve headers
+                    if (error instanceof Response) {
+                        throw error;
+                    }
+                    return data({ ok: false, errors: [String(error)] }, { status: 400 });
+                }
+                // Handle other types of failures
+                return data({ ok: false, errors: ['Internal server error'] }, { status: 400 });
+            },
+            onSuccess: (result) => {
+                // If the result is a Response, throw it directly to preserve headers (including Set-Cookie)
+                // This is how React Router expects to handle Responses from actions
+                if (result instanceof Response) {
+                    throw result;
+                }
+                // Otherwise, match the HttpResponse types
+                return matchHttpResponse()({
+                    HttpResponseSuccess: ({ data: response }) => ({ ok: true, response }),
+                    HttpResponseFailure: ({ cause }) => data({ ok: false, errors: [String(cause)] }, { status: 400 }),
+                    HttpResponseRedirect: ({ to, init = {} }) => redirect(to, init),
+                })(result);
+            },
         }));
-        return runtime.runPromise(runnable);
     };
     return { withLoaderEffect, withActionEffect };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectify/react-router",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Integration of React Router with Effect for React applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,10 +22,10 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@effect/platform": "0.91.1",
-    "@effect/platform-node": "0.97.1",
-    "effect": "3.17.14",
-    "react-router": "7.9.2"
+    "@effect/platform": "0.93.3",
+    "@effect/platform-node": "0.101.1",
+    "effect": "3.19.6",
+    "react-router": "7.9.6"
   },
   "devDependencies": {},
   "peerDependencies": {},