Tech-Spec

Installation

npm install -g tech-spec

Usage example

techs-spec/some-feature.tech-spec.yaml

type: feature
metadata:
  name: somrt
spec:
  someting:
    type: date
    value: '2023-02-01'
  another:
    type: link
    value: https://google.com
  asd:
    type: string
    value: 'test string'

tech-spec/login.field.tech-spec.yaml

type: field
metadata:
  name: login
spec:
    type: string
    regex: '^[\w_]{4,100}$'

tech-spec/password.field.tech-spec.yaml

type: field
metadata:
  name: password
spec:
  type: string
  regex: '^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9]){5;150}$'

tech-spec/registration.form.tech-spec.yaml

type: form
metadata:
  name: Registration
spec:
  login:
    required: true
    fieldRef: login
    helperMessage: null
    errorMessage: null

  password:
    required: true
    fieldRef: password
    errorMessage: 'Invalid'
    helperMessage: null

Command:

techspec generate tech-spec output
❇️  Code is successfully generated

output/form.ts

export const RegistrationForm = {
  login: {
    required: true,
    fieldRef: "login",
    helperMessage: null,
    errorMessage: null,
    field: {
      type: "string",
      regex: new RegExp("^[\\w_]4,100}$")
    }
  },
  password: {
    required: true,
    fieldRef: "password",
    errorMessage: "Invalid",
    helperMessage: null,
    field: {
      type: "string",
      regex: new RegExp("^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9]){5;150}$")
    }
  }
};

output/features.ts

export const somrtFeature = {
  someting: {
    type: "date",
    value: new Date("2023-02-01")
  },
  another: {
    type: "link",
    value: new URL("https://google.com")
  },
  asd: {
    type: "string",
    value: "adsa"
  }
};

In your client code:

import { buildValidators, FormValidators, ValidatorError } from 'tech-spec'
import { RegistrationForm } from '<output-dir>/form'

const validators: FormValidators<typeof RegistrationForm> = buildValidators(RegistrationForm)
const result: ValidatorError = validators.login('asd') // login has less characters than required in spec
if (!result.isValid) {
    throw new Error(result.errorMessage)
}

Yaml Parsing Errors Examples

tech-spec/light.theme.tech-spec.yaml

type: theme
metadata:
  name: light
  asd
spec:
  colors:
    check: rgba(255, 255, 255, 255)

techspec validate tech-spec

🚨 YamlParsingError: tech-spec/registration.form.tech-spec.yaml

Reason: bad indentation of a mapping entry

4 | spec:
5 |   login:
6 |     asdasd
7 |     required: true
-----------------^
8 |     fieldRef: login
9 |     helperMessage: null

Types of spec

• form
• field
• DesignSystem
• feature

Form

type: form

Metadata fields:

• name: string

Each key in spec mapping represents name of field.

Field mapping keys:

• required: boolean
• errorMessage: string | null
• helperMessage: string | null
• fieldRef: string (must be the same as field.metadata.name)

Example:

type: form
metadata:
  name: Registration
spec:
  login:
    required: true
    fieldRef: login
    helperMessage: null
    errorMessage: null

  password:
    required: true
    fieldRef: password
    errorMessage: 'Invalid'
    helperMessage: null

Field

type: field

Metadata fields:

• name: string

Each key in spec mapping represents name of field.

Spec fields:

• type: 'string'
• regex: string (valid regex string)

Example:

type: field
metadata:
  name: login
spec:
  type: string
  regex: '^[\w_]4,100}$'

Feature

type: feature

Metadata fields:

• name: string

Each key in spec mapping represents name of field.

Different types have different configuration options.

Field types and their spec fields

• type: string

  value: string (any string)

• type: uint

  value: number (unsigned integer number)

• type: int

  value: number (signed integer number)

• type: float

  value: number (number with floating point)

• type: link

  value: string (http link)

• type: email

  value: string

• type: regex

  value: string (valid regex string)

• type: date

  value: string (date string according to RFC3339)

• type: time

  value: string (time string according to RFC3339)

• type: datetime

  value: string (date-time string according to RFC3339)

• type: duration

  value: string (duration string according to RFC3339)

• type: uuid

  value: string (valid uuid string according to RFC4122)

Example:

type: feature
metadata:
  name: somrt
spec:
  someting:
    type: date
    value: '2023-02-01'
  another:
    type: link
    value: https://google.com
  asd:
    type: string
    value: 'test string'