zitejs 0.9.144 → 0.9.146

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

@@ -87,8 +87,11 @@ export type ZiteTrigger = {
 };
 /**
  * What a form trigger's run gets as `input`: one submission. `answers` is
- * keyed by question name; `submission` is the whole export, as the Fillout
- * API returns it (`questions`, `calculations`, `urlParameters`, …).
+ * keyed by question name, `answersById` by question id; `submission` is the
+ * whole export, as the Fillout API returns it (`questions`, `calculations`,
+ * `urlParameters`, …). Two questions with the same label are named
+ * `Email` and `Email (1)` in an order the form doesn't show, so read those by
+ * id.
  */
 export type ZiteFormTriggerInput = {
     event: "submitted";
@@ -97,6 +100,7 @@ export type ZiteFormTriggerInput = {
     submissionId: string;
     submittedAt: string | null;
     answers: Record<string, unknown>;
+    answersById: Record<string, unknown>;
     submission: Record<string, unknown> & {
         submissionId: string;
     };
@@ -303,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;
@@ -322,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();
@@ -226,7 +228,11 @@ const stepStub = {
             execute: async ({ input, trigger }) => {
                 // @ts-expect-error a form submission has no cursor API
                 trigger?.advance("x");
-                return { email: input.answers.Email, id: input.submissionId };
+                return {
+                    email: input.answers.Email,
+                    workEmail: input.answersById["wWorkEmail"],
+                    id: input.submissionId,
+                };
             },
         });
         (0, index_js_1.createEndpoint)({

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

@@ -87,8 +87,11 @@ export type ZiteTrigger = {
 };
 /**
  * What a form trigger's run gets as `input`: one submission. `answers` is
- * keyed by question name; `submission` is the whole export, as the Fillout
- * API returns it (`questions`, `calculations`, `urlParameters`, …).
+ * keyed by question name, `answersById` by question id; `submission` is the
+ * whole export, as the Fillout API returns it (`questions`, `calculations`,
+ * `urlParameters`, …). Two questions with the same label are named
+ * `Email` and `Email (1)` in an order the form doesn't show, so read those by
+ * id.
  */
 export type ZiteFormTriggerInput = {
     event: "submitted";
@@ -97,6 +100,7 @@ export type ZiteFormTriggerInput = {
     submissionId: string;
     submittedAt: string | null;
     answers: Record<string, unknown>;
+    answersById: Record<string, unknown>;
     submission: Record<string, unknown> & {
         submissionId: string;
     };
@@ -303,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;
@@ -322,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();
@@ -224,7 +226,11 @@ describe("platform-triggered runs", () => {
             execute: async ({ input, trigger }) => {
                 // @ts-expect-error a form submission has no cursor API
                 trigger?.advance("x");
-                return { email: input.answers.Email, id: input.submissionId };
+                return {
+                    email: input.answers.Email,
+                    workEmail: input.answersById["wWorkEmail"],
+                    id: input.submissionId,
+                };
             },
         });
         createEndpoint({

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.144",
+  "version": "0.9.146",
   "description": "The Zite framework — build apps on Zite Database",
   "type": "module",
   "sideEffects": false,
@@ -97,6 +97,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
+    "release": "node ./scripts/release.mjs",
     "prepublishOnly": "npm run build"
   },
   "files": [