Alternative naming convention/usage

[bjarketrux]

Hi all,
I want to start a discussion and show how we use Valibot in our project - which does things a bit alternatively.

Our use case

We have an API in C# that our Angular application consumes via HTTP/JSON. All data is typed (TypeScript) but there was no actual validation on whether the TS and C# models align. Enter Valibot.

Example model (product.model.ts)

export interface Product {
  readonly id: string;
  readonly title: string;
}

export interface DiscountedProduct extends Product {
  readonly discount: number;
}

export interface BasketItem {
  readonly product: Product;
  readonly quantity: number;
}

Notice that Product is exported, use, and inherited from.

Our requirements

• We want to use our models
  • Not the inferred model (see below)
  • Be as independent on the validation framework as possible (should not be spread throughout the code)
• We want to validate the JSON
  • Find extraneous properties
  • Find spelling/case mistakes
  • Align optional/undefined/null (especially because myProp? in TS and C# is different)

Our schema definition (product.schema.ts)

export const ProductSchemaRaw = v.strictObject({
  id: v.string(),
  title: v.string(),
});

export const ProductSchema: v.GenericSchema<Product> = ProductSchemaRaw;

export const DiscountedProductSchema: v.GenericSchema<DiscountedProduct> = v.strictObject({
  ...ProductSchemaRaw.entries,
  discount: v.number(),
});

export const BasketItemSchema: v.GenericSchema<BasketItem> = v.strictObject({
  product: ProductSchema,
  quantity: v.number(),
});

Why?

This is not really similar to the existing naming conventions. Here is why:

1. We type cast all schemas we export (v.GenericSchema<Product>). This will use our models (when parsing the JSON) not the inferred model. See the example below why this is preferable.
2. Because we cast the schemas we sometimes export/use the *Raw version of the schema. We need this for inheritance, see Merge objects.

Consider this example:

const book = v.parse(BasketItemSchema, { product: { id: 'a', title: 'book' }, quantity: 1 });
logProduct1(book.product);
logProduct2(book.product);
logProduct3(book.product);
logProduct4(book.product);

function logProduct1(product: any) {
  console.log(product);
}

function logProduct2(product: v.InferOutput<typeof ProductSchema>) {
  console.log(product);
}

function logProduct3(product: { readonly id: string; readonly title: string; }) {
  console.log(product);
}

function logProduct4(product: Product) {
  console.log(product);
}

The four logProduct function all work, but have a different signature.

1. We don't want any...
2. This is in line with the naming convention 1 (but here I use it directly instead of exporting for illustrative purposes). The problem it that this satisfies our model, but is not the same. Using VSCode's "extract method" on book.product would result in a function like logProduct3.
3. The exploded model/sub-model. This is not great for complex objects (but works)
4. This is how we like it and would like VSCode to do refactoring, i.e. use our named TS models

Feedback

What do you think? Is there a better way than casting and having a *Raw exporting convention? Are we overly lazy and should just manually change the type when using "extract method"?

Playground of examples

[fabian-hiller]

Hey 👋 I'm very sorry for my late reply, but I don't have a lot of time right now. Others should feel welcome to discuss your naming convention here, and once I have a little more time, I'll try to take a close look at it, provide feedback, and maybe add it to our docs.