Generating type definitions for mixin classes with protected members

TypeScript Version: 2.4.2

Code:

I'm using mixins as described by: #13743

export type Constructor<T> = new(...args: any[]) => T;
export function Unsubscriber<T extends Constructor<{}>>(Base: T)  {
  class Unsubscriber extends Base implements OnDestroy {
    protected unsubscribe: Subject<void> = new Subject();

    ngOnDestroy() {
      this.unsubscribe.next();
      this.unsubscribe.complete();
    }
  }
  return Unsubscriber;
}

If I compile this code with "declaration": true to get type definitions for my library, I get the following error:

ERROR in (truncated)/mixins.ts (...): Return type of exported function has or is using private name 'Unsubscriber'.

One solution is to add an interface...

export interface IUnsubscriber extends OnDestroy {
  unsubscribe: Subject<void>;
}

...and have my mixin function have a return type of Constructor<IUnsubscriber>. This works, but it forces me to make the properties/methods exposed by my mixin be public even in cases where I want them to be protected.

Short of adding protected members to interfaces (which I'm not sure is the right thing to do), this seems to be a limitation of the currently supported mixin strategy.

BTW I found that you can work around this limitation to some extent by using ECMAScript symbols, which provide a non-TypeScript way to hide a member:

export type Constructor<T> = new(...args: any[]) => T;

const unsubscribe: unique symbol = Symbol('Unsubscriber.unsubscribe');

export function Unsubscriber<T extends Constructor<{}>>(Base: T)  {
  class Unsubscriber extends Base implements OnDestroy {
    public [unsubscribe]: Subject<void> = new Subject();

    ngOnDestroy() {
      this[unsubscribe].next();
      this[unsubscribe].complete();
    }
  }
  return Unsubscriber;
}

IntelliSense will only show the unsubscribe member to callers who have access to the unsubscribe symbol.

It bothers me too. Seems that this issue was moved into future milestone. No plan to solve it in the near future?

BTW I recently came up with an alternate way to represent mixins in TypeScript. Consider this example:

// Helper that copies properties from base's prototype
// to child's prototype
function extend(child: any, base: any): void {
  for (var property in base) {
    var descriptor = Object.getOwnPropertyDescriptor(base, property) || { value: base[property] };
    Object.defineProperty(child, property, descriptor);
  }
}

// The mixin base classes
class Base1 {
    constructor() {
        console.log('Base1.constructor() called')
    }
    public method1(): void {
        console.log('method1() called')
    }
}

class Base2 {
    constructor() {
        console.log('Base2.constructor() called')
    }
    public method2(): void {
        console.log('method2() called')
    }
}

class Base3 {
    constructor() {
        console.log('Base3.constructor() called')
    }
    private _prop3 = 123;
    public get prop3(): number {
        return this._prop3;
    }
}

// Collect the base classes into an intermediary "Mixin" class
type Mixin = Base1 & Base2 & Base3;
const Mixin: { new(): Mixin } = class { 
    constructor() {
        Base1.call(this);
        Base2.call(this);
        Base3.call(this);
    }
} as any;
extend(Mixin.prototype, Base1.prototype);
extend(Mixin.prototype, Base2.prototype);
extend(Mixin.prototype, Base3.prototype);

// Extend from the "Mixin" class
class Child extends Mixin {
    public method4(): void {
        console.log('method4() called')
    }    
}

const child = new Child();

child.method1();
child.method2();
console.log('prop3 = ' + child.prop3);
child.method4();

The behavior is probably unsound if the base classes happen to have members with the same name. But this issue could be detected in the extend() function.

There are some interesting advantages:

The base classes don't need to be represented specially; they are ordinary TypeScript classes
You can use private members without any trouble
The generated .d.ts file is simple and understandable

Not sure I'd recommend to do this in real code, but it's interesting to contrast with the class-expression approach to mixins.

Ryan Cavanaugh (@RyanCavanaugh)

It bothers me too. Seems that this issue was moved into future milestone. No plan to solve it in the near future?

Well me too !

Ryan Cavanaugh (@RyanCavanaugh) Any update on when this could be fixed ? It's set on the "Future" backlog but as it's pretty huge, could you add some precision ?

Wesley Wigham (@weswigham)

Here is my research regarding possible workarounds for TS mixins with protected methods.

Overview

These are 3 approaches that can be used for writing mixins that need to expose protected methods.
They all allow subclasses extending such mixins to call these methods using super.

1. Symbol approach

Not using protected methods in the mixins
Using Symbol as recommended by Elix
Example: see above comment Generating type definitions for mixin classes with protected members #17744 (comment)

Pros

Methods are truly protected (can't be called from outside, e.g. by third party code)
Methods are "public" in terms of TS and can be annotated on the interface
Explicit exports potentially help with refactoring of the consumers' subclasses
Methods are excluded from the DevTools console's auto-complete list (good for user)
Avoid potential name conflicts if user extends a class with their own methods

Cons

Consumers have to import symbols if they need to override protected methods
Jump to definition is not ideal (jumps to the place where Symbol() is created)

2. Dumb class approach

Using protected methods in the mixins
Using abstract class SomeMixinClass to "annotate" them
Example: [ts] 'private' modifier cannot appear on a type member. #25163 (comment)

Pros

No need to import anything (except the mixin itself) for the consumer component
Methods are easy to access in the DevTools console (good for maintainer)

Cons

Both interface (for public API) and abstract class (for protected API) are needed
The abstract class ends up in the JS output (as empty class with no methods)
The mixin function needs to confusingly accept the argument with a type cast (instead of the actual expected class) in order to pick up the annotated protected methods from it:

// with dumb class: confusing
<T extends Constructor<SlottedItemsClass>>(base: T)

// without dumb class: clean
<T extends Constructor<LitElement>>(base: T)

Need for extra super check: super._focus && super._focus() - this is needed because the abstract classes mark methods using _focus?(), i.e. "possibly undefined"
Jump to definition from the subclass goes to a dumb class

3. Public methods

Keep methods public, add them on the interface
Jump to definition works as expected
Example: Make members private again hypermedia-app/Alcaeus#33

Pros

No extra code needed (symbols / dumb classes)

Cons

TS users would get protected methods listed in the code completion
Messing up public and protected API might need tweaks for tools

Summary

Personally, I like symbols approach more because it's cleaner and bulletproof. The "jump to definition" inconvenience is a drawback that is more of a personal preference.

On the other hand, the dumb class approach has its benefits: once the issue is resolved, we can get rid of those dumb classes and potentially keep the methods themselves unchanged.

Wesley Wigham (@weswigham) according to your comment at #17293 (comment), what do you have on your mind to tackle these issues? Is there a plan, or does this still need a concrete proposal that you mentioned?

Is there a plan, or does this still need a concrete proposal that you mentioned?

Still needs a proposal.

Chris Frolik (@fr0)

Chris Frolik (@fr0) Also worth noting #35822

Wesley Wigham (@weswigham)

We hit this issue again when we tried to factor out a base class with private and protected members into a mixin.

Because we've already provided protected methods to subcasses of our base class, we really needed to keep existing protected members protected. If the members became public, then subclasses would get errors on trying to override public members with protected.

The workarounds we've had to do to satisfy the compiler are pretty onerous. We've created a fake class outside of the mixin and cast the mixin function to return an intersection of the argument and that class. Static require another fake class. Then we need to get our build system to remove the fake class. I'm not sure this approach solved every problem yet.

Wesley Wigham (@weswigham)

Still needs a proposal.

Is there anything anyone not on the TS team can do to help here?

Well, we discussed it at our last design meeting as future work beyond abstract constructor types, however some team members think allowing a class-expression-like-thing in a type position (and having that refer to the static shape of the declared class) would be confusing. IMO, it makes sense since the shape stored by

type A = class {}

would be the same as the type of the const in

const A = class {}

But that's only my point of view. The disagreement within the team means we're going to need to see both a serious proposal and serious justification for why it's needed and how it makes sense before we're going to get close to agreement.

Wesley Wigham (@weswigham)

Wesley Wigham (@weswigham) I think a list of why it is needed is in this issue: #35822
The list in the Description.

I come up with a (maybe) visually better solution based on The Dumb Class Approach.

Pros:

Easier to understand by hiding the ugly type details

Cons:

Still need to define two classes
Unsound: no guarantee that the mixin class implements the dumb class correctly
A little runtime overhead: uses a function createMixin to make TypeScript infer types

export type ConstructorOf<T> = new (...args: unknown[]) => T

export type MixinFactory<T, TBase> = (Base: ConstructorOf<TBase>) => ConstructorOf<T>
export interface MixinOf<T> {
  (): ConstructorOf<T>
  <U = {}>(Base?: ConstructorOf<U>): ConstructorOf<T & U>
}

export function createMixin<TBase = {}, T = TBase>(factory: MixinFactory<T, TBase>): MixinOf<T & TBase> {
  return ((Base = Object) => factory(Base as any)) as any
}

export type MixinType<T extends MixinOf<unknown>> = T extends MixinOf<infer U> ? U : never

// Case 1. define a normal mixin (with no type parameter)
export type FooMixin = MixinType<typeof FooMixin>
export const FooMixin = createMixin(Base => class FooMixin extends Base {
  foo() {}
})

// Case 2. define a mixin with protected/private fields (with type parameter)
declare class BarMixinBase {
  protected bar(): void
}

export type BarMixin = MixinType<typeof BarMixin>
export const BarMixin = createMixin<BarMixinBase>(Base => class BarMixin extends Base {
  protected bar() {}
})

// Usage
export class MyClass extends FooMixin(BarMixin()) {
  test() {
    this.foo()
    this.bar()
  }
}

Hope the TS team to eventually solve the issue.

Enable declaration file emission. Fix issues that arrise from this

Jingkun Hua (@hjkcai)

I recently encountered this issue when I tried to create mixins for WebComponents (more specifically with Lit). It's really annoying that the whole mixin situation still hasn't been fixed after 8 years, even though mixins are a well-known (and much needed) pattern.

Since the existing workarounds didn't fully meet my needs, I experimented with building on Jingkun Hua (@hjkcai)'s approach, with the following goals:

Support both standalone and constrained mixins
Enforce that a mixin class actually implements the dumb class
Allow constrained mixins to extend static properties
Ensure constrained mixins work with abstract and generic base classes
Allow mixins themselves to be abstract

The main drawback of my approach, forcing a mixin to actually implements the dumb class, is that you need two dumb classes. This means you have to define the properties three times in total – but you can usually auto-generate them after specifying them once (at least with VSCode).

Here's how it works:

The MixinAbstractAPI dumb class defines which properties and methods the mixin itself must implement.
The MixinAPI dumb class defines the shape of the class after the mixin is applied.

In most cases:

All members in MixinAbstractAPI should be marked as abstract.
The corresponding members in MixinAPI should not be abstract.

This ensures the mixin must implement those members, and the consuming class automatically gets them. Unfortunately, this is the only option I've found, as there is currently no way to have an interface with protected members or something similar. You can also skip the part with the second dumb class (MixinAbstractAPI), but then the implementation will not be enforced. (see example below)

export type Constructor<TInstance = object> = new (...args: any[]) => TInstance;
export type AbstractConstructor<TInstance = object> = abstract new (...args: any[]) => TInstance;

export type MixinFactory<TBase extends AbstractConstructor, TMixin, TMixinAPI = TMixin> = (
  Base: Constructor<TMixinAPI> & TBase
) => Constructor<TMixin> & TBase;

export interface MixinOf<TMixinAPI> {
  (): Constructor<TMixinAPI>;
  <T extends AbstractConstructor>(Base?: T): Constructor<TMixinAPI> & T;
}

export interface ConstrainedMixinOf<TBase extends AbstractConstructor, TMixinAPI> {
  <T extends AbstractConstructor>(Base: TBase & T): Constructor<TMixinAPI> & TBase & T;
}

export function createMixin<
  TMixin extends object,
  TMixinAPI extends object = TMixin
>(factory: MixinFactory<AbstractConstructor, TMixin, TMixinAPI>): MixinOf<TMixin & TMixinAPI>;

export function createMixin<
  TMixinAPI extends TMixinAbstractAPI,
  TMixinAbstractAPI extends object
>(factory: MixinFactory<AbstractConstructor, TMixinAbstractAPI>): MixinOf<TMixinAPI>;

export function createMixin(factory: MixinFactory<Constructor, object>): unknown {
  return function Mixin(Base: Constructor) {
    return factory(Base);
  };
}

export function createConstrainedMixin<
  TBase extends AbstractConstructor,
  TMixinAPI extends object = object
>(factory: MixinFactory<TBase, TMixinAPI>): ConstrainedMixinOf<TBase, TMixinAPI>;

export function createConstrainedMixin<
  TBase extends AbstractConstructor,
  TMixinAPI extends TMixinAbstractAPI,
  TMixinAbstractAPI extends object
>(factory: MixinFactory<TBase, TMixinAbstractAPI>): ConstrainedMixinOf<TBase, TMixinAPI>;

export function createConstrainedMixin(factory: MixinFactory<Constructor, object>): unknown {
  return function Mixin(Base: Constructor) {
    return factory(Base);
  };
}

Examples

Case 1: Standalone Mixin adding only public properties

export const WithIdMixin = createMixin(
  Base =>
    class extends Base {
      public readonly id = `component-${Math.random().toString(36).substring(2, 9)}`;
    }
);

Case 2: Standalone Mixin adding public/protected properties (no implementation guarantee)

export declare class LoggingMixinAPI {
  protected logPrefix: string;
  protected log(message: string): void;
}

export const WithLoggingMixin = createMixin<LoggingMixinAPI>(
  Base =>
    class extends Base {
      protected override logPrefix = 'INFO';

      protected override log(message: string): void {
        console.log(`[${this.logPrefix}] ${message}`);
      }
    }
);

Case 3: Standalone Mixin adding public/protected properties (with implementation guarantee)

declare abstract class LoggingMixinAbstractAPI {
  protected abstract logPrefix: string;
  protected abstract log(message: string): void;
}

export declare class LoggingMixinAPI extends LoggingMixinAbstractAPI {
  protected logPrefix: string;
  protected log(message: string): void;
}

export const WithLoggingMixin = createMixin<LoggingMixinAPI, LoggingMixinAbstractAPI>(
  Base =>
    class extends Base {
      protected logPrefix = 'INFO';

      protected log(message: string): void {
        console.log(`[${this.logPrefix}] ${message}`);
      }
    }
);

Case 4: Constrained Mixin adding no new public/protected properties

export const WithLifecycleLoggingMixin = createConstrainedMixin<typeof LitElement>(
  Base =>
    class extends Base {
      protected override firstUpdated(changedProperties: PropertyValues): void {
        super.firstUpdated(changedProperties);
        console.log(`${this.constructor.name} has been rendered to the DOM for the first time.`);
      }
    }
);

Case 5: Constrained Mixin adding new public/protected properties (no implementation guarantee)

export declare class DisabledMixinAPI {
  public disabled: boolean;
}

export const WithDisabledMixin = createConstrainedMixin<typeof LitElement, DisabledMixinAPI>(Base => {
  class Mixin extends Base {
    @property({ type: Boolean, reflect: true })
    public override disabled = false;
  }
  return Mixin;
});

Case 6: Constrained Mixin adding new public/protected properties (with implementation guarantee)

declare abstract class DisabledMixinAbstractAPI {
  public abstract disabled: boolean;
}

export declare class DisabledMixinAPI extends DisabledMixinAbstractAPI {
  public override disabled: boolean;
}

export const WithDisabledMixin = createConstrainedMixin<typeof LitElement, DisabledMixinAPI, DisabledMixinAbstractAPI>(
  Base => {
    class Mixin extends Base {
      @property({ type: Boolean, reflect: true })
      public disabled = false;
    }
    return Mixin;
  }
);

Example: Composing multiple Mixins

export class ButtonComponent extends WithDisabledMixin(WithLifecycleLoggingMixin(WithLoggingMixin(WithIdMixin(LitElement)))
) {
  public constructor() {
    super();
    this.log(`Component created with ID: ${this.id}`);
  }

  public clickHandler(): void {
    if (this.disabled) {
      this.log('Button is disabled.');
      return;
    }

    this.log('Button clicked!');
  }
}

Example: Abstract Mixin

declare abstract class FormMixinAbstractAPI {
  protected abstract submit(): void;

  // This property doesn't need to be implemented by the mixin.
  public value: string;
}

export declare abstract class FormMixinAPI extends FormMixinAbstractAPI {
  protected submit(): void;

  // This property MUST be implemented by the class using the mixin.
  public abstract value: string;
}

export const WithFormMixin = createMixin<FormMixinAPI, FormMixinAbstractAPI>(
  Base =>
    class extends Base {
      public override submit(): void {
        console.log('Submitting value:', this.value);
      }
    }
);

export class FormComponent extends WithFormMixin(LitElement) {
  @property()
  public value = 'Hello World!';
}

Example: Mixin with a Abstract Base Class

export abstract class SomeAbstractClass {
  public abstract value: string;

  public printValue(): void {
    console.log(`Value from abstract base: ${this.value}`);
  }
}

export class SomeClass extends WithIdMixin(SomeAbstractClass) {
  public value = 'Hello World!';
}

Example: Mixin with a Generic Base Class

export class ListComponent<T> extends LitElement {
  @property({ type: Array })
  public items: T[] = [];
}

declare abstract class SelectionMixinAbstractAPI {
  public abstract selectedItem: number | null;
  public abstract selectItem(index: number): void;
}

export declare class SelectionMixinAPI extends SelectionMixinAbstractAPI {
  public selectedItem: number | null;
  public selectItem(item: number): void;
}

export const WithSelectionMixin = createConstrainedMixin<
  Constructor<LitElement>,
  SelectionMixinAPI,
  SelectionMixinAbstractAPI
>(Base => {
  class Mixin extends Base {
    @property()
    public selectedItem: number | null = null;

    public selectItem(item: number): void {
      this.selectedItem = item;
    }
  }
  return Mixin;
});

export interface User {
  id: number;
  name: string;
}

export class UserListSelectionComponent extends WithSelectionMixin<typeof ListComponent<User>>(ListComponent) {
  // `this.items` has type `User[]`
}

Example: Constrained Mixin extending static properties

export class SomeBaseComponent extends LitElement {
  public static override get styles(): CSSResultGroup {
    return css`
      :host {
        color: var(--theme-color-primary);
        background: var(--theme-background-primary);
      }
    `;
  }
}

export const WithThemeMixin = createConstrainedMixin<typeof SomeBaseComponent>(
  Base =>
    class extends Base {
      public static override get styles(): CSSResultGroup {
        return [
          super.styles,
          css`
            :host {
              --theme-color-primary: #3498db;
              --theme-background-primary: #ecf0f1;
            }
          `
        ];
      }
    }
);

export class ThemedComponent extends WithThemeMixin(SomeBaseComponent) {}

Example: Constrained Mixin based on another Mixin

declare abstract class DebugMixinAbstractAPI {
  protected abstract debug(message: string): void;
}

export declare class DebugMixinAPI extends DebugMixinAbstractAPI {
  protected debug(message: string): void;
}

export const DebugMixin = createConstrainedMixin<typeof LitElement & Constructor<LoggingMixinAPI>, DebugMixinAPI, DebugMixinAbstractAPI>(
  Base =>
    class extends Base {
      protected override logPrefix = 'DEBUG';

      protected debug(message: string): void {
        this.log(`${this.tagName}: ${message}`);
      }
    }
);

Example: Extending the EventMap of a Component (Generic Mixin)

export declare class EventMapMixinAPI<TEventMap extends HTMLElementEventMap> extends HTMLElement {
  public override addEventListener<TEvent extends keyof TEventMap>(
    type: TEvent,
    listener: (this: HTMLElement, ev: TEventMap[TEvent]) => void,
    options?: boolean | AddEventListenerOptions
  ): void;

  public override removeEventListener<TEvent extends keyof TEventMap>(
    type: TEvent,
    listener: (this: HTMLElement, ev: TEventMap[TEvent]) => void,
    options?: boolean | EventListenerOptions
  ): void;
}

export const createEventMapMixin = <TEventMap extends HTMLElementEventMap>(): ConstrainedMixinOf<
  Constructor<HTMLElement>,
  EventMapMixinAPI<TEventMap>
> => createConstrainedMixin(Base => Base);

interface SomeComponentEventMap extends HTMLElementEventMap {
  updated: CustomEvent<{ value: string }>;
}

const SomeComponentEventMapMixin = createEventMapMixin<SomeComponentEventMap>();

class SomeComponent extends SomeComponentEventMapMixin(LitElement) {
  protected override updated(): void {
    this.dispatchEvent(new CustomEvent('change', { detail: { value: 'Hello World' } }));
  }
}

const someComponent = new SomeComponent();
someComponent.addEventListener('updated', event => console.log(event.detail.value));

Edit (2025-11-30): Fixes TBase not being enforced when using constrained mixins.

Navigation Menu

Repository navigation

Generating type definitions for mixin classes with protected members #17744

4 remaining items

Overview

1. Symbol approach

Pros

Cons

2. Dumb class approach

Pros

Cons

3. Public methods

Pros

Cons

Summary

Examples

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Generating type definitions for mixin classes with protected members #17744

Description

Activity

4 remaining items

octogonz commented on Oct 20, 2018

hueyhe commented on Mar 1, 2019

octogonz commented on Mar 1, 2019

Elvynia commented on Aug 30, 2019

web-padawan commented on Nov 27, 2019

Overview

1. Symbol approach

Pros

Cons

2. Dumb class approach

Pros

Cons

3. Public methods

Pros

Cons

Summary

weswigham commented on Nov 27, 2019

trusktr commented on May 12, 2020

justinfagnani commented on Nov 17, 2020

weswigham commented on Nov 18, 2020

jogibear9988 commented on Mar 19, 2021

hjkcai commented on Apr 1, 2021

hampoelz commented on Sep 29, 2025

Examples

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions