simpler-forms 0.1.0-alpha.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 (76) hide show
  1. package/LICENSE.md +21 -0
  2. package/README.md +111 -0
  3. package/dist/src/decorators/index.d.ts +4 -0
  4. package/dist/src/decorators/index.js +7 -0
  5. package/dist/src/decorators/index.js.map +1 -0
  6. package/dist/src/decorators/meta.d.ts +22 -0
  7. package/dist/src/decorators/meta.js +35 -0
  8. package/dist/src/decorators/meta.js.map +1 -0
  9. package/dist/src/decorators/shared.d.ts +49 -0
  10. package/dist/src/decorators/shared.js +149 -0
  11. package/dist/src/decorators/shared.js.map +1 -0
  12. package/dist/src/decorators/ui.d.ts +41 -0
  13. package/dist/src/decorators/ui.js +106 -0
  14. package/dist/src/decorators/ui.js.map +1 -0
  15. package/dist/src/decorators/validation.d.ts +25 -0
  16. package/dist/src/decorators/validation.js +91 -0
  17. package/dist/src/decorators/validation.js.map +1 -0
  18. package/dist/src/emitter.d.ts +15 -0
  19. package/dist/src/emitter.js +224 -0
  20. package/dist/src/emitter.js.map +1 -0
  21. package/dist/src/emitters/block-index.d.ts +4 -0
  22. package/dist/src/emitters/block-index.js +19 -0
  23. package/dist/src/emitters/block-index.js.map +1 -0
  24. package/dist/src/emitters/block-ui.d.ts +18 -0
  25. package/dist/src/emitters/block-ui.js +203 -0
  26. package/dist/src/emitters/block-ui.js.map +1 -0
  27. package/dist/src/emitters/field-occurrences.d.ts +18 -0
  28. package/dist/src/emitters/field-occurrences.js +237 -0
  29. package/dist/src/emitters/field-occurrences.js.map +1 -0
  30. package/dist/src/emitters/overlay.d.ts +16 -0
  31. package/dist/src/emitters/overlay.js +449 -0
  32. package/dist/src/emitters/overlay.js.map +1 -0
  33. package/dist/src/emitters/override-condition.d.ts +12 -0
  34. package/dist/src/emitters/override-condition.js +25 -0
  35. package/dist/src/emitters/override-condition.js.map +1 -0
  36. package/dist/src/index.d.ts +51 -0
  37. package/dist/src/index.js +55 -0
  38. package/dist/src/index.js.map +1 -0
  39. package/dist/src/lib.d.ts +361 -0
  40. package/dist/src/lib.js +194 -0
  41. package/dist/src/lib.js.map +1 -0
  42. package/dist/src/linter.d.ts +1 -0
  43. package/dist/src/linter.js +337 -0
  44. package/dist/src/linter.js.map +1 -0
  45. package/dist/src/model.d.ts +134 -0
  46. package/dist/src/model.js +203 -0
  47. package/dist/src/model.js.map +1 -0
  48. package/dist/src/public.d.ts +33 -0
  49. package/dist/src/public.js +40 -0
  50. package/dist/src/public.js.map +1 -0
  51. package/dist/src/validate.d.ts +15 -0
  52. package/dist/src/validate.js +737 -0
  53. package/dist/src/validate.js.map +1 -0
  54. package/lib/main.tsp +4 -0
  55. package/lib/meta.tsp +33 -0
  56. package/lib/types.tsp +134 -0
  57. package/lib/ui.tsp +78 -0
  58. package/lib/validation.tsp +134 -0
  59. package/package.json +54 -0
  60. package/src/decorators/index.ts +6 -0
  61. package/src/decorators/meta.ts +52 -0
  62. package/src/decorators/shared.ts +187 -0
  63. package/src/decorators/ui.ts +192 -0
  64. package/src/decorators/validation.ts +220 -0
  65. package/src/emitter.ts +272 -0
  66. package/src/emitters/block-index.ts +24 -0
  67. package/src/emitters/block-ui.ts +254 -0
  68. package/src/emitters/field-occurrences.ts +345 -0
  69. package/src/emitters/overlay.ts +596 -0
  70. package/src/emitters/override-condition.ts +37 -0
  71. package/src/index.ts +59 -0
  72. package/src/lib.ts +195 -0
  73. package/src/linter.ts +380 -0
  74. package/src/model.ts +400 -0
  75. package/src/public.ts +94 -0
  76. package/src/validate.ts +887 -0
