@geekmidas/constructs 9.2.1 → 9.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (170) hide show
  1. package/CHANGELOG.md +73 -0
  2. package/README.md +1 -1
  3. package/dist/{AWSScheduledFunction-CU7mMGFA.mjs → AWSScheduledFunction-BXmRm9W6.mjs} +4 -3
  4. package/dist/{AWSScheduledFunction-CU7mMGFA.mjs.map → AWSScheduledFunction-BXmRm9W6.mjs.map} +1 -1
  5. package/dist/{AWSScheduledFunction-CKhVurOa.cjs → AWSScheduledFunction-C-JBSNak.cjs} +6 -5
  6. package/dist/{AWSScheduledFunction-CKhVurOa.cjs.map → AWSScheduledFunction-C-JBSNak.cjs.map} +1 -1
  7. package/dist/{AWSScheduledFunction-a6hRp3nk.d.mts → AWSScheduledFunction-DgQuL5kt.d.mts} +49 -11
  8. package/dist/AWSScheduledFunction-DgQuL5kt.d.mts.map +1 -0
  9. package/dist/{AWSScheduledFunction-DPMzOjZP.d.cts → AWSScheduledFunction-DoDZR8E6.d.cts} +49 -11
  10. package/dist/AWSScheduledFunction-DoDZR8E6.d.cts.map +1 -0
  11. package/dist/{Construct-D_3yZ9m5.d.cts → Construct-BEh2DSMe.d.cts} +7 -13
  12. package/dist/Construct-BEh2DSMe.d.cts.map +1 -0
  13. package/dist/{Construct-D09WUUOf.cjs → Construct-Cf_0pAvo.cjs} +2 -10
  14. package/dist/Construct-Cf_0pAvo.cjs.map +1 -0
  15. package/dist/{Construct-DsqpiAym.d.mts → Construct-CgluLUuF.d.mts} +7 -13
  16. package/dist/Construct-CgluLUuF.d.mts.map +1 -0
  17. package/dist/{Construct-D0uZvbr3.mjs → Construct-D5LZBFhb.mjs} +3 -11
  18. package/dist/Construct-D5LZBFhb.mjs.map +1 -0
  19. package/dist/{Endpoint-nhjtdDL3.d.cts → Endpoint-1u_i-nCT.d.cts} +2 -2
  20. package/dist/{Endpoint-nhjtdDL3.d.cts.map → Endpoint-1u_i-nCT.d.cts.map} +1 -1
  21. package/dist/{Endpoint-DEydLuBs.d.mts → Endpoint-CypDvYJW.d.mts} +3 -3
  22. package/dist/{Endpoint-DEydLuBs.d.mts.map → Endpoint-CypDvYJW.d.mts.map} +1 -1
  23. package/dist/{HonoEndpointAdaptor-CJfFQ5KR.mjs → HonoEndpointAdaptor-C-mPVfwk.mjs} +11 -18
  24. package/dist/HonoEndpointAdaptor-C-mPVfwk.mjs.map +1 -0
  25. package/dist/{HonoEndpointAdaptor-DCD0rhFg.cjs → HonoEndpointAdaptor-D_2UDPNs.cjs} +12 -19
  26. package/dist/HonoEndpointAdaptor-D_2UDPNs.cjs.map +1 -0
  27. package/dist/{Queue-Brw--scg.d.cts → Queue-Bl87Atny.d.cts} +2 -2
  28. package/dist/{Queue-Brw--scg.d.cts.map → Queue-Bl87Atny.d.cts.map} +1 -1
  29. package/dist/{Queue-D5z1bwFu.d.mts → Queue-Dhl8bc45.d.mts} +2 -2
  30. package/dist/{Queue-D5z1bwFu.d.mts.map → Queue-Dhl8bc45.d.mts.map} +1 -1
  31. package/dist/{Subscriber-DvKSp0N4.d.cts → Subscriber-YwPpHrBc.d.cts} +2 -2
  32. package/dist/{Subscriber-DvKSp0N4.d.cts.map → Subscriber-YwPpHrBc.d.cts.map} +1 -1
  33. package/dist/{Subscriber-CJ22tp8r.d.mts → Subscriber-panMf5vp.d.mts} +2 -2
  34. package/dist/{Subscriber-CJ22tp8r.d.mts.map → Subscriber-panMf5vp.d.mts.map} +1 -1
  35. package/dist/{Topic-BMfrIFdX.d.cts → Topic-DGtlTlu5.d.mts} +3 -3
  36. package/dist/{Topic-B-fxOsR2.d.mts.map → Topic-DGtlTlu5.d.mts.map} +1 -1
  37. package/dist/{Topic-B-fxOsR2.d.mts → Topic-dIcPqSLa.d.cts} +3 -3
  38. package/dist/{Topic-BMfrIFdX.d.cts.map → Topic-dIcPqSLa.d.cts.map} +1 -1
  39. package/dist/adaptors/aws.cjs +9 -14
  40. package/dist/adaptors/aws.cjs.map +1 -1
  41. package/dist/adaptors/aws.d.cts +6 -6
  42. package/dist/adaptors/aws.d.cts.map +1 -1
  43. package/dist/adaptors/aws.d.mts +8 -8
  44. package/dist/adaptors/aws.d.mts.map +1 -1
  45. package/dist/adaptors/aws.mjs +9 -14
  46. package/dist/adaptors/aws.mjs.map +1 -1
  47. package/dist/adaptors/hono.cjs +7 -7
  48. package/dist/adaptors/hono.d.cts +3 -3
  49. package/dist/adaptors/hono.d.cts.map +1 -1
  50. package/dist/adaptors/hono.d.mts +4 -4
  51. package/dist/adaptors/hono.d.mts.map +1 -1
  52. package/dist/adaptors/hono.mjs +7 -7
  53. package/dist/adaptors/testing.cjs +22 -29
  54. package/dist/adaptors/testing.cjs.map +1 -1
  55. package/dist/adaptors/testing.d.cts +5 -5
  56. package/dist/adaptors/testing.d.cts.map +1 -1
  57. package/dist/adaptors/testing.d.mts +6 -6
  58. package/dist/adaptors/testing.d.mts.map +1 -1
  59. package/dist/adaptors/testing.mjs +22 -29
  60. package/dist/adaptors/testing.mjs.map +1 -1
  61. package/dist/{clone-I_WIpiFf.cjs → clone-BQnYiRgm.cjs} +1 -1
  62. package/dist/{clone-I_WIpiFf.cjs.map → clone-BQnYiRgm.cjs.map} +1 -1
  63. package/dist/{clone-pdXxc0t3.mjs → clone-BWIwx6vL.mjs} +1 -1
  64. package/dist/{clone-pdXxc0t3.mjs.map → clone-BWIwx6vL.mjs.map} +1 -1
  65. package/dist/crons/index.cjs +31 -6
  66. package/dist/crons/index.cjs.map +1 -1
  67. package/dist/crons/index.d.cts +23 -9
  68. package/dist/crons/index.d.cts.map +1 -1
  69. package/dist/crons/index.d.mts +19 -5
  70. package/dist/crons/index.d.mts.map +1 -1
  71. package/dist/crons/index.mjs +31 -6
  72. package/dist/crons/index.mjs.map +1 -1
  73. package/dist/endpoints/index.cjs +7 -32
  74. package/dist/endpoints/index.cjs.map +1 -1
  75. package/dist/endpoints/index.d.cts +4 -12
  76. package/dist/endpoints/index.d.cts.map +1 -1
  77. package/dist/endpoints/index.d.mts +5 -13
  78. package/dist/endpoints/index.d.mts.map +1 -1
  79. package/dist/endpoints/index.mjs +7 -32
  80. package/dist/endpoints/index.mjs.map +1 -1
  81. package/dist/functions/index.cjs +3 -3
  82. package/dist/functions/index.d.cts +2 -2
  83. package/dist/functions/index.d.mts +2 -2
  84. package/dist/functions/index.mjs +3 -3
  85. package/dist/{functions-DhkDodl0.mjs → functions-CNJbRq0O.mjs} +4 -89
  86. package/dist/functions-CNJbRq0O.mjs.map +1 -0
  87. package/dist/{functions-B3OFv3QV.cjs → functions-DzjxHo1V.cjs} +3 -100
  88. package/dist/functions-DzjxHo1V.cjs.map +1 -0
  89. package/dist/{index-B8LNLQXD.d.mts → index-BUNi5ldW.d.mts} +2 -8
  90. package/dist/index-BUNi5ldW.d.mts.map +1 -0
  91. package/dist/{index-CXpim5mV.d.cts → index-zeG5G432.d.cts} +2 -8
  92. package/dist/index-zeG5G432.d.cts.map +1 -0
  93. package/dist/index.cjs +1 -1
  94. package/dist/index.d.cts +1 -1
  95. package/dist/index.d.mts +3 -3
  96. package/dist/index.mjs +1 -1
  97. package/dist/{lazyAccessors-C1n1QfEj.cjs → lazyAccessors-BZJl6bx_.cjs} +3 -3
  98. package/dist/{lazyAccessors-C1n1QfEj.cjs.map → lazyAccessors-BZJl6bx_.cjs.map} +1 -1
  99. package/dist/{lazyAccessors-fFIQrblM.mjs → lazyAccessors-BjAZqRqK.mjs} +3 -3
  100. package/dist/{lazyAccessors-fFIQrblM.mjs.map → lazyAccessors-BjAZqRqK.mjs.map} +1 -1
  101. package/dist/monitor-D3uHJ8DU.cjs +67 -0
  102. package/dist/monitor-D3uHJ8DU.cjs.map +1 -0
  103. package/dist/monitor-Dt7fiasS.mjs +61 -0
  104. package/dist/monitor-Dt7fiasS.mjs.map +1 -0
  105. package/dist/monitors/index.cjs +3 -3
  106. package/dist/monitors/index.cjs.map +1 -1
  107. package/dist/monitors/index.d.cts +3 -3
  108. package/dist/monitors/index.d.cts.map +1 -1
  109. package/dist/monitors/index.d.mts +3 -3
  110. package/dist/monitors/index.mjs +3 -3
  111. package/dist/monitors/index.mjs.map +1 -1
  112. package/dist/{processAudits-CwyaaSQc.mjs → processAudits-BEiSkgH3.mjs} +1 -1
  113. package/dist/{processAudits-CwyaaSQc.mjs.map → processAudits-BEiSkgH3.mjs.map} +1 -1
  114. package/dist/{processAudits-94Ar_EJF.cjs → processAudits-Cd912Eck.cjs} +2 -2
  115. package/dist/{processAudits-94Ar_EJF.cjs.map → processAudits-Cd912Eck.cjs.map} +1 -1
  116. package/dist/{publisher-BZgcrVPy.cjs → publisher-B6Wu-JNv.cjs} +1 -1
  117. package/dist/{publisher-BZgcrVPy.cjs.map → publisher-B6Wu-JNv.cjs.map} +1 -1
  118. package/dist/{publisher-CnpeMv-r.mjs → publisher-Cs7WcvJl.mjs} +1 -1
  119. package/dist/{publisher-CnpeMv-r.mjs.map → publisher-Cs7WcvJl.mjs.map} +1 -1
  120. package/dist/queue/index.cjs +2 -2
  121. package/dist/queue/index.d.cts +4 -4
  122. package/dist/queue/index.d.mts +2 -2
  123. package/dist/queue/index.mjs +2 -2
  124. package/dist/subscribers/index.cjs +2 -2
  125. package/dist/subscribers/index.d.cts +5 -5
  126. package/dist/subscribers/index.d.cts.map +1 -1
  127. package/dist/subscribers/index.d.mts +3 -3
  128. package/dist/subscribers/index.mjs +2 -2
  129. package/dist/{telemetry-C--EgYVr.d.mts → telemetry-Bp4DLvdQ.d.mts} +1 -1
  130. package/dist/{telemetry-C--EgYVr.d.mts.map → telemetry-Bp4DLvdQ.d.mts.map} +1 -1
  131. package/dist/topic/index.cjs +2 -2
  132. package/dist/topic/index.d.cts +2 -2
  133. package/dist/topic/index.d.mts +2 -2
  134. package/dist/topic/index.mjs +2 -2
  135. package/dist/{types-DNngH0fX.d.mts → types-j0ti0JTY.d.mts} +1 -1
  136. package/dist/{types-DNngH0fX.d.mts.map → types-j0ti0JTY.d.mts.map} +1 -1
  137. package/dist/types.d.mts +1 -1
  138. package/package.json +22 -22
  139. package/src/Construct.ts +2 -13
  140. package/src/__tests__/Construct.environment.spec.ts +2 -2
  141. package/src/__tests__/builder-reuse.spec.ts +2 -2
  142. package/src/__tests__/uptime.spec.ts +340 -0
  143. package/src/crons/Cron.ts +197 -60
  144. package/src/crons/CronBuilder.ts +25 -5
  145. package/src/crons/__tests__/AWSScheduledFunction.spec.ts +8 -6
  146. package/src/crons/__tests__/Cron.spec.ts +53 -91
  147. package/src/crons/__tests__/CronBuilder.state-isolation.spec.ts +28 -28
  148. package/src/crons/index.ts +2 -1
  149. package/src/endpoints/AmazonApiGatewayEndpointAdaptor.ts +2 -23
  150. package/src/endpoints/EndpointBuilder.ts +1 -4
  151. package/src/endpoints/EndpointFactory.ts +0 -31
  152. package/src/endpoints/HonoEndpointAdaptor.ts +1 -16
  153. package/src/endpoints/TestEndpointAdaptor.ts +4 -20
  154. package/src/functions/BaseFunctionBuilder.ts +0 -10
  155. package/src/functions/FunctionBuilder.ts +0 -2
  156. package/src/monitor.ts +14 -55
  157. package/src/monitors/heartbeat.ts +5 -3
  158. package/dist/AWSScheduledFunction-DPMzOjZP.d.cts.map +0 -1
  159. package/dist/AWSScheduledFunction-a6hRp3nk.d.mts.map +0 -1
  160. package/dist/Construct-D09WUUOf.cjs.map +0 -1
  161. package/dist/Construct-D0uZvbr3.mjs.map +0 -1
  162. package/dist/Construct-D_3yZ9m5.d.cts.map +0 -1
  163. package/dist/Construct-DsqpiAym.d.mts.map +0 -1
  164. package/dist/HonoEndpointAdaptor-CJfFQ5KR.mjs.map +0 -1
  165. package/dist/HonoEndpointAdaptor-DCD0rhFg.cjs.map +0 -1
  166. package/dist/functions-B3OFv3QV.cjs.map +0 -1
  167. package/dist/functions-DhkDodl0.mjs.map +0 -1
  168. package/dist/index-B8LNLQXD.d.mts.map +0 -1
  169. package/dist/index-CXpim5mV.d.cts.map +0 -1
  170. package/src/__tests__/monitor.spec.ts +0 -696
