simpler-forms 0.1.0-alpha.1 → 0.2.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 (89) hide show
  1. package/README.md +300 -76
  2. package/dist/src/casing.d.ts +43 -0
  3. package/dist/src/casing.js +146 -0
  4. package/dist/src/casing.js.map +1 -0
  5. package/dist/src/decorators/index.d.ts +1 -0
  6. package/dist/src/decorators/index.js +1 -0
  7. package/dist/src/decorators/index.js.map +1 -1
  8. package/dist/src/decorators/mapping.d.ts +17 -0
  9. package/dist/src/decorators/mapping.js +122 -0
  10. package/dist/src/decorators/mapping.js.map +1 -0
  11. package/dist/src/decorators/meta.d.ts +15 -5
  12. package/dist/src/decorators/meta.js +31 -4
  13. package/dist/src/decorators/meta.js.map +1 -1
  14. package/dist/src/decorators/shared.d.ts +2 -2
  15. package/dist/src/decorators/shared.js.map +1 -1
  16. package/dist/src/decorators/ui.d.ts +14 -12
  17. package/dist/src/decorators/ui.js +20 -43
  18. package/dist/src/decorators/ui.js.map +1 -1
  19. package/dist/src/emitter.d.ts +8 -0
  20. package/dist/src/emitter.js +55 -16
  21. package/dist/src/emitter.js.map +1 -1
  22. package/dist/src/emitters/block-ui.d.ts +14 -3
  23. package/dist/src/emitters/block-ui.js +81 -119
  24. package/dist/src/emitters/block-ui.js.map +1 -1
  25. package/dist/src/emitters/layout-ui.d.ts +12 -0
  26. package/dist/src/emitters/layout-ui.js +225 -0
  27. package/dist/src/emitters/layout-ui.js.map +1 -0
  28. package/dist/src/emitters/overlay.d.ts +10 -8
  29. package/dist/src/emitters/overlay.js +30 -105
  30. package/dist/src/emitters/overlay.js.map +1 -1
  31. package/dist/src/forms.d.ts +23 -0
  32. package/dist/src/forms.js +54 -0
  33. package/dist/src/forms.js.map +1 -0
  34. package/dist/src/index.d.ts +22 -8
  35. package/dist/src/index.js +17 -3
  36. package/dist/src/index.js.map +1 -1
  37. package/dist/src/layout.d.ts +50 -0
  38. package/dist/src/layout.js +397 -0
  39. package/dist/src/layout.js.map +1 -0
  40. package/dist/src/lib.d.ts +585 -39
  41. package/dist/src/lib.js +258 -15
  42. package/dist/src/lib.js.map +1 -1
  43. package/dist/src/linter.js +8 -43
  44. package/dist/src/linter.js.map +1 -1
  45. package/dist/src/mapping-from.d.ts +21 -0
  46. package/dist/src/mapping-from.js +169 -0
  47. package/dist/src/mapping-from.js.map +1 -0
  48. package/dist/src/mapping.d.ts +65 -0
  49. package/dist/src/mapping.js +209 -0
  50. package/dist/src/mapping.js.map +1 -0
  51. package/dist/src/model.d.ts +143 -23
  52. package/dist/src/model.js +108 -21
  53. package/dist/src/model.js.map +1 -1
  54. package/dist/src/public.d.ts +20 -4
  55. package/dist/src/public.js +28 -4
  56. package/dist/src/public.js.map +1 -1
  57. package/dist/src/validate.d.ts +2 -1
  58. package/dist/src/validate.js +208 -58
  59. package/dist/src/validate.js.map +1 -1
  60. package/lib/main.tsp +1 -0
  61. package/lib/mapping.tsp +173 -0
  62. package/lib/meta.tsp +25 -6
  63. package/lib/types.tsp +24 -63
  64. package/lib/ui.tsp +34 -17
  65. package/package.json +17 -11
  66. package/src/casing.ts +172 -0
  67. package/src/decorators/index.ts +1 -0
  68. package/src/decorators/mapping.ts +200 -0
  69. package/src/decorators/meta.ts +56 -13
  70. package/src/decorators/shared.ts +6 -1
  71. package/src/decorators/ui.ts +43 -59
  72. package/src/emitter.ts +76 -16
  73. package/src/emitters/block-ui.ts +83 -135
  74. package/src/emitters/layout-ui.ts +280 -0
  75. package/src/emitters/overlay.ts +43 -116
  76. package/src/forms.ts +82 -0
  77. package/src/index.ts +17 -3
  78. package/src/layout.ts +592 -0
  79. package/src/lib.ts +264 -15
  80. package/src/linter.ts +17 -49
  81. package/src/mapping-from.ts +216 -0
  82. package/src/mapping.ts +358 -0
  83. package/src/model.ts +287 -46
  84. package/src/public.ts +60 -6
  85. package/src/validate.ts +221 -60
  86. package/dist/src/emitters/override-condition.d.ts +0 -12
  87. package/dist/src/emitters/override-condition.js +0 -25
  88. package/dist/src/emitters/override-condition.js.map +0 -1
  89. package/src/emitters/override-condition.ts +0 -37
