@kuroski/effect-svelte 1.0.0

package/README.md

@@ -0,0 +1,223 @@
+# effect-svelte
+
+Integration library for [Effect](https://effect.website/) with [SvelteKit](https://kit.svelte.dev/). Run Effect programs in SvelteKit load functions and remote functions with automatic error handling, redirects, and form validation.
+
+## Installation
+
+```sh
+npm add effect-svelte
+# or
+bun add effect-svelte
+```
+
+**Peer dependencies:** `effect >=3.19.15`, `svelte >=5`, `@sveltejs/kit >=2`
+
+## Quick Start
+
+### 1. Create a Runner
+
+```ts
+// src/lib/server/runtime.ts
+import { Effect, Layer, ManagedRuntime } from "effect";
+import { createRunner } from "effect-svelte";
+
+const AppLayer = Layer.mergeAll(
+  // your service layers
+);
+
+const RuntimeServer = ManagedRuntime.make(AppLayer);
+
+export const remoteRunner = createRunner({
+  runtime: RuntimeServer,
+  before: () => Effect.log("Starting operation"),
+  after: () => Effect.log("Operation completed"),
+  onError: (err, isUnexpectedError) =>
+    isUnexpectedError
+      ? Effect.logError("Operation failed", err)
+      : Effect.void,
+});
+```
+
+### 2. Use in Load Functions
+
+The runner works directly inside SvelteKit `load` functions. Call it with an operation name, your Effect program, and an optional error-mapping pipeline:
+
+```ts
+// src/routes/posts/+page.server.ts
+import { Effect } from "effect";
+import { httpErrorEffect } from "effect-svelte";
+import { remoteRunner } from "$lib/server/runtime";
+
+export async function load({ params }) {
+  return remoteRunner(
+    "load-posts",
+    Effect.gen(function* () {
+      const posts = yield* fetchPosts();
+
+      if (posts.length === 0) {
+        yield* httpErrorEffect(404, "NOT_FOUND", "No posts found");
+      }
+
+      return { posts };
+    }),
+  );
+}
+```
+
+```svelte
+<!-- src/routes/posts/+page.svelte -->
+<script lang="ts">
+  let { data } = $props();
+</script>
+
+<ul>
+  {#each data.posts as post (post.id)}
+    <li>{post.title}</li>
+  {/each}
+</ul>
+```
+
+### 3. Use in Remote Functions
+
+The same runner works with SvelteKit's experimental [remote functions](https://svelte.dev/docs/kit/remote-functions):
+
+```ts
+// src/routes/posts.remote.ts
+import { Effect } from "effect";
+import { query } from "$app/server";
+import { remoteRunner } from "$lib/server/runtime";
+
+export const getPosts = query(() =>
+  remoteRunner(
+    "get-posts",
+    Effect.gen(function* () {
+      yield* Effect.logInfo("Fetching posts");
+      return { posts: [{ id: 1, title: "Hello" }] };
+    }),
+  ),
+);
+```
+
+```svelte
+<!-- src/routes/+page.svelte -->
+<script lang="ts">
+  import { getPosts } from "./posts.remote.ts";
+</script>
+
+<svelte:boundary>
+  {#snippet pending()}
+    <p>loading...</p>
+  {/snippet}
+
+  {#snippet failed(error)}
+    <span>Error: {error}</span>
+  {/snippet}
+
+  {@const { posts } = await getPosts()}
+  <ul>
+    {#each posts as post (post.id)}
+      <li>{post.title}</li>
+    {/each}
+  </ul>
+</svelte:boundary>
+```
+
+## Error Handling
+
+The library provides three tagged error types that map to SvelteKit's control flow:
+
+```ts
+import { Effect } from "effect";
+import {
+  SvelteKitRedirect,
+  SvelteKitHttpError,
+  SvelteKitInvalidError,
+  redirectEffect,
+  httpErrorEffect,
+  invalidEffect,
+} from "effect-svelte";
+
+Effect.gen(function* () {
+  // Redirect (throws SvelteKit redirect())
+  yield* redirectEffect(303, "/login");
+  // or: yield* Effect.fail(SvelteKitRedirect.make(303, "/login"));
+
+  // HTTP error (throws SvelteKit error())
+  yield* httpErrorEffect(404, "NOT_FOUND", "Resource not found");
+  // or: yield* Effect.fail(SvelteKitHttpError.make(404, "NOT_FOUND", "Not found"));
+
+  // Form validation error (throws SvelteKit invalid())
+  yield* invalidEffect("email", "Invalid email format");
+  // or: yield* Effect.fail(SvelteKitInvalidError.make({ email: "Invalid" }));
+});
+```
+
+### Pipeline for Error Mapping
+
+Use the third argument of the runner to map domain errors to SvelteKit errors:
+
+```ts
+export const listProjects = remoteRunner(
+  "listProjects",
+  Effect.gen(function* () {
+    const service = yield* ProjectService;
+    return yield* service.all();
+  }),
+  (effect) =>
+    effect.pipe(
+      Effect.catchTags({
+        ParseError: () =>
+          httpErrorEffect(500, "PARSE_ERROR", "Unexpected data from the server"),
+        ResponseError: () =>
+          httpErrorEffect(500, "GENERIC_ERROR", "Unexpected server response"),
+      }),
+    ),
+);
+```
+
+## API Reference
+
+### `createRunner(options)`
+
+Creates a runner function that executes Effect programs in a SvelteKit context.
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `runtime` | `ManagedRuntime<R, never>` | The Effect runtime to use |
+| `before` | `() => Effect<void>` | Runs before the effect |
+| `after` | `(result: A) => Effect<void>` | Runs after successful execution |
+| `onError` | `(err, isUnexpectedError) => Effect<void>` | Error handler. `isUnexpectedError` is `true` for 500+ errors and unrecognized failures, `false` for redirects, validation errors, and <500 HTTP errors |
+
+**Returns:** `Runner<R>` - a function with signature:
+
+```ts
+(operationName: string, effect: Effect<A, E, R>, pipeline?: PipelineFn<R>) => Promise<A>
+```
+
+**Execution order:** `before` → `effect` → `pipeline` → `onError` (on failure) → `after` (on success) → `withSpan(operationName)`
+
+### Error Types
+
+| Class | Converts to | Factory |
+|-------|-------------|---------|
+| `SvelteKitRedirect` | `redirect(status, location)` | `SvelteKitRedirect.make(status, location)` |
+| `SvelteKitHttpError` | `error(status, body)` | `SvelteKitHttpError.make(status, code, message, details?)` |
+| `SvelteKitInvalidError` | `invalid(issues)` | `SvelteKitInvalidError.make(issues)` |
+
+### Convenience Functions
+
+| Function | Description |
+|----------|-------------|
+| `redirectEffect(status, location)` | Returns `Effect.fail(SvelteKitRedirect.make(...))` |
+| `httpErrorEffect(status, code, message, details?)` | Returns `Effect.fail(SvelteKitHttpError.make(...))` |
+| `invalidEffect(issues)` | Returns `Effect.fail(SvelteKitInvalidError.make(...))` |
+
+### `SvelteEffect.Code`
+
+Error code type: `"GENERIC_ERROR" | "PARSE_ERROR" | "NOT_FOUND" | "UNAUTHORIZED"`
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,67 @@
+import type { HttpError, invalid, Redirect } from "@sveltejs/kit";
+import { Effect } from "effect";
+export declare namespace SvelteEffect {
+    type Code = "GENERIC_ERROR" | "PARSE_ERROR" | "NOT_FOUND" | "UNAUTHORIZED";
+    interface ErrorBody {
+        code: Code;
+        details?: Record<string, unknown>;
+        message: string;
+        timestamp: string;
+    }
+}
+export declare class SvelteKitError extends Error implements SvelteEffect.ErrorBody {
+    code: SvelteEffect.Code;
+    details?: Record<string, unknown>;
+    timestamp: string;
+    constructor(message: string, code: SvelteEffect.Code, details?: Record<string, unknown>);
+}
+declare const SvelteKitRedirect_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]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SvelteKitRedirect";
+} & Readonly<A>;
+/**
+ * Tagged error representing a SvelteKit redirect.
+ *
+ * When handled by the runner it is converted to a thrown SvelteKit `redirect()`.
+ */
+export declare class SvelteKitRedirect extends SvelteKitRedirect_base<{
+    readonly status: Redirect["status"];
+    readonly location: string;
+}> {
+    static make(status: Redirect["status"], location: string): SvelteKitRedirect;
+}
+declare const SvelteKitHttpError_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]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SvelteKitHttpError";
+} & Readonly<A>;
+/**
+ * Tagged error representing a SvelteKit HTTP error.
+ *
+ * When handled by the runner it is converted to a thrown SvelteKit `error()`.
+ */
+export declare class SvelteKitHttpError extends SvelteKitHttpError_base<{
+    readonly status: HttpError["status"];
+    readonly body: {
+        code: SvelteEffect.Code;
+        details?: Record<string, unknown> | undefined;
+        message: string;
+        timestamp: string;
+    };
+}> {
+    static make(status: HttpError["status"], code: SvelteEffect.Code, message: string, details?: Record<string, unknown> | undefined): SvelteKitHttpError;
+}
+declare const SvelteKitInvalidError_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]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SvelteKitInvalidError";
+} & Readonly<A>;
+/**
+ * Tagged error representing SvelteKit form validation errors.
+ *
+ * When handled by the runner it is converted to a thrown SvelteKit `invalid()`.
+ */
+export declare class SvelteKitInvalidError extends SvelteKitInvalidError_base<{
+    readonly issues: Parameters<typeof invalid>;
+}> {
+    static make(...issues: Parameters<typeof invalid>): SvelteKitInvalidError;
+}
+export declare function redirectEffect(status: Redirect["status"], location: string): Effect.Effect<never, SvelteKitRedirect>;
+export declare function httpErrorEffect(status: HttpError["status"], code: SvelteEffect.Code, message: string, details?: Record<string, unknown>): Effect.Effect<never, SvelteKitHttpError>;
+export declare function invalidEffect(...issues: [field: string, message: string] | [Record<string, string>]): Effect.Effect<never, SvelteKitInvalidError>;
+export {};