package/src/crons/Cron.ts CHANGED
@@ -7,6 +7,7 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';
7
7
 
8
8
  import { ConstructType } from '../Construct';
9
9
  import { Function, type FunctionHandler } from '../functions';
10
+ import type { MonitorInfo } from '../monitor';
10
11
 
11
12
  export class Cron<
12
13
  TInput extends ComposableStandardSchema | undefined = undefined,
@@ -71,47 +72,105 @@ export class Cron<
71
72
  get schedule(): ScheduleExpression | undefined {
72
73
  return this._schedule;
73
74
  }
75
+
76
+ /**
77
+ * The monitor set with `.uptime()` as the build manifest records it, or
78
+ * nothing when the cron has none.
79
+ */
80
+ getUptime(): MonitorInfo | undefined {
81
+ const [uptime] = this.monitors;
82
+ return uptime && (uptime.monitor ?? { type: uptime.serviceName });
83
+ }
74
84
  }
75
85
 
76
- export type RateExpression = `rate(${string})`;
86
+ // ---- Cron expression types ------------------------------------------------
87
+ //
88
+ // `.schedule()` takes a `cron(…)` in either of two dialects, told apart by the
89
+ // field count, and checks each by its own rules:
90
+ //
91
+ // - Unix, five fields: `min hour day-of-month month day-of-week`, with
92
+ // day-of-week 0–7 (SUN = 0 or 7) and no `?`.
93
+ // - AWS, six fields: `min hour day-of-month month day-of-week year`, with
94
+ // day-of-week 1–7 (SUN = 1), `?` in exactly one day field, and `L`, `W`
95
+ // and `#` where EventBridge allows them.
96
+ //
97
+ // The types are generic because a plain union of every field's forms is too
98
+ // large for TypeScript, so the literal is checked field by field instead.
99
+ // `@geekmidas/manifest`'s `parseCron` applies the same rules at build time.
77
100
 
