[triggers] Support offset param for DateTimeTrigger

src/triggers.js

@@ -264,14 +264,23 @@ const TimeOfDayTrigger = (time, triggerName) =>
  *
  * @memberof triggers
  * @param {Item|string} itemOrName the {@link Item} or the name of the Item to monitor for change
- * @param {boolean} [timeOnly=false] Specifies whether only the time of the Item should be compared or the date and time.
+ * @param {boolean} [timeOnly=false] Specifies whether only the time of the DateTime Item should be compared or the date and time.
+ * @param {number} [offset=0] The offset in seconds to add to the time of the DateTime Item
  * @param {string} [triggerName] the optional name of the trigger to create
  */
-const DateTimeTrigger = (itemOrName, timeOnly = false, triggerName) =>
-  _createTrigger('timer.DateTimeTrigger', triggerName, {
+const DateTimeTrigger = (itemOrName, timeOnly = false, offset = 0, triggerName) => {
+  // backward compatibility for (itemOrName, timeOnly, triggerName) signature:
+  if (typeof offset === 'string') {
+    triggerName = offset;
+    offset = 0;
+    console.warn('The signature DateTimeTrigger(itemOrName, timeOnly, triggerName) is deprecated. Please use DateTimeTrigger(itemOrName, timeOnly, offset, triggerName) instead.');
+  }
+  return _createTrigger('timer.DateTimeTrigger', triggerName, {
     itemName: _isItem(itemOrName) ? itemOrName.name : itemOrName,
-    timeOnly
+    timeOnly,
+    offset
   });
+};
 
 /**
  * Creates a trigger that fires upon a matching event from the event bus.

test/triggers.spec.js

@@ -27,12 +27,14 @@ jest.mock('../src/items', () => ({
 }));
 const Item = require('../src/items').Item;
 
+console.warn = jest.fn();
+
 describe('triggers.js', () => {
   const moduleBuilderSpy = new ModuleBuilder();
   moduleBuilderSpy.build.mockImplementation(() => new Object()); // eslint-disable-line no-new-object
   ModuleBuilder.createTrigger.mockImplementation(() => moduleBuilderSpy);
 
-  it('use random UUID if no trigger name is specified.', () => {
+  it('uses random UUID if no trigger name is specified.', () => {
     const uuid = 'random UUID';
     jest.spyOn(UUID, 'randomUUID').mockImplementation(() => uuid);
     ItemCommandTrigger('itemName', 'command');
@@ -296,10 +298,27 @@ describe('triggers.js', () => {
   describe('DateTimeTrigger', () => {
     const itemName = 'itemName';
     const timeOnly = true;
+    const offset = 60;
     const triggerName = 'triggerName';
     const item = new Item(itemName);
 
-    it.each([[itemName], [item]])('creates trigger from %s.', (groupOrName) => {
+    it.each([[itemName], [item]])('creates trigger from %s.', (itemOrName) => {
+      const trigger = DateTimeTrigger(itemOrName, timeOnly, offset, triggerName);
+
+      expect(trigger).not.toBe(undefined);
+      expect(moduleBuilderSpy.withTypeUID).toHaveBeenCalledWith(
+        'timer.DateTimeTrigger'
+      );
+      expect(moduleBuilderSpy.withId).toHaveBeenCalledWith(triggerName);
+      expect(moduleBuilderSpy.withConfiguration).toHaveBeenCalledWith(
+        expect.objectContaining({
+          config: { itemName, timeOnly, offset }
+        })
+      );
+    });
+
+    // test backward compatibility for (itemOrName, timeOnly, triggerName) signature:
+    it('provides backward compatibility for old param signature and logs deprecation warning.', () => {
       const trigger = DateTimeTrigger(itemName, timeOnly, triggerName);
 
       expect(trigger).not.toBe(undefined);
@@ -309,9 +328,10 @@ describe('triggers.js', () => {
       expect(moduleBuilderSpy.withId).toHaveBeenCalledWith(triggerName);
       expect(moduleBuilderSpy.withConfiguration).toHaveBeenCalledWith(
         expect.objectContaining({
-          config: { itemName, timeOnly }
+          config: { itemName, timeOnly, offset: 0 }
         })
       );
+      expect(console.warn).toHaveBeenCalled();
     });
   });
 

types/triggers.d.ts

@@ -224,10 +224,11 @@ export function TimeOfDayTrigger(time: string, triggerName?: string): HostTrigge
  *
  * @memberof triggers
  * @param {Item|string} itemOrName the {@link Item} or the name of the Item to monitor for change
- * @param {boolean} [timeOnly=false] Specifies whether only the time of the Item should be compared or the date and time.
+ * @param {boolean} [timeOnly=false] Specifies whether only the time of the DateTime Item should be compared or the date and time.
+ * @param {number} [offset=0] The offset in seconds to add to the time of the DateTime Item
  * @param {string} [triggerName] the optional name of the trigger to create
  */
-export function DateTimeTrigger(itemOrName: Item | string, timeOnly?: boolean, triggerName?: string): HostTrigger;
+export function DateTimeTrigger(itemOrName: Item | string, timeOnly?: boolean, offset?: number, triggerName?: string): HostTrigger;
 /**
  * Creates a trigger for the {@link https://openhab.org/addons/automation/pwm/ Pulse Width Modulation (PWM) Automation} add-on.
  *