package/lib/meta.tsp CHANGED
@@ -12,22 +12,41 @@ namespace SimplerForms.Meta;
12
12
  * A question's portable identity. The `entity` field and the first segment of `id`
13
13
  * describe the same thing and must agree.
14
14
  */
15
- extern dec question(target: Model | Scalar, meta: valueof QuestionMeta);
15
+ extern dec question(target: Model | Scalar | Enum, meta: valueof QuestionMeta);
16
16
 
17
- /** A form's identity, lifecycle, and the paper form it mirrors. */
17
+ /**
18
+ * A form an applicant opens: the data it collects and submits. Publishes the model's JSON
19
+ * Schema under `forms/<id>/`, and is what its mappings and validation hang off. Its fields'
20
+ * `@UI.*` decorators lay it out, unless a `@UI.layout` model presents it.
21
+ */
18
22
  extern dec form(target: Model, meta: valueof FormMeta);
19
23
 
20
24
  /**
21
- * Catalogue markers. Applies to a question, and also to a bare constrained scalar that
22
- * carries no question identity of its own — a money-shaped string, a bounded count.
25
+ * Declare the tags a program catalogues its questions by, as `@UI.widgets` declares its
26
+ * widgets. The set belongs to the consuming program, not to this library: declare it once,
27
+ * on any namespace, and `@Meta.tag` accepts its members.
28
+ */
29
+ extern dec tags(target: Namespace, tags: Enum);
30
+
31
+ /**
32
+ * Declare the entities a program's questions are asked about, as `@Meta.tags` declares its
33
+ * tags. A question's `entity` is a member of this set.
34
+ */
35
+ extern dec entities(target: Namespace, entities: Enum);
36
+
37
+ /**
38
+ * Catalogue markers, each a member of an enum declared with `@Meta.tags`. Applies to a
39
+ * question, and also to a bare constrained scalar that carries no question identity of its
40
+ * own — a money-shaped string, a bounded count. A member's string value, when it has one, is
41
+ * the tag emitted; otherwise its name is.
23
42
  */
24
- extern dec tag(target: Model | Scalar, ...tags: valueof TagName[]);
43
+ extern dec tag(target: Model | Scalar | Enum, ...tags: EnumMember[]);
25
44
 
26
45
  /**
27
46
  * Why a block or field exists in a response. Deliberately separate from semantic
28
47
  * question identity, capture mechanism, UI behavior, and delivery targets.
29
48
  */
30
49
  extern dec role(
31
- target: Model | Scalar | ModelProperty,
50
+ target: Model | Scalar | Enum | ModelProperty,
32
51
  role: valueof ResponseRole
33
52
  );