78
- type CronMinute =
79
- | '*'
80
- | number
81
- | `${number}`
82
- | `${number}-${number}`
83
- | `${number}/${number}`
84
- | `*/${number}`
85
- | `${number},${number}`
86
- | string; // Allow more complex patterns
87
-
88
- type CronHour =
89
- | '*'
90
- | number
91
- | `${number}`
92
- | `${number}-${number}`
93
- | `${number}/${number}`
94
- | `*/${number}`
95
- | `${number},${number}`
96
- | string; // Allow more complex patterns
97
-
98
- type CronDay =
99
- | '*'
100
- | number
101
- | `${number}`
102
- | `${number}-${number}`
103
- | `${number}/${number}`
104
- | `*/${number}`
105
- | `${number},${number}`
106
- | string; // Allow more complex patterns
107
-
108
- type CronMonth =
109
- | '*'
110
- | number
111
- | `${number}`
112
- | `${number}-${number}`
113
- | `${number}/${number}`
114
- | `*/${number}`
101
+ type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
102
+
103
+ /** `'0'`…`'99'`, with an optional leading zero (`'08'`). */
104
+ type UpTo99 = Digit | `${Digit}${Digit}`;
105
+
106
+ type ToNumber<S extends string> = S extends `0${infer R extends `${number}`}`
107
+ ? R extends ''
108
+ ? 0
109
+ : ToNumber<R>
110
+ : S extends `${infer N extends number}`
111
+ ? N
112
+ : never;
113
+
114
+ type Range<
115
+ N extends number,
116
+ Acc extends number[] = [],
117
+ > = Acc['length'] extends N ? Acc[number] : Range<N, [...Acc, Acc['length']]>;
118
+
119
+ /** Numbers from `Min` to `Max` inclusive. */
120
+ type Between<Min extends number, Max extends number> =
121
+ | Exclude<Range<Max>, Range<Min>>
122
+ | Max;
123
+
124
+ /** A single value: a number in range, or one of the field's names. */
125
+ type IsValue<
126
+ S extends string,
127
+ Min extends number,
128
+ Max extends number,
129
+ Names extends string,
130
+ > = S extends Names
131
+ ? true
132
+ : S extends UpTo99
133
+ ? ToNumber<S> extends Between<Min, Max>
134
+ ? true
135
+ : false
136
+ : false;
137
+
138
+ /** `v`, `a-b` or `*`, with an optional `/step`. */
139
+ type IsAtom<
140
+ S extends string,
141
+ Min extends number,
142
+ Max extends number,
143
+ Names extends string,
144
+ > = S extends `${infer Base}/${infer Step}`
145
+ ? Step extends UpTo99
146
+ ? Base extends '*'
147
+ ? true
148
+ : IsAtom<Base, Min, Max, Names>
149
+ : false
150
+ : S extends '*'
151
+ ? true
152
+ : S extends `${infer A}-${infer B}`
153
+ ? [IsValue<A, Min, Max, Names>, IsValue<B, Min, Max, Names>] extends [
154
+ true,
155
+ true,
156
+ ]
157
+ ? true
158
+ : false
159
+ : IsValue<S, Min, Max, Names>;
160
+
161
+ /** A comma-separated list of atoms. */
162
+ type IsField<
163
+ S extends string,
164
+ Min extends number,
165
+ Max extends number,
166
+ Names extends string = never,
167
+ > = S extends `${infer Head},${infer Rest}`
168
+ ? IsAtom<Head, Min, Max, Names> extends true
169
+ ? IsField<Rest, Min, Max, Names>
170
+ : false
171
+ : IsAtom<S, Min, Max, Names>;
172
+
173
+ type MonthName =
115
174
  | 'JAN'
