hap-fluent / AccessoryHandler

Class: AccessoryHandler<TContext, Services>

Defined in: packages/hap-fluent/src/AccessoryHandler.ts:432

Class-based wrapper around a Homebridge PlatformAccessory that manages its fluent service helpers and exposes a typed services map.

Remarks

Extend AccessoryHandler in your Homebridge platform accessory class to get typed access to all services via this.services without writing boilerplate wrap calls. Call this.addService() in your constructor for each HAP service you want to manage, then call this.initialize() with initial state if needed.

this.services is populated from accessory.services at construction time. Services added later via this.addService() are accessible through FluentService references returned by that method but are not automatically added to this.services — update this.services manually if needed.

Use When

• You prefer class inheritance over the functional initializeAccessory() pattern.
• You need a stable this.services reference that persists across handler calls.
• You want to extend the handler with custom methods specific to your device type.

Avoid When

• Your Homebridge plugin already extends another base class — use the functional initializeAccessory() pattern instead to avoid multiple inheritance issues.
• You only need a one-off initialization — initializeAccessory() is simpler.

Pitfalls

• NEVER call this.initialize() after api.registerPlatformAccessories() — characteristic values set post-publish are sent as HomeKit notifications, which can spam the iOS controller and drain device battery.
• NEVER hold references to FluentService instances across Homebridge restarts — each restart creates a fresh AccessoryHandler; old service references are invalid and will silently operate on orphaned characteristic objects.

Example

import { AccessoryHandler } from 'hap-fluent';

class SmartLightHandler extends AccessoryHandler<MyContext, [LightbulbInterface]> {
  constructor(plugin: MyPlatform, accessory: PlatformAccessory<MyContext>) {
    super(plugin, accessory);
  }

  async setup() {
    const lightbulb = this.addService(hap.Service.Lightbulb, 'Ceiling Light');
    lightbulb.onGet('on', async () => this.fetchState());
    lightbulb.onSet('on', async (v) => this.applyState(v));
    await this.initialize({ lightbulb: { on: false, brightness: 100 } });
  }
}

Type Parameters

Type Parameter	Description
TContext extends UnknownContext	The accessory's custom context type (extends UnknownContext).
Services extends Interfaces[]	Tuple of HAP interface types for services this handler manages.

Constructors

Constructor

new AccessoryHandler<TContext, Services>(plugin, accessory): AccessoryHandler<TContext, Services>;

Defined in: packages/hap-fluent/src/AccessoryHandler.ts:440

Parameters

Parameter	Type	Description
plugin	DynamicPlatformPlugin	Homebridge platform plugin instance.
accessory	PlatformAccessory<TContext>	Platform accessory to manage.

Returns

AccessoryHandler<TContext, Services>

Properties

Property	Modifier	Type	Description	Defined in
accessory	readonly	PlatformAccessory<TContext>	Platform accessory to manage.	packages/hap-fluent/src/AccessoryHandler.ts:442
context	public	TContext	-	packages/hap-fluent/src/AccessoryHandler.ts:433
plugin	protected	DynamicPlatformPlugin	Homebridge platform plugin instance.	packages/hap-fluent/src/AccessoryHandler.ts:441
services	public	ServicesObject<Services>	-	packages/hap-fluent/src/AccessoryHandler.ts:434

Methods

addService()

addService<S>(
   serviceClass, 
   displayName?, 
subType?): FluentService<S>;

Defined in: packages/hap-fluent/src/AccessoryHandler.ts:457

Add or retrieve a service and wrap it with fluent helpers.

Type Parameters

Type Parameter
S extends typeof Service

Parameters

Parameter	Type	Description
serviceClass	WithUUID<S>	HAP service class constructor.
displayName?	string	Optional display name for the service.
subType?	string	Optional subtype identifier.

Returns

FluentService<S>

---

initialize()

initialize(initialState?): Promise<void>;

Defined in: packages/hap-fluent/src/AccessoryHandler.ts:470

Ensure services exist on the accessory and apply initial values.

Parameters

Parameter	Type	Description
initialState?	InternalServicesStateObject<Services>	Optional initial characteristic values.

Returns

Promise<void>