Static typing for Custom Fields

[michaelbromley]

Problem

Defining custom fields is done in the Vendure config object:

export const config: VendureConfig = {
  // ...
  customFields: {
    Product: [{ name: 'keywords',  type: 'string', list: true }],
  }
};

The problem is that these fields are generated dynamically at run-time, so the static TS Product.customFields property has no knowledge of them (the actual type is {} which is pretty useless). This leads to awkward code in your plugins like:

// this is not type-safe
(product.customFields as any).keywords = keywords;

// this is more type-safe but verbose
interface ProductCustomFields {
  keywords: string[];
}

(product.customFields as ProductCustomFields).keywords = keywords;

Solution: declaration merging

TypeScript has a feature known as "declaration merging" which allows interface declarations to "stack", adding properties to the overall interface:

interface Box {
  height: number;
  width: number;
}

interface Box {
  scale: number;
}

let box: Box = { height: 5, width: 6, scale: 10 };

We can use this feature, and combine it with ambient module declarations to merge custom field properties into the built-in Vendure custom field types:

import { CustomProductFields } from '@vendure/core/dist/entity/custom-entity-fields';

declare module '@vendure/core/dist/entity/custom-entity-fields' {
    interface CustomProductFields {
        keywords: string[];
    }
}

// ...

// now TS will know about the custom fields on Product, and
// you can just write this:
product.customFields.keywords = keywords;

The nice thing is that this declaration need only be made in one place, and then all usages of the product.customFields field will be correctly typed implicitly.

Improving dev experience

In a future release I will export the CustomProductFields etc types so that the deep import @vendure/core/dist/entity/custom-entity-fields will be just @vendure/core.

A possible good pattern would be to bundle a custom-field-typings.ts file in the plugin template which sets up the declaration boilerplate for you. Then importing this file into the main plugin.ts file would give access to the merged declarations in all the TS files of the plugin:

// custom-field-typings.ts
import { 
  CustomAddressFields
  CustomFacetFields
  CustomFacetValueFields
  // etc...
} from '@vendure/core';

declare module '@vendure/core' {
    interface CustomAddressFields {
        // add custom fields here
    }
    interface CustomFacetFields {
        // add custom fields here
    }
   // etc...
}

then the plugin.ts file imports it:

// plugin.ts

import './custom-field-typings.ts';

We could also do something similar in the project root of a new @vendure/create install.

Feedback?

I'd like to hear feedback on this proposal - you can try it out in your own projects and let me know how it goes, and any suggestions for better ways to do it.

[jonyw4]

Wonderful, This will be so helpful!!!

[thomas-advantitge]

Hi @michaelbromley, would be a nice improvement!
Would it be possible to change the structure of the custom fields definition in such a way that both compile & runtime definitions can be extracted from the same declaration/initialization:

Do you thinks this would suffice or would it cause problems on the runtime generation? It would probably require to change the VendureConfig from interface to class, but maybe that's worth the change if no declaration at all is needed at the plugin develop's end.

[michaelbromley]

A solution that negates the need for manual declarations would of course be the best option. I'm not quite clear on how the example above could do that though. If you can provide a more complete proof-of-concept which results in being able to have intellisense on product.customFields.foo then I would love to see it!

[thomas-advantitge]

Sorry for the late reaction. I could perhaps build a Vendure fork so you could reproduce the suggestion more easily, but please find a concrete example below which at my end seems to result in strict typings.

The main catch is that it requires to pass typeof customFields to a VendureEntity if you want to access the typed fields. However, there will always be something (like the declare module in your example) needed to fix these typings.

// vendure-config.ts

import { CustomFieldBoolean, CustomFieldString, VendureConfig } from './custom-field-types';

// It is required to extract the custom fields to its own const for reference later on.
export const customFields = {
    Product: {
        infoUrl: CustomFieldString,
        downloadable: CustomFieldBoolean,
    },
};

export const config: VendureConfig = {
    customFields: customFields
    // Other config parts should be added here
};

// example.ts

import { Product } from './custom-field-types';
import { customFields } from './vendure-config';

// Passing the custom fields here fixes typing
const product: Product<typeof customFields> = new Product();
product.customFields = { downloadable: true, infoUrl: '' } // TS OK
product.customFields = { downloadable: 'true', infoUrl: '' } // TS ERROR

// custom-field-types.ts

export class CustomFieldString { constructor(v: string) {} }
export class CustomFieldBoolean { constructor(v: boolean) {} }

export type CustomFieldConfig = Record<string, typeof CustomFieldString | typeof CustomFieldBoolean>;

export interface CustomFields {
    Product: CustomFieldConfig;
    // Other custom fields should be added here
}

export type VendureConfig = { customFields: CustomFields };
export type EntityCustomFields<E extends keyof CustomFields, T extends CustomFields[E]> = { [K in keyof T]: ConstructorParameters<T[K]>[0]};

export class Product<T extends CustomFields> {
    public customFields?: EntityCustomFields<'Product', T['Product']>;
}