116
175
  | 'FEB'
117
176
  | 'MAR'
@@ -123,27 +182,105 @@ type CronMonth =
123
182
  | 'SEP'
124
183
  | 'OCT'
125
184
  | 'NOV'
126
- | 'DEC'
127
- | string; // Allow more complex patterns
185
+ | 'DEC';
186
+ type DayName = 'SUN' | 'MON' | 'TUE' | 'WED' | 'THU' | 'FRI' | 'SAT';
187
+
188
+ type AllTrue<T extends boolean[]> = T extends true[] ? true : false;
189
+
190
+ type IsUnix<S extends string> =
191
+ S extends `${infer Mi} ${infer H} ${infer Dom} ${infer Mo} ${infer Dow}`
192
+ ? AllTrue<
193
+ [
194
+ IsField<Mi, 0, 59>,
195
+ IsField<H, 0, 23>,
196
+ IsField<Dom, 1, 31>,
197
+ IsField<Mo, 1, 12, MonthName>,
198
+ IsField<Dow, 0, 7, DayName>,
199
+ ]
200
+ >
201
+ : false;
202
+
203
+ type IsAwsDayOfMonth<S extends string> = S extends 'L' | `L-${UpTo99}` | 'LW'
204
+ ? true
205
+ : S extends `${infer D}W`
206
+ ? IsValue<D, 1, 31, never>
207
+ : IsField<S, 1, 31>;
128
208
 
