@20baht/engine 0.3.0 → 0.3.2

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/README.md CHANGED
@@ -18,6 +18,7 @@ on its own when there is no UI to render: a server, a worker, an agent, a render
18
18
  | --- | --- |
19
19
  | Schema types | `FormDefinition`, `WorkflowDefinition`, `FieldDescriptor`, `Rule`, `Registry`, ... |
20
20
  | Field types | the 22 built-in ones (`BUILT_IN_FIELD_TYPES`, `isBuiltInFieldType`; `BUILT_IN_TYPES` / `builtInType(type)` is the table of them: per type its `tag`, `empty` default, `display`, `check` and default `maxLength`) and the app's own: `registry.fieldTypes[type]` is a `FieldTypeSpec` (`tag`, `check`, `display`), found with `fieldTypeSpec(registry, type)`; `validateField` runs its `check`, `displayValue(field, value, options, registry)` its `display` (spec 01 §5.1) |
21
+ | Typed data | `defineForm` / `defineWorkflow` keep a schema's literal types; from them `FormValues<F>` (a form's data as held), `ValidValues<F>` (after validation: a `required` field is never null), `WorkflowValues<W>` (a workflow's data by form name; forms and fields optional, since a rule may hide either). A field type of the app's own names its value in `CustomFieldValues` (declaration merging). Types only: no codegen, nothing at run time |
21
22
  | Rules | `evaluate(workflow, data)` → per-field and per-form state plus the cleaned data, to a fixpoint |
22
23
  | Validation | `validateField`, `validateShownField`, the built-in validators, pattern safety |
23
24
  | Routing | `visibleForms`, `resolveNext`, `walkPath`, `stepFieldStates` (one step's field states, for a run kept on a server), `advanceRun(workflow, { form_name, data }, move)` (where such a run goes once a form step is submitted or an approval step is settled: moved, bounced, ended or stayed; spec 03 §5.1) |
@@ -4,7 +4,7 @@ import type { ApprovalDecision, FieldDescriptor, WorkflowForm } from './types.js
4
4
  * The engine indexes them like authored fields so `<name>.decision` /
5
5
  * `<name>.comment` are rule-addressable, survive `evaluate()`'s output
6
6
  * filter, and get clear-on-skip semantics. Authored fields with the same
7
- * key win (none expected in v1 — approval steps carry no authored fields).
7
+ * key win. An approval step's authored fields are its decider's input, kept by a server (spec 03 §4).
8
8
  */
9
9
  export declare function approvalFields(form: WorkflowForm): FieldDescriptor[];
10
10
  /**
@@ -1,4 +1,4 @@
1
- import type { FormDefinition, UploadedFile, WorkflowDefinition } from './types.js';
1
+ import type { ApprovalDecision, CustomFieldValues, FormDefinition, UploadedFile, WorkflowDefinition } from './types.js';
2
2
  /** The option keys a choice field offers: the literal keys when known, else `string`. */
3
3
  type OptionKey<F> = F extends {
4
4
  readonly options_from: string;
@@ -16,56 +16,124 @@ type DateValue<F> = F extends {
16
16
  } ? [string, string] : F extends {
17
17
  readonly date_mode: 'multiple';
18
18
  } ? string[] : string;
19
- /** The value one descriptor holds in `getData()` (its empty default included). */
20
- type ValueOf<F> = F extends {
19
+ /** A single value, or its empty `null`: a required one that passed validation is never empty. */
20
+ type Maybe<T, Required extends boolean> = Required extends true ? T : T | null;
21
+ /** A field type of the app's own: what `CustomFieldValues` names for it, else `unknown`. */
22
+ type CustomValue<F, Required extends boolean> = F extends {
23
+ readonly type: infer T extends keyof CustomFieldValues;
24
+ } ? Maybe<CustomFieldValues[T], Required> : unknown;
25
+ /**
26
+ * The value one descriptor holds in `getData()` (its empty default included). `Valid`: the
27
+ * value is one that passed validation, so a `required` field has ruled its empty value out.
28
+ */
29
+ type ValueOf<F, Valid extends boolean> = F extends {
21
30
  readonly type: 'text' | 'textarea' | 'markdown' | 'email' | 'password' | 'time' | 'reference';
22
- } ? string | null : F extends {
31
+ } ? Maybe<string, Demanded<F, Valid>> : F extends {
23
32
  readonly type: 'number' | 'currency' | 'range' | 'rating';
24
- } ? number | null : F extends {
33
+ } ? Maybe<number, Demanded<F, Valid>> : F extends {
25
34
  readonly type: 'checkbox' | 'toggle';
26
- } ? boolean : F extends {
35
+ } ? Demanded<F, Valid> extends true ? true : boolean : F extends {
27
36
  readonly type: 'dropdown' | 'radio';
28
- } ? OptionKey<F> | null : F extends {
37
+ } ? Maybe<OptionKey<F>, Demanded<F, Valid>> : F extends {
29
38
  readonly type: 'multiselect';
30
39
  } ? OptionKey<F>[] : F extends {
31
40
  readonly type: 'tags';
32
41
  } ? string[] : F extends {
33
42
  readonly type: 'date';
34
- } ? DateValue<F> | null : F extends {
43
+ } ? Maybe<DateValue<F>, Demanded<F, Valid>> : F extends {
35
44
  readonly type: 'file';
36
45
  } ? F extends {
37
46
  readonly multiple: true;
38
- } ? FileValue<F>[] : FileValue<F> | null : F extends {
47
+ } ? FileValue<F>[] : Maybe<FileValue<F>, Demanded<F, Valid>> : F extends {
39
48
  readonly type: 'repeater';
40
49
  readonly fields: readonly unknown[];
41
- } ? ValuesOf<F['fields'][number]>[] : unknown;
50
+ } ? ValuesOf<F['fields'][number], Valid>[] : CustomValue<F, Demanded<F, Valid>>;
51
+ /** Does the descriptor ask for a value: `required: true`, or a `required` validator. */
52
+ type IsRequired<F> = F extends {
53
+ readonly required: true;
54
+ } ? true : F extends {
55
+ readonly validators: readonly (infer V)[];
56
+ } ? [Extract<V, {
57
+ readonly type: 'required';
58
+ }>] extends [never] ? false : true : false;
59
+ type Demanded<F, Valid extends boolean> = Valid extends true ? IsRequired<F> : false;
42
60
  /** Keyed values of a union of descriptors; static blocks (label, section) carry none. */
43
- type ValuesOf<D> = string extends (D extends {
61
+ type ValuesOf<D, Valid extends boolean> = string extends (D extends {
44
62
  readonly key: infer K;
45
63
  } ? K : never) ? Record<string, unknown> : {
46
64
  -readonly [F in Exclude<D, {
47
65
  readonly type: 'label' | 'section';
48
66
  }> as F extends {
49
67
  readonly key: infer K extends string;
50
- } ? K : never]: ValueOf<F>;
68
+ } ? K : never]: ValueOf<F, Valid>;
51
69
  };
52
70
  /**
53
- * The data a form holds, derived from its descriptors: what `<baht-form>.getData()` returns
54
- * and what `validateSubmission(form, …).data` is. Needs literal descriptor types: declare the
55
- * form with `defineForm({...})` (or `as const`); a form typed as plain `FormDefinition` gives
56
- * `Record<string, unknown>`.
71
+ * The data a form holds, derived from its descriptors: what `<baht-form>.getData()` returns.
72
+ * Needs literal descriptor types: declare the form with `defineForm({...})` (or `as const`);
73
+ * a form typed as plain `FormDefinition` gives `Record<string, unknown>`.
57
74
  *
58
- * text / textarea / markdown / email / password / reference → `string | null`;
75
+ * text / textarea / markdown / email / password / time / reference → `string | null`;
59
76
  * number / currency / range / rating → `number | null`; checkbox / toggle → `boolean`;
60
77
  * dropdown / radio → the option keys `| null` (`string` with `options_from`); multiselect →
61
78
  * option keys `[]`; tags → `string[]`; date → `string`, `[string, string]` (range) or
62
79
  * `string[]` (multiple), `| null`; file → `UploadedFile` with an `uploader` (else `File`),
63
- * `| null`, or an array with `multiple`; repeater → an array of its rows. Inside a workflow,
64
- * a field a rule hides is absent from the data: read those keys as optional there.
80
+ * `| null`, or an array with `multiple`; repeater → an array of its rows; a type of the app's
81
+ * own → what `CustomFieldValues` names `| null`, else `unknown`. For the data of a form that
82
+ * passed validation see `ValidValues`; for a workflow's, `WorkflowValues`.
65
83
  */
66
84
  export type FormValues<F extends {
67
85
  readonly fields: readonly unknown[];
68
- }> = ValuesOf<F['fields'][number]>;
86
+ }> = ValuesOf<F['fields'][number], false>;
87
+ /**
88
+ * The data of a form that passed validation: `validateSubmission(form, body).data` once
89
+ * `valid` is true, and the `data` of `baht-submit`. `FormValues` with the empty value ruled out
90
+ * of every field that is `required` (the flag or the validator): `string`, not `string | null`;
91
+ * a required checkbox or toggle is `true`. Rows of a repeater alike.
92
+ *
93
+ * Only for a form on its own. Inside a workflow a rule can lift `required` or hide the field,
94
+ * so nothing is ruled out there: `WorkflowValues`.
95
+ */
96
+ export type ValidValues<F extends {
97
+ readonly fields: readonly unknown[];
98
+ }> = ValuesOf<F['fields'][number], true>;
99
+ /** An approval step's own two values (spec 03 §4), beside its authored fields. */
100
+ interface ApprovalValues {
101
+ decision: ApprovalDecision | null;
102
+ comment: string | null;
103
+ }
104
+ type StepValues<F> = F extends {
105
+ readonly fields: readonly unknown[];
106
+ } ? F extends {
107
+ readonly kind: 'approval';
108
+ } ? Omit<ApprovalValues, keyof FormValues<F>> & FormValues<F> : FormValues<F> : never;
109
+ type Flat<T> = {
110
+ [K in keyof T]: T[K];
111
+ };
112
+ /**
113
+ * The data of one form of a workflow, as `<baht-workflow>` emits it and the validator returns
114
+ * it: a field a rule hides is absent, so every key is optional, and `required` rules nothing
115
+ * out (a rule can lift it). An approval step also holds `decision` and `comment`.
116
+ */
117
+ export type WorkflowFormValues<F extends {
118
+ readonly fields: readonly unknown[];
119
+ }> = Flat<Partial<StepValues<F>>>;
120
+ /**
121
+ * The data of a workflow, `{ formName: { key: value } }`: what `<baht-workflow>.getData()`
122
+ * returns and `validateSubmission(workflow, body).data` is. A form a rule skips is absent, so
123
+ * each form is optional too. Needs literal types (`defineWorkflow`); a plain
124
+ * `WorkflowDefinition` gives `Record<string, Record<string, unknown>>`.
125
+ */
126
+ export type WorkflowValues<W extends {
127
+ readonly forms: readonly unknown[];
128
+ }> = string extends (W['forms'][number] extends {
129
+ readonly form_name: infer N;
130
+ } ? N : never) ? Record<string, Record<string, unknown>> : {
131
+ -readonly [F in W['forms'][number] as F extends {
132
+ readonly form_name: infer N extends string;
133
+ } ? N : never]?: F extends {
134
+ readonly fields: readonly unknown[];
135
+ } ? WorkflowFormValues<F> : never;
136
+ };
69
137
  /**
70
138
  * Returns `form` unchanged, typed with its literal keys, option keys and field types (a
71
139
  * `const` type parameter), so `FormValues<typeof form>` is exact while `form` stays
@@ -73,6 +141,6 @@ export type FormValues<F extends {
73
141
  * `FormDefinition` does not accept.
74
142
  */
75
143
  export declare function defineForm<const F extends FormDefinition>(form: F): F;
76
- /** `defineForm` for a workflow: `FormValues<(typeof wf)['forms'][0]>` is exact. */
144
+ /** `defineForm` for a workflow: `WorkflowValues<typeof wf>` is exact. */
77
145
  export declare function defineWorkflow<const W extends WorkflowDefinition>(workflow: W): W;
78
146
  export {};
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  export * from './types.js';
2
- export { defineForm, defineWorkflow, type FormValues } from './form-values.js';
2
+ export { defineForm, defineWorkflow, type FormValues, type ValidValues, type WorkflowFormValues, type WorkflowValues, } from './form-values.js';
3
3
  export { defaultValue } from './defaults.js';
4
4
  export { BUILT_IN_FIELD_TYPES, fieldTypeSpec, isBuiltInFieldType } from './field-types.js';
5
5
  export { BUILT_IN_TYPES, builtInType, type BuiltInTypeSpec } from './built-in-types.js';
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  export * from './types.js';
2
- export { defineForm, defineWorkflow } from './form-values.js';
2
+ export { defineForm, defineWorkflow, } from './form-values.js';
3
3
  export { defaultValue } from './defaults.js';
4
4
  export { BUILT_IN_FIELD_TYPES, fieldTypeSpec, isBuiltInFieldType } from './field-types.js';
5
5
  export { BUILT_IN_TYPES, builtInType } from './built-in-types.js';
package/dist/types.d.ts CHANGED
@@ -10,6 +10,18 @@
10
10
  */
11
11
  export interface CustomFieldTypes {
12
12
  }
13
+ /**
14
+ * The value a field type of the app's own holds, for `FormValues` (same merging, same names):
15
+ *
16
+ * declare module '@20baht/engine' {
17
+ * interface CustomFieldValues { account_number: string }
18
+ * }
19
+ *
20
+ * A type with no entry here reads as `unknown`. Write the value alone: `| null` (the empty
21
+ * value) is added for a field that is not required.
22
+ */
23
+ export interface CustomFieldValues {
24
+ }
13
25
  /** A built-in control type, or one the app registered. */
14
26
  export type FieldType = BuiltInFieldType | keyof CustomFieldTypes;
15
27
  /** Control types supported by v1 (spec 01 §2). */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@20baht/engine",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=20.19.0"