effective-rsc 0.1.0

package/docs/04-api-reference/02-page/index.md

@@ -0,0 +1,12 @@
+## Page
+
+- `ERSC.Page.make({ render })` creates a static route leaf.
+- `ERSC.Page.make({ params, render })` creates a parameterized route leaf.
+
+`render` returns an Effect whose requirements fit the ERSC service union. For parameterized Pages,
+the Schema's encoded keys must exactly match the path parameters and accept strings. Compose the
+Page with `Routes.page`.
+
+Pages produce React output. Only an unmatched route receives a native `404`. The mapping from a
+matched Page's parameter rejection to an expected HTTP outcome remains a
+[known limitation](https://github.com/nikhilsnayak/effective-rsc/blob/main/docs/ARCHITECTURE.md#known-limitations).

package/docs/04-api-reference/03-layout/index.md

@@ -0,0 +1,4 @@
+## Layout
+
+`ERSC.Layout.make({ render })` creates an Effectful wrapper with one `children` outlet. It may require
+ERSC application services. The root Layout owns the HTML document; nested Layouts own route scopes.

package/docs/04-api-reference/04-loading/index.md

@@ -0,0 +1,4 @@
+## Loading
+
+`ERSC.Loading.make({ render })` creates a Routes-scope fallback. `render` is synchronous and cannot
+require services. A scope accepts at most one Loading value.

package/docs/04-api-reference/05-component/10_component.tsx

@@ -0,0 +1,18 @@
+/**
+ * @title An Effectful Server Component
+ *
+ * Component runs its render Effect in the current ERSC render scope.
+ */
+import { Effect } from 'effect';
+import { Application } from 'effective-rsc';
+
+const ERSC = Application.ersc();
+
+export const ExchangeRate = ERSC.Component.make({
+  render: ({ euros }: { readonly euros: number }) =>
+    Effect.succeed(
+      <p>
+        €{euros} is approximately ${(euros * 1.17).toFixed(2)}
+      </p>,
+    ),
+});

package/docs/04-api-reference/05-component/index.md

@@ -0,0 +1,10 @@
+## Component
+
+`ERSC.Component.make({ render })` creates a non-route Effectful Server Component. Props are inferred
+from `render`; requirements must fit the ERSC service union. Use it only in the RSC graph.
+
+<!-- source-navigation -->
+
+### Example
+
+- [Define an Effectful Server Component](./10_component.tsx)

package/docs/04-api-reference/06-middleware/index.md

@@ -0,0 +1,33 @@
+## Middleware
+
+`ERSC.Middleware.make(handler)` adapts an Effect HTTP middleware to the current ERSC identity.
+`ERSC.withMiddleware(middleware)` returns a derived authoring view of that same identity.
+
+Use `ERSC.Middleware.make<{ provides: CurrentUser }>(handler)` when the handler provides a service to
+the downstream Effect. Multiple services use a union. The derived view adds those services to the
+requirements available to Page, Layout, Component, ServerFn, Routes, Middleware, and further derived
+views.
+
+Routes and ServerFn activate retained middleware. Page, Layout, and Component consume its services
+only while React renders them inside an active scope. Rendering one outside its required scope is a
+programmer error and throws `TypeError`.
+
+Chain `withMiddleware` in request order. Ancestors run before descendants; response transformations
+unwind in reverse. A middleware repeated in one resolved mounted route chain is rejected. Shared
+middleware across mounted scopes runs once.
+
+## Reach
+
+| Request                          | Route scope                          | Server Function scope | Native global middleware |
+| -------------------------------- | ------------------------------------ | --------------------- | ------------------------ |
+| Page GET/HEAD                    | Matched chain                        | No                    | Yes                      |
+| Hydrated Server Function POST    | Remaining route chain around refresh | Server Function chain | Yes                      |
+| Progressive Server Function POST | No route refresh in the POST         | Server Function chain | Yes                      |
+| Userland HTTP, assets, unmatched | No                                   | No                    | Yes                      |
+
+During a hydrated Server Function request, middleware already active for the Server Function is not
+executed again for the refreshed route, even if it appears at another position in that route chain.
+Remaining route middleware wraps refreshed rendering.
+
+Native global Effect HTTP middleware is separate. Register it through the application Layer for
+server-wide policy.

package/docs/04-api-reference/07-routes/index.md

@@ -0,0 +1,20 @@
+## Routes
+
+`ERSC.Routes.make({ layout?, loading? })` creates an immutable route scope.
+
+- `routes.page(path, page)` adds a Page at an absolute Effect HTTP pattern. Parameter Schema keys
+  must exactly match path parameters.
+- `routes.mount(prefix, childRoutes)` mounts a non-empty graph of the same ERSC identity below an
+  absolute, parameter-free prefix.
+- Mounted scopes retain their Layout, Loading, and middleware ancestry.
+
+Both operations return new Routes values. Conflicting matcher shapes and `/_ersc/assets` are
+rejected. Root Routes require a Layout and at least one Page.
+
+Routes created from a derived authoring view activate its middleware.
+
+<!-- source-navigation -->
+
+### Related
+
+- [Middleware](../06-middleware/index.md)

package/docs/04-api-reference/08-server-fn/index.md

@@ -0,0 +1,43 @@
+## ServerFn
+
+`ERSC.ServerFn.make({ input, handler })` creates a native React Server Function reference. `input`
+decodes the invocation payload and infers the handler parameter; do not annotate it. The handler
+returns an Effect whose requirements fit the ERSC service universe. The client reference accepts the
+Schema's encoded type and resolves `Promise<Output>`; the handler receives its decoded type.
+
+```ts
+const followAuthor = ERSC.ServerFn.make({
+  input: Schema.Struct({ authorId: Schema.NonEmptyString }),
+  handler: ({ authorId }) => Effect.succeed({ authorId, following: true }),
+});
+```
+
+Schema transformations may use a different encoded type. To pass a Server Function directly to
+`form.action`, decode `FormData` and return `void`:
+
+```tsx
+const followAuthorForm = ERSC.ServerFn.make({
+  input: Schema.fromFormData(Schema.Struct({ authorId: Schema.NonEmptyString })),
+  handler: ({ authorId }) => Effect.logInfo('Followed author', { authorId }),
+});
+
+<form action={followAuthorForm}>
+  <input name='authorId' />
+  <button type='submit'>Follow</button>
+</form>;
+```
+
+A ServerFn created from a derived view activates its middleware for the POST. The Middleware
+reference defines refresh reach and ordering.
+
+Direct server invocation throws. Encode expected failure in a discriminated output union; unexpected
+failures reject the Promise. Browser requests require an Origin matching the application host and
+may contain at most 10 MiB. See the
+[known limitations](https://github.com/nikhilsnayak/effective-rsc/blob/main/docs/ARCHITECTURE.md#known-limitations)
+for the typed failure channel and progressive bound arguments.
+
+<!-- source-navigation -->
+
+### Related
+
+- [Middleware](../06-middleware/index.md)

package/docs/04-api-reference/index.md

@@ -0,0 +1,17 @@
+## API reference
+
+Under the `react-server` condition, the package root exports `Application`.
+`Application.ersc<Services>()` returns `Component`, `Layout`, `Loading`, `Page`, `Middleware`,
+`Routes`, `ServerFn`, `withMiddleware`, and `make`. Values from different ERSC identities cannot
+be composed.
+
+<!-- source-navigation -->
+
+- [Application](./01-application/index.md)
+- [Page](./02-page/index.md)
+- [Layout](./03-layout/index.md)
+- [Loading](./04-loading/index.md)
+- [Component](./05-component/index.md)
+- [Middleware](./06-middleware/index.md)
+- [Routes](./07-routes/index.md)
+- [ServerFn](./08-server-fn/index.md)

package/docs/environment.d.ts

@@ -0,0 +1 @@
+declare module '*.css' {}

package/docs/index.md

@@ -0,0 +1,15 @@
+# effective-rsc documentation
+
+Use the React and Effect documentation for their underlying concepts. ERSC conventions:
+
+- Only `src/application.tsx` has framework filename semantics.
+- Create application values from one ERSC identity and its derived middleware views.
+- Provide application services and export the result at `ERSC.make`.
+- Import the package root only from the RSC graph.
+
+<!-- source-navigation -->
+
+- [Getting started](./01-getting-started/index.md)
+- [Guides](./02-guides/index.md)
+- [Advanced](./03-advanced/index.md)
+- [API reference](./04-api-reference/index.md)

package/logo-dark.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" role="img" aria-label="effective-rsc">
+  <rect x="16" y="27.5" width="26" height="9" rx="4.5" fill="#A18CFF" />
+  <rect x="16" y="11" width="9" height="42" rx="4.5" fill="#F7F5F1" />
+  <rect x="16" y="11" width="32" height="9" rx="4.5" fill="#F7F5F1" />
+  <rect x="16" y="44" width="32" height="9" rx="4.5" fill="#F7F5F1" />
+</svg>

package/logo.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" role="img" aria-label="effective-rsc">
+  <rect x="16" y="27.5" width="26" height="9" rx="4.5" fill="#5B3FF0" />
+  <rect x="16" y="11" width="9" height="42" rx="4.5" fill="#14131A" />
+  <rect x="16" y="11" width="32" height="9" rx="4.5" fill="#14131A" />
+  <rect x="16" y="44" width="32" height="9" rx="4.5" fill="#14131A" />
+</svg>

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "effective-rsc",
+  "version": "0.1.0",
+  "description": "An experimental, Effect-native React Server Components framework for Bun.",
+  "keywords": [
+    "bun",
+    "effect",
+    "react-server-components"
+  ],
+  "homepage": "https://github.com/nikhilsnayak/effective-rsc#readme",
+  "bugs": {
+    "url": "https://github.com/nikhilsnayak/effective-rsc/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nikhilsnayak/effective-rsc.git",
+    "directory": "packages/effective-rsc"
+  },
+  "bin": {
+    "ersc": "./bin/ersc.js"
+  },
+  "files": [
+    "bin/ersc.js",
+    "dist",
+    "docs",
+    "LICENSE",
+    "LLMS.md",
+    "logo-dark.svg",
+    "logo.svg",
+    "README.md"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-server": "./dist/index.js",
+      "default": "./dist/unsupported.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "docs:check": "bun ../../scripts/generate-docs.ts --check",
+    "prepack": "bun run build && bun run docs:check",
+    "test": "bun run --bun vitest run",
+    "test:types": "tsc --noEmit -p tests/types/tsconfig.json",
+    "test:watch": "bun run --bun vitest"
+  },
+  "dependencies": {
+    "@rspack/core": "2.2.2",
+    "@rspack/plugin-react-refresh": "2.0.2",
+    "@tailwindcss/webpack": "4.3.3",
+    "react-refresh": "0.18.0"
+  },
+  "devDependencies": {
+    "@base-ui/react": "^1.8.0",
+    "@effect/platform-browser": "4.0.0-rc.112",
+    "@effect/platform-bun": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@rsbuild/plugin-react": "2.1.0",
+    "@rslib/core": "1.0.0",
+    "@types/bun": "^1.4.1",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.7",
+    "effect": "4.0.0-rc.112",
+    "react": "19.3.0-canary-8425b691-20260904",
+    "react-dom": "19.3.0-canary-8425b691-20260904",
+    "react-server-dom-rspack": "0.1.0",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "peerDependencies": {
+    "@effect/platform-browser": "4.0.0-rc.112",
+    "@effect/platform-bun": "4.0.0-rc.112",
+    "effect": "4.0.0-rc.112",
+    "react": "19.3.0-canary-8425b691-20260904",
+    "react-dom": "19.3.0-canary-8425b691-20260904",
+    "react-server-dom-rspack": "0.1.0"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  }
+}