Skip to content

Commit 21c5dcb

Browse files
huangyiireneclaude
andauthored
fix(spec): replace the croner-refused cron example in the DisasterRecoveryPlan docblock (#16415)
* fix(spec): replace the croner-refused cron example in the DisasterRecoveryPlan docblock The `DisasterRecoveryPlanSchema` `@example` spelled its six-hourly backup schedule `'0 0/6 * * *'`. `0/6` is Quartz-style stepping, and `croner` — the only cron parser the platform runs, reached via `CronJobAdapter` -> `new Cron()` — refuses it: TypeError: CronPattern: Syntax error, stepping with numeric prefix ('0/6') is not allowed. Use wildcard (*/step) or range (min-max/step) instead. Measured against the croner 10.0.1 copy installed for `@objectstack/service-job`, with the sibling example `'0 2 * * *'` as the positive control (accepted). The replacement `'0 */6 * * *'` is accepted and fires at the same instants; it is the spelling this schema's own tests already use. Comment-only: no schema, no export, no accept-set movement. The docblock does publish into the shipped `dist/system/index.d.ts`, so the change is user-visible and carries a changeset. Claude-Session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno Co-authored-by: Claude <noreply@anthropic.com> * fix(spec): use the enumerated six-hourly spelling — the wildcard step closes the docblock The wildcard-step form croner's own error message suggests cannot be written inside a `/** ... */` block comment: the step separator is the comment terminator, so the file stops parsing. Measured — esbuild refused disaster-recovery.zod.ts at the example's own line, column 26, during `pnpm --filter @objectstack/spec build`. The enumerated equivalent carries no such sequence, is accepted by the same croner 10.0.1 copy, and was measured to fire at the identical instants (00:00, 06:00, 12:00, 18:00). Claude-Session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno Co-authored-by: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 9f890d3 commit 21c5dcb

2 files changed

Lines changed: 20 additions & 1 deletion

File tree

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
"@objectstack/spec": patch
3+
---
4+
5+
The `DisasterRecoveryPlan` docblock example no longer teaches a cron dialect the platform's scheduler refuses.
6+
7+
`DisasterRecoveryPlanSchema`'s `@example` block spelled its six-hourly backup schedule `'0 0/6 * * *'`. A numeric prefix before the step (`0/6`) is Quartz-style stepping. The only cron parser this platform runs is `croner` — reached through `CronJobAdapter`, which hands every scheduled expression to `new Cron(...)` — and it refuses that spelling. Measured against the `croner` 10.0.1 copy installed for `@objectstack/service-job`:
8+
9+
```
10+
new Cron('0 0/6 * * *')
11+
-> TypeError: CronPattern: Syntax error, stepping with numeric prefix ('0/6')
12+
is not allowed. Use wildcard (asterisk-slash-step) or range (min-max/step) instead.
13+
```
14+
15+
The example now reads `'0 0,6,12,18 * * *'`, which the same parser accepts and which fires at 00:00, 06:00, 12:00 and 18:00 — the instants the old spelling was written to mean. The sibling example `'0 2 * * *'` on the same schema is accepted unchanged; it was the positive control for the measurement, so the refusal above is a reading rather than a broken probe.
16+
17+
The wildcard-step spelling croner's own error message suggests, and which this schema's tests use, is **not writable in this position**: inside a `/** … */` block comment the step separator closes the comment, and the file stops parsing (measured — esbuild refuses it at the example's own line). The enumerated form is the equivalent that survives a docblock, and both forms were measured to produce identical firing instants.
18+
19+
Nothing fires differently, because nothing fires at all: `BackupConfig.schedule` is declared-but-unwired and reaches no scheduler, and `CronExpressionInputSchema` judges no cron syntax at parse time by design (`shared/expression.zod.ts`) — so the bad example sat in a position that is deliberately undefended. The accept set of every schema is unchanged by this edit, and no export moves. What changes is what an author copying the example gets: the docblock publishes verbatim into the shipped `dist/system/index.d.ts`, so it is the text an editor shows on hover.

‎packages/spec/src/system/disaster-recovery.zod.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@ export type RTOParsed = z.infer<typeof RTOSchema>;
201201
* rto: { value: 1, unit: 'hours' },
202202
* backup: {
203203
* strategy: 'incremental',
204-
* schedule: '0 0/6 * * *',
204+
* schedule: '0 0,6,12,18 * * *',
205205
* retention: { days: 90, minCopies: 5 },
206206
* destination: { type: 's3', bucket: 'backup-bucket', region: 'us-east-1' },
207207
* },

0 commit comments

Comments
 (0)