homebridge-plugin-utils 1.17.0 → 1.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/service.d.ts +54 -16
- package/dist/service.js +55 -17
- package/dist/service.js.map +1 -1
- package/package.json +2 -2
package/dist/service.d.ts
CHANGED
|
@@ -6,35 +6,73 @@
|
|
|
6
6
|
import type { HAP, PlatformAccessory, Service, WithUUID } from "homebridge";
|
|
7
7
|
import { type Nullable } from "./util.js";
|
|
8
8
|
/**
|
|
9
|
-
* Utility method that either creates a new service on an accessory
|
|
10
|
-
*
|
|
9
|
+
* Utility method that either creates a new service on an accessory if needed, or returns an existing one. Optionally, it executes a callback to initialize a new
|
|
10
|
+
* service instance. Additionally, the various name characteristics of the service are set to the specified name, and optionally added if necessary.
|
|
11
11
|
*
|
|
12
12
|
* @param hap - HAP instance associated with the Homebridge plugin.
|
|
13
|
-
* @param accessory - Homebridge accessory to check.
|
|
14
|
-
* @param serviceType -
|
|
13
|
+
* @param accessory - The Homebridge accessory to check or modify.
|
|
14
|
+
* @param serviceType - The type of service to instantiate or retrieve.
|
|
15
15
|
* @param name - Name to be displayed to the end user for this service.
|
|
16
|
-
* @param subtype -
|
|
17
|
-
* @param onServiceCreate -
|
|
16
|
+
* @param subtype - Optional service subtype to uniquely identify the service.
|
|
17
|
+
* @param onServiceCreate - Optional callback invoked only when a new service is created, receiving the new service as its argument.
|
|
18
18
|
*
|
|
19
|
-
* @returns Returns the created or retrieved service, `null`
|
|
19
|
+
* @returns Returns the created or retrieved service, or `null` if service creation failed.
|
|
20
20
|
*
|
|
21
|
-
* @remarks
|
|
21
|
+
* @remarks
|
|
22
|
+
* This method ensures that the service's display name and available name characteristics are updated to the specified name. If `onServiceCreate` is provided,
|
|
23
|
+
* it will only be called for newly created services, not for existing ones.
|
|
24
|
+
*
|
|
25
|
+
* The `ConfiguredName` and `Name` characteristics are conditionally added or updated based on the type of service, in accordance with HomeKit requirements.
|
|
26
|
+
*
|
|
27
|
+
* @example
|
|
28
|
+
* ```typescript
|
|
29
|
+
* // Example: Ensure a Lightbulb service exists with a user-friendly name, and initialize it if newly created.
|
|
30
|
+
* const lightbulbService = acquireService(hap, accessory, hap.Service.Lightbulb, "Living Room Lamp", undefined, (svc: Service): void => {
|
|
31
|
+
*
|
|
32
|
+
* // Called only if the service is newly created.
|
|
33
|
+
* svc.setCharacteristic(hap.Characteristic.On, false);
|
|
34
|
+
* });
|
|
35
|
+
*
|
|
36
|
+
* if(lightbulbService) {
|
|
37
|
+
*
|
|
38
|
+
* // Service is now available, with display name set and optional characteristics managed.
|
|
39
|
+
* lightbulbService.updateCharacteristic(hap.Characteristic.Brightness, 75);
|
|
40
|
+
* }
|
|
41
|
+
* ```
|
|
22
42
|
*
|
|
23
43
|
* @category Accessory
|
|
24
44
|
*/
|
|
25
45
|
export declare function acquireService(hap: HAP, accessory: PlatformAccessory, serviceType: WithUUID<typeof Service>, name: string, subtype?: string, onServiceCreate?: (svc: Service) => void): Nullable<Service>;
|
|
26
46
|
/**
|
|
27
|
-
*
|
|
47
|
+
* Validates whether a specific service should exist on the given accessory, removing the service if it fails validation.
|
|
48
|
+
*
|
|
49
|
+
* @param accessory - The Homebridge accessory to inspect and potentially modify.
|
|
50
|
+
* @param serviceType - The type of Homebridge service being checked or instantiated.
|
|
51
|
+
* @param validate - A boolean or a function that determines if the service should exist. If a function is provided, it receives a boolean indicating whether the
|
|
52
|
+
* service currently exists, and should return `true` to keep the service, or `false` to remove it.
|
|
53
|
+
* @param subtype - Optional service subtype to uniquely identify the service.
|
|
54
|
+
*
|
|
55
|
+
* @returns `true` if the service is valid (and kept), or `false` if it was removed.
|
|
56
|
+
*
|
|
57
|
+
* @remarks
|
|
58
|
+
* The `validate` parameter can be either:
|
|
59
|
+
* - a boolean (where `true` means keep the service, `false` means remove it).
|
|
60
|
+
* - a function (which is called with `hasService: boolean` and returns whether to keep the service).
|
|
61
|
+
*
|
|
62
|
+
* If the service should not exist according to `validate`, and it is currently present, this function will remove it from the accessory.
|
|
28
63
|
*
|
|
29
|
-
* @
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
64
|
+
* @example
|
|
65
|
+
* ```typescript
|
|
66
|
+
* // Remove a service if it exists
|
|
67
|
+
* validService(accessory, Service.Switch, false);
|
|
33
68
|
*
|
|
34
|
-
*
|
|
69
|
+
* // Only keep a service if a configuration flag is true
|
|
70
|
+
* validService(accessory, Service.Switch, config.enableSwitch);
|
|
35
71
|
*
|
|
36
|
-
*
|
|
72
|
+
* // Keep a service if it currently exists, or add it if a certain condition is met
|
|
73
|
+
* validService(accessory, Service.Switch, (hasService) => hasService || config.enableSwitch);
|
|
74
|
+
* ```
|
|
37
75
|
*
|
|
38
76
|
* @category Accessory
|
|
39
77
|
*/
|
|
40
|
-
export declare function validService(accessory: PlatformAccessory, serviceType: WithUUID<typeof Service>, validate: (hasService: boolean) => boolean, subtype?: string): boolean;
|
|
78
|
+
export declare function validService(accessory: PlatformAccessory, serviceType: WithUUID<typeof Service>, validate: boolean | ((hasService: boolean) => boolean), subtype?: string): boolean;
|
package/dist/service.js
CHANGED
|
@@ -4,19 +4,39 @@
|
|
|
4
4
|
*/
|
|
5
5
|
import { validateName } from "./util.js";
|
|
6
6
|
/**
|
|
7
|
-
* Utility method that either creates a new service on an accessory
|
|
8
|
-
*
|
|
7
|
+
* Utility method that either creates a new service on an accessory if needed, or returns an existing one. Optionally, it executes a callback to initialize a new
|
|
8
|
+
* service instance. Additionally, the various name characteristics of the service are set to the specified name, and optionally added if necessary.
|
|
9
9
|
*
|
|
10
10
|
* @param hap - HAP instance associated with the Homebridge plugin.
|
|
11
|
-
* @param accessory - Homebridge accessory to check.
|
|
12
|
-
* @param serviceType -
|
|
11
|
+
* @param accessory - The Homebridge accessory to check or modify.
|
|
12
|
+
* @param serviceType - The type of service to instantiate or retrieve.
|
|
13
13
|
* @param name - Name to be displayed to the end user for this service.
|
|
14
|
-
* @param subtype -
|
|
15
|
-
* @param onServiceCreate -
|
|
14
|
+
* @param subtype - Optional service subtype to uniquely identify the service.
|
|
15
|
+
* @param onServiceCreate - Optional callback invoked only when a new service is created, receiving the new service as its argument.
|
|
16
16
|
*
|
|
17
|
-
* @returns Returns the created or retrieved service, `null`
|
|
17
|
+
* @returns Returns the created or retrieved service, or `null` if service creation failed.
|
|
18
18
|
*
|
|
19
|
-
* @remarks
|
|
19
|
+
* @remarks
|
|
20
|
+
* This method ensures that the service's display name and available name characteristics are updated to the specified name. If `onServiceCreate` is provided,
|
|
21
|
+
* it will only be called for newly created services, not for existing ones.
|
|
22
|
+
*
|
|
23
|
+
* The `ConfiguredName` and `Name` characteristics are conditionally added or updated based on the type of service, in accordance with HomeKit requirements.
|
|
24
|
+
*
|
|
25
|
+
* @example
|
|
26
|
+
* ```typescript
|
|
27
|
+
* // Example: Ensure a Lightbulb service exists with a user-friendly name, and initialize it if newly created.
|
|
28
|
+
* const lightbulbService = acquireService(hap, accessory, hap.Service.Lightbulb, "Living Room Lamp", undefined, (svc: Service): void => {
|
|
29
|
+
*
|
|
30
|
+
* // Called only if the service is newly created.
|
|
31
|
+
* svc.setCharacteristic(hap.Characteristic.On, false);
|
|
32
|
+
* });
|
|
33
|
+
*
|
|
34
|
+
* if(lightbulbService) {
|
|
35
|
+
*
|
|
36
|
+
* // Service is now available, with display name set and optional characteristics managed.
|
|
37
|
+
* lightbulbService.updateCharacteristic(hap.Characteristic.Brightness, 75);
|
|
38
|
+
* }
|
|
39
|
+
* ```
|
|
20
40
|
*
|
|
21
41
|
* @category Accessory
|
|
22
42
|
*/
|
|
@@ -72,24 +92,42 @@ export function acquireService(hap, accessory, serviceType, name, subtype, onSer
|
|
|
72
92
|
return service;
|
|
73
93
|
}
|
|
74
94
|
/**
|
|
75
|
-
*
|
|
95
|
+
* Validates whether a specific service should exist on the given accessory, removing the service if it fails validation.
|
|
76
96
|
*
|
|
77
|
-
* @param accessory
|
|
78
|
-
* @param serviceType
|
|
79
|
-
* @param validate
|
|
80
|
-
*
|
|
97
|
+
* @param accessory - The Homebridge accessory to inspect and potentially modify.
|
|
98
|
+
* @param serviceType - The type of Homebridge service being checked or instantiated.
|
|
99
|
+
* @param validate - A boolean or a function that determines if the service should exist. If a function is provided, it receives a boolean indicating whether the
|
|
100
|
+
* service currently exists, and should return `true` to keep the service, or `false` to remove it.
|
|
101
|
+
* @param subtype - Optional service subtype to uniquely identify the service.
|
|
81
102
|
*
|
|
82
|
-
* @returns
|
|
103
|
+
* @returns `true` if the service is valid (and kept), or `false` if it was removed.
|
|
83
104
|
*
|
|
84
|
-
* @remarks
|
|
105
|
+
* @remarks
|
|
106
|
+
* The `validate` parameter can be either:
|
|
107
|
+
* - a boolean (where `true` means keep the service, `false` means remove it).
|
|
108
|
+
* - a function (which is called with `hasService: boolean` and returns whether to keep the service).
|
|
109
|
+
*
|
|
110
|
+
* If the service should not exist according to `validate`, and it is currently present, this function will remove it from the accessory.
|
|
111
|
+
*
|
|
112
|
+
* @example
|
|
113
|
+
* ```typescript
|
|
114
|
+
* // Remove a service if it exists
|
|
115
|
+
* validService(accessory, Service.Switch, false);
|
|
116
|
+
*
|
|
117
|
+
* // Only keep a service if a configuration flag is true
|
|
118
|
+
* validService(accessory, Service.Switch, config.enableSwitch);
|
|
119
|
+
*
|
|
120
|
+
* // Keep a service if it currently exists, or add it if a certain condition is met
|
|
121
|
+
* validService(accessory, Service.Switch, (hasService) => hasService || config.enableSwitch);
|
|
122
|
+
* ```
|
|
85
123
|
*
|
|
86
124
|
* @category Accessory
|
|
87
125
|
*/
|
|
88
126
|
export function validService(accessory, serviceType, validate, subtype) {
|
|
89
|
-
// Find the
|
|
127
|
+
// Find the service, if it exists.
|
|
90
128
|
const service = subtype ? accessory.getServiceById(serviceType, subtype) : accessory.getService(serviceType);
|
|
91
129
|
// Validate whether we should have the service. If not, remove it.
|
|
92
|
-
if (!validate(!!service)) {
|
|
130
|
+
if (!((typeof validate === "function") ? validate(!!service) : validate)) {
|
|
93
131
|
if (service) {
|
|
94
132
|
accessory.removeService(service);
|
|
95
133
|
}
|
package/dist/service.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,EAAiB,YAAY,EAAE,MAAM,WAAW,CAAC;AAExD
|
|
1
|
+
{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "homebridge-plugin-utils",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.18.0",
|
|
4
4
|
"displayName": "Homebridge Plugin Utilities",
|
|
5
5
|
"description": "Opinionated utilities to provide common capabilities and create rich configuration webUI experiences for Homebridge plugins.",
|
|
6
6
|
"author": {
|
|
@@ -46,7 +46,7 @@
|
|
|
46
46
|
"eslint": "^9.27.0",
|
|
47
47
|
"homebridge": "1.9.0",
|
|
48
48
|
"shx": "0.4.0",
|
|
49
|
-
"typedoc": "0.28.
|
|
49
|
+
"typedoc": "0.28.5",
|
|
50
50
|
"typedoc-plugin-markdown": "4.6.3",
|
|
51
51
|
"typescript": "5.8.3",
|
|
52
52
|
"typescript-eslint": "^8.32.1"
|