@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.
- package/ai-docs/instructions/service-code-format/02-zod-types.md +59 -15
- package/ai-docs/instructions/service-code-format/16-gotchas.md +4 -0
- package/dist/cli.js +57 -8
- package/dist/cli.js.map +2 -2
- package/dist/index.js +56 -7
- package/dist/index.js.map +2 -2
- package/dist/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +9 -4
- package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +12 -0
- package/package.json +1 -1
- package/runtime/index.js +56 -7
- package/runtime/index.js.map +2 -2
- package/runtime/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +9 -4
- package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +12 -0
|
@@ -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
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
164
|
-
|
|
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
|
-
|
|
168
|
-
|
|
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
|
-
|
|
171
|
-
|
|
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
|
|
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.
|
|
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 } =
|
|
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
|
|
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
|
|
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
|
};
|