Documentation

Complete API reference for ts-lombok-kit decorators.

Getting Started

ts-lombok-kit provides TypeScript decorators that generate boilerplate code at compile time. Unlike runtime decorators, the generated code has zero overhead in production.

Basic Usage

import { Data, Builder, Record, With } from 'ts-lombok-kit/markers';

// Use decorators on your classes
@Data
class User {
  id: number;
  name: string;
  email: string;
}

How It Works

ts-lombok-kit uses TypeScript's compiler API to transform your code at compile time:

Parse

Reads your TypeScript source files and builds an AST

Transform

Identifies decorated classes and generates methods

Emit

Outputs transformed JavaScript with all methods included

Note: The decorator markers (ts-lombok-kit/markers) are no-op functions at runtime—they only serve as markers for the compiler transformer.

Decorator Reference

Decorator	Type	Description
`@Record`	Class	Immutable data carrier (constructor, readonly, freeze, toString)
`@Value`	Class	Alias for @Record
`@Data`	Class	@Getter + @Setter + @ToString + @Equals + @AllArgsConstructor
`@Getter`	Class	Generate getX() methods
`@Setter`	Class	Generate setX() methods
`@ToString`	Class	Generate toString() method
`@Equals`	Class	Generate equals() and hashCode()
`@With`	Class	Generate withX() methods
`@Builder`	Class	Generate builder pattern
`@NoArgsConstructor`	Class	Generate empty constructor
`@AllArgsConstructor`	Class	Generate constructor with all fields
`@RequiredArgsConstructor`	Class	Generate constructor with required fields
`@Singleton`	Class	Singleton pattern with getInstance()
`@Log`	Class	Add protected logger field
`@NonNull`	Property	Validate not null in constructor

Class Decorators

`@Record`

Creates an immutable data carrier with:

Constructor with all fields as parameters
Readonly properties
Object.freeze(this) in constructor
toString() method

@Record
class User {
  id: number;
  name: string;
}

const user = new User(1, 'John');
console.log(user.toString()); // User(id=1, name=John)
console.log(Object.isFrozen(user)); // true
// user.name = 'Jane'; // Error: Cannot assign to readonly

`@Data`

Shortcut that combines: @Getter + @Setter + @ToString + @Equals + @AllArgsConstructor

@Data
class User {
  id: number;
  name: string;
}

const user = new User(1, 'John');
user.getId();           // 1
user.setName('Jane');
user.toString();        // User(id=1, name=Jane)
user.equals(other);     // true/false
user.hashCode();        // number

`@Builder`

Implements the builder pattern with a fluent API:

Static builder() method
Chainable setter methods for each field
build() method to create the instance

@Builder
class User {
  id: number;
  name: string;
  email: string;
}

const user = User.builder()
  .id(1)
  .name('John')
  .email('john@example.com')
  .build();

`@Singleton`

Ensures only one instance exists via getInstance().

@Singleton
@NoArgsConstructor
class AppConfig {
  apiUrl: string = 'https://api.example.com';
}

const config1 = AppConfig.getInstance();
const config2 = AppConfig.getInstance();
console.log(config1 === config2); // true

Property Decorators

`@NonNull`

Property decorator that validates fields are not null/undefined in the constructor.

@AllArgsConstructor
class User {
  @NonNull
  id: number;

  @NonNull
  name: string;
}

new User(1, 'John');     // OK
new User(null, 'John');  // Throws: "id cannot be null or undefined"

Best Practices

Do: Use @Record for immutable data

Prefer @Record or @Value for data transfer objects and value types that shouldn't be modified after creation.

Do: Combine @Record with @With

Use @With alongside @Record to get immutable updates that create new instances instead of mutating.

Don't: Mix @Record with @Setter

@Record makes properties readonly and freezes the object. Adding @Setterwould create unusable setters.

Do: Use @Builder for complex objects

When a class has many fields (4+), use @Builder for clearer object construction.

Troubleshooting

Generated methods not recognized by IDE

Make sure your IDE is using the workspace TypeScript version:

// .vscode/settings.json
{
  "typescript.tsdk": "node_modules/typescript/lib"
}

ts-patch not working

Try reinstalling ts-patch and running the prepare script:

npm uninstall ts-patch
npm install ts-patch
npm run prepare

Decorators not being transformed

Verify your tsconfig.json includes the plugin and has experimentalDecorators enabled:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "plugins": [
      { "transform": "ts-lombok-kit" }
    ]
  }
}

Setup Features