package/lib/types.tsp CHANGED
@@ -36,32 +36,34 @@ model QuestionMeta {
36
36
  id: string;
37
37
 
38
38
  /**
39
- * The entity this question is asked *about* — the `entity` half of the id.
40
- * Declared as an enum member rather than inferred from the id so it autocompletes
41
- * and is checked; `entity-id-mismatch` reports the two disagreeing.
39
+ * The entity this question is asked *about* — the `entity` half of the id. A member of an
40
+ * enum declared with `@Meta.entities`, rather than inferred from the id, so it
41
+ * autocompletes and is checked; `entity-id-mismatch` reports the two disagreeing.
42
42
  *
43
43
  * Optional for now so the fold lands without rewriting every existing question in
44
44
  * one pass. It is present on all 279 questions in practice, so a linter rule should
45
45
  * promote it to mandatory once they carry it.
46
46
  */
47
- entity?: EntityName;
47
+ entity?: unknown;
48
48
 
49
49
  version?: string;
50
50
  status?: "draft" | "stable" | "deprecated";
51
51
  classification?: BlockClassification;
52
52
  }
53
53
 
54
- /** Portable identity, lifecycle, and source metadata for a form. */
54
+ /**
55
+ * A form's identity. A platform's own identity for the form, such as its name and version
56
+ * in a submission system, belongs to that platform's library, as a decorator of its own on
57
+ * the same model.
58
+ */
55
59
  model FormMeta {
56
- /** Semantic id — e.g. "key-contacts". */
60
+ /** Semantic id — e.g. "key-contacts". Also the published schema's id and directory. */
57
61
  id: string;
58
62
 
59
- legacyFormId?: int32;
60
63
  formName: string;
61
- shortFormName: string;
62
- formVersion: string;
63
- agencyCode?: string;
64
- ombNumber?: string;
64
+
65
+ /** Revision of the form. */
66
+ revision?: string;
65
67
  }
66
68
 
67
69
  /** Source-specific constraints applied where a reusable question is composed into a form. */
@@ -73,58 +75,17 @@ model ValidationConstraints {
73
75
  pattern?: string;
74
76
  }
75
77
 
