@formspec/eslint-plugin

ESLint plugin for validating FormSpec decorator DSL usage in TypeScript projects. This plugin catches common mistakes by ensuring decorators match their field types and enforcing consistency rules.

Installation

npm install --save-dev @formspec/eslint-plugin
# or
pnpm add -D @formspec/eslint-plugin

Requirements

ESLint v9+ (flat config)
TypeScript v5+

Usage

Recommended Configuration

Add the plugin to your eslint.config.js:

import formspec from "@formspec/eslint-plugin";

export default [
  // ... other configs
  ...formspec.configs.recommended,
];

Manual Configuration

import formspec from "@formspec/eslint-plugin";

export default [
  {
    plugins: {
      "@formspec": formspec,
    },
    rules: {
      "@formspec/decorator-field-type-mismatch": "error",
      "@formspec/enum-options-match-type": "error",
      "@formspec/showwhen-field-exists": "error",
      "@formspec/showwhen-suggests-optional": "warn",
      "@formspec/min-max-valid-range": "error",
      "@formspec/no-conflicting-decorators": "error",
      "@formspec/no-duplicate-decorators": "error",
    },
  },
];

Rules

Rule	Description	Recommended	Strict
`decorator-field-type-mismatch`	Ensures decorators are applied to fields with compatible types	error	error
`enum-options-match-type`	Ensures @EnumOptions values match the field's union type	error	error
`showwhen-field-exists`	Ensures @ShowWhen references a field that exists	error	error
`showwhen-suggests-optional`	Suggests @ShowWhen fields should be optional	warn	error
`min-max-valid-range`	Ensures @Min/@Max have valid ranges	error	error
`no-conflicting-decorators`	Prevents decorators that imply conflicting types	error	error
`no-duplicate-decorators`	Prevents duplicate decorators on the same field	error	error

decorator-field-type-mismatch

Ensures FormSpec decorators are applied to fields with compatible types.

// Valid
@Min(0)
@Max(100)
age!: number;

@Placeholder("Enter name")
name!: string;

@MinItems(1)
@MaxItems(10)
items!: string[];

// Invalid - @Min requires number field
@Min(0)
name!: string; // Error: @Min can only be used on number fields

enum-options-match-type

Ensures @EnumOptions values match the field's TypeScript union type.

// Valid - options match type
@EnumOptions(["draft", "published", "archived"])
status!: "draft" | "published" | "archived";

// Valid - object options with id property
@EnumOptions([{ id: "a", label: "Option A" }, { id: "b", label: "Option B" }])
type!: "a" | "b";

// Valid - string type accepts any options
@EnumOptions(["any", "options"])
value!: string;

// Invalid - missing option "archived"
@EnumOptions(["draft", "published"])
status!: "draft" | "published" | "archived"; // Error: missing "archived"

showwhen-field-exists

Ensures @ShowWhen references a field that exists in the same class.

// Valid
@EnumOptions(["a", "b"])
type!: "a" | "b";

@ShowWhen({ _predicate: "equals", field: "type", value: "a" })
conditionalField?: string;

// Invalid - "nonexistent" field doesn't exist
@ShowWhen({ _predicate: "equals", field: "nonexistent", value: "x" })
conditionalField?: string; // Error: field "nonexistent" does not exist

showwhen-suggests-optional

Suggests that fields with @ShowWhen should be marked as optional since they may not be present in the output.

// Valid
@ShowWhen({ _predicate: "equals", field: "type", value: "a" })
conditionalField?: string; // Good - optional

// Warning
@ShowWhen({ _predicate: "equals", field: "type", value: "a" })
conditionalField!: string; // Warning: should be optional

min-max-valid-range

Ensures @Min value is less than or equal to @Max value.

// Valid
@Min(0)
@Max(100)
value!: number;

@Min(5)
@Max(5) // Equal is valid
exact!: number;

// Invalid
@Min(100)
@Max(50) // Error: @Min(100) > @Max(50)
invalid!: number;

no-conflicting-decorators

Prevents using decorators that imply conflicting field types.

// Valid - both imply number
@Min(0)
@Max(100)
value!: number;

// Invalid - @Min implies number, @Placeholder implies string
@Min(0)
@Placeholder("Enter value") // Error: conflicting decorators
field!: string;

no-duplicate-decorators

Prevents applying the same decorator multiple times to a field.

// Valid
@Label("Name")
@Placeholder("Enter name")
name!: string;

// Invalid
@Label("First")
@Label("Second") // Error: duplicate @Label
name!: string;

Configurations

Strict

All rules enabled as errors for maximum type safety enforcement.

import formspec from "@formspec/eslint-plugin";

export default [
  ...formspec.configs.strict,
];

License

UNLICENSED