bend-schema 0.1.0 → 0.2.0

package/README.md

@@ -16,6 +16,12 @@ package is `bend-schema-lib`.
 bun add bend-schema
 ```
 
+From a Bend file there is no install step: import the checker from the hub.
+
+```bend
+import bend-schema-lib@0.1.0.0/core.bend as S
+```
+
 Use it with [Bun](https://bun.sh). The package ships TypeScript source, and
 Node.js refuses to run TypeScript from `node_modules`. You do not need Bend
 installed.
@@ -74,6 +80,68 @@ See **[docs/schemas.md](https://github.com/nohzafk/bend-schema/blob/main/docs/sc
 for how to write schemas:
 objects, unions, custom rules, error messages and encoding.
 
+## Optional Effect v4 adapter
+
+Convert an existing schema into an Effect codec (a schema with decoding and
+encoding). The adapter is a separate entry point; importing `bend-schema`
+does not load or require Effect.
+
+```sh
+bun add bend-schema effect@4.0.1
+```
+
+```ts
+import { s } from "bend-schema";
+import { toEffect } from "bend-schema/effect";
+import { Schema } from "effect";
+import { Rpc } from "effect/rpc";
+
+const Message = toEffect(s.object({ text: s.str(), note: s.str().optional() }));
+const decoded = Schema.decodeUnknownSync(Message)({ text: "hello", extra: true });
+// decoded is inferred as { text: string; note?: string }; extra is dropped.
+const encoded = Schema.encodeSync(Message)(decoded);
+
+const Echo = Rpc.make("Echo", { payload: Message, success: Message });
+```
+
+The API infers `T` from the input schema; no type assertion is needed:
+
+```ts
+function toEffect<T>(schema: Schema<T>): EffectSchema.decodeTo<
+  EffectSchema.declareConstructor<T, T, readonly []>, typeof EffectSchema.Unknown
+>;
+// Schema is bend-schema's type; EffectSchema is effect's Schema module.
+```
+
+The concrete return type keeps Effect's constructor input (`~type.make.in`)
+as `T`. RPC clients therefore accept the inferred object, tagged union, or
+string payload and reject incorrectly typed fields at compile time. Widening
+the adapter to `EffectSchema.Codec<T, unknown>` erases that constructor input
+to `unknown`; keep the inferred return type when passing it to `Rpc.make`.
+TypeScript checks field types, not refinement predicates or numeric ranges;
+those are still validated at runtime.
+
+Decoding returns `schema.parse(input).value`, not the untouched input.
+Encoding validates the decoded value with `parse`, then calls `schema.encode`.
+Both directions are synchronous and require no Effect services.
+
+- **Errors:** the first parse error keeps its path and reason in an Effect
+  `SchemaIssue.Pointer` and `InvalidValue`. Effect adds surrounding field paths
+  when the codec is nested. The bend-schema `proved` flag is not carried over.
+- **Semantics:** unknown keys are dropped unless the object is strict. Optional
+  fields, tagged unions, refinements and the existing size limits still apply.
+  Effect parse options do not replace bend-schema's validation rules.
+- **Representation:** the encoded type is `unknown`, as with `schema.encode`.
+  The Effect AST uses an opaque declaration, not a generated structural schema;
+  it does not expose the Bend shape for JSON Schema generation. No Bend datatype
+  parser or source generator is involved.
+- **Failures:** thrown schema configuration errors and thrown refinement
+  callbacks remain programming errors, not validation issues. Exceptions from
+  `encode` become Effect validation issues with the exception's message.
+
+Effect is an optional peer dependency (`^4.0.1`); tests pin `4.0.1`.
+Effect v3 and v4 prereleases are not supported by this adapter.
+
 ## Examples
 
 Each example is a small runnable project with tests:
@@ -155,7 +223,7 @@ The test suite proves it.
 [bend-emit](https://github.com/nohzafk/bend-emit):
 
 ```sh
-bun add -d github:nohzafk/bend-emit
+bun add -d bend-emit
 bunx bend-emit core.bend dist       # writes dist/core.mjs and dist/core.d.mts
 ```
 

package/package.json

@@ -1,18 +1,26 @@
 {
   "name": "bend-schema",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "devDependencies": {
     "@types/bun": "^1.2.0",
     "bend-emit": "0.3.1",
     "bend-falsify": "github:nohzafk/bend-falsify#a50873f",
+    "effect": "4.0.1",
     "typescript": "^7.0.2"
   },
+  "peerDependencies": {
+    "effect": "^4.0.1"
+  },
+  "peerDependenciesMeta": {
+    "effect": { "optional": true }
+  },
   "exports": {
     ".": "./src/index.ts",
     "./codec": "./src/codec.ts",
-    "./gen": "./src/gen.ts"
+    "./gen": "./src/gen.ts",
+    "./effect": "./src/effect.ts"
   },
   "bin": {
     "bend-schema": "./src/gen-cli.ts"
@@ -28,6 +36,7 @@
   "files": [
     "src/index.ts",
     "src/codec.ts",
+    "src/effect.ts",
     "src/gen.ts",
     "src/gen-cli.ts",
     "core/core.bend",

package/src/effect.ts

@@ -0,0 +1,31 @@
+// Optional Effect v4 bridge. The root entry does not import Effect.
+import { Effect, Schema as S, SchemaGetter, SchemaIssue } from "effect";
+import type { Schema } from "./index";
+
+/** Decode with bend-schema's parse (including transformations), and encode
+ * with its encode. The encoded representation is unknown; T is inferred.
+ * Keep the concrete schema type: Codec<T, unknown> erases RPC's make input. */
+export function toEffect<T>(schema: Schema<T>): S.decodeTo<
+  S.declareConstructor<T, T, readonly []>, typeof S.Unknown
+> {
+  const value = S.declareConstructor<T>()([], () => (input) => {
+    const result = schema.parse(input);
+    return result.ok
+      ? Effect.succeed(result.value)
+      : Effect.fail(new SchemaIssue.Pointer(
+          result.error.path,
+          new SchemaIssue.InvalidValue({ message: result.error.message }),
+        ));
+  });
+
+  return S.Unknown.pipe(S.decodeTo(value, {
+    // The declaration validates this unknown value and returns parse's T.
+    decode: SchemaGetter.transform((input: unknown) => input as T),
+    encode: SchemaGetter.transformEffect((input: T) => Effect.try({
+      try: () => schema.encode(input),
+      catch: (error) => new SchemaIssue.InvalidValue({
+        message: error instanceof Error ? error.message : String(error),
+      }),
+    })),
+  }));
+}