[manager] Destructure scheduleTestRun

Author: jamesgpearce

src/@types/docs.js

@@ -959,6 +959,35 @@
    * @since v1.0.0
    */
   /// Manager.scheduleTaskRun
+  /**
+   * When called with an object as the first argument, the scheduleTaskRun
+   * method destructures it to make it easier to skip optional parameters.
+   * @param args An object containing the Id of the task to run, an optional
+   * string argument to pass to the Task, an optional timestamp at, or duration
+   * after which, the task should run; and an optional TaskRunConfig to set for
+   * this run.
+   * @returns A new unique Id of the scheduled task run, or `undefined` if
+   * unsuccessful.
+   * @example
+   * This example registers a task that is then scheduled to run.
+   *
+   * ```js
+   * import {createManager} from 'tinytick';
+   *
+   * const manager = createManager();
+   * manager.setTask('ping', async () => await fetch('https://example.org'));
+   *
+   * const taskRunId = manager.scheduleTaskRun({taskId: 'ping', startAfter: 1});
+   * console.log(manager.getScheduledTaskRunIds().length);
+   * // -> 1
+   *
+   * console.log(manager.getTaskRunInfo(taskRunId).taskId);
+   * // -> 'ping'
+   * ```
+   * @category TaskRun
+   * @since v1.2.5
+   */
+  /// Manager.scheduleTaskRun.2
   /**
    * The getTaskRunConfig method returns the configuration of a task run.
    *

src/@types/index.d.ts

@@ -195,6 +195,14 @@ export interface Manager {
     config?: TaskRunConfig,
   ): Id | undefined;
 
+  /// Manager.scheduleTaskRun.2
+  scheduleTaskRun(args: {
+    taskId: Id;
+    arg?: string;
+    startAfter?: TimestampMs | DurationMs;
+    config?: TaskRunConfig;
+  }): Id | undefined;
+
   /// Manager.getTaskRunConfig
   getTaskRunConfig<WithDefaults extends boolean>(
     taskRunId: Id,

src/@types/ui-react/docs.js

@@ -582,6 +582,53 @@
  * @since v1.2.1
  */
 /// useScheduleTaskRun
+/**
+ * When called with an object as the first argument, the useScheduleTaskRun
+ * hook destructures it to make it easier to skip optional parameters.
+ * @param args An object containing the Id of the task to run, an optional
+ * string argument to pass to the Task, an optional timestamp at, or duration
+ * after which, the task should run; and an optional TaskRunConfig to set for
+ * this run.
+ * @param configDeps An optional array of dependencies for the config object,
+ * which, if any change, result in the task being scheduled again. Defaults to
+ * an empty array.
+ * @returns The new unique Id of the scheduled task run, or `undefined` if
+ * unsuccessful.
+ * @example
+ * This example shows how to use the useScheduleTaskRun hook within a
+ * component that's nested inside a Provider. The hook is used to create a
+ * callback that will schedule a task in response to a click event.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createManager} from 'tinytick';
+ * import {Provider, useScheduleTaskRun} from 'tinytick/ui-react';
+ *
+ * const Pane = () => {
+ *   useScheduleTaskRun({taskId: 'log'});
+ *   return null;
+ * };
+ * const App = ({manager}) => (
+ *   <Provider manager={manager}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ *
+ * const manager = createManager().start();
+ * manager.setTask('log', async () => console.log('Task ran'));
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App manager={manager} />); // !act
+ *
+ * // ... wait 100ms for task to start running // !act
+ * // -> 'Task ran'
+ * ```
+ * @category Task run hooks
+ * @since v1.2.5
+ */
+/// useScheduleTaskRun.2
 
 /**
  * The useScheduleTaskRunCallback hook returns a function that can be used to
@@ -653,6 +700,65 @@
  * @since v1.2.0
  */
 /// useScheduleTaskRunCallback
+/**
+ * When called with an object as the first argument, the
+ * useScheduleTaskRunCallback hook destructures it to make it easier to skip
+ * optional parameters.
+ * @param args An object containing the Id of the task to run, an optional
+ * string argument to pass to the Task, an optional timestamp at, or duration
+ * after which, the task should run; and an optional TaskRunConfig to set for
+ * this run.
+ * @param configDeps An optional array of dependencies for the config object,
+ * which, if any change, result in the callback being regenerated. Defaults to
+ * an empty array.
+ * @returns A callback that will return the new unique Id of the scheduled task
+ * run, or `undefined` if unsuccessful.
+ * @example
+ * This example shows how to use the useScheduleTaskRunCallback hook within a
+ * component that's nested inside a Provider. The hook is used to create a
+ * callback that will schedule a task in response to a click event.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createManager} from 'tinytick';
+ * import {Provider, useScheduleTaskRunCallback} from 'tinytick/ui-react';
+ *
+ * const Pane = () => {
+ *   const handleClick = useScheduleTaskRunCallback({taskId: 'log'});
+ *   return (
+ *     <span id="span" onClick={handleClick}>
+ *       Log
+ *     </span>
+ *   );
+ * };
+ * const App = ({manager}) => (
+ *   <Provider manager={manager}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ *
+ * const manager = createManager().start();
+ * manager.setTask('log', async () => console.log('Task ran'));
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App manager={manager} />); // !act
+ * const span = app.querySelector('span');
+ *
+ * console.log(span.innerHTML);
+ * // -> 'Log'
+ *
+ * // User clicks the <span> element:
+ * // -> span MouseEvent('click', {bubbles: true})
+ *
+ * // ... wait 100ms for task to start running // !act
+ * // -> 'Task ran'
+ * ```
+ * @category Task run hooks
+ * @since v1.2.5
+ */
+/// useScheduleTaskRunCallback.2
 
 /**
  * ProviderProps props are used with the Manager component, so that a TinyTick

src/@types/ui-react/index.d.ts

@@ -57,6 +57,17 @@ export function useScheduleTaskRun(
   configDeps?: DependencyList,
 ): Id | undefined;
 
+/// useScheduleTaskRun.2
+export function useScheduleTaskRun(
+  args: {
+    taskId: Id;
+    arg?: string;
+    startAfter?: TimestampMs | DurationMs;
+    config?: TaskRunConfig;
+  },
+  configDeps?: DependencyList,
+): Id | undefined;
+
 /// useScheduleTaskRunCallback
 export function useScheduleTaskRunCallback(
   taskId: Id,
@@ -66,6 +77,17 @@ export function useScheduleTaskRunCallback(
   configDeps?: DependencyList,
 ): () => Id | undefined;
 
+/// useScheduleTaskRunCallback.2
+export function useScheduleTaskRunCallback(
+  args: {
+    taskId: Id;
+    arg?: string;
+    startAfter?: TimestampMs | DurationMs;
+    config?: TaskRunConfig;
+  },
+  configDeps?: DependencyList,
+): () => Id | undefined;
+
 /// ProviderProps
 export type ProviderProps = {
   /// ProviderProps.manager

src/common/obj.ts

@@ -10,7 +10,14 @@ const objFrozen = object.isFrozen;
 
 const objEntries = object.entries;
 
-const isObject = (obj: unknown): boolean =>
+const objDel = <Value>(obj: IdObj<Value>, id: Id): IdObj<Value> => {
+  delete obj[id];
+  return obj;
+};
+
+export type IdObj<Value> = {[id: string]: Value};
+
+export const isObject = (obj: unknown): obj is IdObj<unknown> =>
   !isUndefined(obj) &&
   (ifNotUndefined(
     getPrototypeOf(obj),
@@ -21,13 +28,6 @@ const isObject = (obj: unknown): boolean =>
     () => true,
   ) as boolean);
 
-const objDel = <Value>(obj: IdObj<Value>, id: Id): IdObj<Value> => {
-  delete obj[id];
-  return obj;
-};
-
-export type IdObj<Value> = {[id: string]: Value};
-
 export const objFreeze = object.freeze;
 
 export const objForEach = <Value>(

src/index.ts

@@ -41,6 +41,7 @@ import {
   mapToObj,
 } from './common/map.ts';
 import {
+  isObject,
   objFilterUndefined,
   objForEach,
   objFreeze,
@@ -616,18 +617,33 @@ export const createManager: typeof createManagerDecl = (): Manager => {
     fluent((taskId) => mapSet(taskMap, taskId), taskId);
 
   const scheduleTaskRun = (
-    taskId: Id,
+    taskIdOrArgs:
+      | Id
+      | {
+          taskId: Id;
+          arg?: string;
+          startAfter?: TimestampMs | DurationMs;
+          config?: TaskRunConfig;
+        },
     arg?: string,
     startAfter: TimestampMs | DurationMs = 0,
     config: TaskRunConfig = {},
   ): Id | undefined => {
     if (status == ManagerStatusValues.Stopping) {
       return undefined;
     }
+    if (isObject(taskIdOrArgs)) {
+      return scheduleTaskRun(
+        taskIdOrArgs.taskId,
+        taskIdOrArgs.arg,
+        taskIdOrArgs.startAfter,
+        taskIdOrArgs.config,
+      );
+    }
     const taskRunId = getUniqueId();
     const startTimestamp = normalizeTimestamp(startAfter);
     mapSet(taskRunMap, taskRunId, [
-      id(taskId),
+      id(taskIdOrArgs),
       arg,
       startTimestamp,
       validatedTestRunConfig(config),
@@ -637,7 +653,7 @@ export const createManager: typeof createManagerDecl = (): Manager => {
     ]);
     insertTaskRunPointer(
       TaskRunState.Scheduled,
-      id(taskId),
+      id(taskIdOrArgs),
       taskRunId,
       startTimestamp,
       TaskRunReasonValues.Scheduled,

src/ui-react/hooks.ts

@@ -29,6 +29,7 @@ import type {
   useTaskRunRunning as useTaskRunRunningDecl,
 } from '../@types/ui-react/index.d.ts';
 import {arrayIsEqual} from '../common/array.ts';
+import {isObject} from '../common/obj.ts';
 import {isUndefined} from '../common/other.ts';
 import {Context} from './context.ts';
 
@@ -79,6 +80,28 @@ const addAndDelListener = (thing: any, listenable: string, ...args: any[]) => {
   return () => thing?.delListener?.(listenerId);
 };
 
+const useScheduleTaskRunImpl = (
+  args: [taskId: Id, arg?: string, startAfter?: TimestampMs | DurationMs],
+  config?: TaskRunConfig,
+  configDeps: DependencyList = EMPTY_ARRAY,
+) => {
+  const callback = useScheduleTaskRunCallbackImpl(args, config, configDeps);
+  return useMemo(callback, [callback]);
+};
+
+const useScheduleTaskRunCallbackImpl = (
+  args: [taskId: Id, arg?: string, startAfter?: TimestampMs | DurationMs],
+  config?: TaskRunConfig,
+  configDeps: DependencyList = EMPTY_ARRAY,
+) => {
+  const manager = useManager();
+  return useCallback(
+    () => manager?.scheduleTaskRun(...args, config),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [manager, ...args, ...configDeps],
+  );
+};
+
 export const useCreateManager: typeof useCreateManagerDecl = (
   create: () => Manager,
   createDeps: DependencyList = EMPTY_ARRAY,
@@ -134,34 +157,50 @@ export const useSetTask: typeof useSetTaskDecl = (
 };
 
 export const useScheduleTaskRun: typeof useScheduleTaskRunDecl = (
-  taskId: Id,
-  arg?: string,
+  taskIdOrArgs:
+    | Id
+    | {
+        taskId?: Id;
+        arg?: string;
+        startAfter?: TimestampMs | DurationMs;
+        config?: TaskRunConfig;
+      },
+  argOrConfigDeps?: string | DependencyList,
   startAfter?: TimestampMs | DurationMs,
   config?: TaskRunConfig,
-  configDeps: DependencyList = EMPTY_ARRAY,
-) => {
-  const callback = useScheduleTaskRunCallback(
-    taskId,
-    arg,
-    startAfter,
-    config,
-    configDeps,
+  configDeps?: DependencyList,
+) =>
+  (useScheduleTaskRunImpl as any)(
+    ...(isObject(taskIdOrArgs)
+      ? [
+          [taskIdOrArgs.taskId, taskIdOrArgs.arg, taskIdOrArgs.startAfter],
+          taskIdOrArgs.config,
+          argOrConfigDeps,
+        ]
+      : [[taskIdOrArgs, argOrConfigDeps, startAfter], config, configDeps]),
   );
-  return useMemo(callback, [callback]);
-};
 
 export const useScheduleTaskRunCallback: typeof useScheduleTaskRunCallbackDecl =
   (
-    taskId: Id,
-    arg?: string,
+    taskIdOrArgs:
+      | Id
+      | {
+          taskId?: Id;
+          arg?: string;
+          startAfter?: TimestampMs | DurationMs;
+          config?: TaskRunConfig;
+        },
+    argOrConfigDeps?: string | DependencyList,
     startAfter?: TimestampMs | DurationMs,
     config?: TaskRunConfig,
-    configDeps: DependencyList = EMPTY_ARRAY,
-  ) => {
-    const manager = useManager();
-    return useCallback(
-      () => manager?.scheduleTaskRun(taskId, arg, startAfter, config),
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-      [manager, taskId, arg, startAfter, ...configDeps],
+    configDeps?: DependencyList,
+  ) =>
+    (useScheduleTaskRunCallbackImpl as any)(
+      ...(isObject(taskIdOrArgs)
+        ? [
+            [taskIdOrArgs.taskId, taskIdOrArgs.arg, taskIdOrArgs.startAfter],
+            taskIdOrArgs.config,
+            argOrConfigDeps,
+          ]
+        : [[taskIdOrArgs, argOrConfigDeps, startAfter], config, configDeps]),
     );
-  };