Deprecation Contracts

Deprecation Contracts

VIEW

Lockness provides a built-in system to manage gracefully the evolution of your code using Deprecation Contracts. This system allows you to signal that a feature is becoming obsolete, while providing guidance on what to use instead.

Inspired by the symfony/deprecation-contracts PHP package, @lockness/deprecation-contracts is a standalone package with zero internal dependencies, making it lightweight and reusable across any Deno project.

🚀 Getting Started

The @lockness/deprecation-contracts package is a core utility of the framework.

Installation

If it's not already installed, you can add it via Nessy:

bash
./nessy package:install deprecation-contracts

Architecture

The package is designed to be framework-agnostic:

  • Zero Dependencies: No internal dependencies on @lockness/container or @lockness/logger
  • Default Handler: Uses console.warn for deprecation notices with styled output
  • Extensible: You can integrate custom loggers at the application level if needed

🛠 Usage

There are two main ways to trigger a deprecation notice: using the triggerDeprecation function or the @Deprecated decorator.

1. Using @Deprecated Decorator (Recommended)

The most elegant way to handle deprecations in a class-based environment like Lockness is using the @Deprecated decorator. It can be applied to classes, methods, and accessors.

Decorating a Class

The notice is triggered when a new instance is created.

typescript
import { Deprecated } from '@lockness/core'

@Deprecated('2.0.0', 'Use AuthService instead')
export class UserRegistrationService {
    // ...
}

Decorating a Method

The notice is triggered only when the method is called.

typescript
class UserService {
    @Deprecated('1.5.0', 'Use findByEmail() for better performance')
    find(id: string) {
        // ...
    }
}

Decorating an Accessor

The notice is triggered when reading or writing the property.

typescript
class Config {
    @Deprecated('1.1.0', 'Use settings.theme instead')
    accessor theme = 'dark'
}

2. Using triggerDeprecation function

For procedural code or more complex conditions, you can use the function directly.

typescript
import { triggerDeprecation } from '@lockness/deprecation-contracts'

function oldHelper() {
    triggerDeprecation(
        'my-package',
        '1.2.0',
        'The oldHelper() is deprecated, use %s instead',
        'newHelper()',
    )
    // ...
}
ArgumentDescription
packageThe name of the package/module triggering the deprecation.
versionThe version that introduced the deprecation.
messageThe notification message (supports %s placeholders).
...argsOptional values to replace placeholders or append to the message.

⚙️ Configuration

Deprecation behavior can be controlled via environment variables in your .env file.

VariableDefaultDescription
STRICT_DEPRECATIONSfalseIf true, triggers an Error instead of a warning. Recommended for CI/Tests.
IGNORE_DEPRECATIONSfalseIf true, suppresses all deprecation notices.

🔧 Devtools Integration

When using the Lockness Devtools, all deprecation notices are automatically captured in a dedicated tab.

  • Stack Trace: Each notice includes a full stack trace to identify exactly where the deprecated code is called.
  • Aggregation: Overlapping notices are grouped for a cleaner overview.
  • Real-time: Notices appear instantly in the Devtools dashboard during development.

🎨 Aesthetics

In the console, deprecations are styled for high visibility:

text
[DEPRECATION] Since my-pkg 1.2.0: Method old() is deprecated. Use new() instead.
Edit this page