@@ -0,0 +1,187 @@
1
+ import type {
2
+ DecoratorContext,
3
+ Model,
4
+ ModelProperty,
5
+ Scalar,
6
+ Type,
7
+ Value,
8
+ } from "@typespec/compiler";
9
+ import { isArrayModelType, serializeValueAsJson } from "@typespec/compiler";
10
+ import { $id as $jsonSchemaId } from "@typespec/json-schema";
11
+ import { reportDiagnostic } from "../lib.js";
12
+ import { rememberConditionSourceModel } from "../model.js";
13
+
14
+ export type Ctx = DecoratorContext;
15
+
16
+ /**
17
+ * `valueof <Model>` arrives as a TypeSpec ObjectValue with parent back-references,
18
+ * so it cannot be serialized directly. Convert to plain JS at the boundary.
19
+ */
20
+ export function plain(ctx: DecoratorContext, value: unknown): unknown {
21
+ const v = value as Value;
22
+ if (
23
+ v &&
24
+ typeof v === "object" &&
25
+ "entityKind" in v &&
26
+ (v as any).entityKind === "Value"
27
+ ) {
28
+ return serializeValueAsJson(ctx.program, v, (v as any).type);
29
+ }
30
+ return value;
31
+ }
32
+
33
+ export function resolvedArgumentProperty(
34
+ ctx: Ctx,
35
+ index: number,
36
+ ): ModelProperty | undefined {
37
+ const target = ctx.getArgumentTarget(index);
38
+ if (!target || (target as any).entityKind) return undefined;
39
+ const node = target as Parameters<
40
+ typeof ctx.program.checker.getTypeForNode
41
+ >[0];
42
+ const resolved = ctx.program.checker.getTypeForNode(node);
43
+ return resolved.kind === "ModelProperty" ? resolved : undefined;
44
+ }
45
+
46
+ /** Store a single value keyed by target. */
47
+ export function set(ctx: Ctx, key: symbol, target: Type, value: unknown): void {
48
+ ctx.program.stateMap(key).set(target, value);
49
+ }
50
+
51
+ /** Append to a list keyed by target. */
52
+ export function push(
53
+ ctx: Ctx,
54
+ key: symbol,
55
+ target: Type,
56
+ value: unknown,
57
+ ): void {
58
+ const map = ctx.program.stateMap(key);
59
+ const existing = (map.get(target) as unknown[] | undefined) ?? [];
60
+ existing.push(value);
61
+ map.set(target, existing);
62
+ }
63
+
64
+ // --- identity -------------------------------------------------------------
65
+
66
+ /**
67
+ * A block's `$id`, relative to the bank's base URI. The base is declared once with
68
+ * `@jsonSchema("<base>")` on the bank namespace, so it is a publishing decision in
69
+ * the specs rather than a constant in this library.
70
+ */
71
+ export const blockSchemaRef = (id: string) => `${id}/schema.json`;
72
+
73
+ /**
74
+ * Delegate to the stock JSON Schema library, which resolves this relative id
75
+ * against the namespace base and uses it for both `$id` and every `$ref` target.
76
+ */
77
+ export function publishAs(ctx: Ctx, target: Model | Scalar, id: string): void {
78
+ $jsonSchemaId(ctx as any, target as any, blockSchemaRef(id));
79
+ }
80
+
81
+ // --- value marshalling ----------------------------------------------------
82
+
83
+ /** Peel one layer of TypeSpec value wrapping. */
84
+ export function unwrap(v: unknown): unknown {
85
+ const o = v as any;
86
+ if (
87
+ o &&
88
+ typeof o === "object" &&
89
+ "entityKind" in o &&
90
+ o.entityKind === "Value" &&
91
+ "value" in o
92
+ ) {
93
+ return o.value;
94
+ }
95
+ return v;
96
+ }
97
+
98
+ /** An enum member argument arrives as the member; take its name. */
99
+ export function enumName(v: unknown): string {
100
+ const m = unwrap(v);
101
+ if (m && typeof m === "object" && "name" in (m as any))
102
+ return String((m as any).name);
103
+ return String(m);
104
+ }
105
+
106
+ /**
107
+ * Resolve a decorator argument to a plain JSON literal. Enum members yield their
108
+ * wire value, so a comparison in an emitted schema is a string rather than a
109
+ * compiler object with parent back-references.
110
+ */
111
+ export function literal(v: unknown): string | number | boolean | null {
112
+ const u = unwrap(v) as any;
113
+ if (u === null || u === undefined) return null;
114
+ if (typeof u !== "object") return u;
115
+ if (u.kind === "EnumMember" || ("name" in u && "enum" in u)) {
116
+ return (u.value ?? u.name) as string | number;
117
+ }
118
+ if ("value" in u) return literal(u.value);
119
+ if ("name" in u) return String(u.name);
120
+ return String(u);
121
+ }
122
+
123
+ // --- conditions -----------------------------------------------------------
124
+ // Shared by UI (visibleWhen, enabledWhen, readOnlyWhen) and Validation
125
+ // (requiredWhen, constraintsWhen), so neither namespace owns them.
126
+
127
+ /**
128
+ * `source` is a ModelProperty passed as `Model.prop` at the call site. It is reduced
129
+ * to plain data here so no emitter ever handles a compiler object.
130
+ */
131
+ export function condition(source: ModelProperty, equals: unknown) {
132
+ const t = source.type as any;
133
+ return {
134
+ operator: "equals" as const,
135
+ sourcePath: [source.name],
136
+ sourceIsArray: t?.kind === "Model" && !!t.indexer,
137
+ value: literal(equals),
138
+ };
139
+ }
140
+
141
+ export function countCondition(
142
+ ctx: Ctx,
143
+ target: ModelProperty,
144
+ source: ModelProperty,
145
+ minimum: number,
146
+ ) {
147
+ let valid = true;
148
+ const resolvedSource = resolvedArgumentProperty(ctx, 0) ?? source;
149
+ if (
150
+ resolvedSource.model &&
151
+ target.model &&
152
+ resolvedSource.model !== target.model
153
+ ) {
154
+ reportDiagnostic(ctx.program, {
155
+ code: "condition-source-not-sibling",
156
+ target,
157
+ format: { source: resolvedSource.name, target: target.name },
158
+ });
159
+ valid = false;
160
+ }
161
+ if (source.type.kind !== "Model" || !isArrayModelType(source.type)) {
162
+ reportDiagnostic(ctx.program, {
163
+ code: "condition-count-source-not-array",
164
+ target,
165
+ format: { source: source.name },
166
+ });
167
+ valid = false;
168
+ }
169
+ const normalizedMinimum = Number(literal(minimum));
170
+ if (!Number.isInteger(normalizedMinimum) || normalizedMinimum <= 0) {
171
+ reportDiagnostic(ctx.program, {
172
+ code: "condition-count-minimum-invalid",
173
+ target,
174
+ format: { minimum: String(normalizedMinimum) },
175
+ });
176
+ valid = false;
177
+ }
178
+ if (!valid) return undefined;
179
+ const result = {
180
+ operator: "countAtLeast" as const,
181
+ sourcePath: [source.name],
182
+ sourceIsArray: true,
183
+ minimum: normalizedMinimum,
184
+ };
185
+ rememberConditionSourceModel(result, resolvedSource.model);
186
+ return result;
187
+ }
@@ -0,0 +1,192 @@
1
+ import type { Enum, Model, ModelProperty, Scalar } from "@typespec/compiler";
2
+ import { $summary } from "@typespec/compiler";
3
+ import { stateKeys } from "../lib.js";
4
+ import {
5
+ type Ctx,
6
+ condition,
7
+ countCondition,
8
+ enumName,
9
+ literal,
10
+ plain,
11
+ push,
12
+ set,
13
+ } from "./shared.js";
14
+
15
+ // --- sections -------------------------------------------------------------
16
+
17
+ export const $sections = (ctx: Ctx, target: Model, sections: Enum) =>
18
+ set(ctx, stateKeys.sections, target, sections);
19
+
20
+ /**
21
+ * `valueof EnumMember` arrives as a value, not the member type, so resolve the
22
+ * member's name and label here rather than in the emitters.
23
+ */
24
+ export const $section = (ctx: Ctx, target: ModelProperty, section: unknown) =>
25
+ set(ctx, stateKeys.section, target, sectionRef(section));
26
+
27
+ export function sectionRef(v: unknown): { name: string; label?: string } {
28
+ const m = v as any;
29
+ if (m && typeof m === "object") {
30
+ if (m.name)
31
+ return {
32
+ name: String(m.name),
33
+ label: m.value ? String(m.value) : undefined,
34
+ };
35
+ if (m.value?.name) {
36
+ return {
37
+ name: String(m.value.name),
38
+ label: m.value.value ? String(m.value.value) : undefined,
39
+ };
40
+ }
41
+ }
42
+ return { name: String(v) };
43
+ }
44
+
45
+ // --- form-scoped overrides ------------------------------------------------
46
+
47
+ function overridePlain(value: unknown): unknown {
48
+ const candidate = value as any;
49
+ if (
50
+ candidate &&
51
+ typeof candidate === "object" &&
52
+ candidate.entityKind === "Value"
53
+ ) {
54
+ return literal(candidate);
55
+ }
56
+ if (Array.isArray(value)) return value.map(overridePlain);
57
+ if (value && typeof value === "object") {
58
+ return Object.fromEntries(
59
+ Object.entries(value).map(([key, nested]) => [
60
+ key,
61
+ overridePlain(nested),
62
+ ]),
63
+ );
64
+ }
65
+ return value;
66
+ }
67
+
68
+ export const $overrides = (
69
+ ctx: Ctx,
70
+ target: Model | ModelProperty,
71
+ patch: unknown,
72
+ ) => set(ctx, stateKeys.overrides, target, overridePlain(plain(ctx, patch)));
73
+
74
+ // --- presentation ---------------------------------------------------------
75
+
76
+ /**
77
+ * A field label. Also delegated to `@summary`, which the JSON Schema emitter maps to
78
+ * `title` -- so the canonical schema carries the label without this library emitting
79
+ * any schema keyword itself.
80
+ */
81
+ export const $label = (
82
+ ctx: Ctx,
83
+ target: Model | Scalar | ModelProperty,
84
+ text: string,
85
+ ) => {
86
+ set(ctx, stateKeys.label, target, text);
87
+ $summary(ctx as any, target as any, text);
88
+ };
89
+
90
+ /**
91
+ * Secondary guidance shown with the field. Distinct from the doc comment, which is the
92
+ * question's own description: help text is what a form says *about asking it here*.
93
+ */
94
+ export const $helpText = (ctx: Ctx, target: ModelProperty, text: string) =>
95
+ set(ctx, stateKeys.helpText, target, text);
96
+
97
+ export const $widget = (ctx: Ctx, target: ModelProperty, widget: unknown) =>
98
+ set(ctx, stateKeys.widget, target, enumName(widget));
99
+
100
+ export const $encodedCheckboxGroup = (
101
+ ctx: Ctx,
102
+ target: ModelProperty,
103
+ contract: unknown,
104
+ ) => {
105
+ set(ctx, stateKeys.widget, target, "EncodedCheckboxGroup");
106
+ set(ctx, stateKeys.encodedCheckboxGroup, target, plain(ctx, contract));
107
+ };
108
+
109
+ export const $order = (ctx: Ctx, target: Model, ...props: ModelProperty[]) =>
110
+ set(
111
+ ctx,
112
+ stateKeys.order,
113
+ target,
114
+ props.map((p) => p.name),
115
+ );
116
+
117
+ export const $omit = (ctx: Ctx, target: ModelProperty) =>
118
+ set(ctx, stateKeys.omit, target, true);
119
+
120
+ export const $readOnly = (ctx: Ctx, target: ModelProperty) =>
121
+ set(ctx, stateKeys.readOnly, target, true);
122
+
123
+ // --- conditional behavior -------------------------------------------------
124
+
125
+ export const $visibleWhen = (
126
+ ctx: Ctx,
127
+ target: ModelProperty,
128
+ source: ModelProperty,
129
+ equals: unknown,
130
+ ) => push(ctx, stateKeys.visibleWhen, target, condition(source, equals));
131
+
132
+ export const $enabledWhen = (
133
+ ctx: Ctx,
134
+ target: ModelProperty,
135
+ source: ModelProperty,
136
+ equals: unknown,
137
+ ) => push(ctx, stateKeys.enabledWhen, target, condition(source, equals));
138
+
139
+ export const $enabledWhenAny = (
140
+ ctx: Ctx,
141
+ target: ModelProperty,
142
+ source: ModelProperty,
143
+ ...equals: unknown[]
144
+ ) => {
145
+ const base = condition(source, null);
146
+ push(ctx, stateKeys.enabledWhen, target, {
147
+ operator: "in",
148
+ sourcePath: base.sourcePath,
149
+ sourceIsArray: base.sourceIsArray,
150
+ values: equals.map(literal),
151
+ });
152
+ };
153
+
154
+ export const $enabledWhenCount = (
155
+ ctx: Ctx,
156
+ target: ModelProperty,
157
+ source: ModelProperty,
158
+ minimum: number,
159
+ ) => {
160
+ const count = countCondition(ctx, target, source, minimum);
161
+ if (count) push(ctx, stateKeys.enabledWhen, target, count);
162
+ };
163
+
164
+ /**
165
+ * Enable a field once a sibling list reaches capacity, while keeping an already-saved
166
+ * value operable if the list later falls below that threshold. This is the narrow
167
+ * disjunction needed by overflow attachment controls; it deliberately does not expose
168
+ * an arbitrary expression AST.
169
+ */
170
+ export const $enabledWhenCountOrPresent = (
171
+ ctx: Ctx,
172
+ target: ModelProperty,
173
+ source: ModelProperty,
174
+ minimum: number,
175
+ ) => {
176
+ const count = countCondition(ctx, target, source, minimum);
177
+ if (!count) return;
178
+ push(ctx, stateKeys.enabledWhen, target, {
179
+ operator: "any",
180
+ predicates: [
181
+ count,
182
+ { operator: "present", sourcePath: [target.name], sourceIsArray: false },
183
+ ],
184
+ });
185
+ };
186
+
187
+ export const $readOnlyWhen = (
188
+ ctx: Ctx,
189
+ target: ModelProperty,
190
+ source: ModelProperty,
191
+ equals: unknown,
192
+ ) => push(ctx, stateKeys.readOnlyWhen, target, condition(source, equals));
@@ -0,0 +1,220 @@
1
+ import type { Model, ModelProperty } from "@typespec/compiler";
2
+ import { reportDiagnostic, stateKeys } from "../lib.js";
3
+ import {
4
+ type Ctx,
5
+ condition,
6
+ enumName,
7
+ literal,
8
+ plain,
9
+ push,
10
+ set,
11
+ } from "./shared.js";
12
+
13
+ // --- constraints ----------------------------------------------------------
14
+
15
+ export const $validationConstraints = (
16
+ ctx: Ctx,
17
+ target: ModelProperty,
18
+ patch: unknown,
19
+ ) => set(ctx, stateKeys.validationConstraints, target, plain(ctx, patch));
20
+
21
+ export const $exclusiveValues = (
22
+ ctx: Ctx,
23
+ target: ModelProperty,
24
+ ...values: unknown[]
25
+ ) =>
26
+ set(ctx, stateKeys.exclusiveValues, target, [
27
+ ...new Set(values.map(literal)),
28
+ ]);
29
+
30
+ export const $validationConstraintsWhen = (
31
+ ctx: Ctx,
32
+ target: ModelProperty,
33
+ source: ModelProperty,
34
+ equals: unknown,
35
+ patch: unknown,
36
+ ) =>
37
+ push(ctx, stateKeys.validationConstraintsWhen, target, {
38
+ condition: condition(source, equals),
39
+ patch: plain(ctx, patch),
40
+ });
41
+
42
+ // --- conditional requiredness ---------------------------------------------
43
+
44
+ export const $requiredWhen = (
45
+ ctx: Ctx,
46
+ target: ModelProperty,
47
+ source: ModelProperty,
48
+ equals: unknown,
49
+ ) => push(ctx, stateKeys.requiredWhen, target, condition(source, equals));
50
+
51
+ export const $requiredWhenPath = (
52
+ ctx: Ctx,
53
+ target: ModelProperty,
54
+ sourcePath: unknown,
55
+ equals: unknown,
56
+ ) =>
57
+ push(ctx, stateKeys.requiredWhen, target, {
58
+ operator: "equals",
59
+ sourcePath: String(literal(sourcePath)).split("."),
60
+ sourceIsArray: false,
61
+ value: literal(equals),
62
+ });
63
+
64
+ export const $requiredPaths = (
65
+ ctx: Ctx,
66
+ target: Model | ModelProperty,
67
+ ...paths: unknown[]
68
+ ) =>
69
+ set(
70
+ ctx,
71
+ stateKeys.requiredPaths,
72
+ target,
73
+ paths.map((path) => String(literal(path))),
74
+ );
75
+
76
+ export const $requiredPathWhen = (
77
+ ctx: Ctx,
78
+ target: Model | ModelProperty,
79
+ targetPath: unknown,
80
+ sourcePath: unknown,
81
+ equals: unknown,
82
+ ) =>
83
+ push(ctx, stateKeys.requiredPathWhen, target, {
84
+ targetPath: String(literal(targetPath)),
85
+ sourcePath: String(literal(sourcePath)),
86
+ value: literal(equals),
87
+ });
88
+
89
+ /** Record a bounded conditional choice over descendant paths. */
90
+ export const $atLeastOnePathWhenPresent = (
91
+ ctx: Ctx,
92
+ target: Model | ModelProperty,
93
+ sourcePath: unknown,
94
+ ...targetPaths: unknown[]
95
+ ) => {
96
+ const source = String(literal(sourcePath));
97
+ const paths = [...new Set(targetPaths.map((path) => String(literal(path))))];
98
+ if (!source || paths.length < 2 || paths.some((path) => !path)) {
99
+ reportDiagnostic(ctx.program, {
100
+ code: "conditional-at-least-one-path-invalid",
101
+ target,
102
+ format: {
103
+ model: target.name || "an anonymous model",
104
+ paths: paths.join(", ") || "none",
105
+ },
106
+ });
107
+ return;
108
+ }
109
+ push(ctx, stateKeys.atLeastOnePathWhenPresent, target, {
110
+ sourcePath: source,
111
+ targetPaths: paths,
112
+ });
113
+ };
114
+
115
+ /** Record a portable JSON Schema any-of-required constraint on sibling properties. */
116
+ export const $atLeastOneOf = (
117
+ ctx: Ctx,
118
+ target: Model,
119
+ ...properties: ModelProperty[]
120
+ ) => {
121
+ const names = [...new Set(properties.map((property) => property.name))];
122
+ if (
123
+ names.length < 2 ||
124
+ properties.some((property) => property.model !== target)
125
+ ) {
126
+ reportDiagnostic(ctx.program, {
127
+ code: "at-least-one-invalid",
128
+ target,
129
+ format: {
130
+ model: target.name || "an anonymous model",
131
+ properties: names.join(", ") || "none",
132
+ },
133
+ });
134
+ return;
135
+ }
136
+ push(ctx, stateKeys.atLeastOneOf, target, names);
137
+ };
138
+
139
+ export const $notBefore = (
140
+ ctx: Ctx,
141
+ target: ModelProperty,
142
+ source: ModelProperty,
143
+ ) => set(ctx, stateKeys.notBefore, target, source);
144
+
145
+ // --- the positive-decimal-string pair -------------------------------------
146
+ // A Grants.gov budget convention: an amount is carried as a string, and presence of
147
+ // one path makes another required (or requires it to be a positive decimal).
148
+
149
+ export const $requiredPathWhenPositiveDecimalString = (
150
+ ctx: Ctx,
151
+ target: Model | ModelProperty,
152
+ targetPath: unknown,
153
+ sourcePath: unknown,
154
+ ) =>
155
+ push(ctx, stateKeys.requiredPathWhenPositiveDecimalString, target, {
156
+ targetPath: String(literal(targetPath)),
157
+ sourcePath: String(literal(sourcePath)),
158
+ });
159
+
160
+ export const $positiveDecimalStringWhenPathPresent = (
161
+ ctx: Ctx,
162
+ target: Model | ModelProperty,
163
+ targetPath: unknown,
164
+ sourcePath: unknown,
165
+ ) =>
166
+ push(ctx, stateKeys.positiveDecimalStringWhenPathPresent, target, {
167
+ targetPath: String(literal(targetPath)),
168
+ sourcePath: String(literal(sourcePath)),
169
+ });
170
+
171
+ // --- calculation ----------------------------------------------------------
172
+
173
+ export const $computed = (
174
+ ctx: Ctx,
175
+ target: ModelProperty,
176
+ operator: unknown,
177
+ ...refs: ModelProperty[]
178
+ ) =>
179
+ set(ctx, stateKeys.computed, target, {
180
+ operator: enumName(operator),
181
+ refs: refs.map((r) => r.name),
182
+ });
183
+
184
+ export const $computedFrom = (
185
+ ctx: Ctx,
186
+ target: ModelProperty,
187
+ operator: unknown,
188
+ ...paths: unknown[]
189
+ ) =>
190
+ set(ctx, stateKeys.computedFrom, target, {
191
+ operator: enumName(operator),
192
+ paths: paths.map((path) => String(literal(path))),
193
+ });
194
+
195
+ export const $materializeWhenAnySourcePresent = (
196
+ ctx: Ctx,
197
+ target: ModelProperty,
198
+ ) =>
199
+ set(
200
+ ctx,
201
+ stateKeys.calculationMaterialization,
202
+ target,
203
+ "when_any_source_present",
204
+ );
205
+
206
+ export const $evaluationOrder = (
207
+ ctx: Ctx,
208
+ target: ModelProperty,
209
+ order: number,
210
+ ) => set(ctx, stateKeys.evaluationOrder, target, order);
211
+
212
+ /**
213
+ * Field-by-field totalling. Only the source properties are recorded; which field of the
214
+ * block pairs with which is worked out at emission, where the type graph is in view.
215
+ */
216
+ export const $totals = (
217
+ ctx: Ctx,
218
+ target: ModelProperty,
219
+ ...sources: ModelProperty[]
220
+ ) => set(ctx, stateKeys.totals, target, sources);