zitejs 0.9.145 → 0.9.147

package/dist/cjs/backend/index.d.ts

@@ -116,11 +116,11 @@ export type ZiteDatabaseTriggerInput<TRecord extends Record<string, unknown> = R
     event: ZiteDatabaseTriggerEvent;
     table: string;
     recordId: string;
-    /** Null if it was deleted before the run read it; on `"deleted"`, the record as it was. */
+    /** Null on `"deleted"`, which leaves only `recordId`, and if it was deleted before the run read it. */
     record: TRecord | null;
     /** The record before an `"updated"`; null otherwise, and on a very large bulk write. */
     previous: TRecord | null;
-    /** What an `"updated"` changed. */
+    /** What an `"updated"` changed; on a very large bulk write, what the write changed across its records. */
     changedFields: string[];
 };
 /**
@@ -307,7 +307,9 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
          * its result is saved before anything after it executes, and when a
          * failed run is resumed, completed steps return their saved results
          * instead of re-running their side effects. Names must be unique within
-         * a run, and results must be plain JSON data under 256KB.
+         * a run, and results must be plain JSON data under 256KB. In a run
+         * fired by a schedule, webhook or trigger, `step.sleep` pauses the run
+         * and a failed step is tried again.
          */
         step: ZiteStep;
         context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : TTrigger extends ZiteTrigger ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;
@@ -326,8 +328,32 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
  * it would matter, and give a step inside a loop the item's id in its name.
  */
 export interface ZiteStep {
-    run<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * In a run fired by a schedule, webhook or trigger, a step that throws is
+     * tried again `retries` more times (default 3, at most 10), 30 seconds,
+     * 2 minutes, then 10 minutes apart. Elsewhere its error fails the request.
+     */
+    run<T>(name: string, fn: () => Promise<T> | T, options?: ZiteStepOptions): Promise<T>;
+    /**
+     * Pause the run for `duration`: `"30s"`, `"15m"`, `"2h"`, `"3d"`, `"1w"`,
+     * or milliseconds, at most 30 days. Only a run fired by a schedule, webhook
+     * or trigger can wait; an editor test run goes straight past, and a request
+     * from the app throws.
+     *
+     * The run continues in a later call, which runs `execute` again from the
+     * top: finished steps return their saved results, and code outside a step
+     * runs again, so keep side effects inside steps.
+     */
+    sleep(name: string, duration: ZiteStepDuration): Promise<void>;
+    /** Pause the run until `when`, at most 30 days ahead. See {@link ZiteStep.sleep}. */
+    sleepUntil(name: string, when: Date | string): Promise<void>;
+}
+export interface ZiteStepOptions {
+    /** How many more times to try the step after it throws: 0 to 10, default 3. */
+    retries?: number;
 }
+/** Milliseconds, or a number with a unit: `ms`, `s`, `m`, `h`, `d` or `w`. */
+export type ZiteStepDuration = number | `${number}${"ms" | "s" | "m" | "h" | "d" | "w"}`;
 /**
  * Create an endpoint definition, parsing `input` against `inputSchema` before
  * `execute` runs. Nothing downstream parses it — the worker calls `execute` on

package/dist/cjs/backend/index.test.js

@@ -8,6 +8,8 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
 // Direct execute() calls need the step surface the runtime always provides.
 const stepStub = {
     run: async (_name, fn) => await fn(),
+    sleep: async () => { },
+    sleepUntil: async () => { },
 };
 (0, vitest_1.afterEach)(() => {
     vitest_1.vi.unstubAllGlobals();

package/dist/cjs/sync/lib.js

@@ -1331,7 +1331,7 @@ function generateBackendWrapperTs(envVarNames = []) {
         "  execute: (",
         "    params: {",
         "      input: ZiteEndpointInput<TInput, TTrigger>;",
-        "      /** Durable steps: step.run(name, fn) runs fn once per logical run — its result is saved before anything after it executes, and a resumed run replays completed steps from their saved results. Provided by the platform; never define a local stand-in. */",
+        "      /** Durable steps: step.run(name, fn) runs fn once per logical run — its result is saved before anything after it executes, and a resumed run replays completed steps from their saved results. In a run fired by a schedule, webhook or trigger, step.sleep(name, \"2d\") pauses the run and a failed step is tried again. Provided by the platform; never define a local stand-in. */",
         "      step: ZiteStep;",
         "      context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : TTrigger extends ZiteTrigger ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;",
         // Mirrors the base module: a trigger's run gets `trigger`.

package/dist/esm/backend/index.d.ts

