fix(client): Schedules specs can be empty (#1032)

Author: mjameswh

packages/client/src/schedule-client.ts

@@ -143,9 +143,6 @@ function assertRequiredScheduleOptions(
   if (action === 'CREATE' && !(opts as ScheduleOptions).scheduleId) {
     throw new TypeError(`Missing ${structureName}.scheduleId`);
   }
-  if (!(opts.spec.calendars?.length || opts.spec.intervals?.length || opts.spec.cronExpressions?.length)) {
-    throw new TypeError(`At least one ${structureName}.spec.calendars, .intervals or .cronExpressions is required`);
-  }
   switch (opts.action.type) {
     case 'startWorkflow':
       if (!opts.action.taskQueue) {
@@ -377,24 +374,22 @@ export class ScheduleClient extends BaseClient {
       );
 
       for (const raw of response.schedules ?? []) {
-        if (!raw.info?.spec) continue;
-
         yield <ScheduleSummary>{
           scheduleId: raw.scheduleId,
 
-          spec: decodeScheduleSpec(raw.info.spec),
-          action: {
+          spec: decodeScheduleSpec(raw.info?.spec ?? {}),
+          action: raw.info?.workflowType?.name && {
             type: 'startWorkflow',
-            workflowType: raw.info.workflowType?.name,
+            workflowType: raw.info.workflowType.name,
           },
           memo: await decodeMapFromPayloads(this.dataConverter, raw.memo?.fields),
           searchAttributes: decodeSearchAttributes(raw.searchAttributes),
           state: {
-            paused: raw.info.paused === true,
-            note: raw.info.notes ?? undefined,
+            paused: raw.info?.paused === true,
+            note: raw.info?.notes ?? undefined,
           },
           info: {
-            recentActions: decodeScheduleRecentActions(raw.info.recentActions),
+            recentActions: decodeScheduleRecentActions(raw.info?.recentActions),
             nextActionTimes: raw.info?.futureActionTimes?.map(tsToDate) ?? [],
           },
         };

packages/client/src/schedule-helpers.ts

@@ -24,7 +24,6 @@ import {
   optionalTsToMs,
   tsToDate,
 } from '@temporalio/common/lib/time';
-import { RequireAtLeastOne } from '@temporalio/common/src/type-helpers';
 import {
   CalendarSpec,
   CalendarSpecDescription,
@@ -300,9 +299,7 @@ export function encodeScheduleState(state?: ScheduleOptions['state']): temporal.
   };
 }
 
-export function decodeScheduleSpec(
-  pb: temporal.api.schedule.v1.IScheduleSpec
-): RequireAtLeastOne<ScheduleSpecDescription, 'calendars' | 'intervals'> {
+export function decodeScheduleSpec(pb: temporal.api.schedule.v1.IScheduleSpec): ScheduleSpecDescription {
   // Note: the server will have compiled calendar and cron_string fields into
   // structured_calendar (and maybe interval and timezone_name), so at this
   // point, we'll see only structured_calendar, interval, etc.

packages/client/src/schedule-types.ts

@@ -1,4 +1,4 @@
-import { checkExtends, Replace, RequireAtLeastOne } from '@temporalio/common/lib/type-helpers';
+import { checkExtends, Replace } from '@temporalio/common/lib/type-helpers';
 import { SearchAttributes, Workflow } from '@temporalio/common';
 import type { temporal } from '@temporalio/proto';
 import { WorkflowStartOptions } from './workflow-options';
@@ -19,7 +19,7 @@ export interface ScheduleOptions<A extends ScheduleOptionsAction = ScheduleOptio
   /**
    * When Actions should be taken
    */
-  spec: RequireAtLeastOne<ScheduleSpec, 'calendars' | 'intervals' | 'cronExpressions'>;
+  spec: ScheduleSpec;
 
   /**
    * Which Action to take
@@ -157,6 +157,9 @@ export type CompiledScheduleUpdateOptions = Replace<
 /**
  * A summary description of an existing Schedule, as returned by {@link ScheduleClient.list}.
  *
+ * Note that schedule listing is eventual consistent; some returned properties may therefore
+ * be undefined or incorrect for some time after creating or modifying a schedule.
+ *
  * @experimental
  */
 export interface ScheduleSummary {
@@ -168,12 +171,12 @@ export interface ScheduleSummary {
   /**
    * When will Actions be taken.
    */
-  spec: RequireAtLeastOne<ScheduleSpecDescription, 'calendars' | 'intervals'>;
+  spec?: ScheduleSpecDescription;
 
   /**
    * The Action that will be taken.
    */
-  action: ScheduleSummaryAction;
+  action?: ScheduleSummaryAction;
 
   /**
    * Additional non-indexed information attached to the Schedule.
@@ -187,7 +190,7 @@ export interface ScheduleSummary {
    *
    * Values are always converted using {@link JsonPayloadConverter}, even when a custom Data Converter is provided.
    */
-  searchAttributes: SearchAttributes;
+  searchAttributes?: SearchAttributes;
 
   state: {
     /**
@@ -249,7 +252,17 @@ export interface ScheduleExecutionStartWorkflowActionResult {
  *
  * @experimental
  */
-export type ScheduleDescription = ScheduleSummary & {
+export type ScheduleDescription = {
+  /**
+   * The Schedule Id. We recommend using a meaningful business identifier.
+   */
+  scheduleId: string;
+
+  /**
+   * When will Actions be taken.
+   */
+  spec: ScheduleSpecDescription;
+
   /**
    * The Action that will be taken.
    */
@@ -282,7 +295,32 @@ export type ScheduleDescription = ScheduleSummary & {
     pauseOnFailure: boolean;
   };
 
-  state: ScheduleSummary['state'] & {
+  /**
+   * Additional non-indexed information attached to the Schedule.
+   * The values can be anything that is serializable by the {@link DataConverter}.
+   */
+  memo?: Record<string, unknown>;
+
+  /**
+   * Additional indexed information attached to the Schedule.
+   * More info: https://docs.temporal.io/docs/typescript/search-attributes
+   *
+   * Values are always converted using {@link JsonPayloadConverter}, even when a custom Data Converter is provided.
+   */
+  searchAttributes: SearchAttributes;
+
+  state: {
+    /**
+     * Whether Schedule is currently paused.
+     */
+    paused: boolean;
+
+    /**
+     * Informative human-readable message with contextual notes, e.g. the reason a Schedule is paused.
+     * The system may overwrite this message on certain conditions, e.g. when pause-on-failure happens.
+     */
+    note?: string;
+
     /**
      * The Actions remaining in this Schedule.
      * Once this number hits `0`, no further Actions are taken (unless {@link ScheduleHandle.trigger} is called).
@@ -292,7 +330,17 @@ export type ScheduleDescription = ScheduleSummary & {
     remainingActions?: number;
   };
 
-  info: ScheduleSummary['info'] & {
+  info: {
+    /**
+     * Most recent 10 Actions started (including manual triggers), sorted from older start time to newer.
+     */
+    recentActions: ScheduleExecutionResult[];
+
+    /**
+     * Scheduled time of the next 10 executions of this Schedule
+     */
+    nextActionTimes: Date[];
+
     /**
      * Number of Actions taken so far.
      */
@@ -322,6 +370,9 @@ export type ScheduleDescription = ScheduleSummary & {
   raw: temporal.api.workflowservice.v1.IDescribeScheduleResponse;
 };
 
+// Invariant: ScheduleDescription contains at least the same fields as ScheduleSummary
+checkExtends<ScheduleSummary, ScheduleDescription>();
+
 // Invariant: An existing ScheduleDescription can be used as template to create a new Schedule
 checkExtends<ScheduleOptions, ScheduleDescription>();
 

packages/common/src/type-helpers.ts

@@ -12,11 +12,6 @@ export function checkExtends<_Orig, _Copy extends _Orig>(): void {
 
 export type Replace<Base, New> = Omit<Base, keyof New> & New;
 
-export type RequireAtLeastOne<Base, Keys extends keyof Base> = Omit<Base, Keys> &
-  {
-    [K in Keys]-?: Required<Pick<Base, K>> & Partial<Pick<Base, Exclude<Keys, K>>>;
-  }[Keys];
-
 export function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }

packages/test/src/test-schedules.ts

@@ -122,6 +122,29 @@ if (RUN_INTEGRATION_TESTS) {
     }
   });
 
+  test('Can create schedule without any spec', async (t) => {
+    const { client } = t.context;
+    const scheduleId = `can-create-schedule-without-any-spec-${randomUUID()}`;
+    const handle = await client.schedule.create({
+      scheduleId,
+      spec: {},
+      action: {
+        type: 'startWorkflow',
+        workflowType: dummyWorkflow,
+        taskQueue,
+      },
+    });
+
+    try {
+      const describedSchedule = await handle.describe();
+      t.deepEqual(describedSchedule.spec.calendars, []);
+      t.deepEqual(describedSchedule.spec.intervals, []);
+      t.deepEqual(describedSchedule.spec.skip, []);
+    } finally {
+      await handle.delete();
+    }
+  });
+
   test('Can create schedule with startWorkflow action (no arg)', async (t) => {
     const { client } = t.context;
     const scheduleId = `can-create-schedule-with-startWorkflow-action-${randomUUID()}`;

packages/worker/src/worker-options.ts

@@ -345,9 +345,7 @@ export type WorkerOptionsWithDefaults = WorkerOptions &
     /**
      * Controls the number of Worker threads the Worker should create.
      *
-     * Threads are used to create {@link https://nodejs.org/api/vm.html | vm }s for the
-     *
-     * isolated Workflow environment.
+     * Threads are used to create {@link https://nodejs.org/api/vm.html | vm }s for the isolated Workflow environment.
      *
      * New Workflows are created on this pool in a round-robin fashion.
      *