package/dist/errors.js

@@ -0,0 +1,63 @@
+import { Data, Effect } from "effect";
+export class SvelteKitError extends Error {
+    constructor(message, code, details) {
+        super(message);
+        this.name = "SvelteKitError";
+        this.code = code;
+        this.details = details;
+        this.timestamp = new Date().toISOString();
+    }
+}
+// ---------------------------------------------------------------------------
+// Tagged errors (used inside Effect programs)
+// ---------------------------------------------------------------------------
+/**
+ * Tagged error representing a SvelteKit redirect.
+ *
+ * When handled by the runner it is converted to a thrown SvelteKit `redirect()`.
+ */
+export class SvelteKitRedirect extends Data.TaggedError("SvelteKitRedirect") {
+    static make(status, location) {
+        return new SvelteKitRedirect({ location, status });
+    }
+}
+/**
+ * Tagged error representing a SvelteKit HTTP error.
+ *
+ * When handled by the runner it is converted to a thrown SvelteKit `error()`.
+ */
+export class SvelteKitHttpError extends Data.TaggedError("SvelteKitHttpError") {
+    static make(status, code, message, details) {
+        return new SvelteKitHttpError({
+            body: {
+                code,
+                details,
+                message,
+                timestamp: new Date().toISOString(),
+            },
+            status,
+        });
+    }
+}
+/**
+ * Tagged error representing SvelteKit form validation errors.
+ *
+ * When handled by the runner it is converted to a thrown SvelteKit `invalid()`.
+ */
+export class SvelteKitInvalidError extends Data.TaggedError("SvelteKitInvalidError") {
+    static make(...issues) {
+        return new SvelteKitInvalidError({ issues });
+    }
+}
+// ---------------------------------------------------------------------------
+// Convenience effect constructors
+// ---------------------------------------------------------------------------
+export function redirectEffect(status, location) {
+    return Effect.fail(SvelteKitRedirect.make(status, location));
+}
+export function httpErrorEffect(status, code, message, details) {
+    return Effect.fail(SvelteKitHttpError.make(status, code, message, details));
+}
+export function invalidEffect(...issues) {
+    return Effect.fail(SvelteKitInvalidError.make(...issues));
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./errors.js";
+export * from "./runner.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./errors.js";
+export * from "./runner.js";

package/dist/runner.d.ts

@@ -0,0 +1,10 @@
+import { Effect, type ManagedRuntime } from "effect";
+export interface RunnerOptions<R> {
+    runtime: ManagedRuntime.ManagedRuntime<R, never>;
+    before?: () => Effect.Effect<void>;
+    after?: <A>(result: A) => Effect.Effect<void>;
+    onError?: (err: unknown, isUnexpectedError: boolean) => Effect.Effect<void>;
+}
+export type PipelineFn<A, E, R> = (effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+export type Runner<R> = <A, E>(operationName: string, effect: Effect.Effect<A, E, R>, pipeline?: PipelineFn<A, E, R>) => Promise<A>;
+export declare function createRunner<R>(options: RunnerOptions<R>): Runner<R>;

package/dist/runner.js

@@ -0,0 +1,59 @@
+import { error, invalid, redirect } from "@sveltejs/kit";
+import { Cause, Effect, Exit, Function, Match, Option, } from "effect";
+import { SvelteKitError, SvelteKitHttpError, SvelteKitInvalidError, SvelteKitRedirect, } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function isUnexpectedError(err) {
+    if (err instanceof SvelteKitRedirect)
+        return false;
+    if (err instanceof SvelteKitInvalidError)
+        return false;
+    if (err instanceof SvelteKitHttpError && err.status < 500)
+        return false;
+    return true;
+}
+function handleExit(exit) {
+    return Exit.match(exit, {
+        onFailure: (cause) => Function.pipe(Cause.failureOption(cause), Option.match({
+            onNone: () => {
+                console.error("Unhandled Effect error:", Cause.pretty(cause));
+                throw error(500, new SvelteKitError("Internal Server Error", "GENERIC_ERROR"));
+            },
+            onSome: (failure) => Match.value(failure).pipe(Match.when(Match.instanceOf(SvelteKitRedirect), (err) => {
+                throw redirect(err.status, err.location);
+            }), Match.when(Match.instanceOf(SvelteKitHttpError), (err) => {
+                throw error(err.status, new SvelteKitError(err.body.message, err.body.code, err.body.details));
+            }), Match.when(Match.instanceOf(SvelteKitInvalidError), (err) => {
+                throw invalid(...err.issues);
+            }), Match.orElse(() => {
+                console.error("Unhandled Effect error:", Cause.pretty(cause));
+                throw error(500, new SvelteKitError("Internal Server Error", "GENERIC_ERROR"));
+            })),
+        })),
+        onSuccess: Function.identity,
+    });
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function createRunner(options) {
+    return async function remoteRunner(operationName, effect, pipeline) {
+        let program = options.before
+            ? Effect.zipRight(options.before(), effect)
+            : effect;
+        if (pipeline) {
+            program = pipeline(program);
+        }
+        program = program.pipe(Effect.tapError((err) => {
+            if (!options.onError)
+                return Effect.void;
+            return options.onError(err, isUnexpectedError(err));
+        }));
+        if (options.after) {
+            program = program.pipe(Effect.tap(options.after));
+        }
+        const exit = await options.runtime.runPromiseExit(program.pipe(Effect.withSpan(operationName)));
+        return handleExit(exit);
+    };
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "author": {
+    "email": "daniel.kuroski@gmail.com",
+    "name": "Daniel Kuroski",
+    "url": "https://github.com/kuroski"
+  },
+  "bugs": {
+    "url": "https://github.com/kuroski/effect-svelte/issues"
+  },
+  "description": "Integration library for Effect with SvelteKit - seamless effect handling in SvelteKit remote functions",
+  "devDependencies": {
+    "@biomejs/biome": "2.3.13",
+    "@commitlint/cli": "20.4.0",
+    "@commitlint/config-conventional": "20.4.0",
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/git": "10.0.1",
+    "@sveltejs/kit": "2.50.1",
+    "@sveltejs/package": "2.5.7",
+    "@sveltejs/vite-plugin-svelte": "6.2.4",
+    "husky": "9.1.7",
+    "publint": "0.3.17",
+    "semantic-release": "25.0.3",
+    "svelte": "5.49.1",
+    "svelte-check": "4.3.6",
+    "typescript": "5.9.3",
+    "vite": "7.3.1",
+    "vitest": "4.0.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "homepage": "https://github.com/kuroski/effect-svelte#readme",
+  "keywords": [
+    "sveltekit",
+    "effect",
+    "effect-ts",
+    "svelte",
+    "functional",
+    "error-handling"
+  ],
+  "license": "MIT",
+  "name": "@kuroski/effect-svelte",
+  "peerDependencies": {
+    "@sveltejs/kit": ">=2.0.0",
+    "effect": ">=3.19.15 <4.0.0",
+    "svelte": ">=5.49.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuroski/effect-svelte.git"
+  },
+  "scripts": {
+    "biome:check": "biome check --write",
+    "biome:ci": "biome check",
+    "build": "vite build && bun run prepack",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "dev": "vite dev",
+    "prepack": "svelte-kit sync && svelte-package && publint",
+    "prepare": "husky && (svelte-kit sync || echo '')",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}