@ngx-cocktail/common

A foundational Angular library that provides the core infrastructure for feature-based component and directive enhancement. This library enables the use of Angular Ivy's feature system to create reusable, composable features that can be applied to components and directives through decorators.

⚠️ Experimental Status

Warning! This library is experimental and leverages Angular's internal Ivy APIs. It may contain known and undiscovered issues. Use with caution in production environments.

✨ Features

• Feature-based architecture: Create reusable features that can be applied to any component or directive
• Ivy integration: Leverages Angular's internal Ivy feature system for optimal performance
• Type-safe: Full TypeScript support with proper typing and IntelliSense
• Composable: Combine multiple features on a single component or directive
• Framework agnostic: Works with any Angular application using Ivy
• Lightweight: Minimal bundle size impact
• Decorator-based: Clean, declarative syntax using @Features() decorator

🚀 Quick Start

Installation

npm install @ngx-cocktail/common

Basic Usage

import { Component } from "@angular/core";
import { Features } from "@ngx-cocktail/common";

// Define a custom feature
function MyFeature() {
  return (componentDef: any) => {
    // Your feature logic here
    console.log("MyFeature applied to component");
  };
}

@Component({
  selector: "app-example",
  template: "<div>Hello from enhanced component!</div>",
})
@Features([MyFeature()])
export class ExampleComponent {
  // Your component logic here
}

📖 Documentation

Core Concepts

The @ngx-cocktail/common library provides the foundation for creating feature-based enhancements in Angular applications. It consists of several key components:

Features Decorator

The main decorator that applies features to components and directives.

@Features([Feature1(), Feature2(), Feature3()])
export class MyComponent {}

Component Features

Features that can be applied to Angular components:

import { ComponentFeature } from "@ngx-cocktail/common";

const MyComponentFeature: ComponentFeature = (componentDef) => {
  // Modify component definition
  // Add lifecycle hooks, properties, methods, etc.
};

Directive Features

Features that can be applied to Angular directives:

import { DirectiveFeature } from "@ngx-cocktail/common";

const MyDirectiveFeature: DirectiveFeature = (directiveDef) => {
  // Modify directive definition
  // Add lifecycle hooks, properties, methods, etc.
};

API Reference

Features(features: Feature[])

A decorator that applies features to a component or directive.

Parameters:

• features - Array of feature functions to apply

Returns: ClassDecorator - A decorator function

ComponentFeature

Interface for component features.

interface ComponentFeature extends DirectiveFeature {
  <T>(componentDef: ɵComponentDef<T>): void;
  ngInherit?: true;
}

DirectiveFeature

Interface for directive features.

interface DirectiveFeature {
  <T>(directiveDef: ɵDirectiveDef<T>): void;
  ngInherit?: true;
}

Writable<T>

Utility type that makes all properties of type T writable.

type Writable<T> = {
  -readonly [K in keyof T]: T[K];
};

Advanced Usage

Creating Custom Features

import { ComponentFeature } from '@ngx-cocktail/common';

function LoggingFeature() {
  return (componentDef: any) => {
    const originalFactory = componentDef.factory;

    componentDef.factory = () => {
      const instance = originalFactory();
      console.log(`Component ${componentDef.type.name} created`);
      return instance;
    };
  } as ComponentFeature;
}

@Component({
  selector: 'app-logged',
  template: '<div>Logged component</div>'
})
@Features([LoggingFeature()])
export class LoggedComponent {}

Combining Multiple Features

@Component({
  selector: "app-enhanced",
  template: "<div>Enhanced component</div>",
})
@Features([LoggingFeature(), PerformanceFeature(), AnalyticsFeature()])
export class EnhancedComponent {}

Feature with Inheritance

function InheritableFeature() {
  const feature = (componentDef: any) => {
    // Feature logic
  };

  feature.ngInherit = true; // Makes the feature inheritable
  return feature as ComponentFeature;
}

🔧 Compatibility

| Angular Version | Library Version | | --------------- | --------------- | | Angular 20 | >= v20.0.0 | | Angular 19 | >= v19.0.0 | | Angular 18 | >= v18.0.0 | | Angular 17 | >= v17.0.0 | | Angular 16 | >= v16.0.0 | | Angular 15 | >= v15.0.0 | | Angular 14 | >= v14.0.1 | | Angular 13 | >= v13.0.1 | | Angular 12 | >= v12.0.1 | | Angular 11 | >= v11.0.1 | | Angular 10 | >= v10.0.1 |

📚 Best Practices

1. Keep features focused: Each feature should have a single responsibility
2. Use TypeScript: Leverage TypeScript for better type safety and developer experience
3. Test thoroughly: Features modify internal Angular APIs, so comprehensive testing is essential
4. Document your features: Provide clear documentation for any custom features you create
5. Handle errors gracefully: Features can affect component lifecycle, so proper error handling is crucial
6. Consider inheritance: Use ngInherit: true for features that should be inherited by child components

⚠️ Important Notes

• Experimental: This library uses Angular's internal Ivy APIs which may change between versions
• Breaking changes: Updates to Angular may require updates to this library
• Testing: Always test features thoroughly in your specific use case
• Performance: Features are applied at component creation time, so keep them lightweight
• Debugging: Features can make debugging more complex, so use them judiciously

🔗 Related Libraries

This library serves as the foundation for other ngx-cocktail libraries:

• @ngx-cocktail/destroyable - Automatic subscription cleanup
• @ngx-cocktail/title - Title management for Angular applications

🤝 Contributing

We welcome contributions! Please see our contributing guidelines for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support

• 📧 GitHub Issues
• 📖 Documentation
• ⭐ Star the project

📦 Publishing

1. Commit & push your changes
2. Update a version in package.json
3. Run npm run build:common
4. Run cd dist/common
5. Run npm publish

Made with ❤️ by the ngx-cocktail team