129
- type CronWeekday =
209
+ type IsAwsDayOfWeek<S extends string> = S extends `${infer D}L`
210
+ ? IsValue<D, 1, 7, DayName>
211
+ : S extends `${infer D}#${infer N}`
212
+ ? AllTrue<[IsValue<D, 1, 7, DayName>, IsValue<N, 1, 5, never>]>
213
+ : IsField<S, 1, 7, DayName>;
214
+
215
+ /** 1970–2199, EventBridge's range. */
216
+ type Year = `19${'7' | '8' | '9'}${Digit}` | `${'20' | '21'}${Digit}${Digit}`;
217
+
218
+ type IsYearAtom<S extends string> = S extends
130
219
  | '*'
131
- | number
132
- | `${number}`
133
- | `${number}-${number}`
134
- | `${number}/${number}`
135
- | `*/${number}`
136
- | 'SUN'
137
- | 'MON'
138
- | 'TUE'
139
- | 'WED'
140
- | 'THU'
141
- | 'FRI'
142
- | 'SAT'
143
- | `${string}-${string}` // Allow patterns like MON-FRI
144
- | string; // Allow more complex patterns
145
-
146
- export type CronExpression =
147
- `cron(${CronMinute} ${CronHour} ${CronDay} ${CronMonth} ${CronWeekday})`;
148
-
149
- export type ScheduleExpression = RateExpression | CronExpression;
220
+ | Year
221
+ | `${'*' | Year}/${UpTo99}`
222
+ | `${Year}-${Year}`
223
+ ? true
224
+ : false;
225
+
226
+ type IsAwsYear<S extends string> = S extends `${infer Head},${infer Rest}`
227
+ ? IsYearAtom<Head> extends true
228
+ ? IsAwsYear<Rest>
229
+ : false
230
+ : IsYearAtom<S>;
231
+
232
+ type IsAws<S extends string> =
233
+ S extends `${infer Mi} ${infer H} ${infer Dom} ${infer Mo} ${infer Dow} ${infer Y}`
234
+ ? AllTrue<
235
+ [
236
+ IsField<Mi, 0, 59>,
237
+ IsField<H, 0, 23>,
238
+ IsField<Mo, 1, 12, MonthName>,
239
+ IsAwsYear<Y>,
240
+ Dom extends '?'
241
+ ? Dow extends '?'
242
+ ? false
243
+ : IsAwsDayOfWeek<Dow>
244
+ : Dow extends '?'
245
+ ? IsAwsDayOfMonth<Dom>
246
+ : false,
247
+ ]
248
+ >
249
+ : false;
250
+
251
+ /** `T` when it is a valid five-field Unix `cron(…)`. */
252
+ export type UnixCronExpression<T extends string> = T extends `cron(${infer S})`
253
+ ? IsUnix<S> extends true
254
+ ? T
255
+ : never
256
+ : never;
257
+
258
+ /** `T` when it is a valid six-field AWS (EventBridge) `cron(…)`. */
259
+ export type AwsCronExpression<T extends string> = T extends `cron(${infer S})`
260
+ ? IsAws<S> extends true
261
+ ? T
262
+ : never
263
+ : never;
264
+
265
+ /**
266
+ * `T` when it is a valid cron expression in either dialect, otherwise a
267
+ * message saying what's expected. A schedule built at runtime can be cast to
268
+ * {@link ScheduleExpression}, which `gkm build` then checks.
269
+ */
270
+ export type CronExpression<T extends string> = [T] extends [ScheduleExpression]
271
+ ? [ScheduleExpression] extends [T]
272
+ ? T
273
+ : CheckedCronExpression<T>
274
+ : CheckedCronExpression<T>;
275
+
276
+ type CheckedCronExpression<T extends string> = [
277
+ UnixCronExpression<T> | AwsCronExpression<T>,
278
+ ] extends [never]
279
+ ? 'Expected cron(…) with 5 fields (Unix) or 6 fields (AWS)'
280
+ : T;
281
+
282
+ /**
283
+ * A cron's schedule once set. Literals are checked by {@link CronExpression};
284
+ * every schedule is checked again by `gkm build`.
285
+ */
286
+ export type ScheduleExpression = `cron(${string})`;
@@ -7,7 +7,8 @@ import uniqBy from 'lodash.uniqby';
7
7
  import { ConstructType } from '../Construct';
