@flowrunner/cli 0.1.15 → 0.1.16

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.
@@ -17,6 +17,7 @@ and behaviors.
17
17
  | `z.array(inner)` | list | | `.labels({ value: 'Label' })` | `z.enum` | UI shows the label; the flow stores and `execute` receives the VALUE |
18
18
  | `z.union([...])` | the **first** branch's widget — see below | | | | |
19
19
  | `z.filesUploadOptions([...])`, `z.filesListOptions([...])`, `z.filesGetOptions([...])`, `z.filesDeleteOptions([...])` | nested form — the platform's own file-storage options, one group per Files call (see [03-parameters.md](03-parameters.md)) | | | | |
20
+ | | | | `.required()` | `z.unknown()` / `z.any()` field | required, any value — the open types are the only ones optional by default (see [Any value, but required](#any-value-but-required)) |
20
21
  | | | | `.secret()` | `z.string()` config field | Masks the input, with a reveal toggle. **Display only** — see below |
21
22
  | | | | `.dynamicProps({ dependsOn, execute })` | top-level **action** param: `z.looseObject()` or `z.array(z.looseObject())` | the object's inner fields are loaded at design time from other params (see [03-parameters.md](03-parameters.md)) |
22
23
 
@@ -27,7 +28,8 @@ Notes:
27
28
  config field is the `type` it **publishes**: a closed set in which `z.number()` lands on `string`. That is
28
29
  what a test asserts, not what the form renders. See
29
30
  [Config fields publish a smaller set of types](#config-fields-publish-a-smaller-set-of-types).
30
- - **Required is the default** — mark optional fields with `.optional()`.
31
+ - **Required is the default** — mark optional fields with `.optional()`. The exception is `z.unknown()` / `z.any()`,
32
+ optional unless marked `.required()`.
31
33
  - `.shared()` marks a config field as a **shared** (global) config value rather than per-app — used for
32
34
  OAuth client id/secret and other secrets. It is a **UI directive**: it decides who fills the field in and
33
35
  in which dialog, not how your handler reads it. `config.clientId` is the same either way, and a service
@@ -98,7 +100,7 @@ The table above is what a service declares day to day. A few more types are acce
98
100
  | `z.bigint()` | numeric stepper | your handler receives a `BigInt`. A fractional value is refused rather than rounded, since the conversion would lose information |
99
101
  | `z.literal(v)` | the widget of `v`'s own type — a toggle for `z.literal(true)`, a stepper for `z.literal(7)` | a literal of several values of *different* types has no such type and publishes as text |
100
102
  | `z.record(k, v)` | nested form with no declared fields, because the keys are open | the values are converted against `v` like any other declaration |
101
- | `z.any()` / `z.unknown()` | single-line | declares nothing: the value reaches your handler exactly as it arrived, unconverted |
103
+ | `z.any()` / `z.unknown()` | single-line | declares nothing: the value reaches your handler exactly as it arrived, unconverted. **Optional unless marked** — the one exception to *required is the default*; see [Any value, but required](#any-value-but-required) |
102
104
 
103
105
  **Those two tables together are the whole surface.** A declaration outside them — `z.tuple()`,
104
106
  `z.intersection()`, a modifier a future zod release adds — **fails when the extension loads**, naming the
@@ -118,12 +120,33 @@ These modifiers are looked THROUGH — the parameter publishes and coerces as th
118
120
  | Modifier | Published as |
119
121
  |---|---|
120
122
  | `.optional()` / `.nullable()` / `.nullish()` | the inner type, not required |
121
- | `.default(v)` / `.prefault(v)` | the inner type, not required, with `defaultValue` |
123
+ | `.default(v)` / `.prefault(v)` | the inner type, **not required**, with `defaultValue` — always, even with `.nonoptional()` around it: the runner fills the default, so an empty field never reaches the handler |
122
124
  | `.readonly()` | the inner type |
123
- | `.nonoptional()` | the inner type, required — it overrides an `.optional()` inside it |
125
+ | `.nonoptional()` / `.required()` | the inner type, required — it overrides an `.optional()` inside it, but not a `.default(v)`. `.required()` is the FlowRunner spelling for `z.unknown()` / `z.any()`; on `z.object()` it is zod's own (every key required) |
124
126
  | `.pipe(…)` / `.transform(fn)` | the **input** side. `bodyParams` describes what a caller supplies, which is what the console renders a form for; what your handler receives afterwards is the pipe's business |
125
127
  | `z.lazy(() => …)` | the type the thunk returns |
126
128
 
129
+ ### Any value, but required
130
+
131
+ `z.unknown()` and `z.any()` pass a value through **unconverted** — a number or a boolean bound from an
132
+ expression keeps its type, an object stays an object — which is what you want for a field the vendor takes
133
+ in any type (a Redis value, a Cosmos DB partition key, a custom-field value). Unlike every other type they
134
+ are **optional unless marked**, so mark the ones that must be set:
135
+
136
+ ```js
137
+ value: z.unknown().required().label('Value') // or .nonoptional() — the same thing
138
+ ```
139
+
140
+ | The flow sends | The handler receives |
141
+ |---|---|
142
+ | text (`''` included), a number, `0`, `false`, an object, a list, a date | the value, as given |
143
+ | `null` | `null` — a value the flow passed on purpose |
144
+ | nothing (`undefined`) | refused: `«Value» is required` — the handler never runs |
145
+
146
+ A bare `z.unknown()` is optional: a missing value reaches the handler as `undefined`, while `''` and `null` arrive
147
+ as given, as on a required one. Use `.required()` rather than guarding for `undefined` in the handler — it also marks the field required in the
148
+ form, where a guard cannot.
149
+
127
150
  ### `.catch(v)` is refused — use `.default(v)`
128
151
 
129
152
  `.catch(v)` looks like the natural way to say "if this isn't a valid list, use an empty one", so it is what
@@ -155,22 +178,42 @@ Both declarations validate identically. They **publish differently**, and nothin
155
178
  — so reordering branches to read more nicely silently changes what the flow author is shown. Put the shape
156
179
  you want on the form first, and treat the order as part of the contract.
157
180
 
158
- ### Coercion tries the branches in that same order, and the first that fits wins
181
+ ### A value that already fits a branch is kept as given
182
+
183
+ The branches are checked in that same order against the value **exactly as it arrived**, and the first that
184
+ accepts it wins — nothing is converted. Only a value that fits no branch is converted, into the first branch
185
+ it can become.
186
+
187
+ ```js
188
+ badge: z.union([z.number(), z.string()]) // 5 → 5 '+1' → '+1' true → 'true' (fits neither, converted)
189
+ id : z.union([z.string(), z.number()]) // 5 → 5 '5' → '5'
190
+ ```
191
+
192
+ So one field can keep both forms of a mixed value — a count and an increment, a number and a vendor's text
193
+ decimal — whichever order you declare.
194
+
195
+ **Text always fits a `z.string()` branch.** A value bound from a template or typed into an expression is
196
+ text, so a union with a `z.string()` branch never turns it into a number or a boolean, whatever the order.
197
+ That is worth spelling out for booleans, because the failure is silent: in `z.union([z.boolean(),
198
+ z.string()])` the expression text `'false'` reaches `execute` as the string `'false'`, which is truthy —
199
+ `if (params.flag)` runs the *on* path for an explicit *off*. (The toggle itself sends a real `false`.)
159
200
 
160
- A flow supplies every value as text, so a union has to convert before it can tell which branch applies.
201
+ When the other accepted forms are **a few fixed words**, declare the words, not `z.string()`. A
202
+ `z.literal()` or a `z.enum()` does not fit arbitrary text, so text that is a number or a boolean is
203
+ converted:
161
204
 
162
205
  ```js
163
- flag: z.union([z.boolean(), z.string()]) // 'true' → your handler receives the boolean true
164
- flag: z.union([z.string(), z.boolean()]) // 'true' → your handler receives the string 'true'
206
+ limit: z.union([z.number(), z.literal('max')]) // '5' → 5 'max' → 'max'
207
+ mode : z.union([z.boolean(), z.literal('auto')]) // 'false' → false 'auto' → 'auto'
208
+ scope: z.union([z.number(), z.enum(['all', 'none'])]) // '5' → 5 'all' → 'all' 'x' → «Scope» is invalid
165
209
  ```
166
210
 
167
- **A branch that accepts anything hides every branch after it.** `z.string()` takes `'true'` as-is, so the
168
- boolean branch is never reached. If one branch is a fallback, declare it last.
211
+ Keep `z.string()` in a union only when free text really is one of the forms, and convert in the handler if
212
+ you need a number out of it. For a value that must pass through untouched whatever its type, use
213
+ `z.unknown()` (see [Any value, but required](#any-value-but-required)).
169
214
 
170
- That is worth spelling out for booleans, because the failure is silent. In `z.union([z.string(),
171
- z.boolean()])` the field draws as the **first** branch's widget — a text box, not a toggle — the boolean
172
- vocabulary below is never applied, and `execute` receives the string `'false'`, which is truthy: `if
173
- (params.flag)` runs the *on* path for an explicit *off*. Put the boolean branch first.
215
+ A constraint is part of "fits": `z.union([z.number().min(10), z.string()])` given `5` hands over `'5'`,
216
+ because the number branch refuses it and the string branch takes it converted.
174
217
 
175
218
  ### A blank means "not set"
176
219
 
@@ -272,5 +315,6 @@ knowing:
272
315
  - **Absence follows your modifiers, not the transport.** Whether an empty field arrives as `undefined`,
273
316
  `null`, or the declared `.default(v)` is decided by what your schema accepts, so you write `.optional()` or
274
317
  `.nullable()` — whichever reads naturally — instead of guarding for all three. One exception: an empty
275
- string on a `z.string()` field is a *value*, not absence, so it does not fail a required field. See
318
+ string on a `z.string()` field — and on `z.unknown()` / `z.any()` — is a *value*, not absence, so it does not
319
+ fail a required field. See
276
320
  [16-gotchas.md](16-gotchas.md).
@@ -6,6 +6,10 @@ in full.
6
6
 
7
7
  ## An empty string is a value, not an absence
8
8
 
9
+ On a plain `z.string()`, and on `z.unknown()` / `z.any()`, which take any value as given. On every other type
10
+ `''` is absence; and a `.default(v)` — on any type, an enum included — fills `''` and `null` as well as a missing
11
+ value, so a defaulted field never sees either.
12
+
9
13
  Request bodies are usually built by dropping unset params. Drop only `undefined` and `null`:
10
14
 
11
15
  ```js
package/dist/cli.js CHANGED
@@ -14508,7 +14508,7 @@ var require_package = __commonJS({
14508
14508
  "package.json"(exports2, module2) {
14509
14509
  module2.exports = {
14510
14510
  name: "@flowrunner/cli",
14511
- version: "0.1.15",
14511
+ version: "0.1.16",
14512
14512
  publishConfig: {
14513
14513
  access: "public"
14514
14514
  },
@@ -16291,16 +16291,39 @@ function declaredAbsence(schema) {
16291
16291
  current = def.innerType;
16292
16292
  }
16293
16293
  const absence = acceptsUndefined && acceptsNull ? "as-received" : acceptsUndefined ? "undefined" : acceptsNull ? "null" : "required";
16294
- return { absence, absorbsBlank };
16294
+ return { absence, absorbsBlank, keepsEmpty: false, blankIsValue: false };
16295
16295
  }
16296
16296
  function coerces(schema) {
16297
16297
  return inspect(schema).core?._zod?.def?.coerce === true;
16298
16298
  }
16299
16299
  var parsesJson = (schema) => !!inspect(schema).meta.frJson;
16300
+ var OPEN_TYPES = /* @__PURE__ */ new Set(["unknown", "any"]);
16301
+ var isOpenType = (schema) => OPEN_TYPES.has(inspect(schema).coreType);
16302
+ function requiredOpenType(schema) {
16303
+ if (!isOpenType(schema)) {
16304
+ return false;
16305
+ }
16306
+ let current = schema;
16307
+ while (current?._zod) {
16308
+ const def = current._zod.def ?? {};
16309
+ const type = def.type;
16310
+ if (type === "nonoptional") {
16311
+ return true;
16312
+ }
16313
+ if (!TRANSPARENT_WRAPPERS.has(type)) {
16314
+ return false;
16315
+ }
16316
+ current = innerOf(def, type);
16317
+ }
16318
+ return false;
16319
+ }
16300
16320
  function probeAbsence(schema) {
16301
16321
  if (coerces(schema) || parsesJson(schema)) {
16302
16322
  return declaredAbsence(schema);
16303
16323
  }
16324
+ if (requiredOpenType(schema)) {
16325
+ return { absence: "required", absorbsBlank: false, keepsEmpty: true, blankIsValue: true };
16326
+ }
16304
16327
  const parse = (value) => {
16305
16328
  try {
16306
16329
  return schema.safeParse(value);
@@ -16311,24 +16334,24 @@ function probeAbsence(schema) {
16311
16334
  const asUndefined = parse(void 0);
16312
16335
  const asNull = parse(null);
16313
16336
  const absence = asUndefined.success && asNull.success ? "as-received" : asUndefined.success ? "undefined" : asNull.success ? "null" : "required";
16314
- return { absence, absorbsBlank: asUndefined.success && asUndefined.data !== void 0 };
16337
+ return { absence, absorbsBlank: asUndefined.success && asUndefined.data !== void 0, keepsEmpty: false, blankIsValue: false };
16315
16338
  }
16316
16339
  var probeCache = /* @__PURE__ */ new WeakMap();
16317
16340
  function absenceOf(schema) {
16318
16341
  if (!schema || typeof schema !== "object") {
16319
- return { absence: "as-received", absorbsBlank: false };
16342
+ return { absence: "as-received", absorbsBlank: false, keepsEmpty: false, blankIsValue: false };
16320
16343
  }
16321
16344
  const cached2 = probeCache.get(schema);
16322
16345
  if (cached2) {
16323
16346
  return cached2;
16324
16347
  }
16325
- const probed = probeAbsence(schema);
16348
+ const probed = { ...probeAbsence(schema), blankIsValue: isOpenType(schema) && !parsesJson(schema) };
16326
16349
  probeCache.set(schema, probed);
16327
16350
  return probed;
16328
16351
  }
16329
16352
  function planField(name, schema) {
16330
16353
  const ins = inspect(schema);
16331
- const { absence, absorbsBlank } = probeAbsence(schema);
16354
+ const { absence, absorbsBlank, keepsEmpty, blankIsValue } = absenceOf(schema);
16332
16355
  return {
16333
16356
  name,
16334
16357
  schema,
@@ -16337,6 +16360,8 @@ function planField(name, schema) {
16337
16360
  isUnion: !!ins.branches,
16338
16361
  absence,
16339
16362
  absorbsBlank,
16363
+ keepsEmpty,
16364
+ blankIsValue,
16340
16365
  passThroughDate: passesDateThrough(ins),
16341
16366
  restoresDates: hasPassThroughDate(schema, inspect, shapeEntries)
16342
16367
  };
@@ -16435,6 +16460,9 @@ function accepts(schema, value) {
16435
16460
  }
16436
16461
  }
16437
16462
  function coerceUnion(value, branches) {
16463
+ if (branches.some((branch) => accepts(branch, value))) {
16464
+ return value;
16465
+ }
16438
16466
  for (const branch of branches) {
16439
16467
  const coerced = coerceDeep(value, branch);
16440
16468
  if (accepts(branch, coerced)) {
@@ -16510,7 +16538,13 @@ function coerceLeaf(value, ins) {
16510
16538
  return coerceValue(value, ins.coreType);
16511
16539
  }
16512
16540
  function isBlank(value, ins, schema) {
16513
- if (value === void 0 || value === null) {
16541
+ if (value === void 0) {
16542
+ return true;
16543
+ }
16544
+ if (absenceOf(schema).keepsEmpty) {
16545
+ return false;
16546
+ }
16547
+ if (value === null) {
16514
16548
  return true;
16515
16549
  }
16516
16550
  if (value !== "") {
@@ -16519,6 +16553,9 @@ function isBlank(value, ins, schema) {
16519
16553
  if (ins.branches) {
16520
16554
  return true;
16521
16555
  }
16556
+ if (absenceOf(schema).blankIsValue) {
16557
+ return absenceOf(schema).absorbsBlank;
16558
+ }
16522
16559
  return ins.coreType !== "string" || absenceOf(schema).absorbsBlank;
16523
16560
  }
16524
16561
  function absentAs(schema, value) {
@@ -16655,7 +16692,13 @@ function toFieldIssue(plan2, issue, fieldValue) {
16655
16692
  var resolved2 = (value) => ({ value, present: true, issues: [] });
16656
16693
  var rejected = (issues) => ({ present: false, issues });
16657
16694
  function isAbsent(value, plan2) {
16658
- if (value === void 0 || value === null) {
16695
+ if (value === void 0) {
16696
+ return true;
16697
+ }
16698
+ if (plan2.keepsEmpty) {
16699
+ return false;
16700
+ }
16701
+ if (value === null) {
16659
16702
  return true;
16660
16703
  }
16661
16704
  if (value !== "") {
@@ -16664,6 +16707,9 @@ function isAbsent(value, plan2) {
16664
16707
  if (plan2.isUnion) {
16665
16708
  return true;
16666
16709
  }
16710
+ if (plan2.blankIsValue) {
16711
+ return plan2.absorbsBlank;
16712
+ }
16667
16713
  return plan2.coreType !== "string" || plan2.absorbsBlank;
16668
16714
  }
16669
16715
  function normalizeAbsence(value, plan2) {
@@ -16951,6 +16997,9 @@ function extendPrototype() {
16951
16997
  const existing = this.meta()?.examples ?? [];
16952
16998
  return this.meta({ examples: [...existing, value] });
16953
16999
  };
17000
+ proto.required = function required() {
17001
+ return this.nonoptional();
17002
+ };
16954
17003
  proto.shared = function shared() {
16955
17004
  return this.meta({ frShared: true });
16956
17005
  };