Choosing

Luq or zod?

Where does your type come from?

A validator whose schema is the source of truth assumes you are the one who decides the shape. Often you are not — it arrives already decided:

• codeopenapi-typescript, generated from an API spec you do not own
• databasePrisma or Drizzle, generated from the schema of record
• swap_horizprotobuf or GraphQL codegen, shared with services in other languages
• smart_toyA generator or a model writing the validation for you

In all four the shape is upstream and not yours to move, so a schema-first validator asks you to write it a second time and keep the copy in step by hand. The compiler can be made to check the copy against the original — satisfies z.ZodType<Order> does exactly that — but the copy still has to be authored, updated, and remembered.

Where schema-first is the better fit

A codebase should have one source of truth for a shape. If that source is a schema you author, schema-first is the coherent arrangement, and Luq cannot give you that.

Luq's case is the one where the artefact already exists elsewhere and is not yours to move. Then the schema-first arrangement asks you to author a second source of truth, and the question stops being which library is nicer and becomes which copy is right.

One thing that is easy to miss: Luq contains both directions. fromJsonSchema(document) is schema-first, and the document decides. What Luq declines to do is make you hand-write the second copy.

It patches onto the types you already have

This is what being type-first buys you in an existing codebase, and it is the main practical reason to reach for Luq: your type definitions do not change. Not re-authored as a schema, not replaced by an inferred one, not moved. .for<Order>() takes the Order that is already there, and every rule is declared against it.

So Luq asks you to describe the rules, not the shape.

Which is what makes adoption a patch rather than a migration. Nothing here is global — no registry, no installation step, no shared configuration object; a validator is a value in a module:

• filter_altDeclare only the fields you care about. A path you did not declare is not validated, not required and not read, so a partly-covered type is a normal state rather than a half-finished one.
• touch_apppick(path) returns a validator for one field, which is what a form needs on blur. pickAll(paths) does a named subset.
• swap_horizStandard Schema means adding Luq to one route does not commit the next one, and does not remove zod from the ones it is already in.
• ruleAnd when you want the opposite, .strict() asks for it: the builder stops compiling until every leaf path of the type is declared, and the error names the ones you missed. Partial is the default, not the only option.

The direction is the whole difference

Nearly every widely used validator in TypeScript infers the type out of a schema you write. Luq runs the other way.

Luq is not the first to run that way. fluentvalidation-ts has declared rules against an existing type with a fluent chain since 2019. The direction is older than this library and the credit is not ours.

import { z } from "zod";

// The schema is the source. The type comes out of it.
const User = z.object({
  name: z.string().min(3),
  age: z.number().min(18),
});

type User = z.infer<typeof User>;

const result = User.safeParse({ name: "Jo", age: 25 });

if (result.success) {
  console.log(result.data.name);
} else {
  for (const issue of result.error.issues) {
    console.error(issue.path.join("."), issue.message);
  }
}

import { Builder } from "@maroonedog/luq";
import { requiredPlugin } from "@maroonedog/luq/plugins/required";
import { stringMinPlugin } from "@maroonedog/luq/plugins/stringMin";
import { numberMinPlugin } from "@maroonedog/luq/plugins/numberMin";

// The type is the source. The rules are declared against it.
type User = {
  name: string;
  age: number;
};

const validateUser = Builder()
  .use(requiredPlugin)
  .use(stringMinPlugin)
  .use(numberMinPlugin)
  .for<User>()
  .v("name", (b) => b.string.required().min(3))
  .v("age", (b) => b.number.required().min(18))
  .build();

const result = validateUser.validate({ name: "Jo", age: 25 });

if (result.valid) {
  console.log(result.data.name);
} else {
  for (const issue of result.issues) {
    console.error(issue.path, issue.message);
  }
}

Same job, same depth on both sides, and the Luq column is the longer one. The extra lines are not scattered: they are one plugin import plus one matching .use() per rule kind, and the type written out as a type instead of falling out of the schema. That is the cost of the direction — nothing is in the bundle that you did not name, and the type is yours rather than inferred — and it is a real cost, not a rounding error.

What the type-first direction buys

Because the type is known when the rules are read, these are compile errors:

• blockA rule that does not apply to the fieldb.string.min(3) on a number field
• blockA path that does not exist on the type"custmer.name"
• blockA missing array wildcard"items.name" instead of "items[*].name"
• blockDescending into a built-in"when.getTime" on a Date
• blockA method that does not existinside an element sub-chain

Each is pinned by a @ts-expect-error in test/type/. TypeScript reports an unused directive, so a green typecheck is the proof that they still fail.

What you give up by choosing this direction

It is not either/or at the boundary

Luq implements Standard Schema v1, so anything that accepts one — tRPC, TanStack Form, Hono, t3-env — takes a Luq validator wherever it takes a zod schema. Using both in one codebase is a normal outcome, not a migration failure.

// Standard Schema means this is not an either/or at the boundary.
import { toStandardSchema } from "@maroonedog/luq/standard-schema";

// Anything that accepts a Standard Schema takes either one.
router.input(toStandardSchema(validateUser));