@shivaedev/errors 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.3.0 - 2026-10-31
+
+### Added
+
+- `rpcBoundaryHandlers(group, boundary, handlers)` applies one boundary and unexpected mapping to a native RPC handler map, including Effect and Stream handlers and native RPC wrappers.
+- Contract changes streams declare `WebSocketRequired` so HTTP clients can decode the protocol error.
+
+### Fixed
+
+- Hosted `$changes` subscriptions over HTTP fail with a message saying they need the WebSocket protocol.
+
 ## 0.2.0 - 2026-10-31
 
 ### Added

package/README.md

@@ -70,6 +70,20 @@ export const Handlers = Api.toLayer({
 
 `storageSave` is the application's Effect. `unexpected` constructs a member of the declared schema from the public message. The default message is `Internal server error`; `message` supplies application text, with credential-shaped strings redacted. Before masking an unexpected failure, the boundary reports its diagnostic-redacted cause through Effect's registered `ErrorReporter`s at `Error` severity. Request tracing logs that masked failure at ERROR with its redacted stack, while declared rejections stay at INFO. The original Effect cause is kept on the server rejection's non-enumerable `cause`, so a server span can trace it. Keep `cause` out of the wire schema, as the taxonomy classes do. `ServiceUnavailable` describes a declared availability failure without implying a session-provider outage.
 
+Apply the same boundary to an entire handler registration with `rpcBoundaryHandlers(group, boundary, handlers)`:
+
+```ts
+import { rpcBoundaryHandlers } from "@shivaedev/errors/rpcBoundaryHandlers.ts";
+
+export const Handlers = Api.toLayer(
+	rpcBoundaryHandlers(Api, expose, {
+		Save: () => storageSave,
+	}),
+);
+```
+
+The group supplies payload and result types. Each RPC must declare the boundary's rejection schema. Effect and Stream handlers share the mapping, including failures after a stream has delivered values; native `Rpc.Wrapper` options remain available. Handler service requirements pass through to the native handler Layer. Use this map inside an Effect passed to `toLayer` when handler construction needs services. Queue-backed streams and Deferred results use native handlers with an explicit boundary at their producer instead.
+
 ### Masking secrets in failures
 
 `sensitive.ts` decides which names are secret. `isSensitiveKey(key)` matches credential-shaped names whatever their casing or separator, such as `sessionId`, `bearerToken`, `access_key_id` or `cardNumber`, and database diagnostic keys `db.user`, `db.user.name` and `db.connection_string`. A `SensitiveKey` is any `(key: string) => boolean`, so an application can widen the policy with its own names. `redactText(text, sensitive, maxLength?, key?)` masks credential-shaped text and `key=value` assignments inside a string, URL user information, query values and fragments, and cuts it at 2,048 characters by default; passing `Infinity` keeps complete public text. The optional `key` supplies context for standalone URL components such as `url.query`. `redactUrl(value, key?)` from `sensitive.ts` applies just the URL rules, including nested JSON strings. Masked values become `REDACTED`, the string `<redacted>`.

package/dist/rpcBoundaryHandlers.d.ts

@@ -0,0 +1,14 @@
+import { Effect, Stream } from "effect";
+import { Rpc, type RpcGroup, type RpcSchema } from "effect/rpc";
+type Handlers<R extends Rpc.Any> = {
+    readonly [TRpc in R as TRpc["_tag"]]: (...args: Parameters<Rpc.ToHandlerFn<TRpc>>) => Rpc.WrapperOr<TRpc extends {
+        readonly successSchema: RpcSchema.Stream<infer TSuccess, infer _E>;
+    } ? Stream.Stream<TSuccess["Type"], unknown, unknown> : Effect.Effect<Rpc.Success<TRpc>, unknown, unknown>>;
+};
+type Bounded<T, E> = T extends Effect.Effect<infer A, infer _E, infer R> ? Effect.Effect<A, E, R> : T extends Stream.Stream<infer A, infer _E, infer R> ? Stream.Stream<A, E, R> : T extends Rpc.Wrapper<infer TValue> ? Rpc.Wrapper<Bounded<TValue, E>> : never;
+type BoundedHandlers<THandlers, E> = {
+    readonly [TKey in keyof THandlers]: THandlers[TKey] extends (...args: infer TArgs) => infer TValue ? (...args: TArgs) => Bounded<TValue, E> : never;
+};
+export declare function rpcBoundaryHandlers<TRpcs extends Rpc.Any, E, THandlers extends Handlers<TRpcs>>(group: RpcGroup.RpcGroup<TRpcs>, boundary: <A, TError, R>(effect: Effect.Effect<A, TError, R>) => Effect.Effect<A, E, R>, handlers: THandlers): BoundedHandlers<THandlers, E>;
+export {};
+//# sourceMappingURL=rpcBoundaryHandlers.d.ts.map

package/dist/rpcBoundaryHandlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpcBoundaryHandlers.d.ts","sourceRoot":"","sources":["../src/rpcBoundaryHandlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,GAAG,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAGhE,KAAK,QAAQ,CAAC,CAAC,SAAS,GAAG,CAAC,GAAG,IAAI;IAClC,QAAQ,EAAE,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CACrC,GAAG,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,KACtC,GAAG,CAAC,SAAS,CACjB,IAAI,SAAS;QAAE,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAC,MAAM,CAAC,MAAM,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAA;KAAE,GAChF,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,GACjD,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CACrD;CACD,CAAC;AAEF,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,IAChB,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,GAChD,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACtB,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,GAClD,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACtB,CAAC,SAAS,GAAG,CAAC,OAAO,CAAC,MAAM,MAAM,CAAC,GAClC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAC/B,KAAK,CAAC;AAEZ,KAAK,eAAe,CAAC,SAAS,EAAE,CAAC,IAAI;IACpC,QAAQ,EAAE,IAAI,IAAI,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,KAAK,KAAK,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,KAAK;CACnJ,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,SAAS,SAAS,QAAQ,CAAC,KAAK,CAAC,EAC9F,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAC/B,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACvF,QAAQ,EAAE,SAAS,GACjB,eAAe,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC"}

package/dist/rpcBoundaryHandlers.js

@@ -0,0 +1,9 @@
+import { Effect, Stream } from "effect";
+import { Rpc } from "effect/rpc";
+export function rpcBoundaryHandlers(_group, boundary, handlers) {
+    return Object.fromEntries(Object.entries(handlers).map(([tag, handler]) => [
+        tag,
+        (...args) => Rpc.wrapMap(handler(...args), (result) => Effect.isEffect(result) ? boundary(result) : Stream.catchCause(result, (cause) => Stream.fromEffect(boundary(Effect.failCause(cause))))),
+    ]));
+}
+//# sourceMappingURL=rpcBoundaryHandlers.js.map

package/dist/rpcBoundaryHandlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpcBoundaryHandlers.js","sourceRoot":"","sources":["../src/rpcBoundaryHandlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,GAAG,EAAiC,MAAM,YAAY,CAAC;AA+BhE,MAAM,UAAU,mBAAmB,CAClC,MAAkC,EAClC,QAA6F,EAC7F,QAA+E;IAE/E,OAAO,MAAM,CAAC,WAAW,CACxB,MAAM,CAAC,OAAO,CAA8C,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;QAC7F,GAAG;QACH,CAAC,GAAG,IAAa,EAAE,EAAE,CACpB,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CACxC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CACvI;KACF,CAAC,CACF,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/errors",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Typed expected failures and secret-safe failure reporting for Effect applications",
   "keywords": [
     "effect"
@@ -45,7 +45,7 @@
     "README.md"
   ],
   "devDependencies": {
-    "@shivaedev/quality": "0.49.0",
+    "@shivaedev/quality": "0.50.0",
     "@shivaedev/test": "0.12.0",
     "@types/node": "24.19.2",
     "effect": "4.0.6",

package/src/rpcBoundaryHandlers.ts

@@ -0,0 +1,47 @@
+import { Effect, Stream } from "effect";
+import { Rpc, type RpcGroup, type RpcSchema } from "effect/rpc";
+
+type Result = Effect.Effect<unknown, unknown, unknown> | Stream.Stream<unknown, unknown, unknown>;
+type Handlers<R extends Rpc.Any> = {
+	readonly [TRpc in R as TRpc["_tag"]]: (
+		...args: Parameters<Rpc.ToHandlerFn<TRpc>>
+	) => Rpc.WrapperOr<
+		TRpc extends { readonly successSchema: RpcSchema.Stream<infer TSuccess, infer _E> }
+			? Stream.Stream<TSuccess["Type"], unknown, unknown>
+			: Effect.Effect<Rpc.Success<TRpc>, unknown, unknown>
+	>;
+};
+
+type Bounded<T, E> =
+	T extends Effect.Effect<infer A, infer _E, infer R>
+		? Effect.Effect<A, E, R>
+		: T extends Stream.Stream<infer A, infer _E, infer R>
+			? Stream.Stream<A, E, R>
+			: T extends Rpc.Wrapper<infer TValue>
+				? Rpc.Wrapper<Bounded<TValue, E>>
+				: never;
+
+type BoundedHandlers<THandlers, E> = {
+	readonly [TKey in keyof THandlers]: THandlers[TKey] extends (...args: infer TArgs) => infer TValue ? (...args: TArgs) => Bounded<TValue, E> : never;
+};
+
+export function rpcBoundaryHandlers<TRpcs extends Rpc.Any, E, THandlers extends Handlers<TRpcs>>(
+	group: RpcGroup.RpcGroup<TRpcs>,
+	boundary: <A, TError, R>(effect: Effect.Effect<A, TError, R>) => Effect.Effect<A, E, R>,
+	handlers: THandlers,
+): BoundedHandlers<THandlers, E>;
+export function rpcBoundaryHandlers(
+	_group: RpcGroup.RpcGroup<Rpc.Any>,
+	boundary: <A, TError, R>(effect: Effect.Effect<A, TError, R>) => Effect.Effect<A, unknown, R>,
+	handlers: Readonly<Record<string, (...args: never[]) => Rpc.WrapperOr<Result>>>,
+) {
+	return Object.fromEntries(
+		Object.entries<(...args: never[]) => Rpc.WrapperOr<Result>>(handlers).map(([tag, handler]) => [
+			tag,
+			(...args: never[]) =>
+				Rpc.wrapMap(handler(...args), (result) =>
+					Effect.isEffect(result) ? boundary(result) : Stream.catchCause(result, (cause) => Stream.fromEffect(boundary(Effect.failCause(cause)))),
+				),
+		]),
+	);
+}