76
- enum TagName {
77
- address,
78
- phone,
79
- email,
80
- identifier,
81
- name,
82
- title,
83
- person,
84
- organization,
85
- details,
86
- generic,
87
- money,
88
- count,
89
- attachment,
90
- narrative,
91
- date,
92
- role,
93
- }
94
-
95
- enum EntityName {
96
- primaryOrg,
97
- fiscalSponsor,
98
- poc,
99
- principalInvestigator,
100
- authorizedRepresentative,
101
- project,
102
- opportunity,
103
- application,
104
- generic,
105
- }
106
-
107
- /** Mirrors the SGG frontend's WidgetTypes union. */
108
- enum WidgetName {
109
- Attachment,
110
- AttachmentArray,
111
- Checkbox,
112
- EncodedCheckboxGroup,
113
- Text,
114
- TextArea,
115
- Radio,
116
- Select,
117
- MultiSelect,
118
- Print,
119
- PrintAttachment,
120
- FieldList,
121
- Table,
122
- Budget424aSectionA,
123
- Budget424aSectionB,
124
- Budget424aSectionC,
125
- Budget424aSectionD,
126
- Budget424aSectionE,
127
- Budget424aSectionF,
78
+ /**
79
+ * How a condition compares the answer at its source with its value. `exists` takes no value,
80
+ * and `in` takes a list: the answer is one of its entries. `contains` holds when the answer is
81
+ * a list with the value among its entries.
82
+ */
83
+ enum Operator {
84
+ equals,
85
+ notEquals,
86
+ in,
87
+ contains,
88
+ exists,
128
89
  }
129
90
 
130
91
  enum Op {
package/lib/ui.tsp CHANGED
@@ -8,28 +8,45 @@ using TypeSpec.Reflection;
8
8
 
9
9
  namespace SimplerForms.UI;
10
10
 
11
- /** Declare the ordered section set for a block. */
12
- extern dec sections(target: Model, sections: Enum);
13
-
14
- /** Assign a property (and everything under it) to one section. */
15
- extern dec section(target: ModelProperty, section: valueof EnumMember);
11
+ /**
12
+ * This model is a presentation of `form`. Its properties are sections, in order.
13
+ *
14
+ * A property inside a section is one of three things. A field reference
15
+ * (`payee: Form.payee;`) places that field as its model lays it out. A model with
16
+ * `@UI.field` places that field with the changes it lists. A model without `@UI.field` is a
17
+ * new group of only what it lists.
18
+ */
19
+ extern dec layout(target: Model, form: Model);
16
20
 
17
21
  /**
18
- * Form-scoped override table, keyed by dotted path relative to the target.
19
- * Presentation keys stay local to the form. `enabledWhen` may name an exact sibling/root
20
- * response path and equality value when a form applies behavior to a shared question.
21
- * `visibleReadOnly: true` is valid only with `readOnly: true`: it renders a visible control
22
- * backed by a read-only JSON Schema occurrence. Plain `readOnly` retains the target's historic
23
- * hidden/null behavior for technical identifiers.
22
+ * Lay out one field's contents here. Entries inside are relative to the field's type, or
23
+ * its item type for a list. The field's unlisted children follow in their declared order.
24
24
  */
25
- extern dec overrides(
26
- target: Model | ModelProperty,
27
- patch: valueof Record<unknown>
28
- );
25
+ extern dec field(target: ModelProperty, field: ModelProperty);
26
+
27
+ /** Place the referenced field's children here instead of as a group of their own. */
28
+ extern dec flatten(target: ModelProperty);
29
29
 
30
- extern dec label(target: Model | Scalar | ModelProperty, text: valueof string);
30
+ extern dec label(
31
+ target: Model | Scalar | Enum | ModelProperty,
32
+ text: valueof string
33
+ );
31
34
  extern dec helpText(target: ModelProperty, text: valueof string);
32
- extern dec widget(target: ModelProperty, widget: valueof WidgetName);
35
+ /**
36
+ * Declare the widgets a program's renderers provide, as `@versioned` declares its versions.
37
+ * The set belongs to the consuming program, not to this library: declare it once, on any
38
+ * namespace, and `@UI.widget` accepts its members. A member's string value, when it has
39
+ * one, is the name emitted; otherwise its name is.
40
+ */
41
+ extern dec widgets(target: Namespace, widgets: Enum);
42
+
43
+ /**
44
+ * Render the property with a widget declared by `@UI.widgets`. On a property whose type is
45
+ * a question with fields of its own, the widget applies to the group those fields lay out as.
46
+ * On a scalar or model, it is the widget every property of that type renders with unless the
47
+ * property names its own; a scalar passes it to the scalars that extend it.
48
+ */
49
+ extern dec widget(target: ModelProperty | Scalar | Model, widget: EnumMember);
33
50
  /** Render source-approved checkbox choices while preserving one encoded wire value. */
34
51
  extern dec encodedCheckboxGroup(
35
52
  target: ModelProperty,
package/package.json CHANGED
@@ -1,8 +1,14 @@
1
1
  {
2
2
  "name": "simpler-forms",
3
- "version": "0.1.0-alpha.1",
3
+ "version": "0.2.0",
4
4
  "description": "A TypeSpec library for specifying forms once and emitting portable form artifacts.",
5
5
  "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/agilesix/simpler-forms.git"
9
+ },
10
+ "homepage": "https://github.com/agilesix/simpler-forms#readme",
11
+ "bugs": "https://github.com/agilesix/simpler-forms/issues",
6
12
  "type": "module",
7
13
  "main": "dist/src/index.js",
8
14
  "types": "dist/src/index.d.ts",
@@ -24,20 +30,20 @@
24
30
  "node": ">=22"
25
31
  },
26
32
  "peerDependencies": {
27
- "@typespec/compiler": "^1.13.0",
28
- "@typespec/json-schema": "^1.13.0"
33
+ "@typespec/compiler": "^1.16.0",
34
+ "@typespec/json-schema": "^1.16.0"
29
35
  },
30
36
  "devDependencies": {
31
- "@typespec/compiler": "^1.13.0",
32
- "@typespec/json-schema": "^1.13.0",
33
- "@vitest/coverage-v8": "^4.1.11",
37
+ "@eslint/js": "^9.39.5",
38
+ "@typespec/compiler": "^1.18.0",
39
+ "@typespec/json-schema": "^1.18.0",
40
+ "@vitest/coverage-v8": "^4.1.12",
34
41
  "ajv": "^8.20.0",
35
42
  "eslint": "^9.39.5",
36
- "prettier": "^3.4.2",
37
- "typescript": "^5.6.0",
38
- "typescript-eslint": "^8.24.0",
39
- "vitest": "^4.1.11",
40
- "@eslint/js": "^9.20.0"
43
+ "prettier": "^3.10.1",
44
+ "typescript": "^5.9.3",
45
+ "typescript-eslint": "^8.72.2",
46
+ "vitest": "^4.1.12"
41
47
  },
42
48
  "scripts": {
43
49
  "build": "tsc -p .",
package/src/casing.ts ADDED
@@ -0,0 +1,172 @@
1
+ import type { ModelProperty, Namespace, Program } from "@typespec/compiler";
2
+ import { resolveEncodedName } from "@typespec/compiler";
3
+ import { reportDiagnostic } from "./lib.js";
4
+ import { modelProperties } from "./model.js";
5
+
6
+ /** How a property's TypeSpec name becomes its name in every emitted artifact. */
7
+ export type PropertyCasing = "preserve" | "snake";
8
+
9
+ /**
10
+ * `firstName` to `first_name`.
11
+ *
12
+ * A word starts at each capital that follows a lowercase letter or a digit, and at the last
13
+ * capital of a run that a lowercase letter follows, so an acronym is one word: `ombNumber`
14
+ * and `OMBNumber` both become `omb_number`, and `HTTPServer` becomes `http_server`. Digits
15
+ * stay with the word before them, so `street1` and `sf424Version` become `street1` and
16
+ * `sf424_version`. A name that is already snake case is unchanged.
17
+ */
18
+ export function snakeCase(name: string): string {
19
+ return name
20
+ .replace(/([a-z\d])([A-Z])/g, "$1_$2")
21
+ .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
22
+ .toLowerCase();
23
+ }
24
+
25
+ /**
26
+ * The name a property is emitted under.
27
+ *
28
+ * `@encodedName("application/json", ...)` wins over the casing, so a name the rule
29
+ * converts badly can be stated outright.
30
+ */
31
+ export function jsonPropertyName(
32
+ program: Program,
33
+ property: ModelProperty,
34
+ casing: PropertyCasing,
35
+ ): string {
36
+ const encoded = resolveEncodedName(program, property, "application/json");
37
+ if (encoded !== property.name) return encoded;
38
+ return casing === "snake" ? snakeCase(property.name) : property.name;
39
+ }
40
+
41
+ /**
42
+ * Renames properties in a finished artifact.
43
+ *
44
+ * The emitters build every artifact in TypeSpec names, which is also what an author writes in
45
+ * a string path, so the casing is applied once, after everything that resolves a path has run.
46
+ * One table maps each TypeSpec name to its emitted name across the whole program. That keeps
47
+ * renaming independent of where in an artifact a name appears, at the cost of requiring a name
48
+ * to be emitted the same way everywhere it is declared.
49
+ */
50
+ export class Casing {
51
+ private readonly names = new Map<string, string>();
52
+
53
+ constructor(
54
+ program: Program,
55
+ private readonly casing: PropertyCasing,
56
+ ) {
57
+ const declared = new Map<string, ModelProperty>();
58
+ const visit = (namespace: Namespace): void => {
59
+ for (const model of namespace.models.values()) {
60
+ const claimed = new Map<string, ModelProperty>();
61
+ for (const property of modelProperties(model)) {
62
+ const name = jsonPropertyName(program, property, casing);
63
+ const sibling = claimed.get(name);
64
+ if (sibling) {
65
+ reportDiagnostic(program, {
66
+ code: "property-casing-collision",
67
+ target: property,
68
+ format: {
69
+ model: model.name,
70
+ first: sibling.name,
71
+ second: property.name,
72
+ name,
73
+ },
74
+ });
75
+ } else claimed.set(name, property);
76
+
77
+ const elsewhere = declared.get(property.name);
78
+ const previous = this.names.get(property.name);
79
+ if (elsewhere && previous !== name) {
80
+ reportDiagnostic(program, {
81
+ code: "property-casing-inconsistent",
82
+ target: property,
83
+ format: {
84
+ property: property.name,
85
+ name,
86
+ other: `${elsewhere.model?.name}.${elsewhere.name}`,
87
+ otherName: previous!,
88
+ },
89
+ });
90
+ } else if (!elsewhere) {
91
+ declared.set(property.name, property);
92
+ this.names.set(property.name, name);
93
+ }
94
+ }
95
+ }
96
+ for (const child of namespace.namespaces.values()) visit(child);
97
+ };
98
+ visit(program.getGlobalNamespaceType());
99
+ // The stock emitter serializes an `@example` with encoded names already applied.
100
+ for (const name of [...this.names.values()]) this.names.set(name, name);
101
+ }
102
+
103
+ /** The name a property named `key` in TypeSpec is emitted under. */
104
+ name(key: string): string {
105
+ return (
106
+ this.names.get(key) ?? (this.casing === "snake" ? snakeCase(key) : key)
107
+ );
108
+ }
109
+
110
+ /** A JSON Schema or JSON Forms layout. */
111
+ json<T>(node: T): T {
112
+ if (Array.isArray(node)) return node.map((entry) => this.json(entry)) as T;
113
+ if (!isObject(node)) return node;
114
+ return Object.fromEntries(
115
+ Object.entries(node).map(([key, value]) => {
116
+ if (key === "properties" && isObject(value))
117
+ return [key, this.keys(value, (entry) => this.json(entry))];
118
+ if (key === "required" && Array.isArray(value))
119
+ return [key, value.map((name) => this.name(name))];
120
+ if (key === "scope" && typeof value === "string")
121
+ return [
122
+ key,
123
+ value.replace(/(?<=properties\/)[^/]+/g, (name) => this.name(name)),
124
+ ];
125
+ if (key === "examples" || key === "default" || key === "const")
126
+ return [key, this.instance(value)];
127
+ return [key, this.json(value)];
128
+ }),
129
+ ) as T;
130
+ }
131
+
132
+ /** A JSON Pointer such as `/keyContacts/[]/name`. */
133
+ pointer(path: string): string {
134
+ return path
135
+ .split("/")
136
+ .map((token, index) =>
137
+ index === 0 || token === "[]"
138
+ ? token
139
+ : escapePointer(this.name(unescapePointer(token))),
140
+ )
141
+ .join("/");
142
+ }
143
+
144
+ /** Data shaped like the schema, such as an `@example` value. */
145
+ private instance(value: unknown): unknown {
146
+ if (Array.isArray(value)) return value.map((entry) => this.instance(entry));
147
+ return isObject(value)
148
+ ? this.keys(value, (entry) => this.instance(entry))
149
+ : value;
150
+ }
151
+
152
+ private keys(
153
+ value: Record<string, unknown>,
154
+ inner: (entry: unknown) => unknown,
155
+ ): Record<string, unknown> {
156
+ return Object.fromEntries(
157
+ Object.entries(value).map(([name, entry]) => [
158
+ this.name(name),
159
+ inner(entry),
160
+ ]),
161
+ );
162
+ }
163
+ }
164
+
165
+ const isObject = (value: unknown): value is Record<string, unknown> =>
166
+ typeof value === "object" && value !== null && !Array.isArray(value);
167
+
168
+ const unescapePointer = (token: string) =>
169
+ token.replaceAll("~1", "/").replaceAll("~0", "~");
170
+
171
+ const escapePointer = (token: string) =>
172
+ token.replaceAll("~", "~0").replaceAll("/", "~1");
@@ -4,3 +4,4 @@ export { blockSchemaRef } from "./shared.js";
4
4
  export * from "./meta.js";
5
5
  export * from "./ui.js";
6
6
  export * from "./validation.js";
7
+ export * from "./mapping.js";
@@ -0,0 +1,200 @@
1
+ import {
2
+ getNamespaceFullName,
3
+ type Enum,
4
+ type EnumMember,
5
+ type Model,
6
+ type ModelProperty,
7
+ type Namespace,
8
+ } from "@typespec/compiler";
9
+ import { reportDiagnostic, stateKeys } from "../lib.js";
10
+ import type {
11
+ MappingCondition,
12
+ MappingFromLink,
13
+ MappingLink,
14
+ MappingMatch,
15
+ MappingPathLink,
16
+ MappingSelection,
17
+ } from "../model.js";
18
+ import { type Ctx, enumName, push, set } from "./shared.js";
19
+
20
+ export const $targets = (ctx: Ctx, target: Namespace, targets: Enum) =>
21
+ set(ctx, stateKeys.mappingTargets, target, targets);
22
+
23
+ export const $transforms = (ctx: Ctx, target: Namespace, transforms: Enum) =>
24
+ set(ctx, stateKeys.mappingTransformSets, target, transforms);
25
+
26
+ export const $transform = (
27
+ ctx: Ctx,
28
+ target: ModelProperty,
29
+ transform: EnumMember,
30
+ params?: Record<string, unknown>,
31
+ ) =>
32
+ set(ctx, stateKeys.mappingTransform, target, {
33
+ member: transform,
34
+ ...(params ? { params } : {}),
35
+ });
36
+
37
+ /**
38
+ * Accumulated rather than overwritten: one model or property carries a link per mapping.
39
+ * Two links for the same mapping are reported by `$onValidate`, not here, so the check sees
40
+ * every decorator before it decides which one is the duplicate.
41
+ */
42
+ export const $to = (
43
+ ctx: Ctx,
44
+ target: Model | ModelProperty,
45
+ mapping: EnumMember,
46
+ mappedTo: Model | ModelProperty,
47
+ ) =>
48
+ push(ctx, stateKeys.mappedTo, target, {
49
+ mapping,
50
+ mappedTo,
51
+ } satisfies MappingLink);
52
+
53
+ export const $path = (
54
+ ctx: Ctx,
55
+ target: Model,
56
+ mapping: EnumMember,
57
+ sourcePath: string,
58
+ mappedTo: ModelProperty,
59
+ ) =>
60
+ push(ctx, stateKeys.mappingPaths, target, {
61
+ mapping,
62
+ sourcePath,
63
+ mappedTo,
64
+ } satisfies MappingPathLink);
65
+
66
+ export const $match = (
67
+ ctx: Ctx,
68
+ target: ModelProperty,
69
+ cases: Record<string, string | number | boolean>,
70
+ fallback?: ModelProperty | string | number | boolean,
71
+ ) =>
72
+ set(ctx, stateKeys.mappingMatch, target, {
73
+ cases: Object.fromEntries(
74
+ Object.entries(cases).map(([key, value]) => [key, literal(value)]),
75
+ ),
76
+ ...(fallback === undefined
77
+ ? {}
78
+ : {
79
+ default: isField(fallback)
80
+ ? { field: fallback }
81
+ : { value: literal(fallback) },
82
+ }),
83
+ } satisfies MappingMatch);
84
+
85
+ /** A `valueof numeric` arrives as TypeSpec's arbitrary-precision `Numeric`: as a JS number. */
86
+ const literal = (value: unknown) =>
87
+ typeof value === "object" && value !== null && "asNumber" in value
88
+ ? ((value as { asNumber(): number | null }).asNumber() ?? Number.NaN)
89
+ : (value as string | number | boolean);
90
+
91
+ export const $required = (ctx: Ctx, target: ModelProperty) =>
92
+ ctx.program.stateSet(stateKeys.mappingRequired).add(target);
93
+
94
+ export const $when = (
95
+ ctx: Ctx,
96
+ target: ModelProperty,
97
+ source: ModelProperty | Model,
98
+ operator: unknown,
99
+ value?: unknown,
100
+ ) => {
101
+ const name = enumName(operator) as MappingCondition["operator"];
102
+ const picked =
103
+ source.kind === "ModelProperty" ? { source } : selection(source);
104
+ if (!picked) {
105
+ reportDiagnostic(ctx.program, {
106
+ code: "mapping-when-source",
107
+ target: ctx.getArgumentTarget(0) ?? target,
108
+ format: { name: target.name },
109
+ });
110
+ return;
111
+ }
112
+ const given = value !== undefined;
113
+ const fail =
114
+ name === "exists"
115
+ ? given && "exists"
116
+ : name === "in"
117
+ ? !Array.isArray(value) && "in"
118
+ : !given && "default";
119
+ if (fail) {
120
+ reportDiagnostic(ctx.program, {
121
+ code: "mapping-when-value",
122
+ messageId: fail,
123
+ target: ctx.getArgumentTarget(given ? 2 : 1) ?? target,
124
+ format: { name: target.name, source: picked.source.name, operator: name },
125
+ });
126
+ return;
127
+ }
128
+ push(ctx, stateKeys.mappingWhen, target, {
129
+ ...picked,
130
+ operator: name,
131
+ ...(given ? { value: plainValue(value) } : {}),
132
+ } satisfies MappingCondition);
133
+ };
134
+
135
+ /** A condition's value as plain JSON: lists entry by entry, numbers as JS numbers, enum members as their value. */
136
+ function plainValue(value: unknown): unknown {
137
+ if (Array.isArray(value)) return value.map(plainValue);
138
+ if (typeof value === "object" && value !== null) {
139
+ const v = value as { kind?: string; value?: unknown; name?: string };
140
+ if (v.kind === "EnumMember") return v.value ?? v.name;
141
+ if ("asNumber" in value) return literal(value);
142
+ }
143
+ return value;
144
+ }
145
+
146
+ const isField = (value: unknown): value is ModelProperty =>
147
+ typeof value === "object" &&
148
+ value !== null &&
149
+ (value as ModelProperty).kind === "ModelProperty";
150
+
151
+ /** A source named with `Mapping.Item` or `Mapping.Slice` is stored as its field and selection. */
152
+ export const $from = (
153
+ ctx: Ctx,
154
+ target: Model | ModelProperty,
155
+ mapping: EnumMember,
156
+ source: Model | ModelProperty,
157
+ ) =>
158
+ push(ctx, stateKeys.mappedFrom, target, {
159
+ mapping,
160
+ ...(selection(source) ?? { source }),
161
+ } satisfies MappingFromLink);
162
+
163
+ /** The field and selection `Mapping.Item<…>` or `Mapping.Slice<…>` names, or undefined for any other source. */
164
+ function selection(
165
+ source: Model | ModelProperty,
166
+ ): { source: ModelProperty; select: MappingSelection } | undefined {
167
+ if (source.kind !== "Model" || !source.templateMapper || !source.namespace)
168
+ return undefined;
169
+ if (getNamespaceFullName(source.namespace) !== "SimplerForms.Mapping")
170
+ return undefined;
171
+ const [field, ...bounds] = source.templateMapper.args;
172
+ if (field?.entityKind !== "Type" || field.kind !== "ModelProperty")
173
+ return undefined;
174
+ const [first, second] = bounds.map(numberOf);
175
+ if (source.name === "Item" && first !== undefined)
176
+ return { source: field, select: { index: first } };
177
+ if (source.name === "Slice" && first !== undefined)
178
+ return {
179
+ source: field,
180
+ select:
181
+ second === undefined
182
+ ? { start: first }
183
+ : { start: first, stop: second },
184
+ };
185
+ return undefined;
186
+ }
187
+
188
+ /** The number a template's `valueof int32` argument holds, or undefined (as for `null`). */
189
+ function numberOf(arg: unknown): number | undefined {
190
+ const entity = arg as {
191
+ entityKind?: string;
192
+ valueKind?: string;
193
+ value?: { asNumber(): number | null };
194
+ type?: { kind: string; value?: number };
195
+ };
196
+ if (entity.entityKind === "Value" && entity.valueKind === "NumericValue")
197
+ return entity.value?.asNumber() ?? undefined;
198
+ if (entity.type?.kind === "Number") return entity.type.value;
199
+ return undefined;
200
+ }