8
8
  import { cloneWith } from '../clone';
9
9
  import { FunctionBuilder, type FunctionHandler } from '../functions';
10
- import { Cron, type ScheduleExpression } from './Cron';
10
+ import type { MonitorService } from '../monitor';
11
+ import { Cron, type CronExpression, type ScheduleExpression } from './Cron';
11
12
 
12
13
  export class CronBuilder<
13
14
  TInput extends ComposableStandardSchema,
@@ -31,6 +32,7 @@ export class CronBuilder<
31
32
  TDatabaseServiceName
32
33
  > {
33
34
  private _schedule?: ScheduleExpression;
35
+ private _uptime?: MonitorService;
34
36
 
35
37
  constructor() {
36
38
  super(ConstructType.Cron);
@@ -40,8 +42,12 @@ export class CronBuilder<
40
42
  return cloneWith(this, { _memorySize: memorySize });
41
43
  }
42
44
 
43
- schedule(
44
- _expression: ScheduleExpression,
45
+ /**
46
+ * When the cron runs: a five-field Unix `cron(…)` or a six-field AWS one.
47
+ * `gkm build` writes it to the manifest in the AWS form.
48
+ */
49
+ schedule<const T extends string>(
50
+ _expression: CronExpression<T>,
45
51
  ): CronBuilder<
46
52
  TInput,
47
53
  TServices,
@@ -52,7 +58,21 @@ export class CronBuilder<
52
58
  TDatabase,
53
59
  TDatabaseServiceName
54
60
  > {
55
- return cloneWith(this, { _schedule: _expression });
61
+ return cloneWith(this, {
62
+ _schedule: _expression as ScheduleExpression,
63
+ });
64
+ }
65
+
66
+ /**
67
+ * Report each run to an uptime monitor, so a cron that stops running is
68
+ * noticed: `heartbeat.betterStack()` pings on success and reports a
69
+ * failure. Calling it again replaces the monitor.
70
+ *
71
+ * `gkm build` records it in the manifest with the schedule's period, the
72
+ * longest gap between runs, so infrastructure can create the heartbeat.
73
+ */
74
+ uptime(monitor: MonitorService): this {
75
+ return cloneWith(this, { _uptime: monitor });
56
76
  }
57
77
 
58
78
  override input<T extends ComposableStandardSchema>(
@@ -254,7 +274,7 @@ export class CronBuilder<
254
274
  // configured base keeps its configuration for every construct built
255
275
  // from it. The reset that used to be here wiped the base on first use.
256
276
 
257
- cron.monitors = this._monitors;
277
+ cron.monitors = this._uptime ? [this._uptime] : [];
258
278
 
259
279
  return cron;
260
280
  }
@@ -77,9 +77,11 @@ describe('AWSScheduledFunction', () => {
77
77
 
78
78
  it('runs the cron handler on a scheduled event', async () => {
79
79
  const ran = vi.fn();
80
- const cron = new CronBuilder().schedule('rate(1 day)').handle(async () => {
81
- ran();
82
- });
80
+ const cron = new CronBuilder()
81
+ .schedule('cron(0 0 * * *)')
82
+ .handle(async () => {
83
+ ran();
84
+ });
83
85
 
84
86
  const adapter = new AWSScheduledFunction(envParser, cron);
85
87
  const result = await adapter.handler(
@@ -96,7 +98,7 @@ describe('AWSScheduledFunction', () => {
96
98
 
97
99
  it('parses and returns output when the cron declares an output schema', async () => {
98
100
  const cron = new CronBuilder()
99
- .schedule('rate(1 day)')
101
+ .schedule('cron(0 0 * * *)')
100
102
  .output(z.object({ cancelled: z.number() }))
101
103
  .handle(async () => ({ cancelled: 3 }));
102
104
 
@@ -113,7 +115,7 @@ describe('AWSScheduledFunction', () => {
113
115
  it('exposes services to the cron handler', async () => {
114
116
  let observed = 0;
115
117
  const cron = new CronBuilder()
116
- .schedule('rate(1 hour)')
118
+ .schedule('cron(0 * * * *)')
117
119
  .services([new CounterService()])
118
120
  .handle(async ({ services }) => {
119
121
  observed = services.counter.increment();
@@ -134,7 +136,7 @@ describe('AWSScheduledFunction', () => {
134
136
  const logger = makeSpyLogger();
135
137
 
136
138
  const cron = new CronBuilder()
137
- .schedule('rate(1 day)')
139
+ .schedule('cron(0 0 * * *)')
138
140
  .logger(logger)
139
141
  .handle(async () => {
140
142
  hadContext = serviceContext.hasContext();
@@ -3,7 +3,7 @@ import type { Service } from '@geekmidas/services';
3
3
  import { describe, expect, it, vi } from 'vitest';
4
4
  import { z } from 'zod';
5
5
  import { ConstructType } from '../../Construct';
6
- import { Cron, type CronExpression, type RateExpression } from '../Cron';
6
+ import { Cron, type ScheduleExpression } from '../Cron';
7
7
  import { CronBuilder } from '../CronBuilder';
8
8
 
9
9
  // Mock service for testing
@@ -41,7 +41,7 @@ describe('Cron', () => {
41
41
 
42
42
  it('should create a Cron instance with schedule expression', () => {
43
43
  const handler = vi.fn();
44
- const schedule: CronExpression = 'cron(0 12 * * MON)';
44
+ const schedule: ScheduleExpression = 'cron(0 12 * * MON)';
45
45
  const cron = new Cron(handler, undefined, schedule);
46
46
 
47
47
  expect(cron).toBeInstanceOf(Cron);
@@ -134,7 +134,7 @@ describe('Cron', () => {
134
134
  it('should create a Cron with all parameters', () => {
135
135
  const inputSchema = z.object({ name: z.string() });
136
136
  const outputSchema = z.object({ greeting: z.string() });
137
- const schedule: RateExpression = 'rate(5 minutes)';
137
+ const schedule: ScheduleExpression = 'cron(*/5 * * * *)';
138
138
  const timeout = 60000;
139
139
  const service = new MockService();
140
140
  const logger = new ConsoleLogger();
@@ -207,7 +207,7 @@ describe('Cron', () => {
207
207
 
208
208
  it('should set schedule with schedule() method', () => {
209
209
  const builder = new CronBuilder();
210
- const schedule: CronExpression = 'cron(0 0 * * SUN)';
210
+ const schedule: ScheduleExpression = 'cron(0 0 * * SUN)';
211
211
 
212
212
  const result = builder.schedule(schedule);
213
213
 
@@ -231,7 +231,7 @@ describe('Cron', () => {
231
231
  it('should build Cron with full builder chain', () => {
232
232
  const inputSchema = z.object({ task: z.string() });
233
233
  const outputSchema = z.object({ completed: z.boolean() });
234
- const schedule: RateExpression = 'rate(1 hour)';
234
+ const schedule: ScheduleExpression = 'cron(0 * * * *)';
235
235
  const service = new MockService();
236
236
  const logger = new ConsoleLogger();
237
237
 
@@ -259,7 +259,7 @@ describe('Cron', () => {
259
259
 
260
260
  it('should support method chaining in any order', () => {
261
261
  const builder = new CronBuilder();
262
- const schedule: CronExpression = 'cron(30 2 * * TUE)';
262
+ const schedule: ScheduleExpression = 'cron(30 2 * * TUE)';
263
263
 
264
264
  const chained = builder
265
265
  .timeout(30000)
@@ -274,90 +274,52 @@ describe('Cron', () => {
274
274
  });
275
275
 
276
276
  describe('Schedule Expression Types', () => {
277
- it('should accept valid rate expressions', () => {
278
- const validRates: RateExpression[] = [
279
- 'rate(5 minutes)',
280
- 'rate(1 hour)',
281
- 'rate(7 days)',
282
- 'rate(30 seconds)',
283
- 'rate(2 weeks)',
284
- ];
285
-
286
- validRates.forEach((rate) => {
287
- const builder = new CronBuilder();
288
- expect(() => builder.schedule(rate)).not.toThrow();
289
- });
290
- });
291
-
292
- it('should accept valid cron expressions', () => {
293
- const validCrons: CronExpression[] = [
294
- 'cron(0 12 * * MON)',
295
- 'cron(15 10 * * FRI)',
296
- 'cron(0 0 1 JAN SUN)',
297
- 'cron(*/5 * * * *)',
298
- 'cron(0 0-23/2 * * *)',
299
- 'cron(30 4 1,15 * *)',
300
- 'cron(0 12 * DEC MON)',
301
- ];
302
-
303
- validCrons.forEach((cron) => {
304
- const builder = new CronBuilder();
305
- expect(() => builder.schedule(cron)).not.toThrow();
306
- });
307
- });
308
-
309
- it('should work with complex cron patterns', () => {
310
- const complexPatterns: CronExpression[] = [
311
- 'cron(*/15 * * * *)', // Every 15 minutes
312
- 'cron(0 */4 * * *)', // Every 4 hours
313
- 'cron(0 9-17 * * MON-FRI)', // Every hour 9-5 on weekdays
314
- 'cron(0 0 1-7 * SUN)', // First Sunday of month
315
- 'cron(*/30 8-18 * * *)', // Every 30 min during business hours
316
- ];
317
-
318
- complexPatterns.forEach((pattern) => {
319
- const builder = new CronBuilder();
320
- expect(() => builder.schedule(pattern)).not.toThrow();
321
- });
322
- });
323
-
324
- it('should handle all month names', () => {
325
- const months: CronExpression[] = [
326
- 'cron(0 0 1 JAN *)',
327
- 'cron(0 0 1 FEB *)',
328
- 'cron(0 0 1 MAR *)',
329
- 'cron(0 0 1 APR *)',
330
- 'cron(0 0 1 MAY *)',
331
- 'cron(0 0 1 JUN *)',
332
- 'cron(0 0 1 JUL *)',
333
- 'cron(0 0 1 AUG *)',
334
- 'cron(0 0 1 SEP *)',
335
- 'cron(0 0 1 OCT *)',
336
- 'cron(0 0 1 NOV *)',
337
- 'cron(0 0 1 DEC *)',
338
- ];
339
-
340
- months.forEach((expression) => {
341
- const builder = new CronBuilder();
342
- expect(() => builder.schedule(expression)).not.toThrow();
343
- });
344
- });
345
-
346
- it('should handle all weekday names', () => {
347
- const weekdays: CronExpression[] = [
348
- 'cron(0 0 * * SUN)',
349
- 'cron(0 0 * * MON)',
350
- 'cron(0 0 * * TUE)',
351
- 'cron(0 0 * * WED)',
352
- 'cron(0 0 * * THU)',
353
- 'cron(0 0 * * FRI)',
354
- 'cron(0 0 * * SAT)',
355
- ];
356
-
357
- weekdays.forEach((expression) => {
358
- const builder = new CronBuilder();
359
- expect(() => builder.schedule(expression)).not.toThrow();
360
- });
277
+ it('accepts Unix and AWS literals and rejects invalid ones', () => {
278
+ const c = new CronBuilder();
279
+
280
+ c.schedule('cron(0 8 * * *)');
281
+ c.schedule('cron(0 9 * * MON-FRI)');
282
+ c.schedule('cron(0 9 1 * MON)');
283
+ c.schedule('cron(0 0 * * 7)');
284
+ c.schedule('cron(0 8 * * ? *)');
285
+ c.schedule('cron(0 9 ? * MON-FRI *)');
286
+ c.schedule('cron(0 9 L * ? *)');
287
+ c.schedule('cron(0 9 15W * ? *)');
288
+ c.schedule('cron(0 9 ? * 6#3 *)');
289
+ c.schedule('cron(0 9 ? * FRIL 2026-2027)');
290
+
291
+ // @ts-expect-error 4 fields
292
+ c.schedule('cron(0 8 * *)');
293
+ // @ts-expect-error 7 fields
294
+ c.schedule('cron(0 0 8 * * ? *)');
295
+ // @ts-expect-error `?` is AWS, not Unix
296
+ c.schedule('cron(0 8 * * ?)');
297
+ // @ts-expect-error AWS needs `?` in one day field
298
+ c.schedule('cron(0 8 * * * *)');
299
+ // @ts-expect-error AWS with `?` in both day fields
300
+ c.schedule('cron(0 8 ? * ? *)');
301
+ // @ts-expect-error AWS with both day fields restricted
302
+ c.schedule('cron(0 9 1 * MON *)');
303
+ // @ts-expect-error AWS day-of-week is 1-7
304
+ c.schedule('cron(0 9 ? * 0 *)');
305
+ // @ts-expect-error hour 25
306
+ c.schedule('cron(0 25 * * *)');
307
+ // @ts-expect-error minute 60
308
+ c.schedule('cron(60 * * * ? *)');
309
+ // @ts-expect-error `L` is AWS only
310
+ c.schedule('cron(0 9 L * *)');
311
+ // @ts-expect-error rate() is not supported
312
+ c.schedule('rate(1 day)');
313
+ // @ts-expect-error double space
314
+ c.schedule('cron(0 8 * * *)');
315
+ // @ts-expect-error not a month
316
+ c.schedule('cron(0 8 * FOO *)');
317
+ // @ts-expect-error a year before 1970
318
+ c.schedule('cron(0 8 * * ? 1969)');
319
+ // @ts-expect-error a plain string needs a cast
320
+ c.schedule('cron(0 8 * * *)' as string);
321
+ // A runtime schedule cast to ScheduleExpression is checked at build.
322
+ c.schedule('cron(0 8 * * *)' as ScheduleExpression);
361
323
  });
362
324
  });
363
325
 
@@ -454,7 +416,7 @@ describe('Cron', () => {
454
416
 
455
417
  const cron1 = new CronBuilder()
456
418
  .timeout(1000)
457
- .schedule('rate(5 minutes)')
419
+ .schedule('cron(*/5 * * * *)')
458
420
  .handle(handler1);
459
421
 
460
422
  const cron2 = new CronBuilder()