@@ -116,11 +116,11 @@ export type ZiteDatabaseTriggerInput<TRecord extends Record<string, unknown> = R
     event: ZiteDatabaseTriggerEvent;
     table: string;
     recordId: string;
-    /** Null if it was deleted before the run read it; on `"deleted"`, the record as it was. */
+    /** Null on `"deleted"`, which leaves only `recordId`, and if it was deleted before the run read it. */
     record: TRecord | null;
     /** The record before an `"updated"`; null otherwise, and on a very large bulk write. */
     previous: TRecord | null;
-    /** What an `"updated"` changed. */
+    /** What an `"updated"` changed; on a very large bulk write, what the write changed across its records. */
     changedFields: string[];
 };
 /**
@@ -307,7 +307,9 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
          * its result is saved before anything after it executes, and when a
          * failed run is resumed, completed steps return their saved results
          * instead of re-running their side effects. Names must be unique within
-         * a run, and results must be plain JSON data under 256KB.
+         * a run, and results must be plain JSON data under 256KB. In a run
+         * fired by a schedule, webhook or trigger, `step.sleep` pauses the run
+         * and a failed step is tried again.
          */
         step: ZiteStep;
         context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : TTrigger extends ZiteTrigger ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;
@@ -326,8 +328,32 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
  * it would matter, and give a step inside a loop the item's id in its name.
  */
 export interface ZiteStep {
-    run<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * In a run fired by a schedule, webhook or trigger, a step that throws is
+     * tried again `retries` more times (default 3, at most 10), 30 seconds,
+     * 2 minutes, then 10 minutes apart. Elsewhere its error fails the request.
+     */
+    run<T>(name: string, fn: () => Promise<T> | T, options?: ZiteStepOptions): Promise<T>;
+    /**
+     * Pause the run for `duration`: `"30s"`, `"15m"`, `"2h"`, `"3d"`, `"1w"`,
+     * or milliseconds, at most 30 days. Only a run fired by a schedule, webhook
+     * or trigger can wait; an editor test run goes straight past, and a request
+     * from the app throws.
+     *
+     * The run continues in a later call, which runs `execute` again from the
+     * top: finished steps return their saved results, and code outside a step
+     * runs again, so keep side effects inside steps.
+     */
+    sleep(name: string, duration: ZiteStepDuration): Promise<void>;
+    /** Pause the run until `when`, at most 30 days ahead. See {@link ZiteStep.sleep}. */
+    sleepUntil(name: string, when: Date | string): Promise<void>;
+}
+export interface ZiteStepOptions {
+    /** How many more times to try the step after it throws: 0 to 10, default 3. */
+    retries?: number;
 }
+/** Milliseconds, or a number with a unit: `ms`, `s`, `m`, `h`, `d` or `w`. */
+export type ZiteStepDuration = number | `${number}${"ms" | "s" | "m" | "h" | "d" | "w"}`;
 /**
  * Create an endpoint definition, parsing `input` against `inputSchema` before
  * `execute` runs. Nothing downstream parses it — the worker calls `execute` on

package/dist/esm/backend/index.test.js

@@ -6,6 +6,8 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
 // Direct execute() calls need the step surface the runtime always provides.
 const stepStub = {
     run: async (_name, fn) => await fn(),
+    sleep: async () => { },
+    sleepUntil: async () => { },
 };
 afterEach(() => {
     vi.unstubAllGlobals();

package/dist/esm/sync/lib.js

@@ -1316,7 +1316,7 @@ export function generateBackendWrapperTs(envVarNames = []) {
         "  execute: (",
         "    params: {",
         "      input: ZiteEndpointInput<TInput, TTrigger>;",
-        "      /** Durable steps: step.run(name, fn) runs fn once per logical run — its result is saved before anything after it executes, and a resumed run replays completed steps from their saved results. Provided by the platform; never define a local stand-in. */",
+        "      /** Durable steps: step.run(name, fn) runs fn once per logical run — its result is saved before anything after it executes, and a resumed run replays completed steps from their saved results. In a run fired by a schedule, webhook or trigger, step.sleep(name, \"2d\") pauses the run and a failed step is tried again. Provided by the platform; never define a local stand-in. */",
         "      step: ZiteStep;",
         "      context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : TTrigger extends ZiteTrigger ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;",
         // Mirrors the base module: a trigger's run gets `trigger`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zitejs",
-  "version": "0.9.145",
+  "version": "0.9.147",
   "description": "The Zite framework — build apps on Zite Database",
   "type": "module",
   "sideEffects": false,