feat: allow passing a type to .chain

Author: jviide

.changeset/dark-suits-stand.md

@@ -0,0 +1,22 @@
+---
+"@badrap/valita": patch
+---
+
+Allow passing a type to .chain()
+
+The `.chain()` method of types now accepts other types as-is:
+
+```ts
+v.string()                // Accept strings as input,
+  .map((s) => Number(s))  // then parse the strings to numbers,
+  .chain(v.literal(1));   // and ensure that the parsed number is 1.
+```
+
+The parsing mode is propagated to the chained type:
+
+```ts
+const example = v.unknown().parse(v.object({ a: v.number() }));
+
+example.parse({ a: 1, b: 2 }, { mode: "strip" });
+// { a: 1 }
+```

README.md

@@ -651,6 +651,23 @@ CompanyString.parse('{ "name": "Acme Inc.", "ceo": "Wiley E. Coyote" }', {
 // { name: 'Acme Inc.' }
 ```
 
+Turns out that composing parsers like this is relatively common. Therefore you can pass types to `.chain(...)`. The following is equal to the above definition of `CompanyString`:
+
+```ts
+const Company = v.object({ name: v.string() });
+
+// We now have a handy common helper for parsing JSON strings!
+const JsonString = v.string().chain((json) => {
+  try {
+    return v.ok(JSON.parse(json));
+  } catch {
+    return v.err("not valid JSON");
+  }
+});
+
+const CompanyString = JsonString.chain(Company);
+```
+
 ### Inferring Output Types
 
 The exact output type of a validator can be _inferred_ from a type validator's using with `v.Infer<typeof ...>`:

eslint.config.mjs

@@ -35,6 +35,7 @@ export default [
       "@typescript-eslint/consistent-indexed-object-style": "off",
       "@typescript-eslint/prefer-return-this-type": "off",
       "@typescript-eslint/unbound-method": "off",
+      "@typescript-eslint/unified-signatures": "off",
       "@typescript-eslint/restrict-template-expressions": [
         "error",
         {

src/index.ts

@@ -644,8 +644,8 @@ abstract class AbstractType<Output = unknown> {
     error?: CustomError,
   ): Type<T> {
     const err: IssueLeaf = { ok: false, code: "custom_error", error };
-    return new TransformType(this, (v, options) =>
-      func(v as Output, options) ? undefined : err,
+    return new TransformType(this, (v, flags) =>
+      func(v as Output, flagsToOptions(flags)) ? undefined : err,
     );
   }
 
@@ -673,9 +673,9 @@ abstract class AbstractType<Output = unknown> {
   ): Type<T>;
   map<T>(func: (v: Output, options: ParseOptions) => T): Type<T>;
   map<T>(func: (v: Output, options: ParseOptions) => T): Type<T> {
-    return new TransformType(this, (v, options) => ({
+    return new TransformType(this, (v, flags) => ({
       ok: true,
-      value: func(v as Output, options),
+      value: func(v as Output, flagsToOptions(flags)),
     }));
   }
 
@@ -712,13 +712,21 @@ abstract class AbstractType<Output = unknown> {
   chain<T>(
     func: (v: Output, options: ParseOptions) => ValitaResult<T>,
   ): Type<T>;
-  chain<T>(
-    func: (v: Output, options: ParseOptions) => ValitaResult<T>,
-  ): Type<T> {
-    return new TransformType(this, (v, options) => {
-      const r = func(v as Output, options);
-      return r.ok ? r : (r as unknown as { _issueTree: IssueTree })._issueTree;
-    });
+  chain<T>(type: Type<T>): Type<T>;
+  chain(
+    input: Type | ((v: Output, options: ParseOptions) => ValitaResult<unknown>),
+  ): Type {
+    if (typeof input === "function") {
+      return new TransformType(this, (v, flags) => {
+        const r = input(v as Output, flagsToOptions(flags));
+        return r.ok
+          ? r
+          : (r as unknown as { _issueTree: IssueTree })._issueTree;
+      });
+    }
+    return new TransformType(this, (v, flags) =>
+      callMatcher(input[MATCHER_SYMBOL], v, flags),
+    );
   }
 }
 
@@ -1781,12 +1789,20 @@ class UnionType<T extends Type[] = Type[]> extends Type<Infer<T[number]>> {
   }
 }
 
-type TransformFunc = (value: unknown, options: ParseOptions) => MatcherResult;
+type TransformFunc = (value: unknown, flags: number) => MatcherResult;
 
 const STRICT = Object.freeze({ mode: "strict" }) as ParseOptions;
 const STRIP = Object.freeze({ mode: "strip" }) as ParseOptions;
 const PASSTHROUGH = Object.freeze({ mode: "passthrough" }) as ParseOptions;
 
+function flagsToOptions(flags: number): ParseOptions {
+  return flags & FLAG_FORBID_EXTRA_KEYS
+    ? STRICT
+    : flags & FLAG_STRIP_EXTRA_KEYS
+      ? STRIP
+      : PASSTHROUGH;
+}
+
 class TransformType<Output> extends Type<Output> {
   readonly name = "transform";
 
@@ -1835,14 +1851,8 @@ class TransformType<Output> extends Type<Output> {
           current = v;
         }
 
-        const options =
-          flags & FLAG_FORBID_EXTRA_KEYS
-            ? STRICT
-            : flags & FLAG_STRIP_EXTRA_KEYS
-              ? STRIP
-              : PASSTHROUGH;
         for (let i = 0; i < chain.length; i++) {
-          const r = chain[i](current, options);
+          const r = chain[i](current, flags);
           if (r !== undefined) {
             if (!r.ok) {
               return r;

tests/Type.test.ts

@@ -232,15 +232,25 @@ describe("Type", () => {
     });
   });
   describe("chain", () => {
-    it("changes the output type to the function's return type", () => {
+    it("changes the output type to the given function's return type", () => {
       const _t = v.number().chain((n) => v.ok(String(n)));
       expectTypeOf<v.Infer<typeof _t>>().toEqualTypeOf<string>();
     });
-    it("infers literals when possible", () => {
+
+    it("changes the output type to given type's output type", () => {
+      const _t = v
+        .number()
+        .map((n) => String(n))
+        .chain(v.literal("1"));
+      expectTypeOf<v.Infer<typeof _t>>().toEqualTypeOf<"1">();
+    });
+
+    it("infers literals as the given function's output type when possible", () => {
       const _t = v.number().chain(() => ({ ok: true, value: "test" }));
       expectTypeOf<v.Infer<typeof _t>>().toEqualTypeOf<"test">();
     });
-    it("passes in the parsed value", () => {
+
+    it("passes in the parsed value to the given function", () => {
       let value: unknown;
       const t = v.number().chain((n) => {
         value = n;
@@ -249,7 +259,20 @@ describe("Type", () => {
       t.parse(1000);
       expect(value).to.equal(1000);
     });
-    it("passes in normalized parse options", () => {
+
+    it("passes in the parsed value to the given type", () => {
+      let value: unknown;
+      const t = v.number().chain(
+        v.unknown().chain((n) => {
+          value = n;
+          return v.ok("test");
+        }),
+      );
+      t.parse(1000);
+      expect(value).to.equal(1000);
+    });
+
+    it("passes in normalized parse options to the given function", () => {
       let options: unknown;
       const t = v.number().chain((n, opts) => {
         options = opts;
@@ -264,11 +287,36 @@ describe("Type", () => {
       t.parse(1, { mode: "strict" });
       expect(options).to.deep.equal({ mode: "strict" });
     });
-    it("passes on the success value", () => {
+
+    it("propagates parse options to the given type", () => {
+      let options: unknown;
+      const t = v.number().chain(
+        v.unknown().chain((n, opts) => {
+          options = opts;
+          return v.ok("test");
+        }),
+      );
+      t.parse(1, { mode: "strict" });
+      expect(options).to.deep.equal({ mode: "strict" });
+      t.parse(1, { mode: "strip" });
+      expect(options).to.deep.equal({ mode: "strip" });
+      t.parse(1, { mode: "passthrough" });
+      expect(options).to.deep.equal({ mode: "passthrough" });
+      t.parse(1, { mode: "strict" });
+      expect(options).to.deep.equal({ mode: "strict" });
+    });
+
+    it("passes on the success value from the given function", () => {
       const t = v.number().chain(() => v.ok("test"));
       expect(t.parse(1)).to.equal("test");
     });
-    it("fails on error result", () => {
+
+    it("passes on the success value from the given type", () => {
+      const t = v.number().chain(v.unknown().map(() => "test"));
+      expect(t.parse(1)).to.equal("test");
+    });
+
+    it("fails on error result from the given function", () => {
       const t = v.number().chain(() => v.err());
       expect(() => t.parse(1))
         .to.throw(v.ValitaError)
@@ -277,7 +325,19 @@ describe("Type", () => {
           code: "custom_error",
         });
     });
-    it("allows passing in a custom error message", () => {
+
+    it("fails on error result from the given type", () => {
+      const t = v.number().chain(v.string());
+      expect(() => t.parse(1))
+        .to.throw(v.ValitaError)
+        .with.nested.property("issues[0]")
+        .that.deep.includes({
+          code: "invalid_type",
+          expected: ["string"],
+        });
+    });
+
+    it("allows passing in a custom error message from the given function", () => {
       const t = v.number().chain(() => v.err("test"));
       expect(() => t.parse(1))
         .to.throw(v.ValitaError)
@@ -287,7 +347,8 @@ describe("Type", () => {
           error: "test",
         });
     });
-    it("allows passing in a custom error message in an object", () => {
+
+    it("allows passing in a custom error message in an object from the given function", () => {
       const t = v.number().chain(() => v.err({ message: "test" }));
       expect(() => t.parse(1))
         .to.throw(v.ValitaError)
@@ -297,7 +358,8 @@ describe("Type", () => {
           error: { message: "test" },
         });
     });
-    it("allows passing in an error path", () => {
+
+    it("allows passing in an error path from the given function", () => {
       const t = v.number().chain(() => v.err({ path: ["test"] }));
       expect(() => t.parse(1))
         .to.throw(v.ValitaError)
@@ -307,13 +369,16 @@ describe("Type", () => {
           path: ["test"],
         });
     });
+
     it("runs multiple chains in order", () => {
       const t = v
         .string()
         .chain((s) => v.ok(s + "b"))
-        .chain((s) => v.ok(s + "c"));
-      expect(t.parse("a")).to.equal("abc");
+        .chain((s) => v.ok(s + "c"))
+        .chain(v.string().map((s) => s + "d"));
+      expect(t.parse("a")).to.equal("abcd");
     });
+
     it("works together with .try()", () => {
       const s = v.string();
       const t = v.unknown().chain((x) => s.try(x));
@@ -322,6 +387,7 @@ describe("Type", () => {
       expect(() => t.parse(1)).to.throw(v.ValitaError);
     });
   });
+
   describe("optional", () => {
     it("returns an Optional", () => {
       expectTypeOf(v.unknown().optional()).toExtend<v.Optional>();