@rc312/tss-effect-serverfn 0.0.0-stage → 0.1.0

package/dist/vite.d.ts

@@ -0,0 +1,24 @@
+import type { Plugin } from "vite";
+/**
+ * Adapt Effect Schemas and handlers before TanStack Start compiles server functions.
+ *
+ * Install before `tanstackStart()`. The plugin recognizes static builder chains
+ * and transparent aliases/re-exports, wraps validator and handler arguments, and
+ * emits source maps. Start remains responsible for extraction, RPC identifiers,
+ * manifests, and removal of server implementations from browser bundles.
+ *
+ * @returns A Vite pre-transform plugin with build/watch module-cache invalidation.
+ *
+ * @example
+ * ```ts
+ * import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+ * import { effectServerFns } from "@rc312/tss-effect-serverfn/vite";
+ * import { defineConfig } from "vite";
+ *
+ * export default defineConfig({
+ *   plugins: [effectServerFns(), tanstackStart()],
+ * });
+ * ```
+ */
+export declare const effectServerFns: () => Plugin;
+//# sourceMappingURL=vite.d.ts.map

package/dist/vite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAuWnC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,QAAO,MA6ElC,CAAC"}

package/dist/vite.js

@@ -0,0 +1,296 @@
+import { readFile } from "node:fs/promises";
+import * as babel from "@babel/core";
+import * as t from "@babel/types";
+const runtimeModule = "@rc312/tss-effect-serverfn/compiler-runtime";
+const builderMethods = new Set(["middleware", "validator", "handler"]);
+const staticName = (node) => {
+    if (t.isIdentifier(node)) {
+        return node.name;
+    }
+    return t.isStringLiteral(node) ? node.value : undefined;
+};
+const parseModule = async (code, id) => {
+    const ast = await babel.parseAsync(code, {
+        babelrc: false,
+        configFile: false,
+        filename: id,
+        parserOpts: { plugins: ["typescript", "jsx"] },
+        sourceType: "module",
+    });
+    let program;
+    if (ast) {
+        babel.traverse(ast, {
+            Program(path) {
+                program = path;
+                path.stop();
+            },
+        });
+    }
+    if (!ast || !program) {
+        throw new Error(`Unable to parse Effect server functions in ${id}`);
+    }
+    return { ast, program };
+};
+/**
+ * Resolve whether an expression originates from `createEffectServerFn`.
+ * Follows lexical bindings, configured builders, and application re-exports;
+ * Babel NodePaths preserve scope so shadowed names are not mistaken for imports.
+ * Traversal-local visited keys terminate alias and export cycles.
+ *
+ * @param load - Load an application module with its binding-aware Program path.
+ * @param resolve - Resolve imports through Vite's module-resolution rules.
+ * @returns An asynchronous predicate over expressions in a module.
+ * @throws {Error} When a recognized factory uses unsupported mutable or dynamic composition.
+ */
+const createFactoryResolver = (load, resolve) => {
+    const trace = {
+        async factory(path, id, seen = new Set()) {
+            if (path.isTSAsExpression()) {
+                return trace.factory(path.get("expression"), id, seen);
+            }
+            if (path.isTSSatisfiesExpression()) {
+                return trace.factory(path.get("expression"), id, seen);
+            }
+            if (path.isTSNonNullExpression()) {
+                return trace.factory(path.get("expression"), id, seen);
+            }
+            if (path.isCallExpression()) {
+                return trace.factory(path.get("callee"), id, seen);
+            }
+            if (path.isMemberExpression()) {
+                return trace.member(path, id, seen);
+            }
+            if (path.isImportSpecifier() && path.parentPath.isImportDeclaration()) {
+                const { imported } = path.node;
+                return trace.imported(path.parentPath.node.source.value, t.isIdentifier(imported) ? imported.name : imported.value, id, seen);
+            }
+            if (path.isVariableDeclarator()) {
+                return trace.factory(path.get("init"), id, seen);
+            }
+            if (path.isArrowFunctionExpression() &&
+                (await trace.factory(path.get("body"), id, seen))) {
+                throw new Error(`Effect factory wrappers are not supported in ${id}; export a configured builder directly`);
+            }
+            if (!path.isIdentifier()) {
+                return false;
+            }
+            const binding = path.scope.getBinding(path.node.name);
+            const key = `${id}:${binding?.scope.uid}:${path.node.name}`;
+            if (!binding || seen.has(key)) {
+                return false;
+            }
+            const found = await trace.factory(binding.path, id, new Set([...seen, key]));
+            if (found && !binding.constant) {
+                throw new Error(`Mutable Effect factory binding ${path.node.name} in ${id}; use const`);
+            }
+            return found;
+        },
+        async imported(source, name, importer, seen) {
+            if (source === "@rc312/tss-effect-serverfn") {
+                return name === "createEffectServerFn";
+            }
+            const id = await resolve(source, importer);
+            if (!id ||
+                id.includes("/node_modules/") ||
+                id.startsWith("\0") ||
+                seen.has(`${id}:${name}`)) {
+                return false;
+            }
+            const next = new Set([...seen, `${id}:${name}`]);
+            const { program } = await load(id);
+            const stars = [];
+            for (const statement of program.get("body")) {
+                if (statement.isExportAllDeclaration()) {
+                    stars.push(statement.node.source.value);
+                }
+                if (!statement.isExportNamedDeclaration()) {
+                    continue;
+                }
+                for (const specifier of statement.get("specifiers")) {
+                    if (specifier.isExportSpecifier() &&
+                        staticName(specifier.node.exported) === name) {
+                        return statement.node.source
+                            ? trace.imported(statement.node.source.value, specifier.node.local.name, id, next)
+                            : trace.factory(specifier.get("local"), id, next);
+                    }
+                }
+                const declaration = statement.get("declaration");
+                if (declaration.isVariableDeclaration()) {
+                    const exported = declaration
+                        .get("declarations")
+                        .find((item) => item.get("id").isIdentifier({ name }));
+                    if (exported) {
+                        return trace.factory(exported.get("id"), id, next);
+                    }
+                }
+            }
+            const matches = await Promise.all(stars.map((star) => trace.imported(star, name, id, next)));
+            return matches.some(Boolean);
+        },
+        async member(path, id, seen) {
+            const object = path.get("object");
+            if (await trace.factory(object, id, seen)) {
+                if (path.node.computed ||
+                    !t.isIdentifier(path.node.property) ||
+                    !builderMethods.has(path.node.property.name)) {
+                    throw new Error(`Unsupported Effect builder composition in ${id}; use static .middleware(), .validator(), and .handler() calls`);
+                }
+                return true;
+            }
+            const binding = object.isIdentifier()
+                ? object.scope.getBinding(object.node.name)
+                : undefined;
+            if (!path.node.computed &&
+                t.isIdentifier(path.node.property) &&
+                binding?.path.isImportNamespaceSpecifier() &&
+                binding.path.parentPath.isImportDeclaration()) {
+                return trace.imported(binding.path.parentPath.node.source.value, path.node.property.name, id, seen);
+            }
+            return false;
+        },
+    };
+    return trace.factory;
+};
+/** Check helper import identity, rather than its local name, to keep lowering idempotent. */
+const isAlreadyLowered = (argument, helper) => {
+    if (!argument.isCallExpression() || !t.isIdentifier(argument.node.callee)) {
+        return false;
+    }
+    const binding = argument.scope.getBinding(argument.node.callee.name);
+    return (binding?.path.isImportSpecifier() &&
+        t.isIdentifier(binding.path.node.imported, { name: helper }) &&
+        binding.path.parentPath.isImportDeclaration() &&
+        binding.path.parentPath.node.source.value === runtimeModule);
+};
+/** Collect syntactic candidates; binding analysis must approve them before rewriting. */
+const collectBuilderCalls = (program) => {
+    const candidates = [];
+    program.traverse({
+        CallExpression(path) {
+            const { callee } = path.node;
+            if (t.isMemberExpression(callee) &&
+                ["validator", "handler"].includes(staticName(callee.property) ?? "")) {
+                candidates.push(path);
+            }
+        },
+    });
+    return candidates;
+};
+/**
+ * Wrap validated builder arguments with generated runtime helpers in place.
+ * Input paths must already be resolved to Effect builders. Fresh import names
+ * avoid lexical collisions; previously lowered arguments remain untouched.
+ *
+ * @returns Whether any AST nodes and helper imports were added or changed.
+ * @throws {Error} For computed methods or calls without exactly one expression argument.
+ */
+const lowerBuilderCalls = (calls, program, id) => {
+    const helpers = new Map();
+    for (const call of calls) {
+        const { callee } = call.node;
+        if (!t.isMemberExpression(callee) ||
+            callee.computed ||
+            !t.isIdentifier(callee.property)) {
+            throw new Error(`Computed Effect builder methods are unsupported in ${id}`);
+        }
+        const [argument] = call.get("arguments");
+        if (call.node.arguments.length !== 1 || !argument?.isExpression()) {
+            throw new Error(`Effect builders require one schema or handler expression before TanStack compilation in ${id}`);
+        }
+        const helper = callee.property.name === "validator" ? "prepareInput" : "effectHandler";
+        if (isAlreadyLowered(argument, helper)) {
+            continue;
+        }
+        let local = helpers.get(helper);
+        if (!local) {
+            local = program.scope.generateUidIdentifier(helper);
+            helpers.set(helper, local);
+        }
+        argument.replaceWith(t.callExpression(local, [argument.node]));
+    }
+    if (helpers.size === 0) {
+        return false;
+    }
+    program.unshiftContainer("body", t.importDeclaration(Array.from(helpers, ([name, local]) => t.importSpecifier(local, t.identifier(name))), t.stringLiteral(runtimeModule)));
+    return true;
+};
+/**
+ * Adapt Effect Schemas and handlers before TanStack Start compiles server functions.
+ *
+ * Install before `tanstackStart()`. The plugin recognizes static builder chains
+ * and transparent aliases/re-exports, wraps validator and handler arguments, and
+ * emits source maps. Start remains responsible for extraction, RPC identifiers,
+ * manifests, and removal of server implementations from browser bundles.
+ *
+ * @returns A Vite pre-transform plugin with build/watch module-cache invalidation.
+ *
+ * @example
+ * ```ts
+ * import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+ * import { effectServerFns } from "@rc312/tss-effect-serverfn/vite";
+ * import { defineConfig } from "vite";
+ *
+ * export default defineConfig({
+ *   plugins: [effectServerFns(), tanstackStart()],
+ * });
+ * ```
+ */
+export const effectServerFns = () => {
+    const modules = new Map();
+    const load = (id) => {
+        let module = modules.get(id);
+        if (!module) {
+            module = (async () => parseModule(await readFile(id, "utf-8"), id))();
+            modules.set(id, module);
+        }
+        return module;
+    };
+    return {
+        buildStart() {
+            modules.clear();
+        },
+        enforce: "pre",
+        name: "@rc312/tss-effect-serverfn",
+        async transform(code, id) {
+            if (!/\.[cm]?[jt]sx?(?:\?|$)/u.test(id) ||
+                !/(?:validator|handler)/u.test(code)) {
+                return;
+            }
+            const cleanId = id.split("?")[0] ?? id;
+            const { ast, program } = await parseModule(code, cleanId);
+            const candidates = collectBuilderCalls(program);
+            const isFactory = createFactoryResolver(load, async (source, importer) => {
+                const resolved = await this.resolve(source, importer, {
+                    skipSelf: true,
+                });
+                return resolved?.id;
+            });
+            // Finish binding analysis before mutating paths shared by nested builder calls.
+            const resolvedCalls = await Promise.all(candidates.map(async (candidate) => {
+                const callee = candidate.get("callee");
+                return callee.isMemberExpression() &&
+                    (await isFactory(callee.get("object"), cleanId))
+                    ? candidate
+                    : undefined;
+            }));
+            const effectCalls = resolvedCalls.filter((call) => call !== undefined);
+            if (!lowerBuilderCalls(effectCalls, program, id)) {
+                return;
+            }
+            const result = await babel.transformFromAstAsync(ast, code, {
+                babelrc: false,
+                configFile: false,
+                filename: cleanId,
+                sourceFileName: cleanId,
+                sourceMaps: true,
+            });
+            if (result?.code) {
+                return { code: result.code, map: result.map ?? null };
+            }
+        },
+        watchChange() {
+            modules.clear();
+        },
+    };
+};
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"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"}

package/docs/composition.md

@@ -0,0 +1,188 @@
+# Composing Effect handlers
+
+Handlers can return any native Effect. `Effect.gen`, `pipe`, `.pipe`, `flow`, `Effect.fn`, and do notation all use the same configured runtime, decoded input, and request Scope.
+
+Start with the [configured factory](../README.md#quick-start). Try the examples in the [basic app](https://github.com/RyanCallahan312/tss-effect-serverfn/tree/main/examples/basic): its **Composition** selector runs five equivalent server functions through real RPCs.
+
+## Choose a composition style
+
+| API | Use it for |
+| --- | --- |
+| `Effect.gen` | Sequential steps with `yield*`, local variables, and branching |
+| `pipe(value, ...steps)` / `value.pipe(...steps)` | Passing a value through transformations; both forms are equivalent for Effects |
+| `flow(...steps)` | Building a reusable function that composes steps left to right |
+| `Effect.fn("name")(body, ...steps)` | A reusable Effect-returning function with a tracing span and optional result combinators |
+| `Effect.map` | Transforming a success value with a pure function |
+| `Effect.flatMap` | Running a dependent Effect and using its result |
+| `Effect.tap` | Awaiting a dependent Effect while retaining the original success value |
+| `Effect.as` | Replacing a successful result with a constant |
+| `Effect.all` | Combining independent Effects into a tuple or record; concurrency is explicit |
+| `Effect.Do`, `bind`, `let` | Building up named results: `bind` runs Effects, `let` adds pure values |
+| `Effect.catchTag` | Recovering from one tagged business failure |
+
+`pipe` and `flow` apply ordinary functions; they do not execute the Effects those functions construct. Keep side effects inside Effect constructors such as `Effect.sync`.
+
+## Pipe a Schema, then pipe the decoded value
+
+Here is a complete endpoint module using the configured factory:
+
+```ts
+// src/greeting.functions.ts
+import { Effect, flow, pipe, Schema } from "effect";
+
+import { createEffectServerFn } from "./effect-server-fn";
+
+const Input = Schema.Struct({
+  count: Schema.FiniteFromString.pipe(Schema.check(Schema.isGreaterThan(0))),
+  name: Schema.NonEmptyString,
+});
+
+const greeting = (name: string) => Effect.succeed(`Hello, ${name}!`);
+const environment = () => Effect.succeed("server");
+
+export const getPipedGreeting = createEffectServerFn({ method: "GET" })
+  .validator(Input)
+  .handler(({ data }) =>
+    pipe(
+      greeting(data.name),
+      Effect.flatMap((message) =>
+        environment().pipe(
+          Effect.map((value) => ({
+            count: data.count,
+            environment: value,
+            message,
+          }))
+        )
+      ),
+      Effect.withSpan("Greeting.pipe")
+    )
+  );
+```
+
+The browser sends `{ count: "41", name: "Ada" }`. The handler receives a **number** for `data.count`; the positive-number check runs after decoding. A count of `"0"` or an invalid numeric string rejects with `INVALID_INPUT` before the handler runs.
+
+The runnable app uses Start's native environment helpers for `greeting` and `environment`; their returned Effects compose in exactly the same way.
+
+## Pass `flow` directly to `.handler`
+
+Add this to the same module:
+
+```ts
+const greetTogether = (data: typeof Input.Type) =>
+  Effect.all(
+    {
+      count: Effect.succeed(data.count),
+      environment: environment(),
+      message: greeting(data.name),
+    },
+    { concurrency: 2 }
+  );
+
+export const getFlowGreeting = createEffectServerFn({ method: "GET" })
+  .validator(Input)
+  .handler(
+    flow(
+      ({ data }: { data: typeof Input.Type }) => data,
+      greetTogether,
+      Effect.withSpan("Greeting.flow")
+    )
+  );
+```
+
+Annotating the first function with `typeof Input.Type` gives a separately composed function its decoded input type. The client's input is still inferred from the Schema's encoded type. Error and required-service types continue through the composition.
+
+`Effect.all` preserves the record's keys and bounds concurrency here to two. Use `flatMap`, `tap`, or `yield*` when one operation must finish before another starts, such as saving before reading updated state.
+
+## Pass `Effect.fn` directly to `.handler`
+
+The same module can also export:
+
+```ts
+export const getFnGreeting = createEffectServerFn({ method: "GET" })
+  .validator(Input)
+  .handler(
+    Effect.fn("Greeting.fn")(
+      function* greet({ data }: { data: typeof Input.Type }) {
+        return {
+          count: data.count,
+          environment: yield* environment(),
+          message: yield* greeting(data.name),
+        };
+      },
+      Effect.annotateLogs({ feature: "greeting" })
+    )
+  );
+```
+
+`Effect.fn` accepts a generator or an Effect-returning callback. Supply its result combinators as additional arguments, as above. When calling an existing Effect-returning function, pipe the returned Effect: `greetTogether(data).pipe(Effect.withSpan("Greeting.request"))`.
+
+## Build a record with do notation
+
+Another export in the same module:
+
+```ts
+export const getDoGreeting = createEffectServerFn({ method: "GET" })
+  .validator(Input)
+  .handler(({ data }) =>
+    Effect.Do.pipe(
+      Effect.bind("message", () => greeting(data.name)),
+      Effect.bind("environment", () => environment()),
+      Effect.let("count", () => data.count)
+    )
+  );
+```
+
+Each step retains earlier fields. A later `bind` or `let` callback can use those fields. Use `Effect.map` at the end if you want to project a different response shape.
+
+## Pipe service work and recover a business error
+
+The [services app](https://github.com/RyanCallahan312/tss-effect-serverfn/tree/main/examples/services) provides `Notes` through its application-owned `ManagedRuntime`. Its `notes.functions.ts` composes the service directly:
+
+```ts
+import { Effect, flow, Schema } from "effect";
+
+import { createEffectServerFn } from "./effect-server-fn";
+import { Notes } from "./notes.server";
+
+const RenameInput = Schema.Struct({
+  id: Schema.NonEmptyString,
+  title: Schema.NonEmptyString,
+});
+
+const saveNote = Effect.fn("Notes.save")((data: typeof RenameInput.Type) =>
+  Notes.pipe(
+    Effect.tap((notes) => notes.rename(data.id, data.title)),
+    Effect.flatMap((notes) => notes.read),
+    Effect.map((note) => ({ saved: true, title: note.title }))
+  )
+);
+
+export const renameNote = createEffectServerFn({ method: "POST" })
+  .validator(RenameInput)
+  .handler(
+    flow(({ data }: { data: typeof RenameInput.Type }) => data, saveNote)
+  );
+
+export const renameNoteIfPresent = createEffectServerFn({ method: "POST" })
+  .validator(RenameInput)
+  .handler(({ data }) =>
+    saveNote(data).pipe(
+      Effect.catchTag("NoteMissing", () =>
+        Effect.succeed({ saved: false, title: null })
+      )
+    )
+  );
+```
+
+`tap` awaits the mutation and retains the `Notes` service, so `flatMap` can read the saved title. A failed mutation skips that read. `catchTag` implements an explicit policy: a missing note is a successful skip. In the app, enable **Recover missing notes with catchTag** and submit ID `missing` to try it.
+
+Without recovery, `NoteMissing` reaches the configured public-error boundary. With recovery, it leaves the Effect error channel and becomes a normal successful RPC result. Defects still use the safe fallback. Endpoint Schema failures happen before this handler and cannot be caught by its pipeline.
+
+## Execution stays at the boundary
+
+- Keep the static `createEffectServerFn(...).validator(...).handler(...)` declaration so Start can extract it. Compose the Schema and handler freely inside that declaration.
+- Return the final Effect from the handler. The configured middleware runs it once; the client keeps Start's Promise API.
+- `Effect.ensuring` finalizers and request-scoped `Effect.acquireRelease` cleanup are awaited before the handler Promise settles. Piping does not change Scope ownership.
+- Compose internal Effect operations such as `saveNote` for reuse between endpoints. An exported server function is a framework/RPC boundary, not an Effect-returning domain function.
+
+The browser suite exercises every style in dev and production preview. Type tests check encoded/decoded inputs, success values, typed recovery, and required services; boundary tests check lazy construction, `tap`, `as`, `ensuring`, and scoped cleanup on success and recovery.