rename to createScheduledTaskRunner

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

.changeset/new-books-protect.md

@@ -21,7 +21,7 @@ All things said, a typical setup might now look as follows:
 +      id: 'our-ldap-master',
 +      target: 'ldaps://ds.example.net',
 +      logger: env.logger,
-+      schedule: env.scheduler.createTaskSchedule({
++      schedule: env.scheduler.createScheduledTaskRunner({
 +        frequency: Duration.fromObject({ minutes: 60 }),
 +        timeout: Duration.fromObject({ minutes: 15 }),
 +      }),

docs/integrations/ldap/org.md

@@ -49,7 +49,7 @@ schedule it:
 +      id: 'our-ldap-master',
 +      target: 'ldaps://ds.example.net',
 +      logger: env.logger,
-+      schedule: env.scheduler.createTaskSchedule({
++      schedule: env.scheduler.createScheduledTaskRunner({
 +        frequency: Duration.fromObject({ minutes: 60 }),
 +        timeout: Duration.fromObject({ minutes: 15 }),
 +      }),

packages/backend-tasks/api-report.md

@@ -11,7 +11,7 @@ import { Logger } from 'winston';
 
 // @public
 export interface PluginTaskScheduler {
-  createTaskSchedule(schedule: TaskScheduleDefinition): TaskSchedule;
+  createScheduledTaskRunner(schedule: TaskScheduleDefinition): TaskRunner;
   scheduleTask(
     task: TaskScheduleDefinition & TaskInvocationDefinition,
   ): Promise<void>;
@@ -30,7 +30,7 @@ export interface TaskInvocationDefinition {
 }
 
 // @public
-export interface TaskSchedule {
+export interface TaskRunner {
   run(task: TaskInvocationDefinition): Promise<void>;
 }
 

packages/backend-tasks/src/tasks/PluginTaskSchedulerImpl.test.ts

@@ -62,7 +62,7 @@ describe('PluginTaskManagerImpl', () => {
 
   // This is just to test the wrapper code; most of the actual tests are in
   // TaskWorker.test.ts
-  describe('createTaskSchedule', () => {
+  describe('createScheduledTaskRunner', () => {
     it.each(databases.eachSupportedId())(
       'can run the happy path, %p',
       async databaseId => {
@@ -70,7 +70,7 @@ describe('PluginTaskManagerImpl', () => {
 
         const fn = jest.fn();
         await manager
-          .createTaskSchedule({
+          .createScheduledTaskRunner({
             timeout: Duration.fromMillis(5000),
             frequency: Duration.fromMillis(5000),
           })

packages/backend-tasks/src/tasks/PluginTaskSchedulerImpl.ts

@@ -20,7 +20,7 @@ import { TaskWorker } from './TaskWorker';
 import {
   PluginTaskScheduler,
   TaskInvocationDefinition,
-  TaskSchedule,
+  TaskRunner,
   TaskScheduleDefinition,
 } from './types';
 import { validateId } from './util';
@@ -55,7 +55,7 @@ export class PluginTaskSchedulerImpl implements PluginTaskScheduler {
     );
   }
 
-  createTaskSchedule(schedule: TaskScheduleDefinition): TaskSchedule {
+  createScheduledTaskRunner(schedule: TaskScheduleDefinition): TaskRunner {
     return {
       run: async task => {
         await this.scheduleTask({ ...task, ...schedule });

packages/backend-tasks/src/tasks/index.ts

@@ -19,6 +19,6 @@ export type {
   PluginTaskScheduler,
   TaskFunction,
   TaskInvocationDefinition,
-  TaskSchedule,
+  TaskRunner,
   TaskScheduleDefinition,
 } from './types';

packages/backend-tasks/src/tasks/types.ts

@@ -103,7 +103,7 @@ export interface TaskInvocationDefinition {
  *
  * @public
  */
-export interface TaskSchedule {
+export interface TaskRunner {
   /**
    * Takes the schedule and executes an actual task using it.
    *
@@ -136,7 +136,8 @@ export interface PluginTaskScheduler {
   ): Promise<void>;
 
   /**
-   * Creates a task schedule, ready to be invoked at a later time.
+   * Creates a scheduled but dormant recurring task, ready to be launched at a
+   * later time.
    *
    * @remarks
    *
@@ -146,7 +147,7 @@ export interface PluginTaskScheduler {
    *
    * @param schedule - The task schedule
    */
-  createTaskSchedule(schedule: TaskScheduleDefinition): TaskSchedule;
+  createScheduledTaskRunner(schedule: TaskScheduleDefinition): TaskRunner;
 }
 
 function isValidOptionalDurationString(d: string | undefined): boolean {

plugins/catalog-backend-module-ldap/api-report.md

@@ -15,7 +15,7 @@ import { LocationSpec } from '@backstage/plugin-catalog-backend';
 import { Logger } from 'winston';
 import { SearchEntry } from 'ldapjs';
 import { SearchOptions } from 'ldapjs';
-import { TaskSchedule } from '@backstage/backend-tasks';
+import { TaskRunner } from '@backstage/backend-tasks';
 import { UserEntity } from '@backstage/catalog-model';
 
 // @public
@@ -119,7 +119,7 @@ export interface LdapOrgEntityProviderOptions {
   groupTransformer?: GroupTransformer;
   id: string;
   logger: Logger;
-  schedule: 'manual' | TaskSchedule;
+  schedule: 'manual' | TaskRunner;
   target: string;
   userTransformer?: UserTransformer;
 }

plugins/catalog-backend-module-ldap/src/processors/LdapOrgEntityProvider.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { TaskSchedule } from '@backstage/backend-tasks';
+import { TaskRunner } from '@backstage/backend-tasks';
 import {
   ANNOTATION_LOCATION,
   ANNOTATION_ORIGIN_LOCATION,
@@ -69,11 +69,16 @@ export interface LdapOrgEntityProviderOptions {
   /**
    * The refresh schedule to use.
    *
-   * If you pass in 'manual', you are responsible for calling the `read`
-   * method manually at some interval. If not, it will be automatically
-   * called regularly with the given schedule using the scheduler.
+   * @remarks
+   *
+   * If you pass in 'manual', you are responsible for calling the `read` method
+   * manually at some interval.
+   *
+   * But more commonly you will pass in the result of
+   * {@link @backstage/backend-tasks#PluginTaskScheduler.createScheduledTaskRunner}
+   * to enable automatic scheduling of tasks.
    */
-  schedule: 'manual' | TaskSchedule;
+  schedule: 'manual' | TaskRunner;
 
   /**
    * The function that transforms a user entry in